aeat.core.observability._replay module

Deterministic read-only replay of a recorded RunTrace.

Replay loads a persisted trace, recomputes the current corpus_sha256, refuses on drift, and re-enters the same Typer CLI path reconstructed from captured ArgumentRecord values.

Replay also refuses recorded arguments containing the removed --no-dry-run flag, so old traces cannot reintroduce an obsolete CLI shape during argv reconstruction.

replay_run(run_id, *, invoke=None, assert_envelope=False, assert_db_state=False)[source]

Replay a recorded run after gating on corpus drift.

When assert_envelope is set and invoke is provided, the re-entered invocation’s emitted --format json envelope is captured and asserted byte-identical (after the declared narrow mask) against the golden envelope persisted for the original run — closing the research F1 gap so replay proves “the same JSON came out”, not only “the same argv re-runs”. The capture/canonicalise/mask/compare logic lives in the shared substrate primitive (aeat.core.observability._golden); the operator golden gate reuses the same primitive.

Parameters:

  • run_id (str) – Identifier of the recorded run to replay.

  • invoke (Callable[[list[str]], object] | None) – Optional callable that re-enters the CLI with the reconstructed argv. When None the function loads and validates the trace but does not re-execute it, returning the original RunTrace directly.

  • assert_envelope (bool) – When True (and invoke is provided), load the original run’s persisted envelope.json, capture the re-entered invocation’s emitted envelope, and assert they match after masking.

  • assert_db_state (bool) – When True (and invoke is provided), the OPTIONAL post-state tier: recompute the var/ fingerprint after re-entry and assert it equals the recorded db_sha256. This proves state-transition determinism (a retried write is a true no-op) and is meaningful only for a scenario that runs against a hermetic synthetic var/ root; the shared var/ would flap it, which is why it is opt-in and never a hard gate for all replays.

Return type:

RunTrace

Returns:

The loaded RunTrace of the original run.

Raises:

  • AeatObservabilityError – When the trace carries removed write-era flags, when assert_envelope is set but the re-entered invocation emitted no envelope to compare, or when assert_db_state is set and the post-state var/ fingerprint drifts from the recorded one.

  • AeatCorpusDriftError – When the current corpus hash differs from the recorded one.

  • GoldenReplayMismatchError – When assert_envelope is set and the replayed envelope diverges from its captured expectation.