The engine-registration path is still unreached by the introspection compile channel: `IDataDriver` declares no `introspectSchema`, and `IDataEngine.introspectDatasource()` returns `Promise<unknown>`

[os-steve]

Found while implementing #11381 (option C of the #11123 ruling — tightening DatasourceDriverHandle.introspectSchema to the spec IntrospectedSchema, PR #11492). Out of scope there by the ruling's own boundary: the ruling names the DatasourceDriverHandle seam; this is the other road into the same runtime read. Filed unassigned, measured at b6d9432d1a.

The gap

#11492 wires the compiler channel for drivers that cross DatasourceDriverHandle — the host-factory path. But a custom driver has a second documented entry: constructed by the host and handed to IDataEngine.registerDriver() (directly, or via the handle's driver: unknown escape hatch that the connection service registers for it). On that path nothing types the introspection result:

• packages/spec/src/contracts/data-driver.ts — IDataDriver declares no introspectSchema member at all, so a driver author implementing the interface gets no signature to mis-match against.
• packages/objectql/src/engine.ts — introspectDatasource(datasource: string): Promise<unknown> duck-types the call (this.drivers.get(datasource) as any … driver.introspectSchema()), and its Promise<unknown> return then forces every consumer to re-narrow (the one in-tree consumer, service-datasource/src/plugin.ts, declares its own structural DataEngineLike with the spec type to get around it).

So a mis-shaped driver registered through the engine still compiles clean and is absorbed only by the PR #11001 runtime shim — exactly the population/channel argument recorded in #11123, one seam over.

Candidate shape (needs its own ruling — both are public-surface changes)

1. Add introspectSchema?(): Promise<IntrospectedSchema> (spec contract) to IDataDriver — an optional-member addition on the central driver contract; audit the in-tree drivers' declared return types (driver-sql / objectql types already extend the spec contract post-fix(driver-sql): introspectSchema() emits the spec introspection contract — primaryKey, dialect, introspectedAt (#10676, #10998) #11124/spec: withdraw the never-honored introspection indexes promise; widen defaultValue/maxLength to the measured emitted types #11270).
2. Tighten introspectDatasource(): Promise<unknown> to the spec type in objectql, which then lets plugin.ts drop its structural re-declaration.

Blast radius is wider than #11381's (the engine and the central driver contract vs one handle member), so it wants its own four-axis pass, not a rider.

Refs: #11123 (ruling + analysis) · #11381 / PR #11492 (the handle-side tightening) · PR #11001 (the runtime shim both channels fall back to)

[claude]

分诊落箱(session session_01Kktexqp6uVuFMztvvTMf3V,2026-08-24)。一句话问题:自定义数据库驱动的作者有两条路把驱动接进平台,一条(#11492 刚修好的)写错形状编译器会报错,另一条(直接注册进引擎)写错形状什么都不报,运行时靠兜底垫片悄悄吸收 —— 要不要把第二条路也管起来。

选项 × 真实代价:

• A. 两处都管:给驱动契约加可选的 introspectSchema 签名 + 把引擎的返回类型从「随便什么」收紧到规范类型。代价:公开契约面扩一格(可选成员,存量驱动零破坏);在树内三个驱动上核对一遍。业务上 = 驱动作者不管走哪条门,写错当场编译器红。
• B. 只收引擎返回类型,不动驱动契约:半闭合 —— 引擎消费者不再自带私货类型,但驱动作者仍无签名可对。业务上 = 修了一半,作者侧的坑还在。
• C. defer:记录不动。业务上 = 等第一个真实第三方驱动作者踩坑再说。

四棱:

• ① 长远合理性:A 是 service-datasource: the primaryKeyReader docblock now describes a producer that no longer exists, and the union read's isPrimary arm has no in-tree producer left #11123 裁决「population/channel」论证的自然收官 —— 同一个运行时读,两条通道一个强一个弱,弱的那条恒被绕行者选中;闭合它缩小特例。
• ② 实际业务拉动:今天树内消费者已被迫自造结构类型绕行(service-datasource 自declare),这是真实成本;树外第三方驱动作者今天还少,拉动中等。
• ③ 防 AI 犯错:AI 写驱动最容易「照 interface 实现」,interface 没有的成员它就自由发挥 —— A 让错误在编译期响亮,C 让错误在运行时静默。
• ④ 创业阶段不扩散:加的是可选成员且对齐既裁方向,不是新能力面;但仍是公开契约变化,故上人工地板。

推荐 A;回退 B。置信缺口:本分析未测树外是否已有第三方驱动实现 IDataDriver(若有,可选成员仍零破坏,但其 introspect 返回形状可能与规范类型冲突)。回「A」/「B」/「C」即可。裁后执行(你不用管):A ⇒ 此卡转 pm:queue 派 spec 席,Clause-② yes 走契约复审档;C ⇒ 关卡留档。

---

Generated by Claude Code