@aiwayds/dsh-topics-memory 0.22.0 → 0.23.0

package/src/quality.ts

@@ -15,8 +15,11 @@
  * Picks rest in a per-session pending slot and inject at the NEXT spliced
  * (steer message), then the slot is gone (消费即清). Hard bounds: per-call
  * 20s, pipeline 45s, pending TTL 10min, turn-lag ≤2. Every failure is
- * contained and silent — I3 (可丢弃性): async products may be missing, never
- * blocking. The lexical re-gate at consumption is SHADOW-ONLY (v4 B3): it
+ * contained — async products may be missing, never blocking (I3 可丢弃性) —
+ * but no longer SILENT (A4 决议 3): each run lands a `slow-lane-outcome`
+ * disposition (SlowOutcome) on the session and in the pipeline-events
+ * ledger, so 「没跑」and 「跑了全败」are distinguishable in the log. The
+ * lexical re-gate at consumption is SHADOW-ONLY (v4 B3): it
  * records verdicts into ilog and never blocks a pick.
  *
  * @module quality
@@ -26,7 +29,7 @@ import type { TopicsService } from './service.ts'
 import type { ModelCaller } from './distill.ts'
 import { searchTopics } from './retrieval.ts'
 import type { RingEntry } from './observer.ts'
-import type { QueryBuildShape } from './ilog.ts'
+import type { QueryBuildShape, SlowOutcome } from './ilog.ts'
 import type { TopicsConfigValue } from './config.ts'
 import { jevAskDual } from './jev/dual.ts'
 import type { JevQuestion } from './jev/client.ts'
@@ -35,6 +38,11 @@ import { band as jevBand } from './jev/thresholds.ts'
 import type { JevBand } from './jev/thresholds.ts'
 import { digestFor, logVerdicts } from './jev/log.ts'
 import type { JevVerdictRecord } from './jev/log.ts'
+import { recordPipelineEvent } from './pipeline-events.ts'
+
+/** Re-exported for the ilog writers (spec §8.2): the service layer takes a
+ *  pending's `outcome` (or lastOutcomeOf) as the record's `slowOutcome`. */
+export type { SlowOutcome }
 
 export const PENDING_TTL_MS = 10 * 60_000
 /** Hard drift bound: a pending older than this many turn-ends expires. */
@@ -197,6 +205,13 @@ export interface PendingInjection {
   queryBuild: QueryBuildShape
   model: string
   ms: number
+  /**
+   * The producing run's disposition (A4 决议 3, spec §8.2) — always
+   * 'delivered' here (a pending only exists after a settled run). The
+   * service layer copies it into the ilog record's `slowOutcome` at
+   * consumption; expiry surfaces as `expired` via ConsumeResult instead.
+   */
+  outcome: SlowOutcome
 }
 
 export type ConsumeResult = { pending: PendingInjection } | { expired: 'ttl' | 'turn-lag' } | undefined
@@ -270,11 +285,32 @@ export function parseJsonObject(raw: string): Record<string, unknown> {
   throw new Error('unbalanced JSON in output')
 }
 
+/** The closed outcome for an error that escaped the produce body: our own
+ *  withTimeout rejections and the pipeline-deadline abort are `timeout`,
+ *  everything else (model error, bad transport, unexpected throw) is
+ *  `llm-error`. Raw error text never enters the ledger (jev/log redaction
+ *  envelope — the outcome class is the observable, not the message). */
+function classifySlowError(e: unknown, controller: AbortController): SlowOutcome {
+  if (e !== null && typeof e === 'object') {
+    const msg = (e as { message?: unknown }).message
+    if (typeof msg === 'string' && msg.startsWith('slow-lane call timeout')) return 'timeout'
+  }
+  if (controller.signal.aborted) return 'timeout'
+  return 'llm-error'
+}
+
 export class SlowLane {
   private pending = new Map<string, PendingInjection>()
   private inFlight = new Map<string, Promise<void>>()
   /** Same-session shadow serialization — a second trigger never overlaps. */
   private shadowInFlight = new Map<string, Promise<void>>()
+  /**
+   * The session's most recent slow-lane disposition (A4 决议 3): what a
+   * spliced with NO pending reports as its `slowOutcome` — without it a
+   * consumed-undefined round cannot say whether the lane never ran or ran
+   * and failed. One slot per session, overwritten by every trigger.
+   */
+  private outcomeBySession = new Map<string, SlowOutcome>()
   private readonly service: TopicsService
   private readonly caller: ModelCaller | undefined
   /**
@@ -302,10 +338,40 @@ export class SlowLane {
     return this.inFlight.has(sessionId)
   }
 
+  /**
+   * The session's most recent slow-lane disposition (A4 §3.2): a round whose
+   * consume() came up empty writes THIS as its ilog `slowOutcome` (spec §8.2
+   * — 「spliced 收到但未 produce 也留痕」). Undefined when the lane never
+   * triggered for the session.
+   */
+  lastOutcomeOf(sessionId: string): SlowOutcome | undefined {
+    return this.outcomeBySession.get(sessionId)
+  }
+
+  /**
+   * One disposition, two sinks (A4 决议 3): the per-session slot above and a
+   * `slow-lane-outcome` row in the pipeline-events ledger. Metadata only
+   * (outcome/reason/session/turn/timing — never ring or query text). Never
+   * throws, never rejects: traceability must not become a failure source.
+   */
+  private traceOutcome(sessionId: string, turnId: number, outcome: SlowOutcome, reason: string, extra: Record<string, string | number | boolean> = {}): void {
+    try {
+      this.outcomeBySession.set(sessionId, outcome)
+      void recordPipelineEvent(this.service.store.root, {
+        at: new Date().toISOString(),
+        kind: 'slow-lane-outcome',
+        detail: { outcome, reason, sessionId, turnId, ...extra },
+      })
+    } catch {
+      // contained — the ledger is best-effort by design
+    }
+  }
+
   /** Drop the pending slot (session teardown, restore boundary). */
   clear(sessionId: string): void {
     this.pending.delete(sessionId)
     this.shadowInFlight.delete(sessionId)
+    this.outcomeBySession.delete(sessionId)
   }
 
   /**
@@ -400,17 +466,36 @@ export class SlowLane {
 
   /**
    * Produce a pending slot for the session's next steer message. Fire-and-
-   * forget; every guard failure is silent. Policy gates live here (config,
-   * sampling, in-flight); host gates (delegation, distill yield) live with
-   * the caller, which owns those services.
+   * forget; every guard failure is contained (never breaks the event
+   * handler) and QUALIFIED (A4 决议 3): a skipped trigger lands a `no-run`
+   * outcome naming the guard, so a later spliced can report why there was
+   * nothing to consume. Policy gates live here (config, sampling, in-flight);
+   * host gates (delegation, distill yield) live with the caller, which owns
+   * those services.
    */
   dispatch(sessionId: string, input: DispatchInput): void {
     try {
       const cfg = this.service.cfg
-      if (cfg.qualityLane !== 'sampled' && cfg.qualityLane !== 'always') return
-      if (cfg.qualityLane === 'sampled' && input.turnId % SAMPLED_EVERY !== 0) return
-      if (this.caller === undefined || this.inFlight.has(sessionId)) return
-      if (input.ring.length === 0) return
+      if (cfg.qualityLane !== 'sampled' && cfg.qualityLane !== 'always') {
+        this.traceOutcome(sessionId, input.turnId, 'no-run', 'lane-off')
+        return
+      }
+      if (cfg.qualityLane === 'sampled' && input.turnId % SAMPLED_EVERY !== 0) {
+        this.traceOutcome(sessionId, input.turnId, 'no-run', 'cadence')
+        return
+      }
+      if (this.caller === undefined) {
+        this.traceOutcome(sessionId, input.turnId, 'no-run', 'no-caller')
+        return
+      }
+      if (this.inFlight.has(sessionId)) {
+        this.traceOutcome(sessionId, input.turnId, 'no-run', 'in-flight')
+        return
+      }
+      if (input.ring.length === 0) {
+        this.traceOutcome(sessionId, input.turnId, 'no-run', 'empty-ring')
+        return
+      }
       const run = this.produce(sessionId, input).finally(() => {
         this.inFlight.delete(sessionId)
         this.onSettle(sessionId)
@@ -424,11 +509,15 @@ export class SlowLane {
 
   private async produce(sessionId: string, input: DispatchInput): Promise<void> {
     const caller = this.caller
-    if (caller === undefined) return
+    if (caller === undefined) return // unreachable — dispatch gated it, already traced
     const started = Date.now()
     const controller = new AbortController()
     const deadline = setTimeout(() => controller.abort(), PIPELINE_TIMEOUT_MS)
     deadline.unref?.()
+    // A4 决议 3: every exit qualifies — outcome on the session + the ledger.
+    const trace = (outcome: SlowOutcome, reason: string): void => {
+      this.traceOutcome(sessionId, input.turnId, outcome, reason, { ms: Date.now() - started })
+    }
     try {
       const cfg = this.service.cfg
       const ringText = input.ring
@@ -453,9 +542,13 @@ export class SlowLane {
       try {
         built = parseJsonObject(buildRaw)
       } catch {
-        return // unparseable build → no pending, nothing logged, next turn retries
+        trace('llm-error', 'build-bad-json') // unparseable build → no pending, next turn retries
+        return
+      }
+      if (built.needs !== true || typeof built.query !== 'string' || built.query.trim() === '') {
+        trace('no-claim', 'build-no-need') // the query builder claimed no background need
+        return
       }
-      if (built.needs !== true || typeof built.query !== 'string' || built.query.trim() === '') return
       const query = built.query.trim()
       const stripped = Array.isArray(built.ignore)
         ? built.ignore.filter((s): s is string => typeof s === 'string' && s.trim() !== '').slice(0, 5)
@@ -463,7 +556,10 @@ export class SlowLane {
       const queryBuild: QueryBuildShape = { rawChars: ringText.length, keptChars: query.length, stripped }
 
       const roster = await this.service.roster().catch(() => [])
-      if (roster.length === 0) return
+      if (roster.length === 0) {
+        trace('no-candidates', 'roster-empty')
+        return
+      }
       // Recall-oriented band: gate OFF (the rerank IS this lane's gate);
       // candidates = threshold passers + the near-miss band beneath them.
       const band = searchTopics(query, roster, {
@@ -478,7 +574,10 @@ export class SlowLane {
       const candidates = [...band.hits, ...band.nearMisses]
         .filter((c) => !exclude?.has(c.slug))
         .slice(0, CANDIDATE_LIMIT)
-      if (candidates.length === 0) return
+      if (candidates.length === 0) {
+        trace('no-candidates', 'band-empty')
+        return
+      }
       const bySlug = new Map(roster.map((r) => [r.slug, r]))
       const payload = candidates.flatMap((c) => {
         const meta = bySlug.get(c.slug)
@@ -494,7 +593,10 @@ export class SlowLane {
           },
         ]
       })
-      if (payload.length === 0) return
+      if (payload.length === 0) {
+        trace('no-candidates', 'payload-empty')
+        return
+      }
       // ---- jev batch rerank (design §2 row 1) — replaces the LLM rerank ----
       // One batched noul request over the whole band; the calibrated bands
       // decide the picks. A settled jev round is FINAL here (picks or none) —
@@ -503,9 +605,15 @@ export class SlowLane {
       if (this.service.cfg.jevEnabled === true) {
         const jevItems = await this.jevRerank(query, payload)
         if (jevItems !== undefined) {
-          if (jevItems.length > 0) this.settlePending(sessionId, input, jevItems, queryBuild, started)
+          if (jevItems.length > 0) {
+            this.settlePending(sessionId, input, jevItems, queryBuild, started)
+            trace('delivered', 'jev-picks')
+          } else {
+            trace('no-candidates', 'jev-zero-picks')
+          }
           return
         }
+        // jev failure → the legacy rerank below owns the final trace.
       }
       const rerankRaw = await withTimeout(
         caller({
@@ -528,6 +636,7 @@ export class SlowLane {
       try {
         reranked = parseJsonObject(rerankRaw)
       } catch {
+        trace('llm-error', 'rerank-bad-json')
         return
       }
       const legal = new Set(payload.map((p) => p.slug))
@@ -545,16 +654,28 @@ export class SlowLane {
         items.push({ slug, why: why.trim().slice(0, 200) })
         if (items.length >= 2) break
       }
-      if (items.length === 0) return
+      if (items.length === 0) {
+        trace('no-candidates', 'rerank-zero-picks') // ran fine, gate picked nothing worth injecting
+        return
+      }
       this.settlePending(sessionId, input, items, queryBuild, started)
-    } catch {
-      // timeouts, aborts, model errors — I3: the async product is simply absent
+      trace('delivered', 'rerank-picks')
+    } catch (e) {
+      // RED LINE, A4 决议 3 (revising the old silent catch): the fast lane's
+      // fail-silently principle only covers the SYNCHRONOUS seam — this is an
+      // async lane, so the failure must be observable while still never
+      // rethrowing at the caller (I3 可丢弃性: the async product is absent,
+      // but its absence is now qualified, not mute).
+      trace(classifySlowError(e, controller), 'call-failed')
     } finally {
       clearTimeout(deadline)
     }
   }
 
-  /** One pending slot per settled pipeline (the 0-2 picks + lane metadata). */
+  /** One pending slot per settled pipeline (the 0-2 picks + lane metadata).
+   *  The pending carries its producing run's disposition (A4 §3.2) so the
+   *  ilog writer can copy it verbatim — a pending only exists when the run
+   *  delivered, hence the constant. */
   private settlePending(sessionId: string, input: DispatchInput, items: { slug: string; why: string }[], queryBuild: QueryBuildShape, started: number): void {
     const route = this.service.cfg
     this.pending.set(sessionId, {
@@ -564,6 +685,7 @@ export class SlowLane {
       queryBuild,
       model: `${route.distillProvider}/${route.distillModel}`,
       ms: Date.now() - started,
+      outcome: 'delivered',
     })
   }
 
@@ -657,10 +779,12 @@ export class SlowLane {
     const produced = Date.parse(pending.computedAt)
     if (!Number.isNaN(produced) && Date.now() - produced > PENDING_TTL_MS) {
       this.pending.delete(sessionId)
+      this.traceOutcome(sessionId, turnId, 'expired', 'ttl', { ageMs: Date.now() - produced })
       return { expired: 'ttl' }
     }
     if (turnId - pending.turnId > TURN_LAG_LIMIT) {
       this.pending.delete(sessionId)
+      this.traceOutcome(sessionId, turnId, 'expired', 'turn-lag', { producedTurnId: pending.turnId })
       return { expired: 'turn-lag' }
     }
     this.pending.delete(sessionId)

package/src/retrieval.ts

@@ -12,8 +12,11 @@
  * @module retrieval
  */
 
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
 import type { TopicMeta } from './store.ts'
 import { dependsSlugs } from './okf.ts'
+import type { EmbedResult } from './embedding.ts'
 
 export interface RetrievableTopic extends TopicMeta {
   /** `# Conclusion` section text (may be empty). */
@@ -340,3 +343,335 @@ export function searchTopics(query: string, roster: readonly RetrievableTopic[],
   }
   return { hits, nearMisses, rosterSize: roster.length }
 }
+
+// ---------------------------------------------------------------------------
+// Injection-quality line (wave/injection-quality, spec §2.1/§3.1/§3.3) —
+// CAPABILITY ONLY. None of this is wired into searchTopics or any service
+// path; the caller gates it on packageMode ≠ 'off' (Phase 2 wiring). With
+// the config keys at their defaults every code path below is unreachable
+// from the hot lane, so default-off behavior stays byte-for-byte.
+// ---------------------------------------------------------------------------
+
+// --- ① Query sanitization (A4 决议 4, spec §3.3) ---------------------------
+// Pure, LLM-free, millisecond-scale. Treats the queryTokenCount p90=462
+// paste-pollution tail: fenced code blocks, URLs, line-leading shell
+// prompts, over-long lines, and a hard token cap.
+
+/**
+ * Token cap in tokenize() units — the SAME unit injections.jsonl logs as
+ * queryTokenCount (p90=462 baseline; real-query p50=153 stays untouched).
+ * Raised or lowered via SanitizeOptions.maxTokens.
+ */
+export const QUERY_TOKEN_CAP = 96
+
+/**
+ * Lines longer than this are folded to their head (log-paste guard). Sized
+ * so the 96-token cap is the binding constraint, not the fold: 96 latin
+ * tokens ≈ 650+ chars, so a legitimate long single-line query passes the
+ * fold intact and only the token cap trims it. (实现期定 constant.)
+ */
+export const MAX_LINE_CHARS = 720
+
+export interface SanitizeOptions {
+  maxTokens?: number
+  maxLineChars?: number
+}
+
+const FENCE_OPEN = /^[ \t]*(```|~~~)/
+// Line-leading shell prompt: `user@host:~/repo$ `, `C:\> `, or a bare
+// `$ `/`# `/`% `/`> `/`❯ ` marker. Requires trailing whitespace so words
+// like `$PATH` or `#tag` survive untouched.
+const LINE_PROMPT = /^[ \t]*(?:[\w.@:/\\~-]*[$#%>❯➜])[ \t]+/
+const URL_RE = /\b(?:https?:\/\/|www\.)[^\s<>"'`)\]]+/gi
+// Chunks the cap walks: one latin/digit word (or hyphenated compound) per
+// match, or one CJK run (sliced when a run alone busts the cap).
+const CHUNK_RUN = new RegExp(`${WORD_RUN.source}|${CJK_RUN.source}`, 'gu')
+
+/** Remove fenced code blocks wholesale (markers AND body): fenced code is
+ *  the paste-pollution payload; the prose around it is the actual query. */
+function stripFencedBlocks(text: string): string {
+  const out: string[] = []
+  let open: string | null = null
+  for (const line of text.split('\n')) {
+    const m = line.match(FENCE_OPEN)
+    if (open === null) {
+      if (m !== null) open = m[1]
+      else out.push(line)
+    } else if (m !== null && m[1] === open) {
+      open = null // closing fence — block fully dropped
+    }
+    // inside an open fence: drop the line
+  }
+  return out.join('\n')
+}
+
+/** Cap the sanitized text to ≤ cap distinct retrieval tokens. Fast path:
+ *  at or under the cap the text passes through VERBATIM (no re-chunking —
+ *  hyphens, punctuation and spacing survive byte-exact; retrieval scores
+ *  tokens, not bytes, but the string may be echoed into logs/injection).
+ *  Only an over-cap text rebuilds from chunks: head-first (a query's intent
+ *  leads; pollution trails), with CJK runs sliced at the character level so
+ *  a single giant run truncates instead of being dropped whole. */
+function capTokens(text: string, cap: number): string {
+  const total = tokenize(text).length
+  if (total === 0) return '' // nothing lexical survives — caller sees a zero-token query
+  if (total <= cap) return text
+  const seen = new Set<string>()
+  const kept: string[] = []
+  for (const chunk of text.match(CHUNK_RUN) ?? []) {
+    const fresh = tokenize(chunk).filter((t) => !seen.has(t))
+    if (fresh.length === 0) continue // already-covered chunk adds nothing
+    if (seen.size + fresh.length <= cap) {
+      for (const t of fresh) seen.add(t)
+      kept.push(chunk)
+      continue
+    }
+    const room = cap - seen.size
+    if (room <= 0) break
+    // Over budget: CJK runs truncate exactly (slice room+1 chars → ≤ room
+    // fresh bigrams, so the cap invariant holds). Latin chunks are single
+    // tokens by construction — they never reach here with room > 0, but if
+    // one ever does, dropping it beats busting the cap.
+    if (/^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u.test(chunk)) {
+      kept.push(chunk.slice(0, room + 1))
+    }
+    break
+  }
+  return kept.join(' ')
+}
+
+/**
+ * Sanitize a raw user query for retrieval (spec §3.3): strip fenced code
+ * blocks and URLs, fold line-leading shell prompts, fold over-long lines to
+ * their head, cap the distinct-token count. Returns '' when nothing lexical
+ * survives — the caller treats that as a zero-token query (natural skip).
+ * Pure function; the hot lane only reaches it behind packageMode.
+ */
+export function sanitizeQuery(raw: string, opts: SanitizeOptions = {}): string {
+  const cap = opts.maxTokens ?? QUERY_TOKEN_CAP
+  const maxLineChars = opts.maxLineChars ?? MAX_LINE_CHARS
+  if (raw === '') return ''
+  let text = stripFencedBlocks(raw)
+  text = text.replace(URL_RE, ' ')
+  text = text
+    .split('\n')
+    .map((line) => {
+      let l = line.replace(LINE_PROMPT, '')
+      if (l.length > maxLineChars) l = l.slice(0, maxLineChars)
+      return l
+    })
+    .join('\n')
+  text = text.replace(/\s+/g, ' ').trim()
+  if (text === '') return ''
+  return capTokens(text, cap)
+}
+
+// --- ② Embedding index (A4 决议 2, spec §3.1) -------------------------------
+// meta/embeddings.json: { slug: { model, dim, vec } }. Loading and auditing
+// never throws; a missing/corrupt index reads as EMPTY, which routes every
+// semantic path into the explicit passthrough below.
+
+export interface EmbeddingIndexEntry {
+  model: string
+  dim: number
+  vec: number[]
+}
+
+/** slug -> entry, exactly as persisted in meta/embeddings.json. */
+export type EmbeddingIndex = Record<string, EmbeddingIndexEntry>
+
+export function embeddingIndexPath(bundleDir: string): string {
+  return join(bundleDir, 'meta', 'embeddings.json')
+}
+
+function parseEmbeddingIndexEntry(value: unknown): EmbeddingIndexEntry | null {
+  if (typeof value !== 'object' || value === null) return null
+  const e = value as Record<string, unknown>
+  if (typeof e.model !== 'string' || e.model === '') return null
+  if (typeof e.dim !== 'number' || !Number.isInteger(e.dim) || e.dim <= 0) return null
+  if (!Array.isArray(e.vec) || e.vec.length !== e.dim) return null
+  if (!e.vec.every((n) => typeof n === 'number' && Number.isFinite(n))) return null
+  return { model: e.model, dim: e.dim, vec: e.vec as number[] }
+}
+
+/** Load meta/embeddings.json from a bundle dir. Missing file, corrupt JSON,
+ *  or malformed entries are skipped/empty — never throws (a broken index
+ *  must degrade to the lexical path, not break retrieval). */
+export function loadEmbeddingIndex(bundleDir: string): EmbeddingIndex {
+  let raw: string
+  try {
+    raw = readFileSync(embeddingIndexPath(bundleDir), 'utf8')
+  } catch {
+    return {}
+  }
+  try {
+    const json: unknown = JSON.parse(raw)
+    if (typeof json !== 'object' || json === null || Array.isArray(json)) return {}
+    const out: EmbeddingIndex = {}
+    for (const [slug, entry] of Object.entries(json as Record<string, unknown>)) {
+      if (slug === '') continue
+      const parsed = parseEmbeddingIndexEntry(entry)
+      if (parsed !== null) out[slug] = parsed
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+/** Persist the index in the canonical shape (the rebuild's write side —
+ *  embedding/rebuilding itself stays with the caller). Offline rebuild
+ *  path, not the hot lane. */
+export function saveEmbeddingIndex(bundleDir: string, index: EmbeddingIndex, mkdir = true): void {
+  if (mkdir) mkdirSync(join(bundleDir, 'meta'), { recursive: true })
+  writeFileSync(embeddingIndexPath(bundleDir), JSON.stringify(index))
+}
+
+/**
+ * An embed function bound to a config, carrying the RESOLVED model identity
+ * the index must match (build once via embedding.ts's `embedderWith`).
+ * ensureIndexFresh reads `.model` only — it never calls the function; the
+ * rebuild is the caller's job.
+ */
+export type EmbedderFn = ((texts: readonly string[]) => Promise<EmbedResult>) & { model: string }
+
+/**
+ * Freshness audit: which slugs need (re)embedding — missing from the index,
+ * built by a different model, or shape-broken (dim/vec disagree). Returns
+ * them in roster order; an EMPTY list means the index covers the roster.
+ * A '' embedder model means the semantic layer is off → nothing to maintain.
+ *
+ * NOTE the freshness boundary: content-change invalidation needs a stored
+ * content hash, which the pinned {model,dim,vec} entry shape does not carry
+ * — the rebuild trigger policy is spec-实现期定 and stays with the caller.
+ */
+export function ensureIndexFresh(index: EmbeddingIndex, topics: readonly { slug: string }[], embedFn: EmbedderFn): string[] {
+  if ((embedFn.model ?? '') === '') return []
+  const stale: string[] = []
+  for (const t of topics) {
+    const e = index[t.slug]
+    if (e === undefined || e.model !== embedFn.model || e.dim !== e.vec.length || !(e.dim > 0)) stale.push(t.slug)
+  }
+  return stale
+}
+
+// --- ③ nearFloor semantic rerank (A4 决议 2, spec §3.1) ---------------------
+// Cosine reordering of the nearFloor band ONLY (0.20–0.30 — the 93%
+// near-miss mass). Thresholds, gateScore and the structural gate are
+// untouched: the reranker reorders and tags, never re-scores.
+
+export const RERANK_FLOOR = 0.2
+export const RERANK_CEILING = 0.3
+export const SEMANTIC_RERANK_REASON = 'semantic-rerank'
+
+export interface RerankedHit extends SearchHit {
+  /** Cosine(query, slug-vector), rounded 4dp. Present only on reranked
+   *  hits; absent = the candidate rode through unchanged. */
+  similarity?: number
+}
+
+export type RerankPassthroughReason =
+  | 'no-candidates' // nothing to rank
+  | 'no-query-vector' // embed failed upstream — the explicit degradation
+  | 'empty-index' // meta/embeddings.json absent/corrupt
+  | 'no-rerankable-candidates' // band candidates lack usable index vectors
+
+export interface RerankOptions {
+  /** Expected index model; entries built by another model count as
+   *  vector-less (they ride through at the band tail). */
+  expectedModel?: string
+  floor?: number
+  ceiling?: number
+}
+
+export interface RerankResult {
+  /** Candidates in final order. On passthrough: the input array, same
+   *  order, no tags — byte-identical ordering, explicit why. */
+  hits: RerankedHit[]
+  /** true = the semantic layer engaged (order may or may not have moved). */
+  reranked: boolean
+  passthroughReason?: RerankPassthroughReason
+}
+
+/** Cosine similarity; 0 for dim mismatch or zero vectors (never throws). */
+export function cosineSimilarity(a: readonly number[], b: readonly number[]): number {
+  if (a.length === 0 || a.length !== b.length) return 0
+  let dot = 0
+  let na = 0
+  let nb = 0
+  for (let i = 0; i < a.length; i += 1) {
+    dot += a[i]! * b[i]!
+    na += a[i]! * a[i]!
+    nb += b[i]! * b[i]!
+  }
+  if (na === 0 || nb === 0) return 0
+  return dot / Math.sqrt(na * nb)
+}
+
+/**
+ * Reorder the nearFloor band (0.20–0.30 by gateScore) by cosine similarity
+ * against the query vector. Band members with a usable index vector sort by
+ * similarity (stable — ties keep input order) and gain the
+ * `semantic-rerank` reason plus their similarity; everyone else — out of
+ * band, unindexed, model-mismatched — passes through UNCHANGED at the tail
+ * in input order. Scores are never touched.
+ *
+ * Degradation is explicit and total: provider/model unconfigured, probe
+ * failure, missing query vector or missing index all return the input as-is
+ * with `reranked:false` and a passthroughReason (原序透传，不许静默 — the
+ * caller logs it into the degraded status). `queryText` rides the signature
+ * for provenance/debug parity with the caller's logging; the v1 math is
+ * vector-only.
+ */
+export function rerankNearFloor(
+  queryText: string,
+  queryVec: readonly number[] | null | undefined,
+  nearFloorCandidates: readonly SearchHit[],
+  index: EmbeddingIndex,
+  opts: RerankOptions = {},
+): RerankResult {
+  void queryText // v1 math is vector-only — see doc above
+  if (nearFloorCandidates.length === 0) {
+    return { hits: [], reranked: false, passthroughReason: 'no-candidates' }
+  }
+  if (!Array.isArray(queryVec) || queryVec.length === 0) {
+    return { hits: [...nearFloorCandidates], reranked: false, passthroughReason: 'no-query-vector' }
+  }
+  if (Object.keys(index).length === 0) {
+    return { hits: [...nearFloorCandidates], reranked: false, passthroughReason: 'empty-index' }
+  }
+  const floor = opts.floor ?? RERANK_FLOOR
+  const ceiling = opts.ceiling ?? RERANK_CEILING
+  const simOf = new Map<SearchHit, number | null>()
+  for (const hit of nearFloorCandidates) {
+    const entry = index[hit.slug]
+    const usable =
+      entry !== undefined &&
+      entry.dim === entry.vec.length &&
+      entry.dim > 0 &&
+      entry.dim === queryVec.length &&
+      (opts.expectedModel === undefined || entry.model === opts.expectedModel)
+    simOf.set(hit, usable ? cosineSimilarity(queryVec, entry.vec) : null)
+  }
+  const band = nearFloorCandidates.filter((h) => {
+    const sim = simOf.get(h)
+    return sim !== null && sim !== undefined && h.gateScore !== undefined && h.gateScore >= floor && h.gateScore < ceiling
+  })
+  if (band.length === 0) {
+    return { hits: [...nearFloorCandidates], reranked: false, passthroughReason: 'no-rerankable-candidates' }
+  }
+  const rerankedSet = new Set(band)
+  const tail = nearFloorCandidates.filter((h) => !rerankedSet.has(h))
+  // Stable sort: V8's Array#sort keeps input order for equal similarities.
+  const ordered = [...band].sort((x, y) => (simOf.get(y) as number) - (simOf.get(x) as number))
+  return {
+    hits: [
+      ...ordered.map((h) => {
+        const sim = simOf.get(h) as number
+        return { ...h, reasons: [...h.reasons, SEMANTIC_RERANK_REASON], similarity: Math.round(sim * 10_000) / 10_000 }
+      }),
+      ...tail.map((h) => ({ ...h })),
+    ],
+    reranked: true,
+  }
+}