aeat.core.observability._errors module

Concrete observability errors layered over AeatObservabilityError.

The base class aeat.core.errors.AeatObservabilityError lives in aeat.core.errors so other subpackages can catch it without importing observability internals. This module re-exports the base and declares the leaf error types raised by record_event(), run_context(), load_trace(), and replay_run().

exception RunContextMissingError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatObservabilityError

Raised when record_event() runs outside an active run_context().

Caused by calling the recorder from a thread that did not propagate the contextvar bound by aeat.core.observability.run_context(), or by calling it from CLI bootstrap code that runs before the run context enters.

Parameters:

  • message (str | None)

  • context (dict[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception RunTraceValidationError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatObservabilityError

Raised when persisted trace.json or events.jsonl fails strict validation.

Surfaces both shape-level rejections (bad run_id, malformed JSON line) and strict validation failures for RunTrace or RunEvent records.

Parameters:

  • message (str | None)

  • context (dict[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception RunTracePersistenceError(*, operation, path)[source]

Bases: AeatObservabilityError

Raised when run-trace files cannot be created, read, or written.

Parameters:

  • operation (str)

  • path (Path)

Return type:

None

code: ClassVar[ErrorCode]
exception AeatCorpusDriftError(*, run_id, recorded, observed, entrypoint)[source]

Bases: AeatObservabilityError

Raised when replay detects that corpus_sha256 has drifted.

Carries both the recorded and observed hashes plus the entrypoint so the caller can render an actionable diff. aeat.core.observability.replay_run() is the only call site that raises this.

Variables:

  • run_id – Identifier of the recorded run being replayed.

  • recorded – corpus_sha256 captured at the original run.

  • observed – corpus_sha256 computed against the current tree.

  • entrypoint – CLI entrypoint string of the recorded run.

Parameters:

  • run_id (str)

  • recorded (str)

  • observed (str)

  • entrypoint (str)

Return type:

None

code: ClassVar[ErrorCode]
exception GoldenCaptureError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: AeatObservabilityError

Raised when a captured envelope document cannot be typed / re-validated.

Surfaces an emitted-envelope document whose command is not in the JSON-contract schema registry, or whose payload fails strict validation against the registered schema. The deterministic-output substrate refuses to compare an untyped document, keeping the captured payload from degrading to a dict[str, Any] bag.

Parameters:

  • message (str | None)

  • context (dict[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
exception GoldenReplayMismatchError(*, differing_paths, detail)[source]

Bases: AeatObservabilityError

Raised when a replayed envelope diverges from its captured expectation.

Carries the differing JSON paths (after the declared narrow mask is applied) so the caller can render an actionable diff. The aeat.core.observability.replay_run() envelope-assertion tier and the operator golden gate both raise this through the shared compare primitive.

Variables:

differing_paths – Sorted tuple of dotted JSON paths that differ after masking.

Parameters:
Return type:

None

code: ClassVar[ErrorCode]