@aiwayds/dsh-topics-memory 0.18.2 → 0.20.0

package/src/index.ts

@@ -288,14 +288,19 @@ interface UserMessageData {
 /** Provider name under `ctx.skills`; doubles as the skill name. */
 const SKILL_PROVIDER_NAME = 'dsh-topics-memory-config'
 
-/** Packaged skill body; `../skills/` resolves to the package root from both lib/ and src/. */
+/** Packaged skill bodies; `../skills/` resolves to the package root from both lib/ and src/. */
 const SKILL_BODY_URL = new URL('../skills/dsh-topics-memory-config/SKILL.md', import.meta.url)
+const LAYA_SKILL_BODY_URL = new URL('../skills/dsh-topics-memory-laya/SKILL.md', import.meta.url)
 
-/** Resource base served with the skill so its relative links resolve. */
+/** Resource bases served with the skills so their relative links resolve. */
 const SKILL_RESOURCE_BASE = {
   kind: 'directory',
   path: fileURLToPath(new URL('../skills/dsh-topics-memory-config/', import.meta.url)),
 } as const
+const LAYA_SKILL_RESOURCE_BASE = {
+  kind: 'directory',
+  path: fileURLToPath(new URL('../skills/dsh-topics-memory-laya/', import.meta.url)),
+} as const
 
 const SKILL_INVOCATION = { modelInvocable: true, userInvocable: true } as const
 
@@ -313,18 +318,36 @@ const SKILL_CANDIDATE: SkillCandidate = {
   locator: SKILL_BODY_URL,
 }
 
+/** The laya setup skill rides the same provider: installing/configuring the
+ *  local pace-maker is part of operating this plugin's decision layer. */
+const LAYA_SKILL_NAME = 'dsh-topics-memory-laya'
+const LAYA_SKILL_DESCRIPTION = '为 dsh-topics-memory 的 jev 决策层安装并配置本地 laya 陪跑（laya-serve）。当用户要开启 jevLayaFallback、安装 laya、启动 laya-serve、配置 laya 端点、排查陪跑不生效或 decisions.jsonl 没有 laya 行时读本指南：venv 创建、国内三镜像加速（清华 PyPI / hf-mirror / 禁 Xet）、checkpoint 下载、laya-serve 启动、jevLayaFallback/jevLayaUrl 两键、真机验证（decisions.jsonl 出现 backend=laya 行）。触发词：laya、laya-serve、陪跑、本地决策、jevLaya、离线、8000 端口。'
+const LAYA_SKILL_CANDIDATE: SkillCandidate = {
+  name: LAYA_SKILL_NAME,
+  description: LAYA_SKILL_DESCRIPTION,
+  invocation: SKILL_INVOCATION,
+  provider: SKILL_PROVIDER_NAME,
+  source: 'bundled',
+  resourceBase: LAYA_SKILL_RESOURCE_BASE,
+  rank: BUNDLED_SKILL_RANK,
+  locator: LAYA_SKILL_BODY_URL,
+}
+
 const skillProvider: SkillProvider = {
   name: SKILL_PROVIDER_NAME,
-  list: () => Promise.resolve([SKILL_CANDIDATE]),
-  async get(_candidate): Promise<SkillDefinition> {
+  list: () => Promise.resolve([SKILL_CANDIDATE, LAYA_SKILL_CANDIDATE]),
+  async get(candidate): Promise<SkillDefinition> {
+    const isLaya = candidate.name === LAYA_SKILL_NAME
+    const bodyUrl = isLaya ? LAYA_SKILL_BODY_URL : SKILL_BODY_URL
+    const resourceBase = isLaya ? LAYA_SKILL_RESOURCE_BASE : SKILL_RESOURCE_BASE
     return {
-      name: SKILL_CANDIDATE.name,
-      description: SKILL_CANDIDATE.description,
-      invocation: SKILL_CANDIDATE.invocation,
-      provider: SKILL_CANDIDATE.provider,
-      source: SKILL_CANDIDATE.source,
-      resourceBase: SKILL_RESOURCE_BASE,
-      content: stripFrontmatter(await readFile(SKILL_BODY_URL, 'utf8')),
+      name: candidate.name,
+      description: candidate.description,
+      invocation: candidate.invocation,
+      provider: SKILL_PROVIDER_NAME,
+      source: candidate.source,
+      resourceBase,
+      content: stripFrontmatter(await readFile(bodyUrl, 'utf8')),
     }
   },
 }
@@ -450,6 +473,16 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
 
   const agents = () => (ctx as unknown as { agents?: AgentMapLike }).agents
 
+  // Fastgate shadow context (design §2 row 3): the fast-lane round's query and
+  // candidate set, captured at spliced time so the SAME turn's turn-end shadow
+  // can audit them against the lexical disposition. Metadata only (slug +
+  // disposition); overwritten every round, consumed once at the trigger.
+  interface FastGateCapture {
+    query: string
+    candidates: { slug: string; disposition: 'hit' | 'nearFloor' | 'gate-blocked' }[]
+  }
+  const fastGateBySession = new Map<string, FastGateCapture>()
+
   // 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.
@@ -494,12 +527,50 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
         for (const slug of r.included) marked.add(slug)
         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' as const })),
+            ...r.outcome.nearMisses.map((nm) => ({
+              slug: nm.slug,
+              disposition: nm.reasons.includes('gate-blocked') ? ('gate-blocked' as const) : ('nearFloor' as const),
+            })),
+          ],
+        })
+      }
       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: string): void {
+    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
@@ -513,7 +584,12 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
       // autoInject before reaching the consume point).
       if (!cfgNow().autoInject) return
       if (isDelegated(agents()?.get(sessionId))) return
-      if (distiller.hasPending(sessionId)) return
+      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
@@ -539,6 +615,10 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
           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
     }
@@ -606,7 +686,7 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
   // 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
@@ -739,6 +819,7 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
         // 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
@@ -773,6 +854,7 @@ export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Pro
       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);

package/src/jev/backends.ts

@@ -0,0 +1,69 @@
+/**
+ * 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'
+/** The local laya pace-maker writes its own call-layer rows; not a config
+ *  backend (no entry in BACKENDS) — it rides jevAsk's overrides hook. */
+export type JevPaceMakerName = 'laya'
+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 const BACKENDS: Readonly<Record<JevBackendName, JevBackend>> = {
+  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: string | undefined): JevBackend {
+  if (name === 'native' || name === 'openrouter') return BACKENDS[name]
+  return BACKENDS.zen
+}

package/src/jev/client.ts

@@ -0,0 +1,336 @@
+/**
+ * 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.ts'
+import type { JevFamily } from './backends.ts'
+import { currentSecrets, scanForSecrets } from './gate.ts'
+import type { GateLogger } from './gate.ts'
+import { logCall } from './log.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
+  /** Dual-run pace-maker hook (jev/dual.ts): target this endpoint/model with
+   *  no auth header and tag the call-layer row backend='laya'. Never set by
+   *  user config — internal to the dual wrapper. */
+  overrides?: { endpoint: string; model: string }
+}
+
+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
+
+/** Guard for non-positive/absent values from bare harnesses. */
+const DEFAULT_TIMEOUT_MS = 3000
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
+// ---------------------------------------------------------------------------
+// API key resolution: backend env var first, then the macOS keychain via
+// `security find-generic-password`. Only zen falls back to its default
+// keychain service; native/openrouter need an explicit
+// JEV_KEYCHAIN='<service>[:<account>]' (dsh-jev-mcp server.mjs parity).
+// ---------------------------------------------------------------------------
+
+export interface KeychainSpec {
+  service: string
+  account?: string
+}
+
+/** 'svc' -> {service:'svc'}; 'svc:acct' -> {service:'svc', account:'acct'} */
+export function parseKeychainSpec(spec: string): KeychainSpec {
+  const i = spec.indexOf(':')
+  if (i === -1) return { service: spec }
+  return { service: spec.slice(0, i), account: spec.slice(i + 1) }
+}
+
+export type KeychainRunner = (file: string, args: string[]) => Promise<{ stdout: string }>
+
+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: KeychainRunner = async (file, args) => {
+  return (await execFileAsync(file, args, { encoding: 'utf8' })) as { stdout: string }
+}
+
+/** Runs `security find-generic-password -w`; null on any failure (silent). */
+export async function keychainLookup(
+  spec: KeychainSpec,
+  runner: KeychainRunner = securityRunner,
+): Promise<string | null> {
+  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: { keyEnv: string; keychainService: string; keychainByDefault: boolean },
+  lookup: (spec: KeychainSpec) => Promise<string | null> = keychainLookup,
+): Promise<string> {
+  const envKey = process.env[backend.keyEnv] ?? ''
+  if (envKey !== '') return envKey
+  const explicit = process.env.JEV_KEYCHAIN?.trim() ?? ''
+  const spec: KeychainSpec | null =
+    explicit !== '' ? parseKeychainSpec(explicit) : backend.keychainByDefault ? { service: backend.keychainService } : null
+  if (spec === null) return ''
+  return (await lookup(spec)) ?? ''
+}
+
+// ---------------------------------------------------------------------------
+// Question normalization onto the active wire protocol (design §3.1). The
+// plugin ALWAYS sends two-sided noul criteria and string score levels, so
+// both families accept every request: absent noul criteria are auto-generated
+// two-sided from the instructions (single-sided instructions measurably
+// degrade calibration), and anything that can NOT be sent to the active
+// family is refused LOCALLY before anything leaves the process.
+// ---------------------------------------------------------------------------
+
+type WireQuestions = Record<string, Record<string, unknown>>
+
+interface NormalizeOk {
+  ok: true
+  questions: WireQuestions
+}
+interface NormalizeRefusal {
+  ok: false
+  message: string
+}
+
+function where(id: string): string {
+  return `questions['${id}']`
+}
+
+export function normalizeQuestions(questions: Record<string, JevQuestion>, family: JevFamily): NormalizeOk | NormalizeRefusal {
+  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: WireQuestions = {}
+  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: Record<string, unknown> = { 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: JevAskArgs): Promise<JevAskResult> {
+  // 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,
+      } as unknown as ReturnType<typeof resolveBackend>)
+    : 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: Exclude<JevOutcome, 'ok'> | 'ok', usage: JevUsage | null): Promise<void> {
+    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: Exclude<JevOutcome, 'ok'>, message: string): Promise<JevAskFailure> => {
+    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: Response
+  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: Exclude<JevOutcome, 'ok'> =
+      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: Exclude<JevOutcome, 'ok'> = res.status >= 500 ? 'http_5xx' : 'http_4xx'
+    return refuse(outcome, `${backend.name} responded ${res.status}: ${text}`)
+  }
+
+  let json: unknown
+  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 as unknown as JevUsage) : null
+  await emit('ok', usage)
+  return { ok: true, answers: answers as Record<string, JevAnswer>, usage, latencyMs: Date.now() - started }
+}

package/src/jev/dual.ts

@@ -0,0 +1,73 @@
+/**
+ * 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.ts'
+import type { JevAskArgs, JevAskConfig, JevAskResult } from './client.ts'
+
+/** 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 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 async function jevAskDual(args: JevDualArgs): Promise<JevDualResult> {
+  if (args.config.jevLayaFallback !== true) {
+    const r = await jevAsk(args as JevAskArgs)
+    return { ...r, source: 'primary', layaResult: null }
+  }
+  const layaArgs: JevAskArgs = {
+    ...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 as JevAskArgs), 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 }
+}