{
  "schemaVersion": "1.0",
  "title": "Upgrade a connector to the frozen SDK",
  "description": "Use this guide to move an existing Rust connector from legacy connector or direct ActionHandler execution to the FrozenConnector boundary. It is for connector developers who need to preserve published capability behavior while adopting trus",
  "canonical": "https://getaip.org/docs/guides/upgrade-connector-sdk",
  "route": "/docs/guides/upgrade-connector-sdk",
  "source": "docs/guides/upgrade-connector-sdk.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Guide",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "97be86e9efedf07ecf1783b03800f683f107fb04",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/guides/upgrade-connector-sdk.md",
    "txt": "/docs/download/guides/upgrade-connector-sdk.txt",
    "json": "/docs/download/guides/upgrade-connector-sdk.json",
    "pdf": "/docs/download/guides/upgrade-connector-sdk.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Upgrade a connector to the frozen SDK\ndescription: Move an existing connector to trusted typed execution without changing its contract\nkind: how-to\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Upgrade a connector to the frozen SDK\n\nUse this guide to move an existing Rust connector from legacy connector or\ndirect `ActionHandler` execution to the `FrozenConnector` boundary. It is for\nconnector developers who need to preserve published capability behavior while\nadopting trusted execution context, typed failures, and explicit implementation\nsupport.\n\nThis migration does not change AIP 1.0 wire semantics. It also does not create a\nstandalone host, admit an artifact into the connector registry, or qualify a\nprovider deployment. Those are separate steps after the SDK migration passes.\n\nThe procedure reflects source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`.\n\n## Use this procedure for an existing connector\n\nApply this migration when a connector already implements some combination of\n`Connector`, `CapabilityProviderConnector`, `OutboundConnector`,\n`InboundConnector`, or `ActionHandler`, but production execution does not\nyet go through `FrozenConnectorHandler`.\n\nDo not use it to:\n\n- design a new provider surface;\n- move an already frozen connector from a bundled daemon to the fleet;\n- change capability IDs, schemas, or side-effect contracts as part of an SDK\n  cleanup;\n- claim new streaming, cancellation, retry, transaction, approval, or\n  credential behavior without implementing and testing it.\n\nIf the provider boundary is still undefined, start with\n[Build a connector](build-a-connector.md).\n\n## Prepare the migration boundary\n\nYou need:\n\n- the exact source and provider revisions for the current connector;\n- permission to inspect its deployment configuration and secret flow;\n- current deterministic, conformance, and live-provider evidence;\n- an isolated account or provider stub for regression tests;\n- authority to change connector registration and roll it back;\n- retained copies of the previous manifest, schemas, and artifact identity.\n\nDo not expose secret values while collecting the baseline. Record secret kinds,\nopaque references, scope, and rotation behavior instead.\n\nThe highest-risk input is the current execution path. Trace it from gateway or\nmodule registration to the provider call. Identify whether any path:\n\n- accepts actor, tenant, credential, approval, or transaction authority from an\n  action payload;\n- invokes `ActionHandler::handle` without an execution context;\n- drops idempotency, deadline, cancellation, or redaction state;\n- writes to a second lifecycle or idempotency store;\n- converts a provider timeout into a retryable success path;\n- serializes credentials or full provider payloads in an error.\n\nBlock migration rollout until each such path is removed, isolated, or recorded\nas an explicit compatibility-only boundary.\n\n## Capture a contract baseline\n\nSerialize the current manifest under the exact configuration class you intend\nto migrate. Retain the canonical manifest digest and a stable inventory of:\n\n| Baseline | Compare after migration |\n|---|---|\n| Connector and provider identity | Same connector family and account boundary |\n| Capability IDs and kinds | No missing, renamed, or newly callable operation |\n| Input and output schemas | Same accepted and returned data shapes |\n| Side effects and risk | No weakened mutation or data classification |\n| Idempotency and retry | Same key requirement, scope, collision, and safety |\n| Completion behavior | Same synchronous, asynchronous, or streaming claim |\n| Cancellation | Same provider-reaching behavior |\n| Approval | Same policy and retained evidence |\n| Transactions | Same plan, commit, reconciliation, and compensation behavior |\n| Credentials | Same required handle and scopes without secret material |\n| Ingress | Same signature, account, timestamp, replay, and durability boundary |\n\nA byte-identical manifest is a useful migration target when the existing\ncontract is accurate. If the baseline overclaims behavior, correct the contract\nas a separately reviewed change and record why its digest changed.\n\n## Map legacy paths to frozen operations\n\nKeep `Connector` as the base discovery and health contract. Keep\n`CapabilityProviderConnector` when the gateway, tests, or compatibility code\nneeds the capability list independently.\n\nMove production execution into these frozen operations:\n\n| Existing behavior | Frozen destination |\n|---|---|\n| Normal provider invocation | `invoke_typed` |\n| Dry run or transaction plan | `plan_typed` |\n| Prepared mutation commit | `commit_typed` |\n| Governed compensation | `compensate_typed` |\n| Provider-reaching cancellation | `cancel_typed` |\n| Unknown-outcome status recovery | `reconcile_typed` |\n| Terminal result or provider event emission | `emit_typed` |\n| Provider event ingestion under trusted authority | `ingest_typed` |\n\nEvery optional operation already returns\n`connector.operation_unsupported`. Leave that default in place until the\nprovider path exists. A successful no-op is not an acceptable replacement.\n\nThe `FrozenConnectorHandler` chooses the typed operation from the action\ntransaction mode:\n\n| Transaction mode | Called operation |\n|---|---|\n| `dry_run` or `plan` | `plan_typed` |\n| `commit` | `commit_typed` |\n| `compensate` | `compensate_typed` |\n| `reconcile` | `reconcile_typed` |\n| `execute`, `rollback_not_supported`, or no transaction | `invoke_typed` |\n\nContextual cancellation uses `cancel_typed`. Reconciliation also requires\ndurable transaction context and a provider operation ID; the adapter rejects a\nrequest that lacks either.\n\n## Move authority into trusted execution context\n\nEach typed operation receives an `ActionExecutionContext`. It is a\nnon-serializable runtime value containing:\n\n- the transport-authenticated actor and verified tenant;\n- an opaque credential handle;\n- an absolute deadline and cooperative cancellation token;\n- an owned idempotency reservation;\n- verified approval evidence;\n- transaction state and a durable provider-operation checkpoint publisher;\n- a provider-effect checkpoint publisher;\n- the incremental stream publisher;\n- trusted trace identifiers and the redaction policy.\n\nUse these fields for authorization, account scope, credentials, lifecycle, and\noutput handling. Do not reconstruct them from `Action.identity`, input,\nmetadata, model output, or legacy process globals.\n\n`ConnectorContext::from_execution` is a narrow migration helper. It projects\nonly the tenant ID, authenticated principal ID, authentication issuer, and\ntrace ID. It does not preserve the credential handle, deadline, idempotency\nreservation, approval evidence, transaction state, cancellation token,\ncheckpoint publishers, stream publisher, or redaction policy.\n\nUse that projection only for an audited legacy helper that needs those four\nnon-secret values. Do not pass it through an old invocation path and treat the\nresult as frozen execution.\n\n## Declare implementation support per capability\n\nImplement `FrozenConnector::implementation_support` from the admitted\noperation, not from a connector-wide constant. A connector whose configuration\nenables only part of the provider surface should return support only for that\npart.\n\nSet:\n\n- `invocation` when the capability has a typed provider path;\n- `cancellation` only when cancellation reaches the provider operation;\n- `streaming` only when chunks use the supplied stream publisher;\n- `retry` only when classification and downstream idempotency match the\n  contract;\n- `transaction` only when plan and commit exist;\n- `reconciliation` only when uncertain outcomes can be resolved;\n- `compensation` only for a separately governed compensation action;\n- `approval` only when verified evidence and resume behavior are enforced;\n- `credentials` only when a deployment credential handle is resolved.\n\nManifest admission compares this map with each capability contract. It reports\n`implementation.missing` when a required callable capability has no\nimplementation claim and `implementation.claim_unsupported` when the contract\nadvertises behavior that the support map does not implement.\n\nDo not solve a mismatch by setting every support flag to `true`. Correct the\nimplementation or narrow the contract.\n\n## Convert errors and secrets\n\nReturn `ConnectorFailure` from typed operations. Preserve the provider\nrequest ID, provider operation reference, remote status, retry delay, and\nunknown-outcome decision when available. Keep the message and structured\ndetails bounded and redacted.\n\nAudit each legacy error mapping:\n\n| Legacy behavior | Migration decision |\n|---|---|\n| String-only provider error | Add a stable namespaced code, category, source, and operation |\n| Every timeout marked retryable | Split pre-dispatch failure from possible provider commit |\n| Mutation timeout retried | Mark uncertain and add reconciliation or fail closed |\n| Local cancellation reported as provider cancellation | Keep outcome conservative until the provider confirms |\n| Full response included in diagnostics | Retain bounded redacted fields and correlation IDs only |\n| Unsupported operation returns success | Restore the explicit unsupported failure |\n\nWrap in-memory credential bytes in `ConnectorSecret` and expose them only at\nthe provider request boundary. Keep opaque credential references in protocol\nand registry data. Verify that debug output, manifests, action state, errors,\nreceipts, logs, traces, and evidence cannot serialize the raw value.\n\n## Switch to the frozen adapter\n\nFor an embedded gateway, replace the legacy outbound registration path with\n`register_frozen_connector`. The frozen registration path discovers the\nmanifest, creates one `FrozenConnectorHandler` per non-resource capability,\nadmits the manifest with those handlers, and registers the connector.\n\nThe adapter provides two fail-closed checks:\n\n1. `ActionHandler::handle` without trusted context returns an authorization\n   error.\n2. A handler bound to one capability rejects an action for a different\n   capability.\n\nDo not register the connector itself as the production `ActionHandler` after\ncutover. A connector may temporarily retain older trait implementations for\ntests or known compatibility callers, but those paths should not receive new\nproduction traffic.\n\nFor a standalone connector host, the common host constructs the same\nper-capability frozen handlers from the discovered manifest. The host also\nverifies the configured gateway and pinned route before creating trusted\nexecution context.\n\n## Test the migration\n\nRun the old and new paths against the same controlled provider behavior before\nswitching registration. Compare:\n\n- canonical manifest and schema digests;\n- successful outputs and terminal statuses;\n- provider requests and idempotency keys;\n- errors, retry delays, and unknown-outcome flags;\n- cancellation and streaming behavior;\n- approval and transaction state transitions;\n- webhook acceptance, replay rejection, and durable event publication;\n- redacted logs, traces, receipts, and retained evidence.\n\nAdd focused negative tests for:\n\n- context-free handler invocation;\n- a capability sent to the wrong frozen handler;\n- contract and support-map disagreement;\n- expired deadline and cooperative cancellation;\n- missing approval or credential context;\n- duplicate idempotency keys with changed input;\n- commit interruption before and after a provider operation checkpoint;\n- restart with pending or uncertain work;\n- credential rotation while a route pins the previous revision.\n\nImplement a `ConnectorConformanceDriver` and run every scenario implied by the\nmanifest and support map. Record an unsupported feature as not applicable, not\npassed. Retain the exact source revision, artifact identity, topology, procedure,\ntime, and result for any conformance or qualification claim.\n\n## Cut over one bounded route\n\nUse a reversible rollout:\n\n1. freeze the approved baseline manifest and evidence;\n2. deploy the migrated artifact without changing capability bindings;\n3. select one non-production tenant or local registration path;\n4. switch that path from the legacy handler to the frozen adapter;\n5. verify discovery before allowing an action;\n6. run a non-destructive or explicitly approved action;\n7. exercise one failure and one restart path;\n8. compare provider requests, runtime state, and retained evidence;\n9. expand only after the migration result is accepted.\n\nDo not send the same mutation through old and new handlers as a comparison.\nUse provider fixtures, read-only operations, or distinct idempotency and account\nboundaries.\n\n## Hand the connector to fleet packaging\n\nA connector that passes the frozen SDK migration is ready for a separate\ndeployment conversion, not yet for fleet traffic. The next work item is to:\n\n- compose a standalone host around the connector;\n- build and identify an immutable host artifact;\n- generate the manifest and implementation support from that artifact;\n- collect the seven admission evidence families;\n- create connector type, version, instance, replica, policy, and tenant binding\n  records;\n- verify and apply a signed admission package;\n- qualify the exact artifact through an admitted route.\n\nFollow the connector-building procedure linked earlier for that complete\nboundary. Keep bundled-to-fleet deployment changes outside the SDK migration\ndiff so execution regressions and topology regressions remain distinguishable.\n\n## Verify the upgraded connector\n\nThe SDK migration is complete only when:\n\n- published capability behavior is unchanged or every correction is separately\n  approved;\n- each callable capability has an accurate implementation support record;\n- production registration creates `FrozenConnectorHandler` instances;\n- context-free execution fails closed;\n- all authority and lifecycle decisions use trusted execution context;\n- failures preserve retry and uncertain-outcome semantics;\n- secret bytes cannot escape the connector-to-provider request boundary;\n- applicable conformance scenarios pass for the exact migrated artifact;\n- the old production handler path receives no new traffic;\n- a rollback artifact and state-preservation procedure are available.\n\nSource presence establishes implementation only. Report conformance,\nqualification, live verification, and production readiness as separate evidence\nclasses.\n\n## Decide migration failures\n\n| Failure | Decision |\n|---|---|\n| Manifest digest changes unexpectedly | Stop and identify the changed field before routing |\n| A contract claim lacks support | Implement it or narrow the contract in a separate reviewed change |\n| Frozen handler returns authorization for normal traffic | Fix gateway registration or trusted-context construction; do not bypass the adapter |\n| Legacy and frozen outputs differ | Compare provider request, context, and error mapping before expanding |\n| Cancellation creates an uncertain mutation | Preserve state and reconcile instead of retrying |\n| A compatibility caller still needs the old trait | Keep the trait behind an explicit boundary while production stays frozen |\n| Conformance scenario is absent | Add the scenario or mark a source-backed non-applicable reason |\n| Live-provider behavior changed | Stop rollout and re-baseline the provider revision |\n\n## Roll back without restoring a bypass\n\nDrain the migrated route and stop new assignments before restoring the\npreviously accepted artifact or local registration. Preserve runtime state,\nidempotency records, provider operation references, callbacks, evidence, and\nlogs needed to finish or reconcile in-flight work.\n\nRestore the old path only in the environment where its documented trust\nlimitations were already accepted. Do not route high-risk traffic through a\ncontext-free handler as an emergency shortcut. Correct the migration under a\nnew immutable artifact identity, repeat the regression and conformance work,\nand cut over through the same bounded route.\n\n## Related documentation\n\n- [Capabilities](../concepts/capabilities.md)\n- [Actions and sessions](../concepts/actions-and-sessions.md)\n- [Identity and trust](../concepts/identity-and-trust.md)\n- [Profiles and connectors](../concepts/profiles-and-connectors.md)\n",
    "text": "Upgrade a connector to the frozen SDK\n\nUse this guide to move an existing Rust connector from legacy connector or\ndirect ActionHandler execution to the FrozenConnector boundary. It is for\nconnector developers who need to preserve published capability behavior while\nadopting trusted execution context, typed failures, and explicit implementation\nsupport.\n\nThis migration does not change AIP 1.0 wire semantics. It also does not create a\nstandalone host, admit an artifact into the connector registry, or qualify a\nprovider deployment. Those are separate steps after the SDK migration passes.\n\nThe procedure reflects source revision\n97be86e9efedf07ecf1783b03800f683f107fb04.\n\nUse this procedure for an existing connector\n\nApply this migration when a connector already implements some combination of\nConnector, CapabilityProviderConnector, OutboundConnector,\nInboundConnector, or ActionHandler, but production execution does not\nyet go through FrozenConnectorHandler.\n\nDo not use it to:\n• design a new provider surface;\n• move an already frozen connector from a bundled daemon to the fleet;\n• change capability IDs, schemas, or side-effect contracts as part of an SDK\n  cleanup;\n• claim new streaming, cancellation, retry, transaction, approval, or\n  credential behavior without implementing and testing it.\n\nIf the provider boundary is still undefined, start with\nBuild a connector (build-a-connector.md).\n\nPrepare the migration boundary\n\nYou need:\n• the exact source and provider revisions for the current connector;\n• permission to inspect its deployment configuration and secret flow;\n• current deterministic, conformance, and live-provider evidence;\n• an isolated account or provider stub for regression tests;\n• authority to change connector registration and roll it back;\n• retained copies of the previous manifest, schemas, and artifact identity.\n\nDo not expose secret values while collecting the baseline. Record secret kinds,\nopaque references, scope, and rotation behavior instead.\n\nThe highest-risk input is the current execution path. Trace it from gateway or\nmodule registration to the provider call. Identify whether any path:\n• accepts actor, tenant, credential, approval, or transaction authority from an\n  action payload;\n• invokes ActionHandler::handle without an execution context;\n• drops idempotency, deadline, cancellation, or redaction state;\n• writes to a second lifecycle or idempotency store;\n• converts a provider timeout into a retryable success path;\n• serializes credentials or full provider payloads in an error.\n\nBlock migration rollout until each such path is removed, isolated, or recorded\nas an explicit compatibility-only boundary.\n\nCapture a contract baseline\n\nSerialize the current manifest under the exact configuration class you intend\nto migrate. Retain the canonical manifest digest and a stable inventory of:\n\n| Baseline | Compare after migration |\n\n| Connector and provider identity | Same connector family and account boundary |\n| Capability IDs and kinds | No missing, renamed, or newly callable operation |\n| Input and output schemas | Same accepted and returned data shapes |\n| Side effects and risk | No weakened mutation or data classification |\n| Idempotency and retry | Same key requirement, scope, collision, and safety |\n| Completion behavior | Same synchronous, asynchronous, or streaming claim |\n| Cancellation | Same provider-reaching behavior |\n| Approval | Same policy and retained evidence |\n| Transactions | Same plan, commit, reconciliation, and compensation behavior |\n| Credentials | Same required handle and scopes without secret material |\n| Ingress | Same signature, account, timestamp, replay, and durability boundary |\n\nA byte-identical manifest is a useful migration target when the existing\ncontract is accurate. If the baseline overclaims behavior, correct the contract\nas a separately reviewed change and record why its digest changed.\n\nMap legacy paths to frozen operations\n\nKeep Connector as the base discovery and health contract. Keep\nCapabilityProviderConnector when the gateway, tests, or compatibility code\nneeds the capability list independently.\n\nMove production execution into these frozen operations:\n\n| Existing behavior | Frozen destination |\n\n| Normal provider invocation | invoketyped |\n| Dry run or transaction plan | plantyped |\n| Prepared mutation commit | committyped |\n| Governed compensation | compensatetyped |\n| Provider-reaching cancellation | canceltyped |\n| Unknown-outcome status recovery | reconciletyped |\n| Terminal result or provider event emission | emittyped |\n| Provider event ingestion under trusted authority | ingesttyped |\n\nEvery optional operation already returns\nconnector.operationunsupported. Leave that default in place until the\nprovider path exists. A successful no-op is not an acceptable replacement.\n\nThe FrozenConnectorHandler chooses the typed operation from the action\ntransaction mode:\n\n| Transaction mode | Called operation |\n\n| dryrun or plan | plantyped |\n| commit | committyped |\n| compensate | compensatetyped |\n| reconcile | reconciletyped |\n| execute, rollbacknotsupported, or no transaction | invoketyped |\n\nContextual cancellation uses canceltyped. Reconciliation also requires\ndurable transaction context and a provider operation ID; the adapter rejects a\nrequest that lacks either.\n\nMove authority into trusted execution context\n\nEach typed operation receives an ActionExecutionContext. It is a\nnon-serializable runtime value containing:\n• the transport-authenticated actor and verified tenant;\n• an opaque credential handle;\n• an absolute deadline and cooperative cancellation token;\n• an owned idempotency reservation;\n• verified approval evidence;\n• transaction state and a durable provider-operation checkpoint publisher;\n• a provider-effect checkpoint publisher;\n• the incremental stream publisher;\n• trusted trace identifiers and the redaction policy.\n\nUse these fields for authorization, account scope, credentials, lifecycle, and\noutput handling. Do not reconstruct them from Action.identity, input,\nmetadata, model output, or legacy process globals.\n\nConnectorContext::fromexecution is a narrow migration helper. It projects\nonly the tenant ID, authenticated principal ID, authentication issuer, and\ntrace ID. It does not preserve the credential handle, deadline, idempotency\nreservation, approval evidence, transaction state, cancellation token,\ncheckpoint publishers, stream publisher, or redaction policy.\n\nUse that projection only for an audited legacy helper that needs those four\nnon-secret values. Do not pass it through an old invocation path and treat the\nresult as frozen execution.\n\nDeclare implementation support per capability\n\nImplement FrozenConnector::implementationsupport from the admitted\noperation, not from a connector-wide constant. A connector whose configuration\nenables only part of the provider surface should return support only for that\npart.\n\nSet:\n• invocation when the capability has a typed provider path;\n• cancellation only when cancellation reaches the provider operation;\n• streaming only when chunks use the supplied stream publisher;\n• retry only when classification and downstream idempotency match the\n  contract;\n• transaction only when plan and commit exist;\n• reconciliation only when uncertain outcomes can be resolved;\n• compensation only for a separately governed compensation action;\n• approval only when verified evidence and resume behavior are enforced;\n• credentials only when a deployment credential handle is resolved.\n\nManifest admission compares this map with each capability contract. It reports\nimplementation.missing when a required callable capability has no\nimplementation claim and implementation.claimunsupported when the contract\nadvertises behavior that the support map does not implement.\n\nDo not solve a mismatch by setting every support flag to true. Correct the\nimplementation or narrow the contract.\n\nConvert errors and secrets\n\nReturn ConnectorFailure from typed operations. Preserve the provider\nrequest ID, provider operation reference, remote status, retry delay, and\nunknown-outcome decision when available. Keep the message and structured\ndetails bounded and redacted.\n\nAudit each legacy error mapping:\n\n| Legacy behavior | Migration decision |\n\n| String-only provider error | Add a stable namespaced code, category, source, and operation |\n| Every timeout marked retryable | Split pre-dispatch failure from possible provider commit |\n| Mutation timeout retried | Mark uncertain and add reconciliation or fail closed |\n| Local cancellation reported as provider cancellation | Keep outcome conservative until the provider confirms |\n| Full response included in diagnostics | Retain bounded redacted fields and correlation IDs only |\n| Unsupported operation returns success | Restore the explicit unsupported failure |\n\nWrap in-memory credential bytes in ConnectorSecret and expose them only at\nthe provider request boundary. Keep opaque credential references in protocol\nand registry data. Verify that debug output, manifests, action state, errors,\nreceipts, logs, traces, and evidence cannot serialize the raw value.\n\nSwitch to the frozen adapter\n\nFor an embedded gateway, replace the legacy outbound registration path with\nregisterfrozenconnector. The frozen registration path discovers the\nmanifest, creates one FrozenConnectorHandler per non-resource capability,\nadmits the manifest with those handlers, and registers the connector.\n\nThe adapter provides two fail-closed checks:\n1. ActionHandler::handle without trusted context returns an authorization\n   error.\n2. A handler bound to one capability rejects an action for a different\n   capability.\n\nDo not register the connector itself as the production ActionHandler after\ncutover. A connector may temporarily retain older trait implementations for\ntests or known compatibility callers, but those paths should not receive new\nproduction traffic.\n\nFor a standalone connector host, the common host constructs the same\nper-capability frozen handlers from the discovered manifest. The host also\nverifies the configured gateway and pinned route before creating trusted\nexecution context.\n\nTest the migration\n\nRun the old and new paths against the same controlled provider behavior before\nswitching registration. Compare:\n• canonical manifest and schema digests;\n• successful outputs and terminal statuses;\n• provider requests and idempotency keys;\n• errors, retry delays, and unknown-outcome flags;\n• cancellation and streaming behavior;\n• approval and transaction state transitions;\n• webhook acceptance, replay rejection, and durable event publication;\n• redacted logs, traces, receipts, and retained evidence.\n\nAdd focused negative tests for:\n• context-free handler invocation;\n• a capability sent to the wrong frozen handler;\n• contract and support-map disagreement;\n• expired deadline and cooperative cancellation;\n• missing approval or credential context;\n• duplicate idempotency keys with changed input;\n• commit interruption before and after a provider operation checkpoint;\n• restart with pending or uncertain work;\n• credential rotation while a route pins the previous revision.\n\nImplement a ConnectorConformanceDriver and run every scenario implied by the\nmanifest and support map. Record an unsupported feature as not applicable, not\npassed. Retain the exact source revision, artifact identity, topology, procedure,\ntime, and result for any conformance or qualification claim.\n\nCut over one bounded route\n\nUse a reversible rollout:\n1. freeze the approved baseline manifest and evidence;\n2. deploy the migrated artifact without changing capability bindings;\n3. select one non-production tenant or local registration path;\n4. switch that path from the legacy handler to the frozen adapter;\n5. verify discovery before allowing an action;\n6. run a non-destructive or explicitly approved action;\n7. exercise one failure and one restart path;\n8. compare provider requests, runtime state, and retained evidence;\n9. expand only after the migration result is accepted.\n\nDo not send the same mutation through old and new handlers as a comparison.\nUse provider fixtures, read-only operations, or distinct idempotency and account\nboundaries.\n\nHand the connector to fleet packaging\n\nA connector that passes the frozen SDK migration is ready for a separate\ndeployment conversion, not yet for fleet traffic. The next work item is to:\n• compose a standalone host around the connector;\n• build and identify an immutable host artifact;\n• generate the manifest and implementation support from that artifact;\n• collect the seven admission evidence families;\n• create connector type, version, instance, replica, policy, and tenant binding\n  records;\n• verify and apply a signed admission package;\n• qualify the exact artifact through an admitted route.\n\nFollow the connector-building procedure linked earlier for that complete\nboundary. Keep bundled-to-fleet deployment changes outside the SDK migration\ndiff so execution regressions and topology regressions remain distinguishable.\n\nVerify the upgraded connector\n\nThe SDK migration is complete only when:\n• published capability behavior is unchanged or every correction is separately\n  approved;\n• each callable capability has an accurate implementation support record;\n• production registration creates FrozenConnectorHandler instances;\n• context-free execution fails closed;\n• all authority and lifecycle decisions use trusted execution context;\n• failures preserve retry and uncertain-outcome semantics;\n• secret bytes cannot escape the connector-to-provider request boundary;\n• applicable conformance scenarios pass for the exact migrated artifact;\n• the old production handler path receives no new traffic;\n• a rollback artifact and state-preservation procedure are available.\n\nSource presence establishes implementation only. Report conformance,\nqualification, live verification, and production readiness as separate evidence\nclasses.\n\nDecide migration failures\n\n| Failure | Decision |\n\n| Manifest digest changes unexpectedly | Stop and identify the changed field before routing |\n| A contract claim lacks support | Implement it or narrow the contract in a separate reviewed change |\n| Frozen handler returns authorization for normal traffic | Fix gateway registration or trusted-context construction; do not bypass the adapter |\n| Legacy and frozen outputs differ | Compare provider request, context, and error mapping before expanding |\n| Cancellation creates an uncertain mutation | Preserve state and reconcile instead of retrying |\n| A compatibility caller still needs the old trait | Keep the trait behind an explicit boundary while production stays frozen |\n| Conformance scenario is absent | Add the scenario or mark a source-backed non-applicable reason |\n| Live-provider behavior changed | Stop rollout and re-baseline the provider revision |\n\nRoll back without restoring a bypass\n\nDrain the migrated route and stop new assignments before restoring the\npreviously accepted artifact or local registration. Preserve runtime state,\nidempotency records, provider operation references, callbacks, evidence, and\nlogs needed to finish or reconcile in-flight work.\n\nRestore the old path only in the environment where its documented trust\nlimitations were already accepted. Do not route high-risk traffic through a\ncontext-free handler as an emergency shortcut. Correct the migration under a\nnew immutable artifact identity, repeat the regression and conformance work,\nand cut over through the same bounded route.\n\nRelated documentation\n• Capabilities (../concepts/capabilities.md)\n• Actions and sessions (../concepts/actions-and-sessions.md)\n• Identity and trust (../concepts/identity-and-trust.md)\n• Profiles and connectors (../concepts/profiles-and-connectors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "6eb378be91d866c0ccc4fb5b761ef1e4312c1bff326856aa54f79194a809cb11"
  }
}