PyCForge SDK landscape 0.2

Discover the selected installed engine:
  SELECTED_PYTHON -m pycforge --format json sdk-api
or call pycforge.crucible.sdk_api.discover() in that environment.
This endpoint runs in the selected engine environment. No PySide6 import or
SDK installation is required. The returned folder is authoritative for that
engine installation, not the SDK's own Python environment or working directory.

index.json is the entry point. api.xml describes registered public methods,
constructors, signatures, operations, route decisions, scalar representations,
ownership boundaries, bundled packs, capabilities, limits and diagnostics.
api.xsd is the local schema. requirements.txt is the original API requirements.
scalar_template.py is inert authoring guidance; catalogue refresh must not
import it or any extension code. API 0.1 remains provisional.

SDK responsibility: discover on every startup and headless connect, and expose
explicit refresh during a session. Check protocol, schema, engine API, extension
API, required features, all file lengths and SHA256 values, XML structure and
inventory consistency. Read index.json again after copying to detect a mixed
upgrade. Stage a complete snapshot then atomically change the active cache
pointer. On failure keep the last valid snapshot explicitly labeled OFFLINE;
do not authorize operations against a different engine using stale handles.
Re-discover and compare engine identity and manifest hash before an operation.
The future PySide6 application and headless SDK must share this reader/service.
An additive public method needs a new catalogue export, not an SDK UI rewrite.
Unknown required features or incompatible versions block connection. Do not
silently interpret new required semantics. No network is needed or permitted
for refresh. Do not overwrite a developer's extension source or execute a
catalogue-provided method/template during refresh. Hashes detect mixed or
corrupted inventory; they do not establish package publisher authenticity.

The engine exports this data from explicitly registered public interfaces. It
never parses its own XML for conversions. Run tools.export_sdk_landscape --check
in source qualification. tools.sdk_catalogue_client is a separate, stdlib-only
qualification reader demonstrating startup refresh, closed-schema checking,
bounded UTF-8 XML, DTD/entity/XInclude rejection, hash inventory verification,
atomic cache switching and stale-engine rejection. It does not implement the
future SDK GUI, Python entrypoint activation, worker supervision or complete conformance tools.
The accompanying XSD is additionally checked with lxml in release qualification;
the stdlib reader has an explicit structural validator, not an assumed XSD one.

Math pack 0.2.0: *import math [as alias], Runtime route only. The catalogue lists
36 functions for roots, classification, trigonometry/hyperbolic functions,
exponentials/logarithms, powers/remainders, error functions and integer rounding.
Constants remain pi, e, tau, inf, nan. Use the declared call signatures; log takes an optional positional base and isclose supports named values and keyword-only tolerances.
Functions are not first-class values. Namespace rebinding, shadowing, re-export,
undeclared keywords and argument expansion are deliberately rejected. Module constants
may refer to extension constants. Ordinary import math still means an ordinary
source-bundle import. Each consuming module declares its own extension import.
No host Python math module is imported to convert source or run generated C.

Scalar profile: bool/int64/float64 values, binary64 double, C11 math.h, default
round-to-nearest, no fast-math, POSIX libm (-lm); existing Runtime resource and
arena rules apply. Declared domain failures raise ValueError; nonnumeric arguments raise TypeError.
Checked libm calls translate finite-input overflow to OverflowError and permit
underflow. Rounding operations preserve original integer inputs and range-check
floating results before producing bounded int64 integers. NaNs and infinities are admitted where the operation defines
them; NaN payloads and bitwise cross-platform libm equality are not promised.
Compiler callbacks may repeat; source arguments evaluate once, left to right.
No arbitrary-precision integers, custom __float__, full math or NumPy coverage.

Constructing ScalarExtension/ExtensionRegistry validates a trusted authoring
snapshot. It does not activate a package. ImportRegistrationStore separately
admits data-only .pcfplugin scalar packages and keeps immutable copies. Conversion
uses one snapshot of ready registrations, including the bundled math pack.
Registration reads SDK verification metadata; it never runs the SDK test suite.
The register dialog shows author/date/version and an explicit Cannot use status
with SDK guidance for bad imports. Declaration metadata identifies contracts; its
fingerprint is not an attestation of arbitrary Python code. A future Python
entrypoint package profile, process supervision and stable general resource
contracts remain explicit requirements. See the source registration contract.

SDK candidate testing uses PythonToCConverter(extension_registry=candidate),
where candidate is an immutable ExtensionRegistry. This authoring context does
not read or change registrations and explicitly reports PYC4708: conversion is
not SDK verification. Compile/reference-test that output before package_bytes()
and explicit register_file(). A verified status is never needed just to test
an unregistered candidate. The installed API catalogue includes this constructor.

Companion SDK authoring service (PyCForge 1.3.64)

The separate PyCForge SDK 0.3.0 supplies an importable headless backend and
console. Select this engine's interpreter explicitly. ScalarAuthoring accepts
a data-only declaration, inspect() returns its accepted capabilities, convert()
uses an unregistered immutable candidate, and package() serializes the caller's
verification statement. The SDK owns explicit fixture execution and its build
gate. The engine does not run the SDK suite. No PySide6 SDK UI is included.

authoring.json adds task categories, public paths, parameter explanations,
defaults, return/effect/error descriptions, inert examples/templates and the
engine's native test profile. Its schema is independently versioned. Existing
XML catalogue and extension API are 0.2; discovery and engine API remain 0.1.
The SDK accepts both catalogue versions and preserves legacy package identities.
math-template.json supplies a complete inert starter with native/reference and
boundary fixtures. New verification requires source-call coverage of all exports;
it does not prove dynamic branch coverage or every possible input.
The source specifications/PyCForge-SDK-Framework-0.3.md defines the two-product
boundary, evidence requirements and outstanding general-extension gates.

Conversion imports are an ongoing capability, with no two-library limit. The
current directive supersedes that earlier restriction. New import families
must establish public semantic, ownership and platform contracts through the
separate SDK before wider support is claimed.

Documented authoring workflow

ScalarAuthoring.scan(documentation, examples=...) returns a versioned reference,
a blank author template and JSON-pointer issues. It never executes examples.
The SDK scan command binds readiness to the exact project revision. document
adds missing author fields without replacing existing prose. Authors complete
meaningful explanations, then verify native cases and build a documented
package. Scan success means ready to verify, not that native behavior passed.

SDK project/verification schemas 0.2 bind documentation to evidence. Changes
to notes, contracts, fixtures, engine, SDK or compiler require fresh verification.
Current SDK builds require the advertised extension-help/0.1 capability; older
projects need an explicit document upgrade and author completion. The separate
PySide6 UI is not included; Python and console clients share this workflow.

Scalar parameter contracts (0.3)
------------------------------
Explicit parameter names, kinds and inert defaults are documented by ScalarParameter and ScalarFunction. JSON declarations use schema /0.3. The SDK 0.4 reader accepts catalogues 0.1, 0.2 and 0.3; earlier readers refuse 0.3 and retain offline caches. Use the named-scalar template to exercise an independent signal_ops namespace. Math 0.3.0 and signal_ops use the same public path. NumPy, array ownership and lifetime contracts remain outside this scalar profile.
