Declarative `connectors:` stack entries are inert — bridge them to the automation connector registry or document as descriptor-only

[os-zhuang]

The live connector registry behind GET /connectors and the connector_action flow node is populated only by plugins calling automationService.registerConnector(def, handlers) (packages/services/service-automation/src/engine.ts — registration requires a handler per action). Declarative connectors: entries in an app stack are registered as metadata but never reach that registry, so they cannot be dispatched: a declared connector with no plugin behind it is a descriptor with no behavior.

Found while upgrading the showcase to a registry-driven coverage manifest. The showcase demonstrates live connectors the delivered way — ConnectorRestPlugin / ConnectorSlackPlugin instances in objectstack.config.ts plugins:, exercised by the connector flows. Per Prime Directive #10 the declarative connectors: collection is recorded as an explicit waiver in STACK_COLLECTION_COVERAGE (examples/app-showcase/src/coverage.ts) pointing here. (app-crm ships declarative connector examples — examples/app-crm/src/connectors/crm-connectors.ts — which today are declared-but-inert.)

Resolution options:

1. Bridge: at boot, resolve declarative connector entries against installed connector plugins/handlers and register them (declared connector without a matching handler ⇒ loud validation error, not a silent no-op), or
2. Document as descriptor-only: make the schema's contract explicit (catalog/marketplace descriptor, not runtime wiring) and keep runtime registration plugin-only.

Once either lands, flip the showcase waiver to demonstrated.

[os-zhuang]

Resolution decided — option 2 now (hardened), option 1's correct form as roadmap.

Analysis (platform-level, not customer-specific): for a metadata platform whose mission is AI-built enterprise core business systems, a schema collection the AI can author but the runtime ignores is the worst shippable failure mode — plausible, schema-valid, dead. Comparable platforms treat declarative connectors as table stakes (Salesforce External Services, Power Platform custom connectors, ServiceNow IntegrationHub). But the naive bridge (name-match declared entries against installed plugins) was rejected: if the plugin is installed it registers itself, so name-matching adds nothing and creates a two-sources-of-truth drift hazard. And ConnectorActionSchema deliberately carries no execution binding (ADR-0023 rejected re-inventing OpenAPI in the stack schema), so descriptors are structurally uninterpretable into behavior.

Landing now — PR #2985 (interim, stops the silent trap):

• Boot audit in service-automation: declared connectors with actions and no same-name runtime registration log a loud warning at kernel:ready / metadata:reloaded.
• Descriptor-only contract documented in stack.zod.ts + integration/connector.zod.ts (including .describe() text for AI authoring); enabled: false = deliberate catalog-only descriptor.
• Showcase demonstrates the collection per that contract; the STACK_COLLECTION_COVERAGE waiver flips to demonstrated.

Roadmap — #2977 / ADR-0096 (the correct option 1): declarative connector instances with type/instance separation — a provider field binds an entry to an installed generic executor (connector-openapi ADR-0023 / connector-mcp ADR-0024 / connector-rest), which materializes { def, handlers } at boot and registers it; credentialRef instead of inline secrets; declared-provider-without-executor becomes a hard boot error. That upgrade makes the collection genuinely dispatchable along the architecture the ADRs already settled, instead of against it.

Closing via #2985; descriptor-only is the documented contract until #2977 lands.

---

Generated by Claude Code