PyCForge SDK Update Contract 0.1 — first executable landscape

Authority and relationship to earlier documents

The source includes the unchanged PyCForge-Extension-API-Requirements-0.1.txt
and the prior PyCForge-Crucible-SDK-Roadmap-v0.14.html. Their complete API/SDK
vision remains design scope, not an assertion that every facility exists now.
This document distinguishes the implemented first slice and the remaining
requirements. PyCForge owns conversion semantics and the public engine API.
The future SDK is a separate PySide6 application with a shared headless service.
It must use these same public contracts, not import converter implementation
classes or create a separate interpretation of supported language behavior.

Installed handoff

pycforge/crucible/landscape/index.json is the entry point for the SDK update.
It inventories api.xml, api.xsd, guide.txt, scalar_template.py and requirements.txt
with byte sizes and SHA256 values. Registration and SDK update specifications
are also included as registration.txt and sdk-update.txt. api.xml carries methods and signatures,
public constructors, operation and type contracts, ownership, route support,
bundled pack metadata, profiles, limitations and diagnostic codes.

Public discovery: pycforge.crucible.sdk_api.discover().
CLI: SELECTED_PYTHON -m pycforge --format json sdk-api

The folder is returned by the selected installed engine, including when the SDK
runs in another Python environment. No machine-specific path or timestamp is
stored in the exported catalogue. The manifest digest is part of the discovery
identity. Engine version, engine API 0.1, extension API 0.1, discovery protocol
0.1 and catalogue schema 0.1 are independently identified. The future SDK must
add its own independently versioned API and external package format contract;
these are not silently equated with the engine version.

Engine exports are derived from a deliberately registered public surface and
live signatures, plus registered operations and representation services. Guidance
and templates are checked against these public declarations. Export at release
time using python -m tools.export_sdk_landscape; --check detects drift. Both
wheel and source distribution include the installed landscape. PyCForge only
writes XML. It does not parse the exported file to decide runtime conversions.

Reader and cache behavior

The separate SDK checks discovery on every startup and headless connection and
supports explicit refresh. A compatible PyCForge update supplies updated methods
and guidance without rebuilding the SDK or overwriting extension source. Read
and verify the entire inventory before changing the active cache; reread the
manifest after transfer. Check identities, versions, required features, hashes,
lengths, paths, XML grammar and inventory agreement. Do not execute templates,
import entrypoints or fetch anything from the network during metadata refresh.

The source includes tools/sdk_catalogue_client.py as a separate reference reader
and qualification harness. It imports no engine code. It accepts bounded UTF-8
XML with an explicit closed structural validator, rejects DTDs, entity
declarations, XInclude and external references, enforces size/depth/node limits,
and performs no XML network access. ElementTree is not presented as an XSD
validator. The supplied local XSD also undergoes lxml validation in tests.
The reference client accepts additive methods and retains an old cache when an
existing public signature or import path changes incompatibly under API 0.1.

Staged snapshots use content-addressed directories; one atomic current.json
pointer selects the complete cache. Interruption before pointer replacement
leaves the previous snapshot selected. A failed refresh reports OFFLINE with
the old revision, or UNAVAILABLE without one. Cached data can be displayed,
but cannot authorize conversion using another engine. Recheck the selected
engine and manifest identity immediately before a later operation; stale
handles must be rejected. These are ordinary local-filesystem atomicity
semantics, not a power-loss or hostile concurrent-filesystem guarantee.
SHA256 verifies integrity and consistency, not publisher authenticity.

First math extension and API guarantees

The bundled pycforge.extensions.math module authors ScalarFunction and
ScalarConstant declarations inside one ScalarExtension. A closed immutable
ExtensionRegistry validates conflicting identities. Only reviewed bundled packs
and registered data-only scalar packages are admitted. Generic source binding, operation assessment and C scalar-call
lowering remain in the engine; the math file contains no converter mutations,
AST emitter code, C snippets or SDK dependency. A second native operation is
qualified through a separate .pcfplugin file and the public registration API
without editing or patching that adapter. It is not an external Python entrypoint loader. The separate data-only registration
profile is described in PyCForge-Conversion-Import-Registration-0.1.txt.

The explicit selection syntax is *import math [as alias] in a module's import
preamble. Ordinary import semantics are unchanged. Source declarations select
only the closed bundled namespace registry; no filesystem or Python import
fallback occurs. The first supported route is Runtime; Typed receives PYC4703.
Only fabs, sqrt, copysign, isfinite, isinf, isnan and pi/e/tau/inf/nan are
implemented. Calls are positional, scalar and direct; namespace rebinding,
shadowing and re-export are unsupported. Unsupported cases produce explicit
diagnostics and no new C. New syntax does not change ordinary-source output.

Run Python uses one shared preflight for explicit source snapshots. The UI
checks the selected saved document at the Run action; the launch service also
checks its current disk contents and any explicitly supplied companions before
spawning a process, even after command editing. Typing and dialog refresh do
not start extension scans. Unrelated open tabs and installed extensions are
not execution dependencies. The gate does not perform Python's dynamic import
discovery, rewrite declarations, run a supported prefix, or switch to C execution.
It is a language eligibility check, not a sandbox for arbitrary edited commands
or concurrent filesystem changes.

Each admitted source argument evaluates once in source order. Descriptor lookup
and compiler callbacks can repeat. Scalars allocate no new native resource and
retain/mutate no input pointees. The Runtime target owns source and resource
validation, error handling and output publication. Conversion exceptions cancel
publication; they do not publish partially generated C. Typed C-IR proof checks
do not apply to Runtime; its independent output/provenance validation remains
mandatory and its existing preview warning remains visible.

Deterministic conversion assumes fixed source snapshots, settings, engine and
bundled extension versions and target profile. Native numeric results assume
binary64, C11 math.h, default rounding and no fast-math. NaN payloads and bitwise
identity across arbitrary C libraries/platforms are not guaranteed. Inputs are
bool/int64/float64, not arbitrary Python big integers or custom numeric objects.
Negative sqrt raises ValueError; nonnumeric inputs raise TypeError. Native
build profiles must preserve signed zero, infinities and NaNs. Fast-math and
finite-math compilation are explicitly rejected for selected scalar extensions.

Remaining requirements before a general SDK API freeze

The requirements document's inspect/validate/test/activate facade is not yet a
complete implemented service. Public metadata discovery and declarative scalar
authoring and data-only scalar registration are implemented; a production SDK
GUI, external Python entrypoint package profile and execution worker, wall-clock supervision, scheduling services, general external Python activation and full conformance runner remain subsequent work.

The first .pcfplugin data-only scalar profile is implemented; it reads supplied
SDK verification results and performs bounded compatibility/integrity admission.
PyCForge does not run the SDK verification suite. The earlier ordinary-Python
entrypoint package proposal still requires controlled activation and supervision
before executing third-party code. Constructing an authoring registry does not
activate a package.
Before freezing the API, qualify additional buffer/view, caller ownership,
opaque-handle and native-resource examples, as the requirements document states.
Do not proliferate operation-specific flags in OperationRequest; its inherited
integer_divisor field is explicitly numeric-specific. Math expansion and NumPy
need operation-specific semantic/error contracts and target qualification.
