Implement ADR-0096: declarative connector instances (`provider`-bound `connectors:` materialized by generic executors)

[os-zhuang]

Development tracking issue for ADR-0096. The ADR (docs/adr/0096-declarative-connector-instances.md, Status: Proposed) landed with the #2612 interim PR (#2985, merged). This issue tracks moving it from Proposed → Accepted → implemented.

Why

#2612 established that declarative connectors: stack entries never reach the automation connector registry — they are catalog descriptors with no behavior. The interim fix (#2985) stops the silent trap (descriptor-only contract + boot audit warning + enabled: false marker). But for a metadata platform whose goal is AI-built enterprise core systems, integrations must be expressible and executable as pure metadata:

• AI generates metadata, not plugin code; a schema collection the AI can author but the runtime ignores is the worst failure mode (plausible, validated, dead).
• Every comparable platform treats declarative connectors as table stakes: Salesforce External Services (OpenAPI → invocable Flow actions, zero code), Power Platform custom connectors (the connector is an OpenAPI document; connections carry credentials per environment), ServiceNow IntegrationHub spokes.
• The runtime substrate already exists: connector-openapi (ADR-0023) and connector-mcp (ADR-0024) are generic executors that materialize { def, handlers } from declarative inputs. What's missing is the last mile from stack metadata to those factories.

Approach (per ADR-0096)

Type/instance separation, mirroring the datasource pattern (declared in stack, adapter in code):

connectors: [{
  name: 'billing',
  provider: 'openapi',            // ← which installed executor materializes this
  providerConfig: { spec: './billing-openapi.json', baseUrl: 'https://billing.example.com' },
  auth: { type: 'bearer', credentialRef: 'billing_api_token' },  // reference, never inline secrets
}]

At boot, the plugin registered for provider acts as a factory: materializes action handlers from the declarative config and calls engine.registerConnector(def, handlers). Declared provider with no installed factory ⇒ hard boot error (upgrade of the #2985 audit warning).

Task breakdown

• D0 — ADR review & acceptance. Circulate ADR-0096; resolve open questions (credential-resolution degraded story without a secrets service; provider-key namespace). Flip Status: Proposed → Accepted.
• D1 — Schema evolution (@objectstack/spec). Add provider, providerConfig, and credentialRef (on the auth shapes) to the connector schema; reject inline secrets at authoring/publish; changeset + .describe() for AI authoring. No execution bindings on ConnectorActionSchema (ADR-0023 non-goal).
• D2 — Provider factory registration surface. Define how a connector plugin registers a provider factory (providerConfig, resolvedAuth) => { def, handlers }; wire the registry into the automation engine.
• D3 — Boot materialization + credentialRef resolution. In service-automation, resolve each provider-bound instance at kernel:ready, resolve credentialRef via the secrets layer, register the materialized connector. Upgrade findInertDeclaredConnectors warning → hard error for provider-bound entries; keep the warning for plain descriptors.
• D4 — Conflict rule. Provider-bound instance name-colliding with a plugin-registered connector ⇒ loud boot failure (no silent precedence). Tests.
• D5 — Provider implementations. connector-openapi and connector-mcp (and connector-rest) expose provider factories reusing their existing generator/adapter APIs (ADR-0023/0024).
• D6 — Showcase upgrade. Add a live provider-bound declarative connector (e.g. provider: 'mcp') dispatched by a flow connector_action; GET /connectors lists the materialized instance. (Complements the descriptor-only demo shipped in feat(automation,spec): descriptor-only contract + boot audit for declarative connectors (#2612) #2985.)
• D7 — Open/enterprise line. Static credentials open-source; managed vault + OAuth2 refresh + per-tenant connection lifecycle enterprise (per ADR-0015). Document the boundary.

Acceptance

An AI-generated app declares a connector instance (e.g. pointing at an MCP server) as pure metadata and a flow connector_action dispatches one of its actions end-to-end; boot fails loudly for unknown provider / invalid providerConfig / unresolvable credentialRef / name conflict.

Refs

• ADR-0096: docs/adr/0096-declarative-connector-instances.md
• Declarative connectors: stack entries are inert — bridge them to the automation connector registry or document as descriptor-only #2612 (gap + interim contract), feat(automation,spec): descriptor-only contract + boot audit for declarative connectors (#2612) #2985 (interim PR, merged)
• ADR-0018 §Addendum (registry), ADR-0022 (connector = transport), ADR-0023 (OpenAPI generator), ADR-0024 (MCP adapter), ADR-0015 (open/enterprise line)

[os-zhuang]

ADR-0096 implemented — closing as completed ✅

All task-breakdown items (D0–D7) plus two runtime follow-ups have merged to main. ADR status is Accepted, and the acceptance criterion holds end-to-end: an AI-authorable, provider-bound connectors: instance is materialized at boot and dispatched by a flow connector_action; boot fails loudly on unknown provider / invalid providerConfig / unresolvable credentialRef / name conflict.

Item	Delivered by
D0 — ADR review & acceptance (Proposed → Accepted)	#2994
D1 — Schema evolution (@objectstack/spec): provider / providerConfig / auth.credentialRef, inline-secret rejection, .describe() for AI authoring	#2994
D2 — Provider factory registration surface wired into the automation engine	#2994
D3 — Boot materialization + credentialRef resolution (CredentialResolver, env-var default resolver)	#2994
D4 — Conflict rule (origin-tagged registration; cross-origin name collision = loud boot failure)	#2994
D5 — Provider implementations: connector-rest / connector-openapi / connector-mcp factories	#2994
D6 — Showcase upgrade: live provider: 'rest' instance dispatched by a flow connector_action; surfaced by GET /connectors	#2994
D7 — Open/enterprise line documented (static auth + env credentialRef open; managed vault / OAuth2 / per-tenant lifecycle enterprise)	#2994, objectstack-ai/cloud#839
F1 — Runtime re-materialization: boot and metadata:reloaded reconcile (signature-diff add / teardown / re-materialize; boot fatal, reload soft)	#3001
F2 — objectui: flow-designer connector picker reads the runtime registry (GET /api/v1/automation/connectors) and annotates · declarative	objectstack-ai/objectui#2563

Deferred as follow-up enhancements (tracked as sub-issues)

Two refinements found during implementation, both beyond the D0–D7 scope:

• feat(connector-openapi): declarative provider — resolve providerConfig.spec from a file path (ADR-0096 follow-up) #3016 — connector-openapi: resolve providerConfig.spec from a file path (currently inline spec objects only).
• feat(connector-mcp): declarative provider — non-fatal / lazy boot for unreachable MCP servers (ADR-0096 follow-up) #3017 — connector-mcp: non-fatal / lazy boot for an unreachable MCP server (unblocks a live provider: 'mcp' showcase demo).

Release

Version bumps for the touched packages (@objectstack/{spec,service-automation,connector-rest,connector-openapi,connector-mcp} → 15.1.0) are queued in the Changesets release PR #2954.

Closing as completed.

---

Generated by Claude Code