feat(automation): ADR-0096 follow-ups — runtime re-materialization + connector origin (#2977)

[os-zhuang]

Follow-ups to the merged ADR-0096 (#2994). Tracking: #2977. Two cohesive additions to @objectstack/service-automation:

1. Runtime re-materialization

Provider-bound declarative connectors: instances (ADR-0096) materialized only at boot — a connector published from Studio, or introduced by a dev reload, did not become dispatchable until a full restart. materializeDeclaredConnectors is now a reconcile against the declared set, run both at boot and on metadata:reloaded (the Studio-publish / dev-reload hook that already re-syncs flows):

• Add newly-declared instances; tear down removed / newly-enabled:false ones (calling their close, e.g. an MCP connection); re-materialize only instances whose signature — a stable hash of provider + providerConfig + auth + identity — changed. An unchanged MCP instance is not reconnected on an unrelated metadata reload.
• Boot stays fatal ("fail loudly", unchanged): unknown provider / invalid providerConfig / unresolvable credentialRef / name conflict aborts startup.
• Reload is soft: the same problems are logged and the offending entry skipped, so a bad publish never crashes a running server. A changed instance's old connector keeps serving until its replacement materializes successfully.

Tracking moved from a materializedConnectorClosers array to a materializedConnectors Map (name → { signature, close }).

2. Connector origin on the descriptor

ConnectorDescriptor (served by GET /api/v1/automation/connectors) now carries origin: 'plugin' | 'declarative', so the flow designer can distinguish a materialized declarative instance from a plugin-registered connector. Additive — the field is always present; existing consumers ignore it. (Enables the Studio picker to label declarative connectors; that UI change lands separately in objectui.)

Verification

• Reload reconcile: 6 tests (publish-after-boot / remove / newly-disabled / unchanged-untouched / changed-re-materialized / soft-failure-survives). origin: asserted on the descriptor.
• service-automation green (26 files, 285 tests); runtime dispatcher green (523 tests) — the new required descriptor field breaks no consumer. Full DTS build clean; ESLint clean; changeset included.
• ADR-0096 updated: "boot-time only" scope note replaced with a "Runtime reconcile (landed)" section.

Compatibility

Additive — boot behavior is byte-for-byte unchanged (same fatal: true path); the descriptor gains a field. No schema or authorable-key changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Pbmw3pMqNJfPbkvwh9Fkjs

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 16, 2026 4:04am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): packages/services.

6 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/webhooks.mdx (via packages/services)
• content/docs/kernel/runtime-services/audit-service.mdx (via packages/services)
• content/docs/kernel/runtime-services/index.mdx (via packages/services)
• content/docs/kernel/runtime-services/settings-service.mdx (via packages/services)
• content/docs/plugins/packages.mdx (via packages/services)
• content/docs/protocol/kernel/i18n-standard.mdx (via packages/services)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.