@aiwayds/dsh-topics-memory 0.18.1 → 0.19.0

package/lib/jev/client.js

@@ -0,0 +1,211 @@
+/**
+ * System One decision client — direct HTTP with zero dependencies beyond
+ * node:child_process and the global fetch (design 2026-09-25 §3; ADR
+ * proposal: direct HTTP over MCP).
+ *
+ * Semantics (§1/§3.2):
+ *  - one AbortSignal.timeout per request, NO retry — the calling lane's next
+ *    cadence is the natural retry (fail-open hard-coded, red line ②);
+ *  - every failure returns as a structured {ok:false} result, never a throw;
+ *  - the COMPLETE serialized body is gate-scanned before anything leaves the
+ *    process (red line ③, design §3.3).
+ *
+ * @module jev/client
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolveBackend } from "./backends.js";
+import { currentSecrets, scanForSecrets } from "./gate.js";
+import { logCall } from "./log.js";
+/** Guard for non-positive/absent values from bare harnesses. */
+const DEFAULT_TIMEOUT_MS = 3000;
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** 'svc' -> {service:'svc'}; 'svc:acct' -> {service:'svc', account:'acct'} */
+export function parseKeychainSpec(spec) {
+    const i = spec.indexOf(':');
+    if (i === -1)
+        return { service: spec };
+    return { service: spec.slice(0, i), account: spec.slice(i + 1) };
+}
+const execFileAsync = promisify(execFile);
+/** Default runner: `security find-generic-password … -w`; errors (missing
+ *  entry, no binary on non-macOS, access denied) surface as rejections. */
+const securityRunner = async (file, args) => {
+    return (await execFileAsync(file, args, { encoding: 'utf8' }));
+};
+/** Runs `security find-generic-password -w`; null on any failure (silent). */
+export async function keychainLookup(spec, runner = securityRunner) {
+    const args = ['find-generic-password', '-s', spec.service];
+    if (spec.account !== undefined)
+        args.push('-a', spec.account);
+    try {
+        return (await runner('security', [...args, '-w'])).stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolve the API key for a backend: env var wins, then the keychain spec
+ *  (explicit JEV_KEYCHAIN, or the backend default for zen only). */
+export async function resolveApiKey(backend, lookup = keychainLookup) {
+    const envKey = process.env[backend.keyEnv] ?? '';
+    if (envKey !== '')
+        return envKey;
+    const explicit = process.env.JEV_KEYCHAIN?.trim() ?? '';
+    const spec = explicit !== '' ? parseKeychainSpec(explicit) : backend.keychainByDefault ? { service: backend.keychainService } : null;
+    if (spec === null)
+        return '';
+    return (await lookup(spec)) ?? '';
+}
+function where(id) {
+    return `questions['${id}']`;
+}
+export function normalizeQuestions(questions, family) {
+    if (!isPlainObject(questions) || Object.keys(questions).length === 0) {
+        return { ok: false, message: "'questions' must be a non-empty object mapping question id -> {type, instructions, criteria?}." };
+    }
+    const systemone = family === 'systemone';
+    const out = {};
+    for (const [id, q] of Object.entries(questions)) {
+        if (!isPlainObject(q))
+            return { ok: false, message: `${where(id)} must be an object.` };
+        if (q.type !== 'noul' && q.type !== 'choice' && q.type !== 'score') {
+            return { ok: false, message: `${where(id)}.type must be 'noul' | 'choice' | 'score'.` };
+        }
+        if (typeof q.instructions !== 'string' || q.instructions === '') {
+            return { ok: false, message: `${where(id)}.instructions must be a non-empty string (the plugin always sends instructions).` };
+        }
+        const wire = { type: q.type, instructions: q.instructions };
+        if (q.type === 'noul') {
+            if (q.criteria === undefined) {
+                wire.criteria = { true: q.instructions, false: `NOT: ${q.instructions}` };
+            }
+            else if (isPlainObject(q.criteria) && q.criteria.true !== undefined && q.criteria.false !== undefined) {
+                if (!systemone && (typeof q.criteria.true !== 'string' || typeof q.criteria.false !== 'string')) {
+                    return { ok: false, message: `${where(id)}: noul criteria must be the two-sided {true: string, false: string} on the decisions protocol.` };
+                }
+                wire.criteria = q.criteria;
+            }
+            else {
+                return { ok: false, message: `${where(id)}: noul criteria, when given, must be the two-sided {true: ..., false: ...}.` };
+            }
+        }
+        else if (q.type === 'choice') {
+            if (!isPlainObject(q.criteria)) {
+                return { ok: false, message: `${where(id)}: choice criteria must be an OBJECT mapping option -> description.` };
+            }
+            wire.criteria = q.criteria;
+        }
+        else {
+            // score: 2-10 ordered levels; strings everywhere (plugin convention);
+            // the systemone protocol additionally tolerates structured levels.
+            if (!Array.isArray(q.criteria) || q.criteria.length < 2 || q.criteria.length > 10) {
+                return { ok: false, message: `${where(id)}: score criteria must be an ARRAY of 2-10 level descriptions.` };
+            }
+            const stringLevels = q.criteria.every((l) => typeof l === 'string' && l.length > 0);
+            if (!stringLevels && !systemone) {
+                return { ok: false, message: `${where(id)}: score levels must be non-empty strings on the decisions protocol.` };
+            }
+            wire.criteria = q.criteria;
+        }
+        out[id] = wire;
+    }
+    return { ok: true, questions: out };
+}
+// ---------------------------------------------------------------------------
+/** Ask the System One decision model. One request for the whole batch;
+ *  resolves to a structured failure (never throws) so the calling lane can
+ *  fail open. Writes the decisions.jsonl call-layer row on EVERY path. */
+export async function jevAsk(args) {
+    const backend = resolveBackend(args.config.jevBackend);
+    // '' is the sentinel; undefined (bare harnesses) resolves to the default too
+    const model = args.config.jevModel ? args.config.jevModel : backend.defaultModel;
+    const fallback = args.fallback === true; // absent => false: the column is call-time-invariant (fail-open = outcome !== ok)
+    const state = typeof args.state === 'string' ? args.state : '';
+    const started = Date.now();
+    async function emit(outcome, usage) {
+        await logCall({
+            at: new Date().toISOString(),
+            lane: args.lane,
+            backend: backend.name,
+            model,
+            questionCount: isPlainObject(args.questions) ? Object.keys(args.questions).length : 0,
+            stateChars: state.length,
+            latencyMs: Date.now() - started,
+            usage,
+            outcome,
+            fallback,
+        });
+    }
+    const refuse = async (outcome, message) => {
+        await emit(outcome, null);
+        return { ok: false, outcome, message, latencyMs: Date.now() - started };
+    };
+    // 1. Local protocol check — nothing about the request has left the process.
+    const normalized = normalizeQuestions(args.questions, backend.family);
+    if (!normalized.ok)
+        return refuse('invalid_request', normalized.message);
+    const wireQuestions = normalized.questions;
+    // 2. Secret gate over the COMPLETE outbound body — the exact string below
+    //    is what goes on the wire, so the gate sees byte-identical traffic.
+    //    A hit sends NOTHING.
+    const secretFile = args.config.jevSecretFile ?? '';
+    const wire = JSON.stringify({ model, state, questions: wireQuestions });
+    const hit = scanForSecrets(wire, currentSecrets(secretFile, args.logger), secretFile);
+    if (hit !== null) {
+        return refuse('secret_gate_blocked', `outbound payload matched secret pattern '${hit.pattern}' at offset ${hit.offset}; NOTHING was sent. Remove the secret from the request body (model/state/questions).`);
+    }
+    // 3. API key — absent key fails before any network activity.
+    const key = await resolveApiKey(backend);
+    if (key === '') {
+        const hint = backend.keychainByDefault
+            ? ` (set ${backend.keyEnv}, or store the key in the macOS keychain service '${backend.keychainService}')`
+            : ` (set ${backend.keyEnv}, or JEV_KEYCHAIN='<service>[:<account>]' for a macOS keychain lookup)`;
+        return refuse('missing_key', `no API key for the active backend '${backend.name}'${hint}.`);
+    }
+    // 4. One request, one timeout, NO retry.
+    const timeoutMs = Number(args.config.jevTimeoutMs) > 0 ? Number(args.config.jevTimeoutMs) : DEFAULT_TIMEOUT_MS;
+    let res;
+    try {
+        res = await fetch(backend.endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+            body: wire,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        const outcome = err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError') ? 'timeout' : 'network';
+        return refuse(outcome, `${outcome} error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!res.ok) {
+        const text = (await res.text().catch(() => '')).slice(0, 300);
+        const outcome = res.status >= 500 ? 'http_5xx' : 'http_4xx';
+        return refuse(outcome, `${backend.name} responded ${res.status}: ${text}`);
+    }
+    let json;
+    try {
+        json = await res.json();
+    }
+    catch (err) {
+        return refuse('bad_json', `${backend.name} returned non-JSON body: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // 5. Response shape: answers must be an object covering every question id
+    //    (a half-answered batch is a bad response, not a partial success).
+    if (!isPlainObject(json)) {
+        return refuse('bad_json', `${backend.name} returned no answers object.`);
+    }
+    const answers = json.answers;
+    if (!isPlainObject(answers)) {
+        return refuse('bad_json', `${backend.name} returned no answers object.`);
+    }
+    const missing = Object.keys(wireQuestions).filter((id) => answers[id] === undefined);
+    if (missing.length > 0) {
+        return refuse('bad_json', `${backend.name} returned no answer for question id(s): ${missing.join(', ')}.`);
+    }
+    const usage = isPlainObject(json.usage) ? json.usage : null;
+    await emit('ok', usage);
+    return { ok: true, answers: answers, usage, latencyMs: Date.now() - started };
+}

package/lib/jev/gate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Outbound secret gate (design 2026-09-25 §3.3) — self-contained port of the
+ * dsh-jev-mcp `server.mjs` mechanism. The COMPLETE serialized request body
+ * (model, state, questions — byte-identical to what goes on the wire) is
+ * scanned for credential patterns BEFORE anything leaves the process; a hit
+ * aborts the call with a structured descriptor that never echoes the secret.
+ *
+ * SECURITY INVARIANT: hit descriptors carry static metadata only (pattern
+ * name, offset, ≤10 printable chars before the hit) — never the matched
+ * text, and never text at or after the hit point.
+ *
+ * @module jev/gate
+ */
+export interface SecretGateHit {
+    pattern: string;
+    offset: number;
+    context: string;
+}
+/** Minimal logger surface (both sinks optional — bare harnesses have none);
+ *  the gate only ever warns, and a broken logger must not break the gate. */
+export interface GateLogger {
+    warn?: (m: string) => void;
+}
+export declare const BUILTIN_PATTERNS: ReadonlyArray<{
+    name: string;
+    re: RegExp;
+}>;
+/** Literal secrets from the external list file (JEV_SECRET_FILE semantics:
+ *  one entry per line, ≥8 chars, `#` comments skipped, matched at FULL
+ *  length — a >512-char line warns but is never truncated, or everything
+ *  past char 512 would silently escape the gate). */
+export declare function loadExternalSecrets(file: string, log?: GateLogger): string[];
+export declare function currentSecrets(file: string, log?: GateLogger): string[];
+export declare function reloadSecrets(file: string, log?: GateLogger): string[];
+/**
+ * Redacted context: at most 10 printable chars BEFORE the hit plus an
+ * explicit [REDACTED:<pattern>] marker. Content at or after the hit point is
+ * NEVER shown — when a prefix regex under-matches, the secret tail sits
+ * right there. Belt and suspenders: if the matched text or any known
+ * external secret still appears in the context, the whole context collapses
+ * to '[REDACTED]'.
+ */
+export declare function describeHit(pattern: string, offset: number, matched: string, payload: string, externalSecrets?: readonly string[]): SecretGateHit;
+/**
+ * Scan the serialized outbound payload for secrets.
+ * @param payload JSON.stringify({model, state, questions}) — the exact wire body
+ * @param externalSecrets literal secrets from the external list (cached via currentSecrets)
+ * @param externalSource label for hit descriptors (the list file path)
+ */
+export declare function scanForSecrets(payload: string, externalSecrets?: readonly string[], externalSource?: string): SecretGateHit | null;

package/lib/jev/gate.js

@@ -0,0 +1,125 @@
+/**
+ * Outbound secret gate (design 2026-09-25 §3.3) — self-contained port of the
+ * dsh-jev-mcp `server.mjs` mechanism. The COMPLETE serialized request body
+ * (model, state, questions — byte-identical to what goes on the wire) is
+ * scanned for credential patterns BEFORE anything leaves the process; a hit
+ * aborts the call with a structured descriptor that never echoes the secret.
+ *
+ * SECURITY INVARIANT: hit descriptors carry static metadata only (pattern
+ * name, offset, ≤10 printable chars before the hit) — never the matched
+ * text, and never text at or after the hit point.
+ *
+ * @module jev/gate
+ */
+import { readFileSync } from 'node:fs';
+function safeWarn(log, message) {
+    try {
+        log?.warn?.(message);
+    }
+    catch {
+        // contained — diagnostics never take the feature down
+    }
+}
+// Prefix-style patterns require a 20+ char continuation so that merely
+// DISCUSSING a prefix (e.g. "set OPENROUTER_API_KEY to an sk-or-v1- key")
+// never trips the gate — only an actual long token does.
+export const BUILTIN_PATTERNS = [
+    { name: 'jwt', re: /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/ },
+    { name: 'openrouter-key', re: /sk-or-v1-[A-Za-z0-9_-]{20,}/ },
+    { name: 'anthropic-key', re: /sk-ant-[A-Za-z0-9_-]{20,}/ },
+    { name: 'openai-project-key', re: /sk-proj-[A-Za-z0-9_-]{20,}/ },
+    { name: 'openai-sk-key', re: /sk-[A-Za-z0-9]{20,}/ },
+    { name: 'github-token', re: /ghp_[A-Za-z0-9]{20,}/ },
+    { name: 'github-pat', re: /github_pat_[A-Za-z0-9_]{20,}/ },
+    { name: 'gitlab-token', re: /glpat-[A-Za-z0-9_-]{20,}/ },
+    { name: 'slack-token', re: /xox[baprs]-[A-Za-z0-9-]{20,}/ },
+    { name: 'aws-access-key-id', re: /AKIA[0-9A-Z]{16}/ },
+    { name: 'aws-temp-key-id', re: /ASIA[0-9A-Z]{16}/ },
+    { name: 'google-api-key', re: /AIza[A-Za-z0-9_-]{20,}/ },
+    { name: 'private-key-block', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+];
+const MAX_SECRET_LINE = 512; // longer lines WARN; matching ALWAYS uses the full line
+const MIN_EXTERNAL_SECRET = 8; // shorter entries would cause runaway false hits
+/** Literal secrets from the external list file (JEV_SECRET_FILE semantics:
+ *  one entry per line, ≥8 chars, `#` comments skipped, matched at FULL
+ *  length — a >512-char line warns but is never truncated, or everything
+ *  past char 512 would silently escape the gate). */
+export function loadExternalSecrets(file, log) {
+    if (file === '')
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        safeWarn(log, `topics jev: cannot read jevSecretFile (${file}): ${err instanceof Error ? err.message : String(err)}; continuing without it.`);
+        return [];
+    }
+    const secrets = [];
+    raw.split(/\r?\n/).forEach((line, i) => {
+        const s = line.trim();
+        if (s === '' || s.startsWith('#'))
+            return;
+        if (s.length < MIN_EXTERNAL_SECRET) {
+            safeWarn(log, `topics jev: jevSecretFile line ${i + 1} shorter than ${MIN_EXTERNAL_SECRET} chars, skipped (false-positive guard).`);
+            return;
+        }
+        if (s.length > MAX_SECRET_LINE) {
+            safeWarn(log, `topics jev: jevSecretFile line ${i + 1} is ${s.length} chars (> ${MAX_SECRET_LINE}); matching uses the FULL line (no truncation).`);
+        }
+        secrets.push(s);
+    });
+    return secrets;
+}
+// One-time-per-path load, mirroring the reference implementation's
+// load-once-at-startup while staying compatible with the volatile
+// `jevSecretFile` config: an unchanged path is served from the cache (no
+// re-read), a swapped path reloads on the next call. `reloadSecrets` forces
+// a re-read — the `/topics set jev-secret-file` wiring calls it so an
+// in-place content change is picked up too.
+let cache = { file: '', secrets: [] };
+export function currentSecrets(file, log) {
+    if (cache.file !== file)
+        reloadSecrets(file, log);
+    return cache.secrets;
+}
+export function reloadSecrets(file, log) {
+    cache = { file, secrets: loadExternalSecrets(file, log) };
+    return cache.secrets;
+}
+/**
+ * Redacted context: at most 10 printable chars BEFORE the hit plus an
+ * explicit [REDACTED:<pattern>] marker. Content at or after the hit point is
+ * NEVER shown — when a prefix regex under-matches, the secret tail sits
+ * right there. Belt and suspenders: if the matched text or any known
+ * external secret still appears in the context, the whole context collapses
+ * to '[REDACTED]'.
+ */
+export function describeHit(pattern, offset, matched, payload, externalSecrets = []) {
+    const before = payload.slice(Math.max(0, offset - 10), offset).replace(/[^\x20-\x7e]/g, '.'); // keep it printable
+    const context = `${before}[REDACTED:${pattern}]`;
+    if (context.includes(matched) || externalSecrets.some((s) => s !== '' && context.includes(s))) {
+        return { pattern, offset, context: '[REDACTED]' };
+    }
+    return { pattern, offset, context };
+}
+/**
+ * Scan the serialized outbound payload for secrets.
+ * @param payload JSON.stringify({model, state, questions}) — the exact wire body
+ * @param externalSecrets literal secrets from the external list (cached via currentSecrets)
+ * @param externalSource label for hit descriptors (the list file path)
+ */
+export function scanForSecrets(payload, externalSecrets = [], externalSource = '') {
+    for (const { name, re } of BUILTIN_PATTERNS) {
+        const m = re.exec(payload);
+        if (m)
+            return describeHit(name, m.index, m[0], payload, externalSecrets);
+    }
+    for (const secret of externalSecrets) {
+        const idx = payload.indexOf(secret);
+        if (idx !== -1) {
+            return describeHit(externalSource !== '' ? `external(${externalSource})` : 'external', idx, secret, payload, externalSecrets);
+        }
+    }
+    return null;
+}

package/lib/jev/log.d.ts

@@ -0,0 +1,65 @@
+/**
+ * decisions.jsonl — System One usage/optimization telemetry (design
+ * 2026-09-25 §6), always on while jevEnabled is on. Lives beside the ilog at
+ * `<bundle>/meta/decisions.jsonl` under the same discipline: 512KB
+ * auto-compaction keeping the most recent quarter, line JSON, and write
+ * failures swallowed silently — fail-open extends to the stats itself.
+ *
+ * REDACTION INVARIANT (§6.1): metadata and probabilities only — slug/pair
+ * hash/question type/score/latency/token count. NEVER the state text or
+ * conclusion bodies. Writers copy an explicit field whitelist, so extra
+ * fields on caller objects cannot leak into the file.
+ *
+ * @module jev/log
+ */
+import type { JevBand } from './thresholds.ts';
+export type JevLane = 'slowlane-rerank' | 'consolidate-prefilter' | 'fastgate-shadow';
+export type JevOutcome = 'ok' | 'timeout' | 'network' | 'http_4xx' | 'http_5xx' | 'bad_json' | 'secret_gate_blocked' | 'missing_key'
+/** Local pre-flight refusal (e.g. questions violate the decisions/openrouter
+ *  wire contract) — nothing was sent. Reserved outcome beyond §6.2's v1 list. */
+ | 'invalid_request';
+export interface JevUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+/** Call layer (§6.2): one row per HTTP call, failures included — the
+ *  fallback rate is the health metric, so failed calls must be counted. */
+export interface JevCallRecord {
+    at: string;
+    lane: JevLane;
+    backend: string;
+    model: string;
+    questionCount: number;
+    stateChars: number;
+    latencyMs: number;
+    usage: JevUsage | null;
+    outcome: JevOutcome;
+    fallback: boolean;
+}
+/** Verdict layer (§6.2): one row per question, batch requests expanded.
+ *  `agree` reconciles the fast-gate shadow against the lexical disposition
+ *  (wouldBlock = lexical let it through but jev landed in the veto band —
+ *  the other half of the calibration goldmine). */
+export interface JevVerdictRecord {
+    at: string;
+    lane: JevLane;
+    questionId: string;
+    qtype: 'noul' | 'choice' | 'score';
+    /** Candidate reference without content: `slug:xxx` | `pair:hash3`. */
+    ref: string;
+    /** §6.2 digest — stable key for the repeat-decision-rate analysis. */
+    digest: string;
+    probability: number;
+    band: JevBand;
+    agree: 'hit' | 'nearFloor' | 'gate-blocked' | 'wouldBlock' | 'n/a';
+}
+export declare function decisionsFile(root: string): string;
+/** digest(state, questionId, instructions): `h1:` + first 16 hex of
+ *  sha256(state + NUL + questionId + NUL + instructions) — the key the
+ *  repeat-decision-rate analysis joins on. */
+export declare function digestFor(state: string, questionId: string, instructions: string): string;
+/** Call-layer row. Field whitelist enforced here: anything extra on the
+ *  caller's object is dropped, so no state/conclusion text can sneak in. */
+export declare function logCall(rec: JevCallRecord): Promise<void>;
+/** Verdict-layer rows (batch expanded by the caller). */
+export declare function logVerdicts(recs: readonly JevVerdictRecord[]): Promise<void>;

package/lib/jev/log.js

@@ -0,0 +1,119 @@
+/**
+ * decisions.jsonl — System One usage/optimization telemetry (design
+ * 2026-09-25 §6), always on while jevEnabled is on. Lives beside the ilog at
+ * `<bundle>/meta/decisions.jsonl` under the same discipline: 512KB
+ * auto-compaction keeping the most recent quarter, line JSON, and write
+ * failures swallowed silently — fail-open extends to the stats itself.
+ *
+ * REDACTION INVARIANT (§6.1): metadata and probabilities only — slug/pair
+ * hash/question type/score/latency/token count. NEVER the state text or
+ * conclusion bodies. Writers copy an explicit field whitelist, so extra
+ * fields on caller objects cannot leak into the file.
+ *
+ * @module jev/log
+ */
+import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { metaDir, resolveBundleRoot } from "../paths.js";
+const COMPACT_LIMIT = 512 * 1024; // ~512KB cap, same as the ilog sidecars
+export function decisionsFile(root) {
+    return join(metaDir(root), 'decisions.jsonl');
+}
+function liveFile() {
+    return decisionsFile(resolveBundleRoot());
+}
+/** digest(state, questionId, instructions): `h1:` + first 16 hex of
+ *  sha256(state + NUL + questionId + NUL + instructions) — the key the
+ *  repeat-decision-rate analysis joins on. */
+export function digestFor(state, questionId, instructions) {
+    const h = createHash('sha256');
+    h.update(state);
+    h.update('\u0000');
+    h.update(questionId);
+    h.update('\u0000');
+    h.update(instructions);
+    return `h1:${h.digest('hex').slice(0, 16)}`;
+}
+// Serialized like the store's write queue: single-record appends are
+// line-atomic anyway, but the compaction rewrite must not interleave with
+// an append.
+let queue = Promise.resolve();
+function enqueue(op) {
+    const run = queue.then(op, op);
+    queue = run.catch(() => undefined);
+    return run;
+}
+/** All write failures die HERE — never upstream. */
+async function appendJsonl(lines) {
+    await enqueue(async () => {
+        try {
+            const file = liveFile();
+            await mkdir(dirname(file), { recursive: true });
+            await appendFile(file, lines.map((l) => `${l}\n`).join(''), 'utf8');
+            await compactIfNeeded(file);
+        }
+        catch {
+            // fail-open: a broken stats sink must never break the feature (§6.1)
+        }
+    });
+}
+// store.ts compactInjectionsIfNeeded pattern: ~512KB cap; keep the most
+// recent quarter when exceeded (headroom for the next window).
+async function compactIfNeeded(file) {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch {
+        return;
+    }
+    if (raw.length <= COMPACT_LIMIT)
+        return;
+    const lines = raw.split('\n').filter((l) => l.trim() !== '');
+    const keep = lines.slice(-Math.max(1, Math.floor(lines.length / 4)));
+    const tmp = `${file}.tmp-${randomUUID()}`;
+    try {
+        await writeFile(tmp, keep.map((l) => `${l}\n`).join(''), 'utf8');
+        await rename(tmp, file);
+    }
+    catch {
+        // swallow — the next append retries the compaction
+    }
+}
+/** Call-layer row. Field whitelist enforced here: anything extra on the
+ *  caller's object is dropped, so no state/conclusion text can sneak in. */
+export async function logCall(rec) {
+    await appendJsonl([
+        JSON.stringify({
+            at: rec.at,
+            lane: rec.lane,
+            backend: rec.backend,
+            model: rec.model,
+            questionCount: rec.questionCount,
+            stateChars: rec.stateChars,
+            latencyMs: rec.latencyMs,
+            usage: rec.usage === null
+                ? null
+                : { input_tokens: rec.usage.input_tokens, output_tokens: rec.usage.output_tokens },
+            outcome: rec.outcome,
+            fallback: rec.fallback,
+        }),
+    ]);
+}
+/** Verdict-layer rows (batch expanded by the caller). */
+export async function logVerdicts(recs) {
+    if (recs.length === 0)
+        return;
+    await appendJsonl(recs.map((rec) => JSON.stringify({
+        at: rec.at,
+        lane: rec.lane,
+        questionId: rec.questionId,
+        qtype: rec.qtype,
+        ref: rec.ref,
+        digest: rec.digest,
+        probability: rec.probability,
+        band: rec.band,
+        agree: rec.agree,
+    })));
+}

package/lib/jev/thresholds.d.ts

@@ -0,0 +1,21 @@
+/**
+ * System One decision bands (design 2026-09-25 §5).
+ *
+ * The numbers are CALIBRATED — single-case A/B plus a 383-case threshold
+ * sweep (2026-09-25) — and bound to the batch wire protocol (protocol-drift
+ * evidence: the same case scores differently single vs batch). Changing the
+ * protocol requires a re-sweep; do not tune these in place.
+ *
+ * @module jev/thresholds
+ */
+/** Slow-lane rerank (候选问): adopt ≥ 0.60, strong-veto < 0.10. */
+export declare const RERANK_ADOPT = 0.6;
+export declare const RERANK_FALLBACK = 0.1;
+/** Consolidation prefilter (pair 问「同一问题吗」): adopt ≥ 0.50, veto < 0.15. */
+export declare const MERGE_PAIR_ADOPT = 0.5;
+export declare const MERGE_PAIR_FALLBACK = 0.15;
+export type JevBand = 'adopt' | 'record' | 'fallback';
+export type JevBandKind = 'rerank' | 'mergePair';
+/** Map a noul probability to its band: adopt → act on it, record → only log
+ *  it, fallback → hard veto back to the lexical/legacy behavior. */
+export declare function band(probability: number, kind: JevBandKind): JevBand;

package/lib/jev/thresholds.js

@@ -0,0 +1,27 @@
+/**
+ * System One decision bands (design 2026-09-25 §5).
+ *
+ * The numbers are CALIBRATED — single-case A/B plus a 383-case threshold
+ * sweep (2026-09-25) — and bound to the batch wire protocol (protocol-drift
+ * evidence: the same case scores differently single vs batch). Changing the
+ * protocol requires a re-sweep; do not tune these in place.
+ *
+ * @module jev/thresholds
+ */
+/** Slow-lane rerank (候选问): adopt ≥ 0.60, strong-veto < 0.10. */
+export const RERANK_ADOPT = 0.6;
+export const RERANK_FALLBACK = 0.1;
+/** Consolidation prefilter (pair 问「同一问题吗」): adopt ≥ 0.50, veto < 0.15. */
+export const MERGE_PAIR_ADOPT = 0.5;
+export const MERGE_PAIR_FALLBACK = 0.15;
+/** Map a noul probability to its band: adopt → act on it, record → only log
+ *  it, fallback → hard veto back to the lexical/legacy behavior. */
+export function band(probability, kind) {
+    const floor = kind === 'rerank' ? RERANK_FALLBACK : MERGE_PAIR_FALLBACK;
+    const adopt = kind === 'rerank' ? RERANK_ADOPT : MERGE_PAIR_ADOPT;
+    if (probability >= adopt)
+        return 'adopt';
+    if (probability >= floor)
+        return 'record';
+    return 'fallback';
+}

package/lib/legacy-import.d.ts

@@ -50,6 +50,21 @@ export interface LegacyImportInput {
     logger?: LegacyImportLogger | undefined;
     /** Current effective value for one legacy key (Volatile ref `.get()` at the call site). */
     getCurrent(key: LegacyKey): unknown;
+    /**
+     * Retry budget for `settings.update`. The host serializes profile writes
+     * (settings.update → dsh-config-editor) behind the `<profile>/package.json`
+     * writer lock with a 2s per-call deadline, and during BOOT the host itself
+     * holds that lock while preparing the profile — a single bare call almost
+     * always times out (2026-09-25 incident: the import failed EVERY boot and
+     * the migration never converged). Defaults to 5 attempts 2s apart; a
+     * permanently orphaned lock (a SIGKILLed host never releases it — orphan
+     * recovery is an operator action) still exhausts the budget and stays
+     * retry-worthy. Tests shrink this to keep the suite fast.
+     */
+    updateRetry?: {
+        attempts: number;
+        delayMs: number;
+    } | undefined;
 }
 export type LegacyImportOutcome = 'imported' | 'no-op' | 'no-legacy' | 'no-section' | 'marker-exists' | 'no-settings' | 'update-failed';
 export interface LegacyImportResult {