cadrumo.core.observability.errors module

Concrete observability errors layered over CadrumoObservabilityError.

The base class cadrumo.core.errors.hierarchy.CadrumoObservabilityError lives in cadrumo.core.errors so other subpackages can catch it without importing observability internals. This module declares the leaf error types raised by record_event(), run_context(), and load_trace().

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

Bases: CadrumoObservabilityError

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 cadrumo.core.observability.context.run_context(), or by calling it from CLI bootstrap code that runs before the run context enters.

Parameters:

  • message (str | None)

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

  • translated_message (str | None)

Return type:

None

code
exception RunTraceValidationError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoObservabilityError

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 (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

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

Bases: CadrumoObservabilityError

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

Parameters:

  • operation (str)

  • path (Path)

Return type:

None

code
exception GoldenCaptureError(message=None, *, context=None, translated_message=None)[source]

Bases: CadrumoObservabilityError

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 (Mapping[str, object] | None)

  • translated_message (str | None)

Return type:

None

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

Bases: CadrumoObservabilityError

Raised when compared envelopes diverge after the declared mask.

Carries the differing JSON paths (after the declared narrow mask is applied) so the caller can render an actionable diff. The operator golden gate raises this through the shared compare primitive.

Variables:

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

Parameters:
Return type:

None

code