{
  "schemaVersion": "1.0",
  "title": "Connector contract",
  "description": "Use this reference to implement or review a product connector without recreating AIP governance at the provider edge. It identifies the callable surface, the trusted context a connector receives, the behavior it may advertise, and the evide",
  "canonical": "https://getaip.org/docs/spec/connector-contract",
  "route": "/docs/spec/connector-contract",
  "source": "docs/spec/connector-contract.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Protocol Standard",
  "documentType": "Specification reference",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "97be86e9efedf07ecf1783b03800f683f107fb04",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/spec/connector-contract.md",
    "txt": "/docs/download/spec/connector-contract.txt",
    "json": "/docs/download/spec/connector-contract.json",
    "pdf": "/docs/download/spec/connector-contract.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Connector contract\ndescription: Implement a product connector against AIP capability, execution-context, lifecycle, failure, and evidence boundaries\nkind: reference\naudience: connector-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Connector contract\n\nUse this reference to implement or review a product connector without\nrecreating AIP governance at the provider edge. It identifies the callable\nsurface, the trusted context a connector receives, the behavior it may\nadvertise, and the evidence it must retain when a provider outcome is\nuncertain.\n\nThis is a supporting implementation reference for source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`. Native action, capability,\ntransaction, error, and envelope semantics remain normative in\n[AIP 1.0](AIP-1.0.md). Provider-specific operations belong in the applicable\nconnector reference.\n\n## Contract boundary\n\nA connector maps one product edge into the admitted AIP capability contract.\nIt does not become a second gateway, policy engine, or action store.\n\n| Connector owns | AIP runtime owns |\n|---|---|\n| Provider request and response DTOs | Native action and session lifecycle |\n| Provider authentication at the downstream edge | Transport-authenticated actor and tenant |\n| Capability-to-provider operation mapping | Capability admission and input validation |\n| Provider error normalization | Authorization, approval, and retry policy |\n| Provider operation references and reconciliation | Idempotency reservation and transaction state |\n| Verified provider events and channel replies | Durable events, results, receipts, and callbacks |\n| Product-specific readiness detail | Fleet routing and client-facing readiness |\n\nThe connector consumes trusted runtime context. It does not accept a tenant,\nprincipal, credential, approval, route, retry grant, or transaction state from\nordinary action input or untrusted metadata.\n\n## Select the correct surface\n\nThe base `Connector` interface has four responsibilities:\n\n| Method | Contract |\n|---|---|\n| `id` | Return one stable connector identifier |\n| `discover` | Return the connector manifest for the supplied connector context |\n| `map_error` | Convert a connector error to a typed AIP protocol error |\n| `health` | Report whether the connector can currently discover and serve traffic |\n\nThe default health check treats successful discovery as ready. A connector\nwith stronger dependencies should override it and return operator-safe detail.\nReadiness does not prove a provider operation, webhook, or credential has been\nqualified.\n\nFive role-specific interfaces cover focused capability, event, channel,\noutbound, and escalation surfaces:\n\n| Interface | Additional responsibility |\n|---|---|\n| `CapabilityProviderConnector` | Return executable capabilities independently of transport ingress |\n| `InboundConnector` | Map one external event payload to native envelopes |\n| `ChannelConnector` | Ingest channel events and emit results to a conversation surface |\n| `OutboundConnector` | Invoke an external system, observe cancellation, request remote cancellation, and emit a result |\n| `EscalationConnector` | Map a governed human escalation to a product workflow |\n\nCallable production capabilities use `FrozenConnector`. That boundary\nreceives a complete trusted execution context and makes every optional\nlifecycle operation explicit. A connector may also implement an event or\nchannel interface, but those roles do not make its callable claims true.\n\n## Declare implementation support\n\nFor every admitted capability, `implementation_support` returns nine\nindependent flags:\n\n| Flag | True means |\n|---|---|\n| `invocation` | Normal invocation is implemented |\n| `cancellation` | Runtime cancellation reaches a downstream operation |\n| `streaming` | Incremental output is implemented |\n| `retry` | Retry classification and downstream idempotency are implemented |\n| `transaction` | Transaction planning and commit behavior are implemented |\n| `reconciliation` | An uncertain provider outcome can be reconciled |\n| `compensation` | Compensation is implemented as a governed action |\n| `approval` | Verified approval evidence and resume behavior are implemented |\n| `credentials` | Credential handles resolve through the deployment provider |\n\nManifest admission compares these flags with the capability contract:\n\n| Advertised contract behavior | Required implementation flag |\n|---|---|\n| Any callable capability | `invocation` |\n| `execution.supports_cancel` | `cancellation` |\n| `execution.supports_streaming` | `streaming` |\n| `execution.supports_retry` | `retry` |\n| A transaction contract | `transaction` |\n| Transaction mode `reconcile` | `reconciliation` |\n| Supported compensation | `compensation` |\n| Required approval | `approval` |\n| Required credentials | `credentials` |\n\nA missing required claim produces an admission issue. A true flag is still an\nimplementation declaration, not conformance or provider qualification.\nResources are not required to declare callable invocation.\n\n## Consume trusted execution context\n\n`ActionExecutionContext` is deliberately non-serializable. The runtime\nconstructs it from authenticated and durable state for each attempt.\n\n| Field | Connector-visible authority or facility |\n|---|---|\n| `actor` | Transport-authenticated principal, issuer, scheme, scopes, and lifetime |\n| `tenant` | Verified tenant membership when the action is tenant-scoped |\n| `credential` | Opaque credential handle, not secret bytes |\n| `deadline` | Absolute execution deadline and remaining-time calculation |\n| `cancellation` | Cooperative cancellation signal |\n| `idempotency` | Reservation owned by this attempt when applicable |\n| `approval` | Verified approval IDs, decision IDs, policy hashes, and authorization |\n| `transaction` | Transaction ID, provider operation ID, and reconciliation cursor |\n| `transaction_checkpoint` | Durable provider-operation checkpoint publisher |\n| `execution_checkpoints` | Provider-effect durability checkpoint publisher |\n| `stream` | Runtime-owned incremental chunk publisher |\n| `trace` | Trusted trace and span identifiers |\n| `redaction` | Input, output, and JSON-pointer redaction policy |\n\nThe context is attempt-scoped. Do not serialize it, place it in a provider\npayload, retain it as a credential cache, or reconstruct it from fields the\ncaller controls. A remote connector host derives the equivalent context only\nafter verifying the signed, route-pinned central request.\n\n## Implement typed operations\n\n`FrozenConnector` requires an implementation-support declaration and\n`invoke_typed`. Seven other operations default to\n`connector.operation_unsupported`, category `permanent`, with\n`retryable=false`.\n\n| Method | Purpose |\n|---|---|\n| `invoke_typed` | Execute a normal capability action |\n| `plan_typed` | Plan or dry-run a governed mutation |\n| `commit_typed` | Commit a prepared mutation |\n| `compensate_typed` | Execute a separately governed compensation |\n| `cancel_typed` | Request cancellation of a submitted downstream operation |\n| `reconcile_typed` | Determine the terminal outcome of an uncertain provider operation |\n| `emit_typed` | Emit a terminal result or provider event |\n| `ingest_typed` | Map one provider event under trusted context |\n\nFailures identify one of twelve serialized `ConnectorOperation` values:\n\n| Group | Operation values |\n|---|---|\n| Discovery and readiness | `discovery`, `admission`, `health` |\n| Provider execution | `invocation`, `cancellation`, `streaming` |\n| Transaction recovery | `transaction_plan`, `transaction_commit`, `reconciliation`, `compensation` |\n| Provider data exchange | `emission`, `ingestion` |\n\nThe runtime adapter rejects an action whose capability ID differs from the\ncapability bound to the handler. It selects the method from transaction mode:\n\n| Action transaction mode | Selected connector method |\n|---|---|\n| None, `execute`, or `rollback_not_supported` | `invoke_typed` |\n| `dry_run` or `plan` | `plan_typed` |\n| `commit` | `commit_typed` |\n| `compensate` | `compensate_typed` |\n| `reconcile` | `reconcile_typed` |\n\nReconciliation requires transaction context and a durable provider operation\nID. A nonterminal reconciliation result becomes\n`transaction.reconciliation_pending`, category `temporary`, retryable\nafter 5,000 ms, with its cursor and redacted evidence retained. A terminal\nresult records whether the original commit completed.\n\nCancellation is separate from transaction dispatch. The runtime signals the\ncooperative token and can call `cancel_typed` with the same trusted context.\nDropping a local future does not prove that a remote provider stopped work.\n\n## Resolve credentials at the provider edge\n\nThe execution context carries only an opaque `CredentialHandle`. The\nconnector's deployment credential provider resolves that handle inside the\nconnector process and for the verified tenant and account.\n\n`ConnectorSecret` is the in-memory wrapper available to connector\nimplementations. It is intentionally non-serializable, renders as\n`[REDACTED]` in diagnostics, compares equal-length material in constant time,\nand zeroizes its bytes on drop. Secret bytes or UTF-8 text should be exposed\nonly while constructing the downstream request.\n\nDo not copy credential material into:\n\n- manifests or capability schemas;\n- action input, metadata, or trace fields;\n- protocol errors or redacted details;\n- audit events, receipts, metrics, or logs;\n- provider operation references or reconciliation cursors.\n\nEmpty or unresolvable credential material is a typed connector failure. It is\nnot a reason to fall back to caller-supplied credentials.\n\n## Stream, cancel, and honor deadlines\n\nFor a streaming capability, publish each `StreamChunk` through\n`context.stream.emit`. The runtime-owned publisher persists and exposes the\nchunk through the action lifecycle. A connector should not call the\nclient-supplied callback directly or maintain a second authoritative stream\ncursor.\n\nCheck `context.cancellation` before a downstream side effect, while waiting\nbetween provider events, and before expensive follow-up work. If the provider\nsupports cancellation, `cancel_typed` should use the retained provider\noperation reference. Otherwise advertise `cancellation=false` and let the\nunsupported result remain explicit.\n\nUse `context.deadline` to bound downstream requests. The runtime also applies\nthe effective action timeout. On timeout it signals cancellation, attempts\nconnector-specific cancellation, and returns `sla.timeout_exceeded`.\nTimeout retryability is true only when the admitted capability supports retry\nand the action is not a commit or execute transaction.\n\n## Mark durability boundaries\n\nTwo checkpoint publishers solve different recovery problems:\n\n| Publisher | Call it when | Meaning |\n|---|---|---|\n| `transaction_checkpoint.checkpoint` | A provider operation ID exists, before awaiting a commit response that may be lost | The runtime can reconcile the exact provider operation |\n| `execution_checkpoints.provider_effect_committed` | The provider system of record has durably accepted an idempotent effect, before returning its response | A bounded observer can distinguish a pre-effect crash from a post-effect crash |\n\nThe transaction checkpoint accepts a `ProviderOperationRef` and optional\nopaque reconciliation cursor. It is unavailable outside a transactional\naction. The provider-effect checkpoint is a process-local notification; any\nretention is the installed observer's responsibility. It carries no provider\npayload or credentials.\n\nThese calls do not settle the native action. The connector must still return a\ntyped result or failure, and the runtime persists terminal lifecycle and\nidempotency state.\n\n## Return typed results and failures\n\nA successful operation returns an `ActionResult` for the supplied action.\nOutput and message parts must match the admitted capability contract and\nredaction policy. Streaming output does not replace the terminal result.\n\n`ConnectorFailure` preserves twelve fields:\n\n| Field | Contract |\n|---|---|\n| `code` | Stable namespaced failure code |\n| `message` | Human-readable redacted summary |\n| `category` | AIP error category |\n| `retryable` | Whether retry is safe under the capability's idempotency contract |\n| `retry_after_ms` | Optional provider-suggested delay |\n| `provider_request_id` | Optional provider request or trace ID |\n| `provider_operation` | Optional durable operation reference |\n| `remote_status` | Optional provider protocol status, normally HTTP |\n| `uncertain_outcome` | Whether an external effect may have occurred |\n| `redacted_details` | Structured details safe for durable audit storage |\n| `source` | Connector or provider component that produced the failure |\n| `operation` | One of the twelve typed connector operations |\n\nConversion to `ProtocolError` retains retry, provider, remote-status,\nuncertain-outcome, redacted-detail, and source information. It does not make an\nunsafe retry safe.\n\nWhen `uncertain_outcome=true`, return every known provider request and\noperation reference, avoid inventing a terminal result, and use\n`reconcile_typed` when the capability declares reconciliation. A client or\nruntime should reuse the original action and idempotency identity. Starting a\nnew mutation can duplicate an external effect.\n\n## Preserve the contract across placement\n\nThe product contract is the same for local and remote placement:\n\n| Placement | Additional boundary |\n|---|---|\n| Trusted local module | Connector code, credentials, and resource use share the gateway process |\n| Remote connector host | A signed native request pins tenant, instance, replica, version, manifest, lease, credential revision, and capability before context construction |\n\nRemote placement adds route, peer, capacity, callback, and lease checks. It\ndoes not authorize the connector to trust action metadata or change capability\nsemantics. See the [connector fleet HTTP API](../reference/connector-fleet-api.md)\nfor that wire boundary.\n\n## Review an implementation\n\nBefore admitting a connector capability, confirm all of these points:\n\n- the manifest describes only implemented operations and schemas;\n- every callable capability has an exact nine-flag support record;\n- the connector uses only trusted actor, tenant, credential, approval,\n  transaction, and idempotency context;\n- secret material is resolved at the provider edge and excluded from durable\n  output;\n- retries use the original mutation identity and match the provider's\n  idempotency behavior;\n- streaming, cancellation, planning, commit, compensation, and reconciliation\n  are either implemented or explicitly unsupported;\n- provider operation IDs are checkpointed before an uncertain commit wait;\n- provider-visible durable effects publish the effect checkpoint at the\n  documented boundary;\n- failures preserve redacted recovery evidence and identify uncertain\n  outcomes;\n- local or remote placement retains the same capability and lifecycle meaning.\n\nThis review establishes contract alignment for the inspected implementation.\nConformance and live provider qualification require separate suites and\nretained evidence.\n\n## Related documentation\n\n- [Capabilities and contracts](../concepts/capabilities.md)\n- [Profiles, transports, and connectors](../concepts/profiles-and-connectors.md)\n- [Build a connector](../guides/build-a-connector.md)\n- [Conformance and qualification](../reference/conformance.md)\n",
    "text": "Connector contract\n\nUse this reference to implement or review a product connector without\nrecreating AIP governance at the provider edge. It identifies the callable\nsurface, the trusted context a connector receives, the behavior it may\nadvertise, and the evidence it must retain when a provider outcome is\nuncertain.\n\nThis is a supporting implementation reference for source revision\n97be86e9efedf07ecf1783b03800f683f107fb04. Native action, capability,\ntransaction, error, and envelope semantics remain normative in\nAIP 1.0 (AIP-1.0.md). Provider-specific operations belong in the applicable\nconnector reference.\n\nContract boundary\n\nA connector maps one product edge into the admitted AIP capability contract.\nIt does not become a second gateway, policy engine, or action store.\n\n| Connector owns | AIP runtime owns |\n\n| Provider request and response DTOs | Native action and session lifecycle |\n| Provider authentication at the downstream edge | Transport-authenticated actor and tenant |\n| Capability-to-provider operation mapping | Capability admission and input validation |\n| Provider error normalization | Authorization, approval, and retry policy |\n| Provider operation references and reconciliation | Idempotency reservation and transaction state |\n| Verified provider events and channel replies | Durable events, results, receipts, and callbacks |\n| Product-specific readiness detail | Fleet routing and client-facing readiness |\n\nThe connector consumes trusted runtime context. It does not accept a tenant,\nprincipal, credential, approval, route, retry grant, or transaction state from\nordinary action input or untrusted metadata.\n\nSelect the correct surface\n\nThe base Connector interface has four responsibilities:\n\n| Method | Contract |\n\n| id | Return one stable connector identifier |\n| discover | Return the connector manifest for the supplied connector context |\n| maperror | Convert a connector error to a typed AIP protocol error |\n| health | Report whether the connector can currently discover and serve traffic |\n\nThe default health check treats successful discovery as ready. A connector\nwith stronger dependencies should override it and return operator-safe detail.\nReadiness does not prove a provider operation, webhook, or credential has been\nqualified.\n\nFive role-specific interfaces cover focused capability, event, channel,\noutbound, and escalation surfaces:\n\n| Interface | Additional responsibility |\n\n| CapabilityProviderConnector | Return executable capabilities independently of transport ingress |\n| InboundConnector | Map one external event payload to native envelopes |\n| ChannelConnector | Ingest channel events and emit results to a conversation surface |\n| OutboundConnector | Invoke an external system, observe cancellation, request remote cancellation, and emit a result |\n| EscalationConnector | Map a governed human escalation to a product workflow |\n\nCallable production capabilities use FrozenConnector. That boundary\nreceives a complete trusted execution context and makes every optional\nlifecycle operation explicit. A connector may also implement an event or\nchannel interface, but those roles do not make its callable claims true.\n\nDeclare implementation support\n\nFor every admitted capability, implementationsupport returns nine\nindependent flags:\n\n| Flag | True means |\n\n| invocation | Normal invocation is implemented |\n| cancellation | Runtime cancellation reaches a downstream operation |\n| streaming | Incremental output is implemented |\n| retry | Retry classification and downstream idempotency are implemented |\n| transaction | Transaction planning and commit behavior are implemented |\n| reconciliation | An uncertain provider outcome can be reconciled |\n| compensation | Compensation is implemented as a governed action |\n| approval | Verified approval evidence and resume behavior are implemented |\n| credentials | Credential handles resolve through the deployment provider |\n\nManifest admission compares these flags with the capability contract:\n\n| Advertised contract behavior | Required implementation flag |\n\n| Any callable capability | invocation |\n| execution.supportscancel | cancellation |\n| execution.supportsstreaming | streaming |\n| execution.supportsretry | retry |\n| A transaction contract | transaction |\n| Transaction mode reconcile | reconciliation |\n| Supported compensation | compensation |\n| Required approval | approval |\n| Required credentials | credentials |\n\nA missing required claim produces an admission issue. A true flag is still an\nimplementation declaration, not conformance or provider qualification.\nResources are not required to declare callable invocation.\n\nConsume trusted execution context\n\nActionExecutionContext is deliberately non-serializable. The runtime\nconstructs it from authenticated and durable state for each attempt.\n\n| Field | Connector-visible authority or facility |\n\n| actor | Transport-authenticated principal, issuer, scheme, scopes, and lifetime |\n| tenant | Verified tenant membership when the action is tenant-scoped |\n| credential | Opaque credential handle, not secret bytes |\n| deadline | Absolute execution deadline and remaining-time calculation |\n| cancellation | Cooperative cancellation signal |\n| idempotency | Reservation owned by this attempt when applicable |\n| approval | Verified approval IDs, decision IDs, policy hashes, and authorization |\n| transaction | Transaction ID, provider operation ID, and reconciliation cursor |\n| transactioncheckpoint | Durable provider-operation checkpoint publisher |\n| executioncheckpoints | Provider-effect durability checkpoint publisher |\n| stream | Runtime-owned incremental chunk publisher |\n| trace | Trusted trace and span identifiers |\n| redaction | Input, output, and JSON-pointer redaction policy |\n\nThe context is attempt-scoped. Do not serialize it, place it in a provider\npayload, retain it as a credential cache, or reconstruct it from fields the\ncaller controls. A remote connector host derives the equivalent context only\nafter verifying the signed, route-pinned central request.\n\nImplement typed operations\n\nFrozenConnector requires an implementation-support declaration and\ninvoketyped. Seven other operations default to\nconnector.operationunsupported, category permanent, with\nretryable=false.\n\n| Method | Purpose |\n\n| invoketyped | Execute a normal capability action |\n| plantyped | Plan or dry-run a governed mutation |\n| committyped | Commit a prepared mutation |\n| compensatetyped | Execute a separately governed compensation |\n| canceltyped | Request cancellation of a submitted downstream operation |\n| reconciletyped | Determine the terminal outcome of an uncertain provider operation |\n| emittyped | Emit a terminal result or provider event |\n| ingesttyped | Map one provider event under trusted context |\n\nFailures identify one of twelve serialized ConnectorOperation values:\n\n| Group | Operation values |\n\n| Discovery and readiness | discovery, admission, health |\n| Provider execution | invocation, cancellation, streaming |\n| Transaction recovery | transactionplan, transactioncommit, reconciliation, compensation |\n| Provider data exchange | emission, ingestion |\n\nThe runtime adapter rejects an action whose capability ID differs from the\ncapability bound to the handler. It selects the method from transaction mode:\n\n| Action transaction mode | Selected connector method |\n\n| None, execute, or rollbacknotsupported | invoketyped |\n| dryrun or plan | plantyped |\n| commit | committyped |\n| compensate | compensatetyped |\n| reconcile | reconciletyped |\n\nReconciliation requires transaction context and a durable provider operation\nID. A nonterminal reconciliation result becomes\ntransaction.reconciliationpending, category temporary, retryable\nafter 5,000 ms, with its cursor and redacted evidence retained. A terminal\nresult records whether the original commit completed.\n\nCancellation is separate from transaction dispatch. The runtime signals the\ncooperative token and can call canceltyped with the same trusted context.\nDropping a local future does not prove that a remote provider stopped work.\n\nResolve credentials at the provider edge\n\nThe execution context carries only an opaque CredentialHandle. The\nconnector's deployment credential provider resolves that handle inside the\nconnector process and for the verified tenant and account.\n\nConnectorSecret is the in-memory wrapper available to connector\nimplementations. It is intentionally non-serializable, renders as\n[REDACTED] in diagnostics, compares equal-length material in constant time,\nand zeroizes its bytes on drop. Secret bytes or UTF-8 text should be exposed\nonly while constructing the downstream request.\n\nDo not copy credential material into:\n• manifests or capability schemas;\n• action input, metadata, or trace fields;\n• protocol errors or redacted details;\n• audit events, receipts, metrics, or logs;\n• provider operation references or reconciliation cursors.\n\nEmpty or unresolvable credential material is a typed connector failure. It is\nnot a reason to fall back to caller-supplied credentials.\n\nStream, cancel, and honor deadlines\n\nFor a streaming capability, publish each StreamChunk through\ncontext.stream.emit. The runtime-owned publisher persists and exposes the\nchunk through the action lifecycle. A connector should not call the\nclient-supplied callback directly or maintain a second authoritative stream\ncursor.\n\nCheck context.cancellation before a downstream side effect, while waiting\nbetween provider events, and before expensive follow-up work. If the provider\nsupports cancellation, canceltyped should use the retained provider\noperation reference. Otherwise advertise cancellation=false and let the\nunsupported result remain explicit.\n\nUse context.deadline to bound downstream requests. The runtime also applies\nthe effective action timeout. On timeout it signals cancellation, attempts\nconnector-specific cancellation, and returns sla.timeoutexceeded.\nTimeout retryability is true only when the admitted capability supports retry\nand the action is not a commit or execute transaction.\n\nMark durability boundaries\n\nTwo checkpoint publishers solve different recovery problems:\n\n| Publisher | Call it when | Meaning |\n\n| transactioncheckpoint.checkpoint | A provider operation ID exists, before awaiting a commit response that may be lost | The runtime can reconcile the exact provider operation |\n| executioncheckpoints.providereffectcommitted | The provider system of record has durably accepted an idempotent effect, before returning its response | A bounded observer can distinguish a pre-effect crash from a post-effect crash |\n\nThe transaction checkpoint accepts a ProviderOperationRef and optional\nopaque reconciliation cursor. It is unavailable outside a transactional\naction. The provider-effect checkpoint is a process-local notification; any\nretention is the installed observer's responsibility. It carries no provider\npayload or credentials.\n\nThese calls do not settle the native action. The connector must still return a\ntyped result or failure, and the runtime persists terminal lifecycle and\nidempotency state.\n\nReturn typed results and failures\n\nA successful operation returns an ActionResult for the supplied action.\nOutput and message parts must match the admitted capability contract and\nredaction policy. Streaming output does not replace the terminal result.\n\nConnectorFailure preserves twelve fields:\n\n| Field | Contract |\n\n| code | Stable namespaced failure code |\n| message | Human-readable redacted summary |\n| category | AIP error category |\n| retryable | Whether retry is safe under the capability's idempotency contract |\n| retryafterms | Optional provider-suggested delay |\n| providerrequestid | Optional provider request or trace ID |\n| provideroperation | Optional durable operation reference |\n| remotestatus | Optional provider protocol status, normally HTTP |\n| uncertainoutcome | Whether an external effect may have occurred |\n| redacteddetails | Structured details safe for durable audit storage |\n| source | Connector or provider component that produced the failure |\n| operation | One of the twelve typed connector operations |\n\nConversion to ProtocolError retains retry, provider, remote-status,\nuncertain-outcome, redacted-detail, and source information. It does not make an\nunsafe retry safe.\n\nWhen uncertainoutcome=true, return every known provider request and\noperation reference, avoid inventing a terminal result, and use\nreconciletyped when the capability declares reconciliation. A client or\nruntime should reuse the original action and idempotency identity. Starting a\nnew mutation can duplicate an external effect.\n\nPreserve the contract across placement\n\nThe product contract is the same for local and remote placement:\n\n| Placement | Additional boundary |\n\n| Trusted local module | Connector code, credentials, and resource use share the gateway process |\n| Remote connector host | A signed native request pins tenant, instance, replica, version, manifest, lease, credential revision, and capability before context construction |\n\nRemote placement adds route, peer, capacity, callback, and lease checks. It\ndoes not authorize the connector to trust action metadata or change capability\nsemantics. See the connector fleet HTTP API (../reference/connector-fleet-api.md)\nfor that wire boundary.\n\nReview an implementation\n\nBefore admitting a connector capability, confirm all of these points:\n• the manifest describes only implemented operations and schemas;\n• every callable capability has an exact nine-flag support record;\n• the connector uses only trusted actor, tenant, credential, approval,\n  transaction, and idempotency context;\n• secret material is resolved at the provider edge and excluded from durable\n  output;\n• retries use the original mutation identity and match the provider's\n  idempotency behavior;\n• streaming, cancellation, planning, commit, compensation, and reconciliation\n  are either implemented or explicitly unsupported;\n• provider operation IDs are checkpointed before an uncertain commit wait;\n• provider-visible durable effects publish the effect checkpoint at the\n  documented boundary;\n• failures preserve redacted recovery evidence and identify uncertain\n  outcomes;\n• local or remote placement retains the same capability and lifecycle meaning.\n\nThis review establishes contract alignment for the inspected implementation.\nConformance and live provider qualification require separate suites and\nretained evidence.\n\nRelated documentation\n• Capabilities and contracts (../concepts/capabilities.md)\n• Profiles, transports, and connectors (../concepts/profiles-and-connectors.md)\n• Build a connector (../guides/build-a-connector.md)\n• Conformance and qualification (../reference/conformance.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "e88a3acdba0e58461bae0a48aa2eb0bd4f3323d5d673e75ff760ec9df7379ee7"
  }
}