Custom Connector Architecture

When a connector stops being “a few endpoints” and becomes an untraceable knot

Assume a provider accepted a write, but the connection dropped before the response body arrived. Seconds later a webhook for the same operation appears, while the provider also deprecates one response field. If transport, authentication, schemas, retry, webhook handling and business mapping live in one function, you cannot answer basic questions: Did the write happen? Is retry safe? Is the webhook a duplicate? Does the schema change stay inside the adapter or leak into your canonical model?

The lesson output is Custom Connector Boundary and Contract Matrix v1. Every decision must be reconstructible from provider contract through canonical promotion, without real secrets, production tenants or hidden reasoning.

COM-029 ownership boundary

COM-029 owns connector architecture, contract layers and failure boundaries. COM-028 owns the WooCommerce-specific integration. COM-030 owns the canonical Order State Machine. This lesson never lets a provider status silently become internal state and never treats HTTP success as permission to mutate business truth.

Three red lines:

1. API description != runtime guarantee
2. provider payload != canonical domain
3. timeout != safe retry

Mental model: Provider contract → Transport/Auth → Schemas → Events → Retry/Rate limit → Adapter mapping → Canonical promotion → Reconciliation

Auditable path:

provider contract/version → base URL + scoped auth → request/response schema → webhook/callback semantics → event identity → idempotency/retry/backoff/rate limit → mapping adapter/version → canonical command/event → reconciliation → evidence

Each layer owns a distinct failure class. Do not blame mapping for a scope error. Do not rewrite the domain model because a provider schema drifted. Do not classify a timed-out write as success or failure before reconciliation.

Keep FACT, INFERENCE and DESIGN separate

FACT: OpenAPI Specification 3.2.1 was published on 10 September 2026 and is the current published OAS patch. OAS defines a programming-language-agnostic interface description for HTTP APIs.

FACT: In OAS 3.2.1, webhooks describe incoming requests independent from another API call, while callbacks are tied to a parent operation. Describing either mechanism does not create delivery guarantees or exactly-once semantics.

INFERENCE: Making provider contract, transport/auth, schema, delivery, retry/idempotency and mapping independently observable makes failure isolation and migration safer.

DESIGN: MAKNOW contains provider quirks inside adapters, versions mappings, reconciles uncertain writes and does not promote canonical success until decisive evidence is complete. Those are local design rules, not OpenAPI mandates.

The 23-dimension connector contract

Gate 1 — Give connector and provider explicit identity

connector_id and provider_id bind evidence to a concrete integration. “External API” is not sufficient identity.

Gate 2 — Version the provider contract independently from implementation code

contract_version captures compatibility expectations. Without it, you cannot reconstruct which mapping and tests governed a request.

Gate 3 — Treat OpenAPI ref as interface evidence, not behavior proof

openapi_ref tells you what is described. It does not prove runtime behavior, semantic compatibility, latency or delivery guarantees.

Gate 4 — Reference base URL and credentials; never embed production secrets

base_url_ref and credential references must be traceable without putting actual credentials in the connector artifact.

Gate 5 — Authentication scheme without credential scope is incomplete

OAuth/API-key type says how credentials work, not whether the credential is authorized for this operation. Missing or ambiguous scope yields HOLD_AUTH_SCOPE.

Gate 6 — Version request and response schemas separately

A provider can deprecate a response field without changing the request. If response_schema_version changes while mapping_version does not, canonical promotion must stop.

Gate 7 — Do not collapse webhook and callback semantics

A callback is associated with a parent operation; a webhook can arrive independently. Callback→webhook migration can change identity, verification, replay/retry and lifecycle—not merely an endpoint name.

Gate 8 — Inbound events need deduplicatable identity

Without event_identity, provider retry/replay cannot be distinguished from a new event. Calling something a webhook does not imply exactly-once delivery.

Gate 9 — Retryable writes require idempotency or reconciliation

A timed-out write may have succeeded remotely. Blind retry can duplicate the effect. If the provider lacks idempotency support, reconciliation must find the previous effect safely.

Gate 10 — Backoff must understand rate-limit signals

429, Retry-After or an equivalent provider signal must influence retry behavior. Tight fixed loops amplify outages and provider pressure.

Gate 11 — Provider quirks stop at the mapping adapter

Provider-specific statuses and fields do not enter the canonical model directly. A versioned adapter translates them into a canonical command/event.

Gate 12 — Reconcile uncertainty before canonical promotion

Dropped responses, delayed webhooks and ambiguous event order require a declared reconciliation_strategy before external effects become internal truth.

Gate 13 — Deprecation is an operational state

deprecation_state should expose active/deprecated/removal timing or an equivalent explicit state. A deprecated field must not remain invisible until removal day.

Gate 14 — Missing decisive evidence fails closed

Missing version, auth scope, event identity, mapping version or reconciliation produces a typed HOLD_* state instead of a clean-looking success.

Worked examples

1. Versioned baseline connector → ACCEPT_CONTRACT

Contract, schemas, scoped auth, event identity, idempotency, backoff, mapping version and reconciliation all have visible evidence.

2. Response res-v7 → res-v8 while map-v9 stays unchanged → HOLD_MAPPING_VERSION

Even if parsing still works, semantic mapping is no longer proven. Review impact and version the mapping contract first.

3. POST timeout + blind retry + no idempotency/reconciliation → HOLD_IDEMPOTENCY_GAP

Timeout does not prove that the external effect failed. Without write identity or reconciliation, retry can duplicate effects.

4. Provider status leaks directly into Order domain → HOLD_PROVIDER_LEAKAGE

Provider vocabulary stays inside the adapter. The canonical domain receives only its own command/event vocabulary.

5. Webhook without event identity, assumed exactly-once → HOLD_EVENT_IDENTITY

Delivery mechanism does not create uniqueness. Replay and duplicate delivery must be designed for.

6. Transfer: callback removed, webhook v4 added, response field deprecated

Bump contract_version and mapping_version, add webhook verification/event identity, mark the callback deprecated, and preserve canonical_command_or_event if its semantics did not change.

Common failure modes

• one client class doing auth, retry, mapping and business mutation together;
• treating OpenAPI-valid as semantically compatible;
• embedding secrets in config/package artifacts;
• auth scheme without explicit credential scope;
• schema change without mapping-version bump;
• assuming webhooks are exactly-once;
• blind retry after write timeout;
• ignoring Retry-After or equivalent signals;
• provider status leakage into canonical state;
• treating success codes as canonical completion;
• deprecation without owner/removal plan;
• copying the baseline decision during transfer without recomputation.

Alternatives and trade-offs

Endpoint glue: fastest start, weakest failure isolation and migration story.

OpenAPI-generated client: excellent for transport/types, but does not solve semantic mapping, retry safety, event identity or reconciliation on its own.

Unified provider model: can simplify consumers, but may hide provider-specific capabilities if reduced to a lowest common denominator. Loss must be explicit.

Event-driven only: good inbound latency, but without pull/reconciliation missed or replayed events may remain invisible.

Layered connector + canonical boundary: more contracts and instrumentation, but stronger isolation, migration safety and auditability. That is this lesson’s bounded pattern.

Experienced bridge: sixteen review questions

1. What are the connector/provider identities?
2. Where is contract version recorded?
3. Which OpenAPI version/reference governs this integration?
4. How are base URL and secrets referenced?
5. Does credential scope authorize this operation?
6. Are request and response schemas independently versioned?
7. Is the inbound flow a webhook or callback, and why?
8. What is event identity?
9. How are duplicate/replay deliveries detected?
10. How is a timed-out write closed safely?
11. Which failures are retried?
12. How do rate-limit signals alter backoff?
13. When must mapping version change?
14. Where does provider-specific vocabulary stop?
15. Who owns deprecation/removal?
16. Can canonical promotion be reconstructed from evidence_ref alone?

Guided and independent practice

The offline lab contains eight fixtures: baseline, schema drift, unsafe timeout retry, provider leakage, webhook without identity, insufficient auth scope, rate-limit without backoff, and callback→webhook transfer.

Independent task: the provider deprecates legacy_status, introduces status_code, removes the old callback and adds a webhook. Update the connector so adapter mapping changes, event identity and verification are explicit, and the canonical event interface remains unchanged unless semantics truly changed.

Verification evidence

A passing artifact fills all 23 dimensions or returns an explicit typed non-success state. No production secret is embedded; schema/mapping coherence is checkable; unsafe retry fails closed; provider vocabulary stops at the adapter; deprecation/reconciliation are traceable; and transfer changes only affected layers.

The lab is fully synthetic and offline. It needs no API key, network access, real store or customer data.

Assessment and transfer

To finish the lesson you must be able to:

1. explain COM-029’s boundary against COM-028 and COM-030;
2. build Custom Connector Boundary and Contract Matrix v1;
3. distinguish API description from runtime guarantee;
4. distinguish webhook from callback;
5. reject unsafe timeout retry;
6. fail closed on schema drift without mapping-version update;
7. contain provider fields/statuses behind the adapter;
8. redesign callback→webhook + deprecation transfer without needlessly breaking the canonical interface.

References and freshness

• OpenAPI Specification 3.2.1 — published 10 September 2026; rechecked 15 September 2026. FACT authority for interface description, webhooks and callbacks.
• The frozen COM-029 Bible recorded 3.2.0 as current on 3 September 2026. Bible bytes remain unchanged; the governed freshness overlay updates only the external FACT reference to 3.2.1.
• Layer boundaries, typed HOLD states, retry/reconciliation policy and canonical promotion are MAKNOW DESIGN and are not attributed to OpenAPI.