aeat.core.observability._golden module

Canonicalise / mask / compare primitive for golden-output determinism.

One substrate, two consumers (ADR 2026-06-30-deterministic-output-replay-substrate): the observability core.observability.replay_run() envelope-assertion tier and the harness operator golden gate both call this primitive; neither re-implements capture or compare.

The captured payload is the verbatim emitted SchemaEnvelope document. On load it is re-validated against SCHEMA_REGISTRY[command] by validate_captured_envelope() so the captured payload is a typed envelope around a registered OutputSchema, never a dict[str, Any] bag. Comparison (assert_golden_match()) is over the FULL envelope (shared spine plus result), key-sorted and canonicalised, after a declared narrow field mask that hides only the residual non-deterministic surrogate keys.

Masking honesty

GOLDEN_MASK_FIELDS is a declared, narrow allowlist — the two opaque surrogate keys that still flap once the clock seam (core.time.frozen_clock()) is frozen and profile_id is injected: snapshot_id (its profile_id prefix and timestamp are deterministic, only the trailing uuid4().hex flaps) and the observability run_id (a minted uuid4 tail). A mask broad enough to hide a real regression voids the gate, so the mask is kept minimal and is proven minimal by an anti-tautology test that asserts, for a scenario captured twice under a frozen clock and injected identity, the set of differing JSON paths reduces to exactly these masked fields — differing_field_names() and differing_paths() exist for that proof.

MASK_SENTINEL

The sentinel a masked leaf is replaced with before comparison.

GOLDEN_MASK_FIELDS: frozenset[str]

Declared, narrow allowlist of leaf field names whose values are opaque, non-assertable surrogate keys carrying an unseedable uuid4 tail. These are the ONLY residual non-deterministic leaves once core.time.frozen_clock() is frozen and profile_id is injected. Widening this set is a standing honesty hazard; every addition must be proven minimal by the anti-tautology gate.

canonicalise(document)

Return the UTF-8, key-sorted, fixed-indent canonical form of document.

The canonical form is the byte string two captures are compared on. Key-sorting makes the comparison insensitive to emit-time key order; the fixed indent keeps a mismatch diff human-readable.

Return type:

str

Parameters:

document (Mapping[str, object])

mask_document(document, *, fields=frozenset({'run_id', 'snapshot_id'}))

Return a deep copy of document with masked leaves replaced by a sentinel.

Any mapping value stored under a key in fields — at any depth — is replaced by MASK_SENTINEL. The rest of the document is copied verbatim, so a real output difference outside the masked fields is preserved for comparison.

Parameters:

• document (Mapping[str, object]) – The envelope document to mask.

• fields (frozenset[str]) – Leaf field names to mask; defaults to GOLDEN_MASK_FIELDS.

Return type:

dict[str, object]

Returns:

A new dict with the masked leaves replaced.

flatten_paths(document)

Return a flat {dotted-path: leaf-value} view of document.

List elements are addressed with [index] segments (e.g. notices[0].code). Leaves are scalars; empty containers are recorded as their own leaf so a container that gains its first element still surfaces as a differing path.

Return type:

dict[str, object]

Parameters:

document (Mapping[str, object])

differing_paths(left, right)

Return the set of dotted JSON paths whose leaves differ between two documents.

A path is included when it is present in only one document, or when it is present in both with unequal leaf values. This is the raw, UNMASKED diff used by the anti-tautology proof to show the mask is exactly the residual non-deterministic field set.

Return type:

frozenset[str]

Parameters:

• left (Mapping[str, object])

• right (Mapping[str, object])

differing_field_names(left, right)

Return the leaf field names of the paths that differ between two documents.

The leaf field name of result.snapshot_id is snapshot_id and of notices[0].code is code. Used by the anti-tautology proof to assert the residual diff reduces to exactly GOLDEN_MASK_FIELDS.

Return type:

frozenset[str]

Parameters:

• left (Mapping[str, object])

• right (Mapping[str, object])

assert_golden_match(expected, actual, *, fields=frozenset({'run_id', 'snapshot_id'}))

Assert two envelope documents are byte-identical after masking, else raise.

Both documents are masked with fields and canonicalised; if the canonical byte strings differ, a GoldenReplayMismatchError is raised carrying the differing masked paths.

Parameters:

• expected (Mapping[str, object]) – The captured golden expectation.

• actual (Mapping[str, object]) – The replayed / re-emitted envelope document.

• fields (frozenset[str]) – Leaf field names to mask; defaults to GOLDEN_MASK_FIELDS.

Raises:

GoldenReplayMismatchError – When the masked canonical forms differ.

Return type:

None

validate_captured_envelope(document, *, registry=None)

Re-validate a captured envelope document through its registered schema.

Looks up document["command"] in registry (defaulting to the process-global SCHEMA_REGISTRY), specialises SchemaEnvelope over the registered result schema, and strictly validates the document. The return value is a typed envelope, never a dict[str, Any] bag — this is the typed boundary the substrate keeps captured payloads behind.

Parameters:

• document (Mapping[str, object]) – The emitted envelope document to re-validate.

• registry (Mapping[str, TypeAliasType] | None) – Optional command-to-schema registry override (used by tests to avoid polluting the global registry). Defaults to SCHEMA_REGISTRY.

Return type:

SchemaEnvelope[OutputSchema]

Returns:

The strictly-validated SchemaEnvelope whose result is the registered OutputSchema for the captured command.

Raises:

GoldenCaptureError – When the document has no command string, the command is unregistered, or the payload fails strict validation against the registered schema.