@aiwayds/dsh-topics-memory 0.18.2 → 0.20.0

package/lib/jev/client.js

@@ -0,0 +1,225 @@
+/**
+ * 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) {
+    // Pace-maker override: a synthetic laya backend (no key — the auth header
+    // carries a placeholder the local server ignores; the secret gate and the
+    // call-layer row still run, tagged backend='laya').
+    const backend = args.overrides
+        ? {
+            name: 'laya',
+            family: 'systemone',
+            endpoint: args.overrides.endpoint,
+            defaultModel: args.overrides.model,
+            keyEnv: '',
+            keychainService: '',
+            keychainByDefault: false,
+        }
+        : resolveBackend(args.config.jevBackend);
+    // '' is the sentinel; undefined (bare harnesses) resolves to the default too
+    const model = args.overrides ? args.overrides.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. The laya
+    //    pace-maker skips resolution entirely (local, no auth).
+    const key = args.overrides ? 'laya-local' : 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/dual.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Dual-run pace-maker (design §3.4, added 09-27): fire the configured
+ * backend AND the local laya-serve endpoint in parallel on every jev call.
+ *
+ *  - the PRIMARY answer drives the decision whenever it is ok;
+ *  - the laya answer is always logged (its own call-layer row tagged
+ *    backend='laya' plus verdict rows) — a free, permanently running
+ *    laya-vs-jev comparison on identical questions;
+ *  - TELEMETRY-ONLY: laya NEVER drives a decision. On real data its
+ *    within-batch top-1 agreed with the primary 0/14 and its negatives sit in
+ *    the same band as its positives (0.63-0.76), so both its relative ranking
+ *    and its absolute scores are unusable (4-way bench, 09-27). A primary
+ *    FAILURE (cold-start spike, timeout, 5xx…) is therefore a failure even
+ *    when laya answered: the result stays ok:false and the caller fails open
+ *    (ADR 0018). `layaResult` still carries the comparison answers so the
+ *    caller can log the laya verdict rows;
+ *  - laya not running = a refused connection in milliseconds — the switch
+ *    can stay on unconditionally.
+ *
+ * The consolidation prefilter deliberately does NOT ride this wrapper: laya's
+ * Chinese noul is the weak spot, and a wrong veto silently skips real
+ * consolidation work. Prefilter keeps its plain fail-open.
+ *
+ * @module jev/dual
+ */
+import type { JevAskArgs, JevAskConfig, JevAskResult } from './client.ts';
+/** Default local laya-serve endpoint (laya repo: `laya[serve]` binds 8000). */
+export declare const DEFAULT_LAYA_URL = "http://127.0.0.1:8000/v1/systemone";
+export interface JevDualConfig extends JevAskConfig {
+    /** Pace-maker switch (default OFF — zero extra requests when false). */
+    jevLayaFallback: boolean;
+    /** Local laya-serve systemone endpoint. */
+    jevLayaUrl: string;
+}
+export interface JevDualArgs extends Omit<JevAskArgs, 'config'> {
+    config: JevDualConfig;
+}
+export type JevDualSource = 'primary' | 'laya';
+export type JevDualResult = JevAskResult & {
+    /** Which backend ANSWERED for the record: 'primary' when the primary
+     *  answered (the only case that may drive), 'laya' when it failed and the
+     *  pace-maker covered for telemetry only. */
+    source: JevDualSource;
+    /** The pace-maker's own result when it ran (null when the switch is off),
+     *  always logged by jevAsk via the overrides hook. */
+    layaResult: JevAskResult | null;
+};
+export declare function jevAskDual(args: JevDualArgs): Promise<JevDualResult>;

package/lib/jev/dual.js

@@ -0,0 +1,47 @@
+/**
+ * Dual-run pace-maker (design §3.4, added 09-27): fire the configured
+ * backend AND the local laya-serve endpoint in parallel on every jev call.
+ *
+ *  - the PRIMARY answer drives the decision whenever it is ok;
+ *  - the laya answer is always logged (its own call-layer row tagged
+ *    backend='laya' plus verdict rows) — a free, permanently running
+ *    laya-vs-jev comparison on identical questions;
+ *  - TELEMETRY-ONLY: laya NEVER drives a decision. On real data its
+ *    within-batch top-1 agreed with the primary 0/14 and its negatives sit in
+ *    the same band as its positives (0.63-0.76), so both its relative ranking
+ *    and its absolute scores are unusable (4-way bench, 09-27). A primary
+ *    FAILURE (cold-start spike, timeout, 5xx…) is therefore a failure even
+ *    when laya answered: the result stays ok:false and the caller fails open
+ *    (ADR 0018). `layaResult` still carries the comparison answers so the
+ *    caller can log the laya verdict rows;
+ *  - laya not running = a refused connection in milliseconds — the switch
+ *    can stay on unconditionally.
+ *
+ * The consolidation prefilter deliberately does NOT ride this wrapper: laya's
+ * Chinese noul is the weak spot, and a wrong veto silently skips real
+ * consolidation work. Prefilter keeps its plain fail-open.
+ *
+ * @module jev/dual
+ */
+import { jevAsk } from "./client.js";
+/** Default local laya-serve endpoint (laya repo: `laya[serve]` binds 8000). */
+export const DEFAULT_LAYA_URL = 'http://127.0.0.1:8000/v1/systemone';
+export async function jevAskDual(args) {
+    if (args.config.jevLayaFallback !== true) {
+        const r = await jevAsk(args);
+        return { ...r, source: 'primary', layaResult: null };
+    }
+    const layaArgs = {
+        ...args,
+        config: { ...args.config, jevModel: 'laya-rl-agent' },
+        overrides: { endpoint: args.config.jevLayaUrl || DEFAULT_LAYA_URL, model: 'laya-rl-agent' },
+    };
+    const [primary, laya] = await Promise.all([jevAsk(args), jevAsk(layaArgs)]);
+    if (primary.ok)
+        return { ...primary, source: 'primary', layaResult: laya };
+    // REVISED 09-27 (real-data evidence: within-batch top-1 agreement 0/14):
+    // a primary failure is a FAILURE even when the pace-maker answered — laya
+    // is telemetry-only. The caller fails open (ADR 0018); layaResult carries
+    // the comparison answers so the caller can still log laya verdict rows.
+    return { ok: false, outcome: primary.outcome, message: primary.message, latencyMs: primary.latencyMs, source: 'laya', layaResult: laya };
+}

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,73 @@
+/**
+ * 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';
+    /** Which backend produced this verdict: 'primary' (default — the configured
+     *  backend) or 'laya' (the local pace-maker). Design §3.4. */
+    backend?: string;
+    /** True when this row's source DROVE the decision because the primary
+     *  backend was unavailable (degraded mode). Comparison rows from the
+     *  pace-maker are degraded=false; laya rows are excluded from ECE either
+     *  way (uncalibrated probabilities). */
+    degraded?: boolean;
+}
+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>;