[objectstack-fleet]

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

Requested by Leehom · project thread

Part of #28633 (the card stays open for its read-path follow-up, which closes it)

Clause-②: yes (narrowing) — measured, not the claim's expected no: POST /api/v1/datasources and PATCH /api/v1/datasources/NAME now store ssl, autoConnect and description (accepted and dropped before), GET /api/v1/datasources/NAME serves them (three new answer members), POST /api/v1/datasources/test hands the draft's ssl to the probe, and the exported DatasourceDraft, StoredDatasource, ProbeInput and ConnectivityBearingFields types gain those members. The (narrowing) arm: one body that used to answer 201 / 200 (its whole ssl block silently dropped) is now refused with 400 DATASOURCE_ADMIN_ERROR: an ssl block that carries a client private key (ssl.key). No new error code.
Metadata-protocol: none
Skills-docs: updated here — content/docs/data-modeling/drivers.mdx (the TLS bullet says the Setup doors store the block and refuse key); no page under skills/** teaches the admin request body.

BREAKING accept-set narrowing at the datasource admin doors (@objectstack/service-datasource): an inline ssl.key is refused.

Built on PR #28632 (same file, landed as 819b1017): this branch started from its head f1438f52 and has merged origin/main since, so the diff is only this change.

维护者速读

• 改了什么：数据源管理接口的创建、编辑和连接测试，现在保留 DatasourceSchema 声明的所有顶层键（ssl、autoConnect、description 以前被悄悄丢掉）。保留哪些键在运行时直接从 schema 读出，不再有手写清单；origin 和 ADR-0010 保护字段（_lock* 等）仍由服务端决定，不从请求体取。连接测试用的是保存时会存的同一份记录，所以测试也走同样的 TLS。编辑 ssl 会重建连接。
• 为什么改：卡 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：带 TLS 设置创建数据源，接口回 201，但存下来的记录没有 ssl，实际连接不加密，也没有任何提示。
• 风险与回滚：新增一个拒收：ssl.key（客户端私钥）在三个入口都被拒（400，点名不回显值），因为这个入口没有加密存放它的通道，存下来就是明文。这是一个需要您确认的取舍，见下方 Acceptance notes 第一条。读取时永不返回已存的私钥；编辑时原样回传 ssl 会保留已存的私钥。控制台、packages/client、CLI 都不发送这三个键。回滚即 revert。
• 先看：packages/services/service-datasource/src/datasource-admin-service.ts（storedDatasourceKeys、toRecord、编辑合并、inlineSslKeyRefusal、getDatasource）；src/__tests__/datasource-admin-declared-keys-kept.test.ts；src/datasource-admin-plugin.ts（探测把 ssl 交给驱动工厂）。
• 两分钟验证：pnpm --filter @objectstack/service-datasource exec vitest run src/__tests__/datasource-admin-declared-keys-kept.test.ts → 18/18 通过。
• 需要你做的：决定 ssl.key 的处理（推荐：先拒收，等有加密通道再开放）；其余席位落地（收窄需先过合约评审）。

What changes

One projection, derived from the schema (datasource-admin-service.ts). The hand list in toRecord (name, label, driver, schemaMode, config, external, pool, active) becomes storedDatasourceKeys(): every key of DatasourceSchema.shape read at run time, minus the keys the door deliberately does not take from the body, each named with its reason:

• origin — the schema's own words: "server-managed, read-only", "never accepted from client input". The door stamps runtime, as before.
• the ADR-0010 protection envelope, read off MetadataProtectionFields (_lock, _lockReason, _lockSource, _lockDocsUrl, _provenance, _packageId, _packageVersion) — set by a code package's loader only. The metadata save door refuses an authored lock for exactly this reason (ADR-0010 §3.5, authoredLockFamilyRefusal), so storing them here would be the way around that door. The seat asked to include them if the schema derivation covers them; it does, and this is the reason they are left out.

So the stored set at this head is name, label, driver, config, pool, ssl, description, active, autoConnect, schemaMode, external. A key the schema declares later is stored the day it lands.

• Create stores toRecord(input). Edit merges every patched key under the same set (name never, external keeps its credentialsRef rule). The record judgement on an edit now runs whenever the patch touches a key other than label / active (the two documented exemptions), so an ssl edit is judged by the schema's strict ssl shape before it is stored; a description / autoConnect edit is judged too.
• Test door builds one draft = toRecord(...) and both judges and probes it: ProbeInput gains ssl, and the plugin's probe hands it to factory.create (datasource-admin-plugin.ts), as the saved datasource's connect does through toSpec (ssl: record.ssl).
• Live connection. datasourceConnectivityChanged now compares ssl (toSpec reads it), so an edit that changes the TLS block rebuilds the pool; a description edit does not.
• Read. getDatasource serves ssl (without key), autoConnect and description.
• ssl.key. inlineSslKeyRefusal refuses a body whose ssl carries key, on create and edit (throw, 400 DATASOURCE_ADMIN_ERROR, under the door's existing headings) and on the test door (ok: false, like its other record refusals, nothing probed). The message names ssl.key, never the value. A stored key (a row written by another door) is withheld on read, and an edit that sends back the served block keeps it (restoreRedactedConfig's rule, applied to the one withheld member).

Tests

New src/__tests__/datasource-admin-declared-keys-kept.test.ts, same harness as #28607 / #28632 (real routes over HonoHttpServer, real DatasourceAdminService on in-memory stores, entitled-caller.fixture), recording the stored record, the record handed to registerPool / reregisterPool, and the probe input; one case drives the real DatasourceAdminServicePlugin probe over a fake driver factory and reads the spec handed to factory.create.

• Create: ssl + autoConnect + description → 201, all three stored, the record handed to registerPool carries ssl; a GET returns them; an unknown ssl member (insecure) is refused (400 DATASOURCE_ADMIN_ERROR, nothing stored).
• Edit: ssl stored and the pool rebuilt from a record carrying it; autoConnect / description stored.
• Test door: the probe receives the draft's ssl; the plugin probe hands it to the driver factory.
• ssl.key: create, edit and test refuse it (status + error.code + success, or result.ok: false; the value absent from the raw answer; nothing stored, minted, opened or probed); a GET of a row already holding a key does not serve it; an edit sending back the served block keeps the stored key.
• Controls: a draft without these keys stores exactly name, driver, config, origin as before; origin is stamped runtime and no protection field is stored; a description-only edit does not rebuild the pool; a label-only edit leaves a stored ssl alone; a test draft without ssl probes without it. fix(service-datasource)!: refuse every top-level key DatasourceSchema refuses at the datasource test, create and update doors #28632's and fix(service-datasource)!: refuse a top-level password or connectionString at the datasource admin write doors #28607's suites (25 cases) stay green.

Red first, green, ablation

• Red first (production sources restored to f1438f52, fix(service-datasource)!: refuse every top-level key DatasourceSchema refuses at the datasource test, create and update doors #28632's head, test file kept): Tests 12 failed | 6 passed (18). The six passing are the controls. The "read withholds a stored key" case is red at the base because the read serves no ssl at all, so it pins the served block, not a leak at the base.
• Green at the fix: Tests 18 passed (18).
• Ablation (node scripts/ablation-replace.mjs, the new file plus fix(service-datasource)!: refuse every top-level key DatasourceSchema refuses at the datasource test, create and update doors #28632's file, 43 cases; the tests import the service and plugin from src/, so no build sits between mutation and run), each restore proven blob == HEAD and git diff HEAD empty:
  • A1 toRecord back to the hand list: 6 failed (create/read/ssl-judged, both probe cases, test-door key refusal).
  • A2 edit merge back to the old projection: 3 failed (ssl edit, autoConnect/description edit, key carry-forward).
  • A3 / A3b / A3c the ssl.key refusal removed on create / edit / test: 1 failed each, the matching refusal.
  • A4 the read serves the stored ssl unfiltered: 1 failed (the withheld key).
  • A5 the plugin probe stops handing ssl to the factory: 1 failed.
  • A6 ssl out of datasourceConnectivityChanged: 1 failed (the edit no longer rebuilds).
  • A7 the key carry-forward removed: 1 failed.
  • A8 the protection envelope taken off the server-stamped set: 1 failed.

Acceptance notes

• Decision: ssl.key (also in the os-dev-report's open_questions). The card asks that a secret inside ssl be "redacted on read, as config secrets are today". Measured: this door does not store config secrets at all (the driver contracts refuse config.password; the credential goes through secret into the secret store and only the credentialsRef is stored), and the platform's datasource redaction covers config, not ssl. Storing ssl.key would put a private key at rest in cleartext in the datasource row, outside every redaction this package controls. This PR takes the conservative arm: refuse it at all three doors, withhold it on this door's read. Accepting it would need a spec-side change first (redaction of ssl.key wherever datasource rows are read, or a sealed channel for it), which is the spec lane's; the seat has the detail.
• The protection envelope is still dropped, not refused. Left out of the stored set by design (above). Refusing an authored lock family, as the /meta save door does, would be a further narrowing of this door, so it is reported rather than done here.
• The probe still omits pool and schemaMode from the spec it hands the factory, as before; neither changes whether or how the connection is encrypted, and the card asks for ssl.
• Producers measured (order's stop-and-report check): none relies on the drop. The Console form (ui/packages/app-shell/src/views/metadata-admin/datasource/) sends label, driver, schemaMode, config, external, secret and never these three keys; packages/client has no create/update/test method; the CLI datasource commands are read-only.
• The Datasources: the test door and every undeclared top-level key still bypass the refusal DatasourceSchema gives (the rest of #28549) #28612 changeset names description, ssl and autoConnect among the keys "the doors do not store"; it is not edited, and this PR's changeset carries the superseding sentence.

Verification

All readings on head 1599499f (the merge of origin/main at 68a2a216, after #28632 landed as 819b1017; the diff against main is the seven files of this change).

• Package: pnpm --filter @objectstack/service-datasource test → Test Files 68 passed (68), Tests 1143 passed (1143). pnpm --filter @objectstack/service-datasource typecheck exit 0; tsc --listFiles includes the new test file.
• Derived gate families: node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack → 91 families (61 before the docs line; the drivers.mdx edit adds the docs families), each run after a full pnpm build --concurrency=2 (117/117) with its exit code captured before any pipe and stdin from /dev/null: 91 × exit 0. check-plugin-teardown-shape.mjs --self-test first answered exit 3 (shallow clone, fixture commit absent) and exit 0 after git fetch --depth=1 of that commit. --ran: ✓ dispatch-gates --ran: 91 derived famil(ies) accounted for — 91 run, 0 NOT-MEASURED.
• Hand gates: node scripts/check-commit-card-trailers.mjs --range origin/main..HEAD exit 0; node scripts/check-platform-checklist.mjs --changed-from origin/main exit 0 (1 anchored file, 2 anchors judged, 0 lost); pnpm exec eslint --no-inline-config packages/services/service-datasource exit 0, no findings; control-byte scan of the changed files: no hits. The repo-wide pnpm lint is CI's.
• Full dogfood (owed by the ! and the (narrowing) arm), after the full build, under the lock, pnpm --filter @objectstack/dogfood test → Test Files 1 failed | 366 passed | 3 skipped (370), Tests 1 failed | 2965 passed | 28 skipped (2994). The one failure is not this change and is the same one fix(service-datasource)!: refuse every top-level key DatasourceSchema refuses at the datasource test, create and update doors #28632 recorded: route-ledger-live-mount-parity.dogfood.test.ts reports runtime/route-ledger.ts: GET /packages/:id/customizations — LEDGERED BUT NOT MOUNTED, a runtime route from feat(runtime,spec): GET /packages/:id/customizations answers a base's overrides, extensions and switched-off items in one read #28595 (519089e1) on main. This diff touches only service-datasource and one docs page.
• CI families (Test Core incl. test:repo, the lint farm, the type-check lanes) are read off this PR's check-runs by the seat.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FEkQ5oV7AGmgEqUAMoY7y9

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/data-modeling/drivers.mdx (via schemaMode (literal, a string literal in ConnectivityBearingFields; a string literal in RECORD_JUDGED_PATCH_KEYS; a string literal in getDatasource))
• content/docs/data-modeling/external-datasources.mdx (via autoConnect (symbol, a field of interface DatasourceDraft), autoConnect (literal, a string literal in getDatasource), schemaMode (literal, a string literal in ConnectivityBearingFields; a string literal in RECORD_JUDGED_PATCH_KEYS; a string literal in getDatasource))
• content/docs/data-modeling/odata-datasources.mdx (via schemaMode (literal, a string literal in ConnectivityBearingFields; a string literal in RECORD_JUDGED_PATCH_KEYS; a string literal in getDatasource))
• content/docs/data-modeling/virtual-objects.mdx (via schemaMode (literal, a string literal in ConnectivityBearingFields; a string literal in RECORD_JUDGED_PATCH_KEYS; a string literal in getDatasource))
• content/docs/deployment/cli.mdx (via autoConnect (symbol, a field of interface DatasourceDraft), autoConnect (literal, a string literal in getDatasource))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-6.mdx (via schemaMode (literal, a string literal in ConnectivityBearingFields; a string literal in RECORD_JUDGED_PATCH_KEYS; a string literal in getDatasource))
• content/docs/releases/v18/18-1.mdx (via schemaMode (literal, a string literal in ConnectivityBearingFields; a string literal in RECORD_JUDGED_PATCH_KEYS; a string literal in getDatasource))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 214 client-bound route-ledger rows — the other 154 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 154: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 99 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 3 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 6b9c1ca99144b1c96ef05041dd3b0319e43d8f4b → packageMentionDocs.

Which tree this was computed on

This run read content/docs from bbad38ebabf8746563072bdfa92db8dca339b39a — the merge of head 1599499f3dc5ad6303a7233fd1acef153f0cbe8d into base 6b9c1ca99144b1c96ef05041dd3b0319e43d8f4b, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

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

node scripts/docs-audit/affected-docs.mjs --json 6b9c1ca99144b1c96ef05041dd3b0319e43d8f4b

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

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 6b9c1ca99144b1c96ef05041dd3b0319e43d8f4b → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

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

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 1599499f3dc5ad6303a7233fd1acef153f0cbe8d
Local-runs: none
Scope: packages/services/service-datasource/src/datasource-admin-service.ts, packages/services/service-datasource/src/datasource-admin-plugin.ts, packages/services/service-datasource/src/datasource-connectivity-change.ts, packages/services/service-datasource/src/contracts/datasource-admin-service.ts, packages/services/service-datasource/src/tests/datasource-admin-declared-keys-kept.test.ts + packages/spec/src/data/datasource.zod.ts (DatasourceSchema, its ssl shape, origin), packages/spec/src/kernel/metadata-protection.zod.ts (MetadataProtectionFields), packages/spec/src/shared/lazy-schema.ts and strict-object.ts (.shape on the lazy proxy), packages/spec/src/data/driver/common.zod.ts (INLINE_CREDENTIAL_REFUSED, the #7990 rule), packages/spec/src/data/datasource-credential-redaction.ts, packages/spec/src/api/error-code-ledger.zod.ts, packages/services/service-datasource/src/default-datasource-driver-factory.ts (resolveSslOption), packages/services/service-datasource/src/datasource-connection-service.ts (toSpec), packages/services/service-datasource/src/contracts/datasource-driver-factory.ts (DatasourceConnectionSpec.ssl), packages/services/service-datasource/src/admin-routes.ts, ui/packages/app-shell/src/views/metadata-admin/datasource/DatasourceResourcePage.tsx (draftBody, testDraft), packages/client/src, packages/cli/src/commands/datasource, .changeset/28612-datasource-undeclared-top-level-key.md (read, not reviewed). Prose faces (.changeset/28633-datasource-admin-declared-keys.md, content/docs/data-modeling/drivers.mdx) not reviewed.

Inputs read: card #28633 (body, claim 6556196859, os-dev-report 6557222993, claim amendment 6557238812 with the seat's ruling), parent #28612, PR #28648 body, file list and net diff against main, the head's check-runs, and the cited code at origin/main and at the head.

Check-runs on the head, read honestly: every completed run is success or skipped (Check Changeset, Governed Surface Queue Guard, PR-body guards, Lint · PM dispatch-gates, Lint · scoped · tooling self-tests, Spec property liveness, Type Check · debt ledger, Dogfood Regression Gate, Test UI, Auto Label, Check PR Size, Check Documentation Links, Flag docs affected). Still in_progress at the time of this read: Build Core, Build Docs, Test Core 1–8, Lint · ESLint, Lint · CI/release/engine gates, Lint · docs & code guards, Lint · repo & tooling gates, Lint · scoped · query-options erasure, Lint · scoped · slot lookup & corpus, Type Check · workspace, Type Check · source gates, Type Check · consumer gates, Live E2E UI. No completed run is red. The dev's local readings on this head (package suite 1143/1143, typecheck 0, 91/91 derived families, full dogfood with the one pre-existing route-ledger-live-mount-parity failure from #28595 on main, not this diff) are consistent with what has completed; the seat re-reads the in-progress families before the queue.

① Derived judgments

Each accept-set or public-surface change the diff implies, named right or wrong against the cited code:

1. Kept set derived from the schema, no second hand list — right. storedDatasourceKeys() reads Object.keys(DatasourceSchema.shape) at run time (the lazy proxy forwards .shape; strictObject is a zod-4 z.object(...).strict(), and the .superRefine keeps .shape, which the new premise test and the existing assertNoUndeclaredTopLevelKey also rely on) minus SERVER_STAMPED_KEYS = origin + Object.keys(MetadataProtectionFields). Both subtractions are read off the spec's own declarations, not transcribed. The only literals are origin (the schema's "never accepted from client input") and the ssl.key member name. Stored set at this head: name, label, driver, config, pool, ssl, description, active, autoConnect, schemaMode, external — matches the schema on origin/main. Right.
2. Create stores ssl/autoConnect/description — right. toRecord = storedKeysOf(input) + name + driver; assertValidRecord still judges the whole record (the strict ssl shape refuses insecure; null for an optional object is refused by zod), so nothing is stored unjudged.
3. Edit merges every stored key; record judged unless label/active-only — right. RECORD_JUDGED_PATCH_KEYS (allow-list) becomes RECORD_JUDGE_EXEMPT_PATCH_KEYS (label, active). Same exemption as before, now derived; an ssl/description/autoConnect patch is judged by the schema. external keeps its credentialsRef rule. The judgement runs on the merged record BEFORE the ssl.key carry-forward, so a stored key never enters a refusal message. Right.
4. ssl.key carry-forward on edit — right, with one limit (④ should-fix 2). A patched ssl block without key over a row holding one keeps the stored key; the test pins it. It creates no key (the door refuses an inline one first). Consequence: this door cannot remove a stored key, even with enabled: false (the factory then returns false, so the key is inert at connect time but stays at rest).
5. Read serves ssl (key withheld), autoConnect, description — right. servableSsl drops the one member; toSummary (list, create/update answers) serves none of the three. The withheld key does not reach the raw body (test pins raw not containing the placeholder).
6. Test door probes from the same projection — right. draft = toRecord(...), key refusal, record refusal, then probe({ driver, config, external, ssl, timeoutMs }) all from draft. The plugin probe hands ssl to factory.create under the same key toSpec uses (ssl: record.ssl), so resolveSslOption reads it identically for a probe and a saved connect. ProbeInput.ssl, DatasourceDraft.ssl, StoredDatasource.ssl and DatasourceConnectionSpec.ssl are all the same Record of string keys to unknown values — consistent.
7. Connectivity comparison includes ssl — right. datasourceConnectivityChanged deep-compares before.ssl/after.ssl; ConnectivityBearingFields gains 'ssl' (an exported type, additive). The plugin's peer-convergence compare (livePoolRecords holds the record handed to the pool, key included) and the admin door's compare see the same shape, so a round-trip of the served block over a row with a key compares equal after the carry-forward — no spurious rebuild; a real TLS change rebuilds; a description edit does not.
8. Inline ssl.key refused at create, edit and test — implemented as declared. Refused by name (ssl.key), never by value; thrown at the write doors (route maps to 400 DATASOURCE_ADMIN_ERROR, registered in error-code-ledger.zod.ts under this package; no new code), returned as ok: false at the test door like its other record refusals. Checked after the undeclared-key check and before anything is read, written, minted or probed. Whether this narrowing is right is ④'s question.
9. Secret-bearing members of ssl. The schema declares enabled, rejectUnauthorized, ca, cert, key only — key is the one secret-bearing member; there is no passphrase. ca/cert are public material and are stored and served. Nothing in this diff logs a record or a spec (the only JSON.stringify(record) is the sys_metadata persist, i.e. the store itself). Pubsub payload is name only.
10. Server-stamped keys — right. A body origin: 'code' plus _lock/_lockReason/_provenance/_packageId stores origin: 'runtime' and none of the protection fields (test pins it). Dropped silently, not refused — flagged by the dev, ③.
11. Producers. DatasourceResourcePage.tsx draftBody sends label, driver, schemaMode, config, optional external: {} and secret; testDraft sends driver, config, secret. Neither sends ssl, autoConnect or description, and an edit does not spread the GET answer back. packages/client has only the datasources.external.* federation routes; the CLI datasource commands are read-only federation calls. No test or dogfood fixture posts ssl to the admin doors. No producer loses a path. Right.
12. Exported type members. DatasourceDraft (+ssl, autoConnect, description), StoredDatasource (+ssl, description; autoConnect was already declared), ProbeInput (+ssl), ConnectivityBearingFields (+'ssl'), getDatasource return Pick (+ the three) — all optional/additive and declared consistently with the doc comments. The UI test DatasourceResourcePage.externalBlock-11368.test.tsx names the retired RECORD_JUDGED_PATCH_KEYS in a comment over its own local model; it does not import it, so nothing breaks (cosmetic).

② Semver level

Changeset .changeset/28633-datasource-admin-declared-keys.md: @objectstack/service-datasource: patch, fix(...)!: title, Clause-②: yes (narrowing) and Metadata-protocol: none as line-initial declarations, one adr-0087: not-required (no-migration-prescription) marker, the BREAKING banner, and the remedy (leave ssl.key out). The PR body carries the same two declaration lines. Under the repo rule a non-protocol change, widening or breaking, ships patch with its BREAKING banner and ADR-0087 disposition; Metadata-protocol: none is right because no key an author writes under packages/spec changes (the spec is untouched; the doors store keys it already declares). The "at most one arm" form holds (yes (narrowing); the widening — three served members and four type members — is described in prose, as the rule allows). The ADR-0087 reasoning holds: a refused ssl.key body was never stored because the whole block was dropped, so nothing at rest needs a migration. Level and declarations: right.

Clause-②: yes (narrowing) — matches the amendment 6557238812 and what the diff publishes.

③ Boundary flags

• Dev open_questions 1 — store or refuse an inline ssl.key. Ruled by the seat in amendment 6557238812: option A as implemented (refuse at three doors, store enabled/rejectUnauthorized/ca/cert, withhold a stored key on read, keep it across an edit). Grounds recorded there: no secret value stored or served in the clear, zero measured producers, reversible once a sealed channel is ruled. Answered. The design reading of A against the published spec is ④ should-fix 1.
• Dev out-of-scope finding b (security, class b) — a stored ssl.key on a datasource row is not covered by the platform datasource redaction outside this door. Confirmed in the cited code: datasource-credential-redaction.ts names config keys only and no ssl member. Pre-existing, not this diff; a read path outside this PR's scope needs a redaction review. Carrier named by the dev: server seat 3, spec lane, off GitHub. Escalated, not re-described here.
• Dev out-of-scope finding c — the ADR-0010 protection envelope is dropped silently at these doors rather than refused as the /meta save door refuses an authored lock family. Confirmed (①10). A further narrowing of this door; correctly reported rather than done here. No carrier named; the seat decides whether to file it.
• PR Acceptance note — probe still omits pool and schemaMode. Pre-existing, neither changes the encryption of the connection; not this card's wanted set. Noted.
• PR Acceptance note — the Datasources: the test door and every undeclared top-level key still bypass the refusal DatasourceSchema gives (the rest of #28549) #28612 changeset sentence naming description/ssl/autoConnect among keys "the doors do not store" is superseded by this changeset's line, not edited. Acceptable (a shipped changeset is a record).
• Test door refusal shape. The ssl.key refusal answers 200 with result.ok: false while the undeclared-key check on the same door throws 400. Both conventions pre-exist on that door (config and record refusals already answer ok: false); consistent with the door, not a new flag.
• No Metadata-protocol flag; no packages/spec path touched, as the claim requires.

④ Design judgment

The narrowing, read against the published spec on main and the cited code. DatasourceSchema.ssl.key is declared ("Client private key (PEM format or path to file)"), and it is delivered: resolveSslOption hands block.key to pg/mysql2, and toSpec reads record.ssl for every saved datasource, so a code-defined row's key reaches the client today. The admin door is a write consumer of that schema. Refusing ssl.key there is therefore a narrowing of a declared, delivered capability at one consumer, not the spec's own refusal made real: the spec refuses an inline config.password by key (INLINE_CREDENTIAL_REFUSED, the #7990 maintainer-ruled rule — a datasource artefact is persisted whole into sys_metadata, so an inline credential is cleartext at rest) but says nothing of the kind for ssl.key, which is the same class of material in the same row.

I tried to break the alternative. Storing it (option B) puts a private key at rest in cleartext in the datasource row, read back by paths the package's redaction does not cover (③) — the exact defect #7990 ruled against for passwords — so delivering the capability as declared would reintroduce a security defect, and binding it through the secret store (C) is spec surface this card is barred from. Within the card's surface the refusal is the only safe arm, the seat has ruled it, it is loud (named, never echoed), and no producer sends the key. So the narrowing is justified at this door today, but it is incomplete as a design: the spec and the door now disagree (os compile and the code-defined route accept a datasource with ssl.key; the Setup door refuses it), and the spec's own rule for secret material has not been applied to this member.

• Should-fix 1 (spec lane, not this PR): make the refusal the spec's own, as [security] sys_metadata.metadata is a general cleartext sink: any authored artefact whose schema permits an inline credential lands it there (datasource config.password, connector authentication) #7990 did for config.password — either retire the inline ssl.key value at DatasourceSchema with a prescription (the sealed route: a secret-store handle or the code-defined environment route, and a file path if the factory is to honour one), or declare the sealed channel — so the door's refusal becomes the spec's refusal made real rather than a consumer-side narrowing. Until then this PR's refusal is the correct interim arm and is reversible. Not a must-fix: the only alternative inside this PR's lane is the security defect.
• Should-fix 2 (same follow-up): the carry-forward makes a stored key un-removable through this door (①4); the sealed-channel ruling should also say how a key is cleared.
• Reading, not a finding against this PR: the spec's "or path to file" for ca/cert/key is not delivered by resolveSslOption, which hands the string to the client as PEM content; a pre-existing spec-versus-factory gap for the spec lane's list.
• No must-fix. The kept set is truly schema-derived; no secret-bearing ssl member is stored, echoed, served or logged by this diff; the key withheld on read is kept across an edit and cannot surface through this door's answers, refusals or summaries; the factory and the connectivity compare treat ssl the same way for a probe, a save and a peer convergence; the refusal code is already ledgered; no producer sends ssl; the new members are declared consistently; the changeset level is right.

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

VERDICT: PASS

[objectstack-fleet]

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

席位核对 · ACCEPT · PR #28648 · 2026-11-01T11:37Z

Head-sha: 1599499f3dc5ad6303a7233fd1acef153f0cbe8d

维护者速读(席位终稿)

• 改了什么:数据源管理的创建、编辑、连接测试，现在保留 DatasourceSchema 声明的所有顶层键(ssl、autoConnect、description 以前被悄悄丢掉)。保留哪些键在运行时从 schema 读出，没有手写清单;origin 与 ADR-0010 保护字段仍由服务端决定。测试与保存用同一份记录，编辑 ssl 会重建连接。
• 为什么改:带 TLS 设置创建数据源答 201,存下的记录却没有 ssl,实际连接不加密且无提示(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)。
• 风险与回滚:新增一个拒收：内联的 ssl.key(客户端私钥)在三个入口被拒(400,点名不回显),因为此入口没有加密存放通道，存下即明文。读取永不返回已存私钥;编辑回传 ssl 会保留已存私钥。控制台、client、CLI 都不发这三个键。回滚即 revert。
• 先看:datasource-admin-service.ts 的 storedDatasourceKeys、toRecord、编辑合并、inlineSslKeyRefusal;datasource-admin-plugin.ts 探测把 ssl 交给驱动工厂。
• 两分钟验证:pnpm --filter @objectstack/service-datasource exec vitest run src/__tests__/datasource-admin-declared-keys-kept.test.ts → 18/18。
• 需要你做的:无。ssl.key 先拒收由席位裁定(认领修订 6557238812,选项 A),可逆：有加密通道的裁决后再开放。
• 席位意见:契约复核 PASS;TLS 设置真正生效，私钥不落明文。可落。

核对六项

1. 形态:draft → main;席位已把正文的 Fixes #28633 改为 Part of #28633:本 PR 交付卡的三项期望，但卡留给读路径脱敏的后续(认领修订 6557268469),由那个 PR 关卡。其余闭合关键词零命中(已扫)。文件 7 个，在修订后的申报面内。
2. 前提实测:红先在 fix(service-datasource)!: refuse every top-level key DatasourceSchema refuses at the datasource test, create and update doors #28632 head f1438f52 上 12/18 红(6 个对照通过);消融 A1–A7 各自转红(手写清单 6 红、旧编辑合并 3 红、三门 ssl.key 拒收各 1 红、读取回显 1 红、探测丢 ssl 1 红、连接比较漏 ssl 1 红、私钥沿用 1 红),复原后 blob 回 HEAD。
3. 门禁:本 head check-runs 54 个,40 success、14 skipped、0 失败,mergeable clean。dev 本地 1599499f:91/91 派生门禁 exit 0,包测 1143/1143。dogfood 1 红为已知 route-ledger-live-mount-parity(feat(runtime,spec): GET /packages/:id/customizations answers a base's overrides, extensions and switched-off items in one read #28595 / p0 main red: Dogfood Regression Gate — GET /packages/:id/customizations is ledgered but not mounted (#28595), so the route 404s at runtime #28622),不归本 PR。
4. 接受的偏差:实测 Clause-②: yes (narrowing),非认领预期的 no,认领已修订;保护字段由 schema 派生但不存储(ADR-0010 §3.5,/meta 保存门拒收作者写入的锁),理由在 PR 正文，接受。
5. 范围外去向:契约复核 should-fix ①(spec 应自带内联 ssl.key 的拒收或密封通道，使 compile 与本入口一致)与 ②(经本入口无法清除已存私钥)待密封通道裁决时一并处理，记为 Acceptance notes;③(ca/cert/key 的「文件路径」未兑现)为既有问题，仅记录。读路径脱敏 → 已派发，将以 Fixes #28633 关卡。Metadata-protocol: none,无 Skills-docs: 欠账。
6. 落地条款:Clause-②: yes (narrowing) ⇒ 契约复核达档 PASS 在案:comment 6557315933(CONTRACT_REVIEW_TIER,同 head 1599499f)。check-governed-merges --pr 28648:NOT governed,548 行。落地授权，维护者原话:「按照 pm-dispatch 规则复核过的都授权」(2026-10-25T11:35Z)。