fix(storage): load node:sqlite through one lazy, quiet seam

[childrentime]

⚠️ 这是提到个人 fork 的 review 用 PR，不提交上游。正文用中文写，方便逐条核对。

一句话

maka --help 从不打开数据库，却每次都往 stderr 打一行 Node 的 SQLite 实验特性警告。这个 PR 把 node:sqlite 的加载收敛成唯一入口，顺手补回被删掉的守门测试。

现象

$ maka --help
(node:58372) ExperimentalWarning: SQLite is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

--version、run、TUI 启动，每一条路径都会打。这不是新问题——apache#1257 报过，apache#1258 修过，后来又坏回去了。

为什么会坏

有两个独立的原因，只修一个警告还在。

原因一：静态导入又回到 barrel 里了

Node 的规则是：builtin 模块一旦进入模块图就立刻求值。所以下面这一行本身就等于"加载 SQLite"，跟你有没有真的建数据库无关：

import { DatabaseSync } from 'node:sqlite';   // ← 求值发生在这里

三个文件是这么写的，而它们都能被 @maka/storage 的 barrel（index.ts 的 export *）触达：

• operational-state-backup.ts
• session-bundle-policy.ts
• operational-target-schema.ts

而 packages/cli/src/cli-core.ts 在启动时静态导入了这个 barrel（为了拿 resolveMakaDataRoots）。链条就闭合了：启动 CLI → 导入 barrel → 求值 node:sqlite → 打警告，哪怕这次执行的是 --help。

注意区分：仓库里还有几十处 import type { DatabaseSync }，那些是类型导入，编译后完全消失，一点问题没有。只有不带 type 的值导入才会触发。

原因二：抑制逻辑只覆盖了五分之二

光惰性加载治不了真实会话——maka run 是真的要打开 runtime.sqlite 的，那一刻警告照样会打。项目里其实已经有对策：临时把 process.emitWarning 换成一个过滤版，加载完再换回来。

问题是这段十几行的代码只在两个文件里有，而且是一字不差的两份拷贝：

• ✅ operational-state-store.ts
• ✅ sqlite-session-metadata-store.ts
• ❌ sqlite-runtime-store.ts（只惰性，不抑制）
• ❌ sqlite-long-term-memory-store.ts（只惰性，不抑制）
• ❌ managed-dependency-environment.ts（内联 require）
• ❌ foreign-session-store.ts（await import）
• ❌ codex-session-adapter.ts（await import）

谁先加载谁漏警告，等于抑制形同虚设。

改了什么

1. 新增 packages/storage/src/sqlite-module.ts（48 行）

整个包加载 node:sqlite 的唯一入口，三件事：

• 惰性：用 createRequire 在函数体里 require，而不是模块顶层 import，所以只有真要用时才求值。
• 静音：加载期间临时替换 process.emitWarning，只吞掉 ExperimentalWarning 且正文以 SQLite is an experimental feature 开头的那一条。用 try/finally 保证一定换回来。Deprecation 和其它任何警告完全不受影响。
• 记忆化：cached 变量存住结果，避免重复的 emitWarning 换进换出。（require 自己有模块缓存，这层是省开销，不是保证正确性——你觉得多余可以砍掉。）

对外导出两个函数：loadSqliteModule() 拿整个模块（有的调用点要用里面的 backup），loadDatabaseSync() 拿构造器。

2. 三个静态导入改成类型导入 + 运行期加载

以 operational-state-backup.ts 为例：

-import { DatabaseSync } from 'node:sqlite';
+import type { DatabaseSync } from 'node:sqlite';
+import { loadDatabaseSync } from './sqlite-module.js';

-    const database = new DatabaseSync(path, { readOnly: true });
+    const database = new (loadDatabaseSync())(path, { readOnly: true });

import type 编译后消失，类型标注照常可用；真正要建数据库的那一行才去加载。session-bundle-policy.ts 和 operational-target-schema.ts 同样处理。

3. 四个本地加载函数删掉，改用共享的

operational-state-store.ts 和 sqlite-session-metadata-store.ts 里那两份重复的抑制块整段删除（各减 20 多行），连带删掉只为它服务的 createRequire 引入。sqlite-runtime-store.ts、sqlite-long-term-memory-store.ts 里只惰性不抑制的版本也一并换掉。调用点名字没变（loadDatabaseSync() / loadSqliteModule()），所以函数体以下的代码一行没动。

4. 三个零散加载点收编

managed-dependency-environment.ts 的内联 require('node:sqlite')，以及 foreign-session-store.ts / codex-session-adapter.ts 的 await import('node:sqlite')，都换成共享入口。后两个原本就是惰性的，改动是为了让它们也享受到静音——语义等价，只是把 async 边界去掉了（加载时机不变）。

5. 恢复并加固回归测试

packages/storage/src/__tests__/package-import.test.ts 在 apache#2710 的批量删测试里被清掉了，之后静态导入才敢一路溜进发布版。这里恢复，并从 1 条断言扩到 3 条：

断言	覆盖什么
导入包入口后 stderr 为空	apache#1257 的原始守门条件
构造一个 SQLite store 后 stderr 为空	惰性加载覆盖不到的场景——真实会话就走这条
dist/ 里没有任何模块带静态 node:sqlite 说明符	编译后 import type 已被抹掉，剩下的必然是值加载

第三条是我认为最有价值的：apache#1994 落地当天就会被它拦下来。原来那条只盯 barrel，管不到"哪个文件把它拖进来的"。

没改什么

packages/eval/src/maka-artifacts.ts 也有一处静态导入，故意留着。@maka/eval 不依赖 @maka/storage，接过去要新增跨包依赖；而且它只在 maka eval 时加载，不在 CLI 启动路径上，跟本 PR 要修的问题无关。该单独一个 PR。

退化时间线

日期	提交	干了什么
07-20	apache#1258	修好 apache#1257，加上 package-import.test.ts
08-03	apache#1994	给两个 barrel 可达模块加了静态导入
08-11	apache#2710	删掉 package-import.test.ts
08-13	apache#2445	又加了第三个静态导入

验证

Node v24.11.1，macOS arm64。

检查	结果
maka --help（已发布 0.1.0-beta.1）	exit 0，stderr 169 字节
maka --help（本分支）	exit 0，stderr 0 字节
await import('@maka/storage') 改前 / 改后	有警告 / 静默
npm test --workspace @maka/storage	854 条，840 通过，14 跳过，0 失败
npm run typecheck --workspace @maka/storage	通过
npm run lint	通过，扫了 2455 个文件
npm run build	通过

有一项没跑成，如实说明：本想再跑一次真实的 maka run 验证运行期也安静，但 dev build 起的 Runtime Host 和机器上已安装的 beta 版起的那个撞了，卡住没出结果，中止了。不过这个场景已被上表第二条测试（构造 store 后 stderr 为空）覆盖，结论不受影响。

生成式工具声明

Claude Code（Claude Opus 5）做出了实质贡献：定位退化、编写改动与测试、起草本说明。提交带 Generated-by: Claude Code trailer。

human contributor of record 的 review 尚未完成——本 PR 正是为此而开。

[childrentime]

方案作废：改用彻底删除 barrel 的做法，见新 PR。惰性加载 + emitWarning 猴子补丁属于过度设计，被 review 否掉了。