how to structure jev state

State Is an Evidence Contract

TypeSafe describes state as the material shown to a panel of experts before asking them to judge. That analogy is useful only if the panel sees the evidence needed for the criterion and can tell what each field means. A raw agent transcript mixes user claims, tool results, instructions, retries and irrelevant history; a state projection assigns names, selects sources and makes missing evidence visible.

All questions in one request see the same state. If one question needs payment records and another needs a code diff, combining them may expose each to irrelevant context. Split calls by evidence boundary, not merely by endpoint convenience. The multiple-question guide explains dependency and batching tradeoffs.

From Transcript Dump to Decision State

A Structured Support-Evaluation State

Code computed the count and amount comparison because Jev is not a calculator. The user’s message remains visibly separate from verified facts and trusted policy. A question can ask whether the message requests reversal or whether the verified facts meet a semantic policy description; authorization and the refund action remain outside the model.

{
  "customer_request": {
    "message": "I was charged twice. Please reverse one charge.",
    "received_at": "2026-09-22T08:14:00Z"
  },
  "verified_account_facts": {
    "order_id": "A-104",
    "captured_charge_count": 2,
    "duplicate_amount_matches": true
  },
  "trusted_policy": {
    "duplicate_charge": "A verified duplicate captured charge is eligible for review."
  },
  "evidence_status": {
    "payment_lookup_succeeded": true,
    "policy_version": "refund-2026-09"
  }
}

State Can Contain Hostile Instructions

TypeSafe’s Jev 1.13 jaggedness page says adversarial content in state can steer the model. JSON field names do not create a security boundary. Labeling a field untrusted_user_text helps interpretation and auditing, but does not make prompt injection harmless. Apply deterministic allowlists, authorization and data validation before the call, and never place secrets in state merely because the model is asked to ignore them.

Keep trusted criteria in the question rather than concatenating them into an untrusted document. Test strings that ask the evaluator to ignore criteria, claim a false role or embed conflicting instructions. A semantic result can be one defense signal, never the only permission check; see Jev guardrails.

Use Ablation Tests to Justify Every Field

A field may raise aggregate accuracy by leaking the label—for example, a post-resolution status in an evaluator intended to predict pre-resolution risk. Document the timestamp and availability of every field at the decision point. The same projection code should run in offline evaluation and production.

1. Create a held-out labeled set containing ordinary, boundary and adversarial examples.
2. Run the smallest plausible state projection and record quality, calibration, tokens and latency.
3. Add one field group at a time; measure whether errors improve overall and by slice.
4. Remove each field group from the best candidate to detect dependence and leakage.
5. Reject fields that add cost, privacy exposure or brittleness without measured value.

Version State Semantics, Not Only JSON Schemas

Adding a field without changing the API schema can still change every probability. Treat that as an evaluator or policy release, replay labels and reconsider thresholds through Jev calibration. Store an evidence reference or hash so an audit can reconstruct what was judged without retaining unnecessary plaintext forever.

• Projection code version and source schema version.
• Field definitions, units, time basis and missing-value behavior.
• Trusted/untrusted provenance and redaction rules.
• Ordering and truncation behavior for arrays and conversations.
• Token distribution, missingness and observed outcome coverage by version.

Context Capacity Is Not a Quality Target

TypeSafe currently documents 64k total tokens and 32k for state plus the longest question, but also says irrelevant long state hurts Jev 1.13. Retrieve and filter first. For long records, select passages with deterministic rules or retrieval, preserve source identity and ask bounded questions over the shortlist.

If removing context changes answers substantially, investigate whether the criterion genuinely depends on it or the model is reacting to noise. The model card tracks current limits; Jev limitations covers the quality boundary.