@aiwayds/dsh-topics-memory 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwayds/dsh-topics-memory",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "dsh-plugin: quality-first topic memory for dsh — a topic keeps the starting question, conclusion, impact and dependencies, not the process; local-first git-traced OKF bundle, budgeted LLM-free injection",
   "type": "module",
   "main": "lib/index.js",
@@ -42,7 +42,7 @@
     "build": "tsc -p tsconfig.json",
     "check": "tsc --noEmit -p tsconfig.json",
     "pretest": "tsc -p tsconfig.json",
-    "test": "node --test test/yaml.test.mjs test/okf.test.mjs test/retrieval.test.mjs test/digest.test.mjs test/ilog.test.mjs test/store.test.mjs test/paths.test.mjs test/git.test.mjs test/sync.test.mjs test/tools.test.mjs test/dedup.test.mjs test/commands.test.mjs test/onboard.test.mjs test/delegation.test.mjs test/observer.test.mjs test/distill.test.mjs test/consolidate.test.mjs test/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/quality.test.mjs test/replay-gate.test.mjs test/depends-repair.test.mjs test/skill.test.mjs test/fast-lane.test.mjs test/legacy-import.test.mjs test/jev-config.test.mjs test/jev-gate.test.mjs test/jev-client.test.mjs test/jev-log.test.mjs test/jev-dual.test.mjs test/jev-fastgate.test.mjs",
+    "test": "node --test test/yaml.test.mjs test/okf.test.mjs test/retrieval.test.mjs test/digest.test.mjs test/digest-package.test.mjs test/ilog.test.mjs test/store.test.mjs test/paths.test.mjs test/git.test.mjs test/sync.test.mjs test/tools.test.mjs test/dedup.test.mjs test/commands.test.mjs test/onboard.test.mjs test/delegation.test.mjs test/observer.test.mjs test/distill.test.mjs test/consolidate.test.mjs test/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/quality.test.mjs test/replay-gate.test.mjs test/depends-repair.test.mjs test/skill.test.mjs test/fast-lane.test.mjs test/legacy-import.test.mjs test/jev-config.test.mjs test/jev-gate.test.mjs test/jev-client.test.mjs test/jev-log.test.mjs test/jev-dual.test.mjs test/jev-fastgate.test.mjs test/zero-open-decay.test.mjs test/embedding.test.mjs test/embedding-index.test.mjs test/query-sanitize.test.mjs test/semantic-rerank.test.mjs test/inject-config.test.mjs test/distill-links.test.mjs test/store-links.test.mjs",
     "smoke": "node scripts/smoke-boot.mjs"
   },
   "dependencies": {},

package/src/commands.ts

@@ -17,7 +17,7 @@ import { serializeTopicDoc, slugify, firstParagraph } from './okf.ts'
 import { buildGraph, renderGraphHtml } from './viz.ts'
 import { CONFIG_KEYS, displayKey, type ConfigKey, type TopicsConfigValue, parseConfigValue } from './config.ts'
 import { reloadSecrets } from './jev/gate.ts'
-import { aggregateStats } from './ilog.ts'
+import { aggregateStats, aggregateOpenPanel, ZERO_OPEN_MIN_INJECTIONS } from './ilog.ts'
 import {
   askDistillSingle,
   createOnboardHandler,
@@ -52,7 +52,7 @@ export const HELP = [
   '  /topics status              bundle 健康：topic 数、观察积压、冲突、同步状态',
   '  /topics distill             手动触发一次蒸馏（观察池 → Topic，输出 marked/created/updated/gc 摘要）',
   '  /topics consolidate         手动触发一次整理（合并重复/晋升 stable/废弃过时/刷新元数据，无视 cadence 立即跑）',
-  '  /topics stats               注入统计：hit rate、top-N、near-miss 分布与调参建议',
+  '  /topics stats               注入统计：hit rate、open rate、注入 vs 打开、near-miss 分布与调参建议',
   '  /topics list                列出全部 Topic',
   '  /topics show <slug>         查看一个 Topic 全文（含反向引用）',
   '  /topics history <slug>      一个 Topic 的结论变更史（git log）',
@@ -285,7 +285,7 @@ async function doDistill(service: TopicsService, invocation: CommandInvocation,
 
 async function renderStats(service: TopicsService): Promise<string> {
   const records = await service.store.readInjectionRecords()
-  const stats = aggregateStats(records as never)
+  const stats = aggregateStats(records)
   if (records.length === 0) return '还没有注入记录 —— 用起来之后这里会有 hit rate / top-N / near-miss 分布。'
   const lines = [
     `注入统计（最近 ${records.length} 轮）：`,
@@ -310,20 +310,14 @@ async function renderStats(service: TopicsService): Promise<string> {
     }
     lines.push(`| 慢道参与轮 | ${slowRounds}（快 ${records.length - slowRounds} / 慢或混合 ${slowRounds}${medianLag}） |`)
   }
-  // Pointer open rate (v4 §4.3): topic_open calls vs pointer entries injected.
-  // Echoed hits ride the retrieval but never became pointers — excluded here.
+  // Injection-vs-open metrics (v5): the denominator counts only pointers
+  // that truly rendered (deduped/echoed/dropped all excluded, slow pointers
+  // included) and the numerator only counts DISTINCT slugs from that
+  // rendered set opened inside the injection window — search opens and
+  // never-rendered slugs cannot inflate the rate.
   const opens = await service.store.readOpenRecords()
-  if (opens.length > 0 || records.some((r) => r.lane !== undefined)) {
-    const entries = records.reduce(
-      (acc, r) =>
-        acc +
-        r.hits.filter((h) => !(r.deduped ?? []).includes(h.slug) && !(r.echoed ?? []).includes(h.slug)).length +
-        (r.slow?.length ?? 0),
-      0,
-    )
-    const rate = entries === 0 ? 0 : Math.min(1, opens.length / entries)
-    lines.push(`| 指针打开率 | ${(rate * 100).toFixed(1)}%（${opens.length} 次 topic_open / ${entries} 条注入指针） |`)
-  }
+  const panel = aggregateOpenPanel(records, opens)
+  lines.push(`| open rate | ${(panel.openRate * 100).toFixed(1)}%（${panel.opensInWindow} 个被打开指针 / ${panel.pointerEntries} 条注入指针） |`)
   const echoedCount = records.reduce((acc, r) => acc + (r.echoed?.length ?? 0), 0)
   if (echoedCount > 0) {
     lines.push(`| 回声抑制 | ${echoedCount} 次（本会话蒸馏出的 topic 不回注） |`)
@@ -332,6 +326,31 @@ async function renderStats(service: TopicsService): Promise<string> {
     lines.push('', 'Top-N 被注入 Topic：', '', '| Slug | 注入次数 |', '| --- | --- |')
     for (const t of stats.topTopics.slice(0, 5)) lines.push(`| \`${cell(t.slug)}\` | ${t.count} |`)
   }
+  // ---- 注入 vs 打开 panel ----
+  // Per-topic cut: what the header's windowed rate cannot show — which
+  // topics the model actually bothers to open (wide-scope slug attribution).
+  if (panel.topics.length > 0) {
+    lines.push(
+      '',
+      '注入 vs 打开（Top-10，注入=真正渲染的指针；打开按 slug 归因，全窗口）：',
+      '',
+      '| Topic | 注入 | 打开 | 打开率 |',
+      '| --- | --- | --- | --- |',
+      ...panel.topics.map((t) => `| \`${cell(t.slug)}\` | ${t.injections} | ${t.opens} | ${(t.openRate * 100).toFixed(1)}% |`),
+    )
+  }
+  if (panel.zeroOpenTotal > 0) {
+    const shown = panel.zeroOpen.map((z) => `\`${cell(z.slug)}\``).join('、')
+    const more = panel.zeroOpenTotal > panel.zeroOpen.length ? `（共 ${panel.zeroOpenTotal} 个）` : ''
+    lines.push('', `零打开高频（注入 ≥${ZERO_OPEN_MIN_INJECTIONS}、打开 0）：${shown}${more}`)
+  }
+  lines.push('', panel.hasSourceData ? `打开来源：pointer ${panel.pointerOpens} / search ${panel.searchOpens}` : '打开来源：暂无来源数据（需新版本 open 记录）')
+  if (panel.pointerEntries > 0) {
+    lines.push('', '| 分桶 | 指针 | 打开率 |', '| --- | --- | --- |')
+    for (const b of panel.bands) {
+      lines.push(`| ${b.label} | ${b.pointers} | ${b.pointers === 0 ? '—' : `${(b.openRate * 100).toFixed(1)}%`} |`)
+    }
+  }
   if (stats.nearMissHistogram.length > 0) {
     lines.push(
       '',

package/src/config.ts

@@ -72,6 +72,12 @@ export const TopicsConfig = z.object({
    *  granted to zero-lexical candidates; the structural gate still applies.
    *  0 = off. */
   usageBoost: z.number().default(0.15).volatile(),
+  /** Zero-open decay (v5, default off): halve the retrieval score of slugs
+   *  injected ≥5 times in the rolling 30 days with zero opens ever — the
+   *  零打开高频 leaderboard stops out-ranking topics the model actually
+   *  reads. false = zero behavior change; the reason tag `zero-open-decay`
+   *  rides the hit/near-miss reasons when on. */
+  zeroOpenDecay: z.boolean().default(false).volatile(),
   /** Debounced push delay in GitHub mode. */
   pushDebounceSeconds: z.number().default(45).volatile(),
   /** System One decision-model integration (design 2026-09-25), default-off
@@ -99,6 +105,21 @@ export const TopicsConfig = z.object({
   /** laya-serve systemone endpoint for the pace-maker (default: the local
    *  laya-serve bind from the laya repo's serve mode). */
   jevLayaUrl: z.string().default('http://127.0.0.1:8000/v1/systemone').volatile(),
+  /** Local embedding provider (A4 semantic reranker, spec §3.1): ''
+   *  sentinel = the whole semantic layer is OFF (pure lexical); 'ollama' =
+   *  the local ollama embed API (localhost is the ADR 0017 local exception).
+   *  v1 ships no remote provider — a remote embedding may only ever enter a
+   *  slow-lane/offline path, never the fast lane (red line ①). */
+  embeddingProvider: z.string().default('').volatile(),
+  /** Embedding model; '' = provider default (ollama → nomic-embed-text),
+   *  same sentinel pattern as distillModel. */
+  embeddingModel: z.string().default('').volatile(),
+  /** Injection-package master gate (A-line, spec §2/§3): off | shadow | on.
+   *  Carries the WHOLE new-behavior surface — query sanitization, the
+   *  three-layer package, nearFloor semantic rerank, degradation. off = zero
+   *  behavior change anywhere (byte-for-byte legacy); shadow = compute +
+   *  bypass-ledger only, nothing lands in context; on = engage. */
+  packageMode: z.string().default('off').volatile(),
 })
 
 export type TopicsConfigValue = {
@@ -127,6 +148,10 @@ export type TopicsConfigValue = {
   consolidateCadence: string
   deprecatedTtlDays: number
   usageBoost: number
+  /** Zero-open decay (v5). Optional in this TS view only (same sentinel
+   *  pattern as the jev keys): bare-harness DEFAULTS predates it —
+   *  consumers must treat undefined as the documented default (false). */
+  zeroOpenDecay?: boolean
   pushDebounceSeconds: number
   /** System One integration keys (design 2026-09-25 §4). Optional in this TS
    *  view only: index.ts's bare-harness DEFAULTS literal predates them and
@@ -139,6 +164,13 @@ export type TopicsConfigValue = {
   jevSecretFile?: string
   jevLayaFallback?: boolean
   jevLayaUrl?: string
+  /** Injection-quality line keys (spec §7). Optional in this TS view only
+   *  (same sentinel pattern as the jev keys): index.ts's bare-harness
+   *  DEFAULTS literal predates them — consumers must treat undefined as the
+   *  documented default ('' / '' / 'off' = every new behavior zeroed). */
+  embeddingProvider?: string
+  embeddingModel?: string
+  packageMode?: 'off' | 'shadow' | 'on'
 }
 
 export const CONFIG_KEYS = [
@@ -167,6 +199,7 @@ export const CONFIG_KEYS = [
   'consolidateCadence',
   'deprecatedTtlDays',
   'usageBoost',
+  'zeroOpenDecay',
   'pushDebounceSeconds',
   'jevEnabled',
   'jevBackend',
@@ -175,6 +208,9 @@ export const CONFIG_KEYS = [
   'jevSecretFile',
   'jevLayaFallback',
   'jevLayaUrl',
+  'embeddingProvider',
+  'embeddingModel',
+  'packageMode',
 ] as const
 
 export type ConfigKey = (typeof CONFIG_KEYS)[number]
@@ -199,7 +235,8 @@ export function parseConfigValue(key: ConfigKey, raw: string): boolean | number
     case 'autoObserve':
     case 'distillOnSessionEnd':
     case 'includeSubagents':
-    case 'jevEnabled': {
+    case 'jevEnabled':
+    case 'zeroOpenDecay': {
       if (raw === 'on' || raw === 'true') return true
       if (raw === 'off' || raw === 'false') return false
       return { error: `${key} 取值 on|off` }
@@ -245,10 +282,19 @@ export function parseConfigValue(key: ConfigKey, raw: string): boolean | number
     }
     case 'distillProvider':
     case 'distillModel':
+    case 'embeddingModel':
     case 'jevModel':
     case 'jevSecretFile':
     case 'jevLayaUrl':
       return raw
+    case 'embeddingProvider': {
+      if (raw === '' || raw === 'ollama') return raw
+      return { error: 'embedding-provider 仅支持 ollama（留空=语义层关；远程 provider 不进快道）' }
+    }
+    case 'packageMode': {
+      if (raw === 'off' || raw === 'shadow' || raw === 'on') return raw
+      return { error: 'package-mode 取值 off|shadow|on' }
+    }
     case 'jevLayaFallback': {
       if (raw === 'on' || raw === 'true') return true
       if (raw === 'off' || raw === 'false') return false

package/src/digest.ts

@@ -12,6 +12,7 @@
 import type { TopicDoc } from './okf.ts'
 import { sectionOf, firstParagraph, CONCLUSION_HEADING, RECOMMENDATIONS_HEADING } from './okf.ts'
 import type { SearchHit } from './retrieval.ts'
+import { tokenize } from './retrieval.ts'
 
 /** Rough CJK-aware token estimate: ~0.75 token per CJK char, ~4 chars per latin token. */
 export function estimateTokens(text: string): number {
@@ -230,3 +231,418 @@ export function assembleInjection(
 ): AssembleResult {
   return packInjection(entries, cfg, topicDigest, slow)
 }
+
+// ---------------------------------------------------------------------------
+// A3 相关性三层信息包 (spec 2026-10-self-improve-topics §2) — the gated new
+// shape. Coexists with assemblePointer: the service-layer mode gate decides
+// which renderer runs; both stay pure here. 分层预算取代单条 80（§2.6）：
+// 直接相关 ~120×≤2、邻域 ~40×≤3、弱信号合并一行；总预算钉 600 不浮动
+// （A3 决议 3）。降档=琐碎 query 且与全部候选零词面实体 → null（整包跳过）。
+// ---------------------------------------------------------------------------
+
+/** One retrieval-side candidate, roster metadata pre-extracted by the caller. */
+export interface PackageCandidate {
+  slug: string
+  title: string
+  status: string
+  description?: string
+  /** Conclusion section first line (fallback for a missing description). */
+  conclusion?: string
+  score: number
+  /** Retrieval reason tags (`triggers:0.83` / `title:0.50` / `tags:…` / …). */
+  reasons: string[]
+  /** Edge/lane provenance: `depends:dN` | `slow-pick` | `semantic…` | raw. */
+  via?: string
+}
+
+export interface PackageInput {
+  query: string
+  /** Query lexemes the caller retrieved with (tokenize + §3.3 cleaning). */
+  queryTokens: string[]
+  /** Lexical strong hits (gate-passed); lands in the direct layer. */
+  direct: PackageCandidate[]
+  /** Graph expansion + slow-lane picks; lands in the neighborhood layer. */
+  neighborhood: PackageCandidate[]
+  /** nearFloor band (0.20–0.30) head; lands in the merged weak-signal line. */
+  weak: PackageCandidate[]
+  /** ADR 0015 usage signal — within-layer ordering tiebreak only (v1). */
+  usageBySlug?: Map<string, number>
+}
+
+export interface PackageOpts {
+  /**
+   * `'on'` renders the live package; `'shadow'` means the caller double-runs
+   * (old assemblePointer + this) for the bypass ledger (spec §8.3). The pure
+   * output is identical in both modes — the mode is call-site bookkeeping.
+   */
+  mode?: 'on' | 'shadow'
+}
+
+export interface PackageResult {
+  text: string
+  usedTokens: number
+  included: string[]
+  dropped: { slug: string; reason: string }[]
+  /** Final per-layer rosters (what the 包头 counts report). */
+  layers: { direct: string[]; neighborhood: string[]; weak: string[] }
+}
+
+/** Total package cap — pinned, does not float with hit strength (A3 决议 3). */
+export const PACKAGE_TOTAL = 600
+export const PACKAGE_DIRECT_MAX = 2
+export const PACKAGE_DIRECT_BUDGET = 120
+export const PACKAGE_NEIGHBOR_MAX = 3
+export const PACKAGE_NEIGHBOR_BUDGET = 40
+export const PACKAGE_WEAK_MAX = 2
+/**
+ * Padded-trivial arm of the downgrade guard (spec §2.3 名词实体口径, an
+ * implementation-time item per §11): after stripping whitespace, a query this
+ * short counts as 琐碎 even when the tokenizer expands CJK bigrams past 3
+ * tokens. Calibrated on the two named scenarios: 场景① ack query strips to
+ * 15 chars (downgrade), a real review query strips to 18 (kept).
+ */
+export const PACKAGE_TRIVIAL_QUERY_CHARS = 16
+
+const PACKAGE_WRAPPER_OPEN = '<topic-memory>'
+const PACKAGE_WRAPPER_CLOSE = '</topic-memory>'
+
+/** Edge/lane note for the why line / neighborhood annotation (A3 决议 2). */
+function viaNote(via: string | undefined): string | null {
+  if (via === undefined || via === '') return null
+  if (via.startsWith('depends')) return '经 depends 关联'
+  if (via.startsWith('slow')) return '慢道 pick'
+  if (via.startsWith('semantic')) return '语义近邻'
+  return via
+}
+
+/** Trigger reason → the trigger word when the caller carries it, `''` channel-only. */
+function triggerWordOfReason(reason: string): string | undefined {
+  const m = reason.match(/^triggers?[:：](.*)$/)
+  if (m === null) return undefined
+  const v = m[1].trim()
+  return /^[\d.+-]+$/.test(v) ? '' : v
+}
+
+/**
+ * slug/title 词面，含分隔符子词（`cs-geely-voice-agent` → `voice`/`agent`）：
+ * query 里的连字符词（voice-agent）与 slug 复合词永远不相等，实体判定必须
+ * 下探到子词才有交集；CJK 已由 tokenize 的二元切分覆盖。
+ */
+function subtokenSurface(text: string): Set<string> {
+  const out = new Set<string>()
+  for (const t of tokenize(text)) {
+    out.add(t)
+    if (/[+#.-]/.test(t)) {
+      for (const sub of t.split(/[+#.-]+/)) if (sub.length >= 2) out.add(sub)
+    }
+  }
+  return out
+}
+
+function tokenMatchesSurface(token: string, surface: ReadonlySet<string>): boolean {
+  const t = token.toLowerCase()
+  if (surface.has(t)) return true
+  if (/[+#.-]/.test(t)) {
+    for (const sub of t.split(/[+#.-]+/)) if (sub.length >= 2 && surface.has(sub)) return true
+  }
+  return false
+}
+
+/**
+ * Strict display matcher for why-line attribution: a compound query token
+ * counts as a title/weak word only when EVERY separator part ties to the
+ * surface — `voice-agent` matches `cs-geely-voice-agent`, but
+ * `cs-geely-alert-manager-api` must not match it via the shared `cs`.
+ */
+function tokenMatchesSurfaceStrict(token: string, surface: ReadonlySet<string>): boolean {
+  const t = token.toLowerCase()
+  if (surface.has(t)) return true
+  if (!/[+#.-]/.test(t)) return false
+  const subs = t.split(/[+#.-]+/).filter((s) => s.length >= 2)
+  return subs.length > 0 && subs.every((s) => surface.has(s))
+}
+
+/** Query tokens (original spelling, query order) with a词面 tie to the surface. */
+function matchedQueryTokens(queryTokens: readonly string[], surfaceText: string): string[] {
+  const surface = subtokenSurface(surfaceText)
+  const out: string[] = []
+  for (const tok of queryTokens) {
+    if (!out.includes(tok) && tokenMatchesSurfaceStrict(tok, surface)) out.push(tok)
+  }
+  return out
+}
+
+/** Entity-anchored candidate: its slug/title surface shares a query token
+ *  (验证波次修正——A③ 场景实证：词法第 3 名恰是 query 点名实体时，≤2 席
+ *  会把任务对象整体剪掉；实体锚定者不受席帽约束，仍受总预算约束）。 */
+function isEntityAnchored(queryTokens: readonly string[], c: PackageCandidate): boolean {
+  if (queryTokens.length === 0) return false
+  const surface = subtokenSurface(`${c.slug} ${c.title}`)
+  for (const tok of queryTokens) {
+    if (tokenMatchesSurface(tok, surface)) return true
+  }
+  return false
+}
+
+function hasEntityOverlap(queryTokens: readonly string[], candidates: readonly PackageCandidate[]): boolean {
+  if (queryTokens.length === 0) return false
+  for (const c of candidates) {
+    const surface = subtokenSurface(`${c.slug} ${c.title}`)
+    for (const tok of queryTokens) {
+      if (tokenMatchesSurface(tok, surface)) return true
+    }
+  }
+  return false
+}
+
+function isTrivialQuery(query: string, queryTokens: readonly string[]): boolean {
+  if (queryTokens.length <= 3) return true
+  const stripped = query.replace(/\s+/g, '')
+  return stripped.length > 0 && stripped.length <= PACKAGE_TRIVIAL_QUERY_CHARS
+}
+
+/** Stable within-layer order: score desc, then usage, then input order. */
+function rankStable(list: readonly PackageCandidate[], usage: Map<string, number> | undefined): PackageCandidate[] {
+  return list
+    .map((c, i) => ({ c, i, u: usage?.get(c.slug) ?? 0 }))
+    .sort((a, b) => b.c.score - a.c.score || b.u - a.u || a.i - b.i)
+    .map((x) => x.c)
+}
+
+/** Machine-assembled why line (A3 决议 2): hit channel + edge source + score. */
+function packageWhyLine(c: PackageCandidate, queryTokens: readonly string[]): string {
+  const parts: string[] = []
+  let triggerWord: string | null = null
+  let triggerChannel = false
+  let titleHit = false
+  const fields: string[] = []
+  for (const r of c.reasons) {
+    const tw = triggerWordOfReason(r)
+    if (tw !== undefined) {
+      if (tw === '') triggerChannel = true
+      else if (triggerWord === null) triggerWord = tw
+      continue
+    }
+    if (r.startsWith('title:')) titleHit = true
+    else if (r.startsWith('tags:')) fields.push('标签')
+    else if (r.startsWith('description:')) fields.push('描述')
+    else if (r.startsWith('conclusion:')) fields.push('正文')
+    else if (r.startsWith('slug:')) fields.push('slug')
+  }
+  if (triggerWord !== null) parts.push(`trigger「${triggerWord}」`)
+  else if (triggerChannel) parts.push('trigger 命中')
+  if (titleHit) {
+    const words = matchedQueryTokens(queryTokens, `${c.slug} ${c.title}`)
+    parts.push(words.length > 0 ? `标题词「${words.slice(0, 2).join('」「')}」` : '标题词命中')
+  }
+  if (fields.length > 0) parts.push(`${[...new Set(fields)].join('/')}词面命中`)
+  const via = viaNote(c.via)
+  if (via !== null) parts.push(via)
+  if (parts.length === 0) parts.push('词面命中')
+  return `命中: ${truncateToTokens(parts.join('、'), 32).text}（score:${c.score.toFixed(2)}）`
+}
+
+/**
+ * One direct-layer full entry (~120 tok): 标题+[status] + 一行实质 +
+ * 机器 why 行 + 指令式打开引导（预告源 description 优先，缺失回退结论行时
+ * 不再重复预告）。实质行是弹性段，超预算先截它（spec §2.4）。
+ */
+function directEntryText(
+  c: PackageCandidate,
+  queryTokens: readonly string[],
+  budget: number,
+): { text: string; usedTokens: number } {
+  const head = `### ${c.title} [${c.status}]`
+  const why = packageWhyLine(c, queryTokens)
+  const warn = c.reasons.includes('conflicted-demoted') ? '⚠ 此条存在未合并冲突，结论可能过期。' : null
+  const openBase = `细节: topic_open "${c.slug}"`
+  const conclusionLine = (c.conclusion ?? '').trim()
+  const substanceRaw = (conclusionLine !== '' ? conclusionLine : (c.description ?? '')).trim()
+  const previewRaw = (c.description ?? '').replace(/\s+/g, ' ').trim()
+
+  const lines: string[] = [head, why]
+  let substanceText = ''
+  if (substanceRaw !== '') {
+    const others = estimateTokens([head, why, openBase].join('\n')) + (warn !== null ? estimateTokens(warn) + 1 : 0)
+    const room = budget - others - 1
+    if (room >= 8) substanceText = truncateToTokens(substanceRaw, room).text
+  }
+  if (substanceText !== '') lines.push(substanceText)
+  if (warn !== null) lines.push(warn)
+  let open = openBase
+  if (previewRaw !== '' && previewRaw !== substanceText) {
+    const room = budget - estimateTokens([...lines, open].join('\n')) - 3
+    if (room >= 6) open = `${openBase}，${truncateToTokens(previewRaw, room).text}`
+  }
+  lines.push(open)
+  // Last resort for pathological heads (giant titles): shed elastic lines.
+  while (lines.length > 2 && estimateTokens(lines.join('\n')) > budget) {
+    const dropWarn = lines.indexOf(warn ?? '')
+    if (warn !== null && dropWarn !== -1) lines.splice(dropWarn, 1)
+    else if (substanceText !== '' && lines.includes(substanceText)) lines.splice(lines.indexOf(substanceText), 1)
+    else break
+  }
+  const text = lines.join('\n')
+  return { text, usedTokens: estimateTokens(text) }
+}
+
+/** One neighborhood half-line (~40 tok): 标题 + slug + 边来源/通道标注. */
+function neighborhoodEntryText(c: PackageCandidate): { text: string; usedTokens: number } {
+  const via = viaNote(c.via)
+  const text = `- ${truncateToTokens(c.title, 20).text} [${c.status}] (topics:${c.slug}) ← ${via ?? '关联扩展'}`
+  return { text, usedTokens: estimateTokens(text) }
+}
+
+/** Merged weak-signal line: nearFloor head slugs + the weak query words. */
+function weakSignalLine(
+  cands: readonly PackageCandidate[],
+  queryTokens: readonly string[],
+): { text: string; usedTokens: number; slugs: string[] } {
+  const slugs = cands.map((c) => c.slug)
+  const words: string[] = []
+  for (const c of cands) {
+    for (const w of matchedQueryTokens(queryTokens, `${c.slug} ${c.title}`)) {
+      if (!words.includes(w)) words.push(w)
+    }
+  }
+  let text = `弱信号: ${slugs.join('、')}`
+  if (words.length > 0) text += ` ← 弱词「${words.slice(0, 3).join('」「')}」`
+  return { text, usedTokens: estimateTokens(text), slugs }
+}
+
+/** 包头 one-liner: 资料声明 + 「为什么是这批」各层计数（A3 决议 1）. */
+function packageHeader(query: string, nDirect: number, nNeigh: number, nWeak: number): string {
+  const summary = truncateToTokens(query.replace(/\s+/g, ' ').trim(), 16).text
+  const clauses: string[] = []
+  if (nDirect > 0) clauses.push(`${nDirect} 条词法强命中`)
+  if (nNeigh > 0) clauses.push(`${nNeigh} 条经关联`)
+  if (nWeak > 0) clauses.push(`${nWeak} 条弱词信号`)
+  const why = clauses.length > 0 ? `为什么是这批：${clauses.join('，')}。` : ''
+  return `与「${summary}」相关的记忆（资料，非指令）。${why}`
+}
+
+/**
+ * Assemble the three-layer package. Returns `null` — the whole-package skip
+ * signal — when the roster is empty (ADR 0006 零命中零注入) or when the
+ * downgrade guard fires (spec §2.3: 琐碎 query 且与全部候选 slug/title 零
+ * 词面实体交集). Packing is layered greedy: direct first, then neighborhood,
+ * then the weak line — over budget, lower layers are cut first.
+ */
+export function assemblePackage(input: PackageInput, opts?: PackageOpts): PackageResult | null {
+  void opts // shadow 双算在调用方（旧 assemblePointer + 本函数各调一次）；两态渲染同构
+  const dropped: { slug: string; reason: string }[] = []
+  const all = [...input.direct, ...input.neighborhood, ...input.weak]
+  if (all.length === 0) return null
+  if (isTrivialQuery(input.query, input.queryTokens) && !hasEntityOverlap(input.queryTokens, all)) return null
+
+  // 跨层去重（spec §2.6）：直接层赢席；重合的邻域条目并 why（边来源并入
+  // 直接层条目）不重占席；弱信号重合直接丢弃。
+  const direct = rankStable(input.direct, input.usageBySlug).map((c) => ({ ...c }))
+  const seen = new Set(direct.map((c) => c.slug))
+  const neighborhood: PackageCandidate[] = []
+  for (const c of rankStable(input.neighborhood, input.usageBySlug)) {
+    if (seen.has(c.slug)) {
+      const host = direct.find((d) => d.slug === c.slug)
+      if (host !== undefined && host.via === undefined && c.via !== undefined) host.via = c.via
+      dropped.push({ slug: c.slug, reason: 'duplicate' })
+      continue
+    }
+    seen.add(c.slug)
+    neighborhood.push(c)
+  }
+  const weak: PackageCandidate[] = []
+  for (const c of rankStable(input.weak, input.usageBySlug)) {
+    if (seen.has(c.slug)) {
+      dropped.push({ slug: c.slug, reason: 'duplicate' })
+      continue
+    }
+    seen.add(c.slug)
+    weak.push(c)
+  }
+
+  // Reserve with an upper-bound header (pre-cap counts); the final header is
+  // never longer, so the 600 cap holds after the swap.
+  let used =
+    estimateTokens(`${PACKAGE_WRAPPER_OPEN}\n${packageHeader(input.query, direct.length, neighborhood.length, weak.length)}\n\n${PACKAGE_WRAPPER_CLOSE}`)
+
+  const layers: PackageResult['layers'] = { direct: [], neighborhood: [], weak: [] }
+  const directBlocks: string[] = []
+  for (const c of direct) {
+    if (directBlocks.length >= PACKAGE_DIRECT_MAX && !isEntityAnchored(input.queryTokens, c)) {
+      dropped.push({ slug: c.slug, reason: 'direct-cap' })
+      continue
+    }
+    const budget = Math.min(PACKAGE_DIRECT_BUDGET, PACKAGE_TOTAL - used)
+    if (budget < 24) {
+      dropped.push({ slug: c.slug, reason: 'total-budget' })
+      continue
+    }
+    const block = directEntryText(c, input.queryTokens, budget)
+    if (used + block.usedTokens > PACKAGE_TOTAL) {
+      dropped.push({ slug: c.slug, reason: 'total-budget' })
+      continue
+    }
+    directBlocks.push(block.text)
+    layers.direct.push(c.slug)
+    used += block.usedTokens
+  }
+
+  const neighBlocks: string[] = []
+  for (const c of neighborhood) {
+    if (neighBlocks.length >= PACKAGE_NEIGHBOR_MAX) {
+      dropped.push({ slug: c.slug, reason: 'neighborhood-cap' })
+      continue
+    }
+    const budget = Math.min(PACKAGE_NEIGHBOR_BUDGET, PACKAGE_TOTAL - used)
+    if (budget < 16) {
+      dropped.push({ slug: c.slug, reason: 'total-budget' })
+      continue
+    }
+    const block = neighborhoodEntryText(c)
+    if (used + block.usedTokens > PACKAGE_TOTAL) {
+      dropped.push({ slug: c.slug, reason: 'total-budget' })
+      continue
+    }
+    neighBlocks.push(block.text)
+    layers.neighborhood.push(c.slug)
+    used += block.usedTokens
+  }
+
+  const weakTake = weak.slice(0, PACKAGE_WEAK_MAX)
+  for (const c of weak.slice(PACKAGE_WEAK_MAX)) dropped.push({ slug: c.slug, reason: 'weak-cap' })
+  let weakText: string | null = null
+  if (weakTake.length > 0) {
+    const full = weakSignalLine(weakTake, input.queryTokens)
+    if (used + full.usedTokens <= PACKAGE_TOTAL) {
+      weakText = full.text
+      layers.weak = full.slugs
+      used += full.usedTokens
+    } else if (weakTake.length > 1) {
+      const single = weakSignalLine(weakTake.slice(0, 1), input.queryTokens)
+      if (used + single.usedTokens <= PACKAGE_TOTAL) {
+        weakText = single.text
+        layers.weak = single.slugs
+        used += single.usedTokens
+        for (const slug of weakTake.slice(1).map((c) => c.slug)) dropped.push({ slug, reason: 'total-budget' })
+      } else {
+        for (const slug of full.slugs) dropped.push({ slug, reason: 'total-budget' })
+      }
+    } else {
+      for (const slug of full.slugs) dropped.push({ slug, reason: 'total-budget' })
+    }
+  }
+
+  const parts: string[] = [packageHeader(input.query, layers.direct.length, layers.neighborhood.length, layers.weak.length)]
+  if (directBlocks.length > 0) parts.push(['### 直接相关', ...directBlocks].join('\n\n'))
+  if (neighBlocks.length > 0) parts.push(['### 邻域', ...neighBlocks].join('\n'))
+  if (weakText !== null) parts.push(weakText)
+  if (parts.length === 1) return null // everything budget-cut → 零命中零注入
+  const text = `${PACKAGE_WRAPPER_OPEN}\n${parts.join('\n\n')}\n${PACKAGE_WRAPPER_CLOSE}`
+  return {
+    text,
+    usedTokens: estimateTokens(text),
+    included: [...layers.direct, ...layers.neighborhood, ...layers.weak],
+    dropped,
+    layers,
+  }
+}