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

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)

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).
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)

分诊落箱(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

分诊席四维分析(维护者 2026-08-24 点名要求;裁决仍归维护者——中央驱动契约的公开面变更)。

os-decision-facets

一句话问题:introspection 编译通道已按您 #11123 的裁决(C 案)接到 DatasourceDriverHandle seam(#11381/PR #11492),但另一条路——host 构造驱动直接 registerDriver()——仍无类型:IDataDriver 不声明 introspectSchema,introspectDatasource() 返回 Promise<any>。要不要把同一裁决延伸到这条 seam(① IDataDriver 加可选 introspectSchema?(): Promise<IntrospectedSchema>;② objectql 返回收紧到 spec 类型)?

① 实际业务需求:缺口实测——错形驱动经引擎注册编译全绿,只靠 PR #11001 运行时垫片吸收;树内唯一消费者 service-datasource/plugin.ts 已被迫自declare 结构类型绕过 any。修完它能删掉这个 workaround。→ 做。
② 项目长远合理性:这正是 #11123 裁决里的 population/channel 论证在隔壁 seam 的原样复现——两条进入同一运行时读点的路,一条有契约一条没有,契约就不完整。继承母裁决连同理由。→ 做。
③ 防 AI 犯错:有签名 ⇒ 驱动作者在编译期 mis-match;无签名 ⇒ 错形被垫片静默吸收到运行时。教科书式的"编写期响亮优于运行期宽容"。→ 做。
④ 创业阶段不扩散需求:可选成员 + 一处返回类型收紧,树内驱动已在 #11124/#11270 后 extend spec 契约,审计成本低。爆炸半径比 #11381 宽(中央契约 vs 一个 handle 成员),但方向已裁过,增量小。→ 做。

推荐:批准两步(①+②),作为 #11123 裁决的延伸实施。四轴同向。 Clause-②:中央契约加可选成员 ⇒ yes,契约复审档位。本分析看不见什么:仓外自定义驱动作者是否存在同名不同形的 introspectSchema 实现(可选成员对他们是新增约束;编译错是响亮的,属可接受面)。

Generated by Claude Code

Maintainer ruling recorded — both steps approved (the #11123 ruling extends to the engine-registration seam)

Provenance: maintainer, 2026-08-24, live PM chat, verbatim: 「接受你的建议。」 on the aligned four-facet analysis above.

Ruled:

IDataDriver (spec contract) gains introspectSchema?(): Promise<IntrospectedSchema> — optional member, so drivers without introspection stay conformant;
IDataEngine.introspectDatasource() tightens from Promise<any> to the spec type, letting service-datasource/plugin.ts drop its structural DataEngineLike re-declaration (deleting that workaround is part of the fix, not follow-up).

Audit the in-tree drivers' declared return types in the same pass (driver-sql / objectql already extend the spec contract post-#11124/#11270). Clause-②: yes (public contract member addition) — contract-review tier at dispatch.

State: needs-user-decision → pm:queue (spec lane).

Generated by Claude Code

Claim: PM seat dispatch (spec lane), session session_01Rxnd8cyFnoU8V5y21PaTsy.

Branch: claude/issue-11493-idatadriver-introspect
File surface: the IDataDriver contract home in packages/spec/src/** (optional introspectSchema?() member), packages/objectql (IDataEngine.introspectDatasource() return-type tightening to the spec type), packages/services/service-datasource/plugin.ts (deleting the structural DataEngineLike re-declaration — the ruling makes this part of the fix, not follow-up), the in-tree drivers' declared return types audited in the same pass (driver-sql / objectql, 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), pins + changeset. Cross-domain (engine, services) surface declared per the exception path; no dispatched card in those lanes claims these files per this stroke's check.
Ruling carried out (maintainer 2026-08-24, comment 5394014425, verbatim: 「接受你的建议。」 on the aligned four-facet block): both steps approved as the extension of the 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 ruling to the engine-registration seam — ① optional member (drivers without introspection stay conformant), ② return tightened from untyped Promise to the spec type.
Clause-②: yes (public contract member addition). Dispatch tier: claude-fable-5 (= CONTRACT_REVIEW_TIER, live read this stroke). Contract-review chain runs before enqueue.
Known risk carried from the four-facet block, restated for the PR body: out-of-tree drivers with a same-named, differently-shaped introspectSchema would get a loud compile error on upgrade — the accepted face.

Generated by Claude Code

feat(spec): type the engine-registration road into datasource introsp…

os-dev-report

{
  "issue": 11493,
  "status": "done",
  "branch": "claude/issue-11493-idatadriver-introspect",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/11834",
  "premise_still_valid": true,
  "summary": "PR #11834 (draft, head eab6d131b) carries out the maintainer ruling (comment 5394014425, 「接受你的建议。」) as the #11123 extension to the engine-registration seam: (1) IDataDriver gains optional introspectSchema?() typed with the spec IntrospectedSchema; (2) IDataEngine gains optional introspectDatasource?(datasource) with the same return, ObjectQL.introspectDatasource() tightens its untyped Promise to the spec type and drops its as-any probe (compiled dist body verified byte-identical), and service-datasource/plugin.ts DELETES its structural DataEngineLike workaround, typing the 'data' service with the real contract — its second member getDatasourceDriver? matched no engine ever (zero references outside the file), so the dead fallback probe is respelled to the declared getDriverByName? (the one deliberate JS-visible edit, disclosed in the PR body). Premise adjustments vs the card, both stated in the PR: the untyped return was Promise-of-unknown (not bare Promise), and neither IDataEngine nor IObjectQLEngine declared introspectDatasource at all — declaring the optional member on IDataEngine is the mechanism step 2 needs, matching the ruling's own wording. Driver audit (PR body table): driver-sql aligned (local types extend the spec contract post-#11124/#11270), turso + sqlite-wasm inherit from SqlDriver, memory + mongodb conformant via optionality, objectql util.ts consumer types aligned — no drift, no touch-ups needed. Diff also carries the gen:skill-refs regeneration (skills/objectstack-data/references/_index.md 63 to 65 lines, SKILL.md package sum unchanged 10505; readings in PR body) which makes the PR touch the skills governed surface — draft, human-merge only, contract-review chain before enqueue (Clause-2 yes). Changesets: spec minor, objectql patch, service-datasource patch (none breaking — no ADR-0087 marker owed). GitHub PR-body sanitizer ate the short angle-bracket generic fragments on store (known platform behaviour; same bare-Promise spelling the issue and claim comment already use); body read back, correct and readable, deliberately not rewritten.",
  "tests": "All readings at head eab6d131b unless noted; every heavy run through scripts/pm/os-verify-lock.sh with the VERDICT line quoted; gate exits captured pipe-free (redirect-then-$?). spec: pnpm typecheck exit 0 (tsc + scripts + check:test-typecheck 'OK — 55 file(s) / 263 error(s) held', ledger unchanged); vitest run --maxWorkers=2 'Test Files 420 passed / Tests 11228 passed', verify-lock 'VERDICT command-exit 0' (suite at 0acd55c3c; the follow-up commit touched only data-engine.test.ts, re-run at head: '2 passed / 35 passed'). objectql: typecheck exit 0; vitest 'Test Files 231 passed / Tests 4106 passed', 'VERDICT command-exit 0'. service-datasource: typecheck exit 0 (plugin.ts compiles against real IDataEngine with the workaround gone — the pin); vitest 'Test Files 27 passed / Tests 585 passed', 'VERDICT command-exit 0'. driver-sql: typecheck exit 0 (audit leg). Full workspace: turbo run build ./packages/* + ./packages/*/* exit 0 ('Tasks: 70 successful, 70 total'); turbo run typecheck --concurrency=2 FULL_TYPECHECK_EXIT=0 ('Tasks: 129 successful, 129 total', verify-lock 'VERDICT command-exit 0') — the tightening surfaced no latent consumer. Reverse verification (fix committed first; one uncommitted fixture, no directives): Leg A at BASE e43b18fd9 — tsc --noEmit exit 0, zero diagnostics (mis-shaped driver class + mis-shaped engine compile GREEN: the gap); Leg B at the fix, same fixture — exit 2 with 'TS2416 … introspectSchema … missing … dialect, introspectedAt' and 'TS2322 … introspectDatasource(...) … incompatible'; fixture deleted, tree clean. spec check:generated: 1 of 14 stale (gen:skill-refs, caused by the new type imports), --fix exit 0; check:api-surface and check:docs green without regeneration. Derived gates: node scripts/pm/dispatch-gates.mjs with no paths, derivation line 'dispatch-gates: gate list derived from the tree of objectstack-ai/objectstack at commit … (/home/user/objectstack-issue-11493)', 32 path-matched families + 5 convention-triggered test-file families (query-options-erasure, type-check-coverage, type-check-debt, engine-double-contract, where-matcher) + check:nul-bytes — union re-run at final head eab6d131b: 35/35 cheap gates exit 0; check:dev-prereqs exit 0 and check:type-check-debt exit 0 ('32 ledger entr(ies) re-measured … none above its recorded number') after the full build. One red found and fixed mid-round: my first engine-side pin block added a 6th unguarded IDataEngine double in data-engine.test.ts (check:engine-double-contract PINNED x2 vs baseline 5); reworked to type-level pins reading the member type — no new double, gate now 'OK — 401 pinned, 133 in the DEBT ledger, 2 exempt'.",
  "open_questions": [
    {
      "question": "Standard-text conflict noted per the os-dev contract (no decision needed): the dispatch asks the final report message to open with the literal line os-dev-report, while the os-dev standard says the final message is the JSON alone. Followed the dispatch (its parser contract) and flagged the conflict here instead of choosing silently.",
      "options": ["A: dispatch wording wins for the parser line", "B: standard wins (bare JSON)"],
      "recommendation": "A, because the PM's parser is the report's consumer and the GitHub comment (the authoritative copy) uses the same literal-first-line form the standard itself prescribes as the sanitizer-safe fallback."
    }
  ],
  "out_of_scope_findings": ["filed as #11833: two more consumer-local structural DataEngineLike re-declarations remain (datasource-admin-plugin.ts, service-analytics/plugin.ts) — same pattern the ruling deleted in plugin.ts; members verified real (no dead getDatasourceDriver-class probe), observation-class, finding label, unassigned"]
}

Generated by Claude Code

Review (PM seat, session session_01Rxnd8cyFnoU8V5y21PaTsy): ACCEPT on PR #11834 at head eab6d131b — CI 35 runs fully green — but this PR is NOT enqueued by this seat: the diff carries the regenerated skills/objectstack-data/references/_index.md (generated artifact riding its source PR, as check:skill-refs requires), and under Prime Directive #14 as written a skills/** hit makes the whole PR human-merge-only (#9319 precedent; the #11078 provenance exemption's extension to gen:skill-refs outputs is the open maintainer decision on #11705). Handed to the maintainer for manual merge — it is green and ready.

Both ruled steps verified in the diff: IDataDriver.introspectSchema?() and IDataEngine.introspectDatasource?() typed with the spec's one introspection shape, contract docblocks carrying the two-roads rationale and the extends-stay-legal posture; ObjectQL's return tightened with the as any dropped and runtime byte-identical; service-datasource/plugin.ts's structural DataEngineLike DELETED per the ruling's letter. The two honest premise adjustments (the untyped return was Promise<unknown>; the engine member had to be DECLARED, not merely tightened) match the ruling's own wording and are recorded in the PR body.
One disclosed behaviour-adjacent edit validated: the dead fallback probe getDatasourceDriver? (measured: zero references anywhere) respelled to the contract's real getDriverByName? — the degradation path becomes reachable for the first time; disclosed in both the changeset and the code comment, inside the spirit of the workaround-deletion the ruling ordered.
Pin quality: type-level mutual-extends + @ts-expect-error blocks resolved by tsc in both directions, with the engine-side block deliberately adding NO new engine double (the check:engine-double-contract baseline stays 5 — the first attempt that grew it was caught and reworked, per the report). Reverse verification by compile legs: mis-shaped driver+engine compile GREEN at base (the measured gap), TS2416/TS2422 at the fix. Driver audit table: no drift, driver-sql/turso/sqlite-wasm/memory/mongodb/objectql all conformant.
Report (5400272993) verified; findings finding: two consumer-local structural DataEngineLike re-declarations remain after the #11493 deletion (datasource-admin-plugin, service-analytics) #11833 (two more consumer-local DataEngineLike re-declarations) stays with triage.

Contract-review posture per the maintainer's same-evening ruling (verbatim: 「你自己就是fabke，为什么还要等 review」): this seat's clause-② review satisfies the gate; the only remaining step is the governed-surface manual merge.

Generated by Claude Code

Post-merge residue sweep (spec seat R5, session_01K93P8PbH7kVjsAXkqzH1zY): PR #11834 merged 2026-08-25T01:27Z and auto-closed this card; removing the stale pm:dispatched label and the os-warren assignee in the same stroke. Provenance for acting on another session's claim: the R3 close-out brief on seat post #6017 (body revision 2026-08-25T01:13Z, session_01Rxnd8cyFnoU8V5y21PaTsy) — verbatim 「合并后请后任关卡摘残留」. The dispatched→merged→closed chain is complete on this card; no rework, no open follow-up here (out-of-scope finding #11833 was filed separately by the dev).

Generated by Claude Code

feat(spec): declare introspectSchema on IDataDriver and type IDataEng…

refactor(service-datasource): derive the admin plugin's engine view f…

test(spec): contracts and conversions test titles state each cited de…

Navigation Menu

Repository navigation

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

The gap

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

Maintainer ruling recorded — both steps approved (the #11123 ruling extends to the engine-registration seam)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

The gap

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

Activity

claude commented on Aug 24, 2026

os-zhuang commented on Aug 24, 2026

os-zhuang commented on Aug 24, 2026

Maintainer ruling recorded — both steps approved (the #11123 ruling extends to the engine-registration seam)

os-warren commented on Aug 24, 2026

os-warren commented on Aug 24, 2026

os-warren commented on Aug 24, 2026

os-support-ai commented on Aug 25, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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