@aiwayds/dsh-topics-memory 0.21.0 → 0.23.0

package/lib/retrieval.d.ts

@@ -12,6 +12,7 @@
  * @module retrieval
  */
 import type { TopicMeta } from './store.ts';
+import type { EmbedResult } from './embedding.ts';
 export interface RetrievableTopic extends TopicMeta {
     /** `# Conclusion` section text (may be empty). */
     conclusion: string;
@@ -48,10 +49,23 @@ export interface RetrievalConfig {
         hits: number;
         opens: number;
     }>;
+    /**
+     * Zero-open decay (v5, default off — config `zeroOpenDecay`): halve the
+     * score of slugs on the zero-open list (≥5 rendered injections in the
+     * rolling 30 days, zero opens ever) at score-finalization time, BEFORE
+     * the threshold cut — a decayed candidate that drops below the threshold
+     * lands in nearMisses with the `zero-open-decay` reason, so the log
+     * shows why it stopped injecting. Absent/off = zero behavior change.
+     */
+    zeroOpenDecay?: boolean;
+    /** Zero-open slugs for this round (service-built from the ilog tail). */
+    zeroOpenSlugs?: ReadonlySet<string>;
 }
 /** Hard cap for the usage bonus — below threshold 0.3 so usage can never
  *  carry a candidate across the gate on its own (ADR 0015). */
 export declare const USAGE_BOOST_CAP = 0.2;
+/** Score multiplier for zero-open slugs when zeroOpenDecay is on (v5). */
+export declare const ZERO_OPEN_DECAY_FACTOR = 0.5;
 export declare const DEFAULT_RETRIEVAL: RetrievalConfig;
 /** Trigger hits outrank every other lexical field (pi-llm-wiki: highest weight). */
 export declare const TRIGGER_WEIGHT = 5;
@@ -107,3 +121,108 @@ export declare function passesGate(s: {
  * evidence shows what the gate is costing.
  */
 export declare function searchTopics(query: string, roster: readonly RetrievableTopic[], cfg?: Partial<RetrievalConfig>): SearchOutcome;
+/**
+ * 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 declare 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 declare const MAX_LINE_CHARS = 720;
+export interface SanitizeOptions {
+    maxTokens?: number;
+    maxLineChars?: number;
+}
+/**
+ * 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 declare function sanitizeQuery(raw: string, opts?: SanitizeOptions): string;
+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 declare function embeddingIndexPath(bundleDir: string): string;
+/** 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 declare function loadEmbeddingIndex(bundleDir: string): EmbeddingIndex;
+/** 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 declare function saveEmbeddingIndex(bundleDir: string, index: EmbeddingIndex, mkdir?: boolean): void;
+/**
+ * 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 declare function ensureIndexFresh(index: EmbeddingIndex, topics: readonly {
+    slug: string;
+}[], embedFn: EmbedderFn): string[];
+export declare const RERANK_FLOOR = 0.2;
+export declare const RERANK_CEILING = 0.3;
+export declare 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' | 'no-query-vector' | 'empty-index' | 'no-rerankable-candidates';
+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 declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+/**
+ * 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 declare function rerankNearFloor(queryText: string, queryVec: readonly number[] | null | undefined, nearFloorCandidates: readonly SearchHit[], index: EmbeddingIndex, opts?: RerankOptions): RerankResult;

package/lib/retrieval.js

@@ -11,10 +11,14 @@
  *
  * @module retrieval
  */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { dependsSlugs } from "./okf.js";
 /** Hard cap for the usage bonus — below threshold 0.3 so usage can never
  *  carry a candidate across the gate on its own (ADR 0015). */
 export const USAGE_BOOST_CAP = 0.2;
+/** Score multiplier for zero-open slugs when zeroOpenDecay is on (v5). */
+export const ZERO_OPEN_DECAY_FACTOR = 0.5;
 export const DEFAULT_RETRIEVAL = {
     threshold: 0.3,
     topK: 4,
@@ -149,6 +153,14 @@ export function scoreTopic(queryTokens, topic, cfg) {
         score *= 0.3;
         reasons.push('conflicted-demoted');
     }
+    // Zero-open decay (v5): same demotion family as conflicts — applied to
+    // the content score BEFORE gateScore is taken, so the threshold cut and
+    // the near-miss band both see the halved score; recency still rides
+    // outside it as the ranking tiebreaker.
+    if (cfg.zeroOpenDecay === true && cfg.zeroOpenSlugs?.has(topic.slug) === true) {
+        score *= ZERO_OPEN_DECAY_FACTOR;
+        reasons.push('zero-open-decay');
+    }
     const gateScore = score;
     score += recencyBonus;
     const bodySet = new Set([...description, ...conclusion]);
@@ -246,3 +258,281 @@ export function searchTopics(query, roster, cfg = {}) {
     }
     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;
+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) {
+    const out = [];
+    let open = 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, cap) {
+    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();
+    const kept = [];
+    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, opts = {}) {
+    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);
+}
+export function embeddingIndexPath(bundleDir) {
+    return join(bundleDir, 'meta', 'embeddings.json');
+}
+function parseEmbeddingIndexEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const e = value;
+    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 };
+}
+/** 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) {
+    let raw;
+    try {
+        raw = readFileSync(embeddingIndexPath(bundleDir), 'utf8');
+    }
+    catch {
+        return {};
+    }
+    try {
+        const json = JSON.parse(raw);
+        if (typeof json !== 'object' || json === null || Array.isArray(json))
+            return {};
+        const out = {};
+        for (const [slug, entry] of Object.entries(json)) {
+            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, index, mkdir = true) {
+    if (mkdir)
+        mkdirSync(join(bundleDir, 'meta'), { recursive: true });
+    writeFileSync(embeddingIndexPath(bundleDir), JSON.stringify(index));
+}
+/**
+ * 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, topics, embedFn) {
+    if ((embedFn.model ?? '') === '')
+        return [];
+    const stale = [];
+    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';
+/** Cosine similarity; 0 for dim mismatch or zero vectors (never throws). */
+export function cosineSimilarity(a, b) {
+    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, queryVec, nearFloorCandidates, index, opts = {}) {
+    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();
+    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) - simOf.get(x));
+    return {
+        hits: [
+            ...ordered.map((h) => {
+                const sim = simOf.get(h);
+                return { ...h, reasons: [...h.reasons, SEMANTIC_RERANK_REASON], similarity: Math.round(sim * 10_000) / 10_000 };
+            }),
+            ...tail.map((h) => ({ ...h })),
+        ],
+        reranked: true,
+    };
+}

package/lib/service.d.ts

@@ -10,7 +10,7 @@ import { type RetrievableTopic, type SearchOutcome } from './retrieval.ts';
 import { type AssembleResult } from './digest.ts';
 import type { BundleStore, Observation, SaveResult } from './store.ts';
 import type { TopicsConfigValue } from './config.ts';
-import { type AggregateStats, type QueryBuildShape, type UsageSignal } from './ilog.ts';
+import { type AggregateStats, type QueryBuildShape, type SlowOutcome, type UsageSignal } from './ilog.ts';
 import type { Sync } from './sync.ts';
 export interface RetrieveOutcome {
     outcome: SearchOutcome;
@@ -33,12 +33,20 @@ export interface SlowDelivery {
     queryBuild: QueryBuildShape;
     model: string;
     ms: number;
+    /** Producing run's disposition (A4 全留痕) — copied into ilog.slowOutcome. */
+    outcome?: SlowOutcome;
 }
 export declare class TopicsService {
     private cache;
     /** mtime-keyed parse of the observations log, grouped by session. */
     private echoCache;
-    private usageCache;
+    /** Single shared cache over the two feedback JSONL logs (S2): the key is
+     *  the (mtime,size) quartet of injections.jsonl + opens.jsonl, one read
+     *  and one tail parse feed BOTH aggregates — usageSignalsSync and
+     *  zeroOpenSlugsSync used to each keep a full-parse cache of their own.
+     *  Invalidation stays append-driven: the store only ever appends, so any
+     *  write moves mtime+size. Never populated when a read failed (N1). */
+    private logSignalsCache;
     readonly store: BundleStore;
     private readonly getConfig;
     readonly sync?: Sync;
@@ -63,10 +71,50 @@ export declare class TopicsService {
      * Usage signals (ADR 0015): mtime-cached aggregate over the injection log
      * and the opens log, rolling USAGE_WINDOW_DAYS. Synchronous like
      * echoSlugsSync — the retrieval hot path is sync — and cheap when warm:
-     * a fresh cache costs two stat() calls. Unreadable logs fail open to an
+     * a fresh cache costs two stat() calls, one read of each log, and feeds
+     * the zero-open set from the same parse. Unreadable logs fail open to an
      * empty map (no boost), never an error.
      */
     usageSignalsSync(): Map<string, UsageSignal>;
+    /**
+     * Zero-open slug set for the decay (v5): the shared aggregateZeroOpen
+     * rule over the injection tail and the whole opens log (compacted, so a
+     * full read stays small). Shares one cache and one parse with
+     * usageSignalsSync; unreadable logs fail open to an empty set (no
+     * decay), never an error. Only called when zeroOpenDecay is on.
+     */
+    zeroOpenSlugsSync(): ReadonlySet<string>;
+    /**
+     * The one shared feedback-log read behind both signals: stat both files
+     * (mtime+size quartet key), parse the injections TAIL only
+     * (ZERO_OPEN_TAIL rounds comfortably cover both 30-day windows) and the
+     * opens log whole (the zero-open rule is whole-history), then feed the
+     * two pure aggregates from that single parse. A failed read still fails
+     * open to empty inputs but NEVER populates the cache (N1) — otherwise a
+     * stat-success/read-failure race would freeze an empty snapshot until
+     * the next append.
+     */
+    private logSignalsSync;
+    /**
+     * zeroOpenDecay fields for scoring calls: empty when the gate is off —
+     * no file reads, zero behavior change — and the shared mtime-cached set
+     * when on. Spread into every searchTopics/scoreTopic cfg that already
+     * carries the usage signals (injection paths + explicit topic_search;
+     * the slow lane's recall band stays untouched, mirroring usageBoost).
+     */
+    private zeroOpenCfg;
+    /** mtime-cached view of meta/embeddings.json (sync read — hot-lane caller).
+     *  Missing/corrupt index = {} → the reranker degrades to lexical order. */
+    private embedIndexCache;
+    private embeddingIndexCacheGet;
+    /** Shadow bypass ledger (spec §8.3): one line per shadow round — feature
+     *  fields only, never query text (jev-log discipline). Silent on failure;
+     *  512KB truncation keeps the newest three quarters. */
+    private appendPackageShadowLedger;
+    /** Boot-time embedding index maintenance (spec §3: boot 校验+增量重建).
+     *  Provider '' or packageMode off → no-op (default-off byte-for-byte).
+     *  Full-roster embed on rebuild (A1 §5: ~9.5s for 137 topics). */
+    refreshEmbeddingIndex(): Promise<void>;
     /**
      * Full retrieval round: search → assemble → log (ADR 0006/0007). The
      * injection record is written even for zero-hit rounds — the hit-rate
@@ -124,6 +172,13 @@ export declare class TopicsService {
         openQuestions?: string[];
         recommendations?: string;
     }>;
+    /**
+     * Resolve the open's source attribution: the injections tail (bounded by
+     * OPEN_ATTRIBUTION_TAIL) scanned for a same-session hit within the
+     * attribution window. Read failures degrade to 'search' — attribution is
+     * telemetry, never a blocker.
+     */
+    private attributeOpen;
     /** Sync roster read (same mtime cache as roster()). */
     rosterSync(): RetrievableTopic[];
     private readDocSync;
@@ -137,6 +192,8 @@ export declare class TopicsService {
         depends?: string[];
         openQuestions?: string[];
         impact?: string[];
+        /** A2 semantic-link targets; store.saveTopic lands them as body wikilinks. */
+        links?: string[];
         status?: okf.TopicStatus;
         conclusion?: string;
         recommendations?: string;