ComfyUI-OpenClaw/docs/adr/ADR-0003-connector-extraction-feasibility-and-seams.md

ADR-0003: Connector Extraction Feasibility And Split-Package Seams

• Status: Accepted
• Date: 2026-04-24
• Owners: OpenClaw maintainers
• Related roadmap items: R162 with prior boundary decision in ADR-0002

Context

ADR-0002 established that the connector is an optional attached subsystem, not the primary published artifact of this repository. The remaining question is whether that attached subsystem should now be extracted into a separately packaged connector or separate repo.

Current code structure still mixes:

• connector platform adapters and runtime
• shared installation/token lifecycle services
• shared callback signing and replay-protection contracts
• backend delivery/result APIs that the connector calls locally
• tenant/config/auth boundaries that remain owned by the core package

That means extraction is no longer a purely packaging question. It is a shared-contract question.

Decision

OpenClaw adopts a no-go-for-split-now decision for connector extraction.

Current recommendation:

1. Keep the connector in-repo as an optional attached subsystem.
2. Treat a future optional extra package as the only plausible next extraction target.
3. Treat both sidecar-only distribution and separate repo / primary connector package as no-go now options.

Minimum Stable Seams Required Before Any Split

Any future extraction must first stabilize these seam families:

1. installation registry and token refs

   • workspace/account binding records
   • tenant-scoped token-reference ownership
   • installation diagnostics and fail-closed resolution

2. interactive callback security contract

   • signed callback envelopes
   • timestamp / replay / idempotency checks
   • action-policy mapping and approval downgrade semantics

3. delivery and result bridge

   • submission/result polling contract
   • callback delivery expectations
   • backend result payload compatibility

4. config/auth and tenant boundary

   • connector runtime config contract
   • admin token / auth expectations
   • tenant header behavior
   • server-side secret/state ownership

Why Separate Packaging Is A No-Go Now

Current blockers are concrete, not theoretical:

• shared services import connector types and connector adapters import shared services, so extraction would currently create unstable bidirectional package seams
• installation/token/state ownership still lives in shared repo services rather than a versioned connector-boundary package
• connector API/client flows still assume in-repo backend evolution instead of a versioned external backend contract
• services/sidecar still imports connector config/client modules directly, so even a packaging-only split would not isolate ownership yet

Consequences

Positive:

• maintainers now have one explicit go/no-go answer instead of repeatedly re-litigating extraction
• future connector extraction work can target named seam families instead of rediscovering coupling ad hoc
• admin diagnostics can expose the same contract to future packaging or release automation

Trade-offs:

• the repo intentionally keeps connector and core package code together for now
• packaging hygiene remains a future concern rather than a solved distribution problem
• extraction pressure is deferred until shared contracts are versionable on their own

Rejected Alternatives

1. Extract connector into a separate repo now

   • Rejected because current coupling would move instability across package boundaries instead of reducing it.

2. Publish connector as a sidecar-only primary distribution now

   • Rejected because current operator workflows still assume the embedded OpenClaw package/runtime remains primary.

3. Leave extraction as an undocumented future possibility

   • Rejected because future packaging work needs an explicit seam map and a clear no-go baseline.