@aiwayds/dsh-topics-memory 0.22.0 → 0.23.0

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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwayds/dsh-topics-memory",
-  "version": "0.22.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/zero-open-decay.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/config.ts

@@ -105,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 = {
@@ -149,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 = [
@@ -186,6 +208,9 @@ export const CONFIG_KEYS = [
   'jevSecretFile',
   'jevLayaFallback',
   'jevLayaUrl',
+  'embeddingProvider',
+  'embeddingModel',
+  'packageMode',
 ] as const
 
 export type ConfigKey = (typeof CONFIG_KEYS)[number]
@@ -257,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,
+  }
+}