@aiwayds/dsh-topics-memory 0.22.0 → 0.24.0

package/lib/service.js

@@ -6,12 +6,15 @@
  * @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, lessonEntryText, lessonSourceTag, POINTER_PER_TOPIC, POINTER_TOTAL } from "./digest.js";
+import { embedTexts, embedQuerySync, embedderWith, resolveEmbedModel } from "./embedding.js";
+import { currentWorkspaceId, resolveBundleRoot } from "./paths.js";
 import { aggregateStats, querySample, aggregateUsage, aggregateZeroOpen, ZERO_OPEN_TAIL, USAGE_WINDOW_DAYS, attributeOpen, OPEN_ATTRIBUTION_TAIL } from "./ilog.js";
+import { recordPipelineEvent } from "./pipeline-events.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
@@ -111,6 +114,12 @@ export class TopicsService {
             // with its survivor for the injection budget.
             if (doc.fm.status === 'deprecated')
                 continue;
+            // Lesson-kind entries (B2) never ride the topic pipeline — they have
+            // their own gate (lessonInject), confidence rule and scope filter in
+            // lessonsSync(). Gate-independent separation: even with lessonInject
+            // off, a hint lesson must not leak through the topic lexical lane.
+            if (okf.topicKindOf(doc.fm.type) === 'lesson')
+                continue;
             out.push({
                 slug: entry.slug,
                 title: doc.fm.title,
@@ -269,6 +278,80 @@ 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. Shared by the package
+     *  shadow (meta/package-shadow.jsonl) and the lesson shadow (B2,
+     *  meta/lesson-shadow.jsonl). */
+    appendShadowLedger(file, entry) {
+        try {
+            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 */ }
+    }
+    packageShadowLedgerPath() {
+        return join(resolveBundleRoot(), 'meta', 'package-shadow.jsonl');
+    }
+    lessonShadowLedgerPath() {
+        return join(resolveBundleRoot(), 'meta', 'lesson-shadow.jsonl');
+    }
+    /** 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
@@ -358,7 +441,12 @@ export class TopicsService {
         const cfg = this.cfg;
         const roster = this.rosterSync();
         const empty = { hits: [], nearMisses: [], rosterSize: roster.length };
-        if (!cfg.autoInject || query.trim() === '' || roster.length === 0) {
+        // Lesson gate (B2): established lessons are INDEPENDENT of the topic
+        // roster — a lesson-only bundle still injects lessons. The roster read is
+        // shared with the matching block below; gate off → no read at all.
+        const lessonGate = cfg.lessonInject === 'shadow' || cfg.lessonInject === 'on' ? cfg.lessonInject : undefined;
+        const lessonRoster = lessonGate !== undefined ? this.lessonsSync() : [];
+        if (!cfg.autoInject || query.trim() === '' || (roster.length === 0 && lessonRoster.length === 0)) {
             // A consumed/expired pending must always leave an ilog trace (ADR 0014:
             // 过期/消费都写 ilog) — even when the fast path early-returns here
             // because the roster vanished between production and consumption.
@@ -387,10 +475,14 @@ export class TopicsService {
                 }
                 void this.store.appendInjectionRecord(trace).catch(() => undefined);
             }
-            return { text: '', outcome: empty, deduped: [], echoed: [], included: [], slowIncluded: [] };
+            return { text: '', outcome: empty, deduped: [], echoed: [], included: [], slowIncluded: [], lessonIncluded: [] };
         }
+        // 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 +493,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);
@@ -424,6 +546,63 @@ export class TopicsService {
             }
             entries.push({ slug: hit.slug, doc, hit });
         }
+        // ---- Lesson gate (B2, spec 卷一 §6.3): established lessons only (MJ-3:
+        // hint never injects), trigger-channel match = 条件命中 (triggers carry
+        // the condition), top-1 by score. No hit → no lesson (教训不撒背景网).
+        // dedup/echo follow the same rules as topics. ----
+        let lessonMatch;
+        if (lessonGate !== undefined && lessonRoster.length > 0) {
+            const qTokens = new Set(tokenize(effectiveQuery));
+            let best;
+            for (const l of lessonRoster) {
+                if (exclude?.has(l.slug)) {
+                    if (!deduped.includes(l.slug))
+                        deduped.push(l.slug);
+                    continue;
+                }
+                if (echo?.has(l.slug)) {
+                    if (!echoed.includes(l.slug))
+                        echoed.push(l.slug);
+                    continue;
+                }
+                const v = scoreTopic(qTokens, l, {
+                    threshold: cfg.matchThreshold,
+                    topK: cfg.topK,
+                    tagBoost: cfg.tagBoost,
+                    graphDepth: 0,
+                    recencyWindowDays: cfg.recencyWindowDays,
+                    conflicts,
+                    structuralGate: true,
+                    usageBoost: cfg.usageBoost,
+                    usage: this.usageSignalsSync(),
+                    ...this.zeroOpenCfg(),
+                });
+                if (!v.reasons.some((r) => r.startsWith('triggers:')))
+                    continue;
+                if (best === undefined || v.score > best.v.score)
+                    best = { l, v };
+            }
+            if (best !== undefined) {
+                lessonMatch = {
+                    pointer: {
+                        slug: best.l.slug,
+                        title: best.l.title,
+                        status: best.l.status,
+                        description: best.l.description,
+                        score: best.v.score,
+                        source: best.l.source,
+                    },
+                    reasons: best.v.reasons,
+                    conclusion: best.l.conclusion,
+                };
+            }
+        }
+        // MJ-C combination matrix: lesson injection does not depend on the A3
+        // package gray-release. While the emitted shape is a flat list (digest
+        // mode, pointer mode without the package, AND the package-shadow legacy
+        // emit), lessons ride it as flat entries with the source marker; only a
+        // live package (packageMode on) gives them the direct-layer priority seat.
+        const lessonFlat = lessonGate === 'on' && lessonMatch !== undefined ? [lessonMatch.pointer] : undefined;
         // ---- Slow-lane merge (log-only shadow gate; consumption bookkeeping) ----
         const slowPointers = [];
         const slowDelivered = [];
@@ -431,7 +610,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,18 +661,103 @@ 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, lessonFlat);
+        }
+        else if (pkgMode === undefined) {
+            injection = assemblePointer(entries, { perTopicBudget: POINTER_PER_TOPIC, totalBudget: Math.min(cfg.totalBudget, POINTER_TOTAL) }, slowPointers, lessonFlat);
+        }
+        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, lessonFlat);
+            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);
+            }
+            // Lesson priority seat (B2, spec 卷一 §6.3): 主层 ≤2 席中命中 lesson
+            // 至少 1 席 — sorts first and is exempt from the direct-seat cap
+            // (budget-bound). Only on the LIVE package leg; the legacy emit above
+            // carries the flat lesson entry instead (MJ-C).
+            if (lessonFlat !== undefined && lessonMatch !== undefined) {
+                direct.unshift({
+                    slug: lessonMatch.pointer.slug,
+                    title: lessonMatch.pointer.title,
+                    status: lessonMatch.pointer.status,
+                    description: lessonMatch.pointer.description,
+                    conclusion: firstContentLine(lessonMatch.conclusion),
+                    score: lessonMatch.pointer.score,
+                    reasons: lessonMatch.reasons,
+                    prioritySeat: true,
+                    sourceTag: lessonSourceTag(lessonMatch.pointer.source),
+                });
+            }
+            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))
                 slowDelivered.push({ slug: pointer.slug, why: pointer.why });
         }
+        // ---- Lesson gate accounting (B2): what entered the context, the shadow
+        // bypass ledger (meta/lesson-shadow.jsonl — lesson seat vs no-lesson
+        // emitted disposition, same discipline as the package shadow), and the
+        // record fields (absent when the gate is off or nothing matched). ----
+        const lessonIncluded = lessonGate === 'on' && lessonMatch !== undefined
+            ? injection.lessonIncluded ?? (injection.included.includes(lessonMatch.pointer.slug) ? [lessonMatch.pointer.slug] : [])
+            : [];
         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 +772,59 @@ 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.appendShadowLedger(this.packageShadowLedgerPath(), {
+                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 (lessonGate === 'shadow' && lessonMatch !== undefined) {
+            const rendered = lessonEntryText(lessonMatch.pointer, POINTER_PER_TOPIC);
+            const budgetTotal = pointerMode ? Math.min(cfg.totalBudget, POINTER_TOTAL) : cfg.totalBudget;
+            this.appendShadowLedger(this.lessonShadowLedgerPath(), {
+                at: record.at,
+                ...(sessionId !== undefined ? { sessionId } : {}),
+                queryTokenCount: record.queryTokenCount,
+                lessonInject: 'shadow',
+                lessons: [
+                    {
+                        slug: lessonMatch.pointer.slug,
+                        score: lessonMatch.pointer.score,
+                        source: lessonMatch.pointer.source,
+                        entryTokens: rendered.usedTokens,
+                        wouldFit: injection.usedTokens + rendered.usedTokens <= budgetTotal,
+                    },
+                ],
+                emitted: { tokens: injection.usedTokens, included: injection.included },
+            });
+        }
+        if (lessonGate !== undefined && lessonMatch !== undefined) {
+            record.lessonInject = lessonGate;
+            record.lessons = [
+                {
+                    slug: lessonMatch.pointer.slug,
+                    score: lessonMatch.pointer.score,
+                    source: lessonMatch.pointer.source,
+                    included: lessonIncluded.length > 0,
+                },
+            ];
+        }
         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
@@ -547,7 +860,7 @@ export class TopicsService {
         if (injection.dropped.length > 0)
             record.dropped = [...(record.dropped ?? []), ...injection.dropped];
         void this.store.appendInjectionRecord(record).catch(() => undefined);
-        return { text: injection.text, outcome, deduped, echoed, included: injection.included, slowIncluded };
+        return { text: injection.text, outcome, deduped, echoed, included: injection.included, slowIncluded, lessonIncluded };
     }
     /**
      * topic_open tool path (v4 §4.1): full conclusion / open questions /
@@ -647,6 +960,10 @@ export class TopicsService {
             // Same retirement rule as roster(): deprecated knowledge never injects.
             if (doc.fm.status === 'deprecated')
                 continue;
+            // Same lesson separation as roster() (B2): lessons inject only through
+            // the lessonInject gate, never the topic lane.
+            if (okf.topicKindOf(doc.fm.type) === 'lesson')
+                continue;
             out.push({
                 slug: entry.slug,
                 title: doc.fm.title,
@@ -662,6 +979,76 @@ export class TopicsService {
         }
         return out;
     }
+    /** Established, scope-passing lesson entries (B2, spec 卷一 §6.3) — sync,
+     *  sharing the roster's mtime cache. Injection reads ONLY established
+     *  lessons here (MJ-3: hint 仅供审批队列展示，永不注入); scope filter =
+     *  workspace lessons must carry the current workspace id (MJ-2); scope=global
+     *  and legacy entries without a workspaceId pass (fail-open — the filter's
+     *  default is permissive, the confidence gate is the hard one). */
+    lessonsSync() {
+        const ws = currentWorkspaceId();
+        let files;
+        try {
+            files = readdirSync(this.store.topicsDir());
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const file of files) {
+            if (!file.endsWith('.md') || file === 'index.md')
+                continue;
+            const path = join(this.store.topicsDir(), file);
+            let st;
+            try {
+                st = statSync(path);
+            }
+            catch {
+                continue;
+            }
+            const cached = this.cache.get(file);
+            let entry = cached;
+            if (cached === undefined || cached.mtimeMs !== st.mtimeMs || cached.size !== st.size) {
+                try {
+                    const doc = okf.parseTopicDoc(readFileSync(path, 'utf8'));
+                    entry = { mtimeMs: st.mtimeMs, size: st.size, doc, slug: file.slice(0, -3) };
+                    this.cache.set(file, entry);
+                }
+                catch {
+                    this.cache.delete(file);
+                    continue;
+                }
+            }
+            if (entry === undefined)
+                continue;
+            const fm = entry.doc.fm;
+            if (okf.topicKindOf(fm.type) !== 'lesson')
+                continue;
+            // Confidence 事实源：established ⇄ stable；deprecated 已被上面的通用
+            // 退休规则挡住，这里再兜一层（hint↔draft 永不注入）。
+            if (fm.confidence !== 'established' || fm.status === 'deprecated')
+                continue;
+            if (fm.scope === 'workspace' && fm.workspaceId !== undefined && fm.workspaceId !== ws)
+                continue;
+            out.push({
+                slug: entry.slug,
+                title: fm.title,
+                description: fm.description,
+                status: fm.status,
+                tags: fm.tags,
+                triggers: fm.triggers,
+                depends: fm.depends,
+                links: okf.bodyLinkSlugs(entry.doc.body),
+                generatedAt: fm.generated.at,
+                conclusion: okf.sectionOf(entry.doc.body, okf.CONCLUSION_HEADING) ?? '',
+                confidence: fm.confidence,
+                source: fm.source ?? 'manual',
+                scope: fm.scope ?? 'workspace',
+                ...(fm.workspaceId !== undefined ? { workspaceId: fm.workspaceId } : {}),
+            });
+        }
+        return out;
+    }
     readDocSync(slug) {
         try {
             return okf.parseTopicDoc(readFileSync(join(this.store.topicsDir(), `${slug}.md`), 'utf8'));
@@ -678,7 +1065,11 @@ export class TopicsService {
             return undefined;
         }
     }
-    /** topic_save tool path: create or update with actor stamping. */
+    /** topic_save tool path: create or update with actor stamping. `kind:
+     *  'lesson'` (B2 data plane) switches the OKF type to Lesson and stamps the
+     *  lesson frontmatter (scope/confidence/source/workspaceId) with the
+     *  confidence↔status derivation (hint↔draft, established↔stable —
+     *  confidence is the fact source). */
     async saveTopic(input) {
         const now = new Date().toISOString();
         const existing = input.slug !== undefined ? await this.store.readTopic(input.slug) : undefined;
@@ -694,9 +1085,10 @@ export class TopicsService {
         }
         const baseSlug = input.slug ?? okf.slugify(input.title);
         const slug = existing === undefined ? await this.store.uniqueSlug(baseSlug) : okf.slugify(input.slug ?? baseSlug);
+        const isLesson = input.kind === 'lesson' || (existing !== undefined && okf.topicKindOf(existing.fm.type) === 'lesson');
         // store.saveTopic stamps generated {by, at} itself (write-through actor).
         const fm = {
-            type: 'Topic',
+            type: isLesson ? okf.kindTypeValue('lesson') : okf.kindTypeValue('topic'),
             title: input.title,
             tags: dedupeLower(input.tags ?? existing?.fm.tags ?? []),
             // normalizeDependsEntry, never bare slugToPath: the preserved-on-update
@@ -716,9 +1108,34 @@ export class TopicsService {
         const triggers = sanitizeTriggers(input.triggers ?? existing?.fm.triggers ?? []);
         if (triggers.length > 0)
             fm.triggers = triggers;
+        if (isLesson) {
+            // B2 frontmatter (spec 卷一 §6.2): preserve-on-update like tags; the
+            // workspace id is stamped AT WRITE TIME (MJ-2, cwd hash) and survives
+            // updates; confidence is the FACT source → status derives from it,
+            // except a deprecated lesson stays deprecated unless confidence is
+            // explicitly re-driven (no silent revival through topic_save).
+            fm.scope = input.scope ?? existing?.fm.scope ?? 'workspace';
+            fm.confidence = input.confidence ?? existing?.fm.confidence ?? 'hint';
+            fm.source = input.lessonSource ?? existing?.fm.source ?? 'manual';
+            if (fm.scope === 'workspace') {
+                const wsid = existing?.fm.workspaceId ?? currentWorkspaceId();
+                if (wsid !== undefined)
+                    fm.workspaceId = wsid;
+            }
+            else {
+                delete fm.workspaceId;
+            }
+            fm.status =
+                existing?.fm.status === 'deprecated' && input.confidence === undefined
+                    ? 'deprecated'
+                    : okf.deriveLessonStatus(fm.confidence);
+        }
         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(${isLesson ? 'lesson' : 'topic'}): create ${slug}` : `topics(${isLesson ? 'lesson' : 'topic'}): update ${slug}`,
+            created: existing === undefined,
+        });
         this.invalidate();
         void this.sync?.schedulePush();
         return { ...result, slug: result.slug };
@@ -726,6 +1143,127 @@ export class TopicsService {
     async observe(input) {
         return this.store.appendObservation({ kind: input.kind, source: input.source ?? 'model', text: input.text, sessionId: input.sessionId });
     }
+    // -------------------------------------------------------------------------
+    // Dual-write seams (卷二 §6.2 MJ-5) — the new repo's only write surface.
+    // Both run behind the store lock / index recompute; both audit the caller
+    // identity (opts.actor REQUIRED — a blank actor refuses the whole call and
+    // lands a `seam-*` audit row) into meta/pipeline-events.jsonl.
+    // -------------------------------------------------------------------------
+    /**
+     * ① 观察投喂: structured observations (B1 §2.1 whitelist, FEATURES ONLY —
+     * 对话原文禁入, 红线⑤) appended to the observations stream with the `fed`
+     * provenance marker and `kind: 'signal'`; each line carries `by: actor`.
+     * The whitelist copy drops unknown caller fields, caps detail entries and
+     * string sizes, and renders a sorted feature line as the observation text.
+     * Duplicates (same type+session+detail in the recent tail) are counted, not
+     * appended (重复观察由原仓去重). Fail-soft: one malformed entry is counted
+     * as rejected, never sinks the batch.
+     */
+    async feedObservations(obs, opts) {
+        const actor = typeof opts?.actor === 'string' ? opts.actor.trim() : '';
+        const total = Array.isArray(obs) ? obs.length : 0;
+        if (actor === '') {
+            await recordPipelineEvent(this.store.root, {
+                at: new Date().toISOString(),
+                kind: 'seam-observations-fed',
+                detail: { actor: '<missing>', accepted: 0, duplicates: 0, rejected: total, refused: true },
+            });
+            return { accepted: 0, duplicates: 0, rejected: total, ids: [], error: 'unauthorized' };
+        }
+        const accepted = [];
+        let duplicates = 0;
+        let rejected = 0;
+        // Dedup window: the recent observation tail — the signal layer may retry
+        // on its own fail-open local queue (spec 卷二 §2.1) and identical feature
+        // tuples must not double-distill.
+        const recent = await this.store.allObservations(500);
+        const seenKeys = new Set(recent.map((o) => observationKey(o.kind, o.source, o.sessionId, o.text)));
+        for (const raw of obs) {
+            const clean = sanitizeStructuredObservation(raw);
+            if (clean === undefined) {
+                rejected += 1;
+                continue;
+            }
+            const text = renderFeatureLine(clean);
+            const key = observationKey('signal', 'fed', clean.sessionId, text);
+            if (seenKeys.has(key)) {
+                duplicates += 1;
+                continue;
+            }
+            seenKeys.add(key);
+            const saved = await this.store.appendObservation({
+                kind: 'signal',
+                source: 'fed',
+                text,
+                sessionId: clean.sessionId,
+                by: actor,
+            });
+            accepted.push(saved.id);
+        }
+        await recordPipelineEvent(this.store.root, {
+            at: new Date().toISOString(),
+            kind: 'seam-observations-fed',
+            detail: { actor, accepted: accepted.length, duplicates, rejected },
+        });
+        return { accepted: accepted.length, duplicates, rejected, ids: accepted };
+    }
+    /**
+     * ② lesson 状态变更 (B2/卷二 §6.2): hint→established / →deprecated /
+     * →removed. established flips confidence (the FACT source) and derives
+     * status (established↔stable); deprecated flips status only (the TTL sweep
+     * owns the rest); removed = archive FIRST (byte-exact copy to
+     * `archive/lessons/` inside the bundle, git-revertable — 红线④) then out of
+     * the roster, one commit. Each call lands a `seam-lesson-status` audit row.
+     */
+    async setLessonStatus(slug, to, opts) {
+        const actor = typeof opts?.actor === 'string' ? opts.actor.trim() : '';
+        const clean = okf.slugify(slug ?? '');
+        const audit = async (ok, reason, extra) => {
+            await recordPipelineEvent(this.store.root, {
+                at: new Date().toISOString(),
+                kind: 'seam-lesson-status',
+                detail: { actor: actor === '' ? '<missing>' : actor, slug: clean, to, ok, ...(reason !== undefined ? { reason } : {}), ...(extra ?? {}) },
+            });
+        };
+        if (actor === '') {
+            await audit(false, 'unauthorized');
+            return { ok: false, slug: clean, reason: 'unauthorized' };
+        }
+        if (to !== 'established' && to !== 'deprecated' && to !== 'removed') {
+            await audit(false, 'invalid-state');
+            return { ok: false, slug: clean, reason: 'invalid-state' };
+        }
+        const doc = await this.store.readTopic(clean).catch(() => undefined);
+        if (doc === undefined) {
+            await audit(false, 'not-found');
+            return { ok: false, slug: clean, reason: 'not-found' };
+        }
+        if (okf.topicKindOf(doc.fm.type) !== 'lesson') {
+            await audit(false, 'not-a-lesson');
+            return { ok: false, slug: clean, reason: 'not-a-lesson' };
+        }
+        const from = doc.fm.confidence ?? 'hint';
+        if (to === 'removed') {
+            const r = await this.store.archiveLesson(clean, {
+                message: `topics(lesson): remove ${clean} (archive-first, by ${actor})`,
+            });
+            if (r === undefined) {
+                await audit(false, 'not-found');
+                return { ok: false, slug: clean, reason: 'not-found' };
+            }
+            await audit(true, undefined, { archivedTo: r.archivedTo, committed: r.committed });
+            this.invalidate();
+            return { ok: true, slug: clean, from, archivedTo: r.archivedTo, committed: r.committed };
+        }
+        if (to === 'established')
+            doc.fm.confidence = 'established';
+        doc.fm.status = to === 'established' ? okf.deriveLessonStatus('established') : 'deprecated';
+        const result = await this.store.saveTopic({ slug: clean, doc }, { message: `topics(lesson): ${to} ${clean} (by ${actor})`, actor });
+        this.invalidate();
+        void this.sync?.schedulePush();
+        await audit(true, undefined, { committed: result.committed });
+        return { ok: true, slug: clean, from, committed: result.committed };
+    }
     async search(query, topK) {
         const cfg = this.cfg;
         return searchTopics(query, await this.roster(), {
@@ -771,6 +1309,66 @@ export class TopicsService {
 function inclusionDropped(injection) {
     return injection.dropped.length > 0;
 }
+// --- feedObservations whitelist machinery (B-line seam ①) -------------------
+// jev/log REDACTION + pipeline-events discipline: whitelist copy on write,
+// bounded scalar features only — 对话原文（tool arguments、message content）
+// 结构上进不来（红线⑤）。
+const SEAM_TYPE_MAX_CHARS = 64;
+const SEAM_SESSION_MAX_CHARS = 128;
+const SEAM_DETAIL_MAX_ENTRIES = 16;
+const SEAM_DETAIL_KEY_MAX_CHARS = 64;
+const SEAM_DETAIL_VALUE_MAX_CHARS = 256;
+/** Whitelist copy of one structured observation; undefined = reject. A raw
+ *  entry whose detail existed but sanitizes to EMPTY (object/array smuggle,
+ *  garbage values) is rejected outright — a type with no survivable features
+ *  is a malformed signal, not a featureless one. */
+function sanitizeStructuredObservation(raw) {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    if (typeof raw.type !== 'string' || raw.type.trim() === '')
+        return undefined;
+    const out = { type: raw.type.trim().slice(0, SEAM_TYPE_MAX_CHARS) };
+    if (typeof raw.at === 'string' && raw.at !== '')
+        out.at = raw.at;
+    if (typeof raw.sessionId === 'string' && raw.sessionId !== '')
+        out.sessionId = raw.sessionId.slice(0, SEAM_SESSION_MAX_CHARS);
+    const hadDetail = raw.detail !== undefined && typeof raw.detail === 'object' && !Array.isArray(raw.detail);
+    if (hadDetail) {
+        const detail = {};
+        for (const [k, v] of Object.entries(raw.detail)) {
+            if (Object.keys(detail).length >= SEAM_DETAIL_MAX_ENTRIES)
+                break;
+            if (typeof v === 'string') {
+                if (v !== '')
+                    detail[k.slice(0, SEAM_DETAIL_KEY_MAX_CHARS)] = v.slice(0, SEAM_DETAIL_VALUE_MAX_CHARS);
+            }
+            else if (typeof v === 'number') {
+                if (Number.isFinite(v))
+                    detail[k.slice(0, SEAM_DETAIL_KEY_MAX_CHARS)] = v;
+            }
+            else if (typeof v === 'boolean') {
+                detail[k.slice(0, SEAM_DETAIL_KEY_MAX_CHARS)] = v;
+            }
+        }
+        if (Object.keys(detail).length === 0)
+            return undefined;
+        out.detail = detail;
+    }
+    return out;
+}
+/** Sorted feature line as the observation text: `[type] k=v k=v` — stable
+ *  (dedup-keyable), feature-only, bounded. */
+function renderFeatureLine(o) {
+    const parts = Object.keys(o.detail ?? {})
+        .sort()
+        .map((k) => `${k}=${String(o.detail[k])}`);
+    return `[${o.type}]${parts.length > 0 ? ` ${parts.join(' ')}` : ''}`.slice(0, 512);
+}
+/** Dedup key over the stored observation identity (kind/source/session/feature
+ *  line) — candidates key the same way they are stored. */
+function observationKey(kind, source, sessionId, text) {
+    return `${kind}|${source}|${sessionId ?? ''}|${text}`;
+}
 function firstLine(text) {
     return firstParagraphOf(text);
 }
@@ -805,6 +1403,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) {