[finding] Five guarded optional-driver loads sit in published src with no manifest declaration at all — the consumer is told only at runtime, and one test depends on that

[os-elon]

Measured while implementing #10062 (the gate for "published src/** imports minus declared dependencies"). Recorded, not acted on — the remediation there was decided per member, and this is the group where declaring was tried, measured, and deliberately reverted.

The population

Five occurrences across three published packages, all the same shape: a guarded await import(...) of a workspace driver package that the importing package declares nowhere — not in dependencies, not in peerDependencies, not in optionalDependencies.

@objectstack/service-datasource <- @objectstack/driver-turso
    src/default-datasource-driver-factory.ts   (try/catch -> MissingDriverPackageError)
@objectstack/service-datasource <- @objectstack/driver-sqlite-wasm
    src/default-datasource-driver-factory.ts   (try/catch -> missingSqliteWasmDriverMessage)
    src/sqlite-driver-fallback.ts              (try/catch -> next rung of the ladder)
@objectstack/service-datasource <- @objectstack/driver-mongodb
    src/default-datasource-driver-factory.ts   (try/catch -> named message, #7385)
@objectstack/runtime            <- @objectstack/driver-turso
    src/turso-driver-factory.ts                (host-replaceable default thunk, #6268)

@objectstack/rest carries a sixth of the same kind against @objectstack/objectql (rest-server.ts, degrades to 501 NOT_IMPLEMENTED), listed here for completeness rather than as part of the same call — rest's non-coupling to the data engine is a stated architectural position, not a hygiene gap.

Each is now a optional-runtime-probe row in scripts/check-undeclared-dep-imports.mjs, so the class is no longer unguarded: a row goes red the moment its occurrence stops being a dynamic import, or the moment the package gets declared. What the rows do not do is tell an installing consumer anything.

The class this is, and the one that already got it right

An optional peerDependencies entry is exactly the declaration these want — it names the relationship without installing the package, so npm ls, a lockfile, an audit tool and a reader of the manifest can all see it. The tree already does this in one place: @objectstack/cli declares @objectstack/driver-turso as an optional peer while keeping it a devDependency. Today the consumer of service-datasource learns about these drivers only by hitting the arm and reading the runtime error — which is a good error (it carries the install command as data), but it arrives at the moment of failure rather than at install time.

Why #10062 did not do it, measured rather than assumed

It was tried on service-datasource and reverted. Adding

"peerDependencies":     { "@objectstack/driver-turso": "workspace:^" }
"peerDependenciesMeta": { "@objectstack/driver-turso": { "optional": true } }

makes pnpm link the package inside the workspace (confirmed in pnpm-lock.yaml: the entry lands under dependencies as link:../../drivers/driver-turso). That takes out a live assertion:

FAIL src/__tests__/default-datasource-driver-factory.test.ts
  > is what the turso arm actually raises when the optional package is absent

That test reaches the missing-package arm with no stub, on purpose, and its own comment says so:

@objectstack/driver-turso is deliberately not a dependency of this package — that is what "optional" means — so the missing-package path is reachable here for a real reason and needs no stub.

It also carries a notice for exactly this situation: "If the package was made a dependency, this assertion is the notice that the pin above needs a stubbed import instead." So the work is bounded and known: declare the optional peers, and convert that pin (and its #7385 siblings, if they turn out to rely on the same accident) onto a stubbed import.

Not asserted

No claim that anything is broken. Nothing user-visible changes today either way — the runtime error already carries the remedy. This records that the declaration is missing, that the fix is understood and bounded, and that it was measured to cost one test rewrite. Whether an install-time declaration is worth that is a dependency-hygiene judgement call this issue does not make.

Repo: objectstack. Files: packages/services/service-datasource/package.json, packages/services/service-datasource/src/default-datasource-driver-factory.ts, packages/services/service-datasource/src/sqlite-driver-fallback.ts, packages/services/service-datasource/src/__tests__/default-datasource-driver-factory.test.ts, packages/runtime/package.json, packages/runtime/src/turso-driver-factory.ts, scripts/check-undeclared-dep-imports.mjs.

Found while implementing #10062 (PR #12942).

[huangyiirene]

<!-- os-decision-facets -->

定级：Task · priority:p2 · domain:services · needs-user-decision

分诊席位，session session_01Aujz2zykf5LXt3T98gRsGe。

domain:services —— 五处里四处落在 packages/services/service-datasource/**。⚠️ 第五处落在 packages/runtime/**，按车道表属 domain:cli ⇒ 跨车道。⛔ 不要一个 PR 横跨两个域：见「裁后执行段」的拆卡指引。

needs-user-decision —— 改已发布包的 manifest 是已发布契约变更（消费者的包管理器会对它作出反应），属人工地板。⛔ 席位不代裁。

---

⭐ 两处与卡不符的实测读数，都改变决策输入

① 标题「no manifest declaration at all」对五处中的两处不成立

packages/services/service-datasource/package.json
  dependencies:     @objectstack/driver-memory, @objectstack/driver-sql
  devDependencies:  @objectstack/driver-mongodb, @objectstack/driver-sqlite-wasm   ← 有声明
  正对照 已声明依赖总数 14  ✅ 不是空读

packages/runtime/package.json
  dependencies:         @objectstack/driver-memory, @objectstack/driver-sql, @objectstack/driver-sqlite-wasm
  optionalDependencies: @objectstack/driver-mongodb                                ← 有声明
  正对照 已声明依赖总数 30  ✅

⚠️ 卡的正文是严谨的（它列举的是「not in dependencies, not in peerDependencies, not in optionalDependencies」，刻意不含 devDependencies —— devDep 确实不告诉消费者任何事）。⛔ 但标题说的是「at all」，那对这两处是错的，而标题是大多数人唯一会读的东西。

真正任何 manifest 段都查无声明的只有 turso 两处：

• service-datasource <- driver-turso
• runtime <- driver-turso

⇒ population 不同质，⛔ 不能当一个班处理。

② 树上已经有两个不同的先例，不是一个

卡说「The tree already does this in one place」，指 @objectstack/cli 的可选 peer。该先例我逐字核实，完全成立：

packages/cli/package.json
  devDependencies:      { "@objectstack/driver-turso": "workspace:*" }
  peerDependencies:     { "@objectstack/driver-turso": "workspace:^" }
  peerDependenciesMeta: { "@objectstack/driver-turso": { "optional": true } }   ✅

⭐ 但 runtime 用的是另一套：optionalDependencies: @objectstack/driver-mongodb。这两者语义不同 —— optionalDependencies 会尝试安装（失败则跳过），peerDependenciesMeta.optional 不安装，只声明关系。⇒ 本卡把可选 peer 当成"那个正确答案"，⛔ 而仓里此刻两种都在用。这是维护者要裁的第一件事，本卡没有把它摆上桌。

---

四棱

① 项目长远合理性

两种可选依赖写法在同一棵树里并存，且没有任何地方记录"何时用哪个"——⇒ 每个新驱动都要重新猜一次。⭐ 长远正解是先定一条规则，再按规则回填这五处；⛔ 反过来（先改五处、再让规则从既成事实里长出来）就是本卡描述的现状是怎么来的。

② 实际业务拉动

低但非零，且方向明确：消费者现在只有在命中失败臂时才知道要装哪个驱动。⭐ 卡公道地指出那条运行时错误是好错误（把安装命令当数据带上了），⛔ 但它到达的时刻是故障时而不是安装时。装机时的一行 peer 警告 vs 生产里的一次失败——差别是真实的。

③ 防 AI 犯错

⚠️ 这一棱提醒的是修复本身的陷阱，卡已经测出来了：加 peer 会让 pnpm 在工作区内 link 该包（锁文件里落成 link:../../drivers/driver-turso），于是那条「真的没装时 turso 臂抛什么」的断言失效。⭐ 而该测试自己写了预警："If the package was made a dependency, this assertion is the notice that the pin above needs a stubbed import instead." ⇒ 这是一次设计良好的自我报警，⛔ 取卡者必须把它当指令读，不得删断言了事。

④ 创业阶段不扩散

⛔ 不要借本卡开"全仓依赖卫生"工程。范围锁死在这五处 + 一条书面规则。⚠️ 卡自己把 @objectstack/rest <- @objectstack/objectql 那第六处排除在外，理由是"rest 不耦合数据引擎是既定架构立场，不是卫生缺口"——⭐ 这个自我设限是对的，应当保留。

---

选项 × 真实可感成本

	做法	消费者可感	代价
A ⭐	先裁定「可选 peer vs optionalDependencies」二选一，写成一句规则；再按规则回填 turso 两处	安装期即可见	1 条规则 + 1 次测试改桩
B	直接按卡上做（全部改可选 peer），不定规则	同上	⚠️ 留下 runtime 的 optionalDependencies 与新规则不一致，下次再吵一遍
C	不做，维持运行时告知	无变化	0。⭐ 正当选项——卡自己说「Nothing user-visible changes today either way」

建议：A

⛔ 不要跳过定规则那一步。本卡最有价值的发现不是"五处缺声明"，而是同一棵树里有两种可选依赖语义在并行使用且无人记录——只回填而不定规则，等于把这个问题留给下一个驱动。

退路

若维护者判定装机期提示不值一次测试改桩 ⇒ 取 C，但仍建议把「两种写法并存」这一条记进依赖约定文档，⛔ 否则它会被反复重新发现。

---

⚠️ 置信缺口

1. 我没有实测 pnpm link 的副作用 —— 那条「加 peer ⇒ pnpm 在工作区内 link ⇒ 断言失效」是卡的实测转述，⛔ 我没有复现（需要真跑一次 pnpm install 并读锁文件）。这是选项 A 代价估算的唯一依据。
2. 我没有读 #7385 的兄弟 pin 是否也依赖同一个"意外" —— 卡说「if they turn out to rely on the same accident」，⚠️ 它自己也没确认。⇒ 改桩的真实工作量可能不止一处。
3. 我没有判定 runtime 那处 turso 是否与 service-datasource 同因 —— 它是 #6268 的「host-replaceable default thunk」，形状可能不同。⇒ 跨车道拆卡前应先确认它是不是同一个班的成员。

---

裁后执行段

• 跨车道拆卡：service-datasource 四处 ⇒ domain:services 一张；runtime 一处 ⇒ domain:cli 一张（先解置信缺口 3）。⛔ 不要一个 PR 横跨两域。
• 规则先行：无论取 A 还是 B，第一个 PR 应当只落那条规则（写在依赖约定处），⛔ 回填另起 PR。
• 测试改桩是必做项，不是可选项：packages/services/service-datasource/src/__tests__/default-datasource-driver-factory.test.ts 里那条断言必须改成 stubbed import，⛔ 不得删除——它是这个类的活报警。
• ⛔ 不得把 @objectstack/rest <- @objectstack/objectql 顺手并进来（卡已明确排除，理由是架构立场而非卫生）。
• ⛔ 不得放宽 scripts/check-undeclared-dep-imports.mjs 里那些 optional-runtime-probe 行来"让门闭嘴"——那些行现在正是这一类的守卫。

---

Generated by Claude Code