[objectstack-fleet]

Requested by Steve · project thread
Fixes #28738

Clause-②: no (narrowing)
Metadata-protocol: narrowed
Skills-docs: none — the published skills' connector recipes (skills/objectstack-automation/references/integration-recipes.md) author declared keys only and say nothing about the helper's key posture, so no skill text turns false.

维护者速读

• 改了什么:defineConnector() 改为解析闭合的连接器形状;写了未声明的顶层键会当场报错并点名,附处方(凭据类键指向 auth.credentialRef,提供方设置指向 providerConfig,timeout 指向 requestTimeoutMs)。
• 为什么改:它原来解析开放的 ConnectorSchema,先把未声明的键悄悄丢掉,defineStack 等闭合门再也看不到,作者放错位置的设置(比如把 timeout 写在根上)无声丢失。现在它和其它所有连接器入口一样响亮拒收。
• 风险与回滚:属于收窄(破坏性)。仓内 7 处调用和文档示例都只写已声明键,不受影响;第三方若在 defineConnector 里写了未声明键,加载时会报错。插件给 registerConnector 的定义不变。回滚只需把 defineConnector 函数体改回 ConnectorSchema.parse。
• 先看:packages/spec/src/integration/connector.zod.ts 的 DefineConnectorSchema 与 defineConnector 函数体;connector-entry-undeclared-keys.test.ts 新增的一组测试;.changeset/harden-connector-undeclared-keys.md 改动的那一句。
• 两分钟验证:pnpm --filter @objectstack/spec exec vitest run src/integration/connector-entry-undeclared-keys.test.ts,应看到 24 条全过。
• 需要你做的:在本 PR 上书面确认对 feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object auth #28688 待发 changeset 那一句的更正(Check Changeset 因此保持红,它不是必需检查,不挡合并)。

What changes

• defineConnector() (@objectstack/spec, @objectstack/spec/integration) parses a module-private DefineConnectorSchema: the closed carrier DeclarativeConnectorEntryBaseSchema behind the same retired-default residue stage (CONNECTOR_RETIRED_KEY_RESIDUE) that ConnectorSchema and DeclarativeConnectorEntrySchema use. An undeclared top-level key now throws a ZodError with one unrecognized_keys issue at the root, carrying the entry's own message, aliases and guidance. The signature is unchanged: input z.input of ConnectorSchema, return ConnectorParsed; check:api-surface and the rest of check:generated needed no regeneration.
• ConnectorSchema (the def a plugin hands to registerConnector) keeps its open posture; option C of the card is not taken.
• The helper does not apply the stack-only ADR-0097 / ADR-0143 refinements of DeclarativeConnectorEntrySchema (no inline authentication, providerConfig / auth need a provider, no actions on a provider-bound instance, the oauth2 / signed instance rules). Every stack door still applies them to the value the helper returns. See the Acceptance notes for why, and the measured fact that the two choices agree on every in-repo caller.
• The ADR-0087 entry connector-entry-undeclared-key-refused (landed with feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object auth #28688, not yet released) now names defineConnector() in its surface and reason. This PR's changeset disposes as not-required (already-registered connector-entry-undeclared-key-refused).
• Docblocks in connector.zod.ts and the integration/ row of docs/audits/2026-07-unknown-key-strictness-ledger.md stop saying the helper parses the open shape.

A pending release note this PR corrects

.changeset/harden-connector-undeclared-keys.md (from #28688, still pending) said: "ConnectorSchema — the def a plugin hands to registerConnector, and the shape defineConnector() parses — keeps its posture." This PR makes the defineConnector() half false, so the clause is removed and the sentence now reads "ConnectorSchema — the def a plugin hands to registerConnector — keeps its posture." check-empty-changeset refuses this edit by design (the DELIBERATE CORRECTION class), so Check Changeset stays red until a maintainer confirms the correction here in writing. It is not a required context.

Tests

New describe block in packages/spec/src/integration/connector-entry-undeclared-keys.test.ts (12 cases; the file had 12): for an instance and a descriptor, each refusal pinned by code, path and keys on the thrown ZodError, the value never echoed; timeout → requestTimeoutMs with the declared spelling as control; the credentialRef and providerConfig guidance; the helper's issue equal to the stack door's issue on the same entry; residue (status: 'inactive') and the ADR-0010 envelope still accepted; and a pin that the helper applies no stack-only refinement. Forced test edits: none; no existing test changed.

Ablation at 4185e6a (node scripts/ablation-replace.mjs, body put back to ConnectorSchema.parse(config), anchor 1 → 0, restored blob equal to HEAD): 7 failed | 17 passed (24). The 7 are exactly the refusal cases; controls, residue, envelope and the no-refinement pin pass on both sides, as they should.

Readings (packages/spec and the consumers that import defineConnector)

• @objectstack/spec test at f668513: Test Files 788 passed (788), Tests 23279 passed, 1 todo. Typecheck (incl. check:test-typecheck): exit 0.
• @objectstack/spec src/integration/ at bb3b9bc: Test Files 14 passed (14), Tests 264 passed. check:generated at bb3b9bc: all 14 artifacts up to date.
• Consumers, found by git grep "defineConnector(", closure built first (turbo run build, 65 tasks), at f668513:
  • @objectstack/example-showcase (4 calls): typecheck exit 0; Test Files 42 passed (42), Tests 511 passed.
  • @objectstack/connector-app-github (1 call): Test Files 2 passed (2), Tests 13 passed; typecheck exit 0.
  • @objectstack/connector-app-stripe (1 call): Test Files 2 passed (2), Tests 19 passed; typecheck exit 0.
  • @objectstack/downstream-contract (source-resolution identity pin on both import paths): Test Files 3 passed (3), Tests 31 passed; typecheck exit 0.
• Full dogfood (pnpm --filter @objectstack/dogfood test, no shard, at f668513): VERDICT command-exit 0; Test Files 377 passed, 3 skipped (380); Tests 3101 passed, 28 skipped. One named skip is print-service-render (no built Console on this host).
• The final commit bb3b9bc edits one docblock line. The rebuilt packages/spec/dist at bb3b9bc equals the dist the dogfood run read (f668513): 360 of 360 non-map files byte-identical once esbuild's chunk-hash names are normalized. So the dogfood reading carries to the final head.

Acceptance notes

• Why the closed base, not the full entry schema. The card's option B says the helper "parses the closed twin". The full DeclarativeConnectorEntrySchema would also refuse an inline non-none authentication and the other stack-only rules at the helper. That would break any plugin code that builds a registerConnector def through defineConnector, which is the code-to-code break option C was kept out of this card for. Measured: all 7 in-repo callers and all 5 os:check blocks in content/docs/automation/connectors.mdx give the same verdict under either choice, so the choice changes nothing in this repo. It is listed as an open question for the seat.
• The helper's ZodError message is the strict entry's message, because the parse runs through the same strictObject carrier. It says "this connector entry", which fits the documented use.
• content/docs/releases/v17/17-6.mdx names defineConnector among the doors that refuse retired keys. That is release-owned and still true; not touched.

Verification

Gate list derived by node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack (84 commands) and run at the final head bb3b9bc; reconciled with --ran (exit codes recorded): 84 derived, 84 run, 0 NOT-MEASURED, 0 UNRUN. 83 exit 0. One is red by design: node scripts/check-empty-changeset.mjs --base origin/main exit 1, the DELIBERATE CORRECTION class above.

Gate notes

• An earlier sweep at f668513 had two exit-3 prerequisites, both met before the final sweep: check-plugin-teardown-shape.mjs --self-test needed its pinned fixture commit in the shallow clone (fetched; exit 0, 48 cases), and pnpm check:dual-build-cjs-loads needed 7 packages built (built; exit 0, 115 require entry points across 70 packages load).
• check-adr-0087-registration.mjs --base origin/main: exit 0. The new changeset reads [BREAKING+bang+clause-②-narrowing+metadata-protocol-narrowed], disposition not-required (already-registered).
• Local-only pnpm check:dev-prereqs: exit 1. It reads this host's build state (35 ui/ packages with no dist), not this diff. Reported, not acted on.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic.
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes: eslint on the changed files exits 0 locally; the repo-wide run is CI's.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed (none were stale).
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 3 documentable anchor(s).

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

• content/docs/automation/connectors.mdx (via defineConnector (symbol, a top-level function), /meta/connector/:name (route, a path literal in surface))
• content/docs/kernel/cluster.mdx (via /meta/connector/:name (route, a path literal in surface))

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

• content/docs/releases/v17/17-6.mdx (via defineConnector (symbol, a top-level function), /meta/connector/:name (route, a path literal in surface))

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

• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 216 client-bound route-ledger rows — the other 156 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 156: 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; 101 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 — 168 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 70bf43438509ca57a2b18c35c77c735f2ec57beb → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 468b9519489a18f417ec41daed57e4f4fe2c6296 — the merge of head bb3b9bc4d400421a7d6f81b1160c1de483bad2eb into base 70bf43438509ca57a2b18c35c77c735f2ec57beb, 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 468b9519489a18f417ec41daed57e4f4fe2c6296 && git checkout 468b9519489a18f417ec41daed57e4f4fe2c6296
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 70bf43438509ca57a2b18c35c77c735f2ec57beb bb3b9bc4d400421a7d6f81b1160c1de483bad2eb && git checkout -B drift-repro 70bf43438509ca57a2b18c35c77c735f2ec57beb && git merge --no-ff bb3b9bc4d400421a7d6f81b1160c1de483bad2eb

node scripts/docs-audit/affected-docs.mjs --json 70bf43438509ca57a2b18c35c77c735f2ec57beb

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

[objectstack-fleet]

domain:spec#1 · os-steve · session_01ADHkmPi25XXKx92Xmg4viS

Head-sha: bb3b9bc4d400421a7d6f81b1160c1de483bad2eb · read 2026-11-01T21:32Z

维护者速读

• 改了什么:defineConnector() 改为解析闭合的连接器形状，写了未声明的顶层键会当场报错并点名，附处方(凭据类键指向 auth.credentialRef,提供方设置指向 providerConfig,timeout 指向 requestTimeoutMs)。
• 为什么改：它原来解析开放的 ConnectorSchema,先把未声明的键悄悄丢掉，后面所有闭合的入口都看不到，作者放错位置的设置会无声丢失。现在它和其它连接器入口一样响亮拒收。
• 风险与回滚：属于收窄。仓内 7 处调用和文档示例都只写已声明的键，不受影响;插件交给 registerConnector 的定义不变。回滚只需把函数体改回 ConnectorSchema.parse。
• 先看:packages/spec/src/integration/connector.zod.ts 里的 DefineConnectorSchema 和 defineConnector。
• 两分钟验证:pnpm --filter @objectstack/spec exec vitest run src/integration/connector-entry-undeclared-keys.test.ts。
• 需要你做的：无。PR 正文说要你书面确认对 feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object auth #28688 待发 changeset 那一句的更正，按落地规则这由同 head 的契约复审 PASS 记录确认，不用你动手。这张收窄需要一次契约复审档复核，已按常设口径交分诊，PASS 且 CI 全绿后席位落地。

席位意见：可落地，等契约复审。实现只换了解析用的 schema,签名和返回类型不变，没新增导出;选闭合基形而非完整的 stack 条目 schema 是对的，后者会连带拒收插件定义上的内联 authentication,那是卡里明确不做的选项 C。

席位核对 — ACCEPT · domain:spec#1 · head bb3b9bc4

1. Shape: draft, base main, first line Fixes #28738, no other closing keyword. Files (6) sit inside the claimed surface: connector.zod.ts + its test, the ADR-0087 semantic entry 18, two changesets, and the integration/ row of the strictness ledger. Not governed; +180/-13.
2. Premise, measured: defineConnector now parses a module-private DefineConnectorSchema = acceptRetiredDefaultResidue(DeclarativeConnectorEntryBaseSchema, CONNECTOR_RETIRED_KEY_RESIDUE); ConnectorSchema and its open base are untouched; the signature and ConnectorParsed return type are unchanged; no export is added.
3. Gate check-runs (pinned to head bb3b9bc4): at reading 12 success, 8 skipped, 21 running, 1 failure: Check Changeset, red by design (below). Landing needs every other check green or an expected skip.
4. Accepted deviations: ① Clause-②: no (narrowing) in the PR body and changeset, the spelling check-changeset-no-major requires beside narrowed; the claim line is amended to match (6562978018). ② The PR rewrites one clause of feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object auth #28688's pending .changeset/harden-connector-undeclared-keys.md: before "ConnectorSchema — the def a plugin hands to registerConnector, and the shape defineConnector() parses — keeps its posture."; after "ConnectorSchema — the def a plugin hands to registerConnector — keeps its posture." The removed clause is false after this diff, so the correction is right; it changes code too, so per the DELIBERATE CORRECTION rule the confirmation is the same-head contract-review PASS, which must judge this sentence. Check Changeset is not required and is red only for this reason. ③ The dev's open question (closed base vs full DeclarativeConnectorEntrySchema): closed base accepted; the full schema adds stack-only ADR-0097/ADR-0143 rules (it would refuse inline authentication on plugin-style defs, option C territory), and the dev measured all 7 in-repo callers passing both.
5. Out of scope: none filed. Skills-docs: none — … reason checked against skills/objectstack-automation/references/integration-recipes.md (declared keys only). Prose faces read line by line: the ledger row's last two sentences and the semantic entry's surface/reason text match the diff.
6. Landing: owes one CONTRACT_REVIEW_TIER review of the non-prose diff (narrowing face) on this head, which also confirms ②; handed to triage (line below). After a PASS and all checks green except the by-design Check Changeset, the seat readies and queues it through the relay. A head move voids this record.

Contract-review-handoff: triage — CONTRACT_REVIEW_TIER unavailable (maintainer standing word 2026-10-28T15:04Z: the Fable quota is short, so contract reviews wait for triage) · head bb3b9bc

[objectstack-fleet]

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Contract-review-claim: session_01AavokzJ5DndAwitDXvKy4U · head bb3b9bc4d400421a7d6f81b1160c1de483bad2eb · 2026-11-01T21:35Z

Taken on the lane's Request: contract-review doorbell (#28646, 6564203853). Face schema + narrowing, so the review runs at CONTRACT_REVIEW_TIER with ④. It covers the DELIBERATE CORRECTION of .changeset/harden-connector-undeclared-keys.md too.

---

Generated by Claude Code

[objectstack-fleet]

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: bb3b9bc4d400421a7d6f81b1160c1de483bad2eb
Local-runs: none
Scope: packages/spec/src/integration/connector.zod.ts, packages/spec/src/migrations/entries/semantic/18.connector-entry-undeclared-key-refused.ts, packages/spec/src/integration/connector-entry-undeclared-keys.test.ts, docs/audits/2026-07-unknown-key-strictness-ledger.md + packages/spec/src/shared/strict-object.ts, packages/spec/src/shared/retired-key.ts, packages/spec/src/kernel/metadata-protection.zod.ts, packages/spec/src/kernel/metadata-read-decorations.ts, packages/spec/src/index.ts, packages/services/service-automation/src/plugin-extension-api.ts (registerConnector), examples/app-showcase/src/system/connectors/index.ts, packages/apps/connector-github/src/connectors/github.connector.ts, packages/apps/connector-stripe/src/connectors/stripe.connector.ts, packages/qa/downstream-contract/test/source-resolution.pin.test.ts, content/docs/automation/connectors.mdx, skills/objectstack-automation/references/integration-recipes.md, skills/objectstack-automation/evals/integrations-declared.json; the two changesets are judged for the DELIBERATE CORRECTION only.

Face: schema (two packages/spec/src/** non-test hits) plus narrowing (Clause-②: no (narrowing) and Metadata-protocol: narrowed on the PR body and on .changeset/28738-define-connector-closed.md). On the narrowing face the floor is every non-prose path of the diff, so the test file is in scope too. Net diff against main at 70bf43438509ca57a2b18c35c77c735f2ec57beb: 6 files, +180/-13. Author objectstack-fleet[bot], so no external-author note is owed.

① Derived judgments

1. What defineConnector() now refuses. Before: return ConnectorSchema.parse(config), the open carrier (z.object(connectorBaseShape()) behind the residue pipe), so an undeclared top-level key was stripped and nothing downstream saw it. After: return DefineConnectorSchema.parse(config), where DefineConnectorSchema = acceptRetiredDefaultResidue(DeclarativeConnectorEntryBaseSchema, CONNECTOR_RETIRED_KEY_RESIDUE). DeclarativeConnectorEntryBaseSchema is strictObject({...}, connectorBaseShape()), and strictObject is z.object(shape, { error }).strict() with the known-key list derived from the shape. So the helper refuses any top-level key connectorBaseShape() does not declare, with one unrecognized_keys issue at the root naming the key(s). The sentence is the entry's own: surface this connector entry, aliases config/providerOptions to providerConfig, timeout/timeoutMs to requestTimeoutMs, retry to retryConfig; guidance for credential-shaped keys (apiKey, key, token, accessToken, secret, clientSecret, password, credentials, credentialRef) pointing at auth: { type, credentialRef }, and for provider settings (baseUrl, url, spec, transport, headers, defaultHeaders) pointing at providerConfig. Right.
2. The sentence is the same at the stack door. The test gives the verdict the stack door gives on the same entry pins keys and message equal between defineConnector(entry) and ObjectStackDefinitionSchema.safeParse({ connectors: [entry] }). Both run the same strictObject carrier, so this holds by construction. Right.
3. Signature and exports. defineConnector(config): ConnectorParsed, with config typed as the z.input of ConnectorSchema, is unchanged. DefineConnectorSchema is module-private (const, no export), so no new published symbol. defineConnector is still exported from packages/spec/src/index.ts line 181 and from @objectstack/spec/integration; the downstream-contract identity pin (source-resolution.pin.test.ts) imports both and is untouched. The output type of the closed carrier is structurally the output of z.object(connectorBaseShape()), so the declared ConnectorParsed return still types. Type Check · source gates and Type Check · consumer gates are green on this head. Right.
4. In-repo callers. Every defineConnector( call at this head, read: examples/app-showcase/src/system/connectors/index.ts (4: showcase_status_api, showcase_status_openapi, showcase_mcp_tools, showcase_erp_catalog), packages/apps/connector-github/src/connectors/github.connector.ts (1), packages/apps/connector-stripe/src/connectors/stripe.connector.ts (1), plus the identity pin in packages/qa/downstream-contract. Top-level keys used: name, label, type, description, provider, providerConfig, auth, actions, enabled. All declared on connectorBaseShape(). providerConfig.include and transport.headers sit under providerConfig, which is z.record(z.string(), z.unknown()), so they are not top-level and are not refused. No caller breaks. Right.
5. Docs and skill snippets. content/docs/automation/connectors.mdx (5 defineConnector blocks), skills/objectstack-automation/references/integration-recipes.md (4 blocks) and the two eval expected outputs in skills/objectstack-automation/evals/integrations-declared.json author only name, label, type, description, provider, providerConfig, auth, actions, enabled. None turns false. Skills-docs: none holds. Right.
6. registerConnector stays open. packages/services/service-automation/src/plugin-extension-api.ts line 347: const parsed = ConnectorSchema.parse(def). ConnectorSchema is untouched by this diff (acceptRetiredDefaultResidue(ConnectorBaseSchema, ...) over a plain z.object). The plugin path keeps its open posture, as the card's option B intended. Option C is not taken. Right.
7. Stack-only refinements are not applied at the helper. DefineConnectorSchema wraps the base, not the .superRefine(...) that DeclarativeConnectorEntrySchema adds (no inline authentication, providerConfig/auth need provider, no actions on an instance, the oauth2 and signed rules). The test applies none of the stack-only refinements pins this. Every stack door still runs the full entry schema on the helper's return value, so nothing an author could previously publish through a stack now slips. This is the narrower of the two readings of the card's "closed twin" and the one both the card and the seat accept. Right.
8. Residue and envelope. acceptRetiredDefaultResidue is a z.preprocess that deletes connectionTimeoutMs: 30000 and status: 'inactive' before the strict parse, so a def a released toolchain emitted still parses. The ADR-0010 envelope (_lock, _lockReason, _lockSource, _provenance, _packageId, _packageVersion, _lockDocsUrl) is spread into connectorBaseShape(), so a stamped entry parses. Both pinned by tests. Right.
9. Retired tombstones. triggers, syncConfig, fieldMappings, webhooks, rateLimitConfig, connectionTimeoutMs, status, errorMapping, health are declared on the shape as retiredKey(...), so writing one meets the retirement prescription, not unrecognized_keys. strictObject excludes tombstones (acceptsNothing) from the did-you-mean candidates. Pinned by the triggers: [] test. Right.
10. No generated artefact moves. No exported schema changed, so check:generated had nothing to regenerate; Spec property liveness and Lint & Repo Gates are green on this head. The seat's claim of no regeneration is consistent with the diff (no packages/spec/**/*.json or generated doc in the file list). Right.

② Semver level

• .changeset/28738-define-connector-closed.md: '@objectstack/spec': minor, title fix(spec)!:, Clause-②: no (narrowing), Metadata-protocol: narrowed, body opens **BREAKING** accept-set narrowing on defineConnector(). The diff narrows a published helper's accept set and nothing else; a minor bump under the launch-window rule for the narrowing arm is what check-changeset-no-major prints green on this head (direction arm: narrowing — a BREAKING change; during the launch window it ships minor). The two declaration lines match the PR body and the amended claim (6562978018). Consistent.
• ADR-0087 disposition. not-required (already-registered connector-entry-undeclared-key-refused). Extending the existing semantic entry is the right disposition, not a new entry: the entry landed with feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object auth #28688 (merged 2026-11-01T16:31Z), its id appears in no packages/spec/CHANGELOG.md and no content/docs/releases/** page, so it is unreleased and its text may still be edited; the prescription (replacement) is byte-identical for the helper and the stack doors because they share one carrier; and a second entry would send an upgrader to two pages for one rule. check-adr-0087-registration validates already-registered against the base (the id pre-exists at 70bf4343) and prints green in the Check Changeset job. The entry's surface now lists defineConnector() first and the reason gains one sentence; both are true on this tree. Right.
• DELIBERATE CORRECTION, per the check-empty-changeset rule. One pending note changed: .changeset/harden-connector-undeclared-keys.md (from feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object auth #28688), one sentence, line 16.
  • Before: **Unchanged.** ConnectorSchema — the def a plugin hands to registerConnector, and the shape defineConnector() parses — keeps its posture. Nothing in the runtime ever read an undeclared entry key, so no connector's behaviour moves.
  • After: **Unchanged.** ConnectorSchema — the def a plugin hands to registerConnector — keeps its posture. Nothing in the runtime ever read an undeclared entry key, so no connector's behaviour moves.
  • Judgment: the removed clause is false on this tree, because defineConnector() now parses DefineConnectorSchema, not ConnectorSchema. The corrected sentence is true on this tree: ConnectorSchema is byte-unchanged in the diff, it remains the open z.object carrier, and registerConnector parses it at plugin-extension-api.ts:347. The trailing sentence (Nothing in the runtime ever read an undeclared entry key) is unaffected. No other line of that note changed (the diff is 1 insertion, 1 deletion). Restoring the note from base would ship a false sentence beside the new note, so the correction is right and this record is its confirmation on head bb3b9bc4. The two Check Changeset failures on this head are exactly this refusal (check-empty-changeset.mjs exit 1, first error line: .changeset/harden-connector-undeclared-keys.md exists on the merge base and was not added by this PR); the job's later steps (check-adr-0087-registration, check-changeset-no-major) print green inside the same log. Check Changeset is not a required context.

③ Boundary flags

• Dev open_questions 1 (closed base vs full DeclarativeConnectorEntrySchema): option A, the closed base, is the right one and the seat accepted it. The full schema would refuse an inline authentication on any def built through the helper for registerConnector, which is the code-to-code break the card parked as option C. The dev measured both choices agreeing on all 7 callers and 5 doc blocks; I read the same files and agree. Answered.
• Dev open_questions 2 (confirm the correction of feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object auth #28688's pending note): A, keep it. Judged sentence by sentence in ② above. This record is the same-head confirmation the landing rule names, so no maintainer action is owed. Answered.
• Dev deviation Clause-2 line written as no (narrowing): the claim line was amended (6562978018); PR body and changeset agree. Resolved.
• Dev deviation Dogfood ran at f668513f, not the final head: the final commit bb3b9bc4 touches one docblock line in connector.zod.ts; the diff I read confirms it is comment-only. Acceptable carry.
• Dev deviations on MCP assignment, PR subscription, harness attribution lines, fetched pinned commit and built packages: process notes, none touches the contract. No action.
• Seat ## 席位核对 deviations ① to ③: all consistent with the tree as read here.
• Checks on bb3b9bc4d400421a7d6f81b1160c1de483bad2eb, read at 2026-11-01T21:40Z: 29 success, 13 skipped, 2 failure (both Check Changeset, the by-design red above, this PR's), 23 in progress (Build Core, Test Core 1 to 8, Test UI shards, Type Check · workspace, Type Check UI, Build & E2E UI, Live E2E UI). The pending runs are this PR's and are not verdicts yet; the landing rule needs them green before ready and queue. No red other than the by-design one.
• needs:contract-review is on the PR. This record is written, not posted; the seat adopting it removes the label in the same stroke, per the rule.
• Not a flag, for the record: content/docs/releases/v17/17-6.mdx names defineConnector among doors that refuse retired keys; still true, release-owned, untouched.

④ Design judgment

packages/spec/src/integration/connector.zod.ts. The refusal is derived from the one closed shape, not a second hand list: DefineConnectorSchema reuses the very DeclarativeConnectorEntryBaseSchema instance that DeclarativeConnectorEntrySchema refines, so there is one strictObject declaration, one aliases table, one guidance table and one known-key list, all read off connectorBaseShape(). A key added to or removed from the shape moves every door at once. strictObject records its declaration once at construction; reusing the instance adds no second declaration, so the alias-integrity audit sees the same one. Attempts to break it:

• Aliases (config, providerOptions, timeout, timeoutMs, retry): refused at the root with the alias prescription; timeout pinned by test, with the declared spelling requestTimeoutMs: 5000 as the control. Held.
• Retired tombstones with a non-default value (triggers: []): the tombstone's own prescription, no unrecognized_keys; pinned. Retired default residue (status: 'inactive', connectionTimeoutMs: 30000): stripped by the preprocess before the strict object sees it, so accepted and absent from the output; pinned for status. Held.
• providerConfig-only keys at the top level (baseUrl, spec, transport, headers, include): baseUrl pinned with the providerConfig guidance; include would meet the plain refusal with a did-you-mean, which is the same verdict the stack door gives. Under providerConfig they are not top-level and pass. Held.
• Served-body read decorations: the ADR-0010 envelope (_packageId, _lock, ...) is declared and pinned. _diagnostics and _draft (METADATA_READ_DECORATIONS) are not declared on any authoring shape; the save door strips them with stripReadDecorations before its parse, while defineConnector does not strip them, so a served body pasted whole into defineConnector meets unrecognized_keys: ['_diagnostics']. That is the same verdict defineStack({ connectors }) has given such a body since feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object auth #28688, and the helper is the authoring entry for a literal, not a round-trip door. No in-repo code feeds a served body to the helper. Held; noted, not a finding.
• The inline authentication escape: defineConnector({ ...DESCRIPTOR, authentication: { type: 'bearer', token } }) is returned by the helper and refused by DeclarativeConnectorEntrySchema; pinned. The helper never publishes anything by itself, so this leaves the [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 rule where it binds. Held.
• Return-type identity: the closed carrier's output is the output of z.object(connectorBaseShape()), so ConnectorParsed still names it. Typecheck green. Held.

packages/spec/src/migrations/entries/semantic/18.connector-entry-undeclared-key-refused.ts. Judged against its first consumer, the upgrade guide, and its execution plan: the surface now names the helper first, which is where an upgrader hits the refusal in source; replacement is unchanged and still correct for the helper; acceptanceCriteria still reads at DeclarativeConnectorEntrySchema and the stored row's _diagnostics, which remain the places an operator checks. The one added reason sentence is true. Unreleased, so editable. Holds.

packages/spec/src/integration/connector-entry-undeclared-keys.test.ts. 12 new cases on the thrown ZodError by code, path and keys, never echoing the value; a control per refusal; the stack-door equality pin; residue; envelope; the no-refinement pin. The ablation reported (7 of 24 red with the body put back) is the right shape. Holds.

docs/audits/2026-07-unknown-key-strictness-ledger.md. The integration/ row no longer says the helper parses the open carrier and names what it parses now; the ⛔ Deliberately NOT closed clause is narrowed to ConnectorSchema alone. Matches the tree.

Findings:

• should-fix (prose only, non-blocking): the new defineConnector docblock says the key is refused by name, located at the key. Zod locates unrecognized_keys at the containing object, path [], and names the key in keys; the PR's own test pins path ''. The phrase is inherited from the feat(spec)!: an authored connector entry refuses a top-level key it does not declare; the connector read withholds URL credential parts and a non-object auth #28688 docblock above it. Reword to located at the entry root and named in keys in a follow-up; it changes no behaviour.
• No must-fix.

Implemented-by: claude/project-thread-mc4e8j
Reviewed-by: session_01AavokzJ5DndAwitDXvKy4U

VERDICT: PASS

---

Generated by Claude Code