@aiwayds/dsh-topics-memory 0.22.0 → 0.23.0

package/lib/retrieval.js

@@ -11,6 +11,8 @@
  *
  * @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). */
@@ -256,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,6 +33,8 @@ 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;
@@ -101,6 +103,18 @@ export declare class TopicsService {
      * 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
@@ -178,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;

package/lib/service.js

@@ -6,11 +6,13 @@
  * @module service
  */
 import { readFile, stat } from 'node:fs/promises';
-import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import * as okf from "./okf.js";
-import { searchTopics, scoreTopic, passesGate, tokenize } from "./retrieval.js";
-import { assembleInjection, assemblePointer, POINTER_PER_TOPIC, POINTER_TOTAL } from "./digest.js";
+import { searchTopics, scoreTopic, passesGate, tokenize, sanitizeQuery, loadEmbeddingIndex, rerankNearFloor, ensureIndexFresh, saveEmbeddingIndex } from "./retrieval.js";
+import { assembleInjection, assemblePointer, assemblePackage, POINTER_PER_TOPIC, POINTER_TOTAL } from "./digest.js";
+import { embedTexts, embedQuerySync, embedderWith, resolveEmbedModel } from "./embedding.js";
+import { resolveBundleRoot } from "./paths.js";
 import { aggregateStats, querySample, aggregateUsage, aggregateZeroOpen, ZERO_OPEN_TAIL, USAGE_WINDOW_DAYS, attributeOpen, OPEN_ATTRIBUTION_TAIL } from "./ilog.js";
 import { fileHistory, fileAtRev } from "./git.js";
 /** Tolerant JSONL line read: undefined = unreadable file. Unlike an empty
@@ -269,6 +271,73 @@ export class TopicsService {
             return {};
         return { zeroOpenDecay: true, zeroOpenSlugs: this.zeroOpenSlugsSync() };
     }
+    /** mtime-cached view of meta/embeddings.json (sync read — hot-lane caller).
+     *  Missing/corrupt index = {} → the reranker degrades to lexical order. */
+    embedIndexCache;
+    embeddingIndexCacheGet() {
+        const root = resolveBundleRoot();
+        const file = join(root, 'meta', 'embeddings.json');
+        try {
+            const st = statSync(file);
+            if (this.embedIndexCache !== undefined && this.embedIndexCache.mtimeMs === st.mtimeMs && this.embedIndexCache.size === st.size) {
+                return this.embedIndexCache.index;
+            }
+            const index = loadEmbeddingIndex(root);
+            this.embedIndexCache = { mtimeMs: st.mtimeMs, size: st.size, index };
+            return index;
+        }
+        catch {
+            return this.embedIndexCache?.index ?? {};
+        }
+    }
+    /** 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. */
+    appendPackageShadowLedger(entry) {
+        try {
+            const file = join(resolveBundleRoot(), 'meta', 'package-shadow.jsonl');
+            let lines = [];
+            try {
+                const st = statSync(file);
+                if (st.size > 512 * 1024) {
+                    const all = readFileSync(file, 'utf8').split('\n').filter((l) => l !== '');
+                    lines = all.slice(Math.floor(all.length / 4));
+                }
+            }
+            catch { /* first write */ }
+            lines.push(JSON.stringify(entry));
+            writeFileSync(file, lines.join('\n') + '\n');
+        }
+        catch { /* ledger must never break the lane */ }
+    }
+    /** 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). */
+    async refreshEmbeddingIndex() {
+        const provider = (this.cfg.embeddingProvider ?? '').trim();
+        if (provider === '' || this.cfg.packageMode === undefined || this.cfg.packageMode === 'off')
+            return;
+        const embedder = embedderWith({ provider, model: this.cfg.embeddingModel });
+        const topics = await this.roster();
+        const root = resolveBundleRoot();
+        const index = loadEmbeddingIndex(root);
+        const stale = ensureIndexFresh(index, topics, embedder);
+        if (stale.length === 0)
+            return;
+        const docs = await Promise.all(stale.map(async (slug) => (await this.readDoc(slug)) ?? ''));
+        const texts = stale.map((slug, i) => `${slug}\n${docs[i] ?? ''}`);
+        const r = await embedTexts(texts, { provider, model: this.cfg.embeddingModel });
+        if (!r.ok)
+            return;
+        const next = { ...index };
+        stale.forEach((slug, i) => {
+            const vec = r.vectors[i];
+            if (vec !== undefined)
+                next[slug] = { model: r.model, dim: vec.length, vec };
+        });
+        saveEmbeddingIndex(root, next);
+        this.embedIndexCache = undefined;
+    }
     /**
      * Full retrieval round: search → assemble → log (ADR 0006/0007). The
      * injection record is written even for zero-hit rounds — the hit-rate
@@ -389,8 +458,12 @@ export class TopicsService {
             }
             return { text: '', outcome: empty, deduped: [], echoed: [], included: [], slowIncluded: [] };
         }
+        // A-line gate (A3/A4): query cleaning + package + semantic rerank ride
+        // behind packageMode (default off = byte-for-byte legacy path).
+        const pkgMode = cfg.packageMode === 'shadow' || cfg.packageMode === 'on' ? cfg.packageMode : undefined;
+        const effectiveQuery = pkgMode !== undefined ? sanitizeQuery(query) : query;
         const conflicts = this.store.getConflictsSync();
-        const outcome = searchTopics(query, roster, {
+        const outcome = searchTopics(effectiveQuery, roster, {
             threshold: cfg.matchThreshold,
             topK: cfg.topK,
             tagBoost: cfg.tagBoost,
@@ -401,6 +474,36 @@ export class TopicsService {
             usage: this.usageSignalsSync(),
             ...this.zeroOpenCfg(),
         });
+        // ---- A-line semantic rerank (A4 决议 2, spec §3.1) ----
+        // Reorder ONLY the 0.20–0.30 nearFloor band (the 93% near-miss mass);
+        // thresholds/gateScore/hits untouched. Any failure degrades to the
+        // original order — the fast lane never blocks on the semantic layer.
+        let nearFloorRerank;
+        if (pkgMode !== undefined) {
+            const bandLo = 0.2;
+            const band = outcome.nearMisses.filter((h) => h.score >= bandLo && h.score < cfg.matchThreshold);
+            const orderBefore = band.map((h) => h.slug);
+            if (band.length > 1) {
+                const index = this.embeddingIndexCacheGet();
+                const models = new Set(Object.values(index).map((e) => e.model));
+                const embedModel = resolveEmbedModel(cfg.embeddingModel);
+                if (models.size <= 1 && (models.size === 0 || models.has(embedModel))) {
+                    const qv = embedQuerySync(effectiveQuery, { provider: cfg.embeddingProvider, model: cfg.embeddingModel });
+                    const rr = rerankNearFloor(effectiveQuery, qv.ok ? qv.vector : null, band, index);
+                    if (rr.reranked) {
+                        const inBand = (h) => h.score >= bandLo && h.score < cfg.matchThreshold;
+                        const rrSlugs = new Set(rr.hits.map((h) => h.slug));
+                        const merged = [...rr.hits, ...band.filter((h) => !rrSlugs.has(h.slug))];
+                        let mi = 0;
+                        outcome.nearMisses = outcome.nearMisses.map((h) => (inBand(h) ? merged[mi++] : h));
+                        nearFloorRerank = { reranked: true, orderBefore, orderAfter: merged.map((h) => h.slug) };
+                    }
+                    else {
+                        nearFloorRerank = { reranked: false, passthroughReason: rr.passthroughReason, orderBefore, orderAfter: orderBefore };
+                    }
+                }
+            }
+        }
         const exclude = dedup?.exclude;
         const echo = dedup?.echo;
         const deduped = exclude === undefined ? [] : outcome.hits.filter((h) => exclude.has(h.slug)).map((h) => h.slug);
@@ -431,7 +534,7 @@ export class TopicsService {
         let slowIncluded = [];
         const consumedAt = new Date().toISOString();
         if (slow !== undefined) {
-            const queryTokens = new Set(tokenize(query));
+            const queryTokens = new Set(tokenize(effectiveQuery));
             for (const item of slow.items) {
                 if (exclude?.has(item.slug)) {
                     if (!deduped.includes(item.slug))
@@ -482,9 +585,70 @@ export class TopicsService {
         const pointerMode = cfg.injectMode !== 'digest';
         // Pointer budget: per-entry fixed at the design's 80, total clamped to the
         // fast-lane upper bound of 600 (I4) — totalBudget stays tunable downward.
-        const injection = pointerMode
-            ? assemblePointer(entries, { perTopicBudget: POINTER_PER_TOPIC, totalBudget: Math.min(cfg.totalBudget, POINTER_TOTAL) }, slowPointers)
-            : assembleInjection(entries, { perTopicBudget: cfg.perTopicBudget, totalBudget: cfg.totalBudget }, slowPointers);
+        let packageSkipped = false;
+        let packageShadow;
+        let injection;
+        if (!pointerMode) {
+            injection = assembleInjection(entries, { perTopicBudget: cfg.perTopicBudget, totalBudget: cfg.totalBudget }, slowPointers);
+        }
+        else if (pkgMode === undefined) {
+            injection = assemblePointer(entries, { perTopicBudget: POINTER_PER_TOPIC, totalBudget: Math.min(cfg.totalBudget, POINTER_TOTAL) }, slowPointers);
+        }
+        else {
+            // A-line relevance package (A3, spec §2): direct = lexical hits,
+            // neighborhood = graph hits + slow picks, weak = reranked band head.
+            const budget = { perTopicBudget: POINTER_PER_TOPIC, totalBudget: Math.min(cfg.totalBudget, POINTER_TOTAL) };
+            const legacy = assemblePointer(entries, budget, slowPointers);
+            const direct = [];
+            const neighborhood = [];
+            for (const e of entries) {
+                const meta = bySlug.get(e.slug);
+                const cand = {
+                    slug: e.slug,
+                    title: meta?.title ?? e.slug,
+                    status: meta?.status ?? 'draft',
+                    description: meta?.description,
+                    conclusion: firstContentLine(e.doc.body),
+                    score: e.hit.score,
+                    reasons: e.hit.reasons,
+                    via: e.hit.viaGraph ? 'graph' : undefined,
+                };
+                (e.hit.viaGraph ? neighborhood : direct).push(cand);
+            }
+            for (const sp of slowPointers) {
+                neighborhood.push({ slug: sp.slug, title: sp.title, status: sp.status, description: sp.description, score: 0, reasons: [], via: 'slow-pick' });
+            }
+            const weak = outcome.nearMisses
+                .filter((h) => h.score >= 0.2 && h.score < cfg.matchThreshold)
+                .slice(0, 2)
+                .map((h) => {
+                const meta = bySlug.get(h.slug);
+                return { slug: h.slug, title: meta?.title ?? h.slug, status: meta?.status ?? 'draft', score: h.score, reasons: h.reasons, via: 'weak' };
+            });
+            const usage = this.usageSignalsSync();
+            const usageBySlug = new Map([...usage].map(([slug, sig]) => [slug, sig.opens * 3 + sig.hits]));
+            const pkgInput = { query: effectiveQuery, queryTokens: tokenize(effectiveQuery), direct, neighborhood, weak, usageBySlug };
+            const pkg = assemblePackage(pkgInput);
+            if (pkgMode === 'shadow') {
+                packageShadow = pkg;
+                injection = legacy;
+            }
+            else if (pkg === null) {
+                // Trivial-query downgrade (A3 决议 5): emit nothing, log the why.
+                packageSkipped = true;
+                injection = { text: '', usedTokens: 0, included: [], dropped: [] };
+            }
+            else {
+                const slowSet = new Set(slowPointers.map((sp) => sp.slug));
+                injection = {
+                    text: pkg.text,
+                    usedTokens: pkg.usedTokens,
+                    included: pkg.included,
+                    dropped: pkg.dropped,
+                    slowIncluded: pkg.included.filter((slug) => slowSet.has(slug)),
+                };
+            }
+        }
         slowIncluded = injection.slowIncluded ?? [];
         for (const pointer of slowPointers) {
             if (slowIncluded.includes(pointer.slug))
@@ -492,8 +656,8 @@ export class TopicsService {
         }
         const record = {
             at: new Date().toISOString(),
-            queryTokenCount: tokenize(query).length,
-            querySample: querySample(query),
+            queryTokenCount: tokenize(effectiveQuery).length,
+            querySample: querySample(effectiveQuery),
             rosterSize: outcome.rosterSize,
             hits: outcome.hits.map((h) => ({ slug: h.slug, score: h.score, reasons: h.reasons, viaGraph: h.viaGraph, strong: h.strong, bodyHits: h.bodyHits })),
             // Reasons ride along: the gate-blocked marker is the replay evidence
@@ -508,10 +672,28 @@ export class TopicsService {
             record.deduped = deduped;
         if (echoed.length > 0)
             record.echoed = echoed;
+        if (packageSkipped)
+            record.why = 'package-skipped-trivial';
         if (unreadable.length > 0) {
             record.dropped = [...(record.dropped ?? []), ...unreadable.map((slug) => ({ slug, reason: 'doc-unreadable' }))];
         }
+        if (pkgMode === 'shadow' && pointerMode) {
+            this.appendPackageShadowLedger({
+                at: record.at,
+                ...(sessionId !== undefined ? { sessionId } : {}),
+                queryTokenCount: record.queryTokenCount,
+                emitted: { tokens: injection.usedTokens, included: injection.included },
+                package: packageShadow === undefined
+                    ? null
+                    : packageShadow === null
+                        ? { skipped: 'trivial-or-empty' }
+                        : { tokens: packageShadow.usedTokens, included: packageShadow.included, layers: packageShadow.layers },
+                nearFloorRerank: nearFloorRerank ?? null,
+            });
+        }
         if (slow !== undefined) {
+            if (slow.outcome !== undefined)
+                record.slowOutcome = slow.outcome;
             // Any round whose pending was consumed is a slow-participating round —
             // lane never stays undefined when the lane family is present (a
             // delivered pick with fast pointers is 'mixed'; a consumed-but-empty
@@ -718,7 +900,7 @@ export class TopicsService {
             fm.triggers = triggers;
         if (existing !== undefined && existing.fm.verified !== undefined)
             fm.verified = existing.fm.verified;
-        const result = await this.store.saveTopic({ slug, doc: { fm, body } }, { message: existing === undefined ? `topics(topic): create ${slug}` : `topics(topic): update ${slug}`, created: existing === undefined });
+        const result = await this.store.saveTopic({ slug, doc: { fm, body }, links: input.links }, { message: existing === undefined ? `topics(topic): create ${slug}` : `topics(topic): update ${slug}`, created: existing === undefined });
         this.invalidate();
         void this.sync?.schedulePush();
         return { ...result, slug: result.slug };
@@ -805,6 +987,15 @@ function dedupePaths(paths) {
     }
     return out;
 }
+function firstContentLine(doc) {
+    for (const line of doc.split('\n')) {
+        const t = line.trim();
+        if (t === '' || t.startsWith('#'))
+            continue;
+        return t.slice(0, 200);
+    }
+    return '';
+}
 function sanitizeTriggers(triggers) {
     const out = [];
     for (const t of triggers) {

package/lib/store.d.ts

@@ -110,10 +110,19 @@ export declare class BundleStore {
      * Write a topic (atomic), regenerate the index, and commit both — one
      * commit per conclusion change (ADR 0003). `slug` in the doc's depends is
      * NOT normalized here; callers pass bundle-relative paths.
+     *
+     * `links` (A2, optional): whitelist-surviving semantic targets from the
+     * distill lane. Applied INSIDE this one write transaction — the topic and
+     * its edges land together (先落 topic 再建边); the Links section lands as
+     * body wikilinks and the index/backlinks regeneration below (same
+     * transaction) recomputes the edge index over them. Normalized and
+     * self/dedup-guarded here too, so any caller benefits from the same guard
+     * the distill lane already ran.
      */
     saveTopic(input: {
         slug: string;
         doc: okf.TopicDoc;
+        links?: readonly string[];
     }, opts: {
         message: string;
         actor?: string;