prereg_seal.core

prereg-seal — seal an acceptance specification before you measure.

The problem this solves is not fraud. It is the ordinary, mostly-honest drift in which a threshold is chosen after a result is seen, and everyone involved remembers it the other way round. A seal makes the ordering checkable.

Standard library only.

FORMAT = 'prereg-seal/2'

LEGACY_FORMATS = ('prereg-seal/1',)

DOMAIN = b'PREREG-SEAL-v1'

class SealMismatch(builtins.Exception):

Raised when a specification does not match the seal presented with it.

def canonicalize(spec: Any) -> bytes:

Deterministic bytes for any JSON-serializable specification.

Sorted keys, no insignificant whitespace, UTF-8, and NFC-normalised strings. Two specifications that differ only in key order, formatting, or Unicode normalisation form produce identical bytes; two that differ in any value do not.

Note that JSON has no tuple type, so [1,2] and (1,2) canonicalise identically — by design, since they serialise identically.

def digest(spec: Any) -> str:

Domain-separated SHA-256 over the canonical form.

def seal(spec: Any, *, note: str = '') -> dict:

Produce a seal artifact for spec.

The seal deliberately does not contain the specification. It contains the digest. Publishing the seal therefore commits you to the criteria without revealing them, which is what makes it usable before a blind evaluation.

def verify(spec: Any, sealed: dict) -> None:

Raise SealMismatch unless spec matches sealed.

Both directions fail loudly: altering the specification after sealing changes the recomputed digest, and altering the seal to match an altered specification is caught by whatever binds the seal (see bind()).

def matches(spec: Any, sealed: dict) -> bool:

Boolean form of verify().

def bind(result: dict, sealed: dict) -> dict:

Attach a seal to a result record, and cross-bind the pair.

The cross-binding is what makes the second failure direction detectable: swapping in a seal that matches doctored criteria changes seal_binding, because the binding covers the result and the seal together.

def verify_bound(bound: dict, spec: Any) -> None:

Verify a bound result end to end: binding intact and spec matches seal.

def write_seal(path, spec: Any, *, note: str = '') -> dict:

Seal spec and write the artifact to path.

def read_seal(path) -> dict:

def guard( spec: Any, seal_path, *, env_var: str = 'PREREG_SEAL_ALLOW_UNSEALED') -> dict:

Fail-closed guard for use at evaluation time.

Re-serializes the specification actually in force, recomputes its digest and compares it to the seal on disk. Raises unless they match.

If the seal file is absent this raises too — an unsealed evaluation is the condition the tool exists to prevent. Set the escape-hatch environment variable only for local exploration; it is deliberately verbose to type and is reported in the returned record so it cannot pass unnoticed.