voltry-probe 0.1.0__py3-none-any.whl

voltry_probe/__init__.py

@@ -0,0 +1,40 @@
+"""Voltry Probe — the open, read-only agent.
+
+Read mode (Stage 3): read-only NVML/DCGM/Redfish mappers + real attestation verification
+→ a signed evidence bundle. Render (Stage 4), CLI + container (Stage 5), and the
+functional/monitor modes (Stage 9) build on this.
+"""
+
+from __future__ import annotations
+
+from .attestation import AttestationOutcome, AttestationReport, verify_attestation
+from .evidence import build_functional_bundle, build_monitor_bundle, build_read_bundle
+from .functional import DrainConsentError, FunctionalRunner
+from .monitor import MonitorSession, TelemetrySample
+from .readers import map_dcgm, map_nvml, map_redfish, normalize_xid
+from .render import render_certificate
+from .sources import FixtureSource, RawCapture, RawSource
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "build_read_bundle",
+    "build_functional_bundle",
+    "build_monitor_bundle",
+    "FunctionalRunner",
+    "DrainConsentError",
+    "MonitorSession",
+    "TelemetrySample",
+    "render_certificate",
+    "map_nvml",
+    "map_dcgm",
+    "map_redfish",
+    "normalize_xid",
+    "verify_attestation",
+    "AttestationReport",
+    "AttestationOutcome",
+    "FixtureSource",
+    "RawCapture",
+    "RawSource",
+]

voltry_probe/attestation/__init__.py

@@ -0,0 +1,14 @@
+"""Attestation: real cryptographic verification of the device identity chain.
+
+The verdict reflects the **real** chain state and is never stubbed as PASS (crypto-standards
+skill, §security). ``UNVERIFIED`` when the root/PKI is unreachable; ``FAILED`` on a broken
+chain or measurement; ``FALLBACK`` (lower confidence, marked) for parts without a hardware
+root; ``VERIFIED`` only when the full chain checks out.
+"""
+
+from __future__ import annotations
+
+from .model import AttestationReport
+from .verify import AttestationOutcome, verify_attestation
+
+__all__ = ["AttestationReport", "AttestationOutcome", "verify_attestation"]

voltry_probe/attestation/model.py

@@ -0,0 +1,33 @@
+"""The attestation report payload.
+
+A deliberately small but faithful model of the NVIDIA Device Identity (over SPDM) chain:
+a device identity key whose binding is signed by the NVIDIA root, plus a freshness-bound
+measurement (VBIOS hash + nonce) signed by the device key. Verification (``verify.py``)
+checks both signatures and the VBIOS hash — the same structure as the real chain
+(root → device cert → signed measurement), without re-implementing X.509/SPDM transport.
+"""
+
+from __future__ import annotations
+
+from evidence_schema import IdentityScheme
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class AttestationReport(BaseModel):
+    """Verbatim attestation report to be verified (never trusted blindly)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    scheme: IdentityScheme = Field(description="HARDWARE_ROOT or SECONDARY_FALLBACK.")
+    device_id: str = Field(description="Device identity id (the permanent ECC-384 id).")
+    device_public_key_b64: str = Field(
+        description="Device identity public key (SPKI DER, base64), P-384."
+    )
+    root_signature_b64: str = Field(
+        description="Root CA signature over the canonical (device_id, device_public_key) binding."
+    )
+    vbios_hash: str = Field(description="VBIOS measurement hash attested by this report.")
+    nonce: str = Field(description="Freshness nonce bound into the measurement signature.")
+    measurement_signature_b64: str = Field(
+        description="Device-key signature over the canonical (nonce, vbios_hash) measurement."
+    )

voltry_probe/attestation/verify.py

@@ -0,0 +1,190 @@
+"""Verify an attestation report against a trusted root — real ECDSA P-384 checks.
+
+Outcome rules (never a stubbed PASS):
+- no report                     → UNVERIFIED (authenticity NOT_ASSESSED)
+- no trusted root provided      → UNVERIFIED (chain unevaluable; authenticity NOT_ASSESSED)
+- root signature invalid        → FAILED     (authenticity FAIL — disqualifying)
+- measurement signature invalid → FAILED     (authenticity FAIL — disqualifying)
+- VBIOS hash != expected        → reflash_detected=True, firmware FAIL (disqualifying)
+- all checks pass, HARDWARE_ROOT→ VERIFIED   (authenticity PASS, high confidence)
+- all checks pass, FALLBACK     → FALLBACK    (authenticity PASS, lower confidence, marked)
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+
+import rfc8785
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+from evidence_schema import (
+    Attestation,
+    AttestationVerdict,
+    GateResult,
+    IdentityScheme,
+)
+from evidence_schema.sign import load_public_key_spki_b64
+from evidence_schema.types import UtcDateTime, utcnow
+from pydantic import BaseModel, ConfigDict
+
+from .model import AttestationReport
+
+_HASH = hashes.SHA384
+# Confidence levels by outcome (documented, not magic): a hardware-rooted verified chain
+# is near-certain; a secondary fallback is materially lower and explicitly marked.
+_CONFIDENCE_VERIFIED = 0.99
+_CONFIDENCE_FALLBACK = 0.60
+_CONFIDENCE_UNVERIFIED = 0.0
+_CONFIDENCE_FAILED = 0.0
+
+
+class AttestationOutcome(BaseModel):
+    """The verified result: the certificate's Attestation block + derived gate inputs."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    attestation: Attestation
+    reflash_detected: bool
+    authenticity_confidence: float
+    identity_scheme: IdentityScheme
+    vbios_hash: str | None
+    authenticity_gate: GateResult
+    firmware_gate: GateResult
+
+
+def _root_statement_bytes(report: AttestationReport) -> bytes:
+    return rfc8785.dumps(
+        {"device_id": report.device_id, "device_public_key_b64": report.device_public_key_b64}
+    )
+
+
+def _measurement_bytes(report: AttestationReport) -> bytes:
+    return rfc8785.dumps({"nonce": report.nonce, "vbios_hash": report.vbios_hash})
+
+
+def _ecdsa_ok(public_key: ec.EllipticCurvePublicKey, signature_b64: str, payload: bytes) -> bool:
+    try:
+        public_key.verify(
+            base64.b64decode(signature_b64, validate=True), payload, ec.ECDSA(_HASH())
+        )
+        return True
+    except (InvalidSignature, ValueError, binascii.Error):
+        return False
+
+
+def _unverified(
+    scheme: IdentityScheme,
+    detail: str,
+    *,
+    root_reachability: bool,
+    measured_at: UtcDateTime | None,
+) -> AttestationOutcome:
+    return AttestationOutcome(
+        attestation=Attestation(
+            scheme=scheme,
+            verdict=AttestationVerdict.UNVERIFIED,
+            root_reachability=root_reachability,
+            detail=detail,
+            measured_at=measured_at,
+        ),
+        reflash_detected=False,
+        authenticity_confidence=_CONFIDENCE_UNVERIFIED,
+        identity_scheme=scheme,
+        vbios_hash=None,
+        authenticity_gate=GateResult.NOT_ASSESSED,
+        firmware_gate=GateResult.NOT_ASSESSED,
+    )
+
+
+def verify_attestation(
+    report: AttestationReport | None,
+    *,
+    trusted_root_public_key: ec.EllipticCurvePublicKey | None = None,
+    expected_vbios_hash: str | None = None,
+    measured_at: UtcDateTime | None = None,
+) -> AttestationOutcome:
+    """Verify ``report`` against ``trusted_root_public_key`` and return the real outcome."""
+    when = measured_at if measured_at is not None else utcnow()
+
+    if report is None:
+        return _unverified(
+            IdentityScheme.SECONDARY_FALLBACK,
+            "No attestation report available.",
+            root_reachability=False,
+            measured_at=when,
+        )
+    if trusted_root_public_key is None:
+        return _unverified(
+            report.scheme,
+            "Trusted root unreachable; attestation chain not evaluated.",
+            root_reachability=False,
+            measured_at=when,
+        )
+
+    # 1) Chain: the root must have signed the device-key binding.
+    root_ok = _ecdsa_ok(
+        trusted_root_public_key, report.root_signature_b64, _root_statement_bytes(report)
+    )
+    # 2) Measurement: the device key must have signed (nonce, vbios_hash).
+    measurement_ok = False
+    if root_ok:
+        try:
+            device_key = load_public_key_spki_b64(report.device_public_key_b64)
+            measurement_ok = _ecdsa_ok(
+                device_key, report.measurement_signature_b64, _measurement_bytes(report)
+            )
+        except (ValueError, binascii.Error):
+            measurement_ok = False
+
+    if not (root_ok and measurement_ok):
+        detail = "Root signature invalid." if not root_ok else "Measurement signature invalid."
+        return AttestationOutcome(
+            attestation=Attestation(
+                scheme=report.scheme,
+                verdict=AttestationVerdict.FAILED,
+                root_reachability=True,
+                detail=detail,
+                measured_at=when,
+            ),
+            reflash_detected=False,
+            authenticity_confidence=_CONFIDENCE_FAILED,
+            identity_scheme=report.scheme,
+            vbios_hash=report.vbios_hash,
+            authenticity_gate=GateResult.FAIL,
+            firmware_gate=GateResult.NOT_ASSESSED,
+        )
+
+    # 3) Re-flash detection: compare attested VBIOS hash to the known-good expectation.
+    reflash = expected_vbios_hash is not None and report.vbios_hash != expected_vbios_hash
+    firmware_gate = (
+        GateResult.FAIL
+        if reflash
+        else (GateResult.PASS if expected_vbios_hash is not None else GateResult.NOT_ASSESSED)
+    )
+
+    if report.scheme is IdentityScheme.HARDWARE_ROOT:
+        verdict, confidence = AttestationVerdict.VERIFIED, _CONFIDENCE_VERIFIED
+        detail = "Device Identity chain verified; measurement signature valid."
+    else:
+        verdict, confidence = AttestationVerdict.FALLBACK, _CONFIDENCE_FALLBACK
+        detail = "Secondary (no hardware root) scheme verified at lower confidence."
+
+    return AttestationOutcome(
+        attestation=Attestation(
+            scheme=report.scheme,
+            verdict=verdict,
+            root_reachability=True,
+            detail=detail + (" VBIOS re-flash detected." if reflash else ""),
+            measured_at=when,
+        ),
+        reflash_detected=reflash,
+        authenticity_confidence=confidence,
+        identity_scheme=report.scheme,
+        vbios_hash=report.vbios_hash,
+        # A verified-genuine chain passes authenticity even on the marked fallback scheme;
+        # a detected re-flash fails the firmware gate (disqualifying) but the part is still genuine.
+        authenticity_gate=GateResult.PASS,
+        firmware_gate=firmware_gate,
+    )

voltry_probe/cli.py

@@ -0,0 +1,214 @@
+"""``voltry`` — the probe CLI.
+
+Three commands:
+- ``voltry scan``   read-only capture → signed evidence bundle (works fully OFFLINE).
+- ``voltry cert``   bundle → self-contained offline HTML certificate (works OFFLINE).
+- ``voltry submit`` upload a signed bundle to the platform — **opt-in and separate**: it
+  is the only networked command, requires an explicit consent flag, and its HTTP client
+  is an optional dependency so scan/cert stay offline and dependency-light (§1.7).
+
+No PII is collected: identity is device-level only; account linkage is server-side (NGC
+GDPR posture).
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+from pathlib import Path
+
+import typer
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from evidence_schema import AgentInfo, EvidenceBundle, RunMode, generate_keypair, verify_bundle
+
+from . import __version__
+from .evidence import build_read_bundle
+from .render import render_certificate
+from .sources import FixtureSource
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="Voltry Probe — read-only GPU condition & provenance (scan/cert offline; submit opt-in).",
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"voltry-probe {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """Voltry Probe — read-only GPU condition & provenance."""
+
+
+def _load_signing_key(signing_key: Path | None, ephemeral: bool) -> ec.EllipticCurvePrivateKey:
+    """Load the operator signing key from PEM, or generate an ephemeral one if opted in."""
+    if signing_key is not None:
+        key = serialization.load_pem_private_key(signing_key.read_bytes(), password=None)
+        if not isinstance(key, ec.EllipticCurvePrivateKey):
+            raise typer.BadParameter("signing key must be an EC (P-384) private key")
+        return key
+    if ephemeral:
+        typer.echo(
+            "WARNING: using an ephemeral signing key — not a persistent operator identity; "
+            "for production pass --signing-key.",
+            err=True,
+        )
+        return generate_keypair()
+    raise typer.BadParameter("provide --signing-key PATH (PEM) or pass --ephemeral-key")
+
+
+def _load_root_pubkey(path: Path | None) -> ec.EllipticCurvePublicKey | None:
+    if path is None:
+        return None
+    key = serialization.load_pem_public_key(path.read_bytes())
+    if not isinstance(key, ec.EllipticCurvePublicKey):
+        raise typer.BadParameter("trusted root must be an EC public key")
+    return key
+
+
+@app.command()
+def scan(
+    fixture: Path = typer.Option(
+        None, help="Captured RawCapture JSON (dev/sim). Omit to read live hardware."
+    ),
+    out: Path = typer.Option(
+        None, "--out", "-o", help="Write the signed bundle JSON here (default: stdout)."
+    ),
+    methodology: str = typer.Option(
+        "read-v0", help="Methodology version hash stamped into the bundle."
+    ),
+    signing_key: Path = typer.Option(
+        None, help="Operator EC P-384 private key (PEM) to sign the bundle."
+    ),
+    ephemeral_key: bool = typer.Option(
+        False, "--ephemeral-key", help="Sign with a throwaway key (dev only)."
+    ),
+    trusted_root: Path = typer.Option(
+        None, help="NVIDIA root EC public key (PEM) for attestation."
+    ),
+    expected_vbios: str = typer.Option(None, help="Known-good VBIOS hash for re-flash detection."),
+) -> None:
+    """Read the device (read-only) and emit a signed evidence bundle. Offline."""
+    key = _load_signing_key(signing_key, ephemeral_key)
+    root_pub = _load_root_pubkey(trusted_root)
+    if fixture is not None:
+        source = FixtureSource(fixture)
+    else:  # pragma: no cover - requires a GPU + the [hardware] extra
+        from .sources.live import LiveSource
+
+        source = LiveSource()
+    capture = source.capture()
+    bundle = build_read_bundle(
+        capture,
+        signer_key=key,
+        agent=AgentInfo(
+            name="voltry-probe",
+            version=__version__,
+            run_mode=RunMode.READ,
+            host_arch=platform.machine(),
+        ),
+        methodology_version_hash=methodology,
+        trusted_root_public_key=root_pub,
+        expected_vbios_hash=expected_vbios,
+        signer_label="operator",
+    )
+    payload = bundle.model_dump_json(indent=2)
+    if out is None:
+        sys.stdout.write(payload + "\n")
+    else:
+        out.write_text(payload, encoding="utf-8")
+        typer.echo(f"wrote signed bundle: {out}", err=True)
+
+
+@app.command()
+def cert(
+    bundle: Path = typer.Argument(..., help="A signed evidence bundle JSON (from `voltry scan`)."),
+    out: Path = typer.Option(
+        None, "--out", "-o", help="Write the HTML certificate here (default: stdout)."
+    ),
+) -> None:
+    """Render a bundle to a self-contained, offline HTML certificate. Offline."""
+    try:
+        text = bundle.read_text(encoding="utf-8")
+    except OSError as exc:
+        typer.echo(f"ERROR: bundle file not found: {bundle}", err=True)
+        raise typer.Exit(2) from exc
+    try:
+        model = EvidenceBundle.model_validate_json(text)
+    except ValueError as exc:
+        typer.echo(f"ERROR: not a valid evidence bundle ({bundle}): {exc}", err=True)
+        raise typer.Exit(2) from exc
+    # A certificate is authoritative only if the signature actually verifies. Render an
+    # unverified bundle with a prominent watermark rather than refusing outright, but never
+    # let it look like proof (security §trust).
+    verified = model.signature is not None and verify_bundle(model)
+    if not verified:
+        typer.echo(
+            "WARNING: bundle signature is UNVERIFIED — the certificate is a rendered view, "
+            "not cryptographic proof.",
+            err=True,
+        )
+    html = render_certificate(model, verified=verified)
+    if out is None:
+        sys.stdout.write(html + "\n")
+    else:
+        out.write_text(html, encoding="utf-8")
+        typer.echo(f"wrote certificate: {out}", err=True)
+
+
+@app.command()
+def submit(
+    bundle: Path = typer.Argument(..., help="A signed evidence bundle JSON to upload."),
+    url: str = typer.Option(..., help="Platform ingest URL."),
+    i_consent_to_submit: bool = typer.Option(
+        False,
+        "--i-consent-to-submit",
+        help="Required. Uploading the signed bundle (including raw reads) leaves your premises.",
+    ),
+) -> None:
+    """Upload a signed bundle to the platform. OPT-IN and SEPARATE from scan/cert (§1.7)."""
+    if not i_consent_to_submit:
+        typer.echo(
+            "ERROR: submission is opt-in and separate from scan/cert. Nothing leaves your "
+            "premises without consent. Re-run with --i-consent-to-submit to upload the signed "
+            "bundle (which includes its raw reads) to the platform.",
+            err=True,
+        )
+        raise typer.Exit(2)
+    try:
+        import httpx
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        typer.echo(
+            "submit requires the network extra: pip install 'voltry-probe[submit]'", err=True
+        )
+        raise typer.Exit(3) from exc
+    data = bundle.read_text(encoding="utf-8")
+    response = httpx.post(  # pragma: no cover
+        url,
+        content=data,
+        headers={"content-type": "application/json"},
+        timeout=30.0,  # bound the consent-gated upload; never hang on a slow endpoint
+    )
+    typer.echo(f"submitted to {url}: HTTP {response.status_code}")  # pragma: no cover
+
+
+def main() -> None:
+    """Console-script entry point (`voltry`)."""
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover - module run
+    main()

voltry_probe/evidence/__init__.py

@@ -0,0 +1,11 @@
+"""Thin adapter over evidence-schema — assembles reader outputs into a signed bundle.
+
+This never re-implements the contract; it imports the frozen models + signing from
+evidence-schema and only orchestrates assembly.
+"""
+
+from __future__ import annotations
+
+from .builder import build_functional_bundle, build_monitor_bundle, build_read_bundle
+
+__all__ = ["build_read_bundle", "build_functional_bundle", "build_monitor_bundle"]

voltry_probe/evidence/builder.py

@@ -0,0 +1,165 @@
+"""Assemble a Read-mode :class:`EvidenceBundle` from a capture, then sign it."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from cryptography.hazmat.primitives.asymmetric import ec
+from evidence_schema import (
+    AgentInfo,
+    DeterministicGates,
+    EvidenceBundle,
+    FunctionalBlock,
+    GateResult,
+    History,
+    IdentityBlock,
+    MeasuredBlock,
+    ProvenanceBlock,
+    RawPayload,
+    RawReads,
+    Tier,
+    sign_bundle,
+)
+from evidence_schema.types import UtcDateTime, utcnow
+
+from ..attestation import AttestationReport, verify_attestation
+from ..readers import map_dcgm, map_nvml, map_redfish
+from ..sources.base import RawCapture
+
+
+def _raw_payload(source: str, key: str, payload: object, captured_at: UtcDateTime) -> RawPayload:
+    """Wrap a verbatim source payload as a RawPayload with an integrity hash."""
+    content = json.dumps(payload, sort_keys=True, ensure_ascii=False)  # not the signing path
+    return RawPayload(
+        source=source,
+        key=key,
+        format="json",
+        content=content,
+        sha256=hashlib.sha256(content.encode("utf-8")).hexdigest(),
+        captured_at=captured_at,
+    )
+
+
+def build_read_bundle(
+    capture: RawCapture,
+    *,
+    signer_key: ec.EllipticCurvePrivateKey,
+    agent: AgentInfo,
+    methodology_version_hash: str,
+    trusted_root_public_key: ec.EllipticCurvePublicKey | None = None,
+    expected_vbios_hash: str | None = None,
+    signer_label: str | None = "operator",
+    created_at: UtcDateTime | None = None,
+    functional: FunctionalBlock | None = None,
+    tier: Tier = Tier.BRONZE,
+    history: History = History.RECONSTRUCTED,
+    born_on: UtcDateTime | None = None,
+) -> EvidenceBundle:
+    """Map a capture into a schema-valid, signed bundle.
+
+    Read mode (defaults) ⇒ Bronze, reconstructed history. Functional mode passes a
+    ``functional`` block (the functional gates derive from it) with ``tier=SILVER``;
+    Monitor mode passes ``tier=GOLD``, ``history=BORN_ON`` and a ``born_on`` timestamp.
+    Attestation is verified for real (never stubbed) regardless of mode.
+    """
+    when = created_at if created_at is not None else utcnow()
+
+    nvml_out = map_nvml(capture.nvml)
+    dcgm_out = map_dcgm(capture.dcgm)
+    redfish_out = map_redfish(capture.redfish)
+
+    report = AttestationReport.model_validate(capture.attestation) if capture.attestation else None
+    att = verify_attestation(
+        report,
+        trusted_root_public_key=trusted_root_public_key,
+        expected_vbios_hash=expected_vbios_hash,
+        measured_at=capture.captured_at,
+    )
+
+    ecc384_id = (report.device_id if report else None) or nvml_out.gpu_uuid or "UNKNOWN-IDENTITY"
+
+    identity = IdentityBlock(
+        device_part=nvml_out.device_part or nvml_out.device_model or "UNKNOWN",
+        device_model=nvml_out.device_model,
+        serial=nvml_out.serial or "UNKNOWN",
+        ecc384_id=ecc384_id,
+        gpu_uuid=nvml_out.gpu_uuid,
+        board_id=redfish_out.board_id,
+        attestation=att.attestation,
+        vbios_version=nvml_out.vbios_version,
+        vbios_hash=att.vbios_hash,
+        reflash_detected=att.reflash_detected,
+        identity_scheme=att.identity_scheme,
+        authenticity_confidence=att.authenticity_confidence,
+        gates=DeterministicGates(
+            authenticity=att.authenticity_gate,
+            firmware_vbios=att.firmware_gate,
+            # Functional gates derive from the functional block (functional mode); else
+            # NOT_ASSESSED (Read/Monitor mode is non-disruptive).
+            functional_burnin=functional.burnin_result if functional else GateResult.NOT_ASSESSED,
+            sdc_functional=functional.sdc_functional if functional else GateResult.NOT_ASSESSED,
+            data_sanitization=(
+                functional.sanitization.result if functional else GateResult.NOT_ASSESSED
+            ),
+        ),
+    )
+
+    measured = MeasuredBlock(
+        ecc=nvml_out.ecc,
+        xid=nvml_out.xid,
+        pages=nvml_out.pages,
+        spare_rows=nvml_out.spare_rows,
+        stability=nvml_out.stability,
+        thermals=nvml_out.thermals,
+        clock_power=nvml_out.clock_power,
+        nvlink=dcgm_out.nvlink,
+        pcie=dcgm_out.pcie,
+    )
+
+    payloads = [_raw_payload("nvml", "readout", capture.nvml, capture.captured_at)]
+    if capture.dcgm is not None:
+        payloads.append(_raw_payload("dcgm", "telemetry", capture.dcgm, capture.captured_at))
+    if capture.redfish is not None:
+        payloads.append(_raw_payload("redfish", "system", capture.redfish, capture.captured_at))
+    if capture.attestation is not None:
+        payloads.append(
+            _raw_payload("attestation", "report", capture.attestation, capture.captured_at)
+        )
+
+    bundle = EvidenceBundle(
+        created_at=when,
+        agent=agent,
+        methodology_version_hash=methodology_version_hash,
+        calibration_snapshot_id=None,  # Phase 0: no modeled fields.
+        identity=identity,
+        measured=measured,
+        functional=functional,
+        raw_reads=RawReads(payloads=payloads),
+        environment=None,  # No facility instrumentation ⇒ exposure Not Assessed.
+        provenance=ProvenanceBlock(
+            tier=tier,
+            history=history,
+            # Born-on (Monitor) implies a continuous chain; reconstructed implies gaps.
+            chain_gaps=history is not History.BORN_ON,
+            exposure_assessed=False,
+            born_on=born_on,
+        ),
+    )
+    return sign_bundle(bundle, signer_key, signer=signer_label)
+
+
+def build_functional_bundle(
+    capture: RawCapture, *, functional: FunctionalBlock, **kwargs: object
+) -> EvidenceBundle:
+    """Functional mode (Silver): a bundle carrying the drained-unit functional results."""
+    return build_read_bundle(capture, functional=functional, tier=Tier.SILVER, **kwargs)  # type: ignore[arg-type]
+
+
+def build_monitor_bundle(
+    capture: RawCapture, *, born_on: UtcDateTime, **kwargs: object
+) -> EvidenceBundle:
+    """Monitor mode (Gold): a born-on bundle from continuous read-only capture."""
+    return build_read_bundle(
+        capture, tier=Tier.GOLD, history=History.BORN_ON, born_on=born_on, **kwargs  # type: ignore[arg-type]
+    )

voltry_probe/functional/__init__.py

@@ -0,0 +1,13 @@
+"""Functional mode (Silver) — the ONLY package where device-mutating calls may live.
+
+DCGM r4 diagnostics + burn-in + the SDC functional test stress and drain the GPU, so they
+run exclusively here and only behind an explicit drain-consent flag. Everything outside
+``voltry_probe/functional/`` is read-only (invariant §1.1), enforced by the read-only
+invariant test (which excludes this package) and the forbidden-patterns hook.
+"""
+
+from __future__ import annotations
+
+from .runner import DrainConsentError, FunctionalRunner
+
+__all__ = ["FunctionalRunner", "DrainConsentError"]