Decision ledger fields

The decision ledger is an append-only JSONL file: one JSON object per line per proxied request. This page documents the wire schema of that object field-by-field. The schema is v: 1 and evolves additive-only — a breaking change bumps the top-level v.

Top-level record

Field	Type	Meaning
v	int	Schema version (currently 1).
ts	string	Request arrival, RFC3339 with ms, UTC.
req_id	string	Server-minted request id; equals the x-tt-request-id response header.
trace	object	Explicit-header trace grouping. See trace.
http	object	Request/response envelope. See http.
request	object	Parsed-request summary (hash + counted features). See request.
signals	object	Map of every registered provider signal’s output (heterogeneous values). See signals.
decision	object	The routing decision and its disclosure blocks. See decision.
usage	object	Normalized token accounting. See usage.
cost	object	Priced outcome with provenance. See cost.
latency	object	Timing breakdown. See latency.
outcome	object	Response-side result. See outcome.
mcp	array	Per-tool MCP attribution; [] when none. See mcp.
dims	object	Business-dimension attribution (explicit headers only). Omitempty. See dims.
content	object	Capture-state flags for request/response bodies. Omitempty.
demo	bool	Synthetic-row watermark; present only on demo data. Omitempty.
feedback	array	Populated by the reader from feedback companion rows; never on the primary row. Omitempty.
units	object	Non-token billable units (images/audio/…). Omitempty; token rows omit it. See units.
disclosures	object	Row-level honesty ledger (e.g. cross-dialect translation loss). Omitempty. See disclosures.
replica	string	Resolved writing-replica name in a scale-out fleet. Omitempty; absent = single-node/pre-scale-out.

request

Prompt text is never stored — only its hash and counted features.

Field	Type	Meaning
model	string	The model the client requested.
prompt_sha256	string	SHA-256 of the prompt. Not the prompt text — a fingerprint only.
prompt_bytes	int	Byte length of the assembled prompt.
messages	int	Message count.
system_bytes	int	Byte length of the system prompt.
has_tools	bool	Whether tools were declared.
tool_count	int	Number of declared tools.
tool_result_count	int	Number of tool-result messages present.
max_tokens	int	Requested max output tokens.
reasoning	object	Dialect-mapped reasoning knobs. Omitempty. { "effort": "high" }.

trace

Field	Type	Meaning
trace_id	string	Trace grouping id.
step_id	string	Step id within the trace.
parent_id	string	Parent step id.
agent	string	Agent name.
step_class	string	user_turn | tool_loop | provider_state | "".
step_class_source	string	header | derived | "".
w3c	string	Raw traceparent when present.
source	string	x-tt | traceparent | none.

http

Field	Type	Meaning
path	string	Request path, e.g. /v1/chat/completions.
dialect	string	Wire dialect, e.g. openai.
stream	bool	Whether the response was streamed.
status	int	HTTP status code.
endpoint	string	Endpoint kind (e.g. chat). Omitempty; absent = chat-or-passthrough.
provider	string	The provider that served the request — its own identity, decoupled from dialect. Omitempty.

signals

signals is an open map of every registered signal provider’s output. Values are heterogeneous: numeric sub-scores (float64), a token estimate (int under token_est), and the string complexity_tier. Example:

{
  "code": 1,
  "complexity": 0.42,
  "complexity_tier": "MEDIUM",
  "token_est": 4605
}

The decision block

The wire-shaped view of the routing decision, plus its optional disclosure blocks.

Field	Type	Meaning
mode	string	Operating mode, e.g. route | shadow | ledger.
tier	string	Chosen tier; "" when no tier was selected (e.g. a governance-refused row).
upstream	string	Chosen upstream; "" when none.
model_rewrite	object	{from, to} rewrite, or null if none. See below.
rule	string	Deciding rule: a rule id | default | override | pin.
candidates	array	Considered candidates with scores. See below.
shadow_tier	string	Shadow-mode would-route tier; null otherwise.
override	bool	A terminal override fired (e.g. x-tt-tier).
fail_safe	bool	The decision fell back to a fail-safe.
affinity_pin	bool	An affinity pin held the route.
cooldown_skips	array	Tiers skipped due to cooldown.
refused_by_budget	string	Flat-budget that refused the request (HTTP 429). Omitempty.
refused_by_policy	string	Typed reason of a policy refuse target (e.g. budget_exhausted). Omitempty.
policy_rev	string	Content hash of the active policy (v2 policy language). Omitempty.
explain	object	The decision-explain block (v2 rows). Omitempty.
cascade	object	Cascade block; present iff the decision staged a cascade. Omitempty.
response_cache	object	Response-cache disclosure. Omitempty; absent = cache did not engage. See decision.response_cache.
governance	object	Governance disclosure. Omitempty; absent = governance did not engage. See decision.governance.
refused_by_limit	object	Typed governance refusal (HTTP 401/403/429/503). Omitempty. See decision.refused_by_limit.
predicted	object	The calibrated quality the router consulted for the chosen tier. Omitempty; absent = no quality consult. See decision.predicted.

decision.model_rewrite

Field	Type	Meaning
from	string	The client-requested model.
to	string	The model actually served.

decision.candidates[]

Each element (core.Candidate):

Field	Type	Meaning
tier	string	Candidate tier.
eligible	bool	Whether the candidate passed filters.
score	float	Score, or null when unscored.

decision.predicted

The quality-consult witness: the calibrated quality figure the router read for the tier it chose, written only when a selector actually consulted candidate.quality.* at decision time. An absent block is the fact “this row was decided without quality evidence” — it shows as the quality_absent term in decision.explain, and it is never backfilled (backfilling would retroactively claim the router saw a number it never saw). Because the block is written only on a real consult, every field is always emitted: a lcb of 0 here is a real consulted zero, not an absence. See Quality-aware routing for how the figure changes a route.

Field	Type	Meaning
metric	string	The metric consulted, e.g. groundedness.
tier	string	The chosen tier this prediction is for.
lcb	float	The decision value — the Clopper–Pearson lower bound the router gated on (not the mean; routing on a point estimate is the overconfidence anti-pattern).
mean	float	The segment’s calibrated mean. Disclosure only — never the decision value.
confidence	float	The artifact’s nominal coverage (1 − α).
n	int	Observations behind the prediction.
segment	string	The Mondrian segment key metric | tier | model | endpoint — the model is the one served, not requested.
artifact_id	string	The active qcal_ artifact consulted (qcal_<compactTS>_<sha8>).
quality_ver	string	The quality-view version that was consulted.

decision.governance

Present iff governance engaged (a key resolved, limits were evaluated, shadow verdicts were produced, or a suspension was in effect). Absent means governance did not touch the request.

Field	Type	Meaning
kid	string	Resolved key id.
node	string	Resolved tenancy node (e.g. org:acme/team:ml/user:dev1).
verdict	string	allow | would_refuse (shadow).
would_refuse	array	Shadow mode: limit ids that would have fired. Omitempty.
suspended	array	Limits for which fail-open engaged this request. Omitempty.
user_asserted	bool	The §2.2 dims-authority marker. Always present (a disclosed false is meaningful).
rotation_grace	bool	The request rode a key-rotation grace window. Always present.
reserved_tokens	int	TPM reservation taken, when engaged. Omitempty.
serving_key	object	BYO row-attribution: whose key served this row. Names only, never secrets. Omitempty. See below.
gate_us	object	Per-stage gate wall time in µs: { "a": int, "b": int }.

decision.governance.serving_key

Names which tenant key/node served the row (BYO upstream-key attribution). Names only — never secret material.

Field	Type	Meaning
kid	string	Public key id. Omitempty.
node	string	Tenancy node string. Omitempty.
rotated_from	string	Rotation-lineage predecessor kid; "" when none. Omitempty.

decision.refused_by_limit

The full typed governance refusal, minus its human message. Present on every governance-refused row; the accountant charges it zero provider cost.

Field	Type	Meaning
type	string	budget_exceeded | rate_limited | quota_exhausted | concurrency_exceeded | quota_cost_unfittable | scope_violation | invalid_key | enforcement_unavailable.
refused_by	object	The firing limit and the holder’s node. Omitted on a 401. See below.
enforcement	object	Posture and disclosed bound. Omitted on 401/403. See below.

decision.refused_by_limit.refused_by

Field	Type	Meaning
limit_id	string	Id of the firing limit. Omitempty.
limit_type	string	Limit type, e.g. budget_usd. Omitempty.
unit	string	Limit unit, e.g. usd. Omitempty.
node	string	The holder’s own node. Always present.
period	string	Reset period, e.g. month. Omitempty.
resets_at	string	RFC3339 reset time. Omitempty.
retry_after_s	int	Retry-after seconds. Omitempty.
observed	float	Observed value at breach; omitted (not 0) when the store cannot report it.
limit	float	The configured limit; omitted when unavailable.

decision.refused_by_limit.enforcement

Field	Type	Meaning
posture	string	enforcing | fail_closed.
approximate	bool	The refusal used a disclosed approximate bound.
bound	object	Quantitative bound terms. Omitempty. See below.
note	string	Human bound caveat. Omitempty.

enforcement.bound

Field	Type	Meaning
tee_lag_rows	int	Rows the accounting tee lags by. Always emitted (a 0 is meaningful).
dropped_rows	int	Rows dropped from accounting. Always emitted.
in_flight_reserved	int	Current TPM/lease reservation view. Omitempty.
estimate_skew_p95	float	Rolling reconcile-delta p95. Omitempty.
convergence_lag_rows	int	Convergence lag in rows. Omitempty.

decision.response_cache

The response-cache honesty ledger. Written unconditionally whenever the cache engaged (ran a lookup or a store); absent means the cache did not engage. outcome and stored are always present; every other field is omitempty and carried only when its class of row bears it (e.g. kind/similarity/verified on a hit, bypass_reason on a bypass). A present block with stored: false is the meaningful fact “the cache engaged but this row’s response was not written.”

Field	Type	Meaning
outcome	string	hit | would_hit | miss | bypass | error. Always present.
kind	string	Matcher kind on a hit/would_hit, e.g. exact | semantic. Omitempty.
rule	string	Cache rule id that governed the request. Omitempty.
strategy	string	Matcher name. Omitempty.
entry_sha7	string	Stored entry id (short hash). Omitempty.
source_req_id	string	Provenance: the req_id of the original request that produced the entry. Omitempty.
age_ms	int	Age of the stored entry at serve time. Omitempty.
similarity	float	Semantic match score. Omitempty (semantic only).
threshold	float	Match threshold (the calibrated T* when a verified policy is active). Omitempty.
verified	bool	Verifier verdict: true | false | absent (no verifier). Omitempty.
scope_sha7	string	The scope key (short hash). Omitempty.
stored_provider	string	Provider that produced the stored response. Omitempty.
stored_model	string	Model that produced the stored response. Omitempty.
source_usage	object	The source row’s usage block. Omitempty (a bypass/miss omits it).
saved	object	Typed counterfactual savings (StageCost shape). Omitempty. See below.
saved_basis	string	Audit string: how saved was computed. Omitempty.
embed_cost	object	Embedding spend when metered (StageCost shape). Omitempty. See below.
stored	bool	This row’s response was written to cache. Always present (false is meaningful).
bypass_reason	string	On a bypass: client_off | stream_binary | tool_calls | over_budget | …. Omitempty.
lookup_us	int	Lookup wall time (µs). Omitempty.
embed_us	int	Embedding wall time (µs). Omitempty.
serving_tier	string	Cross-tier provenance: l1 | l2 | l3 — which tier served the hit. Omitempty.
recall_exact	bool	Semantic hit: true = exact-KNN recall; false = ANN (a disclosed approximation). Omitempty.
recall_config	string	Semantic ANN hit: the recall backend’s config, e.g. hnsw(m=16,ef_search=200). Omitempty.
verified_active	bool	A verified-semantic policy governed this decision. Omitempty.
verified_calibrated	bool	A calibrated T* replaced the static threshold (licenses the saving). Omitempty.
verified_samples	int	Labeled observations the calibration considered. Omitempty.
verified_bound	float	Wilson lower bound on the correct-serve rate at T*. Omitempty.

saved / embed_cost (StageCost)

Both saved and embed_cost use the typed money shape — never a bare float. An unpriced value sets unpriced: true rather than a silent $0.

Field	Type	Meaning
usd	float	Dollar amount.
estimated	bool	The amount is an estimate.
unpriced	bool	The stage could not be priced; usd is not a real dollar amount.

usage

Normalized token accounting (core.Usage), reused directly by the ledger.

Field	Type	Meaning
input_tokens	int	Prompt tokens.
output_tokens	int	Completion tokens.
cache_read_tokens	int	Provider prompt-cache read tokens.
cache_write_tokens	int	Provider prompt-cache write tokens.
cache_write_detail	object	TTL split of the cache-write tokens: { ephemeral_5m_tokens, ephemeral_1h_tokens }. Omitted when absent.
reasoning_tokens	int	Reasoning/thinking tokens.
total_tokens	int	Total tokens.
source	string	Provenance of the counts: provider | estimated | absent | replay (a cache-served row).

cost

The priced outcome with provenance. Only ledger.CostFrom can construct a priced cost, so usd never carries a dollar figure without a resolved key.

Field	Type	Meaning
usd	float	Dollar cost. Not a real amount when unpriced is true.
pricing_key	string	The catalog key the price resolved under, e.g. anthropic/claude-haiku-4-5.
pricing_snapshot	string	Price provenance, source@date#sha7, e.g. litellm@2026-07-10#c3f1a2.
estimated	bool	The cost is an estimate.
would_usd	object	Per-tier shadow economics: {tier: usd}. null when not computed.
unpriced	bool	The pricing lookup missed. When true, aggregates must exclude-and-disclose the row, never sum its zero. Omitempty.
unpriced_reason	string	Typed miss reason: model_unknown | region_unknown | endpoint_unpriced | unit_missing. Omitempty.
region	string	Region the price resolved under, or the region attempted on a region_unknown miss. Omitempty.
would_unpriced	array	Tiers excluded from would_usd because their counterfactual could not be priced. Omitempty.

latency

Field	Type	Meaning
ttft_ms	int	Time to first token (ms).
total_ms	int	Total wall time (ms).
overhead_us	int	TokenTriage in-proxy overhead (µs).

outcome

Field	Type	Meaning
finish_reason	string	stop | length | tool_use | content_filter | error | budget_refused | limit_refused | "".
error	string	Upstream error string, truncated.
client_disconnect	bool	The client disconnected before completion.
signals	object	Turn-level outcome signals ({name: bool}).
oracle	object	Off-path oracle label {score, label}, filled async when sampled; else null.
shadow_grade	object	Shadow-judge verdict, joined by the reader from a companion row; else null. Omitempty.

mcp

Per-tool MCP attribution; [] before any tool ran. Each element:

Field	Type	Meaning
tool	string	Tool name.
server	string	MCP server name.
calls	int	Number of calls to this tool.
result_bytes	int	Total result bytes returned.
input_tokens_attributed	int	Input tokens attributed to this tool.
estimated	bool	Always true — the attribution is a char/4 estimate, never a provider figure.

dims

Business-dimension attribution — explicit headers only, never inferred from content. Omitempty. user/tenant/feature/tags come from x-tt-* headers; team/key are the server-stamped principal dims when governance resolves an authenticated key.

Field	Type	Meaning
user	string	From x-tt-user. Omitempty.
tenant	string	From x-tt-tenant. Omitempty.
feature	string	From x-tt-feature. Omitempty.
tags	object	Bounded free-form {k: v} from x-tt-tag-<k>. Omitempty.
team	string	Stamped principal dim: resolved team node. Omitempty.
key	string	Stamped principal dim: resolved kid. Omitempty.

units

Non-token billable units, present only on non-token endpoints (images/audio/…). When present, all four keys are emitted — it is a complete unit statement.

Field	Type	Meaning
images	int	Billable images.
seconds	float	Billable seconds.
characters	int	Billable characters.
requests	int	Billable request units.

disclosures

The row-level honesty ledger. Omitempty.

Field	Type	Meaning
translation	object	Cross-dialect translation loss. Written on every translated row (an empty {from,to} is itself the fact “translated, nothing lost”).

disclosures.translation

Field	Type	Meaning
from	string	Source dialect.
to	string	Target dialect.
dropped_params	array	Parameters dropped in translation. Omitempty.
approximations	array	Approximations made in translation. Omitempty.

Companion rows

The ledger stays append-only: async labels are appended as separate rows keyed on req_id, not mutated in place. Readers join them onto the primary row.

kind	Field	Meaning
oracle	oracle	Off-path oracle label {score, label}.
shadow_grade	grade	Shadow-judge verdict for a duplicated request.