feat(automation,spec): descriptor-only contract + boot audit for declarative connectors (#2612) - #2985
Merged
Merged
Conversation
…arative connectors (#2612) Declarative `connectors:` stack entries never reach the automation connector registry (plugins only, via engine.registerConnector — ADR-0018 §Addendum), so a declared connector with actions and no plugin behind it looked dispatchable but was silently inert. Make the contract explicit and audited, and chart the upgrade path: - service-automation: kernel:ready + metadata:reloaded audit — declared connectors with actions but no same-name runtime registration log a loud warning naming each inert entry (findInertDeclaredConnectors, tested). - spec: stack.zod.ts `connectors:` and integration/connector.zod.ts now document the descriptor-vs-registered contract (including .describe() text for AI stack authoring); `enabled: false` marks a deliberate catalog-only descriptor and silences the audit. - showcase: demonstrates the declarative collection per the documented contract (catalog descriptor, enabled: false) and flips the #2612 STACK_COLLECTION_COVERAGE waiver to demonstrated; live connectors remain demonstrated via the connector plugins. - ADR-0096 (Proposed): declarative connector instances — provider-bound entries materialized by the ADR-0023/0024 generic executors, credentialRef instead of inline secrets, loud boot error for unbound providers. Tracked in #2977. Closes #2612. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TQFjxP9nJqyZyRYTNqRNxJ
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 99 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
… (lint #2035 rule) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TQFjxP9nJqyZyRYTNqRNxJ
os-zhuang
marked this pull request as ready for review
July 15, 2026 16:02
8 tasks
68 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
#2612: declarative
connectors:stack entries are registered as metadata but never reach the automation engine's connector registry — only plugins populate it viaengine.registerConnector(def, handlers)(ADR-0018 §Addendum). A declared connector with actions and no plugin behind it looked dispatchable but was silently inert — the worst failure mode for AI-authored stacks (plausible, schema-valid, dead).This PR is the interim resolution (option 2 of #2612, hardened) plus the roadmap for the correct bridge (option 1): ADR-0096 / #2977.
What
service-automation) — atkernel:ready(and re-checked onmetadata:reloaded), declared connectors withactionsbut no same-name runtime registration log a loud warning naming each inert entry, explaining the descriptor-only contract, and pointing at the fixes (install the matching connector plugin / mark deliberate catalog entries / Implement ADR-0096: declarative connector instances (provider-boundconnectors:materialized by generic executors) #2977 for provider binding). Pure helperfindInertDeclaredConnectors+ 9 tests (pure contract + kernel-boot wiring).spec) —stack.zod.tsconnectors:andintegration/connector.zod.tsnow state the descriptor-vs-registered contract explicitly, including the.describe()text AI stack authoring sees.enabled: falseis documented as the deliberate catalog-only marker (silences the audit).src/system/connectors/: a catalog descriptor withenabled: falseand I/O-schema'd actions) and flips the Declarativeconnectors:stack entries are inert — bridge them to the automation connector registry or document as descriptor-only #2612STACK_COLLECTION_COVERAGEwaiver todemonstrated. Live connectors remain demonstrated the delivered way (ConnectorRestPlugin / ConnectorSlackPlugin inplugins:).provider-bound entries materialized at boot by the ADR-0023/0024 generic executors (openapi/mcp/rest),credentialRefinstead of inline secrets, hard boot error for unbound providers, explicit two-sources-of-truth rule. Tracked in Implement ADR-0096: declarative connector instances (provider-boundconnectors:materialized by generic executors) #2977.Verification
service-automation: 25 files / 267 tests pass (includes the newconnector-descriptor-audit.test.ts).spec: 252 files / 6826 tests pass.test/coverage.test.ts13/13 pass; new connectors module typechecks clean.Closes #2612. Roadmap: #2977 (ADR-0096).
🤖 Generated with Claude Code
https://claude.ai/code/session_01TQFjxP9nJqyZyRYTNqRNxJ
Generated by Claude Code