scpn_fusion.studio – Studio Federation

The Studio package emits the schema-A federation manifest, architecture-map extension, evidence-schema vocabulary, and exactness-class reproduction comparator.

Package Re-exports

The FUSION studio’s federation surface on the SCPN-STUDIO platform contract.

Exposes the schema-A capability manifest (verbs, evidence schemas, content digest) that the Hub ingests for federation. See scpn_fusion.studio.manifest and scpn_fusion.studio.verbs.

class scpn_fusion.studio.ComparisonResult(verdict, detail)[source]

Bases: object

One reproduction comparison verdict with a human-readable rationale.

Parameters:

  • verdict (ReproVerdict) – The ReproVerdict.

  • detail (str) – A one-line explanation (the band, the digest mismatch, the absent class).

property reproduced: bool

Return whether the recompute counts as an honest reproduction.

True for a bit-exact match or a within-tolerance float recompute; False for drift or an unverifiable (un-declared) claim.

verdict: ReproVerdict
detail: str
scpn_fusion.studio.build_architecture_map_extension()[source]

Return the architecture-map extension block (fleet architecture-map.v2 schema).

Additive superset over schema A: the pipeline, capability inventory, backend/dispatch matrix, interface surface, cross-repo wire formats, and honest scope boundaries. The field set is peer-aligned with the fleet; the Hub ignores it for federation, the architecture docs consume it.

Returns:

The architecture-map.v2 extension block.

Return type:

dict[str, Any]

scpn_fusion.studio.build_federation_document()[source]

Return the full federation document: schema_a core + architecture_map extension.

Returns:

Mapping with a schema_a capability-manifest block and an architecture_map extension block.

Return type:

dict[str, Any]

scpn_fusion.studio.build_manifest(*, studio_version='4.0.0')[source]

Build the FUSION studio’s capability manifest (schema A).

Parameters:

studio_version (str) – The studio version to stamp; defaults to STUDIO_VERSION.

Returns:

The schema-A manifest, with a content digest over declared_surface().

Return type:

CapabilityManifest

scpn_fusion.studio.canonical_value_digest(value)[source]

Return a language-independent content digest of a committed reference value series.

For a tolerance or stochastic claim, large reference arrays do not belong inline in the signed envelope; the envelope carries only this digest, and the values live in a side artifact. The verifier fetches the side artifact, recomputes this digest, and checks it equals the signed one BEFORE the tolerance compare — so the fetched values are tamper-evident.

The digest is taken over the raw IEEE-754 float64 little-endian bytes, NOT a decimal string representation, so the producer (Python) and consumer (browser/JS) agree byte-for-byte regardless of float formatting — it sidesteps the json.dumps(1e-6)='1e-06' vs JS '0.000001' divergence entirely (you digest the bytes, not a language-dependent repr).

Parameters:

value (ndarray[Any, dtype[float64]] | float) – The committed reference value(s) (scalar or array).

Returns:

A sha256:<hex> digest of the canonical little-endian float64 byte image.

Return type:

str

scpn_fusion.studio.compare_bit_exact(recomputed_digest, committed_digest)[source]

Compare two content digests for a bit-exact claim, wrapping the SDK verdict.

The actual digest comparison is delegated to the platform SDK’s dependency-free scpn_studio_platform.exactness.compare_bit_exact() (the single source for the axis); this wrapper adds FUSION’s ComparisonResult rationale so the bit-exact and the numpy tolerance paths return one consistent type.

Parameters:

  • recomputed_digest (str) – The sha256:<hex> digest of the in-browser recompute.

  • committed_digest (str) – The committed claim’s digest.

Returns:

MATCH on exact digest equality, else DRIFT (loud, tamper-evident).

Return type:

ComparisonResult

scpn_fusion.studio.compare_tolerance(recomputed, reference, *, rtol=1e-09, atol=0.0)[source]

Compare a recomputed float value/array against a committed reference within tolerance.

Parameters:

  • recomputed (ndarray[Any, dtype[float64]] | float) – The in-browser recompute (scalar or array).

  • reference (ndarray[Any, dtype[float64]] | float) – The committed reference value(s).

  • rtol (float) – The relative and absolute tolerance band (atol + rtol * |reference|). For a UQ-grounded band, pass atol = reduce_to_scalar(uq) and rtol = 0.0.

  • atol (float) – The relative and absolute tolerance band (atol + rtol * |reference|). For a UQ-grounded band, pass atol = reduce_to_scalar(uq) and rtol = 0.0.

Returns:

WITHIN_TOLERANCE if the recompute is inside the band, else DRIFT.

Return type:

ComparisonResult

Raises:

ValueError – If rtol or atol is negative (a tolerance band must be non-negative).

scpn_fusion.studio.declared_surface()[source]

Return the content-addressable declared surface of the FUSION studio.

The surface is the canonical JSON of each advertised verb plus the evidence schema list, keyed by a stable logical path. Hashing the declared content (not git state) is what makes the digest reproducible across checkouts.

Returns:

Mapping of logical path to canonical-JSON bytes, suitable for scpn_studio_platform.manifest.content_digest().

Return type:

dict[str, bytes]

scpn_fusion.studio.evidence_schemas()[source]

Return the studio.*.v1 evidence-schema names this studio emits.

The order is stable so the content digest over the declared surface is reproducible across checkouts.

Returns:

The evidence-schema identifiers produced by FUSION_VERBS.

Return type:

tuple[str, …]

scpn_fusion.studio.reproduce(exactness_class, *, recomputed_digest=None, committed_digest=None, recomputed_value=None, reference_value=None, rtol=1e-09, atol=0.0)[source]

Dispatch a reproduction comparison on the claim’s exactness class.

A stochastic claim must be reduced by the caller (seed the RNG, then pass the reduced bit-exact or tolerance class with its payload); passing STOCHASTIC here is itself an error because the reduction is the caller’s responsibility.

Parameters:

  • exactness_class (ExactnessClass | None) – The declared class, or None (which yields UNVERIFIABLE — never a silent default).

  • recomputed_digest (str | None) – Required for bit-exact.

  • committed_digest (str | None) – Required for bit-exact.

  • recomputed_value (NDArray[np.float64] | float | None) – Required for tolerance.

  • reference_value (NDArray[np.float64] | float | None) – Required for tolerance.

  • rtol (float) – The tolerance band for tolerance.

  • atol (float) – The tolerance band for tolerance.

Returns:

The verdict; UNVERIFIABLE when no class is declared.

Return type:

ComparisonResult

Raises:

ValueError – If the class is STOCHASTIC (must be reduced first), or the payload required for the declared class is missing.

scpn_fusion.studio.write_federation_document(repo_root=None)[source]

Write the federation document to STUDIO_MANIFEST_PATH and return the path.

Parameters:

repo_root (Path | None) – Repository root; defaults to the current working directory.

Returns:

The written file path.

Return type:

pathlib.Path

Manifest

The FUSION studio’s capability manifest (schema A) on the platform contract.

Authors FUSION’s scpn_studio_platform.manifest.CapabilityManifest: the verbs it advertises (scpn_fusion.studio.verbs), the evidence schemas they emit, and a content-addressed digest of that declared surface. The digest is computed with scpn_studio_platform.manifest.content_digest() over the canonical JSON of the declared verbs and evidence schemas, so it is reproducible across checkouts and independent of git state — the digest tracks the declared content, not the working tree.

FUSION does not yet ship a federated Studio UI panel, so ui_module is None; the panel is added once the Studio UI binding exists.

scpn_fusion.studio.manifest.PLATFORM_SDK_RANGE = '>=0.10,<0.11'

The platform SDK SemVer range the studio builds on (matches the studio extra).

scpn_fusion.studio.manifest.PROTOCOL_VERSION = '1'

The SYNAPSE wire protocol version the studio pins.

scpn_fusion.studio.manifest.STUDIO_VERSION = '4.0.0'

The FUSION studio version this manifest stamps (the installed package version).

scpn_fusion.studio.manifest.declared_surface()[source]

Return the content-addressable declared surface of the FUSION studio.

The surface is the canonical JSON of each advertised verb plus the evidence schema list, keyed by a stable logical path. Hashing the declared content (not git state) is what makes the digest reproducible across checkouts.

Returns:

Mapping of logical path to canonical-JSON bytes, suitable for scpn_studio_platform.manifest.content_digest().

Return type:

dict[str, bytes]

scpn_fusion.studio.manifest.build_manifest(*, studio_version='4.0.0')[source]

Build the FUSION studio’s capability manifest (schema A).

Parameters:

studio_version (str) – The studio version to stamp; defaults to STUDIO_VERSION.

Returns:

The schema-A manifest, with a content digest over declared_surface().

Return type:

CapabilityManifest

Federation Document

The FUSION studio’s federation document for STUDIO/Hub ingestion.

The federation document is one JSON with two blocks, per the locked fleet convention:

  • schema_a — the platform CapabilityManifest (verbs, evidence schemas, content digest). This is the federation contract the Hub ingests; its vocabulary is the locked SDK enums emitted verbatim.

  • architecture_map — an additive superset block the Hub ignores for federation but the architecture docs consume: the per-stage IO pipeline, the capability inventory, the backend/dispatch matrix, the interface surface, the cross-repo wire formats, and the honest scope boundaries. The field set is the fleet architecture-map.v2 schema (peer-aligned with SC-NEUROCORE and QUANTUM, 2026-06-24); it mirrors docs/ARCHITECTURE.md.

This is emitted to a dedicated file so it never collides with the repository inventory manifest (docs/_generated/capability_manifest.json).

scpn_fusion.studio.federation.STUDIO_MANIFEST_PATH = PosixPath('docs/_generated/studio_manifest.json')

Where the federation document is written, relative to the repository root.

scpn_fusion.studio.federation.ARCHITECTURE_MAP_VERSION = 'architecture-map.v2'

The fleet architecture-map extension schema version (peer-aligned with the fleet).

scpn_fusion.studio.federation.build_architecture_map_extension()[source]

Return the architecture-map extension block (fleet architecture-map.v2 schema).

Additive superset over schema A: the pipeline, capability inventory, backend/dispatch matrix, interface surface, cross-repo wire formats, and honest scope boundaries. The field set is peer-aligned with the fleet; the Hub ignores it for federation, the architecture docs consume it.

Returns:

The architecture-map.v2 extension block.

Return type:

dict[str, Any]

scpn_fusion.studio.federation.build_federation_document()[source]

Return the full federation document: schema_a core + architecture_map extension.

Returns:

Mapping with a schema_a capability-manifest block and an architecture_map extension block.

Return type:

dict[str, Any]

scpn_fusion.studio.federation.write_federation_document(repo_root=None)[source]

Write the federation document to STUDIO_MANIFEST_PATH and return the path.

Parameters:

repo_root (Path | None) – Repository root; defaults to the current working directory.

Returns:

The written file path.

Return type:

pathlib.Path

scpn_fusion.studio.federation.studio_manifest_drift(repo_root=None)[source]

Return a drift description if the committed studio manifest is stale, else None.

The committed docs/_generated/studio_manifest.json must byte-match the generator output, so an edit to the verbs/evidence/architecture-map that forgets to re-emit cannot ship a stale federation artefact for the keeper gate to ingest.

Parameters:

repo_root (Path | None) – Repository root; defaults to the current working directory.

Returns:

A human-readable drift description, or None when the artefact is current.

Return type:

str or None

scpn_fusion.studio.federation.main(argv=None)[source]

Emit the federation document, or --check it for drift.

Parameters:

argv (Sequence[str] | None) – Command-line arguments; defaults to sys.argv[1:].

Returns:

0 on success, 1 when --check finds a drifted or missing artefact.

Return type:

int

Exactness Comparator

The exactness-class reproduction comparator — FUSION’s WS-2 reference implementation.

The fleet honesty model says an in-browser recompute “matches” a committed claim, but its two pins are in tension for floating-point kernels: H2 (digest equality) and H3 (tolerance-aware). Float kernels are not bit-reproducible across toolchains (x86 / ARM / WASM-SIMD, FMA contraction, compiler flags, libm), so a correct recompute yields a different digest and a naive digest check fires a false drift alarm. WS-2 resolves this with a per-claim exactness class that decides how the verifier compares:

  • bit-exact — the recomputed value’s content digest must equal the committed digest. For integer / fixed-point / genuinely bit-reproducible kernels (the producer asserts toolchain independence; CI must cross-check it).

  • tolerance — the recomputed value must match the committed reference value within a band (atol + rtol * |ref|, NumPy allclose semantics). The band is static {rtol, atol} or a scalar reduced from a UQ envelope (reduce_to_scalar(uq), supplied by the producer). For float kernels — the majority of FUSION and the fleet.

  • stochastic — reproduction needs the committed seed and RNG identity, after which it reduces to bit-exact or tolerance. (This module compares the reduced form; seeding is the caller’s.)

This is a pure comparison function over (recomputed, committed, exactness-class) — no I/O, no signing (signing is WS-1). It returns an honest verdict, including unverifiable when the exactness class is absent, never silently defaulting (a default would false-drift floats or mask a bit-exact regression). The browser @anulum/verify lib mirrors this verdict-for-verdict.

class scpn_fusion.studio.exactness.ComparisonResult(verdict, detail)[source]

Bases: object

One reproduction comparison verdict with a human-readable rationale.

Parameters:

  • verdict (ReproVerdict) – The ReproVerdict.

  • detail (str) – A one-line explanation (the band, the digest mismatch, the absent class).

verdict: ReproVerdict
detail: str
property reproduced: bool

Return whether the recompute counts as an honest reproduction.

True for a bit-exact match or a within-tolerance float recompute; False for drift or an unverifiable (un-declared) claim.

scpn_fusion.studio.exactness.canonical_value_digest(value)[source]

Return a language-independent content digest of a committed reference value series.

For a tolerance or stochastic claim, large reference arrays do not belong inline in the signed envelope; the envelope carries only this digest, and the values live in a side artifact. The verifier fetches the side artifact, recomputes this digest, and checks it equals the signed one BEFORE the tolerance compare — so the fetched values are tamper-evident.

The digest is taken over the raw IEEE-754 float64 little-endian bytes, NOT a decimal string representation, so the producer (Python) and consumer (browser/JS) agree byte-for-byte regardless of float formatting — it sidesteps the json.dumps(1e-6)='1e-06' vs JS '0.000001' divergence entirely (you digest the bytes, not a language-dependent repr).

Parameters:

value (ndarray[Any, dtype[float64]] | float) – The committed reference value(s) (scalar or array).

Returns:

A sha256:<hex> digest of the canonical little-endian float64 byte image.

Return type:

str

scpn_fusion.studio.exactness.compare_bit_exact(recomputed_digest, committed_digest)[source]

Compare two content digests for a bit-exact claim, wrapping the SDK verdict.

The actual digest comparison is delegated to the platform SDK’s dependency-free scpn_studio_platform.exactness.compare_bit_exact() (the single source for the axis); this wrapper adds FUSION’s ComparisonResult rationale so the bit-exact and the numpy tolerance paths return one consistent type.

Parameters:

  • recomputed_digest (str) – The sha256:<hex> digest of the in-browser recompute.

  • committed_digest (str) – The committed claim’s digest.

Returns:

MATCH on exact digest equality, else DRIFT (loud, tamper-evident).

Return type:

ComparisonResult

scpn_fusion.studio.exactness.compare_tolerance(recomputed, reference, *, rtol=1e-09, atol=0.0)[source]

Compare a recomputed float value/array against a committed reference within tolerance.

Parameters:

  • recomputed (ndarray[Any, dtype[float64]] | float) – The in-browser recompute (scalar or array).

  • reference (ndarray[Any, dtype[float64]] | float) – The committed reference value(s).

  • rtol (float) – The relative and absolute tolerance band (atol + rtol * |reference|). For a UQ-grounded band, pass atol = reduce_to_scalar(uq) and rtol = 0.0.

  • atol (float) – The relative and absolute tolerance band (atol + rtol * |reference|). For a UQ-grounded band, pass atol = reduce_to_scalar(uq) and rtol = 0.0.

Returns:

WITHIN_TOLERANCE if the recompute is inside the band, else DRIFT.

Return type:

ComparisonResult

Raises:

ValueError – If rtol or atol is negative (a tolerance band must be non-negative).

scpn_fusion.studio.exactness.reproduce(exactness_class, *, recomputed_digest=None, committed_digest=None, recomputed_value=None, reference_value=None, rtol=1e-09, atol=0.0)[source]

Dispatch a reproduction comparison on the claim’s exactness class.

A stochastic claim must be reduced by the caller (seed the RNG, then pass the reduced bit-exact or tolerance class with its payload); passing STOCHASTIC here is itself an error because the reduction is the caller’s responsibility.

Parameters:

  • exactness_class (ExactnessClass | None) – The declared class, or None (which yields UNVERIFIABLE — never a silent default).

  • recomputed_digest (str | None) – Required for bit-exact.

  • committed_digest (str | None) – Required for bit-exact.

  • recomputed_value (NDArray[np.float64] | float | None) – Required for tolerance.

  • reference_value (NDArray[np.float64] | float | None) – Required for tolerance.

  • rtol (float) – The tolerance band for tolerance.

  • atol (float) – The tolerance band for tolerance.

Returns:

The verdict; UNVERIFIABLE when no class is declared.

Return type:

ComparisonResult

Raises:

ValueError – If the class is STOCHASTIC (must be reduced first), or the payload required for the declared class is missing.

Verb and Evidence Schema Vocabulary

The advertised verb names are reconstruct, simulate, analyse, validate, benchmark, replay, control, and predict. The schema-A SDK stores them as Verb values in scpn_fusion.studio.verbs.FUSION_VERBS.

scpn_fusion.studio.verbs.evidence_schemas()[source]

Return the studio.*.v1 evidence-schema names this studio emits.

The order is stable so the content digest over the declared surface is reproducible across checkouts.

Returns:

The evidence-schema identifiers produced by FUSION_VERBS.

Return type:

tuple[str, …]