feat(spec)!: retire the connector resilience family — health (probe + breaker), status and nested webhooks, sixteen keys nothing read (#20273)

[objectstack-fleet]

Fixes #20273

Clause-②: no (narrowing)

Retires the connector resilience family under ADR-0049 enforce-or-remove, one batch, by the triage verdict RETIRE (comment 5858520070) under the maintainer's criterion on #18900: connector.health (the healthCheck probe, eight keys, and the circuitBreaker, six keys), connector.status and the connector-nested webhooks — sixteen authorable keys that nothing read. Authoring any of them is now a tsc error and a parse error that carries the prescription; no alias window.

Census first (origin/main 3f86dc5, each zero beside a lit control)

family	readers outside packages/spec	lit control, same scan
the fourteen health.healthCheck.* / health.circuitBreaker.* leaves	0 (circuitBreaker, fallbackStrategy, halfOpenMaxRequests, unhealthyThreshold, healthyThreshold, monitoringWindowMs, resetTimeoutMs outside generated docs; healthCheck only as the kernel plugin-health contract; no .health. read in packages/connectors or service-automation)	retryConfig read 17 times in packages/connectors + service-automation
status	0 connector reads: one member-read pattern over connectors, service-automation, rest, runtime, metadata and objectql finds 38 .status reads, every one on an HTTP answer, an error case or a flow-run entry	the same pattern finds requestTimeoutMs read off a connector entry / provider context 5 times
nested webhooks	0 reads of a connector's own array (the one test that authors one pins that it is NOT hoisted)	stack.webhooks read 5 times

objectui: nothing imports a removed name at the pinned .objectui-sha f8a9d0fb (one comment mentions WebhookEventSchema), and no connector status / health / webhooks reader at objectui main 610819c40. No key had a live reader, so no premise_still_valid fork.

What changed

• Tombstones. health, status, webhooks are retiredKey() tombstones on the private ConnectorBaseSchema that both published carriers wrap (ConnectorSchema, DeclarativeConnectorEntrySchema), so defineConnector, registerConnector, stack.connectors[] and PUT /api/v1/meta/connector/:name all refuse them. Six RETIRED_KEYS_BY_MAJOR[18] rows.
• Residue. status was .default('inactive'), emitted by every 17.x parse into every connector; status: 'inactive' joins connectionTimeoutMs: 30000 in CONNECTOR_RETIRED_KEY_RESIDUE (accepted and stripped). Every other value is refused.
• Seven defs leave whole (RETIRED_DEFS_BY_MAJOR[18]): ConnectorHealth, HealthCheckConfig, CircuitBreakerConfig, ConnectorStatus, WebhookConfig, WebhookEvent, WebhookSignatureAlgorithm. The manifest keys and baseline rows were deleted deliberately after the build named them.
• D2 conversion connector-resilience-keys-removed (step 18, retired from the load path): strips the three keys from connectors[] and from stored rows, one notice per key; nested webhooks are stripped, never moved.
• D3 entry connector-resilience-keys-retired (one per family, ruling B on [Decision] 一次退役，要写一条记录还是两条？—— 迁移条目的 D2/D3 约定，两处成文相互矛盾 #17152), naming the D2 and the chain below.
• Writers deleted. status: 'active' in the four shipped connector packages and status: 'error' on the automation service's degraded husk were writes nothing read back; tsc found the husk's test fixture too.
• packages/spec/docs/SYNC_ARCHITECTURE.md: the "Monitoring: Health checks" tick is gone, and so are the ticks and example lines this retirement made false (connector webhooks, circuit breaker, status: 'active'); the doc's compile gate (connector-author-shape.test.ts) holds the example.
• automation/webhook.zod.ts: its connector-webhook note is corrected, and the extraKeys: ['signatureAlgorithm'] suggestion is dropped (the only surface accepting that key is gone, so a typo on the delivered webhook would have been pointed at a refused key).
• Ledger: status and webhooks stay one dead row each, now tombstones; connector/webhooks left the undrilled baseline (the gate called it stale); state-counts.md and the README notes cell regenerated / corrected (dead 44 to 30).
• Projections regenerated by their generators only: migrations/registry.ts, api-surface/, declaration-map/, export-origins/, authorable-surface/, authorable-defaults/, json-schema.manifest/, content/docs/references/**, strictness counts, test-typecheck-debt.json (shrink only). spec-changes.json and docs/protocol-upgrade-guide.md do not move: they fold majors up to PROTOCOL_MAJOR 17, and this is step 18 (check:spec-changes / check:upgrade-guide green).
• docs/adr/0122-...md is NOT edited: no gate forced it. type-alias-convention.pin.test.ts loses the three isomorphic pins of the removed enums (786 to 783), the way the error-mapping precedent did.

Deviations from the dispatch's mechanism assumptions (measured)

1. Per-key tombstones vs. defs leaving. The dispatch asked for one tombstone per key AND for ConnectorHealth / ConnectorStatus to leave via RETIRED_DEFS_BY_MAJOR. Both cannot hold for the fourteen health.* leaves: once ConnectorHealth leaves, its leaves have no shape to carry a tombstone. I followed the error-mapping precedent (13c48c2): one carrier tombstone per key the walk still reaches (health, status, webhooks), defs whole.
2. "The liveness rows stay dead." The fourteen drilled health.* rows cannot stay: with health a leaf, check:liveness refuses them (measured: connector/health (declared children but property is not a container)). health is one dead tombstone row whose note carries the fourteen verdicts and their census.
3. "Rename, then removal." Keeping the breaker half of connector-health-and-trigger-durations-unit-in-key is impossible under the conversion table's disjoint-fixture contract: the rename's own fixture carries a health block that the removal strips. Per spec-property-retirement §0 (same unreleased step) the breaker half is ABSORBED: the rename now carries only triggers[].interval, and the removal serves an author holding either spelling (a pin replays monitoringWindow plus a trigger interval and gets exactly one rename notice and one removal notice).
4. plugin.ts:1792 was not comment-only. The line under that comment WROTE status: 'error' into the husk def, which the tombstone makes a tsc error and a registration-time parse refusal; the write is deleted and the comment corrected.
5. File surface grew beyond the claim, each forced by the retirement: the four connector packages and one service-automation test (writers), automation/webhook.zod.ts (orphaned extraKeys), plugin-webhooks' docblock and its pin test's docblock (they quoted the retired spec prose), rest-server.test.ts (a stale comment), connector-author-shape.test.ts, type-alias-convention.pin.test.ts.

Acceptance notes

• PR fix(spec): one D3 entry per major-18 retirement family — the census and the 25 missing entries (#20201) #20255 merged before this PR was finished, so main was merged here and its D3 entry connector-resilience-durations-unit-in-key is reconciled in this PR: it now prescribes only triggers[].interval to intervalSeconds and tells an author holding monitoringWindow / monitoringWindowMs that the renamed key is itself retired (delete the health block). triggers[].interval is untouched otherwise.
• The out-of-repo consumer population of @objectstack/spec is not measured.

Evidence (head 153f652)

• pnpm --filter @objectstack/spec build green (manifest and baseline gates fired on the seven defs first, as they must on a whole-def removal, then passed once the rows were deleted deliberately).
• check:generated: all 15 artifacts current. check:liveness, check:migration-registry, check:spec-changes, check:upgrade-guide green.
• Gate union from node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at 153f652, reconciled with --ran: 118 derived, 113 run with exit 0, 5 NOT MEASURED — check:skill-examples, check:dual-build-cjs-loads, check:i18n, check:type-check-debt refused with exit 3 (PREREQUISITE NOT MET: builds outside this diff's closure — client-react, the CLI plugin set, the whole monorepo), check:query-options-erasure (repo-wide ESLint scan; self-test passed, the ratchet outran a 300s per-gate bound — exit 124). CI runs all five.
• Tests at 153f652: spec --project local over src/migrations, src/conversions, src/integration, the ADR-0122 pin, rest-server, webhook, stack — 18 files, 777 passed; spec --project repo (this PR's pin, the connectionTimeoutMs pin, the migrate-sentence pin, two sibling tree-scoped pins, three reference-tree scripts) — 8 files, 221 passed.
• Earlier on this branch (pre-second-merge heads): full spec --project local 552 files / 16265 passed; service-automation 146 files / 1757 passed; connector-mcp / -openapi / -rest / -slack and plugin-webhooks 27 files / 255 passed; typecheck of those six packages green; dogfood expression-conformance 7 passed.
• ESLint over the 32 changed lintable files (--no-inline-config --format json): 32 files, 0 errors, 0 warnings. Population: eslint.config.mjs flat config over **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}; the config enables no type-aware linting (no parserOptions.project), so this diff cannot move a verdict in an untouched file. The repo-wide pnpm lint is CI's.

Ablation (one per closed door)

Via node scripts/ablation-replace.mjs (anchor must hit, restore proven by blob hash equal to HEAD and an empty git diff HEAD), on committed head 849fb62, running connector-resilience-keys-retirement.test.ts:

tombstone deleted (bare strip)	result
health	4 failed / 17 passed — REJECTS health, the three-door refusal, the either-spelling breaker refusal, the walked-shape pin
status	4 failed / 17 passed — REJECTS status, the three-door refusal, the non-default-value refusal, the walked-shape pin
webhooks	3 failed / 18 passed — REJECTS webhooks, the three-door refusal, the walked-shape pin

Each leg restored to blob 704684dc6f0c (HEAD's). No permanent ablation test is left.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: 62/62 CONTRACT_REVIEW_TIER
Head-sha: 153f652c278a573f06f7b40cd19acdcaa307ba2d

① Derived judgments

1. Premise holds. Re-grepped origin/main (a36a691) outside packages/spec, non-md: circuitBreaker / fallbackStrategy / halfOpenMaxRequests / unhealthyThreshold / healthyThreshold / monitoringWindow(Ms) / resetTimeoutMs = 0; healthCheck 28 and failureThreshold 25 are all the kernel plugin-health contract, knowledge adapters and the messaging outbox (different subjects); lit control retryConfig = 48 in connectors + service-automation. No def.status read anywhere; engine.ts#getConnectorDescriptors publishes state only. No read of a connector's nested webhooks; control stack.webhooks read by lint + plugin-webhooks. examples/, skills/: no connector authors health/status/webhooks (showcase status: { type: 'string' } is an action outputSchema property). objectui at pinned f8a9d0fb: 0 imports of the seven names (one comment mention), 0 connector status/health/webhooks reads; it consumes DeclarativeConnectorEntrySchema whole, so the tombstone travels with it.
2. Refusal shape correct. Three retiredKey() tombstones on the shared private ConnectorBaseSchema; stack.zod.ts:712 uses DeclarativeConnectorEntrySchema, /meta/connector binds the same, registerConnector parses ConnectorSchema (engine.ts:3706). Pin test drives all four doors plus @ts-expect-error on each key and controls without the keys. Prescriptions verified true: GET /api/v1/automation/connectors exists (dispatcher-plugin.ts:1506, route ledger) and reports state (ready/degraded, connector-descriptor.ts:42); enabled: false withdraws materialization (plugin.ts:1488) and marks catalog-only (Declarative connectors: stack entries are inert — bridge them to the automation connector registry or document as descriptor-only #2612); top-level webhooks: is materialized to sys_webhook and delivered on data.record.* (auto-enqueuer). Nothing inert is named. status: 'inactive' residue is strict-equality strip on both carriers; all other values refused (pinned).
3. Nested webhooks. Lossless in the ADR-0087 sense: never registered as a webhook item, never delivered (ledger + connector-nested.test.ts pin). The webhooks prescription, the D3 reason/replacement and the changeset all tell the author to re-author in top-level webhooks:, warn that doing so starts deliveries, and state events/signatureAlgorithm have no counterpart. Not silently dropped.
4. Chain. Pin replays monitoringWindow + trigger interval: exactly [interval→intervalSeconds, health→(removed)]; removal is ordered after the rename in conversionIds. No prescription anywhere ends at monitoringWindowMs: the health tombstone names both spellings, the D3 connector-resilience-durations-unit-in-key says "delete the block". Editing the landed entry is acceptable: step 18 is unreleased (PROTOCOL_VERSION = '17.0.0'; spec-changes.json / upgrade guide carry no step-18 id), the skill §0 prescribes same-major absorption, registry.ts header states step rationale/conversionIds are hand-written and semantic regions regenerate from one-file-per-entry, and check-adr-0087-registration.mjs reads no entry file; the changeset marker names only the two ids this diff adds, as registered requires.
5. Out-of-spec edits. Zero readers of the deleted writes: descriptor payload has no status, objectui reads name/label/origin/actions, the only test fixture (degraded-register-cause.test.ts) is updated. extraKeys: ['signatureAlgorithm'] drop is correct and complete: the only acceptor (WebhookConfigSchema) is gone; alias-integrity.test.ts only audits alias targets, none of which is signatureAlgorithm; no other pin names it.
6. Ledger/baselines. retiredKey() is z.never().optional(), not a container, so children under health is refused by the walk — the single dead tombstone row carrying the fourteen verdicts is the forced shape, in the file's own errorMapping house style. connector/webhooks leaving the undrilled baseline is forced (leaf now). test-typecheck-debt.json −2 (removed unused imports), pin test 786→783 = exactly the three enum pins; the four Parsed-bearing defs were never listed. Nit, non-blocking: the baseline's _containers description prose still narrates connector/webhooks as a recorded row.
7. Projections arithmetically exact: api-surface/export-origins −18 names, declaration-map −14, manifest −7, docs 1523→1516 and 24→17, authorable-surface 6 rows → [RETIRED] plus CBC 7 / ConnectorHealth 2 / HCC 8 / WebhookConfig 21 gone, defaults −15, strictness 8→5 (three non-strict objects). Generated registry regions match the entry files verbatim. Generators not re-run (derived gate).
8. Changeset. Every sentence checked true; FROM→TO table, one-line fix, BREAKING banner, registered marker; Clause-②: no (narrowing) stands alone on its own line in both changeset and body.

② Semver level

PASS. @objectstack/spec: minor is the launch-window rule (check-changeset-no-major.mjs refuses major; AGENTS.md: (narrowing) is BREAKING). The four connector packages and service-automation take patch for deleting an inert write. plugin-webhooks is docblock-only, no changeset owed. no (narrowing) is one of the four spellings clause2-line.mjs reads; no (widening) would be the malformed one.

③ Boundary flags

• ADR-0122 §D is a dated probe table, not a normative claim; the error-mapping precedent 13c48c2 left ErrorMappingConfig/ErrorMappingRule/ConnectorErrorCategory in the same table unedited, so leaving ConnectorHealth/ConnectorStatus (and five more) there is consistent, not false; no gate reads it.
• Driver-free git merge-tree --write-tree origin/main 153f652c27 (os-regen driver replaced by git merge-file): NOT clean — CONFLICT in packages/spec/liveness/state-counts.md (total row moved on main); liveness/README.md, migrations/registry.ts, rest-server.test.ts text-merge clean. With the repo driver it is clean but defers that file to gen:liveness-counts. GitHub reports mergeable: false / dirty: merge main and regenerate before landing.
• Overlaps: feat(spec,rest)!: retire api.responseFormat and api.documentation.enabled (ADR-0049) #20343 (rest-server.test.ts, open/blocked), feat(automation)!: edge-branched decision is exclusive; mode: 'inclusive' takes every branch (#15429) #20344, feat(spec)!: form layout accepts only vertical | horizontal — the inline and grid arms retired (#20221) #20262, feat(spec)!: retire currencyConfig.precision — a currency's decimal places are its currency's (ADR-0049) #20251 (dirty) all open; shared registries regenerate on merge.
• CI: 0 check runs on 153f652 at both reads (draft PR, not started).

Implemented-by: claude/issue-20273-connector-resilience-keys-retired
Reviewed-by: session_01QcAS3qiYYZNezaxZxaUdMV

VERDICT: PASS

[github-actions]

📓 Docs Drift Check

This PR changes 7 package(s): @objectstack/connector-mcp, @objectstack/connector-openapi, @objectstack/connector-rest, @objectstack/connector-slack, @objectstack/plugin-webhooks, @objectstack/service-automation, @objectstack/spec, touching 60 documentable anchor(s). ⚠️ 23 changed file(s) yielded no anchor (packages/plugins/plugin-webhooks/src/bootstrap-declared-webhooks.ts, packages/spec/api-surface/integration.json, packages/spec/authorable-defaults/integration.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/automation/connectors.mdx (via /api/v1/automation/connectors (route, a path literal in HEALTH_RETIRED; a path literal in STATUS_RETIRED; a path literal in a comment in ConnectorBaseSchema; a path literal in a comment in RETIRED_KEYS_BY_MAJOR; a path literal in a comment on a changed line; a path literal in acceptanceCriteria; a path literal in replacement; a path literal in semantic))
• content/docs/automation/flows.mdx (via AutomationServicePlugin (symbol, a top-level class))
• content/docs/automation/webhooks.mdx (via WebhookSchema (symbol, a top-level const))
• content/docs/kernel/cluster.mdx (via RETIRED_DEFS_BY_MAJOR (symbol, a top-level const object))

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

• content/docs/releases/v15.mdx (via /api/v1/automation/connectors (route, a path literal in HEALTH_RETIRED; a path literal in STATUS_RETIRED; a path literal in a comment in ConnectorBaseSchema; a path literal in a comment in RETIRED_KEYS_BY_MAJOR; a path literal in a comment on a changed line; a path literal in acceptanceCriteria; a path literal in replacement; a path literal in semantic))
• content/docs/releases/v17/17-0.mdx (via WebhookConfig (symbol, a top-level type), WebhookEvent (symbol, a top-level type))
• content/docs/releases/v17/17-4.mdx (via intervalSeconds (literal, a string literal in summary))

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

• 23 changed file(s) yielded no anchor (packages/plugins/plugin-webhooks/src/bootstrap-declared-webhooks.ts, packages/spec/api-surface/integration.json, packages/spec/authorable-defaults/integration.json, …) — 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 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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 f39ea95961b2359b56e6b45774d0ce124f373c84 → packageMentionDocs.

Which tree this was computed on

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

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

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