PyCForge extension API: simplicity and behavioral guarantees
Requirements draft 0.1 — 2026-10-27

User requirement: the extension API later used by the separate PyCForge SDK
must offer simplicity and guarantees in behavior.

Status: design requirements for subsequent implementation and qualification.
This document does not change the verified PyCForge 1.3.59 release or declare
its experimental Crucible API 0.1 stable. Proposed method names below are
illustrative; they are not newly implemented calls.

1. ONE ENGINE CONTRACT, ALL CLIENTS

PyCForge, its CLI, the separate SDK and automated checks must use the same
public extension services. The SDK supplies editing, explanations, test
execution and packaging around those services. It must not implement another
converter or a separate interpretation of extension validity.

An extension author should not need internal AST/C-IR classes, compiler stage
names, global registries, GUI objects or private module paths. The engine owns
binding, dependency scheduling, cancellation, validation and publication.

2. A SMALL AUTHORING SURFACE

The normal extension consists of:
- A manifest identifying the package, API compatibility, dependencies and
  supported targets.
- Operation declarations defining signatures, supported types, semantics,
  error behavior and required runtime helpers.
- An implementation using reviewed declarative bindings where possible.
- Conformance examples and expected successful/rejected outcomes.

Routine scalar operations should use engine-provided builders and defaults.
Authors should not repeatedly construct ownership descriptions, target names
and guards that the engine can derive and verify. Advanced operations may need
two explicit callbacks: assess a bound call, then lower an accepted plan using
a restricted engine builder. Assessment describes applicability; it does not
authorize publication. Lowering returns a structured fragment for independent
validation, rather than modifying output files or internal compiler objects.

The engine must check any runtime helper artifact and its declared obligations.
A helper name or metadata fingerprint alone is not evidence that it implements
the required behavior. New representations or effects beyond the public
contract require an explicit engine/API extension, not access to internals.

3. SIMPLE CLIENT OPERATIONS, EXPLICIT EFFECTS

The public facade should keep these distinct responsibilities understandable:
- inspect: describe a package and its requirements without importing its code;
- validate: check a complete package snapshot and return structured findings;
- test: explicitly run the requested conformance cases/toolchains;
- activate: publish an already validated package snapshot atomically;
- catalogue: report the actual available, qualified capabilities.

Conversion remains an engine operation using a frozen extension set. Parsing
or converting a source program must not implicitly execute that program,
install dependencies, search the network, or compile/run the generated program.
Testing and native execution require their explicit test/build workflow.

4. REQUIRED BEHAVIOR AND ACCEPTANCE EVIDENCE

G1 — Deterministic conversion
Identical source bytes and logical module identities, options, engine build,
extension content snapshots and target profile must produce identical C bytes
and semantic results. Structured diagnostics must have deterministic codes,
source locations and ordering. Timings, logs and host-local paths are separate
observations. Timestamps, random identifiers and discovery order must not leak
into semantic output. Qualification compares separate processes and hash seeds.
Different input ordering need only be equivalent where the contract says it is.

G2 — Unambiguous resolution
Names, aliases and shadowing follow a documented policy. Conflicting providers
or dependency versions must be rejected or resolved by explicit configuration;
filesystem enumeration and registration timing must never decide the winner.
Tests permute discovery order and exercise conflicting declarations.

G3 — Precise outcomes
Every assessment states supported, conditional, or unsupported. Conditional
support identifies obligations which the selected backend must discharge.
Unsupported behavior has a stable diagnostic code and a useful explanation.
Malformed packages, extension faults and cancellation remain distinct from a
normal unsupported source construct. There is no silent alternate conversion
with different semantics. Tests exercise each outcome and incomplete plans.

G4 — Atomic activation and publication
Activation either installs the validated snapshot completely or retains the
previous active set. Each conversion keeps the immutable set it started with.
Failed or canceled conversions publish no partial C and do not overwrite the
last successful output. Source/extension changes invalidate dependent plans;
the host rejects stale, cross-job or wrong-stage results. Tests interrupt each
boundary and attempt to reuse obsolete results.

G5 — Evaluation and ownership
Generated programs preserve the declared evaluation order, required single
evaluation of source operands, side effects, errors, ownership and lifetimes.
Borrowing, retention, mutation and cleanup are explicit when applicable. Tests
cover success, early return, errors, aliasing and cancellation-related cleanup.
Compiler callback invocations may be repeated: callbacks must be repeatable
and must not depend on an assumed invocation count, global mutation or timing.
The engine constructs context and validates fragments; it does not expose
mutable scheduling state to extensions.

G6 — Versioned compatibility
The manifest declares API, semantic-profile and target requirements. An
incompatible package is rejected before activation with actionable diagnostics.
Once the API is stabilized, incompatible behavior requires an explicit version
boundary and migration path; an engine update must not silently reinterpret a
previously supported extension. Diagnostics and serialized results have their
own documented compatibility rules. Qualification includes an unchanged SDK
client and unchanged extension against a compatible engine upgrade.

G7 — Qualified numerical behavior
Repeatable code generation is separate from numerical reproducibility. Each
math operation declares supported inputs, rounding/error rules, non-finite
values and platform/toolchain assumptions. Bitwise equality, an error bound,
or another numerical acceptance rule must be explicit and tested. Cross-platform
bitwise floating-point equality is not inferred from identical generated C.

G8 — Honest capability discovery
The catalogue describes the exact functions, types, signatures, routes and
targets actually qualified. A package named math or numpy does not imply
complete library coverage. Unknown cases are rejected explicitly. The SDK
displays the same catalogue and diagnostics returned by the engine.

5. LIMITS THAT MUST REMAIN VISIBLE

The current Python extension-authoring objects are trusted in-process code.
Neither frozen dataclasses nor fingerprints sandbox arbitrary Python or prove
an implementation correct. Guarantees for recovery from a hung or malicious
callback require an enforced isolation/supervision boundary and separate tests;
cooperative cancellation alone cannot provide them. The API must state its
trust and resource assumptions before such recovery claims are made.

Conformance tests demonstrate the specified domains. They do not establish
correctness for arbitrary Python inputs, all external libraries or all C targets.
Claims must name their preconditions and be backed by enforced host checks plus
the corresponding qualification evidence.

6. QUALIFICATION SEQUENCE

First, implement the minimum host path with a small scalar math extension.
Verify import binding, assessment, lowering, diagnostics and compiled results
end to end. Add a second comparable operation by changing only extension code
and declarations; engine edits fail this extensibility acceptance check.

Next, use array/buffer/view and opaque-resource examples to expose lifetime,
mutation, cleanup and scheduling requirements before promising a stable general
API. Then introduce a clearly bounded NumPy pack. Exercise the same installed
engine API from a small separate SDK client before building the SDK's full UI.

Do not freeze API 0.1 merely because the scalar demonstration passes. Its current
OperationRequest.integer_divisor field is specific to the migrated numeric
family. The authoring facade needs general, engine-validated facts and operands
instead of accumulating a new special field for each supported library feature.

7. CURRENT IMPLEMENTATION BASELINE

Verified 1.3.59 already has Operation/TypeService contracts, OperationRegistry
assessment, immutable descriptors/plans, shared module lookup and dependency
algorithms, and real typed/runtime consumers for the migrated responsibilities.
It has no external package activation, general extension lowering dispatch or
separate SDK distribution. The present built-in paths and their tests are the
starting point for the requirements above, not proof that every guarantee is
already implemented.

Reviewed project sources: pycforge/crucible/interfaces.py, contracts.py,
registry.py, namespaces.py and dependencies.py; specifications/
crucible_foundation_1_3_58.md and modularity_1_3_59.md.
