@aiwayds/dsh-topics-memory 0.21.0 → 0.23.0

package/README.md

@@ -201,6 +201,7 @@ First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set
 | `consolidateCadence` | `daily` | Consolidation-lane cadence: `daily`/`3d`/`7d`/`off`. At session start the plugin checks the last consolidation time (`meta/consolidate-state.json`) and, when due, runs the LLM gardener in the background (reusing the distill model route): local lexical clustering only feeds near-look-alike candidate clusters; four op kinds merge/promote/deprecate/refresh, out-of-scope ops are dropped; a failed call never advances the stamp, so the next start retries |
 | `deprecatedTtlDays` | `15` | Deprecated topics older than N days are dropped at session start (local rule, no model; each drop is its own git commit — history stays recoverable); `0` disables the sweep |
 | `usageBoost` | `0.15` | Usage boost (ADR 0015): topics injected/opened in the last 30 days score higher at retrieval (gate-scoped, capped at 0.2, never granted to zero-lexical candidates, structural gate not waived); `0` disables |
+| `zeroOpenDecay` | `false` | Zero-open decay: halve the retrieval score of zero-open high-frequency slugs before the threshold cut (see the section below) |
 | `pushDebounceSeconds` | `45` | GitHub-mode debounced push interval |
 | `jevEnabled` | `false` | System One decision layer master switch (experimental): `false` = zero behavior change — see the Jev decision layer section above |
 | `jevBackend` | `zen` | Decision endpoint: `zen` (free) / `native` / `openrouter` |
@@ -210,6 +211,10 @@ First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set
 | `jevLayaFallback` | `false` | Local laya pace-maker: fire a parallel laya call on every jev request; its answer takes over (degraded, relative-ranking only) when the primary fails |
 | `jevLayaUrl` | `http://127.0.0.1:8000/v1/systemone` | laya-serve endpoint for the pace-maker |
 
+### Zero-open decay (default off)
+
+`zeroOpenDecay: true` halves the hit score of slugs the stats panel lists as 零打开高频 — truly rendered ≥5 injections in the rolling 30 days with zero `topic_open` events ever. The decay applies at score finalization, before the match threshold, so a decayed candidate that drops below it lands in nearMisses carrying the `zero-open-decay` reason — the injection log shows why it stopped ranking. Motivation: 24 high-frequency topics held the injection leaderboard with zero opens while score and opens proved only weakly correlated (the 0.3 threshold stays untouched). Default `false` means zero behavior change; unreadable injection/open logs skip the decay (fail-open). Toggle live with `/topics set zero-open-decay on|off`.
+
 ## Acknowledgements
 
 This project's shape is directly inspired and supported by:

package/README.zh.md

@@ -187,6 +187,7 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 | `consolidateCadence` | `daily` | 整理 lane 节拍：`daily`/`3d`/`7d`/`off`。会话启动时检查上次整理时间（`meta/consolidate-state.json`），到期即在后台自动跑 LLM 园丁（复用蒸馏模型路由）：本地词面聚类只送「长得像」的候选簇，四类动作 merge/promote/deprecate/refresh，越权 op 一律丢弃；模型调用失败不推进节拍，下次启动重试 |
 | `deprecatedTtlDays` | `15` | deprecated 条目超过 N 天在会话启动时自动删除（本地规则不依赖模型，逐条 git commit 可回溯找回）；`0` 关闭清扫 |
 | `usageBoost` | `0.15` | 使用加成（ADR 0015）：近 30 天被注入命中/点开过的 Topic 检索加分（计入门槛分、帽 0.2、零词面相关不加、结构门不豁免）；`0` 关闭 |
+| `zeroOpenDecay` | `false` | 零打开衰减：零打开高频 slug 的命中分在阈值裁剪前减半（见下方小节） |
 | `pushDebounceSeconds` | `45` | GitHub 模式去抖推送间隔 |
 | `jevEnabled` | `false` | System One 决策层总开关（实验）：`false` = 零行为变化——见上方「Jev 决策层」一节 |
 | `jevBackend` | `zen` | 决策端点：`zen`（免费）/ `native` / `openrouter` |
@@ -197,6 +198,10 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 | `jevLayaUrl` | `http://127.0.0.1:8000/v1/systemone` | 陪跑用的 laya-serve 端点 |
 | `jevDebug` | 关 | 诊断日志开关（走宿主 logger，默认静默） |
 
+### 零打开衰减（默认关）
+
+`zeroOpenDecay: true` 时，命中分在 matchThreshold 裁剪前乘 0.5：滚动 30 天内被真正注入 ≥5 次、且 opens.jsonl 全期 0 次打开的 slug（即 `/topics stats` 的「零打开高频」清单——stats 面板与打分衰减共用同一条共享规则）不再霸榜；跌破阈值的候选自然落入 nearMisses 并带 `zero-open-decay` 标签，注入日志可见原因。动机：24 个「注入 ≥5 次、0 打开」的高频话题长期霸榜，而 score 与打开仅弱相关（阈值 0.3 不动）。默认 `false` 零行为变化；injections/opens 读取失败跳过衰减（fail-open）；`/topics set zero-open-decay on|off` 运行时切换。
+
 ### laya 本地陪跑（实验，默认关）
 
 `jevLayaFallback: true` 且本地跑着 [laya](https://github.com/NandhaKishorM/laya) serve 时，每次 jev 调用并发一路本地 laya 请求：主路答案驱动决策，laya 答案并排落账——一组永久运行的 laya vs jev 同题对照。laya 是**纯遥测**（真实负载实测批内排序与主路一致率 0/14、绝对分不可用），主路失败照旧回退旧路径；laya 没起 = 毫秒级连接拒绝。

package/lib/commands.js

@@ -12,7 +12,7 @@ import { serializeTopicDoc, slugify, firstParagraph } from "./okf.js";
 import { buildGraph, renderGraphHtml } from "./viz.js";
 import { CONFIG_KEYS, displayKey, parseConfigValue } from "./config.js";
 import { reloadSecrets } from "./jev/gate.js";
-import { aggregateStats } from "./ilog.js";
+import { aggregateStats, aggregateOpenPanel, ZERO_OPEN_MIN_INJECTIONS } from "./ilog.js";
 import { askDistillSingle, createOnboardHandler, llmDirectoryNotice, makePanel, parseDistillInput, pickLlmDirectory, } from "./onboard.js";
 export const HELP = [
     'dsh-topics-memory — OKF topic 记忆（本地 bundle，git 可追溯，可选 GitHub 同步）',
@@ -20,7 +20,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）',
@@ -277,16 +277,14 @@ async function renderStats(service) {
         }
         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 不回注） |`);
@@ -296,6 +294,24 @@ async function renderStats(service) {
         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('', `Near-miss 分布（低于阈值 ${service.cfg.matchThreshold.toFixed(2)} 或被结构门挡下，对数刻度）：`, '', '```', ...renderNearMissSparkline(stats.nearMissHistogram), '```');
         const hint = tuningHint(stats, service.cfg.matchThreshold);

package/lib/config.d.ts

@@ -70,6 +70,12 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
      *  granted to zero-lexical candidates; the structural gate still applies.
      *  0 = off. */
     usageBoost: z<number, number, "volatile-defined">;
+    /** 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, boolean, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z<number, number, "volatile-defined">;
     /** System One decision-model integration (design 2026-09-25), default-off
@@ -97,6 +103,21 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
     /** laya-serve systemone endpoint for the pace-maker (default: the local
      *  laya-serve bind from the laya repo's serve mode). */
     jevLayaUrl: z<string, string, "volatile-defined">;
+    /** 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, string, "volatile-defined">;
+    /** Embedding model; '' = provider default (ollama → nomic-embed-text),
+     *  same sentinel pattern as distillModel. */
+    embeddingModel: z<string, string, "volatile-defined">;
+    /** 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, string, "volatile-defined">;
 }>>, Schemastery.ObjectT<NoInfer<{
     /** GitHub repo `owner/name`; empty = local-only mode (ADR 0008). */
     repo: z<string, string, "volatile-defined">;
@@ -162,6 +183,12 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
      *  granted to zero-lexical candidates; the structural gate still applies.
      *  0 = off. */
     usageBoost: z<number, number, "volatile-defined">;
+    /** 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, boolean, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z<number, number, "volatile-defined">;
     /** System One decision-model integration (design 2026-09-25), default-off
@@ -189,6 +216,21 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
     /** laya-serve systemone endpoint for the pace-maker (default: the local
      *  laya-serve bind from the laya repo's serve mode). */
     jevLayaUrl: z<string, string, "volatile-defined">;
+    /** 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, string, "volatile-defined">;
+    /** Embedding model; '' = provider default (ollama → nomic-embed-text),
+     *  same sentinel pattern as distillModel. */
+    embeddingModel: z<string, string, "volatile-defined">;
+    /** 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, string, "volatile-defined">;
 }>>, "plain">;
 export type TopicsConfigValue = {
     repo: string;
@@ -216,6 +258,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
@@ -228,8 +274,15 @@ 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 declare const CONFIG_KEYS: readonly ["repo", "autoInject", "injectDedup", "suppressEcho", "topK", "perTopicBudget", "totalBudget", "matchThreshold", "tagBoost", "injectMode", "qualityLane", "graphDepth", "recencyWindowDays", "autoObserve", "includeSubagents", "observationMaxChars", "distillEveryTurns", "distillOnSessionEnd", "distillProvider", "distillModel", "distillBatchSize", "distillMaxModelCalls", "consolidateCadence", "deprecatedTtlDays", "usageBoost", "pushDebounceSeconds", "jevEnabled", "jevBackend", "jevModel", "jevTimeoutMs", "jevSecretFile", "jevLayaFallback", "jevLayaUrl"];
+export declare const CONFIG_KEYS: readonly ["repo", "autoInject", "injectDedup", "suppressEcho", "topK", "perTopicBudget", "totalBudget", "matchThreshold", "tagBoost", "injectMode", "qualityLane", "graphDepth", "recencyWindowDays", "autoObserve", "includeSubagents", "observationMaxChars", "distillEveryTurns", "distillOnSessionEnd", "distillProvider", "distillModel", "distillBatchSize", "distillMaxModelCalls", "consolidateCadence", "deprecatedTtlDays", "usageBoost", "zeroOpenDecay", "pushDebounceSeconds", "jevEnabled", "jevBackend", "jevModel", "jevTimeoutMs", "jevSecretFile", "jevLayaFallback", "jevLayaUrl", "embeddingProvider", "embeddingModel", "packageMode"];
 export type ConfigKey = (typeof CONFIG_KEYS)[number];
 /** CamelCase → dash-display (topK → top-k) for command output. */
 export declare function displayKey(key: string): string;

package/lib/config.js

@@ -70,6 +70,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
@@ -97,6 +103,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 const CONFIG_KEYS = [
     'repo',
@@ -124,6 +145,7 @@ export const CONFIG_KEYS = [
     'consolidateCadence',
     'deprecatedTtlDays',
     'usageBoost',
+    'zeroOpenDecay',
     'pushDebounceSeconds',
     'jevEnabled',
     'jevBackend',
@@ -132,6 +154,9 @@ export const CONFIG_KEYS = [
     'jevSecretFile',
     'jevLayaFallback',
     'jevLayaUrl',
+    'embeddingProvider',
+    'embeddingModel',
+    'packageMode',
 ];
 /** CamelCase → dash-display (topK → top-k) for command output. */
 export function displayKey(key) {
@@ -152,7 +177,8 @@ export function parseConfigValue(key, raw) {
         case 'autoObserve':
         case 'distillOnSessionEnd':
         case 'includeSubagents':
-        case 'jevEnabled': {
+        case 'jevEnabled':
+        case 'zeroOpenDecay': {
             if (raw === 'on' || raw === 'true')
                 return true;
             if (raw === 'off' || raw === 'false')
@@ -206,10 +232,21 @@ export function parseConfigValue(key, raw) {
         }
         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;

package/lib/digest.d.ts

@@ -77,3 +77,76 @@ export declare function assemblePointer(entries: readonly DigestInput[], cfg: As
  * total budget. Zero hits → empty text (ADR 0006: 零命中零注入).
  */
 export declare function assembleInjection(entries: readonly DigestInput[], cfg: AssembleConfig, slow?: readonly SlowPointerInput[]): AssembleResult;
+/** 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 declare const PACKAGE_TOTAL = 600;
+export declare const PACKAGE_DIRECT_MAX = 2;
+export declare const PACKAGE_DIRECT_BUDGET = 120;
+export declare const PACKAGE_NEIGHBOR_MAX = 3;
+export declare const PACKAGE_NEIGHBOR_BUDGET = 40;
+export declare 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 declare const PACKAGE_TRIVIAL_QUERY_CHARS = 16;
+/**
+ * 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 declare function assemblePackage(input: PackageInput, opts?: PackageOpts): PackageResult | null;