@evoclock/pi-agentic-driver 0.9.2 → 0.9.3

package/README.md

@@ -53,6 +53,8 @@ proofs for agentic workflows.
 | `agentic_kanban_board_update` | Moves, closes, flags, edits, or removes cards on the board, always recording who authorized the change. | shipped |
 | `agentic_kanban_board_dispatch` | Claims an eligible board card for automated contained work and creates its assignment envelope. | shipped |
 | `agentic_kanban_pulse` | Checks for ready work and available capacity, then starts assignments under the board policy. | shipped |
+| Router | Capacity/policy routing for Board Pulse: seats with scope statements, tunable policy values, and a binding dispatch gate. | shipped |
+| Janus (bundled service) | Local Jev evaluation service on loopback: semantic ranking, the dispatch-gate judgment, redaction before every external call. See `janus/README.md`. | shipped |
 
 **Status: active development and testing.** Each extension ships only after
 it passes fixture-based acceptance, native tests, live-session checks, and
@@ -102,6 +104,82 @@ only, not a runtime dependency).
 - **inventory refresh.** Git-aware codebase inventory regeneration with
   verification receipts, so prior-art matching stays honest.
 
+<details>
+<summary><strong>router, capacity/policy routing with a binding dispatch gate</strong> <em>(released, 0.9.2)</em></summary>
+
+Board Pulse selects a route seat through the capacity/policy router. The
+router reads a closed configuration file and a local-first SQLite file for
+operational state (reservations, observations, route-decision audit).
+
+Two router features call **Janus** — a separate local service, bundled under
+`janus/`, that is the only component allowed to talk to the TypeSafe Jev
+models:
+
+- **Semantic ranking** (optional): Janus ranks up to eight eligible seats;
+  on any Janus failure the router falls back to preference order.
+- **The binding dispatch gate**: before a task is claimed, Janus judges
+  whether the task fits the selected seat. No verdict, no dispatch — the
+  gate fails closed when Janus is unreachable.
+
+Janus binds loopback only (`127.0.0.1:8787`), reads its API key from the
+macOS Keychain at runtime, redacts state before every external call, and
+coalesces identical requests. See `janus/README.md` for the endpoint
+contract, Keychain provisioning, and configuration.
+
+- **Repository defaults** ship at `.agentic-driver/router.defaults.json`. The
+template contains no accounts and one disabled placeholder seat, so it loads
+out of the box and schedules nothing until you enable a real seat.
+- **User profile (precedence over defaults):**
+`~/.config/agentic-driver/router/profile.json`, or the path in the
+`AGENTIC_DRIVER_ROUTER_PROFILE` environment variable. A profile section
+replaces the matching defaults section wholesale; the merged config must
+validate or the router refuses to produce decisions (fails closed).
+- **Operational state:** `~/.local/share/agentic-driver/router/state.db`, or
+`AGENTIC_DRIVER_ROUTER_DB`. This store is operational state only. The
+authenticated claims file and the board writer remain the only dispatch
+authority; the system repairs SQLite from them, never the reverse.
+- **Runtime requirement:** the operational store uses the built-in
+`node:sqlite` module. You need Node.js 22.5 or newer.
+
+<details>
+<summary><strong>Tunable configuration values</strong> <em>(all keys required, defaults are conservative starting values)</em></summary>
+
+Every numeric policy in the router is a configuration key — never a
+constant in code. All keys are **required**. The repository defaults below
+are conservative starting values. Your profile overrides them. A missing key
+is a configuration validation failure: the router fails closed rather than
+guess. Changing a value participates in the configuration digest, so cached
+routing decisions computed under the old values no longer apply.
+
+| Section | Key | Default | What it controls |
+|---|---|---|---|
+| `eligibility.reserve` | `floorPercent` | 40 | Share of every quota window kept in reserve (per account, per window). Headroom for an unexpected burst and your next interactive session, without idling the account. |
+| `eligibility.reserve` | `scope` | `account-window` | How widely the reserve floor applies (per account per window at launch). |
+| `eligibility.reserve` | `coldStartFraction` | 0.25 | Consumption assumed for a seat with too little history: deliberately generous, so a mis-estimate fails eligibility instead of draining the account. |
+| `eligibility.reserve` | `estimateSamples` | 20 | How many recent dispatches the consumption estimate averages: enough to smooth outliers, quick enough to track a model change. |
+| `eligibility.reserve` | `estimateMinSamples` | 5 | Below this many observations, the estimator treats the average as noise and uses the cold-start value instead. |
+| `eligibility.reserve` | `estimateOutlierSigma` | 3 | Outlier cut for the estimate: one unusually slow dispatch cannot inflate the average, real tail latency is kept. |
+| `eligibility.reserve` | `ownerInteractiveOverride` | false | Whether your own interactive dispatches bypass the reserve rule (they do not, at launch). |
+| `ranking` | `janusUrl` | `http://127.0.0.1:8787` | The local Janus evaluation service endpoint used for semantic ranking. |
+| `ranking` | `maxCandidates` | 8 | The router ranks at most eight eligible seats per request; preference order trims the list first. |
+| `ranking` | `fallback` | `preference-order` | What happens when ranking is unavailable: dispatch falls back to your preference order and never blocks. |
+| `gate` | `threshold` | 0.9 | The dispatch gate's confidence threshold. A task is only dispatched when the evaluation clears it. Lower it only with evidence from your own audit log. |
+| `gate` | `timeoutMs` | 8000 | How long the gate waits for an evaluation. On timeout there is no verdict, and the gate blocks dispatch (fail closed). |
+| `gate` | `requestBudgetTokens` | 30000 | Maximum size of a gate evaluation request. Normal evaluations use under a thousand tokens. |
+| seat record | `maxConcurrency` | 4 | How many workers one seat may run at once. The default suits a typical single machine or hosted seat. Tune it per seat: a cluster takes more, a constrained subscription endpoint may take less. |
+| automation policy | `maxConcurrent` | 4 | How many workers may run at once across all seats. The default is a conservative start. Tune it to the capacity you actually have, and raise it when you add seats or hardware. |
+
+Seats are named for infrastructure, not models: `dgx-spark`,
+`dgx-spark-cluster`, `mac-studio`, `mac-studio-cluster`, `strix-halo`,
+`strix-halo-cluster`, `merge-gateway-worker`. The model is a mutable field on
+the seat, so changing models never renumbers your configuration. Each seat
+also carries `scopeStatements`: plain-language descriptions of what the seat
+is for. The dispatch gate reads them when judging whether a task fits.
+
+</details>
+
+</details>
+
 ## Multi-agent communication
 
 *Extensions for controlled coordination between agents.*
@@ -580,60 +658,6 @@ The package includes the `herdr-communication.ts`, `herdr-lifecycle.ts`, and
 disable individual resources from an installed package. You are not required
 to use every extension.
 
-## Router configuration
-
-Board Pulse selects a route seat through the capacity/policy router. The
-router reads a closed configuration file and a local-first SQLite file for
-operational state (reservations, observations, route-decision audit).
-
-- **Repository defaults** ship at `.agentic-driver/router.defaults.json`. The
-template contains no accounts and one disabled placeholder seat, so it loads
-out of the box and schedules nothing until you enable a real seat.
-- **User profile (precedence over defaults):**
-`~/.config/agentic-driver/router/profile.json`, or the path in the
-`AGENTIC_DRIVER_ROUTER_PROFILE` environment variable. A profile section
-replaces the matching defaults section wholesale; the merged config must
-validate or the router refuses to produce decisions (fails closed).
-- **Operational state:** `~/.local/share/agentic-driver/router/state.db`, or
-`AGENTIC_DRIVER_ROUTER_DB`. This store is operational state only. The
-authenticated claims file and the board writer remain the only dispatch
-authority, and SQLite is repaired from them, never the reverse.
-- **Runtime requirement:** the operational store uses the built-in
-`node:sqlite` module. Node.js 22.5 or newer is required.
-
-### Tunable configuration values
-
-Every numeric policy in the router is a configuration key — never a
-constant in code. All keys are **required**. The repository defaults below
-are conservative starting values. Your profile overrides them. A missing key
-is a configuration validation failure: the router fails closed rather than
-guess. Changing a value participates in the configuration digest, so cached
-routing decisions computed under the old values no longer apply.
-
-| Section | Key | Default | What it controls |
-|---|---|---|---|
-| `eligibility.reserve` | `floorPercent` | 40 | Share of every quota window kept in reserve (per account, per window). Headroom for an unexpected burst and your next interactive session, without idling the account. |
-| `eligibility.reserve` | `scope` | `account-window` | How widely the reserve floor applies (per account per window at launch). |
-| `eligibility.reserve` | `coldStartFraction` | 0.25 | Consumption assumed for a seat with too little history: deliberately generous, so a mis-estimate fails eligibility instead of draining the account. |
-| `eligibility.reserve` | `estimateSamples` | 20 | How many recent dispatches the consumption estimate averages: enough to smooth outliers, quick enough to track a model change. |
-| `eligibility.reserve` | `estimateMinSamples` | 5 | Below this many observations the average is treated as noise and the cold-start value is used instead. |
-| `eligibility.reserve` | `estimateOutlierSigma` | 3 | Outlier cut for the estimate: one unusually slow dispatch cannot inflate the average, real tail latency is kept. |
-| `eligibility.reserve` | `ownerInteractiveOverride` | false | Whether your own interactive dispatches bypass the reserve rule (they do not, at launch). |
-| `ranking` | `janusUrl` | `http://127.0.0.1:8787` | The local janus evaluation service endpoint used for semantic ranking. |
-| `ranking` | `maxCandidates` | 8 | At most eight eligible seats are ranked per request; preference order trims first. |
-| `ranking` | `fallback` | `preference-order` | What happens when ranking is unavailable: dispatch falls back to your preference order and never blocks. |
-| `gate` | `threshold` | 0.9 | The dispatch gate's confidence threshold. A task is only dispatched when the evaluation clears it. Lower it only with evidence from your own audit log. |
-| `gate` | `timeoutMs` | 8000 | How long the gate waits for an evaluation. On timeout there is no verdict and dispatch is blocked (fail closed). |
-| `gate` | `requestBudgetTokens` | 30000 | Maximum size of a gate evaluation request. Normal evaluations use under a thousand tokens. |
-| seat record | `maxConcurrency` | 4 | How many workers one seat may run at once. The default suits a typical single machine or hosted seat. Tune it per seat: a cluster takes more, a constrained subscription endpoint may take less. |
-| automation policy | `maxConcurrent` | 4 | How many workers may run at once across all seats. The default is a conservative start. Tune it to the capacity you actually have, and raise it when you add seats or hardware. |
-
-Seats are named for infrastructure, not models: `dgx-spark-cluster`,
-`mac-studio`, `merge-gateway-worker`. The model is a mutable field on the
-seat, so changing models never renumbers your configuration. Each seat also
-carries `scopeStatements`: plain-language descriptions of what the seat is
-for. The dispatch gate reads them when judging whether a task fits.
-
 ## License
 
 AGPL-3.0-only with author-attribution additional terms (Section 7(b));

package/janus/README.draft.md

@@ -0,0 +1,210 @@
+# janus — Jev evaluation wrapper service
+
+janus is the local wrapper service for the Jev decision layer (design of
+record: `.private-planning/JEV_DECISION_LAYER_DESIGN.md` §5–§7, Revision 2.1).
+It wraps the official `@typesafe-ai/sdk` (TypeSafe Direct — the sole
+provider; the Vercel AI Gateway and merge gateway were dropped by owner
+decision) and exposes one evaluation endpoint plus health/readiness/version
+probes on loopback.
+
+## What janus does
+
+- `POST /evaluate` — evaluates typed questions (boolean / choice / score)
+  against one shared state via TypeSafe Direct (`typesafe-ai`, model `jev-latest`).
+- `GET /healthz` — liveness.
+- `GET /readyz` — readiness (gateway key resolvable from the Keychain).
+- `GET /version` — janus version, AI SDK version, schema versions, allowlist.
+
+Guarantees:
+
+- **Model allowlist** (server-side config; request-level model overrides are
+  rejected with `model_unauthorized`).
+- **Loopback only** — binds `127.0.0.1` and nothing else. No auth beyond
+  loopback; it is a local tool. There is deliberately no bind-address option.
+- **Single-flight** — identical requests (same evalInputDigest) coalesce;
+  distinct in-flight evaluations are capped (default 4) and rejected with
+  `busy`.
+- **30k-token request budget** — oversized requests are rejected with
+  `state_too_large`, never truncated silently.
+- **Redaction** — a general secrets/PII pass runs over the state before any
+  external call.
+- **Audit log** — append-only JSONL of request id, timestamps, question
+  names, verdict probabilities, and token usage. **State contents never
+  reach the audit log.** 90-day default retention, size-capped with
+  oldest-first rotation.
+- **Daily cost breaker** — token/cost ceilings in config; on exceed,
+  `/evaluate` returns `busy` with `budget_exhausted` detail until the UTC
+  day window resets.
+- **Timeouts** — 30s service-side cap; callers may pass a shorter
+  per-request `timeoutMs` (capped at 30s).
+
+## Provisioning the Keychain item
+
+The TypeSafe Direct key is read from the macOS Keychain at runtime — janus
+does not rely on inherited environment variables. The `typesafe-ai` /
+`Typesafe AI` generic-password item does not exist by default; create it
+once (interactive provisioning):
+
+```sh
+security add-generic-password -U -a typesafe-ai -s "Typesafe AI" -w
+# prompts for the secret; nothing is echoed
+```
+
+janus reads it with `security find-generic-password -w` under guarded
+capture: stdout is piped directly into memory, never echoed, never logged,
+never passed to spawned subprocesses. If the item is missing, janus returns
+`model_unauthorized` with `detail.key_unavailable: true` and `GET /readyz`
+reports 503 with the provisioning hint.
+
+Verify the item is present (no secret material is printed):
+
+```sh
+/usr/bin/security find-generic-password -s "Typesafe AI" -a typesafe-ai >/dev/null 2>&1 && echo present
+```
+
+To rotate the secret, re-run the `security add-generic-password -U` command
+above and enter the new value at the prompt (`-U` updates the existing item).
+To remove the item entirely:
+
+```sh
+security delete-generic-password -a typesafe-ai -s "Typesafe AI"
+```
+
+## Running
+
+Dev (from `janus/`):
+
+```sh
+npx tsx janus/server.ts          # listens on 127.0.0.1:8787
+```
+
+Config is read from `~/.config/typesafe-ai/jev/janus-config.json`
+(override with `JANUS_CONFIG_PATH`). Defaults work with no file:
+
+```json
+{
+  "port": 8787,
+  "modelAllowlist": ["typesafe-ai/jev"],
+  "defaultModel": "typesafe-ai/jev",
+  "maxConcurrent": 4,
+  "dailyTokenCeiling": 2000000,
+  "dailyCostCeilingUsd": 10,
+  "audit": { "path": "~/.local/share/janus/audit", "maxBytes": 10485760, "retentionDays": 90 }
+}
+```
+
+launchd — template at `janus/user.janus.plist`. The template is a starting
+point: every user-specific value (the label, the checkout path, log
+locations) is marked ADJUST in the file. Copy it out of the repository,
+adjust it, then load it:
+
+```sh
+cp janus/user.janus.plist ~/Library/LaunchAgents/
+```
+
+```sh
+launchctl load ~/Library/LaunchAgents/user.janus.plist
+```
+
+Tests (no live gateway calls — the SDK is mocked):
+
+```sh
+cd janus && npm test
+```
+
+## Endpoint contract
+
+### POST /evaluate
+
+Request:
+
+```json
+{
+  "state": "string | object | array (message histories pass directly)",
+  "questions": [
+    { "type": "boolean", "question": "Was a refund issued?", "threshold": 0.9 },
+    { "type": "choice", "question": "Route this ticket", "choices": ["billing", "tech", "other"] },
+    { "type": "score", "question": "Rate this PR" }
+  ],
+  "model": "optional; must be on the server allowlist, overrides rejected",
+  "timeoutMs": 10000
+}
+```
+
+Question schema v1 (§6), enforced atomically — any malformed, absent, or
+contradictory element fails the whole request with `validation_error`:
+
+- **boolean** — `threshold` optional, default `0.9`, comparison
+  `probability >= threshold`. Optional `criteria: {true?, false?}` labels.
+- **choice** — `choices` array REQUIRED; the verdict's `choice` is guaranteed
+  to be a member.
+- **score** — numeric 0..5, one decimal. Ordinal vocabularies must be
+  **choice** questions, not scores.
+
+§6 → SDK mapping (verified against ai@7.0.106 at launch step 1): the SDK's
+`experimental_evaluate` has **no top-level `criteria` argument**; the
+candidate set lives inside each question as a REQUIRED `criteria` field
+(choice: `Record<option, description | null>`; score: ordered level array;
+boolean: optional `{true?, false?}`). janus accepts §6's `choices` array at
+the transport layer and maps it to `criteria: {a: null, b: null, ...}`. The
+score vocabulary is passed as the ordered level array `["0".."5"]`.
+
+Success response (200):
+
+```json
+{
+  "request_id": "uuid",
+  "verdict": {
+    "Was a refund issued?": { "type": "boolean", "probability": 0.97, "passed": true },
+    "Route this ticket": { "type": "choice", "choice": "billing", "probabilities": {} },
+    "Rate this PR": { "type": "score", "score": 3.0 }
+  },
+  "usage": { "inputTokens": 0, "outputTokens": 0, "totalTokens": 0 },
+  "model": "typesafe-ai/jev",
+  "digest": "sha256 evalInputDigest"
+}
+```
+
+"Model returned false" is a **200** with `passed: false` / low probability —
+not an error.
+
+### Error taxonomy
+
+All errors: `{ "error": code, "message": ..., "request_id": ..., "detail"?: {...} }`
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `validation_error` | 400 | bad request (schema, JSON, unknown route) |
+| `state_too_large` | 413 | over the 30k-token budget; never truncated |
+| `unknown_question` | 400 | reserved for router/schema-version mismatches |
+| `model_unauthorized` | 403/502/503 | not on allowlist, credential rejected, or key unavailable (`detail.key_unavailable`) |
+| `gateway_unavailable` | 503 | gateway unreachable / model missing / rate limit |
+| `timeout` | 504 | evaluation exceeded the budget |
+| `busy` | 429 | concurrency cap or `detail.budget_exhausted` |
+| `degraded` | 503 | internal error |
+
+Callers distinguish **"model returned false"** (200, low probability) from
+**"no verdict"** (`timeout` / `gateway_unavailable`) from **"bad request"**
+(`validation_error`).
+
+## Layout
+
+```
+janus/
+  janus/
+    config.ts          config load/validate (allowlist, ceilings, retention)
+    schema.ts          §6 question schema v1 enforcement (atomic fail-closed)
+    verdict.ts         verdict enforcement (membership, ranges, thresholds)
+    budget.ts          token estimation, 30k budget, evalInputDigest
+                       redaction pass: shared library typesafe-secure
+                       lib/redaction (MIT), wired via a file: dependency
+    keychain.ts        guarded `security find-generic-password -w` capture
+    single_flight.ts   digest coalescing + concurrency cap
+    budget_breaker.ts  daily token/cost breaker
+    audit.ts           append-only JSONL audit log, rotation + retention
+    sdk.ts             THE ONLY AI SDK import site (pinned versions)
+    evaluate.ts        /evaluate pipeline + SDK error classification
+    server.ts          HTTP surface, loopback bind, entrypoint
+  tests/               node:test suites (mocked SDK, no live calls)
+  user.janus.plist  launchd template
+```

package/janus/README.md

@@ -0,0 +1,196 @@
+# janus — Jev evaluation wrapper service
+
+janus is the local wrapper service for the Jev decision layer (design of
+record: `.private-planning/JEV_DECISION_LAYER_DESIGN.md` §5–§7, Revision 2.1).
+It wraps the official `@typesafe-ai/sdk` (TypeSafe Direct — the sole
+provider; the Vercel AI Gateway and merge gateway were dropped by owner
+decision) and exposes one evaluation endpoint plus health/readiness/version
+probes on loopback.
+
+## What janus does
+
+- `POST /evaluate` — evaluates typed questions (boolean / choice / score)
+  against one shared state via TypeSafe Direct (`typesafe-ai`, model `jev-latest`).
+- `GET /healthz` — liveness.
+- `GET /readyz` — readiness (gateway key resolvable from the Keychain).
+- `GET /version` — janus version, AI SDK version, schema versions, allowlist.
+
+Guarantees:
+
+- **Model allowlist** (server-side config; request-level model overrides are
+  rejected with `model_unauthorized`).
+- **Loopback only** — binds `127.0.0.1` and nothing else. No auth beyond
+  loopback; it is a local tool. There is deliberately no bind-address option.
+- **Single-flight** — identical requests (same evalInputDigest) coalesce;
+  distinct in-flight evaluations are capped (default 4) and rejected with
+  `busy`.
+- **30k-token request budget** — oversized requests are rejected with
+  `state_too_large`, never truncated silently.
+- **Redaction** — a general secrets/PII pass runs over the state before any
+  external call.
+- **Audit log** — append-only JSONL of request id, timestamps, question
+  names, verdict probabilities, and token usage. **State contents never
+  reach the audit log.** 90-day default retention, size-capped with
+  oldest-first rotation.
+- **Daily cost breaker** — token/cost ceilings in config; on exceed,
+  `/evaluate` returns `busy` with `budget_exhausted` detail until the UTC
+  day window resets.
+- **Timeouts** — 30s service-side cap; callers may pass a shorter
+  per-request `timeoutMs` (capped at 30s).
+
+## Provisioning the Keychain item
+
+The TypeSafe Direct key is read from the macOS Keychain at runtime — janus
+does not rely on inherited environment variables. The `typesafe-ai` /
+`Typesafe AI` generic-password item does not exist by default; create it
+once (interactive provisioning):
+
+```sh
+security add-generic-password -U -a typesafe-ai -s "Typesafe AI" -w
+# prompts for the secret; nothing is echoed
+```
+
+janus reads it with `security find-generic-password -w` under guarded
+capture: stdout is piped directly into memory, never echoed, never logged,
+never passed to spawned subprocesses. If the item is missing, janus returns
+`model_unauthorized` with `detail.key_unavailable: true` and `GET /readyz`
+reports 503 with the provisioning hint.
+
+## Running
+
+Dev (from `janus/`):
+
+```sh
+npx tsx janus/server.ts          # listens on 127.0.0.1:8787
+```
+
+Config is read from `~/.config/typesafe-ai/jev/janus-config.json`
+(override with `JANUS_CONFIG_PATH`). Defaults work with no file:
+
+```json
+{
+  "port": 8787,
+  "modelAllowlist": ["typesafe-ai/jev"],
+  "defaultModel": "typesafe-ai/jev",
+  "maxConcurrent": 4,
+  "dailyTokenCeiling": 2000000,
+  "dailyCostCeilingUsd": 10,
+  "audit": { "path": "~/.local/share/janus/audit", "maxBytes": 10485760, "retentionDays": 90 }
+}
+```
+
+launchd — template at `janus/user.janus.plist`. The template is a starting
+point: every user-specific value (the label, the checkout path, log
+locations) is marked ADJUST in the file. Copy it out of the repository,
+adjust it, then load it:
+
+```sh
+cp janus/user.janus.plist ~/Library/LaunchAgents/
+```
+
+```sh
+launchctl load ~/Library/LaunchAgents/user.janus.plist
+```
+
+Tests (no live gateway calls — the SDK is mocked):
+
+```sh
+cd janus && npm test
+```
+
+## Endpoint contract
+
+### POST /evaluate
+
+Request:
+
+```json
+{
+  "state": "string | object | array (message histories pass directly)",
+  "questions": [
+    { "type": "boolean", "question": "Was a refund issued?", "threshold": 0.9 },
+    { "type": "choice", "question": "Route this ticket", "choices": ["billing", "tech", "other"] },
+    { "type": "score", "question": "Rate this PR" }
+  ],
+  "model": "optional; must be on the server allowlist, overrides rejected",
+  "timeoutMs": 10000
+}
+```
+
+Question schema v1 (§6), enforced atomically — any malformed, absent, or
+contradictory element fails the whole request with `validation_error`:
+
+- **boolean** — `threshold` optional, default `0.9`, comparison
+  `probability >= threshold`. Optional `criteria: {true?, false?}` labels.
+- **choice** — `choices` array REQUIRED; the verdict's `choice` is guaranteed
+  to be a member.
+- **score** — numeric 0..5, one decimal. Ordinal vocabularies must be
+  **choice** questions, not scores.
+
+§6 → SDK mapping (verified against ai@7.0.106 at launch step 1): the SDK's
+`experimental_evaluate` has **no top-level `criteria` argument**; the
+candidate set lives inside each question as a REQUIRED `criteria` field
+(choice: `Record<option, description | null>`; score: ordered level array;
+boolean: optional `{true?, false?}`). janus accepts §6's `choices` array at
+the transport layer and maps it to `criteria: {a: null, b: null, ...}`. The
+score vocabulary is passed as the ordered level array `["0".."5"]`.
+
+Success response (200):
+
+```json
+{
+  "request_id": "uuid",
+  "verdict": {
+    "Was a refund issued?": { "type": "boolean", "probability": 0.97, "passed": true },
+    "Route this ticket": { "type": "choice", "choice": "billing", "probabilities": {} },
+    "Rate this PR": { "type": "score", "score": 3.0 }
+  },
+  "usage": { "inputTokens": 0, "outputTokens": 0, "totalTokens": 0 },
+  "model": "typesafe-ai/jev",
+  "digest": "sha256 evalInputDigest"
+}
+```
+
+"Model returned false" is a **200** with `passed: false` / low probability —
+not an error.
+
+### Error taxonomy
+
+All errors: `{ "error": code, "message": ..., "request_id": ..., "detail"?: {...} }`
+
+| Code | HTTP | Meaning |
+|---|---|---|
+| `validation_error` | 400 | bad request (schema, JSON, unknown route) |
+| `state_too_large` | 413 | over the 30k-token budget; never truncated |
+| `unknown_question` | 400 | reserved for router/schema-version mismatches |
+| `model_unauthorized` | 403/502/503 | not on allowlist, credential rejected, or key unavailable (`detail.key_unavailable`) |
+| `gateway_unavailable` | 503 | gateway unreachable / model missing / rate limit |
+| `timeout` | 504 | evaluation exceeded the budget |
+| `busy` | 429 | concurrency cap or `detail.budget_exhausted` |
+| `degraded` | 503 | internal error |
+
+Callers distinguish **"model returned false"** (200, low probability) from
+**"no verdict"** (`timeout` / `gateway_unavailable`) from **"bad request"**
+(`validation_error`).
+
+## Layout
+
+```
+janus/
+  janus/
+    config.ts          config load/validate (allowlist, ceilings, retention)
+    schema.ts          §6 question schema v1 enforcement (atomic fail-closed)
+    verdict.ts         verdict enforcement (membership, ranges, thresholds)
+    budget.ts          token estimation, 30k budget, evalInputDigest
+                       redaction pass: shared library typesafe-secure
+                       lib/redaction (MIT), wired via a file: dependency
+    keychain.ts        guarded `security find-generic-password -w` capture
+    single_flight.ts   digest coalescing + concurrency cap
+    budget_breaker.ts  daily token/cost breaker
+    audit.ts           append-only JSONL audit log, rotation + retention
+    sdk.ts             THE ONLY AI SDK import site (pinned versions)
+    evaluate.ts        /evaluate pipeline + SDK error classification
+    server.ts          HTTP surface, loopback bind, entrypoint
+  tests/               node:test suites (mocked SDK, no live calls)
+  user.janus.plist  launchd template
+```