fix(service-datasource)!: refuse every top-level key DatasourceSchema refuses at the datasource test, create and update doors - #28632

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-datasource, touching 8 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via connectionString (literal, a string literal in TOP_LEVEL_CREDENTIAL_KEYS))

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin cb8536666eeb683ee9b444cfa0bfae7d645bbcb8 && git checkout cb8536666eeb683ee9b444cfa0bfae7d645bbcb8
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d77dc07a5e5a4b5478763fb3a2126913c92f8c01 f1438f52c4d31ddd71759cafd70dda5e3f9bc3f3 && git checkout -B drift-repro d77dc07a5e5a4b5478763fb3a2126913c92f8c01 && git merge --no-ff f1438f52c4d31ddd71759cafd70dda5e3f9bc3f3

node scripts/docs-audit/affected-docs.mjs --json d77dc07a5e5a4b5478763fb3a2126913c92f8c01

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs d77dc07a5e5a4b5478763fb3a2126913c92f8c01 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: f1438f52c4d31ddd71759cafd70dda5e3f9bc3f3
Local-runs: none
Scope: packages/services/service-datasource/src/datasource-admin-service.ts, packages/services/service-datasource/src/tests/datasource-admin-top-level-credential.test.ts + packages/spec/src/data/datasource.zod.ts, packages/spec/src/shared/strict-object.ts, packages/spec/src/kernel/metadata-protection.zod.ts, packages/services/service-datasource/src/admin-routes.ts, packages/services/service-datasource/src/contracts/datasource-admin-service.ts, packages/spec/src/api/error-code-ledger.zod.ts, .changeset/28549-datasource-top-level-credential.md, ui/packages/app-shell/src/views/metadata-admin/datasource/DatasourceResourcePage.tsx, packages/client/src/index.ts, packages/cli/src/commands/datasource/introspect.ts, packages/cli/src/commands/datasource/list-tables.ts, packages/cli/src/commands/datasource/validate.ts, docs/qa/platform-checklist/areas/integration-system.json, packages/qa/dogfood/test/datasource-restore-code-wins.dogfood.test.ts, packages/qa/dogfood/test/datasource-restore-environment-rows.dogfood.test.ts, packages/qa/dogfood/test/datasource-meta-door-reaches-admin-door.dogfood.test.ts, packages/qa/dogfood/test/meta-door-code-datasource.dogfood.test.ts

Inputs read: card #28612 (body, claim 6555258668, dev report 6556117106), parent #28549 (body, triage, claim, dev report 6555151884, landing record) and the parent's contract review 6555221422 on PR #28607, PR #28632 body, file list and net diff at the head above, the 45 check-runs on that head, and the cited code at origin/main (d77dc07a5). The narrowing face has no path hits; the floor is every non-prose path of the diff, listed first on the Scope: line. The changeset is read for ②, not reviewed. Nothing was checked out, built or run; the one mirror of the Console page in the sibling checkout /home/claude/objectui was compared byte-for-byte to the ui/ copy on origin/main (identical) and is not a run.

① Derived judgments

1. Accept-set narrowing at three doors, generalised from two keys to the schema's whole refused set — right. On main the three doors still project through known keys only: testConnection builds its probe from this.toRecord({ ...input, name: PROBE_DRAFT_NAME }), createDatasource spreads this.toRecord(input), updateDatasource merges label/driver/schemaMode/config/pool/active/external by name. The fix(service-datasource)!: refuse a top-level password or connectionString at the datasource admin write doors #28607 check assertNoTopLevelCredential filtered a hand list TOP_LEVEL_CREDENTIAL_KEYS = ['password', 'connectionString']. The diff deletes that list and the method, and assertNoUndeclaredTopLevelKey(heading, body) takes Object.keys(body) (values not undefined), parses the null-valued skeleton through DatasourceSchema and keeps only the root unrecognized_keys issue. So the refused set is exactly the set DatasourceSchema refuses at run time, with no second copy. The premise of the card (item 2) holds at origin/main and the diff closes it at all three doors.

2. The key set is the schema's, read from the live spec. DatasourceSchema is a lazySchema whose body is strictObject({ surface, aliases, guidance, history }, shape) with a .superRefine(...) on the result, and strictObject is closedObject(z.object(shape, { error: strictObjectError(...) }).strict()). A .strict() object emits one root unrecognized_keys issue naming every unknown key whatever the declared fields do with their null values, so a declared key failing its type (driver: null) never masks the refusal and never reaches the kept issues (filtered on code === 'unrecognized_keys' && path.length === 0). No retired spelling sits in the shape as a tombstone (retiredKey( does not occur in datasource.zod.ts): readReplicas, replicas, capabilities, readOnly, retryPolicy, retry, healthCheck, healthcheck are all guidance rows, so each is refused at the root like foo. The declared keys that pass are the shape's: name, label, driver, config, pool, ssl, description, active, autoConnect, schemaMode, external, origin, and the MetadataProtectionFields (_lock, _lockReason, _lockSource, _provenance, _packageId, _packageVersion, _lockDocsUrl). Right.

3. The refusal text comes from the schema's own guidance, one spelling — right. The message is the unrecognized_keys issue's message, composed by strictObjectError from the schema's aliases (type → driver, connection/options → config, enabled → active, tls → ssl, …) and guidance rows (host/port/database/user/username/filename/url/connectionString → belongsInConfig, connector, password, the retired blocks), the same path os compile prints through. The service restates nothing; the test's specRefusal derives the expected text from DatasourceSchema at run time and throws fixture premise broken if the spec stops refusing a key, so neither a re-inlined copy nor a spec drift can pass quietly. Right.

4. The refusal code is already ledgered at this door — right, no published-surface addition. DATASOURCE_ADMIN_ERROR is the @objectstack/service-datasource row in packages/spec/src/api/error-code-ledger.zod.ts ("lifecycle/validation refusal from the datasource-admin service"), and admin-routes.ts badRequest answers every plain Error thrown by the admin service as 400 with SERVICE_ERROR_CODE['datasource-admin'] unless it carries the 503 or 404 envelope; the new throw carries neither. All three routes (POST /test, POST, PATCH /:name) sit inside that try/badRequest. No code, status or envelope field is added.

5. The Test door moves from a projected probe to a thrown refusal — right, and the card rules the shape. On main the test door's own refusals (no driver, bad config, invalid record, lend refusal) answer 200 with result.ok: false; the diff makes an undeclared key a 400 DATASOURCE_ADMIN_ERROR thrown as the first statement, before the driver requirement and before any probe. Item 1 of the card asks for "the same DATASOURCE_ADMIN_ERROR", and the distinction holds: a key that changes what is being tested is a malformed request, not a failed connection. The Console's testDraft reaches both shapes correctly: its api() helper throws the envelope's error.message on a non-2xx, and the catch renders it as a failed test with the server's text. The heading This connection draft is not a valid datasource. is the one recordRefusal already uses at that door. Right.

6. No legitimate producer sends a key the door now refuses — right, measured in the cited code. Console DatasourceResourcePage.tsx: draftBody builds a fresh body (label, driver, schemaMode, config, optional external: {}, optional secret); openEdit copies the GET detail field by field into EditorForm (name, label, driver, schemaMode, storedSchemaMode, config, secret: '') and keeps hasSecret in component state only for the placeholder text, so no GET record is ever sent back whole; the test-draft call sends driver, config, secret; the row "Test" goes to POST /:name/test, a different service. The /home/claude/objectui mirror of that page is byte-identical. packages/client exposes only datasources.external.* (no create, update or test method). The CLI datasource commands (introspect, list-tables, validate) are read-only. The four dogfood suites that POST create bodies send name, label, driver, config; every PATCH they send is { label }. The QA checklist's round-trip clause (integration-system, the ADR-0100 §B3 verify) says "PATCH … with the response's config back unmodified", a declared key, not the whole response; its change log already records that "PUT the response back" was corrected. No seed under examples/, apps/ or scripts/ posts to these doors.

7. The GET round-trip keys hasSecret, redactedConfigKeys, definedIn (and list-row status/statusReason) are refused, not tolerated — right, and the parent review's suggestion is overruled with cause. Those keys are declared nowhere as input: not in DatasourceDraft, not in DatasourceSchema, and no producer sends them (item 6). The one key the GET answer carries that an editor might echo and the schema declares, origin, passes the check and is stamped by the door (control: origin: 'code' on create stores runtime). Tolerating undeclared keys here would be a consumer-side allowance the spec does not make, which is the exact posture ④ forbids. The changeset's remedy line names the keys not to send back. Right.

8. Door-only field named with its reason — right. The PR body names secret as the one key the doors accept that the schema lacks, and the cited code agrees: splitSecret removes secret from the body before testConnection, createDatasource and updateDatasource see the draft, so it never reaches the check (controls on all three doors). DatasourceDraft declares name, label, driver, schemaMode, config, external, pool, active, every one declared by the schema. No other door-only field exists.

9. Ordering at each door — right. Test: first statement, under an input && typeof input === 'object' guard (a null body still answers the driver is required ok: false). Create: after assertValidName and assertNoDraftCredentialsRef, before the driver requirement — fix(service-datasource)!: refuse a top-level password or connectionString at the datasource admin write doors #28607's position. Update: after the 404 and the code-defined refusal, before the merge, on every patch including a label/active-only one — the right reading of the [finding] POST /api/v1/datasources (and the PATCH door) never run DatasourceSchema's cross-field refinements — a mongo credentialsRef pairing that os build and PUT /meta refuse is accepted 201, and the bound secret is silently unused #21058 exemption, as the parent review already judged.

10. No value reaches the judgement or the answer — right. Only key names are parsed (null values); the tests assert the placeholder password and the DSN host are absent from the message, the record store and secret store untouched, and the op log empty (the probe seam now records probe, so "nothing probed" is read, not assumed).

11. Exports and DatasourceDraft unchanged — right. The deleted constant and the renamed method are module-private; the contract file is not in the diff.

12. Metadata-protocol: none and Skills-docs: none — right. DatasourceSchema does not move; no page under skills/** or content/docs teaches the admin request body (the only datasources/test mentions are release notes). Flag docs affected by code changes concluded success.

② Semver level

.changeset/28612-datasource-undeclared-top-level-key.md: '@objectstack/service-datasource': patch, a BREAKING banner, Clause-②: no (narrowing) and Metadata-protocol: none as line-initial declarations, and exactly one ADR-0087 marker (not-required (no-migration-prescription)) with its reason. This matches what the diff publishes: a non-protocol accept-set narrowing on a released service package, no key added, removed or re-shaped, nothing at rest to migrate (a refused body was never stored). The level and disposition are the same the #28549 entry shipped under, and Check Changeset and Governed Surface Queue Guard both concluded success on this head. The PR body carries Clause-②: no (narrowing) at the start of a line, the one spelling this face is keyed on, and the changeset repeats it exactly. The entry's last bullet supersedes the #28549 entry's "Other unknown top-level keys are still dropped as before" sentence by name; that entry is left unedited, which is right for a changeset already landed.

③ Boundary flags

open_questions: []. The report's four deviations and two out-of-scope findings, each answered:

• Three pushes, two merges of origin/main; all readings re-taken on f1438f52: the diff against main is the three files on the file list and nothing of fix(service-datasource)!: refuse a top-level password or connectionString at the datasource admin write doors #28607 is re-stated in it (the hunks delete fix(service-datasource)!: refuse a top-level password or connectionString at the datasource admin write doors #28607's list and rename its method). Answered.
• GET round-trip keys refused rather than tolerated: judged in ① item 7 — the right call, confirmed against the Console, the mirror, packages/client, the CLI, the dogfood suites and the QA checklist clause. Answered; the parent review's suggestion does not stand.
• No labels on pr_create: the labeler added documentation, size/m, tests, tooling; the order named none. Not a contract matter. Answered.
• Merge commit message keeps git's # Conflicts: listing: cosmetic; PR-body guards and the trailer gate concluded success, and a squash landing rewrites it. Answered.
• Out-of-scope finding, class a — ssl, autoConnect, description pass the key check and are then dropped by toRecord / the update merge: confirmed in the cited code (toRecord projects neither; the merge lists neither), and ssl is a declared capability the driver factory honours. Outside this card ("refuse what the schema refuses"); it is the should-fix below, which needs a carrier so it is not lost in a PR's notes.
• Out-of-scope finding, class a — route-ledger live-mount parity red on main (GET /packages/:id/customizations): arrived with feat(runtime,spec): GET /packages/:id/customizations answers a base's overrides, extensions and switched-off items in one read #28595; tracked as p0 main red: Dogfood Regression Gate — GET /packages/:id/customizations is ledgered but not mounted (#28595), so the route 404s at runtime #28622. Not this PR's; and it is not among the check-runs on this head (the full dogfood is the dev's local battery, not a CI family).

Check-runs on f1438f52 at the time of this record: 45 runs, 0 failures. 32 completed — 19 success (Check Changeset, Governed Surface Queue Guard, PR-body guards, Check PR Size, Lint · ESLint, Lint · docs & code guards, Lint · CI, release & engine gates, Lint · PM dispatch-gates, three scoped lint lanes, Type Check · debt ledger, Type Check · source gates, Dogfood Regression Gate, Test UI, Flag docs affected by code changes, Plan Test Core shards, Auto Label, filter) and 13 skipped (UI build/lint/typecheck lanes, opt-in harnesses, the conformance job). 13 still in_progress: Test Core 1–8, Build Core, Type Check · workspace, Type Check · consumer gates, Lint · repo & tooling gates, Live E2E UI. Their conclusions are the gate verdicts for their families; this record does not pre-empt them and the queue stays gated on them. No red on this head is the #28622 dogfood file — there is no red on this head at all. The dev's local readings (service suite 1125/1125, red-first 12/25, three single-door ablations, 61 derived families, full dogfood with the one known main failure) are the PR's account, read but not relied on.

④ Design judgment

The narrowing, judged against the published spec on main: DatasourceSchema is a closed shape whose history line says in so many words that until it was closed "these were dropped silently — a connection key written one level too high left the datasource connecting on driver defaults rather than failing". The build door and the meta door already refuse every undeclared top-level key by name; the admin door's three entrances alone still projected and dropped them, and the Test door answered about a different connection than the one described. Nothing declared is taken away at the consumer: DatasourceDraft never carried any refused key, no stored record ever held one, every key the schema declares still passes, and secret stays the credential channel. This makes the spec's own refusal real at the last three doors that did not give it. Right.

Attempts to break it, each read in the diff and the cited code:

• A body with only declared keys ({ driver, config } on the test door, { label } on PATCH): present is non-empty, the skeleton parse fails on types but emits no root unrecognized_keys, detail is empty, the check returns. The Console's every body is of this shape. Holds.
• Several refused keys at once (foo, host, password): one unrecognized_keys issue names all three, with a guidance line per key; the test pins the exact text. One answer, not three round-trips. Holds.
• An alias (type) and a retired block (readReplicas): both are refused through the aliases / guidance tables, never through the shape, so they arrive as root unrecognized_keys and are caught; pinned. Holds.
• secret beside password on the test door: splitSecret removes secret, the draft still carries password, refused before the probe (op log empty). Holds.
• A non-object body (array or string reaching splitSecret): the rest-spread yields index keys, now refused at the root as unrecognized keys. Before, create threw on the name, the test door answered ok: false, and PATCH merged nothing and answered 200. A 400 for a malformed request is the better answer at every door. Holds.
• A code-defined datasource patched with foo: the code-defined refusal fires first; the row is read-only before the body is judged. Acceptable ordering, as at fix(service-datasource)!: refuse a top-level password or connectionString at the datasource admin write doors #28607.
• Spec drift (a refused key later declared): detail empties and the door opens for that key; the test's specRefusal throws in that case, so the pin goes red rather than the door going quiet. Sound.
• origin / name on PATCH, origin: 'code' on POST: declared, pass, and the door stamps origin: 'runtime' and keeps existing.name as before; pinned by the controls. The spec's "never accepted from client input" is honoured by ignoring, not refusing, which is the status quo and what the GET round-trip needs. Holds.
• Direct in-repo callers of the three doors: none outside admin-routes.ts (searched the live tree); no caller hands a StoredDatasource with definedIn or a GET detail to a door.

Findings:

• should-fix (follow-up card, not this PR): keys DatasourceSchema declares that the doors still drop — ssl, autoConnect, description (and the protection fields) pass the new check and are then left out by toRecord and the update merge. ssl is honoured by the driver factory on a stored record, so an admin-created datasource that asks for TLS connects without it, silently; POST /api/v1/datasources answers 201 for a body the stored row does not match. That is a declared capability not delivered at the consumer, an implementation gap of the kind ④ says must be implemented or retired, never narrowed. It is outside this card's "refuse what the schema refuses" and the dev reported it with carrier: none; it should be filed so it is not lost in a PR's acceptance notes.
• No must-fix.

Implemented-by: claude/project-thread-d8uf4e
Reviewed-by: session_01FEkQ5kE5BrPUPNMMyv6oCH

VERDICT: PASS

domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH

席位核对 · ACCEPT · PR #28632 · 2026-11-01T09:47Z

Head-sha: f1438f52c4d31ddd71759cafd70dda5e3f9bc3f3

维护者速读(席位终稿)

• 改了什么:数据源管理的连接测试、创建、编辑三个入口，现在拒收请求体顶层任何 DatasourceSchema 不认识的键:400 DATASOURCE_ADMIN_ERROR,点名这个键，不回显值，不写入也不探测。拒收的键集和提示都在运行时取自 DatasourceSchema 自己的报错，没有手写清单。
• 为什么改:以前三个入口都悄悄丢掉这些键还答成功;连接测试会丢掉顶层 password,测的其实是另一个连接(Datasources: the test door and every undeclared top-level key still bypass the refusal DatasourceSchema gives (the rest of #28549) #28612)。
• 风险与回滚:schema 声明过的键照常通过拒收检查;secret 仍由路由先拆走。仓内没有生产者发被拒的键(契约复核逐一核过 Console、client、CLI、QA、dogfood)。注意:ssl、autoConnect、description 虽能通过，但仍会在存储时被丢，这是 Datasources: the admin create and edit doors drop the schema-declared ssl, autoConnect and description, so a datasource created there loses its TLS settings #28633 的修复范围，已派发。回滚即 revert。
• 先看:datasource-admin-service.ts 的 assertNoUndeclaredTopLevelKey 与 testConnection 开头的调用。
• 两分钟验证:pnpm --filter @objectstack/service-datasource exec vitest run src/__tests__/datasource-admin-top-level-credential.test.ts → 25/25。
• 需要你做的:无。席位按常设授权落地。
• 席位意见:契约复核 PASS;键集取自 schema 本身，后续 schema 变化自动跟随。可落。

核对六项

1. 形态:draft → main;Fixes #28612,本 PR 交付卡的两项期望，合并即关卡正确;其余闭合关键词零命中(已扫)。文件 3 个，在认领申报面内。
2. 前提实测:红先在 fix(service-datasource)!: refuse a top-level password or connectionString at the datasource admin write doors #28607 head 0cc981aa 上 12/25 红(测试门 200、创建 201、编辑 200);消融逐门恢复(测试门 4 红、创建 9 红、编辑 6 红),每次复原 blob 回 HEAD。
3. 门禁:本 head check-runs 48 个,35 success、13 skipped、0 失败。dev 本地 f1438f52:61/61 派生门禁 exit 0,包测 1125/1125。dogfood 1 红为 route-ledger-live-mount-parity(GET /packages/:id/customizations,feat(runtime,spec): GET /packages/:id/customizations answers a base's overrides, extensions and switched-off items in one read #28595 合入 main 所致，p0 main red: Dogfood Regression Gate — GET /packages/:id/customizations is ledgered but not mounted (#28595), so the route 404s at runtime #28622 由 1 号席位处理),本 diff 只动 service-datasource,不归本 PR。
4. 接受的偏差:GET 回显键 hasSecret / redactedConfigKeys / definedIn 被拒收而非容忍，依卡的期望 2 与生产者实测(无发送方);契约复核认可，推翻 fix(service-datasource)!: refuse a top-level password or connectionString at the datasource admin write doors #28607 复核的「容忍」建议。三次推送(两次合 main),读数皆在 f1438f52,接受。
5. 范围外去向:声明过的 ssl / autoConnect / description(及保护类字段)通过检查后仍被 toRecord 丢弃 → filed Datasources: the admin create and edit doors drop the schema-declared ssl, autoConnect and description, so a datasource created there loses its TLS settings #28633(Datasources: the test door and every undeclared top-level key still bypass the refusal DatasourceSchema gives (the rest of #28549) #28612 的子卡,security,已派发，基于本 PR 叠加)。Metadata-protocol: none,无 Skills-docs: 欠账。
6. 落地条款:Clause-②: no (narrowing) ⇒ 契约复核达档 PASS 在案:comment 6556237821(CONTRACT_REVIEW_TIER,同 head f1438f52)。check-governed-merges --pr 28632:NOT governed,210 行。落地授权，维护者原话:「按照 pm-dispatch 规则复核过的都授权」(2026-10-25T11:35Z)。