Decision log¶

Audience: operators reconstructing why the router / profile / gate picked what it picked, without re-reading four modules of routing code.

Overview¶

Every routing / criterion-profile / gate-fire decision in Bernstein writes one append-only JSONL record to .sdd/runtime/decisions.jsonl.

Source:

src/bernstein/core/observability/decision_log.py
src/bernstein/cli/commands/decisions_cmd.py

The log is append-only, concurrent-safe (in-process lock + append-mode fd; cross-process safety from the kernel for the small line sizes written here), and malformed-line tolerant on read.

Record schema (`schema_version: 1`)¶

Field	Use
`ts`	Float epoch seconds
`decision_id`	`dec-<uuid>`
`kind`	`model_route`, `mode_profile`, `criterion_profile`, `gate_fire`
`chosen`	Winner id
`alternatives`	`[{"id", "score", "reason"}]` (truncated at `MAX_ALTERNATIVES`)
`confidence`	`0.0 - 1.0`
`rationale`	Human-readable summary
`parent_decision_id`	Parent decision id (for chained routing)
`policy_path`	Ordered list of policies that fired
`winner_score`	Numeric score for the chosen alternative
`inputs`	Free-form `{"task_id": ..., ...}`

CLI¶

bernstein decisions tail [-n N] [--path PATH]
bernstein decisions search [--kind KIND] [--since DURATION] [--path PATH]

--kind filters to one decision kind (e.g. model_route).
--since accepts 30s, 15m, 2h, 1d.
--path overrides the default .sdd/runtime/decisions.jsonl.

Both commands render a Rich table with ts, kind, chosen, confidence, and a trimmed rationale. Use redirection / shell tooling on the raw JSONL when you need scriptable output.

Examples¶

Last 50 routing decisions:

bernstein decisions tail -n 50

Look at every gate that fired in the last hour:

bernstein decisions search --kind gate_fire --since 1h

Pipe to jq for richer analysis:

jq -c 'select(.kind == "model_route")' .sdd/runtime/decisions.jsonl \
  | jq -s 'group_by(.chosen) | map({model: .[0].chosen, n: length})'

Disabling¶

Set BERNSTEIN_DECISION_LOG=0 in the orchestrator environment. The single record_decision entry point becomes a no-op; routing paths remain unchanged. The CLI subcommands keep working against any existing log file.

Bounded payloads¶

alternatives is truncated to MAX_ALTERNATIVES entries before serialisation; a routing bug that explores 10,000 candidates cannot fill the disk through this channel.

Troubleshooting¶

bernstein decisions tail is empty. Either the log was disabled via BERNSTEIN_DECISION_LOG=0, or no routing has happened yet in this workdir. Run a small task first, then re-tail.

Concurrent writers from a multi-process run. Cross-process append safety relies on the kernel's atomicity guarantee for sub-PIPE_BUF writes. If you are sharing a log across hosts (NFS), wrap the runs with separate log paths and merge offline.

Malformed line warnings. A partial line (machine killed mid-write) will be skipped by iter_records with a debug log. Trim the trailing broken line by hand if it bothers your downstream tooling.