From fcb984ed384be9bd309e41d33bd7a04bf6acab36 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Tue, 20 Oct 2026 16:05:13 +0800 Subject: [PATCH 1/4] =?UTF-8?q?storage:=20StorageBackend=20contract=20(ste?= =?UTF-8?q?p=201)=20=E2=80=94=20sqlite=20re-wired=20through=20the=20regist?= =?UTF-8?q?ry,=20mysql=20a=20registered=20stub=20(#3931)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - src/storage/backend.ts: operation-level async contract (~40 ops: ingest, reads, session_ext/kv, watermark/pointers, reap journal, archive/gc, checkpoints, summaries, diagnostics) — the seam is operations, not SQL dialects, so per-backend transaction semantics survive. SqliteBackend wraps the existing UnifiedStore (sync under the hood, Promise surface). - registry: openBackend()/listBackendNames(); 'mysql' validates but throws the documented step-2 error at open (mysql2 never loaded in step 1); resolveBackendName (env BILI_STORAGE_BACKEND > storage.backend > sqlite) + backendSelectionNotice keep non-sqlite boots on sqlite with ONE warn. - shadow.maybeOpen takes the file backend tier and logs the notice. - export.ts jsonl renderer consumes the contract (seam proof); guarded open wraps UnifiedStore in the adapter — behavior pinned by existing export tests unchanged. - tests: storage-backend-contract (runs against ANY backend via the registry — reused verbatim for mysql in step 2) + knob matrix. - docs: storage.backend seeds (process.yaml + env-only.yaml), regenerated CONFIGURATION en/zh; CHANGELOG. Zero schema change, zero behavior change for sqlite users (#3931). --- CHANGELOG.md | 1 + CONFIGURATION.md | 3 + CONFIGURATION.zh-CN.md | 3 + src/config.ts | 6 + src/export.ts | 24 +- src/knobs.ts | 5 + src/persist.ts | 3 +- src/storage/backend.ts | 327 +++++++++++++++++++++++++ src/storage/shadow.ts | 12 + tests/export-jsonl.test.ts | 3 +- tests/storage-backend-contract.test.ts | 185 ++++++++++++++ tests/storage-backend-knob.test.ts | 57 +++++ website/config-reference/env-only.yaml | 8 + website/config-reference/process.yaml | 7 + 14 files changed, 632 insertions(+), 12 deletions(-) create mode 100644 src/storage/backend.ts create mode 100644 tests/storage-backend-contract.test.ts create mode 100644 tests/storage-backend-knob.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 716a49def1..eca1a2bf80 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ All notable changes to **billion-context** are documented here. Versions follow the merge of a `*_release-v*` branch; CI publishes to npm on tag. ## [Unreleased] +- 存储后端契约第一步(#3931, #3388):统一存储抽出操作级异步 `StorageBackend` 契约(`src/storage/backend.ts`),sqlite 经注册表以默认后端身份重新接入(Promise 包装适配器,零行为/零 schema 变化);`mysql` 为已注册占位 —— 选中时启动提示一行并继续用 sqlite,直开后端的路径(export)按文档化错误失败。新配置 `storage.backend`(env `BILI_STORAGE_BACKEND`,缺省 sqlite)。`--jsonl` 导出渲染器改吃契约(接缝证真);契约测试套件对任意后端实例跑同一断言,第二步 mysql 落地时原样复用。 ### 存储收尾九项一车(#3901,修复 #3463/#3762/#3841/#3798/#3633;#3723 落地) diff --git a/CONFIGURATION.md b/CONFIGURATION.md index e1b8bedd80..56a191b3d3 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -175,6 +175,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed | `persist.epermAlertRepeatMs` | number | 0 (no repeats) | BILI_PERSIST_EPERM_ALERT_REPEAT_MS | Repeat interval for the EPERM alert; 0 logs it once. | | `storage` | object | {} (all defaults) | — | Unified SQLite storage sidecar settings (#2671). | | `storage.unified` | legacy\|shadow\|full | unset (full) | BILI_STORAGE_UNIFIED | Tiered storage-migration switch (#2671): shadow = unified SQLite double-write dry-run with digest reconciliation; full = drop-in read path (unified-first loads with organic import, legacy fallback). Absent everywhere now defaults to FULL (#3818 flip - the shadow dry-run reconciled cleanly since #2815, so the index is the load path; JSON envelopes keep being written, and legacy remains the one-line escape hatch). File tier is strict legacy/shadow/full; the env tier also accepts 1/true (=shadow) and unified (=full) and wins over the file. Resolved once per lane boot - hot edits need a restart. Encryption (BILI_ENCRYPTION_KEY) hard-blocks the sidecar. | +| `storage.backend` | sqlite\|mysql | unset (sqlite) | BILI_STORAGE_BACKEND | Storage backend selection, step 1 of the pluggable-storage plan (#3388 / #3931): the unified store consumes an operation-level async StorageBackend contract, with sqlite as the default and today the only real implementation (the existing UnifiedStore behind a Promise-wrapped adapter - zero behavior change, no schema change). mysql is a REGISTERED STUB: the name validates so configs do not bounce between unknown/unimplemented as the real backend ships (step 2, mysql2 client via the optional-dependency + self-download discipline), but selecting it logs one notice line at lane boot and the store stays on sqlite; paths that open a backend directly (export) fail with the documented error. Unknown names also fall back to sqlite with a notice. Resolved once per lane boot. | | `storage.sqliteAutoDownload` | boolean | true | BILI_SQLITE_AUTO_DOWNLOAD | Gate for the one-time SQLite engine self-download (#2833): when no engine is available in-process (no built-in node:sqlite, no host-installed better-sqlite3) and the unified sidecar is wanted on this platform, bili downloads the pinned better-sqlite3 prebuilt tarball from the npm registry once (~11 MB, sha512-verified) into the cache dir and reuses it on every later start. Engine resolution order: built-in node:sqlite (Node >= 22.5) -> host-provided better-sqlite3 -> cached self-download -> self-download (gated by this switch) -> none (legacy-only, the #2825 degrade contract). The switch gates only the network fetch - a cached copy is used even when it is false; unsupported platforms never download. The tarball download walks a builtin mirror list (#3338): the configured registry (BILI_UPDATE_REGISTRY / update.registry) is tried first, then https://registry.npmjs.org, then https://registry.npmmirror.com - the first mirror that yields a sha512-verified tarball wins; a Node < 22.5 with no engine gets an explicit Node upgrade hint in the degrade reason (#3385). A failed download arms a 6-hour retry cooldown persisted as a marker file under the cache dir (billion-context/sqlite/.bootstrap-failed.json); the storage diagnostics blob shows the marker's absolute expiry time and path - delete that file and restart bili to force an immediate retry instead of waiting out the whole window (#3788). | | `storage.jsonWriter` | on\|off | on | BILI_STORAGE_JSON_WRITER | Phase 3 envelope switch (#2960): off stops writing the legacy JSON session envelope while storage.unified is full - the SQLite index becomes the only persistent copy (reads are already unified-first; boot enumerates the index union, so index-only sessions load normally). Only honored in effective-full mode: under shadow/legacy (or with encryption active) the request is ignored with a one-time warning because the JSON file remains the sole source of truth. Env tier 0/false/off = off and 1/true/on = on wins over the strict file spellings. Fail-safe: if the sidecar disables itself mid-run, envelope writes resume on the next save. Rollback: unset the knob - writing resumes, index-only sessions keep loading via the boot union, and replicas/restore re-materialize portable JSON envelopes. Downgrading the binary (or losing the SQLite engine) makes index-only sessions invisible to v0.1.196 and older until a >=v0.1.197 binary runs again - the data stays intact in index.db, it is just not read by the older code. The per-session content-store sidecar keeps being written either way. A jsonWriter=off lane must be the SOLE writer of its sessions directory: an off lane reads unified-first and never falls back to the file, so any peer instance running legacy/shadow against the same directory diverges silently (its JSON copy stops receiving updates, and the off lane never sees the peer's writes). | | `storage.walJournalSizeLimitBytes` | number | 8388608 | BILI_STORAGE_WAL_JOURNAL_SIZE_LIMIT_BYTES | WAL reclamation cap for index.db-wal (#3250), in bytes: every completed checkpoint truncates the WAL file back to this size, bounding disk use and crash-recovery replay in long-lived processes. NOT a per-session data quota - data lands in index.db as it is written and the WAL only stages frames between checkpoints, so session count/size does not scale this; a large burst can overshoot temporarily until the next completed checkpoint truncates back. Higher = rarer truncate IO but more steady disk use and a longer crash-replay tail. Env tier (positive integer) wins over the file tier; a garbage or non-positive env value falls through to the file/default tier instead of failing boot. Applied when the store opens at lane boot - hot edits need a restart. The effective value appears on the unified-enable log line and in the storage diagnostics blob. | @@ -333,6 +334,7 @@ This index is generated from `website/config-reference/*.yaml` — edit the seed | Key | Type | Default | Env | Description | |-----|------|---------|-----|-------------| | `BILI_DSH_AUTHORED_COMPACTION` | boolean | true (on, #3901 flip) | — | Let bili ANSWER dsh compaction summarize calls locally with the folded snapshot instead of refusing (#3733): identity header + kernel-rendered block summaries, zero egress; replay recognized via the #2432 rebase. | +| `BILI_STORAGE_BACKEND` | sqlite\|mysql | sqlite | — | Env tier for storage.backend (#3931 step 1): sqlite (default, only real backend) or mysql (registered stub - one boot notice, stays on sqlite until step 2). Wins over the file tier. | | `BILI_STORAGE_ARCHIVE_AFTER_DAYS` | integer | 365 | — | GC age sweep window in days (#3463): sessions idle longer than this are archived (one JSON line appended to the single archive log (archive/archive.jsonl) + tombstone row + content/media refs released). 0 disables the age sweep; the manual entry POST /__bili/storage/gc always runs. Config-file key storage.archiveAfterDays is the persistent form. | | `BILI_SNAPSHOT_SHADOW` | boolean | true (on) | — | Snapshot-render shadow observability (#3756 follow-up): compute the outbound snapshot view on every armed turn WITHOUT using it, classify the diff against the legacy outbound, and surface per-session counters in the web panel + the snapshot-shadow diagnostics topic. 0/false/off disables; 1/true/on enables; otherwise the config-file snapshot.shadow boolean applies (default on). The render lane itself stays rollout-gated (BILI_ROLLOUT_SNAPSHOT_RENDER), so the shadow lane never changes outbound bytes - it is the dry-run evidence that flips the rollout later. | | `BILI_CONFIG_FILE` | string | unset (XDG config path) | — | Override the config file path (path relocation). | @@ -1784,6 +1786,7 @@ File keys resolve only when the matching env var is unset. Defaults in parenthes | `BILI_SQLITE_AUTO_DOWNLOAD` | `storage.sqliteAutoDownload` | true | | `BILI_STABLE_SYSTEM_ANCHOR` | `stableSystemAnchor` | false | | `BILI_STORAGE_ARCHIVE_AFTER_DAYS` | `storage.archiveAfterDays` | 365 | +| `BILI_STORAGE_BACKEND` | `storage.backend` | unset (sqlite) | | `BILI_STORAGE_JSON_WRITER` | `storage.jsonWriter` | on | | `BILI_STORAGE_UNIFIED` | `storage.unified` | unset (full) | | `BILI_STORAGE_WAL_JOURNAL_SIZE_LIMIT_BYTES` | `storage.walJournalSizeLimitBytes` | 8388608 | diff --git a/CONFIGURATION.zh-CN.md b/CONFIGURATION.zh-CN.md index 0052589564..727a85219c 100644 --- a/CONFIGURATION.zh-CN.md +++ b/CONFIGURATION.zh-CN.md @@ -175,6 +175,7 @@ | `persist.epermAlertRepeatMs` | number | 0 (no repeats) | BILI_PERSIST_EPERM_ALERT_REPEAT_MS | EPERM 告警的重复间隔;0 只记录一次。 | | `storage` | object | {} (all defaults) | — | 统一 SQLite 存储边车设置(#2671)。 | | `storage.unified` | legacy\|shadow\|full | unset (full) | BILI_STORAGE_UNIFIED | 分层存储迁移开关(#2671):shadow = 统一 SQLite 双写干跑 + digest 对账;full = 平替读路径(unified-first 加载 + 有机导入 + legacy 兜底)。两处均未设置时默认 full(#3818 翻转 —— shadow 干跑自 #2815 起对账一直干净,索引因此成为默认加载路径;JSON 信封照写,legacy 仍是一行逃生口)。文件层只接受 legacy/shadow/full;环境变量层还接受 1/true(=shadow)与 unified(=full)并优先于文件。每个 lane 启动时解析一次 —— 热改动需重启生效。加密(BILI_ENCRYPTION_KEY)会硬阻断边车。 | +| `storage.backend` | sqlite\|mysql | unset (sqlite) | BILI_STORAGE_BACKEND | 存储后端选择,可插拔存储计划第一步(#3388 / #3931):统一存储消费操作级的异步 StorageBackend 契约,sqlite 为默认且是当前唯一真实现(现有 UnifiedStore 套一层 Promise 包装适配器 —— 零行为变化、零 schema 变化)。mysql 是已注册占位:该名字能通过校验(真实后端随第二步落地 —— mysql2 客户端,走可选依赖+自下载纪律 —— 期间配置不会在 unknown/unimplemented 之间来回弹),但选中它只会在 lane 启动时打一行提示并继续用 sqlite;直接开后端的路径(export)按文档化的错误失败。未知名字同样回退 sqlite 并提示。每个 lane 启动时解析一次。 | | `storage.sqliteAutoDownload` | boolean | true | BILI_SQLITE_AUTO_DOWNLOAD | SQLite 引擎一次性自下载的闸门(#2833):进程内没有可用引擎(无内置 node:sqlite、宿主未装 better-sqlite3)且本平台希望启用统一边车时,bili 从 npm registry 一次性下载钉死的 better-sqlite3 预编译 tarball(约 11 MB,sha512 校验)到缓存目录,之后每次启动复用。引擎解析顺序:内置 node:sqlite(Node >= 22.5)-> 宿主机已装的 better-sqlite3 -> 缓存的自下载副本 -> 自下载(本开关控制)-> 无引擎(仅 legacy,即 #2825 降级契约)。开关只控制网络下载 —— 为 false 时缓存副本仍会使用;不支持的平台永不下载。 tarball 下载内置镜像列表兜底(#3338):先试配置的 registry(BILI_UPDATE_REGISTRY / update.registry),再试 https://registry.npmjs.org、https://registry.npmmirror.com —— 第一个通过 sha512 校验的镜像生效;Node < 22.5 且无引擎时,降级原因会给出明确的 Node 升级提示(#3385)。下载失败会置一个 6 小时的重试冷却,以标记文件形式持久化在缓存目录下(billion-context/sqlite/.bootstrap-failed.json);storage 诊断块会显示该标记的绝对到期时间与路径 —— 删除该文件并重启 bili 即可强制立即重试,不必等完整个冷却窗口(#3788)。 | | `storage.jsonWriter` | on\|off | on | BILI_STORAGE_JSON_WRITER | Phase 3 信封开关(#2960):off 时若 storage.unified 为 full 则不再写 legacy JSON 会话信封 —— SQLite 索引成为唯一持久化副本(读路径本就 unified-first;boot 枚举索引并集,纯索引会话可正常加载)。仅在有效 full 模式下生效:shadow/legacy(或加密激活)下请求会被忽略并警告一次,因为 JSON 文件仍是唯一事实源。环境变量层 0/false/off = off、1/true/on = on,优先于严格拼写的文件层。失败安全:若边车运行中自禁用,下次保存即恢复信封写入。回滚:去掉该开关 —— 写入恢复,纯索引会话经 boot 并集继续可加载,replicas/restore 可重新物化可移植的 JSON 信封。降级二进制(或丢失 SQLite 引擎)会让纯索引会话在 v0.1.196 及更早版本上不可见,直到重新运行 >=v0.1.197 —— 数据在 index.db 中完好无损,只是旧代码不读它。每会话的 content-store 边车无论开关如何都照写。jsonWriter=off 的 lane 必须是其会话目录的唯一写者:off lane 读路径 unified-first、永不回退到文件,因此同一目录上跑 legacy/shadow 的对等实例会静默分叉(它的 JSON 副本收不到更新,off lane 也看不到对等实例的写入)。 | | `storage.walJournalSizeLimitBytes` | number | 8388608 | BILI_STORAGE_WAL_JOURNAL_SIZE_LIMIT_BYTES | index.db-wal 的 WAL 回收上限(#3250),单位字节:每次完成的 checkpoint 把 WAL 文件截回该大小,约束长驻进程的磁盘占用与崩溃恢复重放。不是每会话数据配额 —— 数据写入时就已落进 index.db,WAL 只是两次 checkpoint 之间的帧暂存区,会话数量/大小不会放大它;大 burst 可能暂时超出,直到下一次完成的 checkpoint 截回。调大 = truncate IO 更稀疏,但稳态磁盘占用更多、崩溃恢复重放尾更长。环境变量层(正整数)优先于配置文件层;env 值非法或非正数时静默落到文件/默认层,boot 不崩。lane 启动、store open 时生效 —— 热改动需重启。实际取值会出现在 unified-enable 日志行与 storage 诊断块中。 | @@ -333,6 +334,7 @@ | Key | Type | Default | Env | Description | |-----|------|---------|-----|-------------| | `BILI_DSH_AUTHORED_COMPACTION` | boolean | true (on, #3901 flip) | — | 让 bili 本地应答 dsh 压缩摘要请求(返回折叠快照而非拒绝,#3733):身份头 + 内核渲染格式的块摘要,零出口流量;重放经 #2432 再基线识别。 | +| `BILI_STORAGE_BACKEND` | sqlite\|mysql | sqlite | — | storage.backend 的环境变量层(#3931 第一步):sqlite(默认,唯一真实现)或 mysql(注册占位 —— 启动提示一行,第二步落地前继续用 sqlite)。优先于文件层。 | | `BILI_STORAGE_ARCHIVE_AFTER_DAYS` | integer | 365 | — | GC 年龄清扫窗口(天,#3463):闲置超过该时长的会话被归档(单文件归档日志 archive/archive.jsonl 追加一行 + 墓碑行保留标签 + 释放内容/媒体引用)。0 关闭年龄清扫;手动入口 POST /__bili/storage/gc 始终可用。配置文件键 storage.archiveAfterDays 为持久形式。 | | `BILI_SNAPSHOT_SHADOW` | boolean | true (on) | — | 快照渲染影子对账(#3756 后续):每轮已折叠会话都用引擎现算一次出站快照视图但不使用,与 legacy 实际出站比对分类,逐会话计数进 web 面板与 snapshot-shadow 诊断主题。0/false/off 关闭;1/true/on 开启;否则读配置文件 snapshot.shadow 布尔(默认开)。渲染车道本身仍受灰度开关控制(BILI_ROLLOUT_SNAPSHOT_RENDER),影子车道绝不改变出站字节 —— 它是后续翻转灰度的干跑证据。 | | `BILI_CONFIG_FILE` | string | unset (XDG config path) | — | 覆盖配置文件路径(路径重定位)。 | @@ -1783,6 +1785,7 @@ ACP 原生 agent(当前为 `pi` 扩展)会在每个进程内向代理上报 | `BILI_SQLITE_AUTO_DOWNLOAD` | `storage.sqliteAutoDownload` | true | | `BILI_STABLE_SYSTEM_ANCHOR` | `stableSystemAnchor` | false | | `BILI_STORAGE_ARCHIVE_AFTER_DAYS` | `storage.archiveAfterDays` | 365 | +| `BILI_STORAGE_BACKEND` | `storage.backend` | unset (sqlite) | | `BILI_STORAGE_JSON_WRITER` | `storage.jsonWriter` | on | | `BILI_STORAGE_UNIFIED` | `storage.unified` | unset (full) | | `BILI_STORAGE_WAL_JOURNAL_SIZE_LIMIT_BYTES` | `storage.walJournalSizeLimitBytes` | 8388608 | diff --git a/src/config.ts b/src/config.ts index b787366431..bad4fca6e1 100644 --- a/src/config.ts +++ b/src/config.ts @@ -1880,6 +1880,12 @@ type FileConfig = { * BILI_SQLITE_AUTO_DOWNLOAD wins. A cached copy is still used when * this is false — the switch gates the network fetch only. */ sqliteAutoDownload?: boolean; + /** Storage backend selection (#3931, step 1 of the #3388 pluggable + * plan): "sqlite" (default, only real implementation today) or + * "mysql" (registered stub — step 2). env BILI_STORAGE_BACKEND + * wins; a non-sqlite selection logs one notice and stays on + * sqlite until the backend ships. */ + backend?: string; /** Phase 3 (#2960): "off" stops writing the legacy JSON envelope while * storage.unified is "full" — the SQLite index becomes the only * persistent copy (reads were already unified-first; boot enumerates diff --git a/src/export.ts b/src/export.ts index f24fbbe27e..02492c45e9 100644 --- a/src/export.ts +++ b/src/export.ts @@ -3,6 +3,7 @@ import path from "node:path"; import { matchSession as matchSessionKernel, parseStoredPlaceholder, renderHandoff as renderHandoffKernel, type MessageContentStore } from "acp-kernel"; import type { Session } from "./session.js"; import { SessionStore } from "./persist.js"; +import { SqliteBackend, type StorageBackend } from "./storage/backend.js"; import { UnifiedStore } from "./storage/store.js"; interface ExportOptions { @@ -202,8 +203,11 @@ function safeJson(raw: string | null | undefined): unknown { * placeholders dereferenced to their stored originals when `full`), then * blocks ordered by ord, then dead refs. Deterministic for a given store * state; a generated artifact, never a source of truth. */ -export function renderSessionJsonlFromTables(store: UnifiedStore, sessionId: string, full: boolean, extraCcr?: ReadonlyMap): string { - const row = store.getSessionRow(sessionId); +// #3931: consumes the StorageBackend contract (not UnifiedStore) — the +// jsonl renderer is the step-1 seam proof: it runs unchanged against the +// mysql backend once that lands. +export async function renderSessionJsonlFromTables(backend: StorageBackend, sessionId: string, full: boolean, extraCcr?: ReadonlyMap): Promise { + const row = await backend.getSessionRow(sessionId); if (!row) throw new Error(`session ${sessionId} is not in the unified index`); const lines: string[] = []; lines.push( @@ -228,9 +232,9 @@ export function renderSessionJsonlFromTables(store: UnifiedStore, sessionId: str // Index entries first (fork receipts carry them); the on-disk content // store fills the gaps for normal sessions — the record itself omits the // store by design (multi-MB rewrite cost, see session.ts contentStore). - const ccr = new Map(store.getCcrEntries(sessionId).map((e) => [e.key, e.content] as const)); + const ccr = new Map((await backend.getCcrEntries(sessionId)).map((e) => [e.key, e.content] as const)); if (extraCcr) for (const [k, v] of extraCcr) if (!ccr.has(k)) ccr.set(k, v); - for (const m of store.getMessages(sessionId)) { + for (const m of await backend.getMessages(sessionId)) { let message: Record; try { message = JSON.parse(m.content) as Record; @@ -244,7 +248,7 @@ export function renderSessionJsonlFromTables(store: UnifiedStore, sessionId: str } lines.push(JSON.stringify({ type: "message", seq: m.seq, rawId: m.msgId, ref: m.ref, refNum: m.refNum ?? undefined, role: m.role, kind: m.kind ?? undefined, message })); } - for (const b of store.getBlocks(sessionId)) { + for (const b of await backend.getBlocks(sessionId)) { lines.push( JSON.stringify({ type: "block", @@ -263,7 +267,7 @@ export function renderSessionJsonlFromTables(store: UnifiedStore, sessionId: str }), ); } - const dead = store.getDeadRefs(sessionId); + const dead = await backend.getDeadRefs(sessionId); if (dead.length > 0) lines.push(JSON.stringify({ type: "deadRefs", refs: dead.map((d) => ({ ref: d.ref, refNum: d.refNum, recordedAt: d.recordedAt })) })); return `${lines.join("\n")}\n`; } @@ -354,15 +358,15 @@ export async function exportSession(selector: string | undefined, opts: ExportOp // does — index.db holds cleartext payloads, so an encrypted lane // must never read from it. try { - const unified = UnifiedStore.open(index); + const backend = new SqliteBackend(UnifiedStore.open(index)); try { - if (unified.getSessionRow(matches[0]!.id)) { + if (await backend.getSessionRow(matches[0]!.id)) { const disk = store.loadContentStore(matches[0]!); const extra = disk ? new Map(Object.entries(disk.byRef).map(([ref, e]) => [ref, disk.byHash[e.hash] ?? ""] as const)) : undefined; - return renderSessionJsonlFromTables(unified, matches[0]!.id, opts.full ?? false, extra); + return await renderSessionJsonlFromTables(backend, matches[0]!.id, opts.full ?? false, extra); } } finally { - unified.close(); + await backend.close(); } } catch (err) { process.stderr.write(`[export] unified index unreadable (${String(err)}) — falling back to the legacy-tail renderer\n`); diff --git a/src/knobs.ts b/src/knobs.ts index 40c5f0b899..89fc2f6d13 100644 --- a/src/knobs.ts +++ b/src/knobs.ts @@ -713,6 +713,11 @@ export function fileStorageArchiveAfterDays(): number | undefined { return typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : undefined; } +export function fileStorageBackend(): string | undefined { + const v = loadConfigFile().storage?.backend; + return typeof v === "string" ? v : undefined; +} + export function fileStorageWalJournalSizeLimit(): number | undefined { const v = loadConfigFile().storage?.walJournalSizeLimitBytes; return typeof v === "number" && Number.isInteger(v) && v > 0 ? v : undefined; diff --git a/src/persist.ts b/src/persist.ts index 56d4ef9130..6759f0101a 100644 --- a/src/persist.ts +++ b/src/persist.ts @@ -18,6 +18,7 @@ import { fileStorageJsonWriter, fileStorageArchiveAfterDays, fileStorageWalJournalSizeLimit, + fileStorageBackend, } from "./knobs.js"; import { log as loggerLog } from "./logger.js"; import { recordRequestedMode } from "./storage/runtime-status.js"; @@ -465,7 +466,7 @@ export class SessionStore { ? (UnifiedShadow.maybeOpen(this.sessionsDir, process.env, (rec) => { const s = buildSession(rec as PersistedSession); return toLegacyLike(s); - }, fileStorageUnified(), fileStorageWalJournalSizeLimit()) ?? undefined) + }, fileStorageUnified(), fileStorageWalJournalSizeLimit(), fileStorageBackend()) ?? undefined) : undefined; this.store = new StateStore({ dir: this.sessionsDir, diff --git a/src/storage/backend.ts b/src/storage/backend.ts new file mode 100644 index 0000000000..092cb16a78 --- /dev/null +++ b/src/storage/backend.ts @@ -0,0 +1,327 @@ +import type { SqliteEngineName } from "./driver.ts"; +import type { MessageContentStore } from "acp-kernel"; +import { UnifiedStore } from "./store.ts"; + +/** #3931 / #3388 step 1 — the storage backend contract. + * + * The seam is at the OPERATION level, not the SQL-dialect level: each backend + * implements the same set of storage operations natively, so per-backend + * transaction/atomicity semantics survive (a dialect shim cannot preserve + * `ingestSession`'s single-transaction CAS refcount discipline). The + * interface is async because network backends (MySQL, step 2) are async; + * the sqlite implementation below stays synchronous under the hood and + * `Promise.resolve`-wraps its results — the hot-path cost is one microtask. + * + * `sqlite` is the default and, in step 1, the only real implementation. + * `mysql` is a REGISTERED STUB: the name validates so configs don't bounce + * between "unknown backend" and "unimplemented backend" when step 2 lands, + * but opening it fails with one documented line, and mysql2 is never loaded. + */ + +export type { + SessionRow, + MessageRow, + BlockRow, + RefRow, + CcrEntryRow, + CheckpointRow, + SessionSummaryRow, + WebSummaryRow, + IngestSessionInput, +} from "./store.js"; +import type { + SessionRow, + MessageRow, + BlockRow, + RefRow, + CcrEntryRow, + CheckpointRow, + SessionSummaryRow, + WebSummaryRow, + IngestSessionInput, +} from "./store.js"; + +/** Everything a storage backend must provide. Mirrors the operation surface + * the product consumes (persist/shadow hot path, web lists, export, + * checkpoints/replicas, GC/archive, incremental pointers). Engine + * introspection (engine/engineSource) stays backend-internal and is + * deliberately NOT part of the contract. */ +export interface StorageBackend { + // --- ingest / session lifecycle ------------------------------------- + ingestSession( + input: IngestSessionInput, + delta?: { trustedSeq: number; boundaryMsgId: string; boundaryHash: string; trustedTailSeqs: number[] }, + opts?: { completeLog?: boolean }, + ): Promise; + sessionCounters(sessionId: string): Promise<{ requests: number; nextBlockId: number } | null>; + sessionUpdatedAt(sessionId: string): Promise; + deleteSession(sessionId: string): Promise; + listSessionIds(): Promise; + lookupConversation(namespace: string, conversationId: string): Promise; + listConversationBindings(namespace?: string): Promise<{ namespace: string; conversationId: string; sessionId: string; claimedAt: number }[]>; + + // --- reads ------------------------------------------------------------ + getSessionRow(sessionId: string): Promise; + getMessages(sessionId: string): Promise<(MessageRow & { contentHash: string })[]>; + getBlocks(sessionId: string): Promise<(BlockRow & { summaryHash: string; oneHash: string | null })[]>; + getDeadRefs(sessionId: string): Promise<{ ord: number; ref: string; refNum: number; recordedAt: number }[]>; + getRefs(sessionId: string): Promise; + getCcr(sessionId: string): Promise; + getCcrEntries(sessionId: string): Promise; + + // --- ingest watermark / pointers (#3253, #3798) ------------------------ + ingestWatermark(sessionId: string): Promise<{ seq: number; tailSeqs: number[] } | null>; + tailSeqs(sessionId: string): Promise; + clearIngestWatermark(sessionId: string): Promise; + resetAllIngestWatermarks(): Promise; + probeIngestBoundary(sessionId: string, seq: number): Promise<{ msgId: string; contentHash: string; maxSeq: number } | null>; + + // --- reap journal (#3841) ---------------------------------------------- + reapBlocks(sessionId: string, reapedIds: Set, orphanContents: Map): Promise; + + // --- archive / GC (#3463) ------------------------------------------------ + archiveSession(sessionId: string, opts: { archiveDir: string }): Promise<{ ok: boolean; exportPath?: string; reason?: string; contentRowsDeleted?: number }>; + restoreArchived(sessionId: string, opts: { archiveDir: string }): Promise<{ ok: boolean; reason?: string }>; + gc(opts: { archiveAfterDays: number; archiveDir: string; now?: number; vacuum?: "full" | "incremental" }): Promise<{ archived: number; contentRowsDeleted: number }>; + + // --- refcount introspection (GC + doctor) -------------------------------- + contentRefCountOfBody(needle: string): Promise; + mediaRefCount(bytes: string): Promise; + + // --- checkpoints / replicas (#3014) --------------------------------------- + insertCheckpoint(cp: { + cpId: string; + sessionId: string; + seqAt: number; + blockSetHash: string; + kind: "auto" | "manual" | "replica" | "fork_base"; + label?: string | null; + pinned: boolean; + createdAt: number; + stateJson: string; + }): Promise; + listCheckpoints(sessionId?: string): Promise; + getCheckpoint(cpId: string): Promise; + checkpointState(cpId: string): Promise<{ stateJson: string; byteLen: number }>; + deleteCheckpoint(cpId: string): Promise; + + // --- session_ext / kv -------------------------------------------------------- + setSessionExt(sessionId: string, key: string, value: unknown): Promise; + getSessionExt(sessionId: string, key: string): Promise; + listSessionExt(sessionId: string): Promise<{ key: string; value: unknown; updatedAt: number }[]>; + deleteSessionExt(sessionId: string, key?: string): Promise; + setKv(namespace: string, key: string, value: unknown): Promise; + getKv(namespace: string, key: string): Promise; + listKv(namespace?: string, keyPrefix?: string): Promise<{ namespace: string; key: string; value: unknown; updatedAt: number }[]>; + deleteKv(namespace: string, key?: string): Promise; + + // --- summaries / diagnostics ---------------------------------------------------- + sessionSummaries(): Promise; + webSummaryRows(): Promise; + verifyProjections(sessionId: string): Promise<{ ok: true; checks: number } | { ok: false; error: string }>; + counts(): Promise>; + contentDedupReport(): Promise<{ rows: number; bytesTotal: number; refcounted: number }>; + + close(): Promise; +} + +/** The sqlite backend: the existing UnifiedStore behind the async contract. + * Synchronous under the hood; `Promise.resolve` wrapping only. */ +export class SqliteBackend implements StorageBackend { + readonly store: UnifiedStore; + + constructor(store: UnifiedStore) { + this.store = store; + } + + static open(indexPath: string, engine?: SqliteEngineName): SqliteBackend { + return new SqliteBackend(UnifiedStore.open(indexPath, engine)); + } + + ingestSession(input: IngestSessionInput, delta?: { trustedSeq: number; boundaryMsgId: string; boundaryHash: string; trustedTailSeqs: number[] }, opts?: { completeLog?: boolean }): Promise { + return Promise.resolve(this.store.ingestSession(input, delta, opts)); + } + sessionCounters(sessionId: string): Promise<{ requests: number; nextBlockId: number } | null> { + return Promise.resolve(this.store.sessionCounters(sessionId)); + } + sessionUpdatedAt(sessionId: string): Promise { + return Promise.resolve(this.store.sessionUpdatedAt(sessionId)); + } + deleteSession(sessionId: string): Promise { + return Promise.resolve(this.store.deleteSession(sessionId)); + } + listSessionIds(): Promise { + return Promise.resolve(this.store.listSessionIds()); + } + lookupConversation(namespace: string, conversationId: string): Promise { + return Promise.resolve(this.store.lookupConversation(namespace, conversationId)); + } + listConversationBindings(namespace?: string): Promise<{ namespace: string; conversationId: string; sessionId: string; claimedAt: number }[]> { + return Promise.resolve(this.store.listConversationBindings(namespace)); + } + getSessionRow(sessionId: string): Promise { + return Promise.resolve(this.store.getSessionRow(sessionId)); + } + getMessages(sessionId: string): Promise<(MessageRow & { contentHash: string })[]> { + return Promise.resolve(this.store.getMessages(sessionId)); + } + getBlocks(sessionId: string): Promise<(BlockRow & { summaryHash: string; oneHash: string | null })[]> { + return Promise.resolve(this.store.getBlocks(sessionId)); + } + getDeadRefs(sessionId: string): Promise<{ ord: number; ref: string; refNum: number; recordedAt: number }[]> { + return Promise.resolve(this.store.getDeadRefs(sessionId)); + } + getRefs(sessionId: string): Promise { + return Promise.resolve(this.store.getRefs(sessionId)); + } + getCcr(sessionId: string): Promise { + return Promise.resolve(this.store.getCcr(sessionId)); + } + getCcrEntries(sessionId: string): Promise { + return Promise.resolve(this.store.getCcrEntries(sessionId)); + } + ingestWatermark(sessionId: string): Promise<{ seq: number; tailSeqs: number[] } | null> { + return Promise.resolve(this.store.ingestWatermark(sessionId)); + } + tailSeqs(sessionId: string): Promise { + return Promise.resolve(this.store.tailSeqs(sessionId)); + } + clearIngestWatermark(sessionId: string): Promise { + return Promise.resolve(this.store.clearIngestWatermark(sessionId)); + } + resetAllIngestWatermarks(): Promise { + return Promise.resolve(this.store.resetAllIngestWatermarks()); + } + probeIngestBoundary(sessionId: string, seq: number): Promise<{ msgId: string; contentHash: string; maxSeq: number } | null> { + return Promise.resolve(this.store.probeIngestBoundary(sessionId, seq)); + } + reapBlocks(sessionId: string, reapedIds: Set, orphanContents: Map): Promise { + return Promise.resolve(this.store.reapBlocks(sessionId, reapedIds, orphanContents)); + } + archiveSession(sessionId: string, opts: { archiveDir: string }): Promise<{ ok: boolean; exportPath?: string; reason?: string; contentRowsDeleted?: number }> { + return Promise.resolve(this.store.archiveSession(sessionId, opts)); + } + restoreArchived(sessionId: string, opts: { archiveDir: string }): Promise<{ ok: boolean; reason?: string }> { + return Promise.resolve(this.store.restoreArchived(sessionId, opts)); + } + gc(opts: { archiveAfterDays: number; archiveDir: string; now?: number; vacuum?: "full" | "incremental" }): Promise<{ archived: number; contentRowsDeleted: number }> { + return Promise.resolve(this.store.gc(opts)); + } + contentRefCountOfBody(needle: string): Promise { + return Promise.resolve(this.store.contentRefCountOfBody(needle)); + } + mediaRefCount(bytes: string): Promise { + return Promise.resolve(this.store.mediaRefCount(bytes)); + } + insertCheckpoint(cp: { + cpId: string; + sessionId: string; + seqAt: number; + blockSetHash: string; + kind: "auto" | "manual" | "replica" | "fork_base"; + label?: string | null; + pinned: boolean; + createdAt: number; + stateJson: string; + }): Promise { + return Promise.resolve(this.store.insertCheckpoint(cp)); + } + listCheckpoints(sessionId?: string): Promise { + return Promise.resolve(this.store.listCheckpoints(sessionId)); + } + getCheckpoint(cpId: string): Promise { + return Promise.resolve(this.store.getCheckpoint(cpId)); + } + checkpointState(cpId: string): Promise<{ stateJson: string; byteLen: number }> { + return Promise.resolve(this.store.checkpointState(cpId)); + } + deleteCheckpoint(cpId: string): Promise { + return Promise.resolve(this.store.deleteCheckpoint(cpId)); + } + setSessionExt(sessionId: string, key: string, value: unknown): Promise { + return Promise.resolve(this.store.setSessionExt(sessionId, key, value)); + } + getSessionExt(sessionId: string, key: string): Promise { + return Promise.resolve(this.store.getSessionExt(sessionId, key)); + } + listSessionExt(sessionId: string): Promise<{ key: string; value: unknown; updatedAt: number }[]> { + return Promise.resolve(this.store.listSessionExt(sessionId)); + } + deleteSessionExt(sessionId: string, key?: string): Promise { + return Promise.resolve(this.store.deleteSessionExt(sessionId, key)); + } + setKv(namespace: string, key: string, value: unknown): Promise { + return Promise.resolve(this.store.setKv(namespace, key, value)); + } + getKv(namespace: string, key: string): Promise { + return Promise.resolve(this.store.getKv(namespace, key)); + } + listKv(namespace?: string, keyPrefix?: string): Promise<{ namespace: string; key: string; value: unknown; updatedAt: number }[]> { + return Promise.resolve(this.store.listKv(namespace, keyPrefix)); + } + deleteKv(namespace: string, key?: string): Promise { + return Promise.resolve(this.store.deleteKv(namespace, key)); + } + sessionSummaries(): Promise { + return Promise.resolve(this.store.sessionSummaries()); + } + webSummaryRows(): Promise { + return Promise.resolve(this.store.webSummaryRows()); + } + verifyProjections(sessionId: string): Promise<{ ok: true; checks: number } | { ok: false; error: string }> { + return Promise.resolve(this.store.verifyProjections(sessionId)); + } + counts(): Promise> { + return Promise.resolve(this.store.counts()); + } + contentDedupReport(): Promise<{ rows: number; bytesTotal: number; refcounted: number }> { + return Promise.resolve(this.store.contentDedupReport()); + } + close(): Promise { + return Promise.resolve(this.store.close()); + } +} + +/** Names that validate in configuration. `mysql` validates but does not + * open — see openBackend. */ +const REGISTERED_BACKENDS = ["sqlite", "mysql"] as const; +export type RegisteredBackendName = (typeof REGISTERED_BACKENDS)[number]; + +export function listBackendNames(): string[] { + return [...REGISTERED_BACKENDS]; +} + +/** Resolves a backend by name. `mysql` throws the documented step-2 error + * (registered, not implemented — the config tier must distinguish it from + * a typo'd name); unknown names throw with the valid list. */ +export function openBackend(name: string, indexPath: string, engine?: SqliteEngineName): StorageBackend { + if (name === "sqlite") return SqliteBackend.open(indexPath, engine); + if (name === "mysql") { + throw new Error( + `[storage] backend "mysql" is registered but not implemented yet (#3388 step 2, tracked in #3931) — it ships as a built-in backend with the mysql2 client; until then the unified store runs on "sqlite"`, + ); + } + throw new Error(`[storage] unknown backend "${name}" — valid names: ${REGISTERED_BACKENDS.join(", ")}`); +} + +/** env BILI_STORAGE_BACKEND > file storage.backend > "sqlite". Unknown + * values fall back to the default (the complaint rides the selection + * notice; the hard error lives at open time for the paths that open). */ +export function resolveBackendName(env: { BILI_STORAGE_BACKEND?: string | undefined } | undefined, file: string | undefined): string { + const envRaw = env?.BILI_STORAGE_BACKEND; + const fromEnv = typeof envRaw === "string" ? envRaw.trim().toLowerCase() : ""; + if (fromEnv.length > 0) return (REGISTERED_BACKENDS as readonly string[]).includes(fromEnv) ? fromEnv : "sqlite"; + const fromFile = typeof file === "string" ? file.trim().toLowerCase() : ""; + if (fromFile.length > 0) return (REGISTERED_BACKENDS as readonly string[]).includes(fromFile) ? fromFile : "sqlite"; + return "sqlite"; +} + +/** One-line notice for non-sqlite selections (surfaced by the store's boot + * log; undefined when the selection needs no comment). */ +export function backendSelectionNotice(name: string): string | undefined { + if (name === "sqlite") return undefined; + if ((REGISTERED_BACKENDS as readonly string[]).includes(name)) { + return `[storage] storage.backend="${name}" is registered but not implemented yet (#3388 step 2) — the unified store stays on "sqlite" for now`; + } + return `[storage] storage.backend="${name}" is not a registered backend (valid: ${REGISTERED_BACKENDS.join(", ")}) — using "sqlite"`; +} diff --git a/src/storage/shadow.ts b/src/storage/shadow.ts index 9362d6399f..ce3b2fc8eb 100644 --- a/src/storage/shadow.ts +++ b/src/storage/shadow.ts @@ -26,6 +26,7 @@ import { planIngest, planIngestDelta, loadLegacyView, completeBlockContents, typ import type { BlockView } from "../session.js"; import { resolveStorageMode, resolveStorageWalJournalSizeLimit, type StorageMode } from "../knobs.ts"; import { UnifiedStore, type CheckpointRow, type SessionSummaryRow, type WebSummaryRow } from "./store.ts"; +import { resolveBackendName, backendSelectionNotice } from "./backend.ts"; import { canonicalize, sha256 } from "./canonical.ts"; import { recordSidecarInstance, recordSidecarOpenFailure } from "./runtime-status.ts"; import type { SqliteEngineName, SqliteEngineSource } from "./driver.ts"; @@ -123,10 +124,21 @@ export class UnifiedShadow { legacyLoad?: (record: unknown) => LegacySessionLike | null, fileUnified?: string, fileWalLimit?: number, + fileBackend?: string, ): UnifiedShadow | null { const mode = resolveStorageMode(env, fileUnified); if (mode === "legacy") return null; const walLimit = resolveStorageWalJournalSizeLimit(env, fileWalLimit); + // #3931: the backend seam. Step 1 keeps sqlite as the only real + // implementation; a non-sqlite selection (e.g. "mysql", step 2) + // logs ONE notice line and stays on sqlite rather than crashing + // boots — the hard error lives at openBackend() for the paths that + // open a backend directly (export). + const backendName = resolveBackendName(env, fileBackend); + if (backendName !== "sqlite") { + const notice = backendSelectionNotice(backendName); + if (notice) loggerLog("warn", notice); + } let store: UnifiedStore; try { store = UnifiedStore.open(`${dir}/index.db`, undefined, { walJournalSizeLimitBytes: walLimit }); diff --git a/tests/export-jsonl.test.ts b/tests/export-jsonl.test.ts index 46e58cfef5..ed823bf61a 100644 --- a/tests/export-jsonl.test.ts +++ b/tests/export-jsonl.test.ts @@ -6,6 +6,7 @@ import * as path from "node:path"; import { SessionStore } from "../src/persist.ts"; import { UnifiedStore } from "../src/storage/store.ts"; import { exportSession, renderSessionJsonlFromTables, renderSessionJsonlFromSession } from "../src/export.ts"; +import { SqliteBackend } from "../src/storage/backend.ts"; import { buildStoredPlaceholder } from "acp-kernel"; import type { Session } from "../src/session.ts"; @@ -76,7 +77,7 @@ test("--jsonl renders from the unified tables: header, blocks, dead refs (folded const unified = UnifiedStore.open(path.join(dir, "folded", "index.db")); try { assert.ok(unified.getSessionRow(session.id), "full mode must have ingested the session"); - const lines = parseLines(renderSessionJsonlFromTables(unified, session.id, false)); + const lines = parseLines(await renderSessionJsonlFromTables(new SqliteBackend(unified), session.id, false)); assert.equal(lines[0]!.type, "session"); assert.equal(lines[0]!.source, "unified"); assert.equal(lines[0]!.sessionId, session.id); diff --git a/tests/storage-backend-contract.test.ts b/tests/storage-backend-contract.test.ts new file mode 100644 index 0000000000..abf138e36f --- /dev/null +++ b/tests/storage-backend-contract.test.ts @@ -0,0 +1,185 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import * as fs from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { planIngest, type LegacySessionLike } from "../src/storage/ingest.ts"; +// The contract suite deliberately imports NOTHING from store.ts: every +// assertion goes through the StorageBackend interface only. When the mysql +// backend lands (#3388 step 2) this same file runs against it unchanged. +import { openBackend, listBackendNames } from "../src/storage/backend.ts"; + +/** + * #3931 (step 1 of the #3388 pluggable-storage plan): the operation-level + * backend contract. This suite is the seam proof — the registry resolves a + * backend by name and the whole storage surface (ingest, reads, session_ext, + * watermark, reap journal, archive/restore, gc, conversation lookup, delete + * with refcount release, close) is exercised through the interface. + * + * Against sqlite today the results must equal what the UnifiedStore path + * produces (pinned elsewhere by the corpus/golden suites); the point here is + * that the CONTRACT carries the operations and their semantics, so a second + * implementation has a fixed target to hit. + */ + +interface CoreMsg { id: string; role: string; contentType: string; text: string } +const mkMsg = (id: string, text: string): CoreMsg => ({ id, role: "user", contentType: "text", text }); + +const mkSession = (id: string, msgs: CoreMsg[]): LegacySessionLike => ({ + id, + createdAt: 1_000, + lastSeen: 2_000, + meta: { protocol: "openai", label: `label-${id}` }, + stats: {}, + metadata: { }, + state: { blocks: [], nextBlockId: 1, nextRunId: 1, messageRefs: { byRaw: {}, byRef: {} } }, + blockContents: new Map(), + lastMessages: msgs as unknown as LegacySessionLike["lastMessages"], + lastMessagesFolded: false, + pluginSnapshot: undefined, + contentStore: undefined, +} as unknown as LegacySessionLike); + +function scratch(): string { + return fs.mkdtempSync(path.join(os.tmpdir(), "bili-backend-contract-")); +} + +test("registry: sqlite resolves through the registry; names are advertised", async () => { + const names = listBackendNames(); + assert.ok(names.includes("sqlite"), "sqlite is a registered backend"); + assert.ok(names.includes("mysql"), "mysql is registered as a step-2 stub so config validation recognizes it"); + const dir = scratch(); + try { + const backend = openBackend("sqlite", path.join(dir, "index.db")); + await backend.close(); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test("contract: ingest → reads round-trip through the interface", async () => { + const dir = scratch(); + try { + const backend = openBackend("sqlite", path.join(dir, "index.db")); + try { + const msgs = [mkMsg("m1", "hello " + "x".repeat(200)), mkMsg("m2", "world " + "y".repeat(200))]; + await backend.ingestSession(planIngest(mkSession("sess-contract", msgs))); + + const row = await backend.getSessionRow("sess-contract"); + assert.ok(row, "session row readable via the interface"); + assert.equal(row!.sessionId, "sess-contract"); + assert.equal(row!.label, "label-sess-contract"); + + const rows = await backend.getMessages("sess-contract"); + assert.equal(rows.length, 2, "both messages landed"); + const parsed = JSON.parse(rows[1]!.content) as { id?: string }; + assert.equal(parsed.id, "m2", "message content is the verbatim core JSON"); + assert.ok(typeof rows[1]!.contentHash === "string" && rows[1]!.contentHash.length > 0, "content hashes ride the rows"); + + const counters = await backend.sessionCounters("sess-contract"); + assert.ok(counters, "session counters readable"); + + const ids = await backend.listSessionIds(); + assert.ok(ids.includes("sess-contract"), "session enumerated"); + } finally { + await backend.close(); + } + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test("contract: session_ext + watermark + tailSeqs", async () => { + const dir = scratch(); + try { + const backend = openBackend("sqlite", path.join(dir, "index.db")); + try { + await backend.ingestSession(planIngest(mkSession("sess-ext", [mkMsg("m1", "payload".repeat(60))]))); + await backend.setSessionExt("sess-ext", "inc:canonical-ptrs", [0, 1]); + assert.deepEqual(await backend.getSessionExt("sess-ext", "inc:canonical-ptrs"), [0, 1]); + const listed = await backend.listSessionExt("sess-ext"); + assert.equal(listed.filter((e) => e.key === "inc:canonical-ptrs").length, 1); + assert.equal(await backend.deleteSessionExt("sess-ext", "inc:canonical-ptrs"), 1); + // session_ext reads return undefined when the key is absent + // (verbatim store semantics — the contract keeps them). + assert.equal(await backend.getSessionExt("sess-ext", "inc:canonical-ptrs"), undefined); + + const wm = await backend.ingestWatermark("sess-ext"); + assert.ok(wm && typeof wm.seq === "number", "watermark readable"); + const tails = await backend.tailSeqs("sess-ext"); + assert.ok(Array.isArray(tails), "tailSeqs readable"); + await backend.clearIngestWatermark("sess-ext"); + assert.equal(await backend.ingestWatermark("sess-ext"), null, "clearIngestWatermark clears it"); + } finally { + await backend.close(); + } + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test("contract: reap journal orphans through the interface (#3841 semantics)", async () => { + const dir = scratch(); + try { + const backend = openBackend("sqlite", path.join(dir, "index.db")); + try { + await backend.ingestSession(planIngest(mkSession("sess-reap", [mkMsg("m1", "keep".repeat(80))]))); + const orphans = new Map([["b2", { one: null, full: { text: "orphaned summary", count: 0 } }]]); + await backend.reapBlocks("sess-reap", new Set(["b2"]), orphans); + // Idempotent: re-running the journal with the same shape is a no-op. + await backend.reapBlocks("sess-reap", new Set(["b2"]), new Map()); + } finally { + await backend.close(); + } + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test("contract: archive → restore round-trip + gc counters", async () => { + const dir = scratch(); + const archiveDir = path.join(dir, "archive"); + try { + const backend = openBackend("sqlite", path.join(dir, "index.db")); + try { + await backend.ingestSession(planIngest(mkSession("sess-gc", [mkMsg("m1", "gc target".repeat(120))]))); + const archived = await backend.archiveSession("sess-gc", { archiveDir }); + assert.ok(archived.ok && archived.exportPath, "archive ok"); + assert.ok(fs.existsSync(archived.exportPath!), "export landed on disk"); + const row = await backend.getSessionRow("sess-gc"); + assert.equal(row!.status, "archived", "tombstone keeps the row"); + const restored = await backend.restoreArchived("sess-gc", { archiveDir }); + assert.ok(restored.ok, `restore ok (${restored.reason ?? ""})`); + const back = await backend.getSessionRow("sess-gc"); + assert.equal(back!.status, "active", "restore reactivates"); + const gc = await backend.gc({ archiveAfterDays: 365, archiveDir, now: 9_000_000_000_000 }); + assert.ok(gc.archived >= 0 && gc.contentRowsDeleted >= 0, "gc returns counters"); + } finally { + await backend.close(); + } + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test("contract: conversation lookup + delete releases content refs", async () => { + const dir = scratch(); + try { + const backend = openBackend("sqlite", path.join(dir, "index.db")); + try { + const shared = mkMsg("m-shared", "shared body ".repeat(50)); + await backend.ingestSession(planIngest(mkSession("sess-del-a", [shared]))); + await backend.ingestSession(planIngest(mkSession("sess-del-b", [shared]))); + const before = await backend.contentRefCountOfBody("shared body "); + assert.ok(before >= 2, "shared content is refcounted across sessions"); + await backend.deleteSession("sess-del-a"); + const after = await backend.contentRefCountOfBody("shared body "); + assert.equal(after, before - 1, "delete releases exactly this session's refs"); + assert.equal(await backend.getSessionRow("sess-del-a"), null, "row gone"); + } finally { + await backend.close(); + } + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); diff --git a/tests/storage-backend-knob.test.ts b/tests/storage-backend-knob.test.ts new file mode 100644 index 0000000000..1565938559 --- /dev/null +++ b/tests/storage-backend-knob.test.ts @@ -0,0 +1,57 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import * as fs from "node:fs"; +import * as os from "node:os"; +import * as path from "node:path"; +import { resolveBackendName, backendSelectionNotice } from "../src/storage/backend.ts"; +import { openBackend } from "../src/storage/backend.ts"; + +/** + * #3931 (step 1): the `storage.backend` selection surface. + * + * env BILI_STORAGE_BACKEND > file storage.backend > "sqlite" + * + * `mysql` is a REGISTERED STUB — the name validates (so configs don't bounce + * between "unknown backend" and "unimplemented backend" as step 2 lands), + * but opening it fails with one documented, doctor-readable line. Step 1 + * never loads mysql2; the selection notice keeps the main store on sqlite + * with a single warn line instead of crashing boots. + */ + +test("resolveBackendName: env > file > default sqlite", () => { + assert.equal(resolveBackendName({ BILI_STORAGE_BACKEND: "mysql" }, "sqlite"), "mysql"); + assert.equal(resolveBackendName({ BILI_STORAGE_BACKEND: "sqlite" }, undefined), "sqlite"); + assert.equal(resolveBackendName(undefined, "mysql"), "mysql"); + assert.equal(resolveBackendName(undefined, undefined), "sqlite"); + assert.equal(resolveBackendName({ BILI_STORAGE_BACKEND: "" }, ""), "sqlite"); + // Unknown names fall back to the default with the notice carrying the + // complaint (validated at open time where the full error is thrown). + assert.equal(resolveBackendName({ BILI_STORAGE_BACKEND: "oracle" }, undefined), "sqlite"); +}); + +test("backendSelectionNotice: silent on sqlite, explicit everywhere else", () => { + assert.equal(backendSelectionNotice("sqlite"), undefined); + const notice = backendSelectionNotice("mysql"); + assert.ok(notice && notice.includes("mysql") && notice.includes("#3388"), "notice names the backend and the tracking issue"); + assert.ok(backendSelectionNotice("oracle")!.includes("oracle"), "unknown names also produce a notice"); +}); + +test("openBackend: sqlite opens; mysql throws the documented step-2 error; unknown lists valid names", () => { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bili-backend-knob-")); + try { + const b = openBackend("sqlite", path.join(dir, "index.db")); + b.close(); + + assert.throws(() => openBackend("mysql", path.join(dir, "index.db")), (err: unknown) => { + const msg = String((err as Error).message); + return msg.includes("mysql") && msg.includes("#3388") && msg.includes("sqlite"); + }, "mysql stub error names the backend, the issue, and the working default"); + + assert.throws(() => openBackend("oracle", path.join(dir, "index.db")), (err: unknown) => { + const msg = String((err as Error).message); + return msg.includes("oracle") && msg.includes("sqlite") && msg.includes("mysql"); + }, "unknown backend error lists the valid names"); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); diff --git a/website/config-reference/env-only.yaml b/website/config-reference/env-only.yaml index c63a37593b..895332aa7f 100644 --- a/website/config-reference/env-only.yaml +++ b/website/config-reference/env-only.yaml @@ -10,6 +10,14 @@ entries: group: envonly desc_en: "Let bili ANSWER dsh compaction summarize calls locally with the folded snapshot instead of refusing (#3733): identity header + kernel-rendered block summaries, zero egress; replay recognized via the #2432 rebase." desc_zh: "让 bili 本地应答 dsh 压缩摘要请求(返回折叠快照而非拒绝,#3733):身份头 + 内核渲染格式的块摘要,零出口流量;重放经 #2432 再基线识别。" + - key: BILI_STORAGE_BACKEND + type: "sqlite|mysql" + default: "sqlite" + kind: env-only + audience: user + group: envonly + desc_en: "Env tier for storage.backend (#3931 step 1): sqlite (default, only real backend) or mysql (registered stub - one boot notice, stays on sqlite until step 2). Wins over the file tier." + desc_zh: "storage.backend 的环境变量层(#3931 第一步):sqlite(默认,唯一真实现)或 mysql(注册占位 —— 启动提示一行,第二步落地前继续用 sqlite)。优先于文件层。" - key: BILI_STORAGE_ARCHIVE_AFTER_DAYS type: integer default: "365" diff --git a/website/config-reference/process.yaml b/website/config-reference/process.yaml index 155f4e82ee..8c004ae2ef 100644 --- a/website/config-reference/process.yaml +++ b/website/config-reference/process.yaml @@ -252,6 +252,13 @@ entries: group: process desc_en: "Tiered storage-migration switch (#2671): shadow = unified SQLite double-write dry-run with digest reconciliation; full = drop-in read path (unified-first loads with organic import, legacy fallback). Absent everywhere now defaults to FULL (#3818 flip - the shadow dry-run reconciled cleanly since #2815, so the index is the load path; JSON envelopes keep being written, and legacy remains the one-line escape hatch). File tier is strict legacy/shadow/full; the env tier also accepts 1/true (=shadow) and unified (=full) and wins over the file. Resolved once per lane boot - hot edits need a restart. Encryption (BILI_ENCRYPTION_KEY) hard-blocks the sidecar." desc_zh: "分层存储迁移开关(#2671):shadow = 统一 SQLite 双写干跑 + digest 对账;full = 平替读路径(unified-first 加载 + 有机导入 + legacy 兜底)。两处均未设置时默认 full(#3818 翻转 —— shadow 干跑自 #2815 起对账一直干净,索引因此成为默认加载路径;JSON 信封照写,legacy 仍是一行逃生口)。文件层只接受 legacy/shadow/full;环境变量层还接受 1/true(=shadow)与 unified(=full)并优先于文件。每个 lane 启动时解析一次 —— 热改动需重启生效。加密(BILI_ENCRYPTION_KEY)会硬阻断边车。" + - key: storage.backend + type: "sqlite|mysql" + default: "unset (sqlite)" + env: BILI_STORAGE_BACKEND + group: process + desc_en: "Storage backend selection, step 1 of the pluggable-storage plan (#3388 / #3931): the unified store consumes an operation-level async StorageBackend contract, with sqlite as the default and today the only real implementation (the existing UnifiedStore behind a Promise-wrapped adapter - zero behavior change, no schema change). mysql is a REGISTERED STUB: the name validates so configs do not bounce between unknown/unimplemented as the real backend ships (step 2, mysql2 client via the optional-dependency + self-download discipline), but selecting it logs one notice line at lane boot and the store stays on sqlite; paths that open a backend directly (export) fail with the documented error. Unknown names also fall back to sqlite with a notice. Resolved once per lane boot." + desc_zh: "存储后端选择,可插拔存储计划第一步(#3388 / #3931):统一存储消费操作级的异步 StorageBackend 契约,sqlite 为默认且是当前唯一真实现(现有 UnifiedStore 套一层 Promise 包装适配器 —— 零行为变化、零 schema 变化)。mysql 是已注册占位:该名字能通过校验(真实后端随第二步落地 —— mysql2 客户端,走可选依赖+自下载纪律 —— 期间配置不会在 unknown/unimplemented 之间来回弹),但选中它只会在 lane 启动时打一行提示并继续用 sqlite;直接开后端的路径(export)按文档化的错误失败。未知名字同样回退 sqlite 并提示。每个 lane 启动时解析一次。" - key: storage.sqliteAutoDownload type: boolean default: "true" From e4a15d5d5707edcafbbcf10a44eeadacf85d2e31 Mon Sep 17 00:00:00 2001 From: ranxianglei Date: Tue, 20 Oct 2026 16:23:47 +0800 Subject: [PATCH 2/4] storage: drop unused RegisteredBackendName export (unused-exports gate) --- src/storage/backend.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/src/storage/backend.ts b/src/storage/backend.ts index 092cb16a78..02a039cd0e 100644 --- a/src/storage/backend.ts +++ b/src/storage/backend.ts @@ -285,7 +285,6 @@ export class SqliteBackend implements StorageBackend { /** Names that validate in configuration. `mysql` validates but does not * open — see openBackend. */ const REGISTERED_BACKENDS = ["sqlite", "mysql"] as const; -export type RegisteredBackendName = (typeof REGISTERED_BACKENDS)[number]; export function listBackendNames(): string[] { return [...REGISTERED_BACKENDS]; From c320fc379ee09b14fcd2fcc6e4c302d236330725 Mon Sep 17 00:00:00 2001 From: awork Date: Tue, 20 Oct 2026 18:56:04 +0800 Subject: [PATCH 3/4] fix(storage): surface unknown storage.backend selections at lane boot (#3932 review) resolveBackendName collapses unregistered names to sqlite before the boot notice consults it, so a typo'd selection (env or file) fell back silently while CONFIGURATION.md promised a notice; the unknown-name branch of backendSelectionNotice was dead production code. The notice now judges the raw winning tier via selectedBackendRaw (resolveBackendName builds on it, behavior-identical), and treats "" as unset so the mapper is total over its string domain. Behavior change: unknown names log ONE warn line at boot (previously silent); effective backend unchanged (sqlite). --- src/storage/backend.ts | 20 ++++++++++++++------ src/storage/shadow.ts | 10 ++++++---- tests/storage-backend-knob.test.ts | 11 ++++++++++- 3 files changed, 30 insertions(+), 11 deletions(-) diff --git a/src/storage/backend.ts b/src/storage/backend.ts index 02a039cd0e..0f0cf42e4c 100644 --- a/src/storage/backend.ts +++ b/src/storage/backend.ts @@ -303,22 +303,30 @@ export function openBackend(name: string, indexPath: string, engine?: SqliteEngi throw new Error(`[storage] unknown backend "${name}" — valid names: ${REGISTERED_BACKENDS.join(", ")}`); } +/** The winning tier's raw value before validation ("" when neither tier set + * anything). Callers that judge the SELECTION (boot notices, export's open + * gate) use this — by the time resolveBackendName returns, unknown names + * are already collapsed to sqlite and invisible to it. */ +export function selectedBackendRaw(env: { BILI_STORAGE_BACKEND?: string | undefined } | undefined, file: string | undefined): string { + const envRaw = env?.BILI_STORAGE_BACKEND; + const fromEnv = typeof envRaw === "string" ? envRaw.trim().toLowerCase() : ""; + if (fromEnv.length > 0) return fromEnv; + return typeof file === "string" ? file.trim().toLowerCase() : ""; +} + /** env BILI_STORAGE_BACKEND > file storage.backend > "sqlite". Unknown * values fall back to the default (the complaint rides the selection * notice; the hard error lives at open time for the paths that open). */ export function resolveBackendName(env: { BILI_STORAGE_BACKEND?: string | undefined } | undefined, file: string | undefined): string { - const envRaw = env?.BILI_STORAGE_BACKEND; - const fromEnv = typeof envRaw === "string" ? envRaw.trim().toLowerCase() : ""; - if (fromEnv.length > 0) return (REGISTERED_BACKENDS as readonly string[]).includes(fromEnv) ? fromEnv : "sqlite"; - const fromFile = typeof file === "string" ? file.trim().toLowerCase() : ""; - if (fromFile.length > 0) return (REGISTERED_BACKENDS as readonly string[]).includes(fromFile) ? fromFile : "sqlite"; + const raw = selectedBackendRaw(env, file); + if (raw.length > 0) return (REGISTERED_BACKENDS as readonly string[]).includes(raw) ? raw : "sqlite"; return "sqlite"; } /** One-line notice for non-sqlite selections (surfaced by the store's boot * log; undefined when the selection needs no comment). */ export function backendSelectionNotice(name: string): string | undefined { - if (name === "sqlite") return undefined; + if (!name || name === "sqlite") return undefined; if ((REGISTERED_BACKENDS as readonly string[]).includes(name)) { return `[storage] storage.backend="${name}" is registered but not implemented yet (#3388 step 2) — the unified store stays on "sqlite" for now`; } diff --git a/src/storage/shadow.ts b/src/storage/shadow.ts index ce3b2fc8eb..b3f50449f2 100644 --- a/src/storage/shadow.ts +++ b/src/storage/shadow.ts @@ -26,7 +26,7 @@ import { planIngest, planIngestDelta, loadLegacyView, completeBlockContents, typ import type { BlockView } from "../session.js"; import { resolveStorageMode, resolveStorageWalJournalSizeLimit, type StorageMode } from "../knobs.ts"; import { UnifiedStore, type CheckpointRow, type SessionSummaryRow, type WebSummaryRow } from "./store.ts"; -import { resolveBackendName, backendSelectionNotice } from "./backend.ts"; +import { backendSelectionNotice, selectedBackendRaw } from "./backend.ts"; import { canonicalize, sha256 } from "./canonical.ts"; import { recordSidecarInstance, recordSidecarOpenFailure } from "./runtime-status.ts"; import type { SqliteEngineName, SqliteEngineSource } from "./driver.ts"; @@ -134,9 +134,11 @@ export class UnifiedShadow { // logs ONE notice line and stays on sqlite rather than crashing // boots — the hard error lives at openBackend() for the paths that // open a backend directly (export). - const backendName = resolveBackendName(env, fileBackend); - if (backendName !== "sqlite") { - const notice = backendSelectionNotice(backendName); + // The notice judges the RAW selection (#3932 review): resolveBackendName's + // output would have collapsed typo'd names to sqlite and silenced them. + const selected = selectedBackendRaw(env, fileBackend); + if (selected && selected !== "sqlite") { + const notice = backendSelectionNotice(selected); if (notice) loggerLog("warn", notice); } let store: UnifiedStore; diff --git a/tests/storage-backend-knob.test.ts b/tests/storage-backend-knob.test.ts index 1565938559..971c1478d8 100644 --- a/tests/storage-backend-knob.test.ts +++ b/tests/storage-backend-knob.test.ts @@ -3,7 +3,7 @@ import assert from "node:assert/strict"; import * as fs from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; -import { resolveBackendName, backendSelectionNotice } from "../src/storage/backend.ts"; +import { resolveBackendName, backendSelectionNotice, selectedBackendRaw } from "../src/storage/backend.ts"; import { openBackend } from "../src/storage/backend.ts"; /** @@ -55,3 +55,12 @@ test("openBackend: sqlite opens; mysql throws the documented step-2 error; unkno fs.rmSync(dir, { recursive: true, force: true }); } }); + +test("lane-boot notice composition: the RAW selection decides — typo'd names are NOT silent (#3932 review)", () => { + const unknown = backendSelectionNotice(selectedBackendRaw({ BILI_STORAGE_BACKEND: "oracle" }, undefined)); + assert.ok(unknown && unknown.includes("oracle") && unknown.includes("valid"), "an unknown env selection surfaces the unknown-name notice"); + const stub = backendSelectionNotice(selectedBackendRaw(undefined, "MySQL")); + assert.ok(stub && stub.includes("mysql") && stub.includes("#3388"), "file 'MySQL' normalizes into the registered-stub notice"); + assert.equal(backendSelectionNotice(selectedBackendRaw(undefined, undefined)), undefined, "no selection stays silent"); + assert.equal(backendSelectionNotice(selectedBackendRaw({ BILI_STORAGE_BACKEND: " SQLITE " }, "mysql")), undefined, "env wins over file; normalized sqlite stays silent"); +}); From 5d665fabed4459c2130e7349b29433bc7602cfba Mon Sep 17 00:00:00 2001 From: awork Date: Tue, 20 Oct 2026 18:56:04 +0800 Subject: [PATCH 4/4] fix(storage): enforce storage.backend selection at export open time (#3932 review) The --jsonl path hardcoded new SqliteBackend(UnifiedStore.open(index)), so a deliberate mysql selection silently exported from sqlite instead of failing with the documented stub error that CONFIGURATION.md and #3931 promise. The selection is now enforced before the guarded open: registered-but-unshipped names go through openBackend and throw their documented line before any file access; typo'd names warn once and read sqlite. The guarded try/catch is untouched, so the corrupt-index legacy-tail degrade contract (#2690) on the sqlite path is byte-for-byte preserved. --- src/export.ts | 19 ++++++++++++++++--- tests/export-jsonl.test.ts | 27 +++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 3 deletions(-) diff --git a/src/export.ts b/src/export.ts index 02492c45e9..1dfa5fa280 100644 --- a/src/export.ts +++ b/src/export.ts @@ -3,8 +3,8 @@ import path from "node:path"; import { matchSession as matchSessionKernel, parseStoredPlaceholder, renderHandoff as renderHandoffKernel, type MessageContentStore } from "acp-kernel"; import type { Session } from "./session.js"; import { SessionStore } from "./persist.js"; -import { SqliteBackend, type StorageBackend } from "./storage/backend.js"; -import { UnifiedStore } from "./storage/store.js"; +import { backendSelectionNotice, listBackendNames, openBackend, selectedBackendRaw, type StorageBackend } from "./storage/backend.js"; +import { fileStorageBackend } from "./knobs.js"; interface ExportOptions { dir?: string; @@ -352,13 +352,26 @@ export async function exportSession(selector: string | undefined, opts: ExportOp const index = path.join(store.dir, "index.db"); const encrypted = process.env.BILI_ENCRYPTION_KEY !== undefined && process.env.BILI_ENCRYPTION_KEY !== ""; if (existsSync(index) && !encrypted) { + // #3931: the selection is enforced at open time, mirroring the lane-boot + // split — a registered-but-unshipped choice (mysql, step 2) fails here + // with its documented backend error before any file access, so a deliberate + // selection never silently reads sqlite; a typo'd name warns once and reads sqlite. + const selected = selectedBackendRaw(process.env, fileStorageBackend()); + if (selected && selected !== "sqlite") { + if (listBackendNames().includes(selected)) { + openBackend(selected, index); + } else { + const notice = backendSelectionNotice(selected); + if (notice) process.stderr.write(`[export] ${notice}\n`); + } + } // Guarded open: a corrupt/foreign index.db must degrade to the // legacy-tail renderer, not fail the export (#2690 review notes). // Encryption gates the read for the same reason the ingest side // does — index.db holds cleartext payloads, so an encrypted lane // must never read from it. try { - const backend = new SqliteBackend(UnifiedStore.open(index)); + const backend = openBackend("sqlite", index); try { if (await backend.getSessionRow(matches[0]!.id)) { const disk = store.loadContentStore(matches[0]!); diff --git a/tests/export-jsonl.test.ts b/tests/export-jsonl.test.ts index ed823bf61a..2a124cf3b9 100644 --- a/tests/export-jsonl.test.ts +++ b/tests/export-jsonl.test.ts @@ -169,3 +169,30 @@ test("renderSessionJsonlFromSession dereferences via an injected content store", const msg = lines.find((l) => l.type === "message") as { message: { text: string } }; assert.equal(msg.message.text, "hello"); }); + +test("--jsonl enforces the backend selection at open time: the mysql stub fails with its documented error (#3932 review)", async () => { + await withMode("full", async () => { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), "bili-jsonl-backend-")); + process.env.BILI_STORAGE_BACKEND = "mysql"; + try { + const session = await loadCorpusCase(dir, "folded", "corpus-folded", "anthropic"); + const store = new SessionStore({ dir: path.join(dir, "folded"), debounceMs: 1, enabled: true }); + await store.writeNow(session); + await store.flushAll(); // closes the unified handle (Windows: an open index.db blocks rmSync) + store.cancelAll(); + assert.ok(fs.existsSync(path.join(dir, "folded", "index.db")), "full-mode corpus ingest must leave index.db behind"); + + await assert.rejects( + () => exportSession(session.id, { dir: path.join(dir, "folded"), jsonl: true }), + (err: unknown) => { + const msg = String((err as Error).message); + return msg.includes("mysql") && msg.includes("#3388"); + }, + "a deliberate mysql selection must fail at open time, not silently read sqlite", + ); + } finally { + delete process.env.BILI_STORAGE_BACKEND; + try { fs.rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); } catch { /* Windows: an ephemeral stray handle must not fail CI */ } + } + }); +});