Skip to content

spec(integration): retire the connector health-probe, circuit-breaker, authored status and nested webhooks keys (16), which nothing enforces #20273

Description

@objectstack-fleet

Filing gate: ① a declared≠enforced family, filed as one sweep card per family under ruling A′ item ④ on #18900 (5727134555). This is triage's standing request 5857165909 on the seat post. Family connector-resilience, seat verdict RETIRE.

  • reach: the declared authoring door. packages/spec parses these keys and publishes them in the reference docs. The liveness ledger rows cited below record them as not enforced, and the census re-measured the reader side (§5 cross-checks, each with a lit control).
  • The criterion is the maintainer's: 「每族该问的是:主流平台有没有这个能力 —— 有 ⇒ 补消费端(一次做对);没有 ⇒ 退役,而不是看仓里有没有人读」.
  • The maintainer's one word, per ruling A′ ④: RETIRE (the seat's proposal: the mainstream lacks it, or it duplicates a capability delivered here) or ENFORCE (build the consumer once, correctly).

Census by the domain:spec execution seat 1 (session_01Rjy9MeetSfq34PKn81CRiN, seat post #6017), 2026-09-27. Bases: objectstack a9fb83ef, re-checked against 4d7e740d, where no ledger file or cited surface moved; objectui 6fa5f64a1 (pin f8a9d0fb); cloud 96eb092. Ledger instrument: check-liveness.mts --json, whose byStatus equals the committed state-counts.md row for row. ⛔ Filed bare: routing and grading belong to triage. ⛔ Not a claim. The ranking is by value, user-visible risk × keys. This family's rank is 1 of 16.

Capability: Author-declared connection health probes and circuit breakers; an authored connector status; a webhook list nested in the connector

key ledger status ledger row what the ledger cites
connector.webhooks dead (verified 2026-09-17) packages/spec/liveness/connector.json:231 note: A connector's NESTED webhook array is not the collection the dispatcher reads, and nothing else reads it either. bootstrapDeclaredWebhooks (packages/plugins/plugin-webhooks/src/bootstrap-declared-webhooks.ts) materializes sys_webhook rows from `readDecl…
connector.status dead (verified 2026-09-17) packages/spec/liveness/connector.json:313 note: Declared ConnectorStatusSchema with a .default('inactive'), and dispatched on by nothing — no consumer reads def.status in this repo, and the runtime's answer to 'can this connector be dispatched?' is a DIFFERENT field: RegisteredConnector.state (`r…
connector.health.healthCheck.enabled dead (verified 2026-09-17) packages/spec/liveness/connector.json:334 note: No connector health-check loop exists. Census: the only healthCheck occurrences outside packages/spec are the KERNEL's own plugin health contract (packages/core/src/health-monitor.ts, PluginHealthCheck) — a different shape on a different subject — and…
connector.health.healthCheck.intervalMs dead (verified 2026-09-17) packages/spec/liveness/connector.json:339 note: Dead for the one reason recorded on health.healthCheck.enabled — nothing schedules the probe.
connector.health.healthCheck.timeoutMs dead (verified 2026-09-17) packages/spec/liveness/connector.json:344 note: Dead for the one reason recorded on health.healthCheck.enabled.
connector.health.healthCheck.endpoint dead (verified 2026-09-17) packages/spec/liveness/connector.json:349 note: Dead for the one reason recorded on health.healthCheck.enabled — no request is ever made to it.
connector.health.healthCheck.method dead (verified 2026-09-17) packages/spec/liveness/connector.json:354 note: Dead for the one reason recorded on health.healthCheck.enabled.
connector.health.healthCheck.expectedStatus dead (verified 2026-09-17) packages/spec/liveness/connector.json:359 note: Dead for the one reason recorded on health.healthCheck.enabled.
connector.health.healthCheck.unhealthyThreshold dead (verified 2026-09-17) packages/spec/liveness/connector.json:364 note: Dead for the one reason recorded on health.healthCheck.enabled.
connector.health.healthCheck.healthyThreshold dead (verified 2026-09-17) packages/spec/liveness/connector.json:369 note: Dead for the one reason recorded on health.healthCheck.enabled.
connector.health.circuitBreaker.enabled dead (verified 2026-09-17) packages/spec/liveness/connector.json:378 note: No circuit breaker exists for connectors. Census: nothing outside packages/spec reads circuitBreaker except the protocol-18 rename conversion in packages/spec/src/conversions/registry.ts, which rewrites the key's NAME and is not a consumer. No state machi…
connector.health.circuitBreaker.failureThreshold dead (verified 2026-09-17) packages/spec/liveness/connector.json:383 note: Dead for the one reason recorded on health.circuitBreaker.enabled.
connector.health.circuitBreaker.resetTimeoutMs dead (verified 2026-09-17) packages/spec/liveness/connector.json:388 note: Dead for the one reason recorded on health.circuitBreaker.enabled.
connector.health.circuitBreaker.halfOpenMaxRequests dead (verified 2026-09-17) packages/spec/liveness/connector.json:393 note: Dead for the one reason recorded on health.circuitBreaker.enabled.
connector.health.circuitBreaker.monitoringWindowMs dead (verified 2026-09-17) packages/spec/liveness/connector.json:398 note: Dead for the one reason recorded on health.circuitBreaker.enabled. Renamed from monitoringWindow by the protocol-18 conversion (#15680/#14478) so the unit lives in the key name — an honesty fix to a declaration that is still unread.
connector.health.circuitBreaker.fallbackStrategy dead (verified 2026-09-17) packages/spec/liveness/connector.json:408 note: Dead for the one reason recorded on health.circuitBreaker.enabled. cache / default_value / error / queue name four behaviours none of which is implemented anywhere — the shape this ledger exists to find.

Mainstream evidence:

  • Salesforce Named Credentials / External Credentials and External Services: endpoint and auth only. No author-configured health probe or circuit breaker.
  • Power Platform custom connectors: an OpenAPI definition plus policy templates (set host URL, route request, set header). No health probe or breaker. Connection status is computed ("Connected" / "Error"), never authored.
  • Retool resources and Appsmith datasources: a manual "Test connection" button, no scheduled probe and no breaker.
  • ServiceNow IntegrationHub connection & credential aliases carry a retry policy. A declarative circuit breaker on them is UNVERIFIED (not known to exist).
  • Circuit breakers exist in API gateways (Azure API Management backend circuit breaker, Envoy, Kong). That is infrastructure configuration, not app-author metadata.
  • The duplicates are already delivered here: participation is enabled (live) plus the computed RegisteredConnector.state (feat(connector-mcp): declarative provider — non-fatal / lazy boot for unreachable MCP servers (ADR-0096 follow-up) #3017); webhooks are the top-level webhooks: collection materialized to sys_webhook (plugin-webhooks bootstrap-declared-webhooks.ts).

Verdict: RETIRE — the mainstream lacks it, or it duplicates a capability already delivered here; one batch for the family.

Reader that must exist / disposition: none; this is a retirement. The ADR-0087 conversion and the retiredKey tombstones go on packages/spec/src/integration/connector.zod.ts (ConnectorHealthSchema, HealthCheckConfigSchema, CircuitBreakerConfigSchema, ConnectorStatusSchema, webhooks).

User-visible risk (2): An author who sets circuitBreaker.enabled: true or status: "active" expects protection or activation and gets nothing. SYNC_ARCHITECTURE.md ticks "Monitoring: Health checks" at L3, and the ledger records that this claim has no backing on this surface.

Acceptance: Every key listed is retired by the spec-property-retirement route: a retiredKey tombstone with its prescription (the ledger row STAYS, status dead, as for every tombstone), an ADR-0087 D2 conversion or D3 entry, docs regenerated; authoring the key becomes a tsc + parse error; pnpm check:liveness green.

Lane: domain:spec (objectstack), vertical: spec + ADR-0087 conversion + docs, no consumer repo

File surface: packages/spec/src/integration/connector.zod.ts:715-716,957,1002,1037 · packages/spec/liveness/connector.json · packages/spec/docs/SYNC_ARCHITECTURE.md · content/docs/references/integration/connector.mdx (generated) · packages/spec/src/conversions/registry.ts

Dedupe: healthCheck\.(enabled\|intervalMs\|endpoint) \| circuitBreaker \| HealthCheckConfig \| ConnectorHealth → 1 open hit. None carries a key of this family:

Dedupe: ConnectorStatusSchema \| connector\.status\b \| connector.{0,40}nested.{0,20}webhooks \| connector\.webhooks → 0 open hits.

四轴:

  • 实际业务需求: 主流低代码平台的连接配置里没有作者可写的健康探针和熔断器(Salesforce Named Credential、Power Platform 自定义连接器、Retool/Appsmith 数据源都没有)。熔断器在 API 网关这一基础设施层,不在应用元数据里。作者写了这 16 个键,得到的是空转。
  • 项目长远合理性: 「连接器是否可派发」已经有两处真值:enabled 与运行期计算出的 state。再保留一个作者可写的 status 和一套无引擎的健康配置,长期会形成三套互相矛盾的真值。退役之后,连接器面收敛到 ADR-0097 的实例模型,将来要做韧性就在运行期统一设计,不绑在作者元数据上。
  • 防 AI 写错: AI 看到 circuitBreaker / healthCheck 的 schema 会认真填写,产出「看似有保护」的元数据。退役后解析即报错并附处方,错误在写入时响亮暴露,不再静默通过。
  • 创业阶段不扩散: 一次批量退役 16 个键,不用建探针调度器和熔断状态机。按 NORTH-STAR「按发布批量退役」,立即生效,无过渡窗口。

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions