Skip to content

Studio Federation API

sc_neurocore.federation is the optional Hub-facing Studio federation surface. It is separate from the local FastAPI Studio app under sc_neurocore.studio: the federation package emits schema-A capability manifests, schema-B evidence bundles, and verifiable-honesty envelopes for SC-NeuroCore result claims.

Install the optional platform contract before importing it:

Bash
pip install "sc-neurocore[federation]"

The extra pins scpn-studio-platform>=0.9,<0.10. Environments without that platform SDK should not import this package; tests use pytest.importorskip so the base CI lane stays independent of the optional federation dependency.

Capability Manifest

Use build_manifest() to produce the schema-A manifest consumed by the Studio Hub:

Python
from sc_neurocore.federation import build_manifest

manifest = build_manifest()
assert manifest.studio == "sc-neurocore"

The manifest advertises eight verbs:

Verb Purpose Evidence schema
encode Convert float values into stochastic bitstreams. studio.bitstream-encoding.v1
simulate Run stochastic-computing inference. studio.sc-inference.v1
analyse Extract spike-train analysis results. studio.spike-analysis.v1
benchmark Measure backend throughput against the NumPy reference. studio.backend-benchmark.v1
validate Compare fixed-point reference and RTL co-simulation. studio.cosim-parity.v1
compile Lower a model to synthesisable RTL. studio.rtl-compilation.v1
synthesise Record synthesis resource/timing evidence. studio.fpga-deployment.v1
deploy Record FPGA deployment evidence. studio.fpga-deployment.v1

The committed manifest artifact lives at docs/_generated/studio_manifest.json and is generated by:

Bash
python tools/emit_studio_manifest.py
python tools/emit_studio_manifest.py --check

The digest covers the declared verbs and evidence schemas, not the current git state, so the manifest is stable across checkouts with the same federation surface.

Evidence Bundles

sc_inference_evidence() maps a stochastic inference result into a measured software evidence bundle. It renders as reference-validated only when the accelerated backend is bit-identical to the NumPy reference for the fixed seed. Otherwise the claim is bounded and rejected by the shared platform lattice.

fpga_deployment_evidence() maps a synthesis/deployment result into a hardware-validated FPGA evidence bundle. It renders as reference-validated only when the RTL co-simulation is bit-exact; a mismatch becomes validation-gap.

Python
from sc_neurocore.federation import (
    ScInferenceResult,
    sc_inference_evidence,
)

result = ScInferenceResult(
    active_backend="rust",
    reference_backend="numpy",
    max_abs_error=0.0,
    bitstream_length=4096,
    input_digest="sha256:" + "a" * 64,
    result_digest="sha256:" + "b" * 64,
)

bundle = sc_inference_evidence(
    result,
    operator="opaque:tenant-1",
    studio_version="3.15.35",
    started="2026-06-26T00:00:00Z",
    ended="2026-06-26T00:00:01Z",
)

Verifiable-Honesty Envelopes

The attestation helpers wrap platform seals so a rendered claim grade can be verified from signed evidence:

  • seal_sc_inference() uses recompute mode for bit-exact SC inference.
  • attest_fpga_deployment() uses attestation mode for FPGA result packs that cannot be recomputed client-side.
  • verify_envelope() recomputes the grade by schema and detects stripped, forged, or mismatched rendered claims.

FpgaArtifact entries must be content-addressed. A bit-exact FPGA claim earns the validated grade only when a cosim-transcript artifact backs it.

Reference

sc_neurocore.federation

SC-NeuroCore's STUDIO federation vertical on the scpn-studio-platform contract.

Hub-facing federation surface (schema-A capability manifest + schema-B evidence bundles), distinct from the local FastAPI Studio web app under sc_neurocore.studio. Importing this package requires the federation extra (pip install sc-neurocore[federation] → scpn-studio-platform>=0.9,<0.10, the era that ships the verifiable-honesty :mod:~scpn_studio_platform.seal module); a clean ModuleNotFoundError is raised when the platform SDK is absent, which is why tests guard with pytest.importorskip("scpn_studio_platform").

Example

from sc_neurocore.federation import build_manifest, fpga_deployment_evidence manifest = build_manifest() manifest.studio 'sc-neurocore'

PLATFORM_SDK_RANGE = '>=0.9,<0.10' module-attribute

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

PROTOCOL_VERSION = '1' module-attribute

The SYNAPSE wire protocol version the studio pins.

STUDIO_VERSION = _resolve_studio_version() module-attribute

The SC-NeuroCore studio version this manifest stamps (source package version).

NEUROCORE_VERBS = (ENCODE, SIMULATE, ANALYSE, BENCHMARK, VALIDATE, COMPILE, SYNTHESISE, DEPLOY) module-attribute

Every verb the SC-NeuroCore studio advertises, in manifest order.

STUDIO_ID = 'sc-neurocore' module-attribute

The studio identifier this vertical implements (also the federation name).

FpgaArtifact dataclass

A content-addressed FPGA evidence artifact backing a hardware claim.

Parameters

role What the artifact is — e.g. "synthesis-timing", "synthesis-utilisation", "cosim-transcript" (the bit-exactness proof), or "bitstream". digest SHA-256 of the artifact ("sha256:<hex>"); the identity that binds the claim to the real file. media_type The artifact's media type (e.g. "text/vivado-timing").

Raises

ValueError If any field is blank.

Source code in src/sc_neurocore/federation/attestation.py
Python
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
@dataclass(frozen=True)
class FpgaArtifact:
    """A content-addressed FPGA evidence artifact backing a hardware claim.

    Parameters
    ----------
    role
        What the artifact is — e.g. ``"synthesis-timing"``, ``"synthesis-utilisation"``,
        ``"cosim-transcript"`` (the bit-exactness proof), or ``"bitstream"``.
    digest
        SHA-256 of the artifact (``"sha256:<hex>"``); the identity that binds the claim
        to the real file.
    media_type
        The artifact's media type (e.g. ``"text/vivado-timing"``).

    Raises
    ------
    ValueError
        If any field is blank.
    """

    role: str
    digest: str
    media_type: str

    def __post_init__(self) -> None:
        """Reject blank fields — every artifact must be addressable."""
        if not self.role.strip() or not self.digest.strip() or not self.media_type.strip():
            raise ValueError("FpgaArtifact fields must be non-empty")

    def to_dict(self) -> dict[str, str]:
        """Return the JSON-serialisable mapping of the artifact."""
        return {"role": self.role, "digest": self.digest, "media_type": self.media_type}

__post_init__()

Reject blank fields — every artifact must be addressable.

Source code in src/sc_neurocore/federation/attestation.py
Python
82
83
84
85
def __post_init__(self) -> None:
    """Reject blank fields — every artifact must be addressable."""
    if not self.role.strip() or not self.digest.strip() or not self.media_type.strip():
        raise ValueError("FpgaArtifact fields must be non-empty")

to_dict()

Return the JSON-serialisable mapping of the artifact.

Source code in src/sc_neurocore/federation/attestation.py
Python
87
88
89
def to_dict(self) -> dict[str, str]:
    """Return the JSON-serialisable mapping of the artifact."""
    return {"role": self.role, "digest": self.digest, "media_type": self.media_type}

FpgaDeploymentResult dataclass

A path-free FPGA synthesis/deployment result.

Parameters

device The target device (e.g. "xc7z020-1clg400"). cosim_bit_exact Whether the synthesised RTL co-simulation matched the Q8.8 fixed-point reference bit-for-bit. lut_used, ff_used Look-up tables and flip-flops consumed by the synthesised design. worst_negative_slack_ns Worst negative slack at the target clock; >= 0 means timing closed. clock_mhz The synthesis target clock frequency, in MHz. result_digest SHA-256 of the bitstream / synthesis report.

Raises

ValueError If a resource count is negative, the clock is non-positive, or the digest is empty.

Source code in src/sc_neurocore/federation/evidence.py
Python
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
@dataclass(frozen=True)
class FpgaDeploymentResult:
    """A path-free FPGA synthesis/deployment result.

    Parameters
    ----------
    device
        The target device (e.g. ``"xc7z020-1clg400"``).
    cosim_bit_exact
        Whether the synthesised RTL co-simulation matched the Q8.8 fixed-point
        reference bit-for-bit.
    lut_used, ff_used
        Look-up tables and flip-flops consumed by the synthesised design.
    worst_negative_slack_ns
        Worst negative slack at the target clock; ``>= 0`` means timing closed.
    clock_mhz
        The synthesis target clock frequency, in MHz.
    result_digest
        SHA-256 of the bitstream / synthesis report.

    Raises
    ------
    ValueError
        If a resource count is negative, the clock is non-positive, or the digest
        is empty.
    """

    device: str
    cosim_bit_exact: bool
    lut_used: int
    ff_used: int
    worst_negative_slack_ns: float
    clock_mhz: float
    result_digest: str

    def __post_init__(self) -> None:
        """Validate resource counts, clock, and digest."""
        if self.lut_used < 0 or self.ff_used < 0:
            raise ValueError("FpgaDeploymentResult resource counts must be >= 0")
        if self.clock_mhz <= 0.0:
            raise ValueError("FpgaDeploymentResult.clock_mhz must be > 0")
        if not self.result_digest.strip():
            raise ValueError("FpgaDeploymentResult.result_digest must be non-empty")

__post_init__()

Validate resource counts, clock, and digest.

Source code in src/sc_neurocore/federation/evidence.py
Python
133
134
135
136
137
138
139
140
def __post_init__(self) -> None:
    """Validate resource counts, clock, and digest."""
    if self.lut_used < 0 or self.ff_used < 0:
        raise ValueError("FpgaDeploymentResult resource counts must be >= 0")
    if self.clock_mhz <= 0.0:
        raise ValueError("FpgaDeploymentResult.clock_mhz must be > 0")
    if not self.result_digest.strip():
        raise ValueError("FpgaDeploymentResult.result_digest must be non-empty")

ScInferenceResult dataclass

A path-free stochastic-computing inference result.

Parameters

active_backend The accelerated backend that produced the result (e.g. "rust"). reference_backend The bit-true reference backend (the NumPy floor). max_abs_error Maximum absolute difference between the active and reference outputs for the fixed seed; 0.0 means bit-identical. bitstream_length The stochastic bitstream length used. input_digest SHA-256 of the weights/inputs/seed. result_digest SHA-256 of the output firing rates.

Raises

ValueError If a count is non-positive, an error is negative, or a digest is empty.

Source code in src/sc_neurocore/federation/evidence.py
Python
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
@dataclass(frozen=True)
class ScInferenceResult:
    """A path-free stochastic-computing inference result.

    Parameters
    ----------
    active_backend
        The accelerated backend that produced the result (e.g. ``"rust"``).
    reference_backend
        The bit-true reference backend (the NumPy floor).
    max_abs_error
        Maximum absolute difference between the active and reference outputs for
        the fixed seed; ``0.0`` means bit-identical.
    bitstream_length
        The stochastic bitstream length used.
    input_digest
        SHA-256 of the weights/inputs/seed.
    result_digest
        SHA-256 of the output firing rates.

    Raises
    ------
    ValueError
        If a count is non-positive, an error is negative, or a digest is empty.
    """

    active_backend: str
    reference_backend: str
    max_abs_error: float
    bitstream_length: int
    input_digest: str
    result_digest: str

    def __post_init__(self) -> None:
        """Validate counts, error sign, and digests."""
        if self.bitstream_length <= 0:
            raise ValueError("ScInferenceResult.bitstream_length must be > 0")
        if self.max_abs_error < 0.0:
            raise ValueError("ScInferenceResult.max_abs_error must be >= 0")
        if not self.input_digest.strip() or not self.result_digest.strip():
            raise ValueError("ScInferenceResult digests must be non-empty")

__post_init__()

Validate counts, error sign, and digests.

Source code in src/sc_neurocore/federation/evidence.py
Python
88
89
90
91
92
93
94
95
def __post_init__(self) -> None:
    """Validate counts, error sign, and digests."""
    if self.bitstream_length <= 0:
        raise ValueError("ScInferenceResult.bitstream_length must be > 0")
    if self.max_abs_error < 0.0:
        raise ValueError("ScInferenceResult.max_abs_error must be >= 0")
    if not self.input_digest.strip() or not self.result_digest.strip():
        raise ValueError("ScInferenceResult digests must be non-empty")

attest_fpga_deployment(result, artifacts, *, signer)

Seal an FPGA deployment in attestation mode with a signed result-pack.

The FPGA run cannot be recomputed client-side, so the claim is verified by signature plus artifact-digest binding, not recompute. The result-pack reference content- addresses the real Vivado/cosim/bitstream artifacts and is studio-self-attested (the provider_sig is the studio's detached signature over the pack digest).

Parameters

result The path-free synthesis/deployment result. artifacts The content-addressed artifacts the claim rests on; at least one is required, and a cosim-transcript must be present for the claim to grade as validated. signer The studio's :class:~scpn_studio_platform.seal.keys.Signer.

Returns

HonestyEnvelope An attestation-verifiable envelope on the fpga substrate.

Raises

ValueError If no artifacts are supplied.

Source code in src/sc_neurocore/federation/attestation.py
Python
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def attest_fpga_deployment(
    result: FpgaDeploymentResult,
    artifacts: Iterable[FpgaArtifact],
    *,
    signer: Signer,
) -> HonestyEnvelope:
    """Seal an FPGA deployment in **attestation** mode with a signed result-pack.

    The FPGA run cannot be recomputed client-side, so the claim is verified by signature
    plus artifact-digest binding, not recompute. The result-pack reference content-
    addresses the real Vivado/cosim/bitstream artifacts and is studio-self-attested (the
    ``provider_sig`` is the studio's detached signature over the pack digest).

    Parameters
    ----------
    result
        The path-free synthesis/deployment result.
    artifacts
        The content-addressed artifacts the claim rests on; at least one is required, and
        a ``cosim-transcript`` must be present for the claim to grade as validated.
    signer
        The studio's :class:`~scpn_studio_platform.seal.keys.Signer`.

    Returns
    -------
    HonestyEnvelope
        An attestation-verifiable envelope on the ``fpga`` substrate.

    Raises
    ------
    ValueError
        If no artifacts are supplied.
    """
    materialised = list(artifacts)
    if not materialised:
        raise ValueError("attestation requires at least one content-addressed artifact")
    unit = _fpga_unit(result, materialised)
    pack_digest = content_digest({"artifacts": unit["artifacts"]})
    attestation = {
        "provider": f"vivado@{result.device}",
        "result_pack_digest": pack_digest,
        "provider_sig": base64.b64encode(signer.sign(pack_digest.encode("utf-8"))).decode("ascii"),
    }
    return seal(
        unit,
        signer=signer,
        grader=GRADER,
        verifiability_mode="attestation",
        exactness_class="bit-exact",
        attestation=attestation,
    )

regrade_fpga(unit)

Recompute the FPGA grade from the signed unit.

reference-validated only when the co-simulation is bit-exact and a cosim-transcript artifact backs that claim; otherwise validation-gap. A bit-exact flag with no transcript to prove it does not earn the validated grade.

Source code in src/sc_neurocore/federation/attestation.py
Python
176
177
178
179
180
181
182
183
184
185
def regrade_fpga(unit: Mapping[str, Any]) -> str:
    """Recompute the FPGA grade from the signed unit.

    ``reference-validated`` only when the co-simulation is bit-exact **and** a
    ``cosim-transcript`` artifact backs that claim; otherwise ``validation-gap``. A
    bit-exact flag with no transcript to prove it does not earn the validated grade.
    """
    if unit.get("cosim_bit_exact") is True and _has_cosim_transcript(unit):
        return _REFERENCE_VALIDATED
    return _VALIDATION_GAP

regrade_sc_inference(unit)

Recompute the sc-inference grade from the signed unit.

reference-validated only when the accelerated backend is bit-identical to the NumPy floor (max_abs_error == 0); otherwise bounded-model. Derived from the evidence, never read from a (forgeable) claim_status field.

Source code in src/sc_neurocore/federation/attestation.py
Python
114
115
116
117
118
119
120
121
def regrade_sc_inference(unit: Mapping[str, Any]) -> str:
    """Recompute the sc-inference grade from the signed unit.

    ``reference-validated`` only when the accelerated backend is bit-identical to the
    NumPy floor (``max_abs_error == 0``); otherwise ``bounded-model``. Derived from the
    evidence, never read from a (forgeable) ``claim_status`` field.
    """
    return _REFERENCE_VALIDATED if unit.get("max_abs_error") == 0.0 else _BOUNDED_MODEL

seal_sc_inference(result, *, signer)

Seal an sc-inference result in recompute mode (no attestation).

Parameters

result The path-free stochastic-computing inference result. signer The studio's :class:~scpn_studio_platform.seal.keys.Signer.

Returns

HonestyEnvelope A recompute-verifiable envelope: the WASM/NumPy kernel re-derives the result and its digest must match.

Source code in src/sc_neurocore/federation/attestation.py
Python
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
def seal_sc_inference(result: ScInferenceResult, *, signer: Signer) -> HonestyEnvelope:
    """Seal an sc-inference result in **recompute** mode (no attestation).

    Parameters
    ----------
    result
        The path-free stochastic-computing inference result.
    signer
        The studio's :class:`~scpn_studio_platform.seal.keys.Signer`.

    Returns
    -------
    HonestyEnvelope
        A recompute-verifiable envelope: the WASM/NumPy kernel re-derives the result and
        its digest must match.
    """
    return seal(
        _sc_inference_unit(result),
        signer=signer,
        grader=GRADER,
        verifiability_mode="recompute",
        exactness_class="bit-exact",
    )

verify_envelope(envelope, rendered_grade, *, keyring)

Verify a SC-NeuroCore honesty envelope, dispatching the regrade by schema.

Parameters

envelope The :meth:HonestyEnvelope.to_dict wire form on the page, or None when the page carries no seal. rendered_grade The grade the page displays for the claim, or None. keyring The trust anchor mapping key_id → public verifier.

Returns

Verdict :data:~scpn_studio_platform.seal.verdict.Verdict.VERIFIED only when the signature is valid and the rendered grade equals the grade recomputed from the signed unit; otherwise STRIPPED / FORGED / UNGRADED.

Source code in src/sc_neurocore/federation/attestation.py
Python
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
def verify_envelope(
    envelope: Mapping[str, Any] | None,
    rendered_grade: str | None,
    *,
    keyring: Keyring,
) -> Verdict:
    """Verify a SC-NeuroCore honesty envelope, dispatching the regrade by schema.

    Parameters
    ----------
    envelope
        The :meth:`HonestyEnvelope.to_dict` wire form on the page, or ``None`` when the
        page carries no seal.
    rendered_grade
        The grade the page displays for the claim, or ``None``.
    keyring
        The trust anchor mapping ``key_id`` → public verifier.

    Returns
    -------
    Verdict
        :data:`~scpn_studio_platform.seal.verdict.Verdict.VERIFIED` only when the
        signature is valid and the rendered grade equals the grade recomputed from the
        signed unit; otherwise ``STRIPPED`` / ``FORGED`` / ``UNGRADED``.
    """
    schema: object = None
    if isinstance(envelope, Mapping):
        unit = envelope.get("unit")
        if isinstance(unit, Mapping):
            schema = unit.get("schema")
    regrade = regrade_fpga if schema == FPGA_DEPLOYMENT_SCHEMA else regrade_sc_inference
    return verify(envelope, rendered_grade, keyring=keyring, regrade=regrade)

fpga_deployment_evidence(result, *, operator, studio_version, started, ended, host=None)

Build the studio.fpga-deployment.v1 bundle (hardware-validated silicon).

The synthesised RTL is co-simulated against the Q8.8 fixed-point reference on the fpga substrate. The claim is reference-validated only when that co-simulation is bit-exact; a mismatch degrades to validation-gap.

Parameters

result The path-free synthesis/deployment result. operator Opaque identity of the operator/tenant. studio_version Version of the SC-NeuroCore studio that produced the result. started, ended ISO-8601 start/end timestamps (passed in; no hidden clock). host Optional host descriptor the synthesis ran on.

Returns

EvidenceBundle A hardware-validated bundle on the fpga substrate.

Source code in src/sc_neurocore/federation/evidence.py
Python
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
def fpga_deployment_evidence(
    result: FpgaDeploymentResult,
    *,
    operator: str,
    studio_version: str,
    started: str,
    ended: str,
    host: str | None = None,
) -> EvidenceBundle:
    """Build the ``studio.fpga-deployment.v1`` bundle (hardware-validated silicon).

    The synthesised RTL is co-simulated against the Q8.8 fixed-point reference on
    the ``fpga`` substrate. The claim is ``reference-validated`` only when that
    co-simulation is bit-exact; a mismatch degrades to ``validation-gap``.

    Parameters
    ----------
    result
        The path-free synthesis/deployment result.
    operator
        Opaque identity of the operator/tenant.
    studio_version
        Version of the SC-NeuroCore studio that produced the result.
    started, ended
        ISO-8601 start/end timestamps (passed in; no hidden clock).
    host
        Optional host descriptor the synthesis ran on.

    Returns
    -------
    EvidenceBundle
        A ``hardware-validated`` bundle on the ``fpga`` substrate.
    """
    entity = ProvEntity(
        entity_id=f"{STUDIO_ID}/fpga-deployment/{result.result_digest}", digest=result.result_digest
    )
    activity = ProvActivity(
        verb="synthesise", studio=STUDIO_ID, started=started, ended=ended, host=host
    )
    agent = ProvAgent(studio_version=studio_version, operator=operator)
    cosim = CaseResult(
        operation_family="cosim-bit-exact",
        dimension=1,
        status="pass" if result.cosim_bit_exact else "fail",
        error=0.0 if result.cosim_bit_exact else None,
    )
    physical = PhysicalContract(
        units={"lut": "count", "ff": "count", "wns": "ns", "clock": "MHz"},
        grid={
            "device": result.device,
            "lut_used": result.lut_used,
            "ff_used": result.ff_used,
        },
    )
    claim = ClaimBoundary(
        status=ClaimStatus.REFERENCE_VALIDATED
        if result.cosim_bit_exact
        else ClaimStatus.VALIDATION_GAP,
        admission=AdmissionDecision.ADMITTED
        if result.cosim_bit_exact
        else AdmissionDecision.REJECTED,
        validity_domain=ValidityDomain(
            note=(
                "Bit-exact Q8.8 reference vs synthesised RTL co-simulation on the named "
                "device; hardware-validated for that fixed-point network, not a general "
                "floating-point accuracy guarantee."
            )
        ),
    )
    return EvidenceBundle(
        schema=FPGA_DEPLOYMENT_SCHEMA,
        entity=entity,
        activity=activity,
        agent=agent,
        evidence_level=EvidenceLevel.ENGINEERING_VERIFIED,
        evidence_kind=EvidenceKind.HARDWARE_VALIDATED,
        claim_boundary=claim,
        substrate=Substrate.FPGA,
        cases=(cosim,),
        physical_contract=physical,
    )

sc_inference_evidence(result, *, operator, studio_version, started, ended, host=None)

Build the studio.sc-inference.v1 bundle (measured software result).

Parameters

result The path-free inference result. operator Opaque identity of the operator/tenant. studio_version Version of the SC-NeuroCore studio that produced the result. started, ended ISO-8601 start/end timestamps (passed in; no hidden clock). host Optional host descriptor the run executed on.

Returns

EvidenceBundle A measured bundle that renders as validated only when the accelerated backend is bit-identical to the NumPy floor.

Source code in src/sc_neurocore/federation/evidence.py
Python
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
def sc_inference_evidence(
    result: ScInferenceResult,
    *,
    operator: str,
    studio_version: str,
    started: str,
    ended: str,
    host: str | None = None,
) -> EvidenceBundle:
    """Build the ``studio.sc-inference.v1`` bundle (measured software result).

    Parameters
    ----------
    result
        The path-free inference result.
    operator
        Opaque identity of the operator/tenant.
    studio_version
        Version of the SC-NeuroCore studio that produced the result.
    started, ended
        ISO-8601 start/end timestamps (passed in; no hidden clock).
    host
        Optional host descriptor the run executed on.

    Returns
    -------
    EvidenceBundle
        A ``measured`` bundle that renders as validated only when the accelerated
        backend is bit-identical to the NumPy floor.
    """
    bit_identical = result.max_abs_error == 0.0
    entity = ProvEntity(
        entity_id=f"{STUDIO_ID}/sc-inference/{result.result_digest}", digest=result.result_digest
    )
    activity = ProvActivity(
        verb="simulate", studio=STUDIO_ID, started=started, ended=ended, host=host
    )
    agent = ProvAgent(studio_version=studio_version, operator=operator)
    numeric = NumericProvenance(
        active_backend=result.active_backend, reference_backend=result.reference_backend
    )
    claim = ClaimBoundary(
        status=ClaimStatus.REFERENCE_VALIDATED if bit_identical else ClaimStatus.BOUNDED_MODEL,
        admission=AdmissionDecision.ADMITTED if bit_identical else AdmissionDecision.REJECTED,
        validity_domain=ValidityDomain(
            note=(
                "Stochastic-computing forward pass; reference-validated only against the "
                "bit-true NumPy floor for a fixed seed, not against a third-party SNN simulator."
            )
        ),
    )
    return EvidenceBundle(
        schema=SC_INFERENCE_SCHEMA,
        entity=entity,
        activity=activity,
        agent=agent,
        evidence_level=EvidenceLevel.ENGINEERING_VERIFIED,
        evidence_kind=EvidenceKind.MEASURED,
        claim_boundary=claim,
        numeric_provenance=numeric,
    )

build_manifest(*, studio_version=STUDIO_VERSION)

Build the SC-NeuroCore studio's capability manifest.

Parameters

studio_version The studio version to stamp; defaults to :data:STUDIO_VERSION (the source sc-neurocore version).

Returns

CapabilityManifest The schema-A manifest, with a content digest over :func:declared_surface.

Source code in src/sc_neurocore/federation/manifest.py
Python
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def build_manifest(*, studio_version: str = STUDIO_VERSION) -> CapabilityManifest:
    """Build the SC-NeuroCore studio's capability manifest.

    Parameters
    ----------
    studio_version
        The studio version to stamp; defaults to :data:`STUDIO_VERSION` (the
        source ``sc-neurocore`` version).

    Returns
    -------
    CapabilityManifest
        The schema-A manifest, with a content digest over :func:`declared_surface`.
    """
    return CapabilityManifest(
        studio=STUDIO_ID,
        studio_version=studio_version,
        platform_sdk=PLATFORM_SDK_RANGE,
        content_digest=content_digest(declared_surface()),
        protocol_version=PROTOCOL_VERSION,
        transport_profile=TransportProfile.LOCAL_FIRST,
        verbs=NEUROCORE_VERBS,
        evidence_types=evidence_schemas(),
        ui_module=None,
    )

declared_surface()

Return the content-addressable declared surface of the SC-NeuroCore studio.

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

Returns

dict[str, bytes] Mapping of logical path to canonical-JSON bytes, suitable for :func:scpn_studio_platform.manifest.content_digest.

Source code in src/sc_neurocore/federation/manifest.py
Python
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def declared_surface() -> dict[str, bytes]:
    """Return the content-addressable declared surface of the SC-NeuroCore studio.

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

    Returns
    -------
    dict[str, bytes]
        Mapping of logical path to canonical-JSON bytes, suitable for
        :func:`scpn_studio_platform.manifest.content_digest`.
    """
    surface: dict[str, bytes] = {
        f"verb/{verb.name}": json.dumps(
            verb.to_dict(), sort_keys=True, separators=(",", ":")
        ).encode("utf-8")
        for verb in NEUROCORE_VERBS
    }
    surface["evidence/schemas"] = json.dumps(
        list(evidence_schemas()), sort_keys=True, separators=(",", ":")
    ).encode("utf-8")
    return surface

core_verbs()

Return the SC-NeuroCore verbs drawn from the shared core spine.

Returns

tuple[Verb, ...] The subset of :data:NEUROCORE_VERBS whose names are in the platform :data:scpn_studio_platform.verbs.CORE_VERBS.

Source code in src/sc_neurocore/federation/verbs.py
Python
148
149
150
151
152
153
154
155
156
157
def core_verbs() -> tuple[Verb, ...]:
    """Return the SC-NeuroCore verbs drawn from the shared core spine.

    Returns
    -------
    tuple[Verb, ...]
        The subset of :data:`NEUROCORE_VERBS` whose names are in the platform
        :data:`scpn_studio_platform.verbs.CORE_VERBS`.
    """
    return tuple(verb for verb in NEUROCORE_VERBS if verb.is_core)

domain_verbs()

Return the SC-NeuroCore verbs distinctive to a neuromorphic studio.

Returns

tuple[Verb, ...] The subset of :data:NEUROCORE_VERBS not present in the platform core spine (encode, deploy).

Source code in src/sc_neurocore/federation/verbs.py
Python
160
161
162
163
164
165
166
167
168
169
def domain_verbs() -> tuple[Verb, ...]:
    """Return the SC-NeuroCore verbs distinctive to a neuromorphic studio.

    Returns
    -------
    tuple[Verb, ...]
        The subset of :data:`NEUROCORE_VERBS` not present in the platform core
        spine (``encode``, ``deploy``).
    """
    return tuple(verb for verb in NEUROCORE_VERBS if not verb.is_core)

evidence_schemas()

Return the distinct evidence schemas every SC-NeuroCore verb emits.

Returns

tuple[str, ...] The sorted, de-duplicated union of each verb's produces schemas.

Source code in src/sc_neurocore/federation/verbs.py
Python
172
173
174
175
176
177
178
179
180
181
def evidence_schemas() -> tuple[str, ...]:
    """Return the distinct evidence schemas every SC-NeuroCore verb emits.

    Returns
    -------
    tuple[str, ...]
        The sorted, de-duplicated union of each verb's ``produces`` schemas.
    """
    schemas = {schema for verb in NEUROCORE_VERBS for schema in verb.produces}
    return tuple(sorted(schemas))