Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 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, “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.

Was this page helpful?