@aiwayds/dsh-topics-memory 0.18.2 → 0.19.0

package/README.md

@@ -38,6 +38,78 @@ This plugin is not trying to be the model's notebook. It is trying to be the mod
 - **Knowledge as a graph**: `depends` (machine-readable directed edges) plus body `[[wikilinks]]` and markdown links (human-written edges) form one graph; retrieval walks it in both directions (per-level decay, configurable depth) so a single hit pulls in a knowledge subgraph; every write rebuilds the `meta/backlinks.json` reverse index, and `/topics show` lists "who references me, and how" — check the blast radius before changing a conclusion.
 - **Two-stage observer (M2)**: the main model jots atomic observations with `topic_observe`; a background distill lane (session end + every N turns, model configurable) distills them into formal Topics in batches; when the model itself deems something worth keeping, it `topic_save`s directly.
 
+## Jev decision layer (System One, experimental, default off)
+
+An optional decision layer on the asynchronous lanes, powered by a System One typed-decision model (jev): it batch-scores slow-lane rerank candidates (replacing the LLM rerank), pre-filters consolidation merge pairs before the LLM gardener sees them, and shadow-audits the fast-lane lexical gate from a turn-end lane. Every verdict is probability-gated, and any failure — timeout, network error, bad answer — falls back to today's pure-local behavior (hardcoded fail-open, no switch key). The injection hot path never makes a remote call (ADR 0016–0019; design doc: `docs/design/2026-09-25-system-one-integration.md`). Off by default: `jevEnabled: false` means zero behavior change.
+
+### Keys
+
+| Key | Default | Meaning |
+|---|---|---|
+| `jevEnabled` | `false` | Master switch (rollout: default off → shadow → opt-in per profile → default-on observation); `false` stops the stats too |
+| `jevBackend` | `zen` | `zen` (free) / `native` / `openrouter` |
+| `jevModel` | empty sentinel | Resolved per backend at call time: `jev-1.13-free` (zen) / `jev-1.13.0` (native) / `typesafe/jev-1.13` (openrouter) — pinned, never an alias |
+| `jevTimeoutMs` | `3000` | Per-request timeout; single `AbortSignal.timeout`, no retry (the lane's next cadence retries naturally) |
+| `jevSecretFile` | none | Path to an external secret list; loaded once at boot, re-read when the path is hot-changed |
+
+### Keys provisioning
+
+| Backend | Key source |
+|---|---|
+| `zen` (default, free) | `JEV_ZEN_API_KEY` env, or the macOS keychain service `opencode-zen-inference` (default fallback — zero config) |
+| `native` | `TYPESAFE_API_KEY` |
+| `openrouter` | `OPENROUTER_API_KEY`; the keychain service `openrouter-inference` requires an explicit `JEV_KEYCHAIN` |
+
+dsh scrubs ambient `KEY|PASSWORD|SECRET|TOKEN` variables from plugin environments, so a key exported in your shell never reaches the plugin — pass it explicitly through the profile patch `env:` block, or keep it out of files entirely via the keychain (`JEV_KEYCHAIN` / zen's default service; neither matches the scrub rules):
+
+```yaml
+# ~/.dsh/cordis.patch.yml — merge into your profile patch. The !!js
+# expression keeps the key out of the file (same convention as dsh-jev-mcp).
+- insert:
+    - id: dsh-topics-memory
+      name: '@aiwayds/dsh-topics-memory'
+      env:
+        JEV_ZEN_API_KEY: !!js process.env.JEV_ZEN_API_KEY ?? ''
+        # native:     TYPESAFE_API_KEY: !!js process.env.TYPESAFE_API_KEY ?? ''
+        # openrouter: OPENROUTER_API_KEY: !!js process.env.OPENROUTER_API_KEY ?? ''
+        #   plus JEV_KEYCHAIN: 'openrouter-inference'
+        #   (zen needs no JEV_KEYCHAIN — with no env key it reads the
+        #   default keychain service 'opencode-zen-inference')
+```
+
+### Thresholds
+
+Adopt / record / fallback bands (calibrated offline on a 383-case gold corpus; the numbers are bound to the batch protocol — design doc §5). Record-band verdicts only land in the decision log without affecting behavior. The cluster-level "worth consolidating?" question records without gating in v1:
+
+| Seam | Adopt | Record-only | Fallback line |
+|---|---|---|---|
+| Slow-lane rerank (per candidate) | noul ≥ 0.60 → enters picks | 0.10 – 0.60 | < 0.10 → strong veto, lexical-gate behavior |
+| Consolidation merge (per pair) | noul ≥ 0.50 → pair sent to the LLM | 0.15 – 0.50 (pair still evaluated by the LLM) | < 0.15 → pair cut before the LLM |
+
+### Fallback behavior
+
+| Seam | On failure / timeout / bad answer | Legacy path |
+|---|---|---|
+| Slow-lane rerank | The round falls back to the old LLM rerank; picks still produced | Old RERANK_PROMPT path kept until rollout step 4 (default-on observation), then removed |
+| Consolidation prefilter | The cluster goes to the LLM in full, exactly as today | none |
+| Fast-lane shadow | Records the outcome only; zero behavior impact | none |
+
+Every call and verdict lands in `~/.dsh/topics/meta/decisions.jsonl` — local-only and redacted: slugs, pair hashes, question types, probabilities, latency and token counts; never conversation text or conclusion bodies. It has no config key (it stops together with `jevEnabled: false`); `/topics status` shows a 30-day summary line.
+
+
+### Latency benchmarks (measured 2026-09-26, Apple M5, typesafe `native` backend, jev-1.13.0)
+
+Real-payload benchmarks and in-sandbox runs — use them to pick `jevTimeoutMs`. Sources vary in shape and load; all are the same 8-candidate shadow batch unless noted:
+
+| Source | Shape | p50 | p90 | max | n |
+|---|---|---|---|---|---|
+| Idle benchmark (sequential) | 8-question batch | 742 ms | 1290 ms | 1461 ms | 10 |
+| Idle benchmark (sequential) | 1-question | 367 ms | — | 925 ms | 5 |
+| Threshold-sweep runs (Sept 25) | 20-question batch | 1760 ms avg | — | 8470 ms | 16 |
+| Live headless turns | 8-question batch, **concurrent with the main model streaming** | 327–5698 ms | — | 10619 ms | 3 |
+
+Readings that matter: the idle path sits comfortably under the 3000 ms default (≈2× headroom at p90), but a live turn's shadow call shares the network with the main model's streaming response — the 10.6 s outlier above was observed exactly there. A timeout is fail-open: the batch is dropped (slow-lane rerank falls back to the old LLM path), so a tight timeout costs shadow data, never correctness. Keep the 3000 ms default unless `decisions.jsonl` shows a persistent `timeout` share above ~5% (the 30-day summary in `/topics status` surfaces it); weak-network users can raise `jevTimeoutMs` freely. `zen` and `openrouter` are unmeasured here — after enabling, your own decisions.jsonl latency column is the ground truth for your network.
+
 ## Quick start
 
 1. Install (command below), restart dsh;
@@ -126,6 +198,11 @@ First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set
 | `deprecatedTtlDays` | `15` | Deprecated topics older than N days are dropped at session start (local rule, no model; each drop is its own git commit — history stays recoverable); `0` disables the sweep |
 | `usageBoost` | `0.15` | Usage boost (ADR 0015): topics injected/opened in the last 30 days score higher at retrieval (gate-scoped, capped at 0.2, never granted to zero-lexical candidates, structural gate not waived); `0` disables |
 | `pushDebounceSeconds` | `45` | GitHub-mode debounced push interval |
+| `jevEnabled` | `false` | System One decision layer master switch (experimental): `false` = zero behavior change — see the Jev decision layer section above |
+| `jevBackend` | `zen` | Decision endpoint: `zen` (free) / `native` / `openrouter` |
+| `jevModel` | empty (per backend: `jev-1.13-free` / `jev-1.13.0` / `typesafe/jev-1.13`) | Version-pinned decision model; upgrading is an explicit action |
+| `jevTimeoutMs` | `3000` | Per-request decision timeout; single attempt, no retry |
+| `jevSecretFile` | none | External secret list for the outbound secret gate; re-read when hot-changed |
 
 ## Acknowledgements
 
@@ -148,7 +225,7 @@ This project's shape is directly inspired and supported by:
 ## Design docs
 
 - [CONTEXT.md](CONTEXT.md) — domain glossary
-- [docs/adr/](docs/adr/) — 0001–0013: OKF compliance, remote shape, sync strategy, two-stage observer, bundle layout, injection defaults, observability & tunables, dual-mode persistence, onboarding wizard, subagent isolation, the include-subagents switch, injection dedup default-on, the rename & migration
+- [docs/adr/](docs/adr/) — 0001–0019: OKF compliance, remote shape, sync strategy, two-stage observer, bundle layout, injection defaults, observability & tunables, dual-mode persistence, onboarding wizard, subagent isolation, the include-subagents switch, injection dedup default-on, the rename & migration, dual-channel injection, the usage boost, direct-HTTP decisions, the fast-lane zero-remote-calls line, hardcoded fail-open, the embedded secret gate
 
 ## License
 

package/README.zh.md

@@ -38,6 +38,68 @@ https://github.com/user-attachments/assets/6e9b346d-2ec9-4148-ae62-7087797d3188
 - **知识连接成图**：`depends`（机器可读的有向依赖边）+ 正文 `[[wikilink]]` 与 markdown 链接（人写边）共同构成图；检索命中后沿图双向游走（每层衰减一半、深度可配），一次命中带入一个知识子图；每次写入自动重建 `meta/backlinks.json` 反向引用索引，`/topics show` 直接列出「谁引用了我、怎么引用的」——改一条结论前先看牵连面。
 - **两段式观察（M2）**：主模型用 `topic_observe` 随手记原子观察，后台蒸馏 lane（session end + 每 N 轮，模型可配）把观察批量蒸馏成正式 Topic；主模型认为值得记时直接 `topic_save`。
 
+## Jev 决策层（System One，实验，default off）
+
+架在异步 lane 上的可选决策层，由 System One typed-decision 模型（jev）驱动：慢车道 rerank 候选改批量 noul 打分（替换 LLM rerank）、整理 lane 的 merge 候选对在 LLM 园丁接手前先做前置过滤、快道词法门由 turn-end lane 做影子对账。每个判定都过概率门控，任何失败——超时、网络错、坏答案——一律回退到今天的纯本地行为（fail-open 硬编码，无开关键）。注入热路径永不发起远程调用（ADR 0016–0019；设计文档：`docs/design/2026-09-25-system-one-integration.md`）。默认关闭：`jevEnabled: false` 即零行为变化。
+
+### 键
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `jevEnabled` | `false` | 总开关（灰度：default off → shadow → opt-in per profile → 默认开观察）；`false` 连统计一起停 |
+| `jevBackend` | `zen` | `zen`（免费）/ `native` / `openrouter` |
+| `jevModel` | 空串哨兵 | 调用时按 backend 解析：`jev-1.13-free`（zen）/ `jev-1.13.0`（native）/ `typesafe/jev-1.13`（openrouter）——钉版本号，永不指向别名 |
+| `jevTimeoutMs` | `3000` | 单请求超时；单发 `AbortSignal.timeout` 不重试（lane 的下一节拍自然重试） |
+| `jevSecretFile` | 无 | 外部 secret 清单路径；启动加载一次，热更换路径即重读 |
+
+### key 配置
+
+| Backend | key 来源 |
+|---|---|
+| `zen`（默认，免费） | `JEV_ZEN_API_KEY` env，或 macOS 钥匙串服务 `opencode-zen-inference`（默认回退——零配置） |
+| `native` | `TYPESAFE_API_KEY` |
+| `openrouter` | `OPENROUTER_API_KEY`；钥匙串服务 `openrouter-inference` 需显式 `JEV_KEYCHAIN` |
+
+dsh 会清洗插件环境里匹配 `KEY|PASSWORD|SECRET|TOKEN` 的 ambient 变量，shell 里 export 的 key 到不了插件——请走 profile patch 的 `env:` 块显式透传，或用钥匙串（`JEV_KEYCHAIN` / zen 默认服务；都不匹配清洗规则）完全避开文件落 key：
+
+```yaml
+# ~/.dsh/cordis.patch.yml — 并入你的 profile patch。!!js 表达式让 key 不落文件
+# （与 dsh-jev-mcp 同款约定）。
+- insert:
+    - id: dsh-topics-memory
+      name: '@aiwayds/dsh-topics-memory'
+      env:
+        JEV_ZEN_API_KEY: !!js process.env.JEV_ZEN_API_KEY ?? ''
+        # native:     TYPESAFE_API_KEY: !!js process.env.TYPESAFE_API_KEY ?? ''
+        # openrouter: OPENROUTER_API_KEY: !!js process.env.OPENROUTER_API_KEY ?? ''
+        #   另加 JEV_KEYCHAIN: 'openrouter-inference'
+        #   （zen 无需 JEV_KEYCHAIN——无 env key 时自动读默认钥匙串服务）
+```
+
+### 阈值（rerank / merge pair）
+
+| 档 | rerank（慢车道） | merge pair（整理前置） | 动作 |
+|---|---|---|---|
+| 采纳 | noul ≥ 0.60 | ≥ 0.50 | 进 picks / 送 LLM 生成 |
+| 记录带 | 0.10 – 0.60 | 0.15 – 0.50 | 只落 decisions.jsonl，不影响行为 |
+| 回退 | < 0.10 | < 0.15 | 强否决，回退词法/现状行为 |
+
+绝对线绑定批量协议（换协议必须重扫）。三缝失败回退行为见 ADR 0018。判定与调用明细落 `meta/decisions.jsonl`（本地 only，脱敏——绝不存 state 原文）。
+
+
+### 延迟基准（2026-09-26 实测，Apple M5，typesafe `native` 后端，jev-1.13.0）
+
+真实负载基准 + 沙箱实跑——用来选 `jevTimeoutMs`。各 source 形状与负载不同，除注明外均为同一 8 候选 shadow 批量：
+
+| 来源 | 形状 | p50 | p90 | max | n |
+|---|---|---|---|---|---|
+| 空载基准（顺序发） | 8 问批量 | 742 ms | 1290 ms | 1461 ms | 10 |
+| 空载基准（顺序发） | 单问 | 367 ms | — | 925 ms | 5 |
+| 阈值扫描（09-25） | 20 问批量 | 均值 1760 ms | — | 8470 ms | 16 |
+| 真机 headless 轮 | 8 问批量，**与主模型流式并发** | 327–5698 ms | — | 10619 ms | 3 |
+
+关键读数：空载路径远低于 3000 ms 默认线（p90 约 2× 余量）；但真机轮的 shadow 调用与主模型的流式响应共享网络——上表 10.6 s 离群值正是在这个位置观测到的。超时即 fail-open：该批数据丢弃（慢车道回退旧 LLM rerank），**紧超时损失的是 shadow 数据，不是正确性**。默认 3000 保持不变；除非 `decisions.jsonl` 显示 `timeout` 占比持续 >5%（`/topics status` 的 30 天摘要会露出），弱网用户可自行上调 `jevTimeoutMs`。`zen` 与 `openrouter` 本次未实测——开启后你自己 decisions.jsonl 的 latency 列就是你网络的真值。
+
 ## 工具与命令
 
 | 模型工具 | 用途 |
@@ -126,6 +188,12 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 | `deprecatedTtlDays` | `15` | deprecated 条目超过 N 天在会话启动时自动删除（本地规则不依赖模型，逐条 git commit 可回溯找回）；`0` 关闭清扫 |
 | `usageBoost` | `0.15` | 使用加成（ADR 0015）：近 30 天被注入命中/点开过的 Topic 检索加分（计入门槛分、帽 0.2、零词面相关不加、结构门不豁免）；`0` 关闭 |
 | `pushDebounceSeconds` | `45` | GitHub 模式去抖推送间隔 |
+| `jevEnabled` | `false` | System One 决策层总开关（实验）：`false` = 零行为变化——见上方「Jev 决策层」一节 |
+| `jevBackend` | `zen` | 决策端点：`zen`（免费）/ `native` / `openrouter` |
+| `jevModel` | 空（按 backend：`jev-1.13-free` / `jev-1.13.0` / `typesafe/jev-1.13`） | 版本钉定的决策模型；升级是显式动作 |
+| `jevTimeoutMs` | `3000` | 单次决策请求超时；单发不重试 |
+| `jevSecretFile` | 无 | 出网 secret gate 的外部清单路径；热更换路径即重读 |
+| `jevDebug` | 关 | 诊断日志开关（走宿主 logger，默认静默） |
 
 ## Acknowledgements
 
@@ -148,7 +216,7 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 ## 设计文档
 
 - [CONTEXT.md](CONTEXT.md) — 领域术语表
-- [docs/adr/](docs/adr/) — 0001–0013：OKF 合规、Remote 形态、同步策略、两段式 Observer、Bundle 布局、注入默认值、可观测与调参、双模式持久化、配置向导、子代理隔离、include-subagents 开关、注入去重默认开、更名与迁移
+- [docs/adr/](docs/adr/) — 0001–0019：OKF 合规、Remote 形态、同步策略、两段式 Observer、Bundle 布局、注入默认值、可观测与调参、双模式持久化、配置向导、子代理隔离、include-subagents 开关、注入去重默认开、更名与迁移、双通道注入、使用加成、决策层直连 HTTP、快道零远程红线、fail-open 硬编码、secret gate 内嵌
 
 ## License
 

package/lib/commands.js

@@ -11,6 +11,7 @@ import { spawn } from 'node:child_process';
 import { serializeTopicDoc, slugify, firstParagraph } from "./okf.js";
 import { buildGraph, renderGraphHtml } from "./viz.js";
 import { CONFIG_KEYS, displayKey, parseConfigValue } from "./config.js";
+import { reloadSecrets } from "./jev/gate.js";
 import { aggregateStats } from "./ilog.js";
 import { askDistillSingle, createOnboardHandler, llmDirectoryNotice, makePanel, parseDistillInput, pickLlmDirectory, } from "./onboard.js";
 export const HELP = [
@@ -582,5 +583,7 @@ async function doSet(service, tokens, mutate, resolveAsk = () => undefined, reso
     await mutate([{ op: 'set', path: [key], value: parsed }]);
     if (key === 'repo' || key === 'autoInject')
         service.invalidate();
+    if (key === 'jevSecretFile')
+        reloadSecrets(String(parsed)); // hot-swapped list: force re-read
     return ok(`✅ topics.${displayKey(key)} = ${String(parsed)}`);
 }

package/lib/config.d.ts

@@ -72,6 +72,23 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
     usageBoost: z<number, number, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z<number, number, "volatile-defined">;
+    /** System One decision-model integration (design 2026-09-25), default-off
+     *  master switch: false means zero behavior change anywhere (the fast lane
+     *  never calls out regardless — hard guard); the usage stats stop with it. */
+    jevEnabled: z<boolean, boolean, "volatile-defined">;
+    /** Decision backend: zen (free, opencode.ai) | native (typesafe
+     *  first-party) | openrouter (decisions protocol). */
+    jevBackend: z<string, string, "volatile-defined">;
+    /** Pinned model id; '' = resolve the backend default at call time
+     *  (distillProvider sentinel pattern): jev-1.13-free / jev-1.13.0 /
+     *  typesafe/jev-1.13 — an upgrade is a deliberate act. */
+    jevModel: z<string, string, "volatile-defined">;
+    /** Single-request timeout in ms; one AbortSignal, NO retry (the calling
+     *  lane's next cadence is the natural retry, fail-open hard-coded). */
+    jevTimeoutMs: z<number, number, "volatile-defined">;
+    /** External secret list for the outbound secret gate (JEV_SECRET_FILE
+     *  semantics, design §3.3); swapping the path hot reloads the list. */
+    jevSecretFile: z<string, string, "volatile-defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     /** GitHub repo `owner/name`; empty = local-only mode (ADR 0008). */
     repo: z<string, string, "volatile-defined">;
@@ -139,6 +156,23 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
     usageBoost: z<number, number, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z<number, number, "volatile-defined">;
+    /** System One decision-model integration (design 2026-09-25), default-off
+     *  master switch: false means zero behavior change anywhere (the fast lane
+     *  never calls out regardless — hard guard); the usage stats stop with it. */
+    jevEnabled: z<boolean, boolean, "volatile-defined">;
+    /** Decision backend: zen (free, opencode.ai) | native (typesafe
+     *  first-party) | openrouter (decisions protocol). */
+    jevBackend: z<string, string, "volatile-defined">;
+    /** Pinned model id; '' = resolve the backend default at call time
+     *  (distillProvider sentinel pattern): jev-1.13-free / jev-1.13.0 /
+     *  typesafe/jev-1.13 — an upgrade is a deliberate act. */
+    jevModel: z<string, string, "volatile-defined">;
+    /** Single-request timeout in ms; one AbortSignal, NO retry (the calling
+     *  lane's next cadence is the natural retry, fail-open hard-coded). */
+    jevTimeoutMs: z<number, number, "volatile-defined">;
+    /** External secret list for the outbound secret gate (JEV_SECRET_FILE
+     *  semantics, design §3.3); swapping the path hot reloads the list. */
+    jevSecretFile: z<string, string, "volatile-defined">;
 }>>, "plain">;
 export type TopicsConfigValue = {
     repo: string;
@@ -167,8 +201,17 @@ export type TopicsConfigValue = {
     deprecatedTtlDays: number;
     usageBoost: number;
     pushDebounceSeconds: number;
+    /** System One integration keys (design 2026-09-25 §4). Optional in this TS
+     *  view only: index.ts's bare-harness DEFAULTS literal predates them and
+     *  schemastery applies the runtime defaults on real hosts — consumers must
+     *  treat undefined as the documented default. */
+    jevEnabled?: boolean;
+    jevBackend?: 'zen' | 'native' | 'openrouter';
+    jevModel?: string;
+    jevTimeoutMs?: number;
+    jevSecretFile?: string;
 };
-export declare const CONFIG_KEYS: readonly ["repo", "autoInject", "injectDedup", "suppressEcho", "topK", "perTopicBudget", "totalBudget", "matchThreshold", "tagBoost", "injectMode", "qualityLane", "graphDepth", "recencyWindowDays", "autoObserve", "includeSubagents", "observationMaxChars", "distillEveryTurns", "distillOnSessionEnd", "distillProvider", "distillModel", "distillBatchSize", "distillMaxModelCalls", "consolidateCadence", "deprecatedTtlDays", "usageBoost", "pushDebounceSeconds"];
+export declare const CONFIG_KEYS: readonly ["repo", "autoInject", "injectDedup", "suppressEcho", "topK", "perTopicBudget", "totalBudget", "matchThreshold", "tagBoost", "injectMode", "qualityLane", "graphDepth", "recencyWindowDays", "autoObserve", "includeSubagents", "observationMaxChars", "distillEveryTurns", "distillOnSessionEnd", "distillProvider", "distillModel", "distillBatchSize", "distillMaxModelCalls", "consolidateCadence", "deprecatedTtlDays", "usageBoost", "pushDebounceSeconds", "jevEnabled", "jevBackend", "jevModel", "jevTimeoutMs", "jevSecretFile"];
 export type ConfigKey = (typeof CONFIG_KEYS)[number];
 /** CamelCase → dash-display (topK → top-k) for command output. */
 export declare function displayKey(key: string): string;

package/lib/config.js

@@ -72,6 +72,23 @@ export const TopicsConfig = z.object({
     usageBoost: z.number().default(0.15).volatile(),
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z.number().default(45).volatile(),
+    /** System One decision-model integration (design 2026-09-25), default-off
+     *  master switch: false means zero behavior change anywhere (the fast lane
+     *  never calls out regardless — hard guard); the usage stats stop with it. */
+    jevEnabled: z.boolean().default(false).volatile(),
+    /** Decision backend: zen (free, opencode.ai) | native (typesafe
+     *  first-party) | openrouter (decisions protocol). */
+    jevBackend: z.string().default('zen').volatile(),
+    /** Pinned model id; '' = resolve the backend default at call time
+     *  (distillProvider sentinel pattern): jev-1.13-free / jev-1.13.0 /
+     *  typesafe/jev-1.13 — an upgrade is a deliberate act. */
+    jevModel: z.string().default('').volatile(),
+    /** Single-request timeout in ms; one AbortSignal, NO retry (the calling
+     *  lane's next cadence is the natural retry, fail-open hard-coded). */
+    jevTimeoutMs: z.number().default(3000).volatile(),
+    /** External secret list for the outbound secret gate (JEV_SECRET_FILE
+     *  semantics, design §3.3); swapping the path hot reloads the list. */
+    jevSecretFile: z.string().default('').volatile(),
 });
 export const CONFIG_KEYS = [
     'repo',
@@ -100,6 +117,11 @@ export const CONFIG_KEYS = [
     'deprecatedTtlDays',
     'usageBoost',
     'pushDebounceSeconds',
+    'jevEnabled',
+    'jevBackend',
+    'jevModel',
+    'jevTimeoutMs',
+    'jevSecretFile',
 ];
 /** CamelCase → dash-display (topK → top-k) for command output. */
 export function displayKey(key) {
@@ -119,13 +141,19 @@ export function parseConfigValue(key, raw) {
         case 'suppressEcho':
         case 'autoObserve':
         case 'distillOnSessionEnd':
-        case 'includeSubagents': {
+        case 'includeSubagents':
+        case 'jevEnabled': {
             if (raw === 'on' || raw === 'true')
                 return true;
             if (raw === 'off' || raw === 'false')
                 return false;
             return { error: `${key} 取值 on|off` };
         }
+        case 'jevBackend': {
+            if (raw === 'zen' || raw === 'native' || raw === 'openrouter')
+                return raw;
+            return { error: 'jev-backend 取值 zen|native|openrouter' };
+        }
         case 'topK':
         case 'perTopicBudget':
         case 'totalBudget':
@@ -136,7 +164,8 @@ export function parseConfigValue(key, raw) {
         case 'distillBatchSize':
         case 'distillMaxModelCalls':
         case 'deprecatedTtlDays':
-        case 'pushDebounceSeconds': {
+        case 'pushDebounceSeconds':
+        case 'jevTimeoutMs': {
             const n = Number(raw);
             if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n))
                 return { error: `${key} 需要非负整数` };
@@ -167,6 +196,8 @@ export function parseConfigValue(key, raw) {
         }
         case 'distillProvider':
         case 'distillModel':
+        case 'jevModel':
+        case 'jevSecretFile':
             return raw;
     }
 }

package/lib/consolidate.d.ts

@@ -23,11 +23,19 @@
  *  - 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 type { TopicsService } from './service.ts';
 import { type ModelCaller } from './distill.ts';
+import { jevAsk } from './jev/client.ts';
 /** Clusters are capped — a giant cluster drowns the model in candidates. */
 export declare const MAX_CLUSTER_SIZE = 6;
 export interface ConsolidateOp {
@@ -79,10 +87,21 @@ export interface ClusterEntry {
     description?: string;
     conclusion: string;
 }
+/** One similar pair inside a cluster — the jev prefilter's question units. */
+export interface ClusterPair {
+    /** Indices into the cluster's `entries`. */
+    i: number;
+    j: number;
+    /** Pairwise Jaccard from clustering — REUSED for the prefilter's pair
+     *  selection (top-k at ask time), never recomputed. */
+    similarity: number;
+}
 export interface TopicCluster {
     entries: ClusterEntry[];
     /** Peak pairwise similarity inside the cluster — runs process peaks first. */
     similarity: number;
+    /** Similar pairs (edges ≥ threshold) inside the cluster, best first. */
+    pairs: ClusterPair[];
 }
 /**
  * Group entries whose title+description+tags tokens clear the pairwise
@@ -91,6 +110,9 @@ export interface TopicCluster {
  * {@link MAX_CLUSTER_SIZE} keep their most-connected members.
  */
 export declare function clusterTopics(entries: readonly ClusterEntry[], threshold?: number): TopicCluster[];
+/** The jev seam — injectable so tests run hermetic (same pattern as
+ *  ModelCaller: production never passes it, the real jevAsk is the default). */
+export type JevAsker = typeof jevAsk;
 /**
  * Drop `deprecated` topics older than `ttlDays` — pure housekeeping, never
  * touches the model. `generated.at` is the right clock: every save restamps
@@ -105,7 +127,11 @@ export declare class Consolidator {
     private inFlight;
     private readonly service;
     private readonly caller;
-    constructor(service: TopicsService, caller: ModelCaller | undefined);
+    private readonly askJev;
+    /** Best-effort host-logger sink (warn-style); undefined = stay silent,
+     *  aligned with the lane's quiet discipline for success/no-clusters. */
+    private readonly note;
+    constructor(service: TopicsService, caller: ModelCaller | undefined, askJev?: JevAsker, note?: (message: string) => void);
     get configured(): boolean;
     /** Cadence days for a config value; undefined = off (or unrecognized). */
     static cadenceDays(value: string | undefined): number | undefined;
@@ -125,6 +151,18 @@ export declare class Consolidator {
     private runInner;
     /** Read the active pool and cluster it lexically. */
     private buildClusters;
+    /**
+     * 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).
+     */
+    private prefilterCluster;
     /** One model call over one cluster, ops shape-validated but not yet applied. */
     private runCluster;
     /**