---
title: "Decision model"
description: "What the decision model returns for a turn: the typed-decision wire, one POST with typed questions in and one typed answer per question out (noul 0..1, choice with probabilities over the criteria keys, score); a choice is accepted only when it is a criteria key, the probabilities sum to 1 and their argmax is the choice. Every front-door router speaks it."
type: "living"
source: "docs/contracts/decision.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

decision.v1 — the typed-decision wire the gateway asks a local scorer over

- Status: **live, off by default**. The contract, its types, its goldens and the `decidectl` client are built. The
  gateway speaks it only when the operator turns on the decision shadow (`[decision_shadow] enabled`), against a
  LoRA on kev.serve and the frozen-encoder head. One thing routes on the answers: the decision gate
  (`[decision_gate]`) drops a follow-up-window final whose `is_command` is under the lock's threshold. Every other
  answer is traced only. Tier 3 of the verb resolver is still the Jaccard table (`verb_tier.rs`).
- Types: `DecisionRequest`, `DecisionQuestion`, `DecisionQuestionType`, `DecisionAnswer`, `DecisionAnswerValue`,
  `DecisionUsage` in `crates/protocol/src/lib.rs`; ts-rs bindings in `packages/protocol/src/generated/`.
  `DecisionAnswerValue::check_choice` is the reply guard; `DecisionAnswerValue::margin` is the confidence.
- Goldens: `benchmarks/fixtures/decision.v1/golden/{systemone-request,systemone-response,systemone-optional-instructions}.json`,
  typesafe-ai's contract fixtures (Apache-2.0), copied byte for byte and never executed.
- Vulpine's own request pack: `benchmarks/verbs/questions.json` (the state schema, the `intent` choice with one
  criterion per verb plus `brain_turn`, the `is_command` / `complete` / `destructive` nouls, two span questions).
  `tools/verbs/questions_check.py` builds one request per corpus row and lints the pack.
- Shadow-only packs, asked by nothing live: `benchmarks/verbs/questions-continues.json` (`continues`) and
  `benchmarks/verbs/questions-turnstate.json` (`will_resume`, `yields_floor`).

## The wire (System One)

One HTTP `POST` (jevmlx: `/v1/systemone`; openjev and Jev: the same body on their decide route), or one JSON line on a
subprocess pipe (below). The fixtures are the request and the answer; the tables restate them.

### Request

| field | type | rule |
|---|---|---|
| `model` | string | the scorer's model name (`jev-latest`, `local`); Vulpine's pack says `local` and the adapter substitutes the loaded model |
| `state` | string \| object | what the questions are about. The gateway sends an object: `utterance`, `final`, `silent_ms`, `playback`, `pending_card`, `follow_up_open`, the four gates (`reading_open`, `home_undo_open`, `home_open`, `dictation_open`), `feeds_listed` (true only inside the 90-second window after a pi_feeds unread receipt, and sent only to a pack whose state schema names it — v3; absent means false, so the live v2 wire never carries it), and, when the home stage runs, `devices` (the lines in view) and `user_room`; optionally `assistant_last_said` (an object of text and ended_ms_ago: Vulpine's own last spoken line and how many milliseconds ago its speakers fell silent — absent when Vulpine said nothing recent) |
| `questions` | map id → question | at least one; ids are the caller's |
| `questions.*.type` | `noul` \| `choice` \| `score` | a 0..1 read of one proposition; one of the criteria keys; a position on an ordered legend |
| `questions.*.instructions` | string \| object, optional | a sentence, or Vulpine's `{question, focus}`; absent means "the id is the question" (fixture `systemone-optional-instructions`) |
| `questions.*.criteria` | `choice`: map option → description \| null; `score`: array of legend strings; `noul`: absent | **the options are the criteria keys and nothing else**; a description may be null |

Rules the pack keeps (TypeSafe's, in `questions.json` `_rules`):

- every choice carries a no-match option (`brain_turn`);
- ids never reach the model (only instructions and criteria do);
- standing facts go in the instructions, not the state;
- a gated option the state closes is CUT from the criteria before the ask (`reading` when
  `reading_open` is false), never left in to be "unlikely".

A gate whose key the state does not carry is CLOSED, in `questions_check.request_of`
(`state.get(gate, False)`) and in decidectl's `Pack::request` alike.

### Order is part of the question

The order of a `choice` question's options is part of the question, and so is the order of the questions and of the
state's keys: a model reads the body as text. A body sent in another order asks a different question from the one a
receipt measured.

- **The wire sends pack order.** `decidectl` writes each body in the pack file's key order (`Pack::wire_order`,
  `crates/decidectl/src/wire.rs`): `{model, state, questions}`; the state in `state_schema` order; the questions in
  pack order, each as `{type, instructions, criteria}` with the options and their descriptions as the pack lists
  them; `home_device`'s options follow `state.devices`, then `none`. A key the pack does not name goes after the
  named ones, alphabetically. This is `questions_check.request_of`'s order. The `decidectl` adapter forwards each
  stdin line in the key order the caller wrote.
- **The receipts say which order was sent**: `criteria_order: "pack" | "alpha"`. `scorer_driver.py
  --criteria-order pack|alpha` picks it and records it. `alpha` sorts every key. A scorecard line without the field
  counts as `pack`. `decision_scorecard_weekly.py` counts a shadow row without the `identity` key as `alpha` and
  never pools it with `pack` rows.
- Reorder a pack file and you have asked a new question, so the receipts start again.

### Answer

| field | type | rule |
|---|---|---|
| `model` | string | what actually answered |
| `answers` | map id → answer | one per question asked, same ids |
| `answers.*.type` | the question's type | echoed |
| `noul` answer | `noul: f64` in [0, 1] | ≈ 0.5 is uncertainty, not a verdict either way |
| `choice` answer | `choice: string`, `probabilities: map option → f64`, `confidence?: f64` | the guard below |
| `score` answer | `score: f64`, `legend: map index → string`, `probabilities: map index → f64`, `confidence?: f64` | the legend indexes the criteria array |
| `usage` | `{input_tokens, output_tokens}`, optional | jevmlx also rides `queue_depth` and `queue_wait_ms` per response; the types ignore extra members, the goldens forbid dropping any |

### The reply-membership guard

A `choice` answer is accepted only when (`DecisionAnswerValue::check_choice`, mirrored in
`scorer_driver.guard`):

1. `choice` is one of the criteria keys (`choice_not_in_criteria`);
2. every `probabilities` key is one of the criteria keys (`probability_key_not_in_criteria`);
3. every probability lies in [0, 1] (`probability_out_of_range`);
4. the probabilities sum to 1 ± 0.02 (`probabilities_do_not_sum`);
5. the argmax of `probabilities` is `choice` (`argmax_is_not_choice`).

Around it, the reply guard (from yunuspi's Jev client; `DecisionAnswer::check_reply`
runs all of it, mirrored in `scorer_driver.guard_reply` / `guarded_nouls`):

- the reply answers every question asked and none it was not asked (`question_unanswered`,
  `answer_for_unasked_question`; `DecisionAnswer::check_complete_reply`);
- every answer echoes its question's `type` — a missing type is a mismatch
  (`answer_type_mismatch`; `DecisionAnswerValue::check_answer_type`);
- a `noul` lies in [0, 1] and is not NaN (`noul_out_of_range`; `DecisionAnswerValue::check_noul`).

A `score` answer has only its type checked by `check_reply`. `scorer_driver.guard_score` applies a minimal guard: the
score lies in [0, len(legend) − 1], `legend` restates the criteria array index for index (`legend_not_criteria`),
every probability key is a legend index (`probability_key_not_in_legend`) with a value in [0, 1], and the map sums to
1 ± 0.02. No relation between `score` and `probabilities` is checked. Vulpine's one score question, `operator_tone`, is
in the pack's `_ask_when_named` list and is asked only when a caller names it.

`benchmarks/verbs/questions-v3.json` is v2 plus two ask-when-named questions for the first-party tool arm:
`needs_tool` (a noul) and `tool_family` (a choice over `benchmarks/verbs/tools/seeds.toml`'s families plus `none`). A
whole-pack v3 request is byte-identical to v2's, and the wire is unchanged. Nothing routes on the two questions.
`decision_scorecard.py --tool-questions` scores them.

v3 also carries the corpus verb `feeds_read`, a family leaf gated by the state key `feeds_listed`. The gateway's
decision shadow sets `feeds_listed: true` while the ordinal grammar's own gate is up and its listing is inside
`LISTING_WINDOW` (`ws/feeds_read.rs`), and leaves it absent otherwise. decidectl drops the key for a pack whose
`state_schema` does not name it, so the live v2 request bytes are unchanged.

`suite_scorer.py` (the served wire) abstains the whole row on a gap or a type mismatch, and only the noul on an
out-of-range noul (`guard.noul_rejected` in the receipt). `scorer_driver.py` applies only the noul range, because its
in-process providers neither echo `type` nor answer the span questions.

A refused reply is an ABSTAIN for that question: the row goes to the brain as if the scorer had said `brain_turn`,
and is counted in the receipt's `guard.rejected`. A scorer that answers a `choice` with no probabilities passes the
guard with no confidence. It can route only at a threshold of 0, which the lock never issues, so it is a shadow.

## ONE confidence — the margin

Vulpine reads one number off a `choice` answer: **the margin, top1 − top2 of `probabilities`** (a lone option's margin
is its probability). Not the reply's own `confidence`, not the top probability alone. The margin says how alone the
winner is, which is what routing needs: a top probability of 0.6 with a runner-up at 0.55 is a coin toss.

Under the cascade pack (`benchmarks/verbs/questions-v2.json`: P(verb) = P(family) × P(verb | family), one `none`
collecting every none; `scorer_driver.compose_cascade`) the margin is read on the COMPOSED distribution, never on a
branch question alone. Every receipt reports open-phrasing recall at the 0.90 / 0.95 precision floors for both
`top_prob` and `margin` (`open_recall.measures`; `scorer_table.py --view open`). The acceptance threshold is never a
constant in code: it is the lock's (`tools/verbs/lock.py`, `benchmarks/results/verb-decisions.lock.json`).


## Error taxonomy

The adapters translate server errors into these outcomes; none of them is a verb.

| status | meaning | Vulpine's outcome |
|---|---|---|
| `422` + FastAPI validation list | a field of the wrong shape | a bug in the request builder — refuse the row, log the list, never retry |
| `400` plain text | a question the server cannot ask (no options, too many, an unknown type or model, `api_usage_error`) | same: the pack is wrong for this scorer |
| `401` / `403` `{detail: {error_type, message}}` | auth | the scorer is down for the session; tier 3 stays shadow |
| `413` (jevmlx) | more rows or prompt tokens than `--max-rows` / `--max-prompt-tokens`, before any model work | split or shorten; a single verb row never hits it |
| `429` + `Retry-After` | rate limit / admission queue full | wait `Retry-After` (jevmlx: a fixed 2 s), retry a bounded number of times, then abstain |
| `529` | overloaded (`OPENJEV_MAX_QUEUE` 512 decisions waiting) | abstain now; the voice turn does not wait on a queue |
| `500` | the server's own fault (openjev answers `422` where Jev answers `500` for a body nested a thousand deep) | abstain, count it |

A voice turn has one budget: the follow-up window. An abstain is always cheaper than a late answer, so every error
path above ends in "the row goes to the brain", never in a second wait.

## Backpressure (jevmlx's shape)

`jevmlx serve`: **one Metal GPU, one serial worker, a bounded admission queue in front** (`--queue-size`, default
16). Beyond the queue plus the in-flight request the server answers `429` with `Retry-After: 2` and a body
`{error: "admission queue full", queue_depth, queue_capacity, retry_after_s}`. `/health` is process liveness (always
200, carries `queue_depth`, `queue_capacity`, `worker_alive`); `/ready` is the gate to ask. The client's
`X-Request-Id` is echoed. A disconnected client's queued entry is dropped from the depth; an in-flight one is not.

Vulpine's rule: the gateway asks with the turn id as `X-Request-Id`, reads `/ready` once at adapter start (never per
turn), and treats a `429` inside the follow-up window as an abstain after one retry. The TTS server shares the GPU,
so a scorer that queues behind a render answers after the turn closed.

## Subprocess rules (pastewhat's `EngineBridge`)

A scorer that runs as a child process (laya-mlx, or jevmlx in-process) uses pastewhat's bridge, rule for rule
(`Sources/PasteWhat/EngineBridge.swift`):

- the worker is launched unbuffered (`python -u worker …`) with stdin and stdout as pipes and
  **stderr discarded at the OS boundary** — it can neither fill a pipe nor leak the clipboard
  (for Vulpine: the utterance) into a log;
- one JSON line per request in, one per answer out; a **generation id** tags each request and
  an answer for another generation is dropped as `responseMismatch`, never applied;
- a per-request **timeout task** fails every pending request (`timeout`), closes the process,
  and the next request starts a fresh one — the bridge never waits on a hung worker twice;
- **oversized messages** (request or answer over the limit) are refused before the pipe;
- close is `terminate`, then `SIGKILL` if still running; `connectionClosed` and
  `invalidResponse` both mean "restart on the next request", not "retry now";
- the errors are a closed enum (`invalidConfiguration`, `missingWorker`, `launchFailed`,
  `connectionClosed`, `invalidResponse`, `responseMismatch`, `oversizedMessage`, `timeout`),
  each with one operator-facing sentence.


## Where Vulpine speaks it

- `crates/decidectl`: the client every caller goes through.
  - **The cascade.** `{name, url, model}` entries sit behind ONE deadline. The next model is asked only when this
    one is rejected: `404` or a `400` naming the model, transport, the per-model cap, `5xx` / `503` / `529`,
    `401` / `403`, `429` after one `Retry-After` wait, or `check_reply` refusing the reply. A `422` or other `4xx`
    stops the cascade (the request builder is wrong). A fault opens that model's breaker for five minutes, then one
    probe reopens it. Identical in-flight calls share one request. Every skip is a typed `SkipReason` and every
    abstain an `AbstainReason`.
  - **The adapter.** The `decidectl` binary is a JSON-lines adapter. It reads every model's `/ready` once at start
    (`check_ready`; the adapter's first stdout line is `{"ready": [...]}`), and a model that is not ready starts with
    its breaker open. A `404` on `/ready` means the server has no readiness gate (kev.serve), not that it is cold.
  - **The identity.** Each `ReadyReport` carries `identity: {model, revision, quant, adapter, tokenizer, template,
    context_policy, abi} | null`: what the server says it serves. It is read from the `/ready` body (an `identity`
    object or those fields at its top level), else from one `GET /v1/models` (OpenAI's `{data: [{id}]}` or
    kev.serve's `{models: [{name}]}`). From that list it takes the entry named as the cascade's model, the only
    entry, or the first when every entry serves the same `run`. kev.serve's `release_date`, `backend` + `dtype`,
    `run` and `base` fill revision, quant, adapter and tokenizer; the quant is `backend/dtype`, e.g.
    `mlx/bfloat16`, or either alone. Every field is present on the wire, `null` when the server did not say. The
    whole is `null` when the server is not ready or names none of them. `tools/verbs/head_server.py`'s `/ready`
    reports no identity.
  - **The request.** `decidectl::Pack` builds the request from `questions-v2.json` exactly as
    `questions_check.request_of` does, and `decide_within` takes a per-call budget.
  - **Conformance.** `decidectl::check_reply` and `check_request` (offline, never on the cascade) name every way a
    server's reply or limits leave this page, each marked tolerate or refuse. A reply's `model` must name the
    served identity, never an alias (`local`, a `-latest` tag) or an echo of the request. The cases are
    `benchmarks/fixtures/decision.v1/third-party/`.
- The gateway's decision shadow (`[decision_shadow] enabled = true`, off by default,
  `crates/voice_gateway/src/decision_shadow.rs`). The recognizer's first non-empty partials of each utterance (up to
  `partials`, default 2, each distinct) are asked of the cascade (default: kev.serve `127.0.0.1:8871`, then the
  frozen-encoder head `127.0.0.1:8872`; questions `is_command` + `complete`). The one deadline is the session's
  follow-up window, or `fallback_deadline_ms` when the window is off. The outcome is traced as `decision_shadow`:
  typed answers (a noul's value, a choice's pick and margin), every skip with its reason, the abstain reason,
  `elapsed_ms` against `budget_ms`, the deciding entry's `identity` (`null` on an abstain or when the server said
  nothing), and the utterance's length, never its words. Only the decision gate (next) reads it to decide. The weekly scorecard groups
  rows by `identity` and never pools rows across a model or LoRA change.
  - The decision gate (`[decision_gate] enabled = true` by default, `crates/voice_gateway/src/decision_gate.rs`) is
    the one reader that decides. In the follow-up window, a final whose latest front-door `is_command` is under the
    lock's threshold is refused as not addressed (`follow_up` `verdict: "refused"`, `reason: "decision_gate"`)
    instead of going to the brain. It reads the shadow's answer and never waits. It abstains to the brain path when
    the shadow is off, no answer is in, the answer came from a model other than the lock's, or the lock is missing.
  - Home stage (`home_stage = true` by default): on a station with home verbs the request also carries up to five
    devices in view (the house's live subjects `homectl act` can change, the ones the words name first, then the
    speaker's room; labels from `home_subjects_path`, a `homectl subjects` capture, else derived from the id) and
    `user_room`, and asks the pack's home stage beside the configured questions, as `questions_check.request_of`
    builds it. The row's `home` block traces what the answer maps to and runs nothing: `action` (the
    `homectl act <subject> <verb>` it would run, `executed: false`), `ask_back` (the line an ambiguous answer would
    speak, labels only) or `approval` (`confirm_advised`, advice for the approval policy).
  - The ask cut (`home_stage_gate = "is_command_or_device"` by default): the home stage joins an ask only when this
    utterance's previous front-door answer had `is_command` ≥ 0.5, or the partial's words name a device in view (a
    label or room word that `devices_in_view` ranks by; the room fallback does not count). Otherwise the ask is the
    2-question front door, about 200 ms against about 1 s with the stage. `home_stage_gate = "always"` joins the
    stage to every ask. Every row carries `questions_n`, `home_stage_included`, `gate_reason` (`front_door_only`,
    `is_command`, `device_named`, `always`, `home_closed`, `no_home_store`, `no_devices`, `home_stage_off`) and
    `warm` (false).
  - Warm on arm (`warm_on_arm = true` by default): when the wake arms a request, one front-door ask (`is_command`,
    `complete`, empty partial) goes under its own `warm_deadline_ms` (10,000), so a cold model pages in. It is
    skipped when an ask or warm ended under `warm_skip_recent_s` (60) ago. It is traced as `decision_shadow_warm`
    (`outcome` decided / abstained / skipped_recent, `elapsed_ms`, `deadline_ms`, `warm: true`), never as
    `decision_shadow`, so the shadow's summaries stay unbiased.
  - The mirror (`mirror = []` by default): each entry named in `mirror` is asked on every ask beside the cascade, at
    the same time, with the same request and `X-Request-Id`, under its own `mirror_timeout_ms` (3,000) and its
    entry's breaker. It never changes the cascade's answer. It is traced as `decision_shadow_mirror` (`mirror: true`,
    `entry`, `outcome` decided / failed / mirror_skipped / reused, `answers` or `skip` / `reason`, `elapsed_ms`,
    `timeout_ms`), never as `decision_shadow`. Both rows carry `request_id`, `turn_id` and `transcript_sha` (16 hex
    digits of the asked words' SHA-256), so `tools/telemetry/shadow_pair.py` pairs the two answers. A mirror is
    dropped, never queued, when its breaker is open or the host's load per core is at or over
    `mirror_max_load_per_core` (0.35; `reason: host_load`). An entry the cascade reaches anyway is asked once: the
    cascade awaits the mirror's request (`outcome: reused`, `mirror: "reused"`, no answers on the mirror row).
  - Vulpine's own words: `assistant_last_said` holds the last line handed to the TTS engine while it is audible or
    within the echo gate's 20 s lookback (its tail, at most 280 characters, hex-looking tokens dropped) and
    `ended_ms_ago` from the shipped-bytes playback horizon (0 while audible). It rides in the request only with
    `state_assistant_last_said = true` (off by default). The trace row's `state.assistant_last_said` always carries
    its length, age and whether it was sent, never the words.
  - The stable verdict (shapeshift's two-partial rule): up to `partials` (default 2) distinct partials of an
    utterance are asked, and each row carries `verdict`: `partial` (1-based), `raw` (`would_route`: `is_command`
    ≥ 0.5 and the routing choice, `intent` or the cascade root `family`, picked something other than its no-match;
    with its `top` and `p`) and `stable` (`would_route`, `armed`, `reason`). A raw route is stable only when the same
    top also won the previous partial (`agreed`) or its p is at least `stable_alone` (0.85, `alone`), and only while
    `is_command`'s hysteresis is armed (arms at `stable_arm` 0.6, disarms under `stable_disarm` 0.4).
  - The avatar's `motion_plan` (`motion_plan = true` by default; a frontend's `motion_plan_switch` turns it off for
    its session; the shape and the trace row are in [`avatar-action.v1`](/docs/contracts/avatar-action.v1), "Who produces
    actions"). When a reply is done, one request asks `motion_plan` (a choice over the operations the bound frontend
    declared with closed arguments, plus `none`) and one `motion_plan_<verb>` choice per operation with two or more
    names. They are built in code from the frontend's `hello`, because the criteria are the rig's names. The state
    is `{reply, phase}`. The request goes in the cascade's wire order (its question ids follow alphabetically) under
    `fallback_deadline_ms`, never the turn's budget. Its pick acts only past the reply guard and
    `motion_plan_min_margin` (0.394, from `benchmarks/verbs/motion-plan.v1.lock.json`); otherwise a local lexicon
    picks. It is traced as `avatar_motion_plan`, never as `decision_shadow`. No served model is trained on the
    question, so an enabled `motion_plan` acts as a shadow of the lexicon.
- `tools/verbs/head_server.py`: the frozen-encoder router head on `127.0.0.1:8872`, the cascade's fallback entry. It
  answers the `is_command` / `complete` nouls and any `choice` whose criteria describe their options (the head is a
  set function over descriptions), and refuses anything else whole as `400 api_usage_error` (`GET /info` lists what
  it answers). It loads lazily: the first `/ready` or decide starts the load and is answered `503` until it
  finishes. One worker; `X-Request-Id` echoed; `--encoder hash` serves the wire with no model.


- The Admin approvals card's `band` / `intent_p` / `danger_p` slots show a `choice` answer's margin and two nouls
  once a scorer fills them; nothing reads them to decide. `band` and `intent_p` are empty. No model fills
  `danger_p`: the approval queue's typed exec-risk list sets it (1.0 DANGER, 0.5 CAUTION).

### Which read gates the commit on the partial

Today one read routes: `is_command` (is this addressed to Vulpine at all), in the follow-up window only, through the
decision gate above. `complete` and the verb read are traced and decide nothing. Its bar comes from the receipt's
thresholds at the precision floors `open_recall` uses (0.90 and 0.95), never hand-picked, and the lock pins it as it
pins the margin.


