cadrumo.core.observability.context module

Contextvars-backed run context with nesting support and JSONL sink wiring.

Entering run_context() at the outermost CLI entry point mints a fresh run_id, fingerprints the corpus / db / cert state, attaches a cadrumo.core.observability.sink.JsonlRunSink to the root logger for the duration of the block, emits a cadrumo.core.observability.models.RunEventKind.STEP_START event, and persists the final cadrumo.core.observability.models.RunTrace on exit. Nesting is idempotent: an inner enter reuses the outer run_id and only pushes a new step identifier.

class RunContextInfo(**data)[source]

Bases: BaseModel

Immutable bag of run-level metadata exposed to call sites.

Yielded by run_context() so callers can stamp recorded events with the active run_id or surface it in user-facing output.

Variables:

  • run_id – 16-char lowercase hex identifier for this run.

  • entrypoint – Stable string identifying the CLI entry point (e.g. "program workflow run").

  • started_at – Wall-clock UTC timestamp captured at run-context enter.

  • arguments – Tuple of ArgumentRecord capturing CLI flags and positional values for diagnostic correlation.

  • corpus_sha256 – Fingerprint of the effective Settings configuration at enter time.

  • db_sha256 – Fingerprint of the canonical application data root (Settings.cadrumo_local_storage_root) at enter time, excluding regenerable cache subdirectories.

  • cert_fingerprint – SHA-256 of the configured PKCS#12 certificate, or "" when no cert path is configured.

  • initial_step_id – Step identifier emitted with the first STEP_START boundary event.

Parameters:

data (Any)

run_id: str
entrypoint: str
started_at: datetime
arguments: tuple[ArgumentRecord, ...]
corpus_sha256: ContentDigest
db_sha256: ContentDigest
cert_fingerprint: ContentDigestOrAbsent
initial_step_id: str
RUN_CONTEXT_VAR: ContextVar

Active RunContextInfo for the current task / thread, or None.

STEP_CONTEXT_VAR: ContextVar

Active step identifier within the current run context, or None.

run_context(*, entrypoint, arguments=(), run_id=None, step_id=None)[source]

Enter a run context, emitting STEP_START / STEP_END boundary events.

The outermost enter mints a run_id, fingerprints the corpus / db / cert state, attaches a cadrumo.core.observability.sink.JsonlRunSink to the root logger, emits a STEP_START event, and on exit emits a STEP_END plus persists the finalised cadrumo.core.observability.models.RunTrace (even on exception, with RunOutcome.FAILED).

Inner enters reuse the outer run_id and only push a new step_id, so callers can wrap higher-level commands without every callee knowing whether a run is already active.

Parameters:

  • entrypoint (str) – Stable string identifying the CLI entry point (e.g. "cadrumo workflow run").

  • arguments (Sequence[ArgumentRecord]) – Sequence of ArgumentRecord capturing the CLI flags and values for diagnostics.

  • run_id (str | None) – Optional caller-supplied run_id for correlation.

  • step_id (str | None) – Optional initial step identifier; defaults to "step-0" for the outermost enter and a derived nested id for inner enters.

Yields:

The active RunContextInfo for the block.

Raises:

Exception – The error captured during the save_trace call, re-raised when trace persistence fails and the yielded body completed successfully (outcome OK).

Return type:

Generator[RunContextInfo]