Crucible first.
A general SDK follows.

Long-term product objective: make PyCForge a dependable, programmable conversion platform. A human programmer and an AI system must each be able to construct a useful conversion extension through the SDK’s public API, while Crucible’s public API supplies the modular semantic services that carry it out. Practical API usability and conversion reliability are core acceptance criteria. Desktop interfaces present those same tested services. Authorship by a person or an AI changes neither eligibility nor the evidence required before an extension is cleared for its declared use.

Engineering priority: correctness, modular conversion services, and usable plugin-extension APIs take precedence over conversion throughput. Additional conversion time is acceptable when it enables that architecture and its required checks. No fixed percentage slowdown may veto the modular design or justify bypassing validation. Measure costs and improve them when useful; a speed improvement is not a prerequisite. The first implementation work remains preparation of the existing engine.

Offline operation: after the applications and required local dependencies are installed, discovery, authoring, pre-scan, semantic checks, local fixture tests, compilation, package building, and registration require no internet service. Keep required catalogues, schemas, guidance, and check resources locally available. Missing local prerequisites produce an incomplete result instead of an automatic download. Installing or updating packages remains a separate deliberate activity.

Prepare the existing conversion engine first: preserve its working behavior, establish reusable Crucible services inside PyCForge, and prove their public contracts through both conversion routes. Prove minimal *import binding and the execution gate with the engine interfaces, publish the conversion landscape, and exercise a minimal SDK Python API and CLI against an installed expansion. Extend the sub-script’s options and region language before completing the separate SDK application.

Routine engine capability additions must not require coordinated releases of both projects. SDK updates address its own tools or genuinely new communication/authoring requirements. This reduces duplicated knowledge and cross-project work; resource ownership and transformation scheduling still require explicit, tested engine contracts.

Revision 0.13 retains the earlier engine, API, editor, discovery, scan, sub-script, and execution requirements. It makes normal operation offline and records XML as a candidate for the installed catalogue/profile format. For that design, PyCForge exports XML and the SDK parses and validates it; Crucible continues executing its native rule and scan services. Format qualification remains an implementation gate. This revision reports no completed application implementation.

One owner for each responsibility

Meaning of “SDK interpreter”: a general authoring/script runner that invokes the selected Crucible services. The SDK contains no second Python-to-C engine, independent eligibility model, or separate implementation of PyCForge’s sub-script. Code templates are inserted as source; selecting or refreshing methods does not execute them.

The SDK editor, offline catalogue browsing, scaffolding, and local format checks can work without PyCForge present. A new engine-dependent scan or conversion test requires a compatible selected engine. Headless commands create no Qt application and require no display. SDK GUI dependencies belong to the separate SDK installation; PyCForge has no SDK runtime dependency.

Behavioral interfaces and explicit eligibility

Define small abstract interfaces in P1 and prove their adequacy in P3. Use composition and reusable services so a new supported function does not need its own large class hierarchy or duplicated implementations for both conversion routes. Interface definitions and their structured descriptors live together in the engine project and are checked for consistency.

Assess before converting: eligibility is eligible, conditional, or unsupported. Conditional results identify the unresolved obligations and how they will be established or enforced by generated checks. Unknown conditions never count as approval. Before publishing output, every required obligation must be discharged, represented by an accepted runtime check, or cause rejection. Conversion consumes the validated plan; it must not silently reassess the same function under different rules.

Register each new operation once against these engine-owned services. Abstract methods provide structural requirements; registration validation and behavioral tests establish whether an implementation meets the declared contract. Immutable data records may carry requests, plans, facts, and results. They do not substitute for the behavioral interfaces, and ownership logic must not be copied into route-specific records.

Structured extension boundary: permit plugin-defined operations and representations through documented semantic services, with checked translation into supported C structures or declared native calls. Core parsing, scope/binding, mandatory validation, publication, and scheduling remain authoritative. Hooks declare phase, required facts, effects, and invalidated facts. A plugin cannot bypass checks by claiming support or returning arbitrary replacement C text.

Keep ownership explicit: a borrowed view identifies its owner and lifetime; an owned native resource identifies acquisition, transfer, and cleanup obligations. Test early return, errors, mutation, aliasing, and cancellation where applicable. Sharing these contracts reduces duplicate work without making correct cleanup automatic.

The remaining executable contracts

The product direction is established. The missing detail is the exact contract an independently authored expansion must obey: the language it is written in, the values it receives, the methods it may call at each stage, the namespace it exports, the evidence it supplies, and the failures it can report. These contracts must be exercised in the current engine before a complete SDK interface depends on them.

Order inside one conversion: recognize declarations and preserve source locations; resolve the registered namespace and bind symbols; establish types, eligibility, ownership and effects; schedule allowed transformations; re-establish any invalidated obligations; lower through a declared route; validate the result; publish only on success. Some analyses may need bounded iteration rather than a single linear pass. All routes must use the same applicable semantic decisions. Native compile/link and reference execution follow where the scan or build profile requires them.

The class tree exposes the supported public authoring surface. It does not expose every private interpreter method or permit arbitrary calls into an internal pass. Registration declarations, generated code, and catalogue descriptions must agree. A wrapper around an unchanged monolith does not establish modularity unless the real conversion paths consume these shared services.

Two public APIs, one conversion authority

Both APIs are product interfaces with documented installed import paths, typed requests/results, diagnostics, compatibility rules, and executable examples. A command-line wrapper alone does not establish an importable SDK API. Design and test direct Python use alongside the noninteractive CLI; the PySide6 application consumes the same authoring services.

Contracts for automation: define schemas, status/error categories, progress, timeouts/cancellation, source locations, and request/result identities. Callers must distinguish success, rejection, incomplete checks, cancellation, and internal failure without interpreting prose. Version the SDK’s public API independently from the engine API and communication protocol; document compatible evolution and deprecations. Public SDK imports and headless operations must not initialize or require Qt.

Practical authoring: deliver examples that let either author discover a method, understand its limits, implement a conversion expansion, interpret a diagnostic, correct the source, and re-run the required checks. An AI uses the public SDK API through its execution tools or the CLI; neither path has a validation bypass. Final signatures are implementation deliverables, not promises that these proposed interfaces already exist.

The engine-owned conversion landscape package

PyCForge ships the rules. Every PyCForge release includes Crucible’s authoritative semantic implementations and a machine-readable conversion landscape in a documented public folder inside the installed PyCForge package. Include that folder in both wheel and source distributions. The public discovery contract identifies its location and the selected engine; the SDK does not guess private source paths or reconstruct rules by inspecting implementation files. Generate catalogue structure from registered public interfaces and check authored guidance/templates against those interfaces. The discovery endpoint exposes the same identity and contract as the folder.

The SDK stays general. It provides the Python API, CLI, editor, tree renderer, templates, scaffolding, generic format checks, test orchestration, packaging, and reports. Engine-specific eligibility, ownership/lifetime, hook ordering, conversion, and mandatory semantic validation remain in Crucible. The SDK reads their published descriptions and invokes the engine services that enforce them. A cached catalogue is a versioned view of PyCForge’s information, not a separately maintained rule set.

XML candidate: PyCForge writes, the SDK reads

XML is a candidate for the offline publication of the catalogue, class/method hierarchy, type/handle descriptions, scan profiles, and build requirements. It can express nested definitions and named references with a versioned schema. Prototype the format and parser/validator choice in P1/P2 before freezing the contract. This does not change the native Python API or the established JSON output of CLI commands.

One source of meaning: generate XML from the same registered definitions and check profiles that Crucible executes. Do not keep a second hand-maintained XML rule implementation or make PyCForge ingest its own export to discover its rules. Validate the exported format with the SDK reader or a separate conformance harness during development/release qualification. No production XML parsing dependency is required in PyCForge for this catalogue design.

What XML can describe: class/interface and method IDs; signatures and typed parameters; editable templates and explanations; handle/ownership requirements; scan-profile IDs, check references, prerequisites, and applicability; target/toolchain/build requirements; diagnostics and known limitations. Build descriptions refer to supported public services and declared capabilities. Reading XML never executes embedded scripts, templates, or arbitrary commands. File names and the division into catalogue, types, scan profiles, and build profiles remain draft layout choices.

Two validation layers: the SDK’s local XML/schema checks establish document structure, required fields, supported versions, and declared references. Crucible establishes semantic eligibility, legal hook order, handle lifetimes, conflicts, and actual conversion correctness through its required checks and fixtures. A schema-valid XML document is not proof that a dependency graph is acyclic or an expansion is correct. Preserve the distinction in diagnostics and scan status.

Local parsing contract: bundle the required schema files and resolve only declared local resources. Do not fetch schemas or entities from the internet or process arbitrary external references. Disable DTD/external-entity processing and automatic XInclude, and enforce bounded document size/depth. Use a headless parser/validator shared by SDK API, CLI, and GUI. Version optional extensions and required client features explicitly; unfamiliar required semantics must produce incompatibility rather than guessed behavior.

Acceptance evidence: exercise catalogue export and SDK parsing with internet access blocked, no Qt application, missing/invalid resources, unknown required features, and an unchanged SDK consuming a compatible updated engine export. Verify class/method loading, local schema checks, engine-owned scan execution, and local build requirements. Test that a structurally valid but semantically invalid profile still fails through Crucible. Required parser/validator dependencies must be available locally before these checks begin.

Format references: Python ElementTree, W3C XML Schema, and lxml validation. ElementTree provides XML parsing/writing; XSD validation requires an explicitly selected validator. These references inform the prototype and are not runtime network dependencies.

Refresh from the selected PyCForge installation at startup

On first setup, select the PyCForge installation or its Python environment and remember it in SDK settings. Resolve the published catalogue folder through the installation’s public discovery contract; do not assume the SDK and PyCForge share one environment. The folder layout and manifest format are P1/P2 deliverables. They are part of the compatibility contract.

1. Locate: on every SDK launch, locate the selected installation and its published catalogue folder.
2. Check: read its manifest/index and verify engine identity, API/protocol compatibility, schema version, catalogue revision/hash, and required resources.
3. Refresh: if the advertised content has changed, read and validate the complete listed catalogue. Reuse an already validated cache only when its identity/hash still matches; never skip the startup identity check.
4. Replace together: install the new validated catalogue in the SDK cache as one operation, so a partially updated folder cannot produce a mixture of old and new definitions.
5. Present: update classes, methods, explanations, call templates, prerequisites, limits, and known issues. Retain source edits and saved class visibility selections by stable IDs.

Apply the same discovery/check behavior when a headless SDK API session connects and when a CLI command selects an engine. Keep an explicit Refresh action for updates while the SDK remains open. Before engine-dependent scan/test work, verify that the responding engine and applicable contract match the selected catalogue; a changed installation requires refresh and re-established check applicability.

Startup refresh reads data: it does not scan the author’s expansion source, execute a plugin, run inserted templates, copy engine implementation code into the SDK, or install/update either product. Read the manifest-listed resources through the public format. Engine-dependent work remains an explicit request through Crucible. Catalogue refresh never rewrites existing plugin source.

Unavailable or incompatible installation: keep the last valid catalogue for clearly labeled offline browsing/editing. Do not present cached information as verified against the current installation. Missing files, partial upgrades, invalid content, and incompatible required schemas/features prevent the refresh from replacing the valid cache. New engine-dependent approval requires a compatible available engine; cached descriptions alone cannot approve a conversion.

Two different folders: the published rules/catalogue folder belongs to the selected PyCForge installation and is read by the SDK. The user-selected conversion add-ons folder contains authored expansion packages that PyCForge registers. Catalogue discovery does not install or activate packages from the add-ons folder.

Compatibility rule: additive methods, groups, descriptions, and templates within the supported schema must work in an unchanged client. Optional unknown fields may be ignored only as the schema permits. An unknown required field, semantic feature, or incompatible major version must produce an explicit incompatibility result. The SDK must not guess at an unfamiliar required behavior. A new protocol or authoring primitive can require an SDK update; ordinary method additions must not.

Data stays data: rendering and searching the catalogue execute no plugin code or embedded executable update hooks. Templates become editable source only after insertion. Engine-dependent work runs through an explicit request. Scan evidence records the exact landscape/check profile used; refreshing relevant inputs makes prior approval out of date until applicability is re-established.

Application version, SDK version, SDK public API version, and engine runtime API version remain independent. Version the communication protocol and landscape schema explicitly as well. Plugin manifests require engine capabilities/API compatibility, not matching SDK and PyCForge release numbers. Known-issue information is current to the selected landscape revision, not an implied live internet feed.

One authoring service, API, CLI, and editor

Build the minimal SDK Python API, command-line client, and conformance harness first. Complete and qualify the headless authoring services before the GUI; the GUI invokes those same services. An AI system must be able to inspect the landscape and perform the workflow without reading screenshots, scraping prose, or opening a window.

API names and command names remain design placeholders until their contracts are implemented. Commands must support noninteractive use, documented exit status, stable JSON schemas, diagnostics separate from machine-readable output, timeouts/cancellation, and explicit engine/target selection. Creating source does not install it. Missing prerequisites produce an incomplete result rather than success. API, CLI, and GUI callers use the same checks and receive no alternative bypass.

The agreed SDK method tree and editor

A separate PySide6 application in PyCForge’s theme, with one source editor and no tabs. A searchable method tree on the left groups the selected engine’s public Crucible classes/interfaces, with their published interpreter/API methods underneath. Grouping and ordering come from the landscape. The explanation area sits above the source editor. Completion and insertion templates use that same catalogue. Work on one conversion add-on at a time, starting with its primary implementation file.

Single-click a method: show its explanation in the upper detail area, including purpose, parameters/results, permitted stage, required handles and prerequisites, eligibility, ownership, route/target support, known issues, and an example. Double-click a method: insert its general editable call template at the cursor in the SDK source editor, with clearly marked argument placeholders and required imports handled once. Unresolved required placeholders are scan findings that prevent approval. Insertion changes source; it does not run the method, scan the plugin, or begin conversion. Execution and checks use explicit actions.

Unsupported or incompatible methods remain explainable in the tree. Normal API reference use takes place in this interface; bundled searchable help covers setup, concepts, tutorials, packaging, and troubleshooting. Engine-specific API and sub-script details come from the landscape, including offline cached access. These interactions are acceptance requirements carried forward from the agreed design.

Tree Options above the method tree

Provide a Tree Options button at the top of the left tree panel. It opens an options dialog with a searchable checkbox list of the public classes/interfaces advertised by the selected engine. Authors select the classes useful for their conversion add-on, keeping unrelated branches out of the working view. Offer Select All and Clear Selection controls. With no selected classes, show an empty-state explanation and a Restore All action.

Apply the selection to the tree only; Cancel leaves the current selection unchanged. Display when a filter is active and provide an easy Show All action. Remember the view preference in the SDK’s own settings; do not add it to the add-on’s semantic manifest or PyCForge’s project/session schemas. The initial view shows all advertised classes/interfaces. Filtering, searching, expanding branches, and explaining methods execute no plugin code.

Keep guidance reachable: a method explanation still lists required types, handles, hooks, and related methods even when their classes are hidden. Let the author reveal a referenced class explicitly. Scan findings remain visible regardless of tree filtering and can open their source location or method explanation. A hidden class is available to the engine and authoring API; hiding it neither disables a capability nor waives a required check.

Refresh without losing intent: preserve selections by stable public class/interface IDs. New methods under selected classes appear after refresh. New classes appear in the options dialog and the unfiltered view, without requiring an SDK update. Show retired or unavailable selections clearly rather than silently treating them as valid. View changes alone do not change source, invalidate an approved package snapshot, or alter conversion results; engine, target, source, or semantic-policy changes still follow the usual invalidation rules.

One editor, one complete scan snapshot

Keep a single editing surface with no tab bar. If an add-on declares helper source files, use a compact file selector to replace the file shown in that same editor, preserving unsaved content, undo history, and cursor position. A scan finding may select its file in this surface. The ordinary starting workflow needs only one primary conversion expansion file.

Scanner scope is the declared package: collect the current primary source, declared helper sources, assets, manifest metadata, dependencies, and required tests into one exact snapshot. Include current in-memory edits when present and the identified saved bytes for other declared files. Report missing or inconsistent inputs. API, CLI, and GUI scans of the same snapshot use the same checks and produce equivalent outcomes. The current visible file, tree selection, collapsed branches, and method order never define what is scanned.

Build only the approved snapshot. Switching the visible file or changing a class filter does not alter approval; editing any packaged source, required metadata, asset, dependency, or relevant contract does. A single editor keeps authoring focused; the complete snapshot and shared engine checks establish scan reliability.

Retain useful clipboard/character-map interactions in Edit, the source context menu, and toolbar. Generated C is a read-only result view. Typing, IME, and idle pauses trigger no scan, worker execution, or progress popup. Explicit long actions can show a small labeled progress dialog with cancellation where applicable. The SDK owns its own settings and save/recovery behavior.

Scan approval, packaging, and installation

The SDK scanner uses PyCForge’s current scan mechanics

Rules and procedure have the same owner: PyCForge supplies the required semantic checks, their implementations, prerequisites, legal order, applicability, and acceptance criteria. Its published catalogue describes that versioned scan contract. The SDK’s Scan action calls the selected engine’s public validation services; refreshing descriptions alone is not a substitute for running the corresponding engine checks. GUI, CLI, and Python API use this same service.

For each explicit Scan, capture the complete add-on snapshot, select the engine/ruleset/check profile and target, and verify that their identities match the current contract. Crucible resolves the applicable check dependencies and executes the required semantic workflow. The SDK may coordinate generic file, compiler, fixture, and packaging tasks requested by that workflow, but cannot omit semantic checks, redefine their order, or invent a passing result. Reports record the source/package identity, engine build, ruleset and scan-profile versions/hashes, target/dependencies, required checks, and every result.

Updates apply to scanning too: when PyCForge changes a required check within the supported protocol, the unchanged SDK obtains the new scan contract and invokes the updated engine implementation. Earlier approval is usable only if the engine establishes that its recorded evidence still applies; otherwise require a new scan. Missing, skipped, canceled, failed, or incompatible required checks cannot produce approval. An unfamiliar required client capability produces an explicit incompatibility result. Startup refresh updates catalogue information and approval applicability; it never silently executes the author’s extension.

The shared rule services also govern package registration and conversion inside PyCForge, using the checks applicable to each stage and its actual inputs. Authoring, registration, and conversion need not run identical workloads, but must agree on the meaning of the same rule. General SDK schema/format checks remain useful prerequisites; they do not replace semantic validation by Crucible.

One standard for all authors: engineer-typed and AI-generated source pass the same declaration, eligibility, ownership/effect, route/target, reference-behavior, generated-C compilation/execution, and packaging checks required for the declared capability. Authorship, a plausible implementation, or a passing syntax check cannot waive a required test. Changes made through the API or a text editor invalidate evidence under the same rules. The host independently revalidates the finished package before activation.

Scan captures exact source buffers, assets, final author/version metadata, dependencies, engine/landscape identity, target, and check policy. Every required check must complete with no unresolved error or potential-problem warning before that snapshot becomes approved. Informational notes do not hide actionable findings. The SDK combines local checks with engine results; it does not recreate engine eligibility logic.

Source, metadata, asset, target, dependency, or relevant contract/check changes invalidate approval. Build uses only the approved bytes. If the packaging wizard changes metadata, it requires a fresh applicable scan. A previously approved unchanged snapshot can be packaged offline only when its required evidence is available and applicable. A clean scan means no issue was detected within the recorded checks and fixtures; it is not proof for every possible input.

The user selects a plugin root anywhere, independent of Python/project locations. Configure the target engine and destination once through Tools or the top icon; remember them for future builds. PyCForge owns registration, validates the received package independently, and handles explicit activation/version replacement. Stage a complete artifact before committing it; failed installation preserves the prior working registration. Never edit private project/session files or report plugin configuration failures as unsaved Python/project errors.

A single .pcfplugin archive remains the proposed container; the packaging contract below supplies a concrete candidate to qualify in P2 before freezing the format. Distinguish compiler-side dependencies from target C headers/libraries. Discovery installs nothing and imports no plugin code. Executable plugins run in a bounded worker on explicit requests; worker isolation contains crashes and permits termination but is not an operating-system security sandbox.

Expansion packaging and host recognition

Proposed P2 format: a ZIP-based .pcfplugin archive with a JSON manifest and a closed inventory of declared payload files. This is a proposed layout, not an implemented loader contract. XML remains the candidate for PyCForge’s exported SDK catalogue; the host package manifest uses JSON so this design introduces no XML parser into PyCForge. The SDK’s own PyPI wheel is a different artifact.

Identity without a circular hash: define the payload identity over a canonical manifest and its inventoried content, excluding the verification report. The report refers to that identity; an optional hash of the completed archive is recorded outside the archive. Specify canonicalization in the package format. Neither matching hashes nor a claimed passing report prove authorship or universal semantic correctness.

1. Discover metadata: find candidate archives under the configured root and inspect their manifest without importing code. Validate the container structure, paths, duplicate members, size limits, declared inventory, and hashes. Reject undeclared executable content and unsafe extraction paths.
2. Check compatibility: verify schema and required features, engine/API/Python requirements, namespace conflicts, dependencies, and target/route applicability. Being compatible does not mean the package has passed semantic validation. Missing local prerequisites produce an incomplete status, with no automatic download.
3. Validate on an explicit action: stage immutable content and invoke the selected engine’s registration/scan profile in a bounded worker. Check actual entry-point declarations against the manifest, required hook/handle/type contracts, fixtures, generated C, and native checks applicable to that profile. Reject stale, incomplete, forged, or inapplicable evidence; the host chooses what must be re-established.
4. Commit and activate: atomically register the accepted identity and namespace mapping; activate or replace a version through an explicit operation. Failure preserves the previous working registration. Record the resolved package/dependency identity in conversion results and prevent an active job from switching providers during an update.

Expose separate discovered, compatible, validated, and active states with reasons. A valid filename is only a candidate; it is not a valid extension. Multiple providers for a namespace require an explicit selection or a diagnostic, never the first filesystem match. An update that changes required checks can make prior evidence inapplicable.

A worker provides cancellation and crash containment, not an operating-system security sandbox. Passing checks records conformance within the declared profile and fixtures. Host registration and every later conversion still enforce applicable semantic obligations.

The sub-script in PyCForge’s main Python editor

The SDK creates conversion plugins; PyCForge uses them. In PyCForge’s main Python editor, *import explicitly declares a registered conversion expansion. Ordinary import retains its Python meaning and the existing supported-source-bundle rules; do not silently redirect it to an expansion merely because a namespace matches. The agreed marker supersedes the earlier comment-only selection proposal. Remaining options and region directives belong to PyCForge’s sub-script and use the same engine services.

Minimal declaration: *import matrix_tools, with an optional alias such as *import matrix_tools as matrix. The name identifies a public namespace advertised by a registered expansion package, not an arbitrary archive path. Subsequent expressions such as matrix.sum(values) resolve against that expansion’s declared operations and types. The manifest ties the namespace to the selected package identity/version. Aliases, shadowing, duplicate claims, missing packages, and unavailable methods require explicit checked outcomes. The minimal grammar, placement, alias, and binding rules are P1/P2 deliverables; richer options and region directives remain P4 work.

Language boundary: *import is PyCForge-specific syntax, distinct from Python’s from module import *. A file containing it is Python with an explicit conversion extension, and cannot be passed unchanged to CPython. The frontend must recognize the declaration as syntax, preserve source locations, and provide its bindings to Crucible before ordinary Python analysis rejects the source. Do not implement this as blind text replacement or treat occurrences in comments and strings as declarations.

Support whole functions and consecutive complete statements within the legal region model. Crucible owns parsing, binding, eligibility, input/output and mutation rules, lifetimes, exit behavior, plugin composition, scheduling, and diagnostics. Resolve extension symbols before ordinary unsupported-import rejection. Reject malformed directives, ambiguous attachment, partial statements, invalid crossings, incompatible requirements, and disallowed overlaps or nesting with source locations.

The sub-script uses the same public engine services and mandatory checks as headless conversion. It gives neither an author nor a plugin permission to bypass validation or inject unchecked replacement C. Parse and execute the conversion request on an explicit conversion or validation action; typing, IME composition, and idle pauses never trigger executable plugin work or progress dialogs. Generated C remains read-only.

Ownership and proof: the language implementation stays inside PyCForge. The SDK may display engine-supplied guidance, insert templates, and submit examples for testing; it has no separate sub-script evaluator. P2 must demonstrate an SDK-built plugin installed in PyCForge and selected through the minimal declaration. P4 extends that proof to richer main-editor directives through both editor and public API requests. Validate eligible and rejected regions, compile/run required reference fixtures, and confirm equivalent decisions for the same source and policy.

How a declaration becomes a method call

Illustrative application source: *import matrix_tools as m, followed by view = m.Matrix(values).transpose() and result = view.sum(). These are hypothetical operations for the ownership proof, not claims of present matrix support. *import declares a conversion namespace; it does not execute an ordinary Python import or instruct the SDK to interpret the application.

Registration maps export names and signatures to engine-recognized operation/type declarations and compiler-side implementations. Nested types need explicit declarations; arbitrary object lookup or dynamic getattr does not acquire conversion support merely because a namespace exists. Method availability comes from the receiver’s resolved type and contract. The SDK tree can display and insert calls from these descriptors; Crucible performs binding and conversion at an explicit request.

Keep this distinction testable: calling a method during conversion invokes its compiler implementation to build a checked conversion plan or representation; the resulting target operation executes when the generated program runs. Do not infer support from the presence of a same-name Python module or fall back to importing it. Minimal alias/shadowing rules, missing exports, nested result types, and conflicting registrations require tests before P2 closes.

Error control has distinct owners

Errors are not handled exclusively by PyCForge, but PyCForge owns semantic acceptance and final conversion state. The SDK’s local checks and plugin implementation’s error handling cannot turn a failed mandatory engine check into approval. All clients receive stable diagnostic codes, severity, phase, source span when applicable, plugin/operation/hook identity, target/profile context, and a clear failed, incomplete, canceled, or successful outcome.

For example, an invalid matrix shape may be rejected during conversion if known, or require a generated runtime guard if dynamic. A failed native allocation requires the declared runtime error and cleanup path. A stale compiler handle is an extension contract violation and must stop that conversion. A plugin may not substitute a plausible result to hide any of these failures.

Tests must distinguish expected rejection from a compiler crash and from a generated-program runtime error. Reference fixtures must verify errors, side effects, ownership release, and execution order as well as returned values. The same request and policy must have equivalent outcomes through the direct engine service and SDK API/CLI/GUI; the checks applicable to authoring, installation, conversion, and native building may differ because their inputs and responsibilities differ.

Run Python stops before executing a source with *import

Required behavior: when the selected execution source bundle contains an actual *import declaration, Run Python immediately reports that the source requires conversion and does not launch the user program. No user statements or imports execute, including statements written before the declaration. The same check applies to any public API or command that exposes this Python-run operation.

Scope of the check: examine the current primary source and its explicitly supplied execution dependencies, not unrelated editor tabs or every installed add-on. A declaration in a supplied dependency also blocks the launch. A missing or disabled expansion, or a similarly named installed Python library, does not permit Python fallback for *import. Ordinary import alone does not trigger this rule, and expansion syntax inside comments or string literals is not a declaration. Invalid declarations receive syntax diagnostics before launch.

Implementation contract: preflight uses the current source snapshot and the engine-owned declaration/binding information, without executing user modules or plugin code to probe importability. Source or relevant dependency edits invalidate earlier results. Return a structured blocked status and source-linked diagnostics consistently through API and UI; keyboard shortcuts and stale UI state cannot bypass the check. Merely typing never launches a scan, worker, or progress dialog. Run Python must not silently remove the declaration, substitute a Python implementation, or automatically transpile and run C.

Focused sequence and completion gates

Work on engine structure, public contracts, and harnesses first. Create only the SDK skeleton, public Python API slice, and minimal CLI consumer needed to prove those contracts. Begin the full desktop UI after the engine/contract proofs. Documentation and tests grow with each stage; no stage advances merely because one demonstration ran.

P1/P2 prove minimal expansion declarations and host execution blocking. P3 proves hard contracts and communication evolution with a minimal client; P6 repeats that proof with the full editor. P4 extends the source language without requiring a completed SDK GUI. Set effort estimates after P2 exposes real integration cost. A failed gate keeps dependent work open and the working conversion path available.

The unchanged-SDK upgrade proof

1. Record the installed SDK/client artifact hash. Connect it to engine A; save its landscape and run a known passing plugin.
2. Create engine B with a new public method using the same supported protocol and landscape schema. Add its group/detail/template and declared eligibility, ownership, routes, targets, known issues, and fixtures.
3. Update the selected PyCForge installation and its published catalogue folder. Relaunch the exact same client artifact and verify automatic startup refresh, new information, and old-plugin compatibility. Repeat with explicit refresh in an open session; the SDK must obtain the new engine rules through the selected public services.
4. Generate or insert the new call, implement a plugin using it, obtain scan/test results from engine B, compile/run required fixtures, and build the approved package. Exercise the frozen SDK Python API client as well as its CLI; repeat with the GUI at P6.
5. Run the packaged plugin in engine B with the SDK absent. Confirm the client artifact hash is unchanged and that no private import or client-side semantic special case was introduced.
6. Exercise an incompatible schema/required feature, a malformed refresh, stale cached information, and an unsupported route. Expect explicit diagnostics, no false scan approval, and retention of the last valid catalogue.

Acceptance boundary: compatible capability additions and updated guidance travel as engine data. A genuinely new required client behavior or incompatible protocol needs negotiation and may require a new SDK release. Adding an engine method alone must not force that outcome.

Focused qualification requirements

Performance and resource behavior: modular plugin support, correct semantics, and usable public APIs take priority over conversion throughput. The earlier fixed conversion-speed regression cap is withdrawn. Additional conversion time, including plugin-disabled overhead, is acceptable for the modular architecture and its checks; it is not a release failure by itself. Measure conversion time separately from generated-program execution and record workload, hardware/OS, timing, and memory so future optimization is evidence-based. Discovery measurements at representative catalogue sizes remain useful observations, not fixed speed gates. Do not assume a slowdown is inevitable or promise its size before measurement.

Control and correctness remain required: cancellation, bounded transformation execution, crash containment, memory safety, and a responsive editor remain functional requirements. A slow conversion must remain controllable and must never report an incomplete result as success. Measure cancellation recovery on supported platforms; these control requirements do not reinstate a conversion-throughput budget. Generated-program behavior and declared resource requirements remain independently validated.

Assess eligibility once per applicable conversion plan so all routes consume the same established decision. Batching and reuse are optional optimizations; reuse verified results only when all relevant inputs match. Fingerprints include source/directives, engine/API/landscape/check versions, plugin/assets/dependencies, target/ABI, and compiler where tested. Establish correct uncached behavior before introducing caching. Zero executable plugin calls or discovery scans occur per editor keystroke.

Scope discipline: this work supplies general conversion machinery. NumPy, SciPy, Numba, and Cult of Atom adapters are independent author work. Defer marketplaces, automatic dependency installation, cloud/remote execution, additional target languages, and a separate general sub-script evaluator. New libraries may expose missing reusable primitives; no claim is made that the core will never need further capabilities.

The next implementation increment

Prepare the current engine through P0 and P1, then prove it through P2. The first reviewable deliverable is a reproducible baseline and component map, implemented shared-service boundaries with regression evidence, public contracts for both APIs, and a minimal SDK Python API/CLI client demonstrating a complete external conversion. The graphical SDK follows the earlier engine and protocol gates.

1. Freeze the 1.3.57 baseline and map current Typed/Runtime components, duplicate policies, private dependencies, and extension resolution points.
2. Implement and exercise shared eligibility, ownership, route, and scheduling interfaces incrementally, preserving baseline behavior and testing positive and rejected cases.
3. Specify both public APIs, the installed public catalogue folder and startup discovery contract, landscape/export, and request/result protocol; map descriptors to the same registered interfaces that the engine executes.
4. Implement minimal *import binding, Run Python preflight, and the package identity/validation/registration path early enough for P2. Build the minimal SDK Python API and CLI clients and scalar fixture, with required validation, compilation/execution, equivalent client outcomes, and package evidence.
5. Review the P2 results before expanding into P3’s hard ownership cases and frozen-client upgrade proof. Keep every unmet prerequisite visible.

Each stage records exact artifacts, environments, tests, results, limitations, and changed contracts. This roadmap is design work only; it does not assert that Crucible restructuring, the SDK, or any new gate is implemented. Existing PyCForge release README/image rules remain applicable to actual application releases, with concise user-facing documentation.