prereg_seal

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

FORMAT = 'prereg-seal/2'

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.

def make_anchor(digest: str, kind: str, locator: str, *, note: str = '') -> Dict:

Build an unverified anchor record.

It is unverified on purpose. Creating the record proves nothing; only verify_anchor() does, and only by going and looking.

def verify_anchor( record: Dict, *, fetch: Optional[Callable[[str, float], str]] = None, timeout: float = 15.0, allow_network: bool = True) -> Dict:

Check the digest really is where the record says, and when.

fetch(url, timeout) -> text can be supplied to test this without a network, or to route through your own client. With allow_network=False and no fetch, the result is UNANCHORED — never an accepted claim.

def describe(result: Dict) -> str:

A human-readable line that does not overstate what was established.

class AnchorError(builtins.ValueError):

A malformed anchor record or locator.

ANCHOR_FORMAT = 'prereg-anchor/1'

ANCHORED = 'ANCHORED'

REFUTED = 'REFUTED'

UNANCHORED = 'UNANCHORED'

def emit(res: Dict, fmt: str, **kw) -> str:

def to_json(res: Dict, source: str = 'spec') -> str:

def to_jsonl(res: Dict, source: str = 'spec') -> str:

def to_sarif(res: Dict, source: str = 'spec') -> str:

def to_junit(res: Dict, source: str = 'spec') -> str:

def outcome_meta(outcome: str) -> Tuple[bool, str, str]:

Metadata for an outcome. An unrecognised one is a failure, never a pass.

EMITTERS = {'json': <function to_json>, 'jsonl': <function to_jsonl>, 'sarif': <function to_sarif>, 'junit': <function to_junit>}

__version__ = '1.0.0'