Decision model
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.
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
decidectlclient 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 whoseis_commandis 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,DecisionUsageincrates/protocol/src/lib.rs; ts-rs bindings inpackages/protocol/src/generated/.DecisionAnswerValue::check_choiceis the reply guard;DecisionAnswerValue::marginis 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, theintentchoice with one criterion per verb plusbrain_turn, theis_command/complete/destructivenouls, two span questions).tools/verbs/questions_check.pybuilds one request per corpus row and lints the pack. - Shadow-only packs, asked by nothing live:
benchmarks/verbs/questions-continues.json(continues) andbenchmarks/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 (
readingwhenreading_openis 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.
decidectlwrites each body in the pack file’s key order (Pack::wire_order,crates/decidectl/src/wire.rs):{model, state, questions}; the state instate_schemaorder; 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 followstate.devices, thennone. A key the pack does not name goes after the named ones, alphabetically. This isquestions_check.request_of’s order. Thedecidectladapter 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|alphapicks it and records it.alphasorts every key. A scorecard line without the field counts aspack.decision_scorecard_weekly.pycounts a shadow row without theidentitykey asalphaand never pools it withpackrows. - 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):
choiceis one of the criteria keys (choice_not_in_criteria);- every
probabilitieskey is one of the criteria keys (probability_key_not_in_criteria); - every probability lies in [0, 1] (
probability_out_of_range); - the probabilities sum to 1 ± 0.02 (
probabilities_do_not_sum); - the argmax of
probabilitiesischoice(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
noullies 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, thenSIGKILLif still running;connectionClosedandinvalidResponseboth 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:404or a400naming the model, transport, the per-model cap,5xx/503/529,401/403,429after oneRetry-Afterwait, orcheck_replyrefusing the reply. A422or other4xxstops 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 typedSkipReasonand every abstain anAbstainReason. - The adapter. The
decidectlbinary is a JSON-lines adapter. It reads every model’s/readyonce at start (check_ready; the adapter’s first stdout line is{"ready": [...]}), and a model that is not ready starts with its breaker open. A404on/readymeans the server has no readiness gate (kev.serve), not that it is cold. - The identity. Each
ReadyReportcarriesidentity: {model, revision, quant, adapter, tokenizer, template, context_policy, abi} | null: what the server says it serves. It is read from the/readybody (anidentityobject or those fields at its top level), else from oneGET /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 samerun. kev.serve’srelease_date,backend+dtype,runandbasefill revision, quant, adapter and tokenizer; the quant isbackend/dtype, e.g.mlx/bfloat16, or either alone. Every field is present on the wire,nullwhen the server did not say. The whole isnullwhen the server is not ready or names none of them.tools/verbs/head_server.py’s/readyreports no identity. - The request.
decidectl::Packbuilds the request fromquestions-v2.jsonexactly asquestions_check.request_ofdoes, anddecide_withintakes a per-call budget. - Conformance.
decidectl::check_replyandcheck_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’smodelmust name the served identity, never an alias (local, a-latesttag) or an echo of the request. The cases arebenchmarks/fixtures/decision.v1/third-party/.
- The cascade.
-
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 topartials, default 2, each distinct) are asked of the cascade (default: kev.serve127.0.0.1:8871, then the frozen-encoder head127.0.0.1:8872; questionsis_command+complete). The one deadline is the session’s follow-up window, orfallback_deadline_mswhen the window is off. The outcome is traced asdecision_shadow: typed answers (a noul’s value, a choice’s pick and margin), every skip with its reason, the abstain reason,elapsed_msagainstbudget_ms, the deciding entry’sidentity(nullon 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 byidentityand never pools rows across a model or LoRA change.- The decision gate (
[decision_gate] enabled = trueby default,crates/voice_gateway/src/decision_gate.rs) is the one reader that decides. In the follow-up window, a final whose latest front-dooris_commandis under the lock’s threshold is refused as not addressed (follow_upverdict: "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 = trueby default): on a station with home verbs the request also carries up to five devices in view (the house’s live subjectshomectl actcan change, the ones the words name first, then the speaker’s room; labels fromhome_subjects_path, ahomectl subjectscapture, else derived from the id) anduser_room, and asks the pack’s home stage beside the configured questions, asquestions_check.request_ofbuilds it. The row’shomeblock traces what the answer maps to and runs nothing:action(thehomectl act <subject> <verb>it would run,executed: false),ask_back(the line an ambiguous answer would speak, labels only) orapproval(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 hadis_command≥ 0.5, or the partial’s words name a device in view (a label or room word thatdevices_in_viewranks 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 carriesquestions_n,home_stage_included,gate_reason(front_door_only,is_command,device_named,always,home_closed,no_home_store,no_devices,home_stage_off) andwarm(false). - Warm on arm (
warm_on_arm = trueby default): when the wake arms a request, one front-door ask (is_command,complete, empty partial) goes under its ownwarm_deadline_ms(10,000), so a cold model pages in. It is skipped when an ask or warm ended underwarm_skip_recent_s(60) ago. It is traced asdecision_shadow_warm(outcomedecided / abstained / skipped_recent,elapsed_ms,deadline_ms,warm: true), never asdecision_shadow, so the shadow’s summaries stay unbiased. - The mirror (
mirror = []by default): each entry named inmirroris asked on every ask beside the cascade, at the same time, with the same request andX-Request-Id, under its ownmirror_timeout_ms(3,000) and its entry’s breaker. It never changes the cascade’s answer. It is traced asdecision_shadow_mirror(mirror: true,entry,outcomedecided / failed / mirror_skipped / reused,answersorskip/reason,elapsed_ms,timeout_ms), never asdecision_shadow. Both rows carryrequest_id,turn_idandtranscript_sha(16 hex digits of the asked words’ SHA-256), sotools/telemetry/shadow_pair.pypairs the two answers. A mirror is dropped, never queued, when its breaker is open or the host’s load per core is at or overmirror_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_saidholds 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) andended_ms_agofrom the shipped-bytes playback horizon (0 while audible). It rides in the request only withstate_assistant_last_said = true(off by default). The trace row’sstate.assistant_last_saidalways 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 carriesverdict:partial(1-based),raw(would_route:is_command≥ 0.5 and the routing choice,intentor the cascade rootfamily, picked something other than its no-match; with itstopandp) andstable(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 leaststable_alone(0.85,alone), and only whileis_command’s hysteresis is armed (arms atstable_arm0.6, disarms understable_disarm0.4). - The avatar’s
motion_plan(motion_plan = trueby default; a frontend’smotion_plan_switchturns it off for its session; the shape and the trace row are inavatar-action.v1, “Who produces actions”). When a reply is done, one request asksmotion_plan(a choice over the operations the bound frontend declared with closed arguments, plusnone) and onemotion_plan_<verb>choice per operation with two or more names. They are built in code from the frontend’shello, 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) underfallback_deadline_ms, never the turn’s budget. Its pick acts only past the reply guard andmotion_plan_min_margin(0.394, frombenchmarks/verbs/motion-plan.v1.lock.json); otherwise a local lexicon picks. It is traced asavatar_motion_plan, never asdecision_shadow. No served model is trained on the question, so an enabledmotion_planacts as a shadow of the lexicon.
- The decision gate (
-
tools/verbs/head_server.py: the frozen-encoder router head on127.0.0.1:8872, the cascade’s fallback entry. It answers theis_command/completenouls and anychoicewhose criteria describe their options (the head is a set function over descriptions), and refuses anything else whole as400 api_usage_error(GET /infolists what it answers). It loads lazily: the first/readyor decide starts the load and is answered503until it finishes. One worker;X-Request-Idechoed;--encoder hashserves the wire with no model. -
The Admin approvals card’s
band/intent_p/danger_pslots show achoiceanswer’s margin and two nouls once a scorer fills them; nothing reads them to decide.bandandintent_pare empty. No model fillsdanger_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.