ADR-0062 D1 收尾:`default` driver 的 connect 与失败判决仍是第二份实现(阻塞点已定位)

[os-zhuang]

一句话说明

ADR-0062 D1 要求「exactly one definition → live driver code path」。构造那一半已经收敛(standalone-stack 走共享的 createDefaultDatasourceDriverFactory),但 connect 与连接失败判决那一半没有:default driver 被包成 DriverPlugin 在引擎前注册,它的 connect() 发生在 ObjectQLEngine.init();声明式 datasource 的 connect() 发生在 DatasourceConnectionService。于是「连不上该怎么办」这个决定有两份独立实现。

事实核实

packages/runtime/src/standalone-stack.ts:168-245 的注释自己划了这条线:

用户可见的四种 kind 走 SHARED datasource driver factory(ADR-0062)…… This stack still owns what's standalone-specific: URL→config translation, filesystem prep (mkdir), and DriverPlugin registration (pre-engine — unchanged).

两条路径:

	default	声明式 datasource
构造	createDefaultDatasourceDriverFactory().create() ✅ 共享	同上 ✅
注册	new DriverPlugin(driver),引擎 init 前	engine.registerDriver(),在 connect() 内
connect	ObjectQLEngine.init()(engine.ts:1924)	DatasourceConnectionService.connect()
失败判决	DriverConnectError + 聚合(#3741)	handleFailure()(datasource-connection-service.ts:385)
逃生阀	OS_ALLOW_DRIVER_CONNECT_FAILURE	同一个(#3816 起)

#3816 之后两边的行为已经对齐了(同一判据方向、同一旗标、同一 emitDegradedBootBanner),但那是靠两处代码各自写对来维持的一致,不是结构上的一致。

影响

不是当下的 bug,是结构性漂移风险:任何一次对连接失败策略的改动都要记得改两个地方。这次 #3758 就是活例子 —— #3741 在 init() 那层修了,DatasourceConnectionService 那层的边界原封不动地留了三个月,直到有人再报一次。第三次改动没有理由更幸运。

同样分叉的还有:pool 生命周期(D5 说 DatasourceConnectionService owns connect/disconnect,但 default 的 disconnect 走 DriverPlugin/kernel shutdown)、连接策略(DatasourceConnectPolicy 完全看不到 default)。

建议处置

按 ADR-0062 D1 的原计划把 default 收敛到 DatasourceConnectionService。ADR 自己标注了这是风险最高的一步(§Risk:"Phase 1's default-driver refactor is the riskiest single step (the hot boot path for all apps) — mitigated by landing auto-connect for declared datasources first, refactoring default onto the shared service last, behind the dogfood gate")。前置条件现在都满足了:声明式 auto-connect 已上线并有 dogfood gate 覆盖,失败策略也已在两边对齐 —— 意味着这次重构是纯搬迁,不带行为变更,是它风险最低的时刻。

需要一并想清楚的:

• 注册时机。default 目前是引擎 init 之前注册(DriverPlugin),声明式 datasource 是 AppPlugin.start() 里。default 必须在 schema sync 之前就位,不能简单挪到 start()。
• DriverPlugin 是否保留。它还承担 --fresh / 测试注入的口子,不宜直接删。
• DatasourceConnectPolicy 要不要看到 default。倾向不要 —— policy 是给多租户 host 做 egress 隔离的,主库不在它管辖范围内;但这需要写进 ADR 而不是靠默认行为。

关联

• ADR-0062 D1 / D5、§Risk
• ObjectQLEngine.init() 吞掉 driver 连接失败：连不上数据库的服务器照常启动，driver 的启动期致命错误被降级成运行时报错 #3741 / feat(objectql)!: refuse to boot when a data driver fails to connect (#3741) #3751(引擎层)、显式绑定的 datasource 连不上只降级成一条 warning：绑上去的对象在启动后全废，直到查询时才炸 #3758 / fix(datasource): an explicitly-bound datasource that cannot connect refuses the boot (#3758) #3816(连接服务层)
• Prime Directive [WIP] Fix error in step four of the action run #5(不要临时补丁)、chore: version packages #10

[os-zhuang]

#3836 已合并,但只做了守卫,本 issue 保持 open。读代码后有两处需要修正我原帖的判断:

① 阻塞点不是启动顺序。 原帖担心「default 必须在 schema sync 之前就位,不能简单挪到 start()」。实测:kernel 的 init-all→start-all 保证 DatasourceAdminServicePlugin.init() 注册的连接服务在 ObjectQLPlugin.start() 时已存在,而 default 的发现 + ql.init() + schema sync 全都发生在那个 start() 里。时机是有的。

② 真正的阻塞是输入形态不匹配 + 分层反转。

• DatasourceConnectionService.connect() 接收一个 datasource 定义并通过 factory 构建 driver;而 default 是以已构建的 driver 实例、经 DriverPlugin 发布成 driver.* kernel service 的形式到达的。没有「adopt 一个现成 driver」的入口。
• 让 default 走连接服务,会使 ObjectQLPlugin 的启动依赖 service-datasource —— 一个上层的、可选的 service。为每个 app 都需要的那一个 driver 反转分层,代价不小。

所以出路是二选一,都是设计决策而非机械搬迁:给连接服务加 adoptDriver() 接缝,或者把 standalone 的 default 变成一个真正的 declared datasource 定义。配合 §Risk 标注的「风险最高的一步」,不适合顺手做掉。

本次落地的部分:

• packages/runtime/src/degraded-boot-parity.test.ts —— 把两条路径钉在同一份运维可见契约上:默认 fail-fast、OS_ALLOW_DRIVER_CONNECT_FAILURE 解析逐值一致(含 'YES' / ' True ' / 'off' 等边界)、DEGRADED BOOT 都上 stderr。放在 runtime 是因为它是唯一同时依赖两边的包。ObjectQLEngine.init() 吞掉 driver 连接失败：连不上数据库的服务器照常启动，driver 的启动期致命错误被降级成运行时报错 #3741 → 显式绑定的 datasource 连不上只降级成一条 warning：绑上去的对象在启动后全废，直到查询时才炸 #3758 就是漏改一边、代价三个月加第二份 bug report;下次由 CI 发现。
• ADR-0062 补了一段 status correction,并把 header 从 D1–D8 implemented 更正为 D1 partially implemented —— 它此前一直在高估自己。分叉的完整清单(register / connect / 失败判决 / pool teardown / connect policy)也一并列进去了。

剩余工作 = 上面的二选一。

---

Generated by Claude Code

[os-zhuang]

#3869 已合并:standalone/artifact 路径的 default 现在是 declared definition,经共享 DatasourceConnectionService 连接(方案 B 主体完成)。真机对照验证:dev:crm --fresh 与未修改 main 逐表一致(71 = 71)。

落地过程中有一个值得记录的教训:kernel 的 init/start 顺序按依赖拓扑解析,不是注册顺序(resolveDependencies)。第一版把 connect 放在 start() 靠列表位置排序 —— 单测/集成测试全绿,但 serve 全量 boot 里 ObjectQL 被服务插件的依赖边提前,schema sync 跑在 driver 注册之前,起出来的服务器只有 10 张表。修法是 connect 进 init()(Phase 1 全部完成才进 Phase 2)+ 对 ObjectQL 声明硬依赖。做剩余收敛时请直接从这个形态出发。

本 issue 剩余两处第二实现:

1. CLI serve 的 config-load fallback(serve.ts 的 createStorageDriver + DriverPlugin,host objectstack.config.ts 未带 driver plugin 时走它)。两个耦合点要先解:mysql / turso 两种 kind 不在共享 factory 里(turso 属 cloud 发行);telemetry sibling-datasource 的供给读的是 createStorageDriver 的解析结果(sqliteFilePath / resolved engine),声明化后这些信息在 connect 之前不存在,需要改为从连接服务的结果回读。
2. cloud-stack 的自组路径(cloud 仓库,cloud-stack.ts)。

在两者收敛前,degraded-boot-parity.test.ts 继续作为两条 connect 路径的漂移守卫。

---

Generated by Claude Code

[os-zhuang]

收尾两个 PR,余项(cloud 侧)已落地:

#3968(已合并,main c3bcb42)— 接缝 + 欠账清理。 cloud 组装收敛卡在两个结构性事实上:driver kind 在开源之外(turso),以及实例池化超出单个 kernel(control driver 兼任每个环境 kernel 的 proxy 基座;每环境 driver 跨 kernel 重建缓存)——按定义重建会成倍开 pool,所以「二选一」里的 adopt 方案以 factory 形态落地:DefaultDatasourcePlugin 接受注入的 IDatasourceDriverFactory(缺省共享 factory,不传时行为逐字节不变),createPrebuiltDriverFactory 把现成实例包成 factory —— create() 每次返回同一实例,构造/池化归 host,connect 编排与判决保持唯一实现。同 PR 补上:verify dogfood harness 改走 declared default(§Risk 承诺的 "behind the dogfood gate" 至此才真覆盖收敛路径)、ADR-0062 header 修正(#3836 时它高估自己,#3869/#3886 后又变成低估)、parity guard 注释重写、drivers.mdx 过时的 "the same path the CLI uses internally"。

cloud#915(已开,含 pin bump,CI 绿即可合)— 三个组装点收敛。 control-plane preset step 3、artifact-kernel-factory(objectos 每租户主库,生产热路径——比 issue 原点名的 cloud-stack 更要紧的那一个)、DefaultEnvironmentKernelFactory 两条路径,全部改为 DefaultDatasourcePlugin + prebuilt 收养。新增 preset boot 回归套件钉死:收养身份(引擎 default 是 buildControlDriver 那个实例)、driver.* 探测 service 仍发布、判决收敛(fail-fast 默认 + 同一逃生阀 + 同一 DEGRADED BOOT banner 从 cloud 控制面发出)。objectos-runtime 240、service-cloud 817 全绿。

残留的 DriverPlugin 使用全部归入文档化的命名辅助/逃生舱类,与 telemetry sibling 同构,不再有 default 路径的第二实现:proxy cloud datasource(registerAsDefault:false)、objectos host 路由 shell、artifact 工厂旁挂的 'cloud' 别名 metadata 注册、测试注入。

degraded-boot-parity.test.ts 保留:engine 侧判决仍是活代码(boot 再验证 + 逃生舱 driver),只要 init() 还能抛 connect 判决,它就必须与 service 判决一致——守卫的对象从「未收敛的第二实现」变为「逃生舱不漂移」。

cloud#915 合并后本 issue 随之关闭(PR 带 Closes)。

---

Generated by Claude Code