feat(spec)!: retire connector.connectionTimeoutMs — carried everywhere, applied nowhere

[os-warren]

Fixes #19580

Clause-②: yes (narrowing)

Ruled: comment 5770606746, batch #211 item 1, letter A — retire connector.connectionTimeoutMs (ADR-0049 enforce-or-remove; the standing 2026-09-10 「以协议为准」 ruling; the 2026-08-27 「no staged retirement」). Removal route: the spec-property-retirement playbook.

What this removes

A fully authorable key — bounded (min(1000).max(300000)), defaulted (30000), .describe()d, writable on ConnectorSchema and, through DeclarativeConnectorEntrySchema, on stack.connectors[] and PUT /meta/connector/:name, and served back by /meta/connector. Every signal an authoring surface can give said it worked. Plus the ConnectorProviderContext.connectionTimeoutMs member handed to every provider factory.

requestTimeoutMs is the replacement: the deadline the platform actually keeps, applied as resilientFetch's per-attempt timeout.

⭐ The measurement the ruling left to the dev — D2 or D3

The ruling prescribed a D3 semantic entry and said a D2 conversion is owed only if a stored connector row can carry the key — 「the dev measures」. It can, so both ship.

Measured first-hand on this branch, before the tombstone landed, against the built packages/spec/dist:

leg	reading
getMetadataTypeSchema('connector') bound?	true — it resolves DeclarativeConnectorEntrySchema, the shape PUT /api/v1/meta/connector/:name validates against
door parses a body carrying the key?	true
does its output retain the authored value?	4321 — so the number reaches sys_metadata
control on the same instrument	the already-retired sibling errorMapping on the same schema is refused — the door discriminates rather than accepting everything
applyConversionsToStoredItem('connector', row) live for this type?	yes — it fired connector-error-mapping-removed and stripped that key from a stored row
control on the same seam	the same row's requestTimeoutMs survived untouched, so the strip is attributable

What would have made it the other answer: getMetadataTypeSchema('connector') returning undefined (no write door ⇒ no stored row), or the door's output dropping the key, or the rehydration seam never reaching connector rows. All three fired the other way, so a D2 conversion is owed and a D3-only kit would have left 17.x rows carrying a key the schema now refuses.

Both dispositions are re-measured by pins in packages/spec/src/integration/connector-connection-timeout-retirement.test.ts, so the answer cannot rot into an assumption.

⚠️ The card is STALE, not wrong — and this section previously said otherwise

⛔ This section's earlier premise is known false and is replaced rather than patched. It claimed the card's Leg-2 table 「was already false when this retirement was taken」. It was not.

At the SHA the card cites and dates — 0870fb5418 — git grep -n connectionTimeoutMs SHA -- . ':!packages/spec' returns exactly five non-spec source hits, and all five are connectionTimeoutMs: 30000,: the card's table, line for line. ⇒ the card was correct when measured. What moved it is b929e0a662 (#19388) — the very PR the card itself flagged as pending.

At origin/main the same instrument returns thirteen non-test source occurrences over seven files in five packages: six reads, four type declarations, and three surviving pure hardcoded 30000 writes (connector-mcp/src/mcp-connector.ts, connector-slack/src/slack-connector.ts, service-automation/src/plugin.ts). ⚠️ Seven files, not five — five is the count of packages, and conflating the two is how the earlier number was reached.

site	what it is
services/service-automation/src/plugin.ts:307	reads entry.connectionTimeoutMs into the materialization fingerprint
services/service-automation/src/plugin.ts:1589	reads it onto ConnectorProviderContext
connectors/connector-rest/src/rest-provider.ts:64	reads ctx.connectionTimeoutMs
connectors/connector-openapi/src/openapi-provider.ts:193	reads ctx.connectionTimeoutMs
connector-rest/src/rest-connector.ts:134, connector-openapi/src/openapi-connector.ts:242	?? 30000 — read the opts and deposit the value on the reported def

The ruling's premise survives, and the mechanism is unchanged. Every read is a pass-through. The value's only termini are (a) the def GET /connectors echoes and (b) the fingerprint that decides whether to re-materialize. connectorFetchOptions() (integration/connector-fetch-policy.ts) is handed { retryConfig, requestTimeoutMs } only, and a pin has asserted since #18975 that nothing aliases this key onto timeoutMs. Carrying a number is not honouring it — the parsed-unmarked-unenforced state ADR-0049 forbids, wearing a longer route.

Nor was the 实现 arm available: a WHATWG fetch exposes one AbortSignal over the whole operation and never the connect phase, so bounding time-to-response with this key would kill a slow-but-connected upstream the author meant to allow with a large requestTimeoutMs.

Zero-enforcement verification, with its control

• Claim: nothing applies the value as a deadline. Instrument: git grep -n connectionTimeoutMs over the whole worktree (45 hits, hand-read, not counted) plus the source of connectorFetchOptions(). Radius: the monorepo. Control: requestTimeoutMs — same schema, same census, same files — resolves to a real read (opts.timeoutMs = policy.requestTimeoutMs), so the instrument is not dead.
• Pinned sibling checkout: git grep connectionTimeoutMs at objectui 87af769e9a3ee28ace099fdd653d3ebd79fe82e2 (the .objectui-sha pin) → exit 1, zero hits; control connector on the same command and scope returns 458 lines across 66 files; and requestTimeoutMs is exit 1 / 0 lines there, so it is not a usable control in that repo (it is in objectstack). ⇒ the Console Pin Gate needs no sibling fix and no pin bump with this removal.
  ⚠️ That clearance is about the sibling BUILD, and it is not the whole picture. The residue stage makes both carriers z.preprocess pipes, and objectui's packages/app-shell/src/views/metadata-admin/clientValidation.optOuts.test.ts:468 asserts checks(DeclarativeConnectorEntrySchema) > 0 — 1 against main, 0 here, because a pipe def has no checks array. The SPA still builds and Console Pin Gate never runs that suite, so no gate in either repo sees it. objectui resolves @objectstack/spec from the registry at ^17.0.0, so ⛔ main does not go red on merge — the break lands at objectui's next spec bump. Tracked at objectui#10211; the gate-reach gap at objectstack#19692. ⛔ A .objectui-sha bump is never a rider on another PR, so neither rides here.
• tsc is the real sweeper. retiredKey() types the key never, so every authoring site in the monorepo fails to compile. All six affected packages typecheck green after the cleanup, which is what says the census is complete rather than the grep.

The retirement kit

• retiredKey() tombstone on the non-strict ConnectorSchema (a bare delete would be a silent strip, ADR-0104), inherited by DeclarativeConnectorEntrySchema.
• RETIRED_KEYS_BY_MAJOR[18] × 2 — integration/Connector:connectionTimeoutMs and integration/DeclarativeConnectorEntry:connectionTimeoutMs — as one-file-per-entry under migrations/entries/retired-keys/.
• D2 connector-connection-timeout-ms-removed in conversions/registry.ts, wired into the step-18 chain.
• ⭐ ADR-0087 residue stage acceptRetiredDefaultResidue on both carriers with { connectionTimeoutMs: 30000 }. A D2 does not discharge this: the ruled precedent 18.security__ObjectPermission__allowPurge carries both a D2 (permission-allow-restore-purge-removed) and the residue stage, so D2 coverage cannot be the discriminator. The discriminator is whether a released toolchain MATERIALIZED the default — a 17.x toolchain emits connectionTimeoutMs: 30000 into every connector entry, authored or not — and the second door is AutomationEngine.registerConnector, which parses ConnectorSchema for a def a plugin builds in code, where no conversion runs. Without the stage a 17.x connector package fails registration on a value its author never typed. Head now accepts-and-strips 30000 while still refusing 15000, 1000 and "30000". The preprocess pipe this introduces moves five ADR-0097 refinement sites onto its OUT side, so dropped-refinements.baseline.json moves with them — exactly the moves the build gate printed, no additions.
• D3 semantic connector-provider-context-connection-timeout-ms-retired for the withdrawn ConnectorProviderContext member — a provider factory is code, so there is no authored source for a conversion to rewrite.
• liveness/connector.json: the row stays dead with a REMOVED note, because retiredKey() keeps the key in the walked shape (the rls.priority precedent). Its stale 「every occurrence outside packages/spec is a WRITE」 claim is corrected there, with the reads named.
• Baselines: authorable-surface/integration.json gains two [RETIRED] rows, authorable-defaults/integration.json loses the two = 30000 rows. api-surface/ and json-schema.manifest/ are byte-identical — the correct reading for a key-only tombstone that retires no def, not a missed regeneration.
• Consumers cleaned: the four connector packages and service-automation (fingerprint, declared-item shape, context build, degraded husk).
• Declared widening, round 4: packages/spec/liveness/README.md's connector row asserted, present tense, that the entry schema is ConnectorSchema.superRefine(...) — and rested its byte-identical-key-set conclusion on that attachment. Both halves are corrected: the mechanism is now the pipe's read-through shape, and the conclusion is re-measured rather than inherited (30 keys each carrier, byte-identical, zero entry-only, zero base-only). ⚠️ Hand-edited on purpose, ⛔ never regenerated: .gitattributes:71-77 splits liveness/state-counts.md (driver-managed numbers) from liveness/README.md (hand-written Notes prose), because 「regenerating a Note would fabricate a verdict」.
• ⚠️ A SECOND, declared narrowing: the ZodObject combinators leave both published exports. Wrapping ConnectorSchema and DeclarativeConnectorEntrySchema in the residue stage makes them z.preprocess pipes, so .extend(), .omit(), .pick(), .partial(), .merge(), .strict(), .keyof() and .safeExtend() no longer exist on them. Build on the object and re-wrap — acceptRetiredDefaultResidue(<the extended object>, { connectionTimeoutMs: 30000 }), the EffectiveObjectPermissionSchema route. ⚠️ .superRefine() still exists on a pipe and is callable, but returns a schema with no read-through shape — which is exactly what the schema walkers duck-test — so refine before wrapping, never after. Parsing, z.input / z.infer and the read-through .shape are unchanged. The changeset's FROM → TO carries this row; the docblock at connector.zod.ts and the superseded sentence it replaces carry it in the source.
• Changeset Clause-②: yes (narrowing), minor on @objectstack/spec (the launch-window gate refuses major), patch on the five consumer packages, with the FROM → TO table and the ADR-0087 disposition marker.

Tests and gates run locally

run	verdict
pnpm --filter @objectstack/spec build	exit 0
dependency-closure build of the five consumer packages	exit 0
typecheck × 6 (spec, connector-rest, connector-openapi, connector-mcp, connector-slack, service-automation)	exit 0
test × 5 consumer packages	1786 passed
spec src/integration src/conversions src/migrations + the migrate-sentence and cron pins	569 passed / 16 files
spec test:repo	600 passed
full pnpm build + the re-derived 112-command gate sweep on this head	112 / 112, and on the latest round with zero prerequisite failures, because the full build ran first (earlier rounds had three first-pass non-zeros, all PREREQUISITE NOT MET from unbuilt packages ⇒ read as NOT MEASURED, ⛔ never as failures, and re-run green after the build)
the new retirement pin under --project repo	15 passed
check:generated	15 of 15 green, check:docs and check:liveness included
the 14 source audits check:generated names as not run	all exit 0, each captured separately
check:nul-bytes, check:cross-package-test-inputs, check:adr-0087-registration, check:changeset-no-major	exit 0

Every exit code above was captured before any pipe. The repo-wide gate farm is CI's run, not this PR's local obligation.

Acceptance notes

• Scope deviation, declared. The dispatch fenced content/docs/** off. content/docs/references/integration/connector.mdx is an auto-generated baseline whose gate (check:docs) is inside the required TypeScript Type Check job, and it goes stale on this change alone. Measured across all 19 open PRs (283 file rows, 0 unreadable): zero hold that path, so the fence's stated reason — "open PRs hold files there" — does not apply to it; the instrument discriminates, returning content/docs rows for seven other PRs. It is regenerated here, exactly as the sibling retirement fix(spec): retire tenancy.organizationField from the authorable surface (#19054) #19618 regenerates four of the same tree's pages. No hand-written content/docs/** prose is touched, and skills/** and .claude/** are untouched — this diff hits no governed surface.
• Scope, mechanically forced. The tombstone types the key never, so the four connector packages and service-automation must stop writing it or the monorepo does not compile. Those paths are outside the claim's declared file surface and are held by zero open PRs on the same census.
• The two-writer surface materialised as declared — see the report.
• packages/spec/vitest.repo-tests.json gains one line: the new tree-scoped absence pin's walk radius, which check:cross-package-test-inputs demanded by name. No new glob; the radius was already declared for this package.
• The connectionTimeoutMs-is-never-mapped pin in connector-fetch-policy.test.ts is kept after the retirement, deliberately: it is what makes a re-introduction as a silent alias onto timeoutMs fail.
• health.circuitBreaker remains dead on this schema and is not touched here — a different set of rows on the same ADR-0049 worklist.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 6 package(s): @objectstack/connector-mcp, @objectstack/connector-openapi, @objectstack/connector-rest, @objectstack/connector-slack, @objectstack/service-automation, @objectstack/spec, touching 31 documentable anchor(s). ⚠️ 10 changed file(s) yielded no anchor (packages/spec/authorable-defaults/integration.json, packages/spec/authorable-surface/integration.json, packages/spec/docs/SYNC_ARCHITECTURE.md, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/releases/v15.mdx (via ConnectorSchema (symbol, a top-level const))
• content/docs/releases/v17/17-0.mdx (via ConnectorSchema (symbol, a top-level const), DeclarativeConnectorEntrySchema (symbol, a top-level const))

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

• 10 changed file(s) yielded no anchor (packages/spec/authorable-defaults/integration.json, packages/spec/authorable-surface/integration.json, packages/spec/docs/SYNC_ARCHITECTURE.md, …) — pages documenting those are invisible to this run
• 8 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 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; 100 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 — 136 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 106d4c8dd7fe35d6195c507304ac21a299c510ea → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 106d4c8dd7fe35d6195c507304ac21a299c510ea

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