@aiwayds/dsh-topics-memory 0.18.1 → 0.19.0

package/lib/consolidate.js

@@ -23,11 +23,21 @@
  *  - the cadence stamp (meta/consolidate-state.json) advances only when the
  *    model actually evaluated at least one cluster — a run that died on the
  *    first call leaves the stamp alone, and the next session start retries.
+ *  - jev prefilter (design 2026-09-25 §2, default-off): with jevEnabled the
+ *    cluster first answers to ONE cheap System One batch (≤6 questions: the
+ *    top-5 similar pairs each ask 「同一问题吗」, plus a record-only
+ *    cluster-level 「值得动吗」). Only when ≥1 pair reaches the adopt band
+ *    (≥0.50) does the cluster go to the LLM — an all-non-adopt cluster skips
+ *    the model call entirely. Any jev failure fails open to today's behavior;
+ *    the merge conclusion generation itself stays LLM.
  *
  * @module consolidate
  */
 import * as okf from "./okf.js";
 import { parseOps } from "./distill.js";
+import { jevAsk } from "./jev/client.js";
+import { band } from "./jev/thresholds.js";
+import { digestFor, logVerdicts } from "./jev/log.js";
 /** Below this pairwise Jaccard two topics never share a cluster. */
 const CLUSTER_THRESHOLD = 0.3;
 /** Clusters are capped — a giant cluster drowns the model in candidates. */
@@ -39,6 +49,12 @@ const MAX_OPS_PER_RUN = 12;
 /** Conclusion chars fed per topic in a cluster payload. */
 const CONCLUSION_SNIPPET_CHARS = 600;
 const CONSOLIDATE_MAX_TOKENS = 2500;
+/**
+ * Pair questions per cluster batch (design §2: k≤5, so with the record-only
+ * cluster-level question a batch stays ≤6 问/簇 — the measured cheap end of
+ * the batch protocol).
+ */
+const PREFILTER_TOP_PAIRS = 5;
 export const CONSOLIDATE_SYSTEM_PROMPT = [
     '你是 topic 记忆库的整理引擎（园丁）。输入是一个候选簇：若干条可能相近的已有 topic（JSON，含 slug/标题/状态/标签/结论摘要）。',
     '任务：判断簇内有没有值得整理的动作，输出严格 JSON：{"ops":[...]}，不要任何其他文字或代码块解释。只允许四类 op：',
@@ -142,14 +158,90 @@ export function clusterTopics(entries, threshold = CLUSTER_THRESHOLD) {
                 .sort((a, b) => (degree.get(b) ?? 0) - (degree.get(a) ?? 0))
                 .slice(0, MAX_CLUSTER_SIZE);
         }
+        // Reuse the clustering edges for the prefilter's pair list: positions map
+        // into the (possibly capped) kept order, best similarity first. Edges
+        // lost to the cap — or transitively-clustered pairs below threshold — are
+        // not pair candidates; a capped cluster with no inner edge left simply
+        // has no pairs (the prefilter then behaves as today).
+        const position = new Map();
+        kept.forEach((original, pos) => position.set(original, pos));
+        const pairs = [];
+        for (const [key, s] of scores) {
+            const i = Math.floor(key / entries.length);
+            const j = key % entries.length;
+            const pi = position.get(i);
+            const pj = position.get(j);
+            if (pi === undefined || pj === undefined)
+                continue;
+            pairs.push({ i: pi, j: pj, similarity: s });
+        }
+        pairs.sort((a, b) => b.similarity - a.similarity);
         clusters.push({
             entries: kept.map((i) => entries[i]),
             similarity: peak,
+            pairs,
         });
     }
     clusters.sort((a, b) => b.similarity - a.similarity);
     return clusters;
 }
+// --- Jev prefilter protocol (design 2026-09-25 §2, sweep-aligned) ------------
+// The merge-pair thresholds (band(..., 'mergePair')) are BOUND to the t4
+// threshold-sweep batch protocol: shared state, two-sided criteria, two
+// 600-char side excerpts per question. Absolute scores are protocol-sensitive
+// (t4 §4: the same case scored 0.15 / 0.60 / 0.71 across protocols), so the
+// texts below are copied VERBATIM from
+// .wayfinder/research/t4-labeling-kit/threshold-sweep.mjs (MRG_STATE /
+// MRG_CRITERIA / mrgInstructions) — changing any of them requires a re-sweep
+// of the lines, do not tune in place.
+const PREFILTER_STATE = [
+    '背景：你在为一个个人记忆库做簇内 merge 校准。整理（consolidate）时会把讲同一问题的多个 topic 合并成一份；误并会造成信息丢失，漏并会造成库内冗余与后续漂移。',
+    '判定标准：同一问题指两条记录的是同一件事——同一 bug/特性/任务的不同阶段、两面或后续进展，合并保留一份不丢实质信息。相邻但独立不算：两条各自成立、合并会丢失各自信息（如命名澄清 vs 机制对照、修不同 bug 的相邻提交、不同仓库的两次发版）。',
+].join('\n');
+const PAIR_CRITERIA = {
+    true: '同一问题——两条记录的是同一件事的不同阶段/两面/后续进展，合并保留一份不丢实质信息',
+    false: '相邻但独立——各自成立，合并会丢失各自信息（如命名澄清 vs 机制对照、修不同 bug、不同仓库发版）',
+};
+// Cluster-level 「值得动吗」 — v1 records it only, never gates (design §2:
+// 簇级问只记不门控，无扫描数据).
+const CLUSTER_CRITERIA = {
+    true: '值得整理——簇内存在值得动作的条目（重复可并、draft 已稳定、已被取代、元数据失准），动作有实质收益',
+    false: '不值得动——条目各自成立，或任何整理动作都不会带来实质收益',
+};
+/** Pair question body — the sweep's mrgInstructions: two sides of
+ *  title/tags/conclusion excerpt (ClusterEntry.conclusion is already capped
+ *  at CONCLUSION_SNIPPET_CHARS = the sweep's 600-char protocol). */
+function pairInstructions(a, b) {
+    const side = (t, name) => [`## topic ${name}`, `- title: ${t.title}`, `- tags: ${t.tags.join(', ')}`, '- conclusion:', t.conclusion].join('\n');
+    return [side(a, 'A'), '', side(b, 'B'), '', '综合以上材料判断：这两个 topic 讲的是同一个问题、应当合并吗？'].join('\n');
+}
+/** Cluster-level question body — titles/status/tags only, no conclusions. */
+function clusterInstructions(cluster) {
+    const lines = cluster.entries.map((e) => `- ${e.title}（${e.status}，tags: ${e.tags.join(', ')}）`);
+    return [
+        '## 候选簇内的 topic',
+        ...lines,
+        '',
+        '综合以上材料判断：这一簇值得一次整理动作吗（merge/promote/deprecate/refresh 任一）？',
+    ].join('\n');
+}
+/**
+ * The prefilter's jev config slice — undefined unless jevEnabled is explicitly
+ * true (default-off master switch: false ⇒ the whole branch is dead code and
+ * today's behavior runs untouched). Optional keys fall back to their
+ * documented defaults (config.ts: the bare-harness DEFAULTS literal predates
+ * them; consumers treat undefined as the default).
+ */
+function jevConfigOf(cfg) {
+    if (cfg.jevEnabled !== true)
+        return undefined;
+    return {
+        jevBackend: cfg.jevBackend ?? 'zen',
+        jevModel: cfg.jevModel ?? '',
+        jevTimeoutMs: cfg.jevTimeoutMs ?? 3000,
+        jevSecretFile: cfg.jevSecretFile ?? '',
+    };
+}
 // --- Deprecated-TTL housekeeping (local rule, no model) ----------------------
 /**
  * Drop `deprecated` topics older than `ttlDays` — pure housekeeping, never
@@ -191,9 +283,15 @@ export class Consolidator {
     inFlight;
     service;
     caller;
-    constructor(service, caller) {
+    askJev;
+    /** Best-effort host-logger sink (warn-style); undefined = stay silent,
+     *  aligned with the lane's quiet discipline for success/no-clusters. */
+    note;
+    constructor(service, caller, askJev = jevAsk, note) {
         this.service = service;
         this.caller = caller;
+        this.askJev = askJev;
+        this.note = note;
     }
     get configured() {
         return this.caller !== undefined;
@@ -273,9 +371,22 @@ export class Consolidator {
         let evaluated = 0;
         let fatal;
         let failureDetail;
+        // jev prefilter (design §2): one cheap System One batch decides whether a
+        // cluster is worth the LLM call at all. undefined = jevEnabled off ⇒ the
+        // whole branch never executes and behavior is exactly as before.
+        const jev = jevConfigOf(this.service.cfg);
+        let prefilterSkipped = 0;
         for (const cluster of clusters) {
             if (calls >= MAX_MODEL_CALLS_PER_RUN)
                 break;
+            if (jev !== undefined) {
+                const pf = await this.prefilterCluster(jev, cluster);
+                if (!pf.proceed) {
+                    prefilterSkipped += 1;
+                    this.note?.(`topics consolidate: 前置过滤跳过簇（pair 均未达 adopt 线）：${cluster.entries.map((e) => e.slug).join('、')}`);
+                    continue;
+                }
+            }
             const outcome = await this.runCluster(sessionId, cluster);
             calls += 1;
             if (outcome.fatal !== undefined) {
@@ -334,6 +445,7 @@ export class Consolidator {
         const tail = [
             applied.dropped > 0 ? `丢弃 ${applied.dropped} 个无效 op` : undefined,
             `${calls} 次模型调用（评估 ${evaluated} 簇 / 候选 ${clusters.length} 簇）`,
+            prefilterSkipped > 0 ? `前置过滤跳过 ${prefilterSkipped} 簇` : undefined,
             fatal !== undefined ? `中途失败：${failureDetail ?? 'unknown'}` : undefined,
             stampNote === '' ? undefined : stampNote.replace(/^；/, ''),
         ]
@@ -378,6 +490,88 @@ export class Consolidator {
         }
         return clusterTopics(entries).slice(0, MAX_MODEL_CALLS_PER_RUN);
     }
+    /**
+     * One jev request per cluster (design 2026-09-25 §2 整理 lane 前置). The
+     * top-k similar pairs (k ≤ {@link PREFILTER_TOP_PAIRS}, edges reused from
+     * clustering) each get a pair noul question 「同一问题吗」; one record-only
+     * cluster-level 「值得动吗」 rides along (固定 band='record', never gates).
+     * Gate: ≥1 pair in the adopt band → the cluster goes to the LLM; all pairs
+     * below → skipped (省调用). Any jev failure proceeds fail-open — the
+     * call-layer telemetry row (outcome !== 'ok' marks the fail-open) was already written by jevAsk
+     * itself; only the verdict layer is ours here (agree='n/a', nothing lexical
+     * to reconcile against on this lane).
+     */
+    async prefilterCluster(jev, cluster) {
+        const pairs = cluster.pairs.slice(0, PREFILTER_TOP_PAIRS);
+        // No local similarity evidence (e.g. a capped cluster whose edges all
+        // fell outside) — behave exactly as today, zero jev calls.
+        if (pairs.length === 0)
+            return { proceed: true, failOpen: false };
+        const questions = {};
+        const metas = [];
+        pairs.forEach((p, idx) => {
+            const a = cluster.entries[p.i];
+            const b = cluster.entries[p.j];
+            const instructions = pairInstructions(a, b);
+            const questionId = `p${idx + 1}`;
+            questions[questionId] = { type: 'noul', instructions, criteria: PAIR_CRITERIA };
+            metas.push({ questionId, ref: `pair:${a.slug}|${b.slug}`, instructions, gating: true });
+        });
+        const clusterQuestion = clusterInstructions(cluster);
+        questions['cluster'] = { type: 'noul', instructions: clusterQuestion, criteria: CLUSTER_CRITERIA };
+        metas.push({
+            questionId: 'cluster',
+            ref: `cluster:${cluster.entries[0]?.slug ?? ''}`,
+            instructions: clusterQuestion,
+            gating: false,
+        });
+        const r = await this.askJev({
+            state: PREFILTER_STATE,
+            questions,
+            config: jev,
+            lane: 'consolidate-prefilter',
+            fallback: false,
+            // fallback stays FALSE at call time (jevAsk writes before the outcome
+            // is known); fail-open occurrence = outcome !== 'ok' — this lane's
+            // "cluster goes to the LLM as today" is deterministic per ADR 0018.
+        });
+        if (!r.ok)
+            return { proceed: true, failOpen: true };
+        const at = new Date().toISOString();
+        const recs = [];
+        let adopt = false;
+        let failOpen = false;
+        for (const meta of metas) {
+            // Answer shape per the sweep protocol: noul answers carry the
+            // probability on the `noul` field; anything else is unusable.
+            const raw = r.answers[meta.questionId]?.noul;
+            if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+                // A gate question without a usable score must never veto the cluster.
+                if (meta.gating)
+                    failOpen = true;
+                continue;
+            }
+            const probability = Math.min(1, Math.max(0, raw));
+            const verdictBand = meta.gating ? band(probability, 'mergePair') : 'record';
+            if (verdictBand === 'adopt')
+                adopt = true;
+            recs.push({
+                at,
+                lane: 'consolidate-prefilter',
+                questionId: meta.questionId,
+                qtype: 'noul',
+                ref: meta.ref,
+                digest: digestFor(PREFILTER_STATE, meta.questionId, meta.instructions),
+                probability,
+                band: verdictBand,
+                agree: 'n/a',
+            });
+        }
+        await logVerdicts(recs);
+        if (failOpen)
+            return { proceed: true, failOpen: true };
+        return { proceed: adopt, failOpen: false };
+    }
     /** One model call over one cluster, ops shape-validated but not yet applied. */
     async runCluster(sessionId, cluster) {
         const caller = this.caller;

package/lib/index.d.ts

@@ -113,6 +113,11 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     deprecatedTtlDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
     usageBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
     pushDebounceSeconds: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    jevEnabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    jevBackend: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    jevModel: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    jevTimeoutMs: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    jevSecretFile: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     repo: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
     autoInject: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
@@ -140,6 +145,11 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     deprecatedTtlDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
     usageBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
     pushDebounceSeconds: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    jevEnabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    jevBackend: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    jevModel: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    jevTimeoutMs: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    jevSecretFile: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
 }>>, "plain">;
 /** Live config reference as a 0.1.7 host passes it (cron / mcp-adapter
  * spelling): `.get()` snapshots the current value — the host swaps the

package/lib/index.js

@@ -317,6 +317,7 @@ export async function apply(ctx, config = {}) {
         },
     });
     const agents = () => ctx.agents;
+    const fastGateBySession = new Map();
     // SYNCHRONOUS retrieval: the spliced event dispatches before prompt
     // assembly, and the context() provider reads the assembled digest
     // synchronously — an async round would always lose this race.
@@ -366,12 +367,52 @@ export async function apply(ctx, config = {}) {
                 for (const slug of r.slowIncluded)
                     marked.add(slug);
             }
+            // Fastgate shadow capture (design §2 row 3): this round's candidates with
+            // their lexical dispositions (retrieval.ts split: gate-blocked rides the
+            // near-miss reasons). Pure metadata on an already-built result — no hot
+            // path cost beyond the array literal, and hard-gated on the master switch.
+            if (cfg.jevEnabled === true && r.outcome.rosterSize > 0) {
+                fastGateBySession.set(sessionId, {
+                    query,
+                    candidates: [
+                        ...r.outcome.hits.map((h) => ({ slug: h.slug, disposition: 'hit' })),
+                        ...r.outcome.nearMisses.map((nm) => ({
+                            slug: nm.slug,
+                            disposition: nm.reasons.includes('gate-blocked') ? 'gate-blocked' : 'nearFloor',
+                        })),
+                    ],
+                });
+            }
             state.injectionText = r.text;
         }
         catch {
             // Contained: a retrieval failure must never break the turn.
         }
     }
+    /**
+     * Fastgate shadow trigger: consumes the spliced-time capture and hands it to
+     * the lane's shadow entry (which applies the jevEnabled / cadence gates and
+     * serializes behind a same-session produce pipeline). One audit per round —
+     * the capture is consumed here.
+     */
+    function dispatchFastGateShadow(sessionId) {
+        try {
+            if (cfgNow().jevEnabled !== true)
+                return;
+            const captured = fastGateBySession.get(sessionId);
+            if (captured === undefined)
+                return;
+            fastGateBySession.delete(sessionId);
+            slowLane.dispatchFastGateShadow(sessionId, {
+                query: captured.query,
+                candidates: captured.candidates,
+                turnId: observer.turnCountOf(sessionId),
+            });
+        }
+        catch {
+            // contained — the shadow must never break the event handler
+        }
+    }
     /**
      * Slow-lane production trigger at turn/end (v4 §4.2). Host-side gates live
      * here: subagent sessions never run the lane (hard guard, independent of
@@ -387,8 +428,12 @@ export async function apply(ctx, config = {}) {
                 return;
             if (isDelegated(agents()?.get(sessionId)))
                 return;
-            if (distiller.hasPending(sessionId))
+            if (distiller.hasPending(sessionId)) {
+                // The lane yields to the distill run — but the shadow shares no LLM
+                // route, so it still fires on this sampled trigger.
+                dispatchFastGateShadow(sessionId);
                 return;
+            }
             // Same trigger-time capture the distill trigger uses: the agent's
             // scoped llm is alive NOW, and the lane's caller reads the captured
             // entry lazily inside its async pipeline (released via the
@@ -418,6 +463,10 @@ export async function apply(ctx, config = {}) {
                     return merged;
                 })(),
             });
+            // Same trigger, after the dispatch call: the shadow serializes behind
+            // the produce pipeline (rerank 完成后) or runs standalone when the
+            // dispatch produced nothing (无慢道任务时独立跑).
+            dispatchFastGateShadow(sessionId);
         }
         catch {
             // contained — the lane must never break the event handler
@@ -485,7 +534,7 @@ export async function apply(ctx, config = {}) {
     // Consolidation lane (整理): same caller/route as distill, global single
     // flight inside. Reads the pool and merges/promotes/deprecates/refreshes;
     // cadence-gated at session start, manual via /topics consolidate.
-    const consolidator = new Consolidator(service, caller);
+    const consolidator = new Consolidator(service, caller, undefined, warn);
     // ---- Observer (M2) ----
     // Trigger runs are fire-and-forget everywhere now — including the exit
     // one. Observations are write-through on disk, so a run the process exits
@@ -617,6 +666,7 @@ export async function apply(ctx, config = {}) {
             // fresh process has no dedup registry, so allow re-injection.
             injectedBySession.delete(sessionId);
             slowLane.clear(sessionId);
+            fastGateBySession.delete(sessionId);
         }
         observer.onSessionEvent(sessionId, event.type, event.data);
         // AFTER the observer processed the turn (turnCount already bumped, so
@@ -651,6 +701,7 @@ export async function apply(ctx, config = {}) {
             observer.onSessionEvent(sessionId, name, undefined);
             injectedBySession.delete(sessionId);
             slowLane.clear(sessionId);
+            fastGateBySession.delete(sessionId);
             // A teardown-triggered run (session-end distill) reads the payload
             // capture lazily: drop the entry here only when no run can still read
             // it. The slow lane's in-flight pipeline reads it too (shared caller);
@@ -898,23 +949,26 @@ export async function apply(ctx, config = {}) {
     // The 0.1.7 host imports the old settings.yaml ONCE by "section name =
     // entry id" and renames it settings.yaml.imported — this plugin's legacy
     // section was named `topics`, so the host's import silently dropped it.
-    // Recover it here (see legacy-import.ts). Awaited as apply()'s LAST step:
-    // every registration above stays synchronous (fake-ctx tests dispatch
-    // immediately), while a real boot — whose loader awaits the fiber setup —
-    // also settles the import before activation completes. Fully contained:
-    // any failure only warns and leaves the audit marker unwritten, so the
-    // next boot retries; activation never depends on this.
-    try {
-        await runLegacySettingsImport({
+    // Recover it here (see legacy-import.ts). Wired through
+    // ctx.inject(['settings'], …) instead of a direct `ctx.settings` read: a
+    // real boot can run apply() before the settings service is mounted, the
+    // direct read came up undefined, and the import then took the silent
+    // no-settings exit EVERY boot (no marker, nothing ever recovered). The
+    // inject callback fires the moment the service exists (immediately when
+    // it already does — fake-ctx tests stay synchronous), fire-and-forget so
+    // activation never waits on it. Fully contained: any failure only warns
+    // and leaves the audit marker unwritten, so the next boot retries;
+    // activation never depends on this.
+    ctx.inject(['settings'], (sctx) => {
+        void runLegacySettingsImport({
             home: paths.resolveDshHome(),
-            settings: ctx.settings,
+            settings: sctx.settings,
             logger: ctx.logger,
             getCurrent: (key) => cfgNow()[key],
+        }).catch((error) => {
+            warn(`dsh-topics-memory 旧 settings 迁移失败（不影响启动，下次启动重试）：${error instanceof Error ? error.message : String(error)}`);
         });
-    }
-    catch (error) {
-        warn(`dsh-topics-memory 旧 settings 迁移失败（不影响启动，下次启动重试）：${error instanceof Error ? error.message : String(error)}`);
-    }
+    });
 }
 /** Config defaults for harnesses that skip schemastery's default application. */
 const DEFAULTS = {

package/lib/jev/backends.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Backend table for the System One integration (design 2026-09-25 §3.1),
+ * aligned with dsh-jev-mcp `backends.mjs` (three-endpoint field evidence,
+ * zero changes there). Model ids are PINNED versioned ids: aliases
+ * (jev-latest & friends) silently move on every vendor release, so routing
+ * thresholds and eval numbers stop meaning anything without a deliberate
+ * model bump.
+ *
+ * @module jev/backends
+ */
+export type JevBackendName = 'zen' | 'native' | 'openrouter';
+export type JevFamily = 'systemone' | 'decisions';
+export interface JevBackend {
+    readonly name: JevBackendName;
+    /** Wire protocol family: systemone (instructions required, noul criteria
+     *  optional, structured score levels allowed) vs decisions (noul criteria
+     *  REQUIRED two-sided, score levels strings only). */
+    readonly family: JevFamily;
+    readonly endpoint: string;
+    readonly defaultModel: string;
+    readonly keyEnv: string;
+    readonly keychainService: string;
+    /** Only zen falls back to its default keychain service when JEV_KEYCHAIN
+     *  is unset; native/openrouter expose a service for onboarding but still
+     *  require an explicit JEV_KEYCHAIN (dsh-jev-mcp server.mjs parity). */
+    readonly keychainByDefault: boolean;
+}
+export declare const BACKENDS: Readonly<Record<JevBackendName, JevBackend>>;
+/** Resolve a config value to a backend; anything but a known name (bare
+ *  harnesses, future drift) lands on the config default `zen`. */
+export declare function resolveBackend(name: string | undefined): JevBackend;

package/lib/jev/backends.js

@@ -0,0 +1,46 @@
+/**
+ * Backend table for the System One integration (design 2026-09-25 §3.1),
+ * aligned with dsh-jev-mcp `backends.mjs` (three-endpoint field evidence,
+ * zero changes there). Model ids are PINNED versioned ids: aliases
+ * (jev-latest & friends) silently move on every vendor release, so routing
+ * thresholds and eval numbers stop meaning anything without a deliberate
+ * model bump.
+ *
+ * @module jev/backends
+ */
+export const BACKENDS = {
+    zen: {
+        name: 'zen',
+        family: 'systemone',
+        endpoint: 'https://opencode.ai/zen/v1/systemone',
+        defaultModel: 'jev-1.13-free',
+        keyEnv: 'JEV_ZEN_API_KEY',
+        keychainService: 'opencode-zen-inference',
+        keychainByDefault: true,
+    },
+    native: {
+        name: 'native',
+        family: 'systemone',
+        endpoint: 'https://api.typesafe.ai/v1/systemone',
+        defaultModel: 'jev-1.13.0',
+        keyEnv: 'TYPESAFE_API_KEY',
+        keychainService: 'jev-typesafe',
+        keychainByDefault: false,
+    },
+    openrouter: {
+        name: 'openrouter',
+        family: 'decisions',
+        endpoint: 'https://openrouter.ai/api/alpha/decisions',
+        defaultModel: 'typesafe/jev-1.13',
+        keyEnv: 'OPENROUTER_API_KEY',
+        keychainService: 'openrouter-inference',
+        keychainByDefault: false,
+    },
+};
+/** Resolve a config value to a backend; anything but a known name (bare
+ *  harnesses, future drift) lands on the config default `zen`. */
+export function resolveBackend(name) {
+    if (name === 'native' || name === 'openrouter')
+        return BACKENDS[name];
+    return BACKENDS.zen;
+}

package/lib/jev/client.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 type { JevFamily } from './backends.ts';
+import type { GateLogger } from './gate.ts';
+import type { JevLane, JevOutcome, JevUsage } from './log.ts';
+export type JevQuestionType = 'noul' | 'choice' | 'score';
+export interface JevQuestion {
+    type: JevQuestionType;
+    /** The plugin ALWAYS sends instructions (systemone requires them). */
+    instructions: string;
+    criteria?: unknown;
+}
+/** The config slice jevAsk needs (pass straight from TopicsConfigValue). */
+export interface JevAskConfig {
+    jevBackend: string;
+    jevModel: string;
+    jevTimeoutMs: number;
+    jevSecretFile: string;
+}
+export interface JevAskArgs {
+    state: string;
+    questions: Record<string, JevQuestion>;
+    config: JevAskConfig;
+    /** Seam identity for the decisions.jsonl call-layer row (§6.2) — required
+     *  so telemetry cannot be silently skipped. */
+    lane: JevLane;
+    /** Whether the caller falls back to the legacy path on failure (§6.2
+     *  `fallback` — the fail-open health metric). */
+    fallback?: boolean;
+    /** Host logger (optional, warn-only, best-effort). */
+    logger?: GateLogger;
+}
+export type JevAnswer = Record<string, unknown>;
+export type JevAskOk = {
+    ok: true;
+    answers: Record<string, JevAnswer>;
+    usage: JevUsage | null;
+    latencyMs: number;
+};
+export type JevAskFailure = {
+    ok: false;
+    outcome: Exclude<JevOutcome, 'ok'>;
+    message: string;
+    latencyMs: number;
+};
+export type JevAskResult = JevAskOk | JevAskFailure;
+export interface KeychainSpec {
+    service: string;
+    account?: string;
+}
+/** 'svc' -> {service:'svc'}; 'svc:acct' -> {service:'svc', account:'acct'} */
+export declare function parseKeychainSpec(spec: string): KeychainSpec;
+export type KeychainRunner = (file: string, args: string[]) => Promise<{
+    stdout: string;
+}>;
+/** Runs `security find-generic-password -w`; null on any failure (silent). */
+export declare function keychainLookup(spec: KeychainSpec, runner?: KeychainRunner): Promise<string | 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 declare function resolveApiKey(backend: {
+    keyEnv: string;
+    keychainService: string;
+    keychainByDefault: boolean;
+}, lookup?: (spec: KeychainSpec) => Promise<string | null>): Promise<string>;
+type WireQuestions = Record<string, Record<string, unknown>>;
+interface NormalizeOk {
+    ok: true;
+    questions: WireQuestions;
+}
+interface NormalizeRefusal {
+    ok: false;
+    message: string;
+}
+export declare function normalizeQuestions(questions: Record<string, JevQuestion>, family: JevFamily): NormalizeOk | NormalizeRefusal;
+/** 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 declare function jevAsk(args: JevAskArgs): Promise<JevAskResult>;
+export {};