feat(spec,service-datasource)!: 驱动工厂 4 处未声明 ?? 容错按 ADR-0087 转换层退役 (#4456) - #4637
Merged
os-zhuang merged 2 commits intoAug 2, 2026
Merged
Conversation
…y config ?? fallbacks into an ADR-0087 conversion (#4456) The four undeclared read-side fallbacks createDefaultDatasourceDriverFactory kept after #4410 — sqlite `file`/`database` -> `filename`, pg/mysql `connectionString` -> `url`, pg/mysql/mongo `user` -> `username`, mongo `uri` -> `url` — become the declared, driver-aware conversion entry `datasource-config-driver-key-aliases` (retired from the load path: the authoring gate already rejects each spelling with a rename hint), and the `??` chains are deleted. Stored sys_metadata rows written before the #4410 gate keep loading: every rehydration seam replays the full chain (applyConversionsToStoredItem, #3903), including the DatasourceAdminServicePlugin restore path, which read raw JSON and now converts. Without that, deleting the fallbacks would have silently re-pointed a stored sqlite `file:` datasource at `:memory:`. Also adds the mapDatasources walker (conversions/walk.ts), registers the entry in the step-17 migration chain, regenerates spec-changes.json / protocol-upgrade-guide / driver-sqlite reference, and pins: stored rows with each legacy key load canonical; the factory no longer honours any legacy spelling handed to it directly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012C2cd7tL8QDoZ2QKN3djJ5
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 107 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
August 2, 2026 12:38
os-zhuang
enabled auto-merge
August 2, 2026 12:39
…asource-key-alias-conversion # Conflicts: # docs/protocol-upgrade-guide.md # packages/spec/spec-changes.json # packages/spec/src/conversions/registry.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #4456
做了什么
按 issue 的三步计划,把
createDefaultDatasourceDriverFactory里遗留的 4 组未声明读取侧??回退毕业为一条声明式 ADR-0087 D2 转换,然后真正删除:1. 新转换条目
datasource-config-driver-key-aliases(含 fixture)mapDatasourceswalker(conversions/walk.ts),形状对齐mapPages,委托给现成的mapCollection。resolveDriverId复用 datasource.config 至今无人校验：驱动 configSchema 是声明但完全惰性的（ADR-0049 enforce-or-remove，#4001 收尾发现） #4410 的唯一别名表,不另造第二张表):file/database→filenameconnectionString→url,user→usernameuri→url,user→usernamedatabase只在 sqlite 下是文件路径别名,对 pg/mysql/mongo 是规范键,一律不动(fixture 里 mysql 的database原样保留即为此 pin)。path:/dsn:这类从来只会落到:memory:的拼写不转——转了反而改变行为,违反 D2 的 lossless 约束。renameKey现有约定:规范键已存在则别名保持 shadowed、不动、不发 notice——这与工厂原??链的求值结果一致,无行为漂移。retiredFromLoadPath: true:作者侧 datasource.config 至今无人校验：驱动 configSchema 是声明但完全惰性的（ADR-0049 enforce-or-remove，#4001 收尾发现） #4410 的 strict 门禁已经用改名提示响亮拒绝这些拼写,若做成 live window,normalizeStackInput会先于门禁静默吸收,恰好瓦解 datasource.config 至今无人校验：驱动 configSchema 是声明但完全惰性的（ADR-0049 enforce-or-remove，#4001 收尾发现） #4410。存量数据与migrate meta走的正是includeRetired的重放通道。关于 mongo 的说明:issue 表格第三行的
user→username在buildMongoUrl里同样存在一处cfg.user ?? cfg.username(同一形状的第 5 个读取点),一并纳入转换并删除,否则 mongo 侧会留下半个后门。2. 删除工厂回退 + 中间态注释
??全部删除,工厂对每个键只读一种拼写。sqlite.zod.ts里"工厂仍容忍存量记录"的过渡注释改写为指向转换条目(mongo.zod.ts经核对现版本没有对应注释;工厂内uri的过渡注释随回退一起删除)。DatasourceAdminServicePlugin的 sys_metadata 恢复路径(loadDatasourceRows)此前直接JSON.parse,绕过了 [P2] The spec contract stops at authored source — stored metadata is rehydrated unparsed, unconverted, and ungated #3903 的存量转换。现在按 ADR-0087 addendum 调用applyConversionsToStoredItem('datasource', …)重放整条链——这正是"删了回退存量file:行会无声落到:memory:"的那条路径。metadata / metadata-protocol 的通用 seam 本来就重放整条链,注册后自动覆盖。3. 常规再生成
conversionIds+ rationale 段落;spec-changes.json、docs/protocol-upgrade-guide.md、content/docs/references/data/driver-sqlite.mdx由check:generated --fix再生(仅重生成被判 stale 的三个)。Pin 测试
stored.test.ts:四组 legacy 键的存量 datasource 行经applyConversionsToStoredItem均以规范键载入;pg 的database不被误改;规范键胜出、别名 shadowed。conversions.test.ts:同一database键"sqlite 转、其余驱动不转";插件贡献的未知 driver id 不动;load path 上(不带 includeRetired)作者侧 legacy 拼写不被静默吸收。datasource-admin-plugin.test.ts:直接向 sys_metadata 播种 pre-datasource.config 至今无人校验：驱动 configSchema 是声明但完全惰性的（ADR-0049 enforce-or-remove，#4001 收尾发现） #4410 形状的行,boot + start 后经getDatasource读回的 config 已是规范键。default-datasource-driver-factory.test.ts:工厂对直接递入的 legacy 拼写不再理会——pgconnectionString不再选中 DSN 路径、user不再到达客户端(canonicalusername为对照)、mysql 同;sqlite-wasm 的file/database落到:memory:(legacy 路径无文件产生);mongouri/user不参与 URL 组装(canonical 组装为对照)。验证
pnpm --filter @objectstack/spec test:290 files / 7297 passed(合并 origin/main 后复跑)pnpm --filter @objectstack/spec typecheck、check:generated:全绿(8/8 artifacts up to date)@objectstack/service-datasource:204 passed + typecheck 通过test typecheck --filter metadata --filter metadata-protocol --filter runtime:28 tasks successfulChangeset
.changeset/datasource-config-key-alias-conversion.md(spec minor + service-datasource minor),含 FROM → TO 映射表与一行修复指引。🤖 Generated with Claude Code
https://claude.ai/code/session_012C2cd7tL8QDoZ2QKN3djJ5
Generated by Claude Code