StateStore.loadAll: optional parse budget / stat preselection for sub-linear startup

[ranxianglei]

来源: ranxianglei/billion-context#478 分析 sessions 启动解析开销时发现

背景

billion-context#478 修复了 sessions 注册表存储的三重膨胀(叶块 blockContents 逐字节双份、零 GC、每次启动两遍全量同步解析)。其中"启动解析时间随语料规模线性恶化"目前只能治一半:启动期 GC 把语料总量封顶(默认 1 GiB)之后,每次启动仍然要对全部存活文件做 readFileSync + JSON.parse(kernel loadAll 全量递归目录树,逐文件解析)。语料封顶在 GB 量级时,单次启动的同步解析仍是百毫秒~秒级开销,且随会话数线性增长。

billion-context 侧无法绕过:选择性加载需要复刻 kernel 的 canonical/spill(<name>.fb.json)savedAt 对账("freshest wins")逻辑,属于对 kernel 内部实现的脆弱复制,不可取。

建议(二选一,均纯增量、默认行为不变)

1. loadAll(options?: { maxParseBytes?: number }):先只 readdir + stat(不读内容),按文件大小/mtime 从新到旧累加,超过预算的最旧文件跳过解析;或
2. 暴露 statAll(): Promise<Map<string, { size: number; mtimeMs: number }>>(id → 元信息,不含内容):让下游自行挑选要 loadSync(id, hint?) 的子集。

约束:同一 id 的 canonical 与 .fb.json spill 两个变体必须同进同出(都解析或都跳过),否则破坏现有 freshest-wins 对账语义。

消费方

billion-context SessionStore.boot() 会把 BILI_MAX_SESSIONS 的语义从"加载后截断内存"改造为真正的"加载预算"(#478 建议 4 的后半段):先 stat 预选,只解析预算内最新的记录,最旧的直接不解析(它们大概率也已被保留期 GC 清掉,两者互补)。

依赖顺序

按跨仓规则:acp-kernel 先发版并在 npm 上线,billion-context 再 bump 精确版本依赖并消费。

[ranxianglei]

🤖 ework agent · qwen3.8-27b

[bot] 🏷 审核结论:合理,采用方案 1(loadAll({ maxParseBytes }))

验证(现象层):已核对 src/persist/store.ts —— loadAll() 确实全量递归走目录树后逐文件 readFileSync + JSON.parse(store.ts:292-326、511-534),启动解析开销随存活文件数量/体积线性增长。#478 的 GC 给语料总量封顶后,"每次启动全量解析"的开销仍在,现象成立。

方案选择:方案 1。方案 2(statAll(): Map<id, meta>)结构性不成立:

• flat 默认文件名是 sha256(id)[:24](单向哈希),id 存在 JSON envelope 内部——要给出 id → 元信息 映射就必须先读文件内容,"不含内容"做不到;
• 若改成按路径键控,则 canonical/spill 配对与 freshest-wins 对账逻辑要落到消费方,正是你在 issue 里明确排除的"对 kernel 内部实现的脆弱复制"。

方案 1 把对账留在 kernel 内,预算只做"哪些组参与解析"的预选,纯增量、默认行为不变。

将实现的语义:

1. 不带参数 → 与现状完全一致。
2. 带 maxParseBytes:第一遍只做 readdir + stat(不读内容);把每个 canonical <stem>.json 与其 <stem>.fb.json spill 归为同一组(按 目录+stem 分组,不同目录下同 stem 是不同记录,不会误配;满足同进同出约束);组大小 = 成员之和,组新鲜度 = 成员最大 mtime;从新到旧贪心纳入累计 ≤ 预算的组,其余跳过。
3. 硬上限:若连最新一组都超预算,返回空 map 并打一条 warn 日志。不强制解析单个超大文件——强制会让单个异常大文件无界突破预算,违背限定启动成本的初衷;被跳过的文件不删除(kernel 既有原则),仍可通过 loadSync(id, hint) 单独取回,与你侧保留期 GC 互补。
4. mtime 是 savedAt 的 stat 层近似(不读内容拿不到 savedAt);已被解析记录之间的先后仍以现有 savedAt 对账为准,语义不变。
5. 非有限数/负数预算直接抛 TypeError(fail fast)。

测试覆盖:预算选择最新子集、canonical/spill 同进同出、无一可容纳时返回空集且文件留存、跨目录同 stem 配对隔离、非法参数。PR 建好后在此补链接;发版顺序按跨仓规则:本仓先上线 npm,billion-context 再 bump。

[ranxianglei]

🤖 ework agent · qwen3.8-27b

[bot] 🏷 已实现,PR: #186

方案选择:采用建议 1 loadAll(options?: { maxParseBytes?: number }),纯增量、默认行为不变。建议 2(statAll())不采用的原因:flat 文件名是 sha256(id)[:24].json 单向哈希,id 在 envelope 内部——按 id 返回元信息就必须读内容(失去意义);按路径返回则会把 canonical/spill 配对和 freshest-wins 对账推给消费方,正是本 issue 要避开的脆弱复制。

语义(与 issue 约束对齐):

1. 不传 options ⇒ 与现状逐字节一致;
2. 传 maxParseBytes:第一遍只做 readdir + stat(零内容读取)。每个 canonical <stem>.json 与其 <stem>.fb.json spill 按 dir+stem 成组(不同目录下同名 stem = 不同记录);组大小 = 成员之和,组新鲜度 = max mtimeMs;按新到旧贪心填充预算(skip-and-continue);
3. 硬上限:若最新的组单独就超预算 → 返回空 Map 并 warn([persist] loadAll budget <N> bytes: parsed K/M record groups (skipped ...)),绝不强解超大文件。被跳过的文件不删除(store 从不删数据),仍可经 loadSync(id, hint) 取回;
4. mtime 是 savedAt 的 stat 级代理(不解析就不知道 savedAt);已解析记录之间的顺序仍走原有 savedAt 对账,语义不变;
5. maxParseBytes 非有限数或为负 → TypeError fail-fast。

issue 的硬约束已满足:同一 id 的 canonical 与 spill 同进同出,不会半解析破坏 freshest-wins。

测试(+5,tests/persist.test.ts):预算内恰好解析最新子集 / 无预算行为不变 / 跳过≠删除(loadSync 仍可达)/ canonical+spill 紧预算整体跳过、宽预算双解析且 savedAt 对账正确 / 全超预算→空 Map+warn / -1、NaN→TypeError / 跨目录同名 stem 不误并组。

验证:npm run typecheck ✅ · npm test 577 pass / 0 fail ✅ · npm run build ✅。feature 分支不改 version。

依赖顺序:此 PR 合并发布后,billion-context 再 bump 精确版本,在 SessionStore.boot() 用 maxParseBytes 把 BILI_MAX_SESSIONS 从"加载后截断内存"改造为真正的加载预算(stat 预选 + 只解析预算内最新记录)。

按 AGENTS.md §6,合并前需要 ≥2 个独立 agent 评审。