@aiwayds/dsh-topics-memory 0.21.0 → 0.23.0

package/lib/service.js

@@ -6,18 +6,58 @@
  * @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 { aggregateStats, querySample, aggregateUsage, USAGE_WINDOW_DAYS } from "./ilog.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
+ *  array, undefined tells the caller to fail open AND skip caching — a
+ *  successful stat paired with a failed read must not freeze an empty
+ *  snapshot into the cache until the next append. */
+function readLogLinesSync(file) {
+    try {
+        return readFileSync(file, 'utf8').split('\n');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Parse already-split lines back-to-front, keeping the last `tail` parsed
+ *  records in order: blanks and torn JSON lines are skipped (and never
+ *  consume tail budget), so a torn tail line cannot crowd out a good one.
+ *  Shared by the usage/zero-open cache — one tail parse feeds both. */
+function parseJsonlLinesSync(lines, tail = Number.POSITIVE_INFINITY) {
+    const out = [];
+    for (let i = lines.length - 1; i >= 0 && out.length < tail; i -= 1) {
+        const line = lines[i];
+        if (line.trim() === '')
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            continue; // torn tail line
+        }
+    }
+    out.reverse();
+    return out;
+}
 export class TopicsService {
     cache = new Map();
     /** mtime-keyed parse of the observations log, grouped by session. */
     echoCache;
-    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). */
+    logSignalsCache;
     store;
     getConfig;
     sync;
@@ -92,7 +132,7 @@ export class TopicsService {
     invalidate() {
         this.cache.clear();
         this.echoCache = undefined;
-        this.usageCache = undefined;
+        this.logSignalsCache = undefined;
     }
     /**
      * Slugs distilled from THIS session's own turns — the echo set (2026-09
@@ -151,10 +191,34 @@ export 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() {
+        return this.logSignalsSync().signals;
+    }
+    /**
+     * 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() {
+        return this.logSignalsSync().zeroOpenSlugs;
+    }
+    /**
+     * 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.
+     */
+    logSignalsSync() {
         const injFile = join(this.store.metaDir(), 'injections.jsonl');
         const opensFile = join(this.store.metaDir(), 'opens.jsonl');
         const statOf = (file) => {
@@ -168,42 +232,111 @@ export class TopicsService {
         };
         const injSt = statOf(injFile);
         const opensSt = statOf(opensFile);
-        const cached = this.usageCache;
+        const cached = this.logSignalsCache;
         if (cached !== undefined &&
             cached.injMs === injSt.mtimeMs &&
             cached.injSize === injSt.size &&
             cached.opensMs === opensSt.mtimeMs &&
             cached.opensSize === opensSt.size) {
-            return cached.signals;
+            return cached;
+        }
+        const injLines = readLogLinesSync(injFile);
+        const opensLines = readLogLinesSync(opensFile);
+        const injections = parseJsonlLinesSync(injLines ?? [], ZERO_OPEN_TAIL);
+        const opens = parseJsonlLinesSync(opensLines ?? []);
+        const now = Date.now();
+        const signals = aggregateUsage(injections, opens, USAGE_WINDOW_DAYS, now);
+        const zeroOpenSlugs = new Set(aggregateZeroOpen(injections, opens, now).keys());
+        if (injLines !== undefined && opensLines !== undefined) {
+            this.logSignalsCache = {
+                injMs: injSt.mtimeMs,
+                injSize: injSt.size,
+                opensMs: opensSt.mtimeMs,
+                opensSize: opensSt.size,
+                signals,
+                zeroOpenSlugs,
+            };
+        }
+        return { signals, zeroOpenSlugs };
+    }
+    /**
+     * 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).
+     */
+    zeroOpenCfg() {
+        if (this.cfg.zeroOpenDecay !== true)
+            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 ?? {};
         }
-        const parseLines = (file) => {
-            const out = [];
+    }
+    /** 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 {
-                for (const line of readFileSync(file, 'utf8').split('\n')) {
-                    if (line.trim() === '')
-                        continue;
-                    try {
-                        out.push(JSON.parse(line));
-                    }
-                    catch {
-                        continue; // torn tail line
-                    }
+                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 {
-                // unreadable log: contribute nothing
-            }
-            return out;
-        };
-        const signals = aggregateUsage(parseLines(injFile), parseLines(opensFile), USAGE_WINDOW_DAYS, Date.now());
-        this.usageCache = {
-            injMs: injSt.mtimeMs,
-            injSize: injSt.size,
-            opensMs: opensSt.mtimeMs,
-            opensSize: opensSt.size,
-            signals,
-        };
-        return signals;
+            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
@@ -230,6 +363,7 @@ export class TopicsService {
             conflicts,
             usageBoost: cfg.usageBoost,
             usage: this.usageSignalsSync(),
+            ...this.zeroOpenCfg(),
         });
         const bySlug = new Map(roster.map((r) => [r.slug, r]));
         const entries = [];
@@ -324,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,
@@ -334,7 +472,38 @@ export class TopicsService {
             conflicts,
             usageBoost: cfg.usageBoost,
             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);
@@ -365,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))
@@ -397,6 +566,7 @@ export class TopicsService {
                     structuralGate: true,
                     usageBoost: cfg.usageBoost,
                     usage: this.usageSignalsSync(),
+                    ...this.zeroOpenCfg(),
                 });
                 shadow.push({
                     slug: item.slug,
@@ -415,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))
@@ -425,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
@@ -441,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
@@ -501,9 +750,14 @@ export class TopicsService {
         if (doc === undefined)
             return { found: false, slug };
         // Awaited (tool path, not hot): a settled write makes the pointer-open
-        // stat reliable; a failed log write must not fail the tool.
+        // stat reliable; a failed log write must not fail the tool. Source
+        // attribution rides the same write: a cheap injections-tail scan decides
+        // pointer vs search and, for pointers, carries the hit score and the
+        // open→injection lag (ilog.attributeOpen).
+        const at = new Date().toISOString();
+        const attribution = await this.attributeOpen(slug, sessionId, Date.parse(at));
         await this.store
-            .appendOpenRecord({ slug, at: new Date().toISOString(), ...(sessionId !== undefined ? { sessionId } : {}) })
+            .appendOpenRecord({ slug, at, ...(sessionId !== undefined ? { sessionId } : {}), ...attribution })
             .catch(() => undefined);
         // Optional fields are OMITTED, never present-as-undefined: the host's
         // tool-output validation rejects any object carrying an undefined-valued
@@ -523,6 +777,18 @@ export class TopicsService {
             found.description = doc.fm.description;
         return found;
     }
+    /**
+     * 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.
+     */
+    async attributeOpen(slug, sessionId, nowMs) {
+        if (sessionId === undefined)
+            return { source: 'search' };
+        const tail = await this.store.readInjectionRecords(OPEN_ATTRIBUTION_TAIL).catch(() => []);
+        return attributeOpen(tail, slug, sessionId, nowMs);
+    }
     /** Sync roster read (same mtime cache as roster()). */
     rosterSync() {
         let files;
@@ -634,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 };
@@ -656,6 +922,7 @@ export class TopicsService {
             conflicts: await this.store.getConflicts(),
             usageBoost: cfg.usageBoost,
             usage: this.usageSignalsSync(),
+            ...this.zeroOpenCfg(),
         });
     }
     async history(slug, limit = 20) {
@@ -720,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

@@ -9,7 +9,7 @@
  * @module store
  */
 import * as okf from './okf.ts';
-import type { InjectionRecord } from './ilog.ts';
+import type { InjectionRecord, OpenRecord } from './ilog.ts';
 export interface TopicMeta {
     slug: string;
     title: string;
@@ -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;
@@ -171,18 +180,12 @@ export declare class BundleStore {
     private compactInjectionsIfNeeded;
     readInjectionRecords(limit?: number): Promise<InjectionRecord[]>;
     private opensPath;
-    appendOpenRecord(record: {
-        slug: string;
-        at: string;
-        sessionId?: string;
-    }): Promise<void>;
+    appendOpenRecord(record: OpenRecord): Promise<void>;
     private compactOpensIfNeeded;
-    /** Opens in the recent window; tolerant of a torn tail like the other JSONLs. */
-    readOpenRecords(limit?: number): Promise<{
-        slug: string;
-        at: string;
-        sessionId?: string;
-    }[]>;
+    /** Opens in the recent window; tolerant of a torn tail like the other JSONLs.
+     *  Enrichment fields (sessionId/source/score/sinceInjectionMs) are optional:
+     *  pre-enrichment lines carry only slug/at and read back without them. */
+    readOpenRecords(limit?: number): Promise<OpenRecord[]>;
     getConflicts(): Promise<Set<string>>;
     /** Sync variant for the injection hot path. */
     getConflictsSync(): Set<string>;

package/lib/store.js

@@ -42,6 +42,14 @@ function dedupePaths(paths) {
 function sameStrings(a, b) {
     return a.length === b.length && a.every((v, i) => v === b[i]);
 }
+/**
+ * Body heading for caller-supplied semantic links (A2). Links are rendered as
+ * `[[wikilinks]]` under this section so the EXISTING link-edge machinery
+ * (okf.bodyLinkSlugs → computeBacklinks → retrieval graph walk) indexes them
+ * as `via: 'link'` edges — the edge representation gains no new type; the
+ * body landing spot is what makes them first-class links for free.
+ */
+const LINKS_HEADING = 'Links';
 export class BundleStore {
     root;
     actor;
@@ -285,6 +293,14 @@ export 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.
      */
     async saveTopic(input, opts) {
         return this.enqueue(async () => {
@@ -292,9 +308,24 @@ export class BundleStore {
             const file = this.topicPath(slug);
             const created = opts.created ?? !(await existsSync(file));
             const now = new Date().toISOString();
+            let body = input.doc.body;
+            if (input.links !== undefined && input.links.length > 0) {
+                const targets = [];
+                for (const raw of input.links) {
+                    if (typeof raw !== 'string')
+                        continue;
+                    const target = okf.normalizeLinkTarget(raw);
+                    if (target === undefined || target === slug || targets.includes(target))
+                        continue;
+                    targets.push(target);
+                }
+                if (targets.length > 0) {
+                    body = okf.setSection(body, LINKS_HEADING, targets.map((t) => `- [[${t}]]`).join('\n'));
+                }
+            }
             const doc = {
                 fm: { ...input.doc.fm, generated: { by: opts.actor ?? this.actor, at: now } },
-                body: input.doc.body,
+                body,
             };
             const raw = okf.serializeTopicDoc(doc);
             await atomicWrite(file, raw);
@@ -544,7 +575,8 @@ export class BundleStore {
     }
     // ------------------------------------------------------------------
     // Pointer-open log (v4 §4.3) — one line per topic_open call; feeds the
-    // 「指针打开率」 stat. Features only (slug/time), never conversation text.
+    // 「指针打开率」 stat. Features only (slug/time + attribution), never
+    // conversation text.
     // ------------------------------------------------------------------
     opensPath() {
         return join(this.metaDir(), 'opens.jsonl');
@@ -568,7 +600,9 @@ export class BundleStore {
         const lines = (await readFile(file, 'utf8')).split('\n').filter((l) => l.trim() !== '');
         await atomicWrite(file, lines.slice(-Math.max(1, Math.floor(lines.length / 4))).map((l) => `${l}\n`).join(''));
     }
-    /** Opens in the recent window; tolerant of a torn tail like the other JSONLs. */
+    /** Opens in the recent window; tolerant of a torn tail like the other JSONLs.
+     *  Enrichment fields (sessionId/source/score/sinceInjectionMs) are optional:
+     *  pre-enrichment lines carry only slug/at and read back without them. */
     async readOpenRecords(limit = 2000) {
         let raw;
         try {
@@ -587,6 +621,12 @@ export class BundleStore {
                     const rec = { slug: parsed.slug, at: parsed.at };
                     if (typeof parsed.sessionId === 'string')
                         rec.sessionId = parsed.sessionId;
+                    if (parsed.source === 'pointer' || parsed.source === 'search')
+                        rec.source = parsed.source;
+                    if (typeof parsed.score === 'number')
+                        rec.score = parsed.score;
+                    if (typeof parsed.sinceInjectionMs === 'number')
+                        rec.sinceInjectionMs = parsed.sinceInjectionMs;
                     out.push(rec);
                 }
             }

package/lib/tools.js

@@ -108,8 +108,12 @@ export function buildTopicTools(service) {
                 },
             ],
         },
-        async execute(args) {
-            return await service.openTopic(args.slug);
+        async execute(args, exec) {
+            // The agent handle on the run context IS the session (Agent.id is the
+            // session id — the same key the injection records use). Absent in
+            // bare test/host contexts: attribution then degrades to 'search'.
+            const sessionId = exec?.agent !== undefined ? String(exec.agent.id) : undefined;
+            return await service.openTopic(args.slug, sessionId);
         },
     });
     const topicSearch = defineTool({