role-os 2.6.0 → 2.7.1

package/src/specialist/gate.mjs

@@ -0,0 +1,202 @@
+/**
+ * Gate — the per-dispatch routing decision: specialist or Claude.
+ *
+ * Hides one secret family (Parnas): the routing math. Callers pass in registry state and
+ * runtime signals; the gate is a pure function. Fail-open is the default — any uncertainty,
+ * any malformed signal, any out-of-band condition routes to Claude.
+ *
+ * The OvA score is computed per-specialist (Verma & Nalisnick ICML 2022, arXiv:2202.03673);
+ * there is NO joint softmax across roles. The default v0.1 classifier is deterministic +
+ * embedding-similarity (cosine of input embedding to the version's exam_centroid). A trained
+ * classifier is an additive upgrade — drop in a different `scoreFn`.
+ *
+ * The reject conditions enforced here are R-tier policy gates from
+ * `starter-pack/policy/specialist-tier.md`:
+ *   - shadow_probe_halt           — sticky halt dominates everything
+ *   - no_active_version            — registry has no active pointer
+ *   - uncertified_active_version  — Reject 2 safety net (load-time also catches this)
+ *   - quota_exhausted              — Reject 3
+ *   - ood                          — Reject 5
+ *   - score_below_threshold        — Reject 4
+ *   - score_invalid                — fail-open on a malformed classifier output
+ */
+
+import { resolveActiveVersion } from "./registry.mjs";
+
+/**
+ * @typedef {object} GateDecision
+ * @property {"specialist"|"claude"} route   where the dispatch goes
+ * @property {string} reason                  machine-readable reason
+ * @property {number} score                   OvA score (0 when not computed)
+ * @property {boolean} ood                    OOD check result
+ * @property {boolean} quotaOk                quota check result
+ * @property {string} [detail]                operator-facing explanation
+ */
+
+/**
+ * @typedef {object} QuotaState
+ * @property {number} used        dispatches taken by this specialist in the current window
+ * @property {number} window      window size (dispatches)
+ */
+
+/**
+ * @typedef {object} HaltState
+ * @property {boolean} halted
+ * @property {string} [reason]
+ */
+
+/**
+ * @typedef {object} Classifier
+ * @property {(input:any, version:object, entry:object) => number} scoreFn   returns OvA score in [0, 1]
+ * @property {(input:any, version:object, entry:object) => boolean} oodFn    true if input is OOD for this specialist
+ */
+
+/**
+ * Decide where this dispatch goes. Pure function; all state is in `params`.
+ *
+ * @param {object} params
+ * @param {string} params.role
+ * @param {*}      params.input
+ * @param {object} params.registryEntry           the specialist registry entry for `role`
+ * @param {QuotaState} params.quotaState
+ * @param {HaltState}  params.haltState
+ * @param {Classifier} [params.classifier]        v0.1 default = deterministic + embedding-similarity
+ * @returns {GateDecision}
+ */
+export function gate({ role, input, registryEntry, quotaState, haltState, classifier = defaultClassifier }) {
+  if (!registryEntry) {
+    return failOpen("no_registry_entry", `role "${role}" has no specialist registry entry`);
+  }
+  if (haltState && haltState.halted) {
+    return failOpen("shadow_probe_halt", haltState.reason || "specialist dispatch halted by shadow-probe disagreement");
+  }
+  let active;
+  try {
+    active = resolveActiveVersion(registryEntry);
+  } catch (err) {
+    return failOpen("registry_dangling_pointer", err.message);
+  }
+  if (!active) {
+    return failOpen("no_active_version", `role "${role}" has no active specialist version`);
+  }
+  if (active.certified_level === "L0") {
+    return failOpen("uncertified_active_version", `active version "${active.id}" is L0 (uncertified)`);
+  }
+
+  // Quota check (R3 in the policy): if accepting this dispatch would exceed the workload
+  // quota, fail open. We compute share-if-added — the cap is "share AFTER this dispatch",
+  // so the gate's decision itself is what enforces the cap (no race with later increments).
+  const window = Math.max(1, quotaState?.window ?? 0);
+  const used = Math.max(0, quotaState?.used ?? 0);
+  const shareIfAdd = (used + 1) / window;
+  const quotaOk = shareIfAdd <= registryEntry.workload_quota;
+  if (!quotaOk) {
+    return failOpen(
+      "quota_exhausted",
+      `would push specialist share to ${shareIfAdd.toFixed(3)} > quota ${registryEntry.workload_quota}`,
+      { quotaOk: false },
+    );
+  }
+
+  // OOD check (R5).
+  let ood = false;
+  try {
+    ood = !!classifier.oodFn(input, active, registryEntry);
+  } catch (err) {
+    return failOpen("ood_check_threw", `oodFn threw: ${err.message}`);
+  }
+  if (ood) {
+    return failOpen("ood", "input is out-of-distribution for the active specialist", { ood: true });
+  }
+
+  // OvA score (R4).
+  let score;
+  try {
+    score = classifier.scoreFn(input, active, registryEntry);
+  } catch (err) {
+    return failOpen("score_fn_threw", `scoreFn threw: ${err.message}`);
+  }
+  if (typeof score !== "number" || !Number.isFinite(score) || score < 0 || score > 1) {
+    return failOpen("score_invalid", `scoreFn returned ${score} (must be a finite number in [0, 1])`);
+  }
+  if (score < active.gate_threshold) {
+    return failOpen(
+      "score_below_threshold",
+      `OvA score ${score.toFixed(3)} < gate_threshold ${active.gate_threshold}`,
+      { score },
+    );
+  }
+
+  return {
+    route: "specialist",
+    reason: "ok",
+    score,
+    ood: false,
+    quotaOk: true,
+    detail: `routed to specialist (score=${score.toFixed(3)}, threshold=${active.gate_threshold})`,
+  };
+}
+
+function failOpen(reason, detail, overrides = {}) {
+  return {
+    route: "claude",
+    reason,
+    score: overrides.score ?? 0,
+    ood: overrides.ood ?? false,
+    quotaOk: overrides.quotaOk ?? true,
+    detail,
+  };
+}
+
+// ── Default classifier — deterministic + embedding-similarity ─────────────────────────────────
+
+/**
+ * Default OvA score: cosine similarity of `input.embedding` to `version.exam_centroid`,
+ * mapped from [-1, 1] to [0, 1]. If either is missing, returns 0 (which is below any
+ * positive gate_threshold and so fails open).
+ *
+ * v0.1 inputs that do not carry an embedding will always score 0 → always fail open. That is
+ * the correct default until either:
+ *   (a) inputs are pre-embedded by the consumer (e.g. prism for the Verifier specialist), or
+ *   (b) a trained classifier replaces this default scoreFn.
+ */
+export function defaultScoreFn(input, version /*, entry */) {
+  const emb = input && Array.isArray(input.embedding) ? input.embedding : null;
+  const centroid = Array.isArray(version.exam_centroid) ? version.exam_centroid : null;
+  if (!emb || !centroid || emb.length === 0 || emb.length !== centroid.length) return 0;
+  const sim = cosineSimilarity(emb, centroid);
+  return (sim + 1) / 2;
+}
+
+/**
+ * Default OOD: when there's no centroid or no embedding to measure against, the v0.1 gate
+ * cannot judge in-distribution and so calls the input OOD (fail-open). Once a centroid +
+ * input embedding are both present, OOD is true iff cosine similarity is below `ood_floor`
+ * (default 0.4). A trained OOD detector is an additive upgrade.
+ *
+ * Read together with `defaultScoreFn`: with no embedding, `ood = true` AND `score = 0` —
+ * both reject paths are taken, both fail open. The redundancy is intentional (defense in
+ * depth — neither rejection depends on the other working).
+ */
+export function defaultOodFn(input, version /*, entry */) {
+  const emb = input && Array.isArray(input.embedding) ? input.embedding : null;
+  const centroid = Array.isArray(version.exam_centroid) ? version.exam_centroid : null;
+  if (!emb || !centroid || emb.length === 0 || emb.length !== centroid.length) return true;
+  const floor = typeof version.ood_floor === "number" ? version.ood_floor : 0.4;
+  return cosineSimilarity(emb, centroid) < floor;
+}
+
+export const defaultClassifier = { scoreFn: defaultScoreFn, oodFn: defaultOodFn };
+
+/** Cosine similarity in [-1, 1]. Returns 0 for zero-norm vectors. */
+export function cosineSimilarity(a, b) {
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i], y = b[i];
+    dot += x * y;
+    na += x * x;
+    nb += y * y;
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / Math.sqrt(na * nb);
+}

package/src/specialist/registry.mjs

@@ -0,0 +1,219 @@
+/**
+ * Specialist registry — load + validate `.role-os/specialists.json`.
+ *
+ * Hides one secret family (Parnas CACM 1972): the on-disk schema and the reject conditions
+ * R1-R7 from `starter-pack/schemas/specialist.md`. Callers see a Map<role, entry> and the
+ * resolved active version; they never parse the file themselves.
+ *
+ * Reject 1 (same-family base) and R3/R4 (id collisions / dangling pointer) are correctness
+ * invariants — no bypass flag. R2 (uncertified active) is also a load-time reject so a
+ * misedited file cannot route to L0.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const REGISTRY_SCHEMA = "roleos-specialist-registry/v1";
+
+/** Known Claude-family base-model prefixes — refused by R1 at load. Conservative; widen as needed. */
+const CLAUDE_FAMILY_PREFIXES = [
+  "claude-",
+  "anthropic/",
+  "anthropic.",
+];
+
+export function isClaudeFamily(baseModel) {
+  if (typeof baseModel !== "string") return false;
+  const m = baseModel.toLowerCase();
+  return CLAUDE_FAMILY_PREFIXES.some((p) => m.startsWith(p));
+}
+
+/**
+ * @typedef {object} SpecialistVersion
+ * @property {string} id
+ * @property {string} adapter_id
+ * @property {string} base_model
+ * @property {number} gate_threshold
+ * @property {string} certified_level
+ * @property {string} exam_hash
+ * @property {number} field_audit_window
+ * @property {string} created_at
+ * @property {string} [notes]
+ * @property {number[]} [exam_centroid]      optional pre-computed centroid for embedding-similarity scoring
+ */
+
+/**
+ * @typedef {object} SpecialistEntry
+ * @property {string} role
+ * @property {string} backend_url
+ * @property {string} fallback           must be "claude" in v0.1
+ * @property {number} workload_quota     in (0, 1]
+ * @property {string|null} active_version  id from versions[], or null
+ * @property {SpecialistVersion[]} versions
+ */
+
+/**
+ * @typedef {object} Registry
+ * @property {string} schema
+ * @property {SpecialistEntry[]} specialists
+ */
+
+/**
+ * Load a registry from disk. Returns `{ registry, byRole, errors }`.
+ *
+ * - If the file does not exist, returns an empty registry (`{ specialists: [] }`) with no
+ *   errors — the framework's default state is "no specialists deployed", and that must not
+ *   fail load.
+ * - If the file exists but fails validation, returns `errors[]` populated and `byRole` empty
+ *   (a partial registry is not a registry).
+ */
+export function loadRegistry(path) {
+  if (!existsSync(path)) {
+    return { registry: emptyRegistry(), byRole: new Map(), errors: [] };
+  }
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    return {
+      registry: emptyRegistry(),
+      byRole: new Map(),
+      errors: [`registry parse error: ${err.message}`],
+    };
+  }
+  const { ok, errors } = validateRegistry(raw);
+  if (!ok) return { registry: emptyRegistry(), byRole: new Map(), errors };
+  const byRole = new Map();
+  for (const e of raw.specialists) byRole.set(e.role, e);
+  return { registry: raw, byRole, errors: [] };
+}
+
+/** Persist a registry to disk. Creates the parent directory if needed. Atomic-ish write. */
+export function saveRegistry(path, raw) {
+  const { ok, errors } = validateRegistry(raw);
+  if (!ok) {
+    const err = new Error(`refusing to save invalid registry: ${errors.join("; ")}`);
+    err.code = "REGISTRY_INVALID";
+    err.errors = errors;
+    throw err;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(raw, null, 2) + "\n", "utf8");
+}
+
+export function emptyRegistry() {
+  return { schema: REGISTRY_SCHEMA, specialists: [] };
+}
+
+/**
+ * Validate a parsed registry against R1-R7 (see schema doc). Returns `{ ok, errors }`.
+ * Validation is total — every error is reported, not just the first.
+ */
+export function validateRegistry(raw) {
+  const errors = [];
+  if (!raw || typeof raw !== "object") {
+    return { ok: false, errors: ["registry is not an object"] };
+  }
+  // R7: schema major version
+  if (raw.schema !== REGISTRY_SCHEMA) {
+    errors.push(`R7: schema mismatch — got "${raw.schema}", expected "${REGISTRY_SCHEMA}"`);
+  }
+  if (!Array.isArray(raw.specialists)) {
+    errors.push("registry.specialists must be an array");
+    return { ok: false, errors };
+  }
+  const seenRoles = new Set();
+  for (let i = 0; i < raw.specialists.length; i++) {
+    const e = raw.specialists[i];
+    const tag = `specialists[${i}]${e && e.role ? ` (role="${e.role}")` : ""}`;
+    if (!e || typeof e !== "object") {
+      errors.push(`${tag}: not an object`);
+      continue;
+    }
+    if (typeof e.role !== "string" || !e.role) errors.push(`${tag}: role must be a non-empty string`);
+    if (e.role && seenRoles.has(e.role)) errors.push(`${tag}: duplicate role`);
+    if (e.role) seenRoles.add(e.role);
+    if (typeof e.backend_url !== "string" || !e.backend_url) errors.push(`${tag}: backend_url must be a non-empty string`);
+    if (e.fallback !== "claude") errors.push(`${tag}: fallback must be "claude" in v0.1 (got "${e.fallback}")`);
+    // R6
+    if (typeof e.workload_quota !== "number" || !(e.workload_quota > 0 && e.workload_quota <= 1)) {
+      errors.push(`${tag}: R6 — workload_quota must be in (0, 1] (got ${e.workload_quota})`);
+    }
+    if (!Array.isArray(e.versions)) {
+      errors.push(`${tag}: versions must be an array`);
+      continue;
+    }
+    // R3: id collisions inside versions[]
+    const seenIds = new Set();
+    for (let j = 0; j < e.versions.length; j++) {
+      const v = e.versions[j];
+      const vtag = `${tag}.versions[${j}]${v && v.id ? ` (id="${v.id}")` : ""}`;
+      const vErrors = validateVersion(v, vtag);
+      errors.push(...vErrors);
+      if (v && typeof v.id === "string") {
+        if (seenIds.has(v.id)) errors.push(`${vtag}: R3 — duplicate version id within role`);
+        seenIds.add(v.id);
+      }
+    }
+    // R4: active_version must appear in versions[] (or be null)
+    if (e.active_version !== null && e.active_version !== undefined) {
+      if (typeof e.active_version !== "string") {
+        errors.push(`${tag}: active_version must be a string or null`);
+      } else if (!seenIds.has(e.active_version)) {
+        errors.push(`${tag}: R4 — active_version "${e.active_version}" not found in versions[]`);
+      } else {
+        // R2: active_version must point to a certified (non-L0) version
+        const active = e.versions.find((v) => v && v.id === e.active_version);
+        if (active && active.certified_level === "L0") {
+          errors.push(`${tag}: R2 — active_version "${e.active_version}" is L0 (uncertified); cannot be active`);
+        }
+      }
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function validateVersion(v, tag) {
+  const errors = [];
+  if (!v || typeof v !== "object") return [`${tag}: not an object`];
+  if (typeof v.id !== "string" || !v.id) errors.push(`${tag}: id must be a non-empty string`);
+  if (typeof v.adapter_id !== "string" || !v.adapter_id) errors.push(`${tag}: adapter_id must be a non-empty string`);
+  if (typeof v.base_model !== "string" || !v.base_model) {
+    errors.push(`${tag}: base_model must be a non-empty string`);
+  } else if (isClaudeFamily(v.base_model)) {
+    // R1: same-family base is a correctness regression, not a routing preference.
+    errors.push(`${tag}: R1 — base_model "${v.base_model}" is Claude-family; specialists must be cross-family`);
+  }
+  // R5
+  if (typeof v.gate_threshold !== "number" || !(v.gate_threshold >= 0 && v.gate_threshold <= 1)) {
+    errors.push(`${tag}: R5 — gate_threshold must be in [0, 1] (got ${v.gate_threshold})`);
+  }
+  if (typeof v.certified_level !== "string" || !v.certified_level) {
+    errors.push(`${tag}: certified_level must be a non-empty string (e.g. "L0", "L1", …)`);
+  }
+  if (typeof v.exam_hash !== "string" || !v.exam_hash) errors.push(`${tag}: exam_hash must be a non-empty string`);
+  if (typeof v.field_audit_window !== "number" || v.field_audit_window <= 0) {
+    errors.push(`${tag}: field_audit_window must be a positive number`);
+  }
+  if (typeof v.created_at !== "string" || !v.created_at) errors.push(`${tag}: created_at must be a non-empty ISO-8601 string`);
+  if (v.exam_centroid !== undefined && !Array.isArray(v.exam_centroid)) {
+    errors.push(`${tag}: exam_centroid, if present, must be an array of numbers`);
+  }
+  return errors;
+}
+
+/**
+ * Resolve the active version for a registry entry. Returns the version object, or null if
+ * `active_version` is null. Throws if the registry was malformed (which loadRegistry would
+ * have already rejected, so callers should not normally see this).
+ */
+export function resolveActiveVersion(entry) {
+  if (!entry || !entry.active_version) return null;
+  const v = entry.versions.find((x) => x && x.id === entry.active_version);
+  if (!v) {
+    const err = new Error(`active_version "${entry.active_version}" not found in versions[]`);
+    err.code = "REGISTRY_DANGLING_POINTER";
+    throw err;
+  }
+  return v;
+}

package/src/specialist/shadow.mjs

@@ -0,0 +1,122 @@
+/**
+ * Shadow-probe — every Kth specialist dispatch also runs the Claude path; the two verdicts
+ * are compared and logged. Over a rolling window of N probes, if agreement falls below
+ * `1 - τ`, the role is halted (andon).
+ *
+ * Hides one secret family: the probe schedule + halt math. Callers see `shouldShadowProbe`,
+ * `recordProbe`, and `checkHalt`; they don't compute K-th or read JSONL by hand.
+ *
+ * Defaults (per `policy/specialist-tier.md`):
+ *   - K (probe-every-N) = 20
+ *   - N (rolling window) = 50
+ *   - τ (disagreement threshold) = 0.15  →  halt when agreement rate < 0.85
+ *
+ * These defaults are configurable per-role via the registry entry (future) or globally via
+ * env (`ROLEOS_SHADOW_K`, `ROLEOS_SHADOW_N`, `ROLEOS_SHADOW_TAU`).
+ */
+
+import { readEvents, appendEvent } from "./events.mjs";
+
+export const SHADOW_DEFAULTS = {
+  K: 20,
+  N: 50,
+  TAU: 0.15,
+};
+
+/**
+ * Decide whether the dispatch we're about to make should also fire a shadow probe.
+ * Probe fires on the Kth dispatch (counter === K). Caller increments the counter elsewhere
+ * (see state.mjs/incrementProbeCounter); this is pure.
+ */
+export function shouldShadowProbe(counter, K = SHADOW_DEFAULTS.K) {
+  return counter >= K;
+}
+
+/**
+ * Record a shadow probe outcome. `agreed` is the consumer-domain agreement (the caller
+ * supplied a domain-aware comparator). Optional summary fields are kept short and
+ * operator-facing — full verdicts go in the dispatch receipt, not in the event log.
+ *
+ * @param {string} eventsPath
+ * @param {object} probe
+ * @param {string} probe.role
+ * @param {string} probe.trace_id
+ * @param {boolean} probe.agreed
+ * @param {string} [probe.specialist_summary]
+ * @param {string} [probe.claude_summary]
+ * @param {string} probe.ts                   ISO-8601 (caller-supplied; no Date.now() here)
+ */
+export function recordProbe(eventsPath, probe) {
+  appendEvent(eventsPath, {
+    kind: "shadow-probe",
+    role: probe.role,
+    ts: probe.ts,
+    data: {
+      trace_id: probe.trace_id,
+      agreed: !!probe.agreed,
+      ...(probe.specialist_summary ? { specialist_summary: probe.specialist_summary } : {}),
+      ...(probe.claude_summary ? { claude_summary: probe.claude_summary } : {}),
+    },
+  });
+}
+
+/**
+ * Check the last N shadow-probe events for `role` and compute agreement rate. Returns
+ * `{ probes, agreed, rate, shouldHalt }`. If fewer than N probes exist, `shouldHalt` is
+ * always false — we don't halt off a thin sample (Snell 2024 phase-transition argument:
+ * narrow fine-tunes show step changes, so an early halt on a small sample would be a noise
+ * trigger, not a real disagreement signal).
+ *
+ * @param {string} eventsPath
+ * @param {string} role
+ * @param {number} [N]
+ * @param {number} [tau]
+ * @returns {{ probes: number, agreed: number, rate: number, shouldHalt: boolean }}
+ */
+export function checkHalt(eventsPath, role, N = SHADOW_DEFAULTS.N, tau = SHADOW_DEFAULTS.TAU) {
+  const events = readEvents(eventsPath, { role, kind: "shadow-probe" });
+  const window = events.slice(-N);
+  const probes = window.length;
+  const agreed = window.filter((e) => e.data && e.data.agreed === true).length;
+  const rate = probes === 0 ? 1 : agreed / probes;
+  const shouldHalt = probes >= N && rate < 1 - tau;
+  return { probes, agreed, rate, shouldHalt };
+}
+
+/**
+ * Compose a contrastive halt message — workflow-standard #5 (Buçinca CHI 2025
+ * arXiv:2410.04253). Names what the specialist did, what Claude did, and why we halted.
+ * Caller writes this into the halt event AND into the state file's halt slot.
+ */
+export function contrastiveHaltMessage({ role, probes, rate, tau }) {
+  const pct = (rate * 100).toFixed(1);
+  const required = ((1 - tau) * 100).toFixed(1);
+  return (
+    `specialist for role "${role}" halted: shadow-probe agreement ${pct}% over the last ` +
+    `${probes} probes < required ${required}% (τ=${tau}). The specialist's verdicts have ` +
+    `drifted from Claude's on the same inputs. Clear with: roleos specialist clear-halt ${role}`
+  );
+}
+
+/**
+ * Append a halt event AND set the state's halt slot. The caller saves the state file; this
+ * function only appends to the events log so the operations remain composable (events.jsonl
+ * is shared; state.json is per-call).
+ */
+export function appendHaltEvent(eventsPath, { role, ts, reason, probes, agreed, rate, tau }) {
+  appendEvent(eventsPath, {
+    kind: "halt",
+    role,
+    ts,
+    data: { reason, probes, agreed, rate, tau },
+  });
+}
+
+export function appendClearHaltEvent(eventsPath, { role, ts, operator, reason }) {
+  appendEvent(eventsPath, {
+    kind: "clear-halt",
+    role,
+    ts,
+    data: { operator, reason: reason || "" },
+  });
+}

package/src/specialist/state.mjs

@@ -0,0 +1,125 @@
+/**
+ * Specialist runtime state — quota counters + shadow-probe counter + halt state, per role.
+ *
+ * Hides one secret family (Parnas): the persistence of routing counters. Callers see
+ * `get/inc/setHalt/getHalt`; they never touch the on-disk format. The on-disk format is a
+ * single JSON file, intentionally simple so an operator can hand-edit it in a pinch.
+ *
+ * State default path: `<repo>/.role-os/specialist-state.json`. Override with
+ * `ROLEOS_SPECIALIST_STATE_PATH`.
+ *
+ * Quota: a sliding-window counter. We store the last `window` dispatch timestamps so the
+ * window is a true rolling window, not aligned to wall clock. (A wall-clock window can be
+ * timed against the edge, which the workload-quota anti-collapse argument is meant to
+ * prevent.)
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const STATE_SCHEMA = "roleos-specialist-state/v1";
+
+/**
+ * @typedef {object} RoleState
+ * @property {number[]} dispatch_timestamps   sliding window of dispatch unix-ms
+ * @property {number} probe_counter            count of dispatches since the last shadow probe
+ * @property {object|null} halt                { reason, since } or null when not halted
+ */
+
+/**
+ * @typedef {object} StateFile
+ * @property {string} schema
+ * @property {Object<string, RoleState>} roles
+ */
+
+export function emptyState() {
+  return { schema: STATE_SCHEMA, roles: {} };
+}
+
+export function loadState(path) {
+  if (!existsSync(path)) return emptyState();
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (!raw || raw.schema !== STATE_SCHEMA || typeof raw.roles !== "object") {
+      // Refuse to silently accept a mis-shaped state file. Caller decides what to do.
+      const err = new Error(`state file schema mismatch: got "${raw && raw.schema}", expected "${STATE_SCHEMA}"`);
+      err.code = "STATE_SCHEMA_MISMATCH";
+      throw err;
+    }
+    return raw;
+  } catch (err) {
+    if (err.code === "STATE_SCHEMA_MISMATCH") throw err;
+    const wrapped = new Error(`state file parse error: ${err.message}`);
+    wrapped.code = "STATE_PARSE_ERROR";
+    throw wrapped;
+  }
+}
+
+export function saveState(path, state) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+
+/** Get or create a role's slot in the state object. Mutates and returns the slot. */
+export function ensureRole(state, role) {
+  if (!state.roles[role]) {
+    state.roles[role] = { dispatch_timestamps: [], probe_counter: 0, halt: null };
+  }
+  return state.roles[role];
+}
+
+/**
+ * Record a specialist dispatch in the sliding window. Pure — returns updated state.
+ * `windowSize` is in dispatches, not seconds; we keep the last `windowSize` timestamps.
+ * `nowMs` must be supplied (no Date.now() inside this function for testability).
+ */
+export function recordDispatch(state, role, windowSize, nowMs) {
+  const slot = ensureRole(state, role);
+  slot.dispatch_timestamps.push(nowMs);
+  if (slot.dispatch_timestamps.length > windowSize) {
+    slot.dispatch_timestamps.splice(0, slot.dispatch_timestamps.length - windowSize);
+  }
+  return state;
+}
+
+/**
+ * Build a QuotaState view for the gate. `used` is "how many of the last `windowSize`
+ * dispatches went to the specialist" — but here EVERY tracked timestamp is a specialist
+ * dispatch (Claude calls are not tracked), so `used = dispatch_timestamps.length` and
+ * `window` accounts for both — the gate computes share-if-added.
+ *
+ * Important: this caps `window` at `windowSize`. With fewer than `windowSize` dispatches,
+ * the quota check is generous (a small denominator means small share). That is intentional
+ * — the quota cap is meant to prevent collapse at scale, not to gate a cold start.
+ */
+export function quotaStateFor(state, role, windowSize) {
+  const slot = state.roles[role];
+  const used = slot ? slot.dispatch_timestamps.length : 0;
+  return { used, window: windowSize };
+}
+
+export function incrementProbeCounter(state, role) {
+  const slot = ensureRole(state, role);
+  slot.probe_counter += 1;
+  return slot.probe_counter;
+}
+
+export function resetProbeCounter(state, role) {
+  const slot = ensureRole(state, role);
+  slot.probe_counter = 0;
+}
+
+export function getHalt(state, role) {
+  const slot = state.roles[role];
+  if (!slot || !slot.halt) return { halted: false };
+  return { halted: true, reason: slot.halt.reason, since: slot.halt.since };
+}
+
+export function setHalt(state, role, halt) {
+  const slot = ensureRole(state, role);
+  if (halt) {
+    slot.halt = { reason: halt.reason, since: halt.since };
+  } else {
+    slot.halt = null;
+  }
+}