Jev foundations: typed decisions outside text generation

What this teaches

Jev loses its advantage when it is treated as a source of plausible prose. TypeSafe documents position it as the flagship System One model: it receives state and a typed question, then returns a structured answer and probability distribution that software can consume. The goal is not to replace conversation. It is to turn the small semantic judgments missing from conventional programs into explicit components.

In a support system, code can determine a contractual plan through string matching, while a decision component receives only the ambiguity that needs interpretation: urgency or the closest intent among a known set. Its result selects the next function, search, or review queue; it is not text pasted into a UI. That boundary makes results reusable, comparable, and auditable.

1. 1Observed state
2. 2candidates enumerated by code
3. 3narrow typed question

1. 1Narrow question
2. 2distribution and answer
3. 3code checks threshold and authority
4. 4execute / hold / human review

Mental model: the model supplies meaning; code owns responsibility

State is the named JSON facts required for the decision: document text, ticket history, candidate list, current policy, and target IDs. A candidate absent from state cannot be selected. Generate candidates deterministically first. Search, regular expressions, database authorization, inventory reads, and date arithmetic remain ordinary code; there is no reason to ask a model to rediscover them.

Ask one semantic question at a time. “Does this document request a refund?” and “what amount is requested?” are separate. Extract amount candidates with a deterministic parser before asking a choice question. Routing an incident to safety, quality, or logistics from a bounded set is a natural semantic classification.

Types guarantee an interface, not truth. Missing facts, ambiguous criteria, stale policy, and model errors remain possible. Never wire model output directly to execution: verify IDs, authority, limits, current state, and idempotency in code, then automate only reversible low-risk work.

A minimal design procedure

1. Write the final choice made by an API or screen in one sentence, such as “route this inquiry to one of six existing handlers.”
2. Fix options in a code enum and include unknown or needs_review from the start. Do not let a language model invent candidates.
3. Describe each option, exclusion, and boundary case in the criteria. An implementation ID does not communicate meaning to a model.
4. Mark every state field as observed fact, user input, or inference. Mixing inference into facts makes errors impossible to trace.
5. Save answer, distribution, input and question versions, and downstream outcome. Minimize personal data and keep API keys server-side.

Benefits and trade-offs

Free-form generation often creates parsing, out-of-set rejection, and failure-diagnosis work. Small Choice, Score, or Noul questions establish an application contract first, while code can change weights and thresholds. Independent questions can share one state and run in parallel; the official parallel questions cookbook demonstrates measurement, not a promise about your cost, latency, or accuracy.

The cost is writing candidates and criteria. Missing options cannot be selected; over-splitting loses relationships, while broad questions cannot be evaluated. Open-ended creation and long explanations often fit a generative model or human editor better. Restricting Jev to decisions is a design choice that shrinks the failure surface.

Exercise: a safe reading-note classifier

With thirty fictional local notes, design a classifier that chooses research, implementation, idea, or needs_review. Initially change only a display tag; do not execute anything. Have people label ten cases per tag and deliberately include out-of-set, ambiguous, and underspecified notes. Fix inputs and the question before using confidence, then record whether each error came from candidates, criteria, state, or semantic interpretation.

Avoid invented APIs: executable offline boundary code

An imaginary SDK snippet makes learners implement an API that may not exist. Keep the public JavaScript SDK type reference as the source of live integration details, and teach code that runs offline without a key. The example below does not replace model inference; it tests the candidate validation and side-effect boundary required around it.

const candidates = ["research", "implementation", "idea", "needs_review"] as const;
type Label = (typeof candidates)[number];
type ChoiceFixture = { value: string; probabilities: Record<string, number>; confidence: number };
function toDisplayTag(fixture: ChoiceFixture): Label {
  if (!(candidates as readonly string[]).includes(fixture.value)) {
    throw new Error("invalid Choice label");
  }
  return fixture.value as Label;
}
console.assert(toDisplayTag({ value: "research", probabilities: {}, confidence: 0.9 }) === "research");
// A fixture with value "invented" must throw; a real `needs_review` value remains valid.

Input limits, retention, consent, and access control are separate requirements. If candidates differ between a code tuple and UI, typed output does not prevent harm. Preserve needs_review with its reason and input version so people can decide whether to add a candidate or revise the question. Current public TypeSafe materials call the yes/no primitive Noul; record publication and access dates separately when terminology changes.

Building evaluation data

Use one CSV or JSONL row per case with id, input_text, expected_label, allowed_labels, risk, annotator_a, annotator_b, and adjudicated_label. Keep disagreements as ambiguity rather than deleting them. This data evaluates question, candidates, and operation; it is not automatically training data. Split by time or author and hash-check that a source document and its summary do not land in different splits.

Prepare failures first: a future plan described as though implemented, a research note containing implementation TODOs, and an empty body with only a title. Do not change labels after seeing output; that leaks evaluation. Preserve new holdout cases for every change rather than declaring progress from an old score alone.

2024–2026 context: structured output is an interface, not a verdict

OpenAI’s Structured Outputs announcement (2024-08-06) made schema conformance an explicit API goal. A valid enum only proves that a response fits the interface: it does not establish that the chosen label is true, complete, authorized, or based on current evidence. RouteLLM (submitted 2024-06-26) frames routing as a learned cost/quality preference problem; it is history for evaluation design, not a reason to add an automatic provider substitution.

TypeSafe’s 2026-09-15 System One/Jev post describes early access, RLCD, and parallel sampling as vendor claims. Turn those claims into a bounded exercise: freeze four candidate labels, create adversarial holdouts with missing or conflicting state, and compare the typed decision with a deterministic rule and blinded human label. The code must reject an out-of-contract label. needs_review is valid only when actually returned as an enumerated choice; it is not a silent substitute for malformed output.

The 2026-09-18 LocalLLaMA thread discusses architecture versus interface. It is unverified community debate, not evidence of architectural identity or novelty. Recent boundary: the September post was checked on 2026-10-04; no account availability, benchmark, or independent performance result was measured here.

Put deterministic facts before semantic judgment

Make a boundary table before writing the question. A process exit code, a signed role, a current publication permission, an existing FAQ ID, and a quota are code-owned facts: validate them before Jev and fail with a named cause when absent. “Which of these allowed FAQ intents best matches this ambiguous wording?” is the narrower Jev question. User-supplied instructions cannot grant publishing permission, change a role, add a candidate, or override a deterministic refusal.

In the offline lab, test an invented label as an invalid-contract fixture and assert that it throws. Test needs_review separately as a valid enumerated output. Do not map the first to the second: a silent substitute hides a provider/schema mismatch and makes a later incident impossible to diagnose. Record candidate-tuple version, question version, state hash, and policy result with every held item. A reviewer can then repair candidate coverage without granting the model a new capability.