szl-kernels 0.2.0__py3-none-any.whl

szl_kernels/__init__.py

@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 SZL Holdings · Stephen P. Lutar · ORCID 0009-0001-0110-4173
+"""szl_kernels — SZL Holdings' unified governed-kernel SUITE.
+
+ONE get_kernel-discoverable package that ties the three governed kernels plus
+the energy meter into a single suite with a SHARED, op-agnostic
+``UnifiedReceiptChain`` — cross-kernel provenance in one auditable forward pass.
+This is the gap the Kernel Hub leaders leave open: they optimize FLOPs per op;
+SZL governs provenance ACROSS ops.
+
+Suite members (each independently published as its own Hub kernel):
+  * governed_norm  -> SZLHOLDINGS/szl-governed-norm   (RMSNorm/LayerNorm + receipts)
+  * lambda_gate    -> SZLHOLDINGS/szl-lambda-gate     (advisory Λ gate; Conjecture 1)
+  * energy_core    -> szl_energy_core / governed-inference-meter (MEASURED joules)
+  * govsign        -> SZLHOLDINGS/szl-govsign         (signed governance attestation; DSSE / in-toto)
+  * blocked        -> SZLHOLDINGS/szl-blocked         (honest-BLOCKED first-class state + EU AI Act Annex IV)
+  * provctl        -> SZLHOLDINGS/szl-provctl         (provenance-DAG verify + in-toto v1 / SLSA v1 interop + per-kernel MEASURED energy)
+
+The first three are the NUMERIC core exercised by the shared forward pass.
+govsign + blocked are GOVERNANCE-LAYER series companions: govsign makes a
+verdict third-party-verifiable (sign/verify offline), and blocked makes a
+refusal a first-class, provenanced state (the op never runs — no fake-green)
+and derives an EU AI Act Annex IV DRAFT skeleton from the same chain.
+
+Companion table (NOT a numeric kernel, NOT a transformer LM, NOT Chaski/Khipu):
+  * MiniEmbed      -> SZL-MiniEmbed v1 (PPMI+TruncatedSVD word-embedding table)
+
+Discover + use the suite:
+
+    from kernels import get_kernel
+    suite = get_kernel("SZLHOLDINGS/szl-kernels", version=1, trust_remote_code=True)
+    print(suite.list_kernels())            # {'governed_norm':..., 'lambda_gate':..., 'energy_core':...}
+    print(suite.list_series())             # {'govsign':..., 'blocked':..., 'provctl':...}
+    print(suite.selfcheck())               # one-shot suite health (CPU only)
+
+    # ONE shared chain spanning multiple ops:
+    chain = suite.UnifiedReceiptChain()
+    import torch
+    x = torch.randn(4, 64)
+    y = suite.governed_rms_norm(chain, x, eps=1e-6)
+    gate = suite.governed_lambda_gate(chain, torch.tensor([0.9, 0.8, 0.95]), threshold=0.5)
+    e = suite.governed_measure_energy(chain)   # None joules when no NVML — never faked
+    ok, depth, brk = chain.verify()            # the WHOLE pass verifies as one chain
+    print(chain.kernels_touched())             # ['governed_norm','lambda_gate','energy_core']
+
+    # Flagship composition — a governed transformer sub-block:
+    blk = suite.GovernedBlock()
+    res = blk.forward(x, gov_axes=torch.tensor([0.95, 0.9, 0.92]))
+    print(res["chain_ok"], res["chain_depth"], res["kernels_touched"])
+
+HONESTY (SZL doctrine v11):
+  * Λ is the weighted-geometric-mean ADVISORY aggregator; its uniqueness is
+    Conjecture 1 (OPEN). A recorded gate "pass" is advisory, NEVER proven trust.
+  * Energy joules are MEASURED-only (real NVML delta). No GPU/NVML => None /
+    UNAVAILABLE_NO_NVML, NEVER a fabricated joule.
+  * Receipt digests are SHA3-256 integrity fingerprints — tamper-evidence +
+    ordering, NOT signatures and NOT proof of authorship.
+  * This is a UNIVERSAL (pure-Python) suite: a correctness + provenance
+    reference, not a hand-tuned CUDA speed record. No fabricated benchmarks.
+"""
+from typing import Any, Dict
+
+import torch
+
+from ._chain import GENESIS, UnifiedReceiptChain, tensor_digest
+from ._ops import (
+    GovernedBlock,
+    governed_layer_norm,
+    governed_lambda_gate,
+    governed_measure_energy,
+    governed_rms_norm,
+)
+from .miniembed import MiniEmbed, PUBLISHED_SHA256
+from .retrieval import governed_cosine_topk
+from .estate import (
+    ESTATE,
+    cuda_status,
+    get_estate_member,
+    list_estate,
+    probe_estate,
+    probe_member,
+)
+
+__all__ = [
+    "UnifiedReceiptChain",
+    "tensor_digest",
+    "GENESIS",
+    "governed_rms_norm",
+    "governed_cosine_topk",
+    "governed_layer_norm",
+    "governed_lambda_gate",
+    "governed_measure_energy",
+    "GovernedBlock",
+    "MiniEmbed",
+    "PUBLISHED_SHA256",
+    "list_kernels",
+    "list_series",
+    "get_member",
+    "selfcheck",
+    "ESTATE",
+    "list_estate",
+    "probe_estate",
+    "probe_member",
+    "get_estate_member",
+    "cuda_status",
+    "DOCTRINE_FOOTER",
+    "PROVENANCE",
+    "__version__",
+]
+
+__version__ = "0.2.0"
+
+DOCTRINE_FOOTER = (
+    "SZL Holdings · unified governed-kernel suite · cross-kernel provenance · "
+    "Λ = Conjecture 1 (advisory) · energy MEASURED-only · honesty over checklist"
+)
+
+# Suite registry: maps a suite-member key to its Hub coordinates + role. In
+# production, get_member() would resolve these via kernels.get_kernel(); the
+# reference package ships byte-faithful numerics so it runs standalone.
+_REGISTRY: Dict[str, Dict[str, str]] = {
+    "governed_norm": {
+        "hub_id": "SZLHOLDINGS/szl-governed-norm",
+        "role": "RMSNorm/LayerNorm + SHA3-256 hash-chained receipts",
+        "honesty": "integrity fingerprint, not a signature",
+    },
+    "lambda_gate": {
+        "hub_id": "SZLHOLDINGS/szl-lambda-gate",
+        "role": "advisory Λ weighted-geometric-mean gate",
+        "honesty": "Λ uniqueness = Conjecture 1 (open); advisory, NOT proven trust",
+    },
+    "energy_core": {
+        "hub_id": "SZLHOLDINGS/governed-inference-meter",
+        "role": "MEASURED-joule energy accounting (real NVML delta)",
+        "honesty": "no GPU/NVML => UNAVAILABLE_NO_NVML, joules None — never fabricated",
+    },
+}
+
+# Governance-layer series companions (not part of the numeric forward pass).
+# Each is independently published and operates on the SAME UnifiedReceiptChain
+# provenance, extending the suite from "govern provenance ACROSS ops" to
+# "sign that provenance" and "refuse-and-record honestly."
+_SERIES: Dict[str, Dict[str, str]] = {
+    "govsign": {
+        "hub_id": "SZLHOLDINGS/szl-govsign",
+        "role": "signed governance attestation (DSSE / in-toto, ECDSA P-256)",
+        "honesty": "signature proves authorship+integrity, NOT Λ uniqueness; proven_trust locked False; a BLOCKED verdict is signed as BLOCKED",
+    },
+    "blocked": {
+        "hub_id": "SZLHOLDINGS/szl-blocked",
+        "role": "honest-BLOCKED first-class state + EU AI Act Annex IV DRAFT derivation",
+        "honesty": "a BLOCKED op never executes (no fake-green); Annex IV output is a DRAFT skeleton, NOT legal advice",
+    },
+    "provctl": {
+        "hub_id": "SZLHOLDINGS/szl-provctl",
+        "role": "provenance-DAG verify + in-toto v1 / SLSA v1 interop + per-kernel MEASURED energy",
+        "honesty": "in-toto/SLSA field names spec-exact; proven_trust locked False; energy MEASURED-only (never fabricated); honest-BLOCKED DAG nodes surfaced, never dropped",
+    },
+}
+
+PROVENANCE = {
+    "suite": "szl_kernels",
+    "members": _REGISTRY,
+    "series_companions": _SERIES,
+    "miniembed": {
+        "kind": "distributional_word_embedding_table",
+        "not": ["transformer_lm", "chaski", "khipu"],
+        "files": {"vectors": "vectors.npz", "vocab": "vocab.json"},
+        "method": "PPMI+TruncatedSVD",
+        "receipt_chain": "UnifiedReceiptChain",
+    },
+    "lean_repo": "szl-holdings/lutar-lean",
+    "doi_lutar_lean": "10.5281/zenodo.20434308",
+    "lambda_status": "Conjecture 1 (open) — uniqueness unproven; advisory only",
+    "shared_chain": "UnifiedReceiptChain — op-agnostic SHA3-256 cross-kernel provenance",
+}
+
+
+def list_kernels() -> Dict[str, Dict[str, str]]:
+    """Return the suite registry: member key -> {hub_id, role, honesty}."""
+    return {k: dict(v) for k, v in _REGISTRY.items()}
+
+
+def list_series() -> Dict[str, Dict[str, str]]:
+    """Return the governance-layer series companions (govsign, blocked, provctl).
+
+    These extend the numeric suite with signed attestation (govsign),
+    honest-BLOCKED + EU AI Act Annex IV derivation (blocked), and provenance-DAG
+    verification + in-toto/SLSA interop + per-kernel MEASURED energy (provctl).
+    They operate on the same UnifiedReceiptChain but are not part of the numeric
+    forward pass.
+    """
+    return {k: dict(v) for k, v in _SERIES.items()}
+
+
+def get_member(key: str) -> Dict[str, str]:
+    """Resolve one suite member's Hub coordinates + honest role string."""
+    if key not in _REGISTRY:
+        raise KeyError(f"unknown suite member {key!r}; have {list(_REGISTRY)}")
+    return dict(_REGISTRY[key])
+
+
+def selfcheck() -> Dict[str, Any]:
+    """One-shot CPU-only suite health check; never raises.
+
+    Proves the suite's CENTRAL claim end-to-end: a single shared chain spans
+    governed_norm + lambda_gate + energy_core in ONE forward pass, verifies as
+    one tamper-evident sequence, AND a deliberately mutated copy fails
+    verification (so the tamper-evidence is real, not decorative).
+
+    Returns {ok, version, checks:{...}, chain_head, kernels_touched,
+             tamper_detected, error}.
+    """
+    checks: Dict[str, bool] = {}
+    error = None
+    chain_head = GENESIS
+    kernels_touched = []
+    tamper_detected = False
+    try:
+        torch.manual_seed(0)
+        x = torch.randn(4, 64, dtype=torch.float32)
+        w = torch.randn(64, dtype=torch.float32)
+
+        chain = UnifiedReceiptChain()
+
+        # norm matches a fp32 RMSNorm reference
+        y = governed_rms_norm(chain, x, weight=w, eps=1e-6)
+        ref = (x * torch.rsqrt(x.pow(2).mean(-1, keepdim=True) + 1e-6)) * w
+        checks["norm_correct"] = bool(torch.allclose(y, ref, rtol=1e-5, atol=1e-5))
+
+        # advisory Λ gate runs and is recorded as advisory
+        gate = governed_lambda_gate(
+            chain, torch.tensor([0.9, 0.8, 0.95]), threshold=0.5
+        )
+        checks["lambda_advisory"] = bool(gate["advisory"] is True)
+
+        # energy is MEASURED-only: no NVML here => joules None, honest label
+        e = governed_measure_energy(chain)
+        checks["energy_honest"] = bool(
+            e["joules"] is None and e["label"] == "UNAVAILABLE_NO_NVML"
+        )
+
+        # the WHOLE multi-op pass verifies as ONE chain
+        ok, depth, brk = chain.verify()
+        checks["cross_kernel_verify"] = bool(ok and depth == 3 and brk == -1)
+        chain_head = chain.head()
+        kernels_touched = chain.kernels_touched()
+        checks["spans_three_kernels"] = bool(
+            kernels_touched == ["governed_norm", "lambda_gate", "energy_core"]
+        )
+
+        # offline re-verification of the exported chain
+        ok2, _, _ = UnifiedReceiptChain.verify_json(chain.to_json())
+        checks["offline_reverify"] = bool(ok2)
+
+        # tamper-evidence is REAL: mutate one recorded attr and confirm break
+        blob = chain.to_json()
+        import json as _json
+        recs = _json.loads(blob)
+        recs[0]["attrs"]["eps"] = 9.99e-3  # flip a recorded value
+        ok3, _, brk3 = UnifiedReceiptChain.verify_json(_json.dumps(recs))
+        tamper_detected = bool((not ok3) and brk3 == 0)
+        checks["tamper_detected"] = tamper_detected
+
+        # GovernedBlock composition runs and self-verifies
+        blk = GovernedBlock()
+        res = blk.forward(x, weight=w, gov_axes=torch.tensor([0.95, 0.9, 0.92]))
+        checks["block_forward"] = bool(
+            res["chain_ok"]
+            and res["chain_depth"] == 4
+            and res["kernels_touched"]
+            == ["governed_norm", "lambda_gate", "energy_core", "governed_block"]
+        )
+    except Exception as exc:  # never raise from a health probe
+        error = f"{type(exc).__name__}: {exc}"
+
+    ok = bool(checks) and all(checks.values()) and error is None
+    return {
+        "ok": ok,
+        "version": __version__,
+        "checks": checks,
+        "chain_head": chain_head,
+        "kernels_touched": kernels_touched,
+        "tamper_detected": tamper_detected,
+        "error": error,
+    }

szl_kernels/_chain.py

@@ -0,0 +1,372 @@
+# SPDX-License-Identifier: Apache-2.0
+# © 2026 SZL Holdings · Stephen P. Lutar · ORCID 0009-0001-0110-4173
+"""SHA3-256 linked receipts shared by SZL kernel operations.
+
+Unanchored verification checks internal consistency, not complete history,
+authorship or execution. An independently retained head/depth checkpoint can
+bind the expected extent and recorded contents. The caller must authenticate
+that checkpoint separately and bind it to the relevant run/source/policy.
+
+Receipts preserve the legacy hashed fields and digest encoding. Timestamps
+remain outside the hashed body; finite timestamps are not authenticated time.
+Tensor fingerprints retain the existing rounded-float32 encoding; equal
+fingerprints are not evidence that the original tensor bytes were equal.
+
+Public methods return detached snapshots. This prevents ordinary aliasing from
+mutating stored records, but is not protection against a hostile Python process.
+No network, persistent storage, signing, training or publication is performed.
+"""
+from __future__ import annotations
+
+import copy
+import hashlib
+import hmac
+import json
+import math
+import re
+import struct
+import threading
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+try:  # torch is optional at import time so the chain stays inspectable headless
+    import torch  # noqa: F401
+    _HAS_TORCH = True
+except Exception:  # pragma: no cover - exercised only in torch-less envs
+    _HAS_TORCH = False
+
+# Genesis link: 64 hex zeros, identical to szl_governed_norm and szl_energy_core
+# so the unified chain's genesis is byte-compatible with the per-kernel chains.
+GENESIS = "0" * 64
+
+# Default rounding precision for tensor fingerprints. MUST match
+# szl_governed_norm._receipt._tensor_digest so a unified-chain norm receipt's
+# out_digest is bit-identical to the standalone kernel's.
+_DECIMALS = 6
+_DIGEST_CHUNK_ELEMENTS = 4096
+
+
+def tensor_digest(t: "Any", decimals: int = _DECIMALS) -> str:
+    """Deterministic SHA3-256 over a tensor's rounded float32 contents.
+
+    Identical scheme to szl_governed_norm._receipt._tensor_digest: round to a
+    fixed number of decimals, integerize, hash the raw little-endian bytes. This
+    makes the digest stable across devices/dtypes for the same logical values
+    (tiny FP noise won't change it). Integrity fingerprint, NOT a signature.
+
+    Falls back to hashing the repr only if torch is unavailable (headless
+    inspection); in a real kernel run torch is always present.
+    """
+    if _HAS_TORCH and hasattr(t, "detach"):
+        flat = t.detach().to(torch.float32).reshape(-1)
+        scaled = torch.round(flat * (10 ** decimals)).to(torch.int64).cpu()
+        digest = hashlib.sha3_256()
+        for chunk in scaled.split(_DIGEST_CHUNK_ELEMENTS):
+            values = chunk.tolist()
+            digest.update(struct.pack(f"<{len(values)}q", *values))
+        return digest.hexdigest()
+    return hashlib.sha3_256(repr(t).encode("utf-8")).hexdigest()
+
+
+class UnifiedReceiptChain:
+    """Append-only, SHA3-256 hash-chained log spanning MANY kernel ops.
+
+    Each receipt body is canonical JSON with a fixed, sorted schema:
+        {seq, kernel, op, attrs, prev}
+    where:
+        seq    -- 0-based position in the chain
+        kernel -- which suite member emitted it ('governed_norm', 'lambda_gate',
+                  'energy_core', or a composed block name)
+        op     -- the operation ('rms_norm', 'lambda_gate', 'measure_energy', ...)
+        attrs  -- an op-agnostic, JSON-able dict of honest, reproducible
+                  attributes (shapes, eps, out_digest, advisory Λ fields,
+                  energy label/joules, ...). NEVER fabricated.
+        prev   -- digest of the previous receipt (GENESIS for seq 0)
+
+    digest = SHA3-256 over the canonical JSON of {seq,kernel,op,attrs,prev}
+    (ts is excluded so the digest is reproducible offline).
+
+    verify() re-walks the chain and returns (ok, depth, first_break_seq):
+    it checks every sequence number, digest and prev-link. Without a separately
+    retained checkpoint this establishes only internal consistency: a valid
+    prefix or a fully recomputed history can still pass. Use expected_head and
+    expected_depth from trusted external custody to detect such replacement.
+    Timestamps are finite metadata but remain outside the hashed body. This is
+    not a signature, a proof of execution, or protection from a hostile process.
+    Public read methods return detached snapshots, not references to storage.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._records: List[Dict[str, Any]] = []
+
+    # -- canonical hashing (sorted keys, tight separators, strict no-NaN) --
+    @staticmethod
+    def _digest_body(body: Dict[str, Any]) -> str:
+        raw = json.dumps(
+            body, sort_keys=True, separators=(",", ":"), allow_nan=False
+        ).encode("utf-8")
+        return hashlib.sha3_256(raw).hexdigest()
+
+    def emit(self, kernel: str, op: str, attrs: Dict[str, Any]) -> Dict[str, Any]:
+        """Append one op-agnostic receipt and return it (with digest + ts).
+
+        ``attrs`` must be JSON-able and finite (no NaN/Inf) — a non-finite value
+        would make the receipt un-attestable by a strict third-party verifier,
+        so it is rejected at hash time by allow_nan=False. Callers screen
+        non-finite numbers to None/UNKNOWN upstream (the energy kernel already
+        does this).
+        """
+        with self._lock:
+            prev = self._records[-1]["digest"] if self._records else GENESIS
+            seq = len(self._records)
+            body = {
+                "seq": seq,
+                "kernel": str(kernel),
+                "op": str(op),
+                # Normalize to a detached JSON value before hashing. Later caller
+                # mutation cannot invalidate stored history or future prev-links.
+                "attrs": self._snapshot_attrs(attrs),
+                "prev": prev,
+            }
+            digest = self._digest_body(body)
+            rec = dict(body, digest=digest, ts=time.time())
+            self._records.append(rec)
+            return copy.deepcopy(rec)
+
+    @staticmethod
+    def _snapshot_attrs(attrs: Dict[str, Any]) -> Dict[str, Any]:
+        if not isinstance(attrs, dict):
+            raise TypeError("receipt attrs must be a JSON object")
+        return json.loads(json.dumps(attrs, sort_keys=True, allow_nan=False))
+
+    def checkpoint(self) -> Dict[str, Any]:
+        """Atomically capture depth/head; preserve it OUTSIDE this chain.
+
+        This unsigned dictionary has no authentication by itself. The caller
+        must bind it to a separately trusted signed receipt or retained record.
+        Two separate calls to count() and head() are not an atomic checkpoint.
+        """
+        with self._lock:
+            if not self._verify_records(self._records)[0]:
+                raise ValueError("cannot checkpoint an inconsistent chain")
+            return {
+                "schema": "szl.receipt-checkpoint/v1",
+                "depth": len(self._records),
+                "head": self._records[-1]["digest"] if self._records else GENESIS,
+            }
+
+    # -- convenience emitters that enforce the honesty schema per kernel ----
+    def emit_norm(self, op: str, x: "Any", out: "Any", eps: float) -> Dict[str, Any]:
+        """Record a governed-norm op. out_digest matches szl_governed_norm."""
+        return self.emit(
+            "governed_norm",
+            op,
+            {
+                "in_shape": list(getattr(x, "shape", [])),
+                "in_dtype": str(getattr(x, "dtype", "")).replace("torch.", ""),
+                "eps": float(eps),
+                "out_digest": tensor_digest(out),
+            },
+        )
+
+    def emit_lambda(
+        self,
+        score: float,
+        threshold: float,
+        passed: bool,
+        k: int,
+    ) -> Dict[str, Any]:
+        """Record an ADVISORY Λ-gate evaluation.
+
+        ``advisory`` is hard-coded True and ``lambda_status`` is stamped on every
+        entry so the chain itself is self-documenting: a recorded pass is NEVER
+        proven trust (Λ uniqueness = Conjecture 1, open).
+        """
+        return self.emit(
+            "lambda_gate",
+            "lambda_gate",
+            {
+                "score": float(score),
+                "threshold": float(threshold),
+                "passed": bool(passed),
+                "k": int(k),
+                "advisory": True,
+                "lambda_status": "Conjecture 1 (open) — advisory only, NOT proven trust",
+            },
+        )
+
+    def emit_energy(self, measurement: Dict[str, Any]) -> Dict[str, Any]:
+        """Record an energy reading VERBATIM (label + joules as-given).
+
+        ``joules`` may be None (UNAVAILABLE/UNKNOWN) — it is recorded as None,
+        never upgraded to a fabricated number. ``label`` is the kernel's honest
+        MEASURED/SAMPLE/UNAVAILABLE_NO_NVML/ESTIMATE/UNKNOWN string.
+        """
+        joules = measurement.get("joules", None)
+        return self.emit(
+            "energy_core",
+            "measure_energy",
+            {
+                "label": str(measurement.get("label", "UNKNOWN")),
+                "joules": (None if joules is None else float(joules)),
+                "source": str(measurement.get("source", "")),
+            },
+        )
+
+    # -- read surface --------------------------------------------------------
+    def head(self) -> str:
+        with self._lock:
+            return self._records[-1]["digest"] if self._records else GENESIS
+
+    def count(self) -> int:
+        with self._lock:
+            return len(self._records)
+
+    def tail(self, n: int = 10) -> List[Dict[str, Any]]:
+        if type(n) is not int or n < 0:
+            raise ValueError("tail length must be a nonnegative integer")
+        with self._lock:
+            return copy.deepcopy(self._records[-n:]) if n else []
+
+    def kernels_touched(self) -> List[str]:
+        """Distinct kernels that appear in the chain, in first-seen order.
+
+        This summarizes the recorded kernel labels; it does not prove that
+        any named implementation actually executed.
+        """
+        with self._lock:
+            seen: List[str] = []
+            for r in self._records:
+                if r["kernel"] not in seen:
+                    seen.append(r["kernel"])
+            return seen
+
+    @staticmethod
+    def _validate_checkpoint(expected_head: Optional[str], expected_depth: Optional[int]) -> None:
+        if expected_head is None and expected_depth is None:
+            return
+        if (not isinstance(expected_head, str)
+                or re.fullmatch(r"[0-9a-f]{64}", expected_head) is None
+                or type(expected_depth) is not int or expected_depth < 0):
+            raise ValueError("checkpoint requires a full lowercase head and nonnegative depth")
+        if (expected_depth == 0) != (expected_head == GENESIS):
+            raise ValueError("genesis checkpoint must have exactly zero depth")
+
+    @staticmethod
+    def _verify_records(
+        records: Any,
+        *,
+        expected_head: Optional[str] = None,
+        expected_depth: Optional[int] = None,
+    ) -> Tuple[bool, int, int]:
+        # Checkpoint argument errors are programmer errors, not corrupt history.
+        UnifiedReceiptChain._validate_checkpoint(expected_head, expected_depth)
+        if not isinstance(records, list):
+            return (False, 0, 0)
+        depth = len(records)
+        # OfflineNavigator's existing deterministic projection omits ts.
+        # Only that unhashed metadata is optional; all hashed/digest fields
+        # remain required and unrelated extra fields are rejected.
+        fields = {"seq", "kernel", "op", "attrs", "prev", "digest"}
+        prev = GENESIS
+        for i, rec in enumerate(records):
+            try:
+                if (not isinstance(rec, dict) or set(rec) not in (fields, fields | {"ts"})
+                        or type(rec["seq"]) is not int or rec["seq"] != i
+                        or not isinstance(rec["kernel"], str)
+                        or not isinstance(rec["op"], str)
+                        or not isinstance(rec["attrs"], dict)
+                        or not isinstance(rec["prev"], str)
+                        or re.fullmatch(r"[0-9a-f]{64}", rec["prev"]) is None
+                        or not isinstance(rec["digest"], str)
+                        or re.fullmatch(r"[0-9a-f]{64}", rec["digest"]) is None
+                        or ("ts" in rec and (type(rec["ts"]) not in (int, float)
+                                            or not math.isfinite(rec["ts"])))):
+                    return (False, depth, i)
+                body = {key: rec[key] for key in ("seq", "kernel", "op", "attrs", "prev")}
+                actual = UnifiedReceiptChain._digest_body(body)
+                if rec["prev"] != prev or not hmac.compare_digest(rec["digest"], actual):
+                    return (False, depth, i)
+                prev = rec["digest"]
+            except (ValueError, TypeError, KeyError, OverflowError, RecursionError):
+                return (False, depth, i)
+        if expected_head is not None:
+            if depth != expected_depth or not hmac.compare_digest(prev, expected_head):
+                # The observed chain is internally consistent but not the
+                # expected extent/history. Report the boundary, not a fake row.
+                return (False, depth, min(depth, expected_depth))
+        return (True, depth, -1)
+
+    def verify(
+        self,
+        *,
+        expected_head: Optional[str] = None,
+        expected_depth: Optional[int] = None,
+    ) -> Tuple[bool, int, int]:
+        """Verify consistency, optionally against a separately retained checkpoint.
+
+        Returns (ok, observed_depth, first_break). For checkpoint mismatch,
+        first_break is min(observed_depth, expected_depth), an extent boundary.
+        Unanchored success cannot detect valid-prefix truncation or rehashing.
+        """
+        with self._lock:
+            return self._verify_records(
+                self._records, expected_head=expected_head, expected_depth=expected_depth
+            )
+
+    def export_with_checkpoint(self) -> Tuple[str, Dict[str, Any]]:
+        """Capture one export and matching checkpoint under the same lock.
+
+        The checkpoint still needs separate authenticated custody. Keeping
+        it only beside the export cannot prevent replacement of both.
+        """
+        with self._lock:
+            checkpoint = self.checkpoint()
+            return self.to_json(), checkpoint
+
+    def to_json(self) -> str:
+        """Serialize stored records, not evidence of authorship or execution.
+
+        Preserve an independently trusted checkpoint to verify this export's
+        expected head and length. A checkpoint bundled only with the export
+        cannot protect against coordinated replacement of both.
+        """
+        with self._lock:
+            return json.dumps(self._records, sort_keys=True, separators=(",", ":"), allow_nan=False)
+
+    @staticmethod
+    def verify_json(
+        blob: str,
+        *,
+        expected_head: Optional[str] = None,
+        expected_depth: Optional[int] = None,
+    ) -> Tuple[bool, int, int]:
+        """Verify strict JSON, then consistency and an optional external checkpoint.
+
+        Duplicate object keys, nonfinite numbers, malformed records and wrong
+        sequence ordinals are rejected. Invalid JSON returns (False, 0, 0).
+        No signature, origin, timestamp authenticity or execution claim follows.
+        """
+        UnifiedReceiptChain._validate_checkpoint(expected_head, expected_depth)
+
+        def unique_object(pairs):
+            result = {}
+            for key, value in pairs:
+                if key in result:
+                    raise ValueError("duplicate JSON key")
+                result[key] = value
+            return result
+
+        def reject_constant(value):
+            raise ValueError("nonfinite JSON constant")
+
+        if not isinstance(blob, str):
+            return (False, 0, 0)
+        try:
+            records = json.loads(blob, object_pairs_hook=unique_object, parse_constant=reject_constant)
+        except (ValueError, TypeError, OverflowError, RecursionError):
+            return (False, 0, 0)
+        return UnifiedReceiptChain._verify_records(
+            records, expected_head=expected_head, expected_depth=expected_depth
+        )