Upgrade a Connector to the Frozen SDK

The frozen connector SDK makes product integrations use one trusted execution, failure, lifecycle, and conformance boundary. This guide migrates a legacy connector without changing native AIP semantics.

Before You Change Code

Record the connector’s current:

• published capabilities and schemas;
• upstream product revision and API version;
• authentication and tenant mapping;
• streaming, cancellation, retry, and idempotency behavior;
• transaction, compensation, and reconciliation claims;
• webhook verification and replay rules;
• deterministic and live evidence.

An SDK migration must not silently broaden the advertised product contract.

1. Implement the Base Contract

Implement Connector with a stable id, discovery, error mapping, and a readiness check that tests the real required boundary without exposing secrets.

Implement CapabilityProviderConnector for executable discovery. Every capability must have strict schemas and a complete conservative contract.

2. Move Invocation to FrozenConnector

Implement FrozenConnector::invoke_typed. It receives an ActionExecutionContext established by the runtime. Use its authenticated actor, verified tenant, credential reference, deadline, cancellation token, trace context, transaction context, and stream publisher.

Do not rebuild trusted context from action input, legacy ConnectorContext metadata, or model output.

3. Declare Exact Implementation Support

Return CapabilityImplementationSupport for each capability. The support matrix must agree with the capability contract.

Only override optional SDK operations when the provider behavior exists:

• plan_typed;
• commit_typed;
• compensate_typed;
• cancel_typed;
• reconcile_typed;
• emit_typed;
• ingest_typed.

The defaults fail explicitly. Do not replace an unsupported failure with a successful no-op.

4. Normalize Failures

Return ConnectorFailure with a stable code, category, retry safety, optional backoff, provider correlation, remote status, uncertain-outcome flag, redacted details, source component, and failed operation.

When a provider may have committed, include a durable ProviderOperationRef and set uncertain_outcome. Automatic retry is not a valid substitute for reconciliation.

5. Move Secrets to the Final Boundary

Store secret bytes in ConnectorSecret or a deployment credential provider. Protocol objects carry opaque references only. Verify that manifests, action state, errors, receipts, logs, traces, and debug output cannot serialize secret material.

6. Register through Gateway Admission

Bind each admitted capability with FrozenConnectorHandler. Gateway admission must fail when discovery, implementation support, and registered handlers disagree.

Remove any legacy execution path that can bypass trusted context or create a second lifecycle store.

7. Run the Complete Conformance Family

Test every advertised behavior:

1. identity and discovery;
2. capability and schema admission;
3. trusted execution context;
4. invocation and typed failure mapping;
5. streaming when advertised;
6. cancellation when advertised;
7. idempotency and collision handling;
8. approval park and resume when required;
9. plan, commit, and compensation when advertised;
10. uncertain-outcome reconciliation;
11. ingress, egress, callback, or channel behavior when applicable;
12. restart recovery and redaction.

Mark an inapplicable family explicitly. Absence of a test is not evidence that the behavior is unsupported.

8. Qualify the Pinned Product

Run an isolated-live campaign against the exact upstream revision and built artifact. Retain secret-free evidence with source, image, topology, operation, restart, and result identities.

The connector is migration-complete only when its manifest, frozen implementation, conformance report, and observed provider behavior agree.

See Build a Connector, the Connector Contract, and Conformance and Qualification.