{
  "schemaVersion": "1.0",
  "title": "Connector registry and routing",
  "description": "Use this page to understand how the reviewed AIP connector registry turns an authenticated tenant and capability into one durable execution target. It explains which records participate, how discovery remains revision-consistent, how a new ",
  "canonical": "https://getaip.org/docs/architecture/connector-registry-and-routing",
  "route": "/docs/architecture/connector-registry-and-routing",
  "source": "docs/architecture/connector-registry-and-routing.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Architecture and Security",
  "documentType": "Architecture",
  "language": "en",
  "downloads": {
    "md": "/docs/download/architecture/connector-registry-and-routing.md",
    "txt": "/docs/download/architecture/connector-registry-and-routing.txt",
    "json": "/docs/download/architecture/connector-registry-and-routing.json",
    "pdf": "/docs/download/architecture/connector-registry-and-routing.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Connector registry and routing\ndescription: Understand revision-consistent discovery, deterministic target selection, and durable action routing\nkind: explanation\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Connector registry and routing\n\nUse this page to understand how the reviewed AIP connector registry turns an\nauthenticated tenant and capability into one durable execution target. It\nexplains which records participate, how discovery remains revision-consistent,\nhow a new route is selected, and why retry and cancellation cannot silently\nchange the assigned product account or connector host.\n\nThe model describes version `1.0.0` of the Rust workspace at source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`. These registry and PostgreSQL\nchoices are implementation architecture, not storage requirements imposed by\nAIP 1.0.\n\n## Why routing needs durable registry state\n\nAn action target is more than a URL. It combines a verified tenant, a callable\ncapability, a tenant-owned product account, an admitted connector artifact, a\nlive host identity, policy state, credential revision, and reserved capacity.\nRecomputing that combination after a timeout could select a different account\nor process after the first provider already committed a side effect.\n\nThe registry therefore performs two different jobs:\n\n- it publishes a revisioned, tenant-scoped capability catalog; and\n- it atomically creates or returns one persistent route for each action.\n\nThe route is evidence as well as dispatch state. It records which destination\nand policy snapshot governed the first attempt, then remains available after\ncapacity is released.\n\n## Separate the contract from the durable backend\n\nThe product-neutral registry crate defines five narrow contracts:\n\n| Contract | Consumer | Responsibility |\n|---|---|---|\n| Capability catalog | Runtime, discovery, and compatibility profiles | Resolve one definition or return a bounded tenant-scoped page |\n| Action target resolver | Shared remote handler | Create, read, and settle one durable route assignment |\n| Registry reader | Host admission plus callback and event ingress | Read version, instance, and replica identities |\n| Registry administrator | Admission, lifecycle, and operator components | Change catalog state or replica leases through backend-enforced roles |\n| Fleet status provider | Daemon supervision and observation | Expire bounded stale leases and return fixed-size aggregate state |\n\nThe same crate includes a deterministic in-memory implementation for embedded\ndeployments and conformance work. The fleet backend uses normalized PostgreSQL\ntables and indexed columns. It does not materialize the fleet as one JSON\ndocument and does not store provider credential values.\n\nThe PostgreSQL implementation can hold two independently permissioned pools:\n\n- the **control pool** installs schema and changes catalog or admission state;\n- the **data pool** serves catalog reads, route resolution, reservations,\n  replica lifecycle updates, and aggregate status.\n\nA data-plane-only process verifies that an external control plane installed the\nexpected schema, then retains no control pool. Pool names describe authority,\nnot separate databases: both can connect to the same database through different\nroles and bounds.\n\n## Read the normalized entity graph\n\n~~~mermaid\nflowchart LR\n    T[\"Connector type\"] --> V[\"Immutable connector version\"]\n    V --> C[\"Capability definitions\"]\n    V --> I[\"Tenant-owned instance\"]\n    C --> B[\"Capability binding\"]\n    I --> B\n    I --> R[\"Live replica lease\"]\n    P[\"Admission policy\"] --> B\n    B --> A[\"Durable action assignment\"]\n    R --> A\n~~~\n\nThe text equivalent is:\n\n1. A connector type identifies an implementation family and owner.\n2. An admitted version binds that type to one immutable artifact, manifest,\n   capability set, supported profiles, and supply-chain attestation.\n3. A connector instance selects a version for one tenant-owned installation\n   and points to non-secret configuration and secret-provider revisions.\n4. A capability binding makes one tenant and capability eligible to use one\n   instance under a priority, policy revision, credential revision, and optional\n   quota policy. Gateway authorization still applies to each action.\n5. A replica is one pre-provisioned host identity for the instance and version,\n   with endpoint, signed peer identity, topology, health sequence, lease, and\n   capacity.\n6. A route assignment joins the binding and replica to one action and retains\n   the decision after execution capacity is released.\n\n### Know what may change\n\n| Record | Fixed identity or content | Controlled mutable state |\n|---|---|---|\n| Connector type | ID, name, and owner | Enabled flag |\n| Connector version | ID, type, artifact, manifest, attestation, capability contracts, and profiles | Lifecycle status can move through admitted, active, or revoked; revoked cannot reactivate |\n| Capability definition | Capability ID, complete contract digest, and schema digest | A conflicting contract under the same ID is rejected |\n| Connector instance | ID, connector type, and tenant | Version, status, secret reference, and configuration only through a newer configuration revision |\n| Capability binding | Tenant, capability, and instance key | Priority, enabled state, credential and quota references only through a newer policy revision |\n| Connector replica | ID, instance, version, endpoint, peer identity, trust domain, transport, and topology identity | Status, lease, capacity, and health only through a newer health revision; active assignments remain registry-owned |\n| Route assignment | Complete action destination and policy snapshot | Reservation and settlement bookkeeping; the assignment record itself remains pinned |\n\nInstance and binding changes advance the catalog revision. Replica heartbeat,\nlease, and capacity churn do not. This keeps a catalog page stable without\nserializing every host heartbeat through the catalog publication lock.\n\n## Publish one catalog revision at a time\n\nCatalog administrators take an exclusive database-scoped publication lock,\nvalidate all referenced records, apply one transaction, increment the monotonic\ncatalog revision, and commit. A failed transaction does not publish a partial\nview.\n\nCatalog readers take the shared form of that lock while reading the revision\nand materializing a result. A tenant-scoped read returns a capability only when\nall of these conditions hold:\n\n- the tenant has an enabled binding for the capability;\n- the bound instance belongs to the same tenant and is enabled;\n- the selected version is active and supply-chain qualified;\n- the connector type is enabled; and\n- the version implements the capability and, when requested, the profile.\n\nInternal administrative reads can explicitly request active unbound\ndefinitions. An ordinary read with neither verified tenant context nor that\ninternal permission returns no capabilities.\n\n### Keep pagination tied to the revision\n\nCatalog pages are ordered by capability ID and bounded by both item count and\nserialized bytes. The page carries the revision used for the complete read. A\ncontinuation cursor combines that revision with the last capability ID.\n\nIf a later request presents the cursor after the catalog revision changes, the\nregistry returns `StaleCursor`. The caller restarts at the first page instead of\ncombining definitions from two publication snapshots. Search text, exact\ncapability, profile, tenant, page-size, definition-size, and total-page-size\nlimits are evaluated server-side.\n\n## Resolve a new action in one transaction\n\nThe route request contains only an action ID, capability ID, verified tenant\nID, and deployment-owned topology preference. It contains no instance, replica,\nendpoint, credential value, or peer key.\n\nThe PostgreSQL resolver follows this sequence:\n\n1. Validate that the tenant ID is present.\n2. Serialize concurrent decisions for the same action with an action-scoped\n   advisory lock.\n3. Return an existing assignment when its tenant and capability match. Reject\n   the request as a conflict when those coordinates differ.\n4. For a new action, take a revision-consistent catalog view and establish that\n   at least one enabled tenant binding exists.\n5. Select an eligible replica under a row lock, skipping rows currently locked\n   by other routing transactions and retrying contention only within a bounded\n   limit.\n6. Build and reserve the binding's hard admission scopes, increment the selected\n   replica's active assignment count, create a fresh fence token, and insert the\n   complete route.\n7. Commit the capacity reservation and assignment atomically, then return the\n   route to the remote dispatcher.\n\nNo provider side effect occurs inside this transaction. The remote handler\ndispatches only after the committed assignment is returned.\n\n### Filter before ordering\n\nA replica is eligible for a new assignment only when the complete chain is\nvalid:\n\n- the tenant binding and instance are enabled and belong to the same tenant;\n- the active, qualified version implements the requested capability and belongs\n  to an enabled connector type;\n- the replica serves that instance and version, reports `ready`, has an\n  unexpired lease, and has unused capacity;\n- its circuit is closed; and\n- it satisfies the required capacity class and the configured cross-region\n  constraint.\n\nThe eligible rows are ordered by:\n\n1. lower binding priority;\n2. a preferred-region match;\n3. a preferred-zone match;\n4. fewer active assignments;\n5. an action-dependent hash of the replica ID; and\n6. stable instance and replica ID tie-breakers.\n\nRegion and zone are preferences for a new route. Capacity class is a filter.\nCross-region selection is allowed by default, but a deployment can forbid it.\nNone of these preferences changes an existing route.\n\n## Treat the assignment as an immutable execution contract\n\nThe persisted `RouteAssignment` groups its fields by purpose:\n\n| Field group | Fields | Decision retained |\n|---|---|---|\n| Work identity | `action_id`, `capability_id`, `tenant_id` | Which verified work contract was routed |\n| Logical target | `instance_id`, `version_id`, `manifest_digest` | Which product account and admitted implementation own the action |\n| Concrete peer | `replica_id`, `endpoint`, `peer_principal_id`, `peer_principal_kind`, `peer_did`, `trust_domain`, `transport_profile`, `topology` | Which signed process and failure domain received it |\n| Catalog and policy | `catalog_revision`, `binding_policy_revision`, `credential_revision_ref`, `quota_policy_ref` | Which catalog, binding, credential, and quota decision applied |\n| Capacity and fencing | `replica_health_revision`, `fence_token`, `admission` | Which health observation and reserved policy scopes protect execution |\n| Evidence time | `assigned_at` | When the route was created |\n\nThe remote dispatcher carries the route coordinates needed by the host in\nsigned request metadata and authenticates the assigned peer. The complete\nassignment remains registry state; not every internal reservation field becomes\nan AIP message field.\n\n## Reuse the route for retry and cancellation\n\nResolving an already assigned action never runs new target selection. If its\nprevious reservation was released, the registry tries to reserve the pinned\nadmission scopes and the same replica again. That reacquisition accepts a\n`ready` or `draining` replica only while its lease, version, type, capacity, and\ncircuit state remain valid.\n\nIf the pinned replica is unavailable, resolution fails. It does not create a\nreplacement route. This prevents a retry from moving a possibly committed\nmutation to another provider account or host.\n\nCancellation reads the same assignment and sends the cancellation to its\nassigned replica. Reconciliation also uses the retained route to identify the\nprovider boundary whose outcome is uncertain.\n\n## Settle capacity without deleting evidence\n\nSettlement accepts the exact assignment and one of four outcomes:\n`completed`, `outcome_unknown`, `cancelled`, or `lease_expired`.\n\nThe registry locks the action, compares the complete stored assignment with the\ncaller-provided value, and rejects a mismatch as `FenceLost`. If the reservation\nis still active, one transaction:\n\n- releases every admission counter reserved for the attempt;\n- marks the route unreserved and records its last settlement;\n- decrements the replica's active assignment count; and\n- updates the replica circuit state.\n\nRepeated settlement after the reservation is already released is idempotent.\nThe assignment is retained.\n\nA completed outcome resets consecutive unknown failures. An\n`outcome_unknown` settlement increments the counter when circuit policy is\nenabled and opens the replica circuit after the configured threshold. A\ncancelled or lease-expired settlement releases capacity without pretending that\nthe provider succeeded.\n\nLease maintenance can mark a bounded number of expired replicas offline and\nrelease their fenced reservations. It does not contact connector endpoints and\ndoes not rewrite the destinations recorded in existing assignments.\n\n## Preserve authority and failure boundaries\n\n| Boundary | Safe behavior |\n|---|---|\n| No verified tenant context | Return no tenant catalog and refuse to derive routing authority from payload fields |\n| Missing binding | Return `BindingUnavailable`; do not search another tenant or unbound implementation |\n| No eligible host | Return `ReplicaUnavailable`; do not route to a draining or expired replica as new work |\n| Admission limit reached | Return `CapacityExceeded` with bounded retry guidance; do not overbook the counter |\n| Changed catalog during pagination | Return `StaleCursor`; restart the read from the first page |\n| Assignment mismatch or stale fence | Return conflict or `FenceLost`; do not settle another reservation |\n| Registry storage failure | Stop the state transition; do not infer that a route, reservation, or settlement committed |\n\nThe registry stores host endpoints and signed peer identities because routing\nneeds them. It stores opaque credential and secret-provider references because\nrotation and route evidence need revision identity. It never stores the\nprovider credential value and never lets transport data select a target.\n\n## Trade-offs and non-implications\n\n- **Revision locks favor coherent discovery.** A page observes one catalog\n  publication, while replica heartbeats remain independent of that lock.\n- **Per-action serialization favors stable identity.** Concurrent duplicate\n  requests converge on one assignment but coordinate through one action lock.\n- **Row locking favors bounded contention.** `SKIP LOCKED` avoids waiting on a\n  busy replica row, while bounded retries can still return no capacity during a\n  short contention window.\n- **Pinned assignments favor safe recovery.** They prevent silent failover but\n  can make an unavailable replica a reconciliation problem instead of an\n  immediate rerouting opportunity.\n- **Normalized records favor indexed selection.** They avoid loading the whole\n  fleet, at the cost of explicit schema, transaction, and migration ownership.\n\nThe registry does not execute connector code, start an artifact, resolve a\nprovider secret, authorize a client, or prove a provider outcome. The reviewed\nsource contains a scale qualification contract, but its thresholds and results\nare evidence for a particular environment rather than portable performance or\navailability promises.\n\n## Related pages\n\n- [Connector fleet architecture](connector-fleet.md)\n- [Connector admission and supply-chain trust](connector-admission.md)\n- [Connector fleet HTTP API](../reference/connector-fleet-api.md)\n- [Deploy the connector fleet](../guides/deploy-connector-fleet.md)\n- [Error reference](../reference/errors.md)\n",
    "text": "Connector registry and routing\n\nUse this page to understand how the reviewed AIP connector registry turns an\nauthenticated tenant and capability into one durable execution target. It\nexplains which records participate, how discovery remains revision-consistent,\nhow a new route is selected, and why retry and cancellation cannot silently\nchange the assigned product account or connector host.\n\nThe model describes version 1.0.0 of the Rust workspace at source revision\n97be86e9efedf07ecf1783b03800f683f107fb04. These registry and PostgreSQL\nchoices are implementation architecture, not storage requirements imposed by\nAIP 1.0.\n\nWhy routing needs durable registry state\n\nAn action target is more than a URL. It combines a verified tenant, a callable\ncapability, a tenant-owned product account, an admitted connector artifact, a\nlive host identity, policy state, credential revision, and reserved capacity.\nRecomputing that combination after a timeout could select a different account\nor process after the first provider already committed a side effect.\n\nThe registry therefore performs two different jobs:\n• it publishes a revisioned, tenant-scoped capability catalog; and\n• it atomically creates or returns one persistent route for each action.\n\nThe route is evidence as well as dispatch state. It records which destination\nand policy snapshot governed the first attempt, then remains available after\ncapacity is released.\n\nSeparate the contract from the durable backend\n\nThe product-neutral registry crate defines five narrow contracts:\n\n| Contract | Consumer | Responsibility |\n\n| Capability catalog | Runtime, discovery, and compatibility profiles | Resolve one definition or return a bounded tenant-scoped page |\n| Action target resolver | Shared remote handler | Create, read, and settle one durable route assignment |\n| Registry reader | Host admission plus callback and event ingress | Read version, instance, and replica identities |\n| Registry administrator | Admission, lifecycle, and operator components | Change catalog state or replica leases through backend-enforced roles |\n| Fleet status provider | Daemon supervision and observation | Expire bounded stale leases and return fixed-size aggregate state |\n\nThe same crate includes a deterministic in-memory implementation for embedded\ndeployments and conformance work. The fleet backend uses normalized PostgreSQL\ntables and indexed columns. It does not materialize the fleet as one JSON\ndocument and does not store provider credential values.\n\nThe PostgreSQL implementation can hold two independently permissioned pools:\n• the control pool installs schema and changes catalog or admission state;\n• the data pool serves catalog reads, route resolution, reservations,\n  replica lifecycle updates, and aggregate status.\n\nA data-plane-only process verifies that an external control plane installed the\nexpected schema, then retains no control pool. Pool names describe authority,\nnot separate databases: both can connect to the same database through different\nroles and bounds.\n\nRead the normalized entity graph\n\nmermaid\nflowchart LR\n    T[\"Connector type\"] --> V[\"Immutable connector version\"]\n    V --> C[\"Capability definitions\"]\n    V --> I[\"Tenant-owned instance\"]\n    C --> B[\"Capability binding\"]\n    I --> B\n    I --> R[\"Live replica lease\"]\n    P[\"Admission policy\"] --> B\n    B --> A[\"Durable action assignment\"]\n    R --> A\n\nThe text equivalent is:\n1. A connector type identifies an implementation family and owner.\n2. An admitted version binds that type to one immutable artifact, manifest,\n   capability set, supported profiles, and supply-chain attestation.\n3. A connector instance selects a version for one tenant-owned installation\n   and points to non-secret configuration and secret-provider revisions.\n4. A capability binding makes one tenant and capability eligible to use one\n   instance under a priority, policy revision, credential revision, and optional\n   quota policy. Gateway authorization still applies to each action.\n5. A replica is one pre-provisioned host identity for the instance and version,\n   with endpoint, signed peer identity, topology, health sequence, lease, and\n   capacity.\n6. A route assignment joins the binding and replica to one action and retains\n   the decision after execution capacity is released.\n\nKnow what may change\n\n| Record | Fixed identity or content | Controlled mutable state |\n\n| Connector type | ID, name, and owner | Enabled flag |\n| Connector version | ID, type, artifact, manifest, attestation, capability contracts, and profiles | Lifecycle status can move through admitted, active, or revoked; revoked cannot reactivate |\n| Capability definition | Capability ID, complete contract digest, and schema digest | A conflicting contract under the same ID is rejected |\n| Connector instance | ID, connector type, and tenant | Version, status, secret reference, and configuration only through a newer configuration revision |\n| Capability binding | Tenant, capability, and instance key | Priority, enabled state, credential and quota references only through a newer policy revision |\n| Connector replica | ID, instance, version, endpoint, peer identity, trust domain, transport, and topology identity | Status, lease, capacity, and health only through a newer health revision; active assignments remain registry-owned |\n| Route assignment | Complete action destination and policy snapshot | Reservation and settlement bookkeeping; the assignment record itself remains pinned |\n\nInstance and binding changes advance the catalog revision. Replica heartbeat,\nlease, and capacity churn do not. This keeps a catalog page stable without\nserializing every host heartbeat through the catalog publication lock.\n\nPublish one catalog revision at a time\n\nCatalog administrators take an exclusive database-scoped publication lock,\nvalidate all referenced records, apply one transaction, increment the monotonic\ncatalog revision, and commit. A failed transaction does not publish a partial\nview.\n\nCatalog readers take the shared form of that lock while reading the revision\nand materializing a result. A tenant-scoped read returns a capability only when\nall of these conditions hold:\n• the tenant has an enabled binding for the capability;\n• the bound instance belongs to the same tenant and is enabled;\n• the selected version is active and supply-chain qualified;\n• the connector type is enabled; and\n• the version implements the capability and, when requested, the profile.\n\nInternal administrative reads can explicitly request active unbound\ndefinitions. An ordinary read with neither verified tenant context nor that\ninternal permission returns no capabilities.\n\nKeep pagination tied to the revision\n\nCatalog pages are ordered by capability ID and bounded by both item count and\nserialized bytes. The page carries the revision used for the complete read. A\ncontinuation cursor combines that revision with the last capability ID.\n\nIf a later request presents the cursor after the catalog revision changes, the\nregistry returns StaleCursor. The caller restarts at the first page instead of\ncombining definitions from two publication snapshots. Search text, exact\ncapability, profile, tenant, page-size, definition-size, and total-page-size\nlimits are evaluated server-side.\n\nResolve a new action in one transaction\n\nThe route request contains only an action ID, capability ID, verified tenant\nID, and deployment-owned topology preference. It contains no instance, replica,\nendpoint, credential value, or peer key.\n\nThe PostgreSQL resolver follows this sequence:\n1. Validate that the tenant ID is present.\n2. Serialize concurrent decisions for the same action with an action-scoped\n   advisory lock.\n3. Return an existing assignment when its tenant and capability match. Reject\n   the request as a conflict when those coordinates differ.\n4. For a new action, take a revision-consistent catalog view and establish that\n   at least one enabled tenant binding exists.\n5. Select an eligible replica under a row lock, skipping rows currently locked\n   by other routing transactions and retrying contention only within a bounded\n   limit.\n6. Build and reserve the binding's hard admission scopes, increment the selected\n   replica's active assignment count, create a fresh fence token, and insert the\n   complete route.\n7. Commit the capacity reservation and assignment atomically, then return the\n   route to the remote dispatcher.\n\nNo provider side effect occurs inside this transaction. The remote handler\ndispatches only after the committed assignment is returned.\n\nFilter before ordering\n\nA replica is eligible for a new assignment only when the complete chain is\nvalid:\n• the tenant binding and instance are enabled and belong to the same tenant;\n• the active, qualified version implements the requested capability and belongs\n  to an enabled connector type;\n• the replica serves that instance and version, reports ready, has an\n  unexpired lease, and has unused capacity;\n• its circuit is closed; and\n• it satisfies the required capacity class and the configured cross-region\n  constraint.\n\nThe eligible rows are ordered by:\n1. lower binding priority;\n2. a preferred-region match;\n3. a preferred-zone match;\n4. fewer active assignments;\n5. an action-dependent hash of the replica ID; and\n6. stable instance and replica ID tie-breakers.\n\nRegion and zone are preferences for a new route. Capacity class is a filter.\nCross-region selection is allowed by default, but a deployment can forbid it.\nNone of these preferences changes an existing route.\n\nTreat the assignment as an immutable execution contract\n\nThe persisted RouteAssignment groups its fields by purpose:\n\n| Field group | Fields | Decision retained |\n\n| Work identity | actionid, capabilityid, tenantid | Which verified work contract was routed |\n| Logical target | instanceid, versionid, manifestdigest | Which product account and admitted implementation own the action |\n| Concrete peer | replicaid, endpoint, peerprincipalid, peerprincipalkind, peerdid, trustdomain, transportprofile, topology | Which signed process and failure domain received it |\n| Catalog and policy | catalogrevision, bindingpolicyrevision, credentialrevisionref, quotapolicyref | Which catalog, binding, credential, and quota decision applied |\n| Capacity and fencing | replicahealthrevision, fencetoken, admission | Which health observation and reserved policy scopes protect execution |\n| Evidence time | assignedat | When the route was created |\n\nThe remote dispatcher carries the route coordinates needed by the host in\nsigned request metadata and authenticates the assigned peer. The complete\nassignment remains registry state; not every internal reservation field becomes\nan AIP message field.\n\nReuse the route for retry and cancellation\n\nResolving an already assigned action never runs new target selection. If its\nprevious reservation was released, the registry tries to reserve the pinned\nadmission scopes and the same replica again. That reacquisition accepts a\nready or draining replica only while its lease, version, type, capacity, and\ncircuit state remain valid.\n\nIf the pinned replica is unavailable, resolution fails. It does not create a\nreplacement route. This prevents a retry from moving a possibly committed\nmutation to another provider account or host.\n\nCancellation reads the same assignment and sends the cancellation to its\nassigned replica. Reconciliation also uses the retained route to identify the\nprovider boundary whose outcome is uncertain.\n\nSettle capacity without deleting evidence\n\nSettlement accepts the exact assignment and one of four outcomes:\ncompleted, outcomeunknown, cancelled, or leaseexpired.\n\nThe registry locks the action, compares the complete stored assignment with the\ncaller-provided value, and rejects a mismatch as FenceLost. If the reservation\nis still active, one transaction:\n• releases every admission counter reserved for the attempt;\n• marks the route unreserved and records its last settlement;\n• decrements the replica's active assignment count; and\n• updates the replica circuit state.\n\nRepeated settlement after the reservation is already released is idempotent.\nThe assignment is retained.\n\nA completed outcome resets consecutive unknown failures. An\noutcomeunknown settlement increments the counter when circuit policy is\nenabled and opens the replica circuit after the configured threshold. A\ncancelled or lease-expired settlement releases capacity without pretending that\nthe provider succeeded.\n\nLease maintenance can mark a bounded number of expired replicas offline and\nrelease their fenced reservations. It does not contact connector endpoints and\ndoes not rewrite the destinations recorded in existing assignments.\n\nPreserve authority and failure boundaries\n\n| Boundary | Safe behavior |\n\n| No verified tenant context | Return no tenant catalog and refuse to derive routing authority from payload fields |\n| Missing binding | Return BindingUnavailable; do not search another tenant or unbound implementation |\n| No eligible host | Return ReplicaUnavailable; do not route to a draining or expired replica as new work |\n| Admission limit reached | Return CapacityExceeded with bounded retry guidance; do not overbook the counter |\n| Changed catalog during pagination | Return StaleCursor; restart the read from the first page |\n| Assignment mismatch or stale fence | Return conflict or FenceLost; do not settle another reservation |\n| Registry storage failure | Stop the state transition; do not infer that a route, reservation, or settlement committed |\n\nThe registry stores host endpoints and signed peer identities because routing\nneeds them. It stores opaque credential and secret-provider references because\nrotation and route evidence need revision identity. It never stores the\nprovider credential value and never lets transport data select a target.\n\nTrade-offs and non-implications\n• Revision locks favor coherent discovery. A page observes one catalog\n  publication, while replica heartbeats remain independent of that lock.\n• Per-action serialization favors stable identity. Concurrent duplicate\n  requests converge on one assignment but coordinate through one action lock.\n• Row locking favors bounded contention. SKIP LOCKED avoids waiting on a\n  busy replica row, while bounded retries can still return no capacity during a\n  short contention window.\n• Pinned assignments favor safe recovery. They prevent silent failover but\n  can make an unavailable replica a reconciliation problem instead of an\n  immediate rerouting opportunity.\n• Normalized records favor indexed selection. They avoid loading the whole\n  fleet, at the cost of explicit schema, transaction, and migration ownership.\n\nThe registry does not execute connector code, start an artifact, resolve a\nprovider secret, authorize a client, or prove a provider outcome. The reviewed\nsource contains a scale qualification contract, but its thresholds and results\nare evidence for a particular environment rather than portable performance or\navailability promises.\n\nRelated pages\n• Connector fleet architecture (connector-fleet.md)\n• Connector admission and supply-chain trust (connector-admission.md)\n• Connector fleet HTTP API (../reference/connector-fleet-api.md)\n• Deploy the connector fleet (../guides/deploy-connector-fleet.md)\n• Error reference (../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "3a8c8af01ba25f896caf64614f43094e1d619acadad074d2d0cda55bc27359d1"
  }
}