{
  "schemaVersion": "1.0",
  "title": "Orchestrate and roll back connector hosts",
  "description": "Use this guide to reconcile one connector instance through an external workload platform without giving that platform connector-registry administrator access. The procedure derives a deterministic plan from a verified admission package, an ",
  "canonical": "https://getaip.org/docs/guides/connector-orchestration",
  "route": "/docs/guides/connector-orchestration",
  "source": "docs/guides/connector-orchestration.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Deploy and Operate",
  "documentType": "Guide",
  "language": "en",
  "downloads": {
    "md": "/docs/download/guides/connector-orchestration.md",
    "txt": "/docs/download/guides/connector-orchestration.txt",
    "json": "/docs/download/guides/connector-orchestration.json",
    "pdf": "/docs/download/guides/connector-orchestration.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Orchestrate and roll back connector hosts\ndescription: Derive, sign, verify, execute, and roll back bounded connector deployment plans\nkind: how-to\naudience: operator\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Orchestrate and roll back connector hosts\n\nUse this guide to reconcile one connector instance through an external workload\nplatform without giving that platform connector-registry administrator access.\nThe procedure derives a deterministic plan from a verified admission package,\nan operator-reviewed intent, and a bounded platform observation. It signs the\ncomplete result and fences execution against a fresh observation. It also\njournals each operation before its first effect.\n\nThe contract is implemented by `aip-connector-orchestration` at source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`. It is product-neutral and applies\nto standalone Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and Twenty hosts.\n\nAIP does not contain a Kubernetes, Nomad, ECS, Docker, or other platform\nexecutor. `aipctl connector orchestration plan`, `sign`, and `verify` produce\nand validate JSON; none of them starts a process or writes connector-registry\nstate. A deployment-owned adapter must implement the verified operations and\nthe safety checks described here.\n\n## Keep orchestration outside registry authority\n\nThe orchestration contract separates four authorities:\n\n| Authority | Owns | Must not own |\n|---|---|---|\n| Release and admission | Signed package, immutable version, evidence, instances, and pre-provisioned replicas | Workload-platform credentials |\n| Orchestration signer | Reviewed deployment intent and signed deterministic plan | Registry administrator credentials or provider secrets |\n| External executor | Platform workload creation, observation, graceful termination, and operation journal | Catalog mutation or unsigned replica identity changes |\n| Host lifecycle service | Signed register, heartbeat, drain, and offline transitions | Admission packages or platform scheduling |\n\nThe plan contains an opaque `secret_provider_ref`, never secret material. The\nexecutor maps that reference to an approved platform mount without adding the\nresolved bytes to plans, labels, command lines, observations, or journals.\n\nRouting bindings are also outside this contract. Orchestration can make an\nalready admitted replica process exist, but only a separately admitted enabled\nbinding makes it eligible for a tenant capability.\n\n## Know the reconciliation inputs\n\nOne reconciliation cycle uses these exact inputs:\n\n| Input | Purpose |\n|---|---|\n| Signed admission package | Proves package identity, active immutable version, instance, replica identities, digest, and evidence |\n| Admission trust policy | Verifies the package and all required evidence roles |\n| Deployment intent | Declares one instance, monotonic generation, desired replica IDs, rollout budget, and time window |\n| Observed replicas | Reports the external platform's exact state for that instance |\n| Orchestration trust policy | Defines authorized plan signers and hard reconciliation limits |\n\nThe reconciler derives `ReplicaTarget` values from the verified package. An\nexecutor cannot inject a hidden target into a plan: the target map must exactly\nequal the intent's desired replica set, and verification recomputes the\noperation list from the embedded intent, targets, and observations.\n\nEach target fixes:\n\n- replica, instance, and version IDs;\n- lowercase SHA-256 artifact digest rather than a mutable tag;\n- HTTPS native endpoint ending exactly in `/aip/v1/messages`;\n- peer principal and `did:key`;\n- trust domain and topology;\n- instance configuration revision and opaque secret-provider reference;\n- admitted replica capacity.\n\nThe orchestration validator does not allow the host's loopback HTTP development\nexception. A target must use HTTPS and contain no URL credentials, query, or\nfragment.\n\n## Define the executor trust policy\n\nInstall an executor-local policy before accepting plans:\n\n```json\n{\n  \"trusted_signer_dids\": [\"did:key:<trusted-orchestration-key>\"],\n  \"limits\": {\n    \"max_replicas_per_instance\": 1000,\n    \"max_observations\": 2000,\n    \"max_operations\": 2000,\n    \"max_plan_ttl_seconds\": 300,\n    \"max_clock_skew_seconds\": 30\n  }\n}\n```\n\nThe values shown are implementation defaults, not deployment sizing advice.\nAll collection limits must be non-zero. Plan TTL can be at most 86,400 seconds,\nand accepted clock lead can be at most 300 seconds. Set lower bounds where the\nplatform and review process can support them.\n\nThe signer key must derive one of `trusted_signer_dids`. Keep the 32-byte\nEd25519 seed in a 64-hex-character owner-only file. The executor should receive\nonly the trust root, not the signing seed.\n\n## Build a complete platform observation\n\nRead the platform and connector registry immediately before planning. Include\nevery process observed for the selected instance, not only the desired set.\nEach observation contains:\n\n| Field | Meaning |\n|---|---|\n| `replica_id` | Concrete pre-provisioned or extra observed replica |\n| `instance_id` | The one instance being reconciled |\n| `version_id` | Version reported by the immutable process artifact |\n| `artifact_digest` | Digest reported by the platform runtime |\n| `generation` | Deployment generation applied by the platform |\n| `phase` | `starting`, `ready`, `draining`, `stopped`, or `failed` |\n\nReport `ready` only when the process serves and its connector-registry lease is\nready. A Kubernetes-style pod readiness bit alone is not sufficient. Report\n`draining` while the common lifecycle completes pinned work, `stopped` when the\nprocess is absent, and `failed` for a terminal or restartable platform failure.\n\nObservations must have unique replica IDs, a non-zero generation, and the exact\nintent instance. An observed generation newer than the proposed intent fences\nthe intent as stale. An absent desired replica may be omitted; the reconciler\ncan then produce `start` within budget.\n\nDo not conceal an extra replica. The reconciler needs it to produce a bounded\ndrain or stop operation.\n\n## Create the deployment intent\n\nUse schema `aip.connector-orchestration/v1`. The intent contains:\n\n| Field | Rule |\n|---|---|\n| `generation` | Non-zero and monotonically newer than the platform generation being changed |\n| `rollback_of_generation` | Omit for normal rollout; for rollback name the earlier generation being restored |\n| `package_id` | Stable signed admission package stream ID; 1–256 bytes |\n| `package_revision` | Exact non-zero verified package revision |\n| `package_digest` | Exact lowercase canonical SHA-256 digest returned by admission verification |\n| `instance_id` | One instance contained in that package |\n| `desired_replicas` | Exact set of pre-provisioned replica IDs that should run |\n| `max_surge` | Temporary active processes allowed above the desired count |\n| `max_unavailable` | Desired replicas allowed to be unavailable during replacement |\n| `issued_at`, `expires_at` | Reviewed time window within the policy TTL |\n\n`max_unavailable` cannot exceed the desired count. `max_surge` cannot exceed\nthe per-instance limit, and desired plus surge must fit that limit. An empty\ndesired set is the explicit scale-to-zero intent.\n\nThe verified connector type and instance must be enabled and the version must\nbe active before a non-empty desired set can start. Disabled types and\ninstances may only scale to zero.\n\nRetain the exact intent as a change artifact. Do not silently refresh its\ngeneration, package digest, desired set, budget, or time window after review.\n\n## Derive and review the next operation batch\n\nPlan without signing or writing:\n\n```sh\naipctl connector orchestration plan \\\n  --package admission-signed.json \\\n  --admission-trust-policy admission-trust-policy.json \\\n  --intent deployment-intent.json \\\n  --observed platform-observed.json \\\n  --orchestration-policy orchestration-policy.json > orchestration-plan.json\n```\n\nReview package coordinates, instance, generation, desired set, target digests,\nobserved snapshot, rollout bounds, and every operation. The reconciler emits\nonly four operation types:\n\n| Operation | Reconciler condition | Executor effect |\n|---|---|---|\n| `start` | Desired replica is absent or stopped and surge budget exists | Create the exact immutable target. |\n| `restart` | Desired replica is failed | Restart the same target without changing identity or digest. |\n| `drain` | Ready old or old-generation replica can leave within unavailability budget | Request common graceful host shutdown and verify signed drain state. |\n| `stop` | Replica is stopped or failed; an old-generation desired replica is starting or draining; or a non-desired replica is draining or starting during scale-to-zero | Remove only after the operation's full safety precondition is true. |\n\nOperations are canonically sorted as start/restart, then drain, then stop, with\nreplica ID as the stable tie-breaker. This order is not permission to run every\noperation concurrently. Execute in the signed order and obey the rollout budget\nand per-operation preconditions.\n\nFor a replacement with surge capacity, the first cycle normally starts the new\nreplica and does not drain the old one. A later cycle can drain the old replica\nonly after fresh observation reports enough ready capacity.\n\nAn empty operation list means the observed deployment is reconciled with this\nintent.\n\n## Sign the deterministic plan\n\nDerive and sign the exact batch with a trusted orchestration authority:\n\n```sh\naipctl connector orchestration sign \\\n  --package admission-signed.json \\\n  --admission-trust-policy admission-trust-policy.json \\\n  --intent deployment-intent.json \\\n  --observed platform-observed.json \\\n  --orchestration-policy orchestration-policy.json \\\n  --signing-seed-file /run/operator/orchestration-signing-seed.hex \\\n  --signer-identity deployment-controller > orchestration-signed.json\n```\n\n`sign` re-derives the plan, requires its signing DID to be trusted by the\nexecutor policy, signs canonical plan JSON, and verifies the result before\nprinting it. The signer identity must contain 1–512 bytes.\n\nTreat the signed file as immutable. A modified generation, target, observation,\noperation, order, or time window invalidates its signature or deterministic\nsemantic check.\n\n## Fence execution against fresh state\n\nRead the platform again immediately before the first operation and write a new\nbounded observation file. Verify the signature, limits, time window,\ndeterministic operations, and exact snapshot:\n\n```sh\naipctl connector orchestration verify \\\n  --plan orchestration-signed.json \\\n  --current-observed platform-current.json \\\n  --orchestration-policy orchestration-policy.json\n```\n\nRequire `status: verified`, `write_performed: false`, the expected package and\ngeneration, `snapshot_fenced: true`, and one `orchop_...` ID per operation. A\nchanged phase, generation, version, digest, missing replica, or newly observed\nreplica invalidates the complete batch. Reconcile and sign a new plan; do not\nedit the stale plan.\n\n## Journal before executing\n\nBefore the first platform effect, durably store:\n\n- canonical signed-plan bytes and digest;\n- signer DID and identity;\n- package ID, revision, and digest;\n- instance and generation;\n- fresh observed snapshot and verification time;\n- ordered operation IDs and payloads;\n- per-operation state, attempts, platform resource identity, and result;\n- stop, rollback, and escalation decisions.\n\nAn operation ID is a SHA-256-derived `orchop_` value bound to the complete plan\ndigest, operation index, replica ID, and payload. Use it as the platform\nadapter's idempotency key. Once the first operation begins, resume only this\nexact signed plan; do not reject it merely because execution itself changed the\noriginal observed snapshot.\n\nThe executor must be safe after response loss. Check the journal and platform\nstate before retrying a start, restart, drain, or stop. Never allocate a new\nreplica ID or select a mutable tag during retry.\n\n## Enforce operation-specific safety\n\nFor `start` and `restart`:\n\n1. resolve only the target's opaque secret reference;\n2. require the exact artifact digest from the signed target;\n3. apply the exact replica ID, instance, version, endpoint, principal, DID,\n   trust domain, topology, configuration revision, and capacity;\n4. wait for common host registration and `/ready`;\n5. compare the registered identity with the signed target;\n6. record the platform and lease evidence.\n\nFor `drain`, request the platform's graceful termination path. The host itself\nmust sign its lifecycle transition; the executor must not impersonate the host\nor write registry state. Preserve the process while pinned work completes.\n\nFor `stop`, treat the operation contract's phrase “fully drained” as a hard\nprecondition. The current reconciler can list `stop` when an observation says\n`draining`; that phase alone does not prove zero in-flight provider work.\n\nBegin\nand journal the stop operation, but defer destructive platform removal until\nhost lifecycle evidence shows the process has completed drain and is offline or\nabsent. A failed process may be removed only after its lease and durable-work\nstate are contained.\n\nIf a precondition cannot be established, leave the journal entry pending and\nescalate. Do not reinterpret a signed `stop` as permission for a blind kill.\n\n## Reconcile until no operations remain\n\nAfter the signed batch completes:\n\n1. capture a new complete observation for the same instance;\n2. keep the reviewed generation and desired set unchanged;\n3. issue a newly reviewed time window if the earlier intent expired;\n4. derive and sign the next deterministic batch;\n5. verify against another fresh snapshot;\n6. journal and execute that exact batch;\n7. repeat until the signed plan contains no operations.\n\nA generation refresh of the same immutable replica normally progresses through\ndrain, stop, and start across observations. A rollout to new replica IDs starts\nready replacements before old replicas can drain when the surge and\nunavailability budget require it. Scale-to-zero uses an empty desired set and\ndrains ready replicas before removing them.\n\nCompletion also requires registry readiness and tenant-scoped discovery where\nthe deployment is intended to receive traffic. An empty operation list alone\ndoes not enable a binding or prove provider qualification.\n\n## Roll back with a new generation\n\nRollback is a new desired-state transition, not reversal of journal entries:\n\n1. select a still-trusted admission package whose connector type and instance\n   are enabled and whose immutable version is active;\n2. use only replica targets pre-provisioned in that verified package;\n3. create a generation newer than every observed platform generation;\n4. set `rollback_of_generation` to the earlier known-good generation being\n   restored;\n5. set the desired replica set and bounded surge/unavailability values;\n6. plan, sign, fresh-snapshot verify, journal, and execute normally;\n7. reconcile until the rollback plan is empty;\n8. verify bindings, routes, host readiness, and provider behavior separately.\n\nDo not decrement generation. Do not reuse a current replica ID for an older\nversion or digest. If an old version is revoked, this orchestration contract\ncannot reactivate or start it; admit an acceptable immutable version through\nthe registry process instead.\n\nRollback does not change tenant bindings, rewrite existing route assignments,\nundo provider mutations, or rotate credentials. Coordinate those owning\nprocedures explicitly and retain ambiguous-effect evidence.\n\n## Stop conditions\n\nDiscard the proposed batch and reconcile again when:\n\n- the signed admission package or its evidence no longer verifies;\n- package coordinates or digest differ from the intent;\n- a desired replica is absent from the package;\n- a desired observed replica reports a different version or digest;\n- platform state changed before the first operation;\n- an observation belongs to another instance, is duplicated, or has a newer\n  generation;\n- the plan expired or exceeds executor limits;\n- the signer is untrusted or the signed operation list is not deterministic;\n- a start would use a mutable artifact or unreviewed secret mapping;\n- a drain would violate minimum ready capacity;\n- a stop lacks fully drained, offline, or contained-failure evidence;\n- the journal cannot prove whether an operation began.\n\nFor admission and initial target provisioning, use\n[Deploy the connector fleet](deploy-connector-fleet.md). Follow\n[Operate the connector host lifecycle](connector-host-lifecycle.md) for signed\ndrain and recovery, [Rotate connector credentials](connector-credentials-and-rotation.md)\nfor secret and binding changes, [Deploy AIP in production](production-deployment.md)\nfor authority separation, and [Identity and trust](../concepts/identity-and-trust.md)\nfor signing and opaque-reference boundaries.\n",
    "text": "Orchestrate and roll back connector hosts\n\nUse this guide to reconcile one connector instance through an external workload\nplatform without giving that platform connector-registry administrator access.\nThe procedure derives a deterministic plan from a verified admission package,\nan operator-reviewed intent, and a bounded platform observation. It signs the\ncomplete result and fences execution against a fresh observation. It also\njournals each operation before its first effect.\n\nThe contract is implemented by aip-connector-orchestration at source revision\n97be86e9efedf07ecf1783b03800f683f107fb04. It is product-neutral and applies\nto standalone Cal.diy, Hermes Agent, Chatwoot, Dify, CrewAI, and Twenty hosts.\n\nAIP does not contain a Kubernetes, Nomad, ECS, Docker, or other platform\nexecutor. aipctl connector orchestration plan, sign, and verify produce\nand validate JSON; none of them starts a process or writes connector-registry\nstate. A deployment-owned adapter must implement the verified operations and\nthe safety checks described here.\n\nKeep orchestration outside registry authority\n\nThe orchestration contract separates four authorities:\n\n| Authority | Owns | Must not own |\n\n| Release and admission | Signed package, immutable version, evidence, instances, and pre-provisioned replicas | Workload-platform credentials |\n| Orchestration signer | Reviewed deployment intent and signed deterministic plan | Registry administrator credentials or provider secrets |\n| External executor | Platform workload creation, observation, graceful termination, and operation journal | Catalog mutation or unsigned replica identity changes |\n| Host lifecycle service | Signed register, heartbeat, drain, and offline transitions | Admission packages or platform scheduling |\n\nThe plan contains an opaque secretproviderref, never secret material. The\nexecutor maps that reference to an approved platform mount without adding the\nresolved bytes to plans, labels, command lines, observations, or journals.\n\nRouting bindings are also outside this contract. Orchestration can make an\nalready admitted replica process exist, but only a separately admitted enabled\nbinding makes it eligible for a tenant capability.\n\nKnow the reconciliation inputs\n\nOne reconciliation cycle uses these exact inputs:\n\n| Input | Purpose |\n\n| Signed admission package | Proves package identity, active immutable version, instance, replica identities, digest, and evidence |\n| Admission trust policy | Verifies the package and all required evidence roles |\n| Deployment intent | Declares one instance, monotonic generation, desired replica IDs, rollout budget, and time window |\n| Observed replicas | Reports the external platform's exact state for that instance |\n| Orchestration trust policy | Defines authorized plan signers and hard reconciliation limits |\n\nThe reconciler derives ReplicaTarget values from the verified package. An\nexecutor cannot inject a hidden target into a plan: the target map must exactly\nequal the intent's desired replica set, and verification recomputes the\noperation list from the embedded intent, targets, and observations.\n\nEach target fixes:\n• replica, instance, and version IDs;\n• lowercase SHA-256 artifact digest rather than a mutable tag;\n• HTTPS native endpoint ending exactly in /aip/v1/messages;\n• peer principal and did:key;\n• trust domain and topology;\n• instance configuration revision and opaque secret-provider reference;\n• admitted replica capacity.\n\nThe orchestration validator does not allow the host's loopback HTTP development\nexception. A target must use HTTPS and contain no URL credentials, query, or\nfragment.\n\nDefine the executor trust policy\n\nInstall an executor-local policy before accepting plans:\n\n{\n  \"trustedsignerdids\": [\"did:key:\"],\n  \"limits\": {\n    \"maxreplicasperinstance\": 1000,\n    \"maxobservations\": 2000,\n    \"maxoperations\": 2000,\n    \"maxplanttlseconds\": 300,\n    \"maxclockskewseconds\": 30\n  }\n}\n\nThe values shown are implementation defaults, not deployment sizing advice.\nAll collection limits must be non-zero. Plan TTL can be at most 86,400 seconds,\nand accepted clock lead can be at most 300 seconds. Set lower bounds where the\nplatform and review process can support them.\n\nThe signer key must derive one of trustedsignerdids. Keep the 32-byte\nEd25519 seed in a 64-hex-character owner-only file. The executor should receive\nonly the trust root, not the signing seed.\n\nBuild a complete platform observation\n\nRead the platform and connector registry immediately before planning. Include\nevery process observed for the selected instance, not only the desired set.\nEach observation contains:\n\n| Field | Meaning |\n\n| replicaid | Concrete pre-provisioned or extra observed replica |\n| instanceid | The one instance being reconciled |\n| versionid | Version reported by the immutable process artifact |\n| artifactdigest | Digest reported by the platform runtime |\n| generation | Deployment generation applied by the platform |\n| phase | starting, ready, draining, stopped, or failed |\n\nReport ready only when the process serves and its connector-registry lease is\nready. A Kubernetes-style pod readiness bit alone is not sufficient. Report\ndraining while the common lifecycle completes pinned work, stopped when the\nprocess is absent, and failed for a terminal or restartable platform failure.\n\nObservations must have unique replica IDs, a non-zero generation, and the exact\nintent instance. An observed generation newer than the proposed intent fences\nthe intent as stale. An absent desired replica may be omitted; the reconciler\ncan then produce start within budget.\n\nDo not conceal an extra replica. The reconciler needs it to produce a bounded\ndrain or stop operation.\n\nCreate the deployment intent\n\nUse schema aip.connector-orchestration/v1. The intent contains:\n\n| Field | Rule |\n\n| generation | Non-zero and monotonically newer than the platform generation being changed |\n| rollbackofgeneration | Omit for normal rollout; for rollback name the earlier generation being restored |\n| packageid | Stable signed admission package stream ID; 1–256 bytes |\n| packagerevision | Exact non-zero verified package revision |\n| packagedigest | Exact lowercase canonical SHA-256 digest returned by admission verification |\n| instanceid | One instance contained in that package |\n| desiredreplicas | Exact set of pre-provisioned replica IDs that should run |\n| maxsurge | Temporary active processes allowed above the desired count |\n| maxunavailable | Desired replicas allowed to be unavailable during replacement |\n| issuedat, expiresat | Reviewed time window within the policy TTL |\n\nmaxunavailable cannot exceed the desired count. maxsurge cannot exceed\nthe per-instance limit, and desired plus surge must fit that limit. An empty\ndesired set is the explicit scale-to-zero intent.\n\nThe verified connector type and instance must be enabled and the version must\nbe active before a non-empty desired set can start. Disabled types and\ninstances may only scale to zero.\n\nRetain the exact intent as a change artifact. Do not silently refresh its\ngeneration, package digest, desired set, budget, or time window after review.\n\nDerive and review the next operation batch\n\nPlan without signing or writing:\n\naipctl connector orchestration plan \\\n  --package admission-signed.json \\\n  --admission-trust-policy admission-trust-policy.json \\\n  --intent deployment-intent.json \\\n  --observed platform-observed.json \\\n  --orchestration-policy orchestration-policy.json > orchestration-plan.json\n\nReview package coordinates, instance, generation, desired set, target digests,\nobserved snapshot, rollout bounds, and every operation. The reconciler emits\nonly four operation types:\n\n| Operation | Reconciler condition | Executor effect |\n\n| start | Desired replica is absent or stopped and surge budget exists | Create the exact immutable target. |\n| restart | Desired replica is failed | Restart the same target without changing identity or digest. |\n| drain | Ready old or old-generation replica can leave within unavailability budget | Request common graceful host shutdown and verify signed drain state. |\n| stop | Replica is stopped or failed; an old-generation desired replica is starting or draining; or a non-desired replica is draining or starting during scale-to-zero | Remove only after the operation's full safety precondition is true. |\n\nOperations are canonically sorted as start/restart, then drain, then stop, with\nreplica ID as the stable tie-breaker. This order is not permission to run every\noperation concurrently. Execute in the signed order and obey the rollout budget\nand per-operation preconditions.\n\nFor a replacement with surge capacity, the first cycle normally starts the new\nreplica and does not drain the old one. A later cycle can drain the old replica\nonly after fresh observation reports enough ready capacity.\n\nAn empty operation list means the observed deployment is reconciled with this\nintent.\n\nSign the deterministic plan\n\nDerive and sign the exact batch with a trusted orchestration authority:\n\naipctl connector orchestration sign \\\n  --package admission-signed.json \\\n  --admission-trust-policy admission-trust-policy.json \\\n  --intent deployment-intent.json \\\n  --observed platform-observed.json \\\n  --orchestration-policy orchestration-policy.json \\\n  --signing-seed-file /run/operator/orchestration-signing-seed.hex \\\n  --signer-identity deployment-controller > orchestration-signed.json\n\nsign re-derives the plan, requires its signing DID to be trusted by the\nexecutor policy, signs canonical plan JSON, and verifies the result before\nprinting it. The signer identity must contain 1–512 bytes.\n\nTreat the signed file as immutable. A modified generation, target, observation,\noperation, order, or time window invalidates its signature or deterministic\nsemantic check.\n\nFence execution against fresh state\n\nRead the platform again immediately before the first operation and write a new\nbounded observation file. Verify the signature, limits, time window,\ndeterministic operations, and exact snapshot:\n\naipctl connector orchestration verify \\\n  --plan orchestration-signed.json \\\n  --current-observed platform-current.json \\\n  --orchestration-policy orchestration-policy.json\n\nRequire status: verified, writeperformed: false, the expected package and\ngeneration, snapshotfenced: true, and one orchop... ID per operation. A\nchanged phase, generation, version, digest, missing replica, or newly observed\nreplica invalidates the complete batch. Reconcile and sign a new plan; do not\nedit the stale plan.\n\nJournal before executing\n\nBefore the first platform effect, durably store:\n• canonical signed-plan bytes and digest;\n• signer DID and identity;\n• package ID, revision, and digest;\n• instance and generation;\n• fresh observed snapshot and verification time;\n• ordered operation IDs and payloads;\n• per-operation state, attempts, platform resource identity, and result;\n• stop, rollback, and escalation decisions.\n\nAn operation ID is a SHA-256-derived orchop value bound to the complete plan\ndigest, operation index, replica ID, and payload. Use it as the platform\nadapter's idempotency key. Once the first operation begins, resume only this\nexact signed plan; do not reject it merely because execution itself changed the\noriginal observed snapshot.\n\nThe executor must be safe after response loss. Check the journal and platform\nstate before retrying a start, restart, drain, or stop. Never allocate a new\nreplica ID or select a mutable tag during retry.\n\nEnforce operation-specific safety\n\nFor start and restart:\n1. resolve only the target's opaque secret reference;\n2. require the exact artifact digest from the signed target;\n3. apply the exact replica ID, instance, version, endpoint, principal, DID,\n   trust domain, topology, configuration revision, and capacity;\n4. wait for common host registration and /ready;\n5. compare the registered identity with the signed target;\n6. record the platform and lease evidence.\n\nFor drain, request the platform's graceful termination path. The host itself\nmust sign its lifecycle transition; the executor must not impersonate the host\nor write registry state. Preserve the process while pinned work completes.\n\nFor stop, treat the operation contract's phrase “fully drained” as a hard\nprecondition. The current reconciler can list stop when an observation says\ndraining; that phase alone does not prove zero in-flight provider work.\n\nBegin\nand journal the stop operation, but defer destructive platform removal until\nhost lifecycle evidence shows the process has completed drain and is offline or\nabsent. A failed process may be removed only after its lease and durable-work\nstate are contained.\n\nIf a precondition cannot be established, leave the journal entry pending and\nescalate. Do not reinterpret a signed stop as permission for a blind kill.\n\nReconcile until no operations remain\n\nAfter the signed batch completes:\n1. capture a new complete observation for the same instance;\n2. keep the reviewed generation and desired set unchanged;\n3. issue a newly reviewed time window if the earlier intent expired;\n4. derive and sign the next deterministic batch;\n5. verify against another fresh snapshot;\n6. journal and execute that exact batch;\n7. repeat until the signed plan contains no operations.\n\nA generation refresh of the same immutable replica normally progresses through\ndrain, stop, and start across observations. A rollout to new replica IDs starts\nready replacements before old replicas can drain when the surge and\nunavailability budget require it. Scale-to-zero uses an empty desired set and\ndrains ready replicas before removing them.\n\nCompletion also requires registry readiness and tenant-scoped discovery where\nthe deployment is intended to receive traffic. An empty operation list alone\ndoes not enable a binding or prove provider qualification.\n\nRoll back with a new generation\n\nRollback is a new desired-state transition, not reversal of journal entries:\n1. select a still-trusted admission package whose connector type and instance\n   are enabled and whose immutable version is active;\n2. use only replica targets pre-provisioned in that verified package;\n3. create a generation newer than every observed platform generation;\n4. set rollbackofgeneration to the earlier known-good generation being\n   restored;\n5. set the desired replica set and bounded surge/unavailability values;\n6. plan, sign, fresh-snapshot verify, journal, and execute normally;\n7. reconcile until the rollback plan is empty;\n8. verify bindings, routes, host readiness, and provider behavior separately.\n\nDo not decrement generation. Do not reuse a current replica ID for an older\nversion or digest. If an old version is revoked, this orchestration contract\ncannot reactivate or start it; admit an acceptable immutable version through\nthe registry process instead.\n\nRollback does not change tenant bindings, rewrite existing route assignments,\nundo provider mutations, or rotate credentials. Coordinate those owning\nprocedures explicitly and retain ambiguous-effect evidence.\n\nStop conditions\n\nDiscard the proposed batch and reconcile again when:\n• the signed admission package or its evidence no longer verifies;\n• package coordinates or digest differ from the intent;\n• a desired replica is absent from the package;\n• a desired observed replica reports a different version or digest;\n• platform state changed before the first operation;\n• an observation belongs to another instance, is duplicated, or has a newer\n  generation;\n• the plan expired or exceeds executor limits;\n• the signer is untrusted or the signed operation list is not deterministic;\n• a start would use a mutable artifact or unreviewed secret mapping;\n• a drain would violate minimum ready capacity;\n• a stop lacks fully drained, offline, or contained-failure evidence;\n• the journal cannot prove whether an operation began.\n\nFor admission and initial target provisioning, use\nDeploy the connector fleet (deploy-connector-fleet.md). Follow\nOperate the connector host lifecycle (connector-host-lifecycle.md) for signed\ndrain and recovery, Rotate connector credentials (connector-credentials-and-rotation.md)\nfor secret and binding changes, Deploy AIP in production (production-deployment.md)\nfor authority separation, and Identity and trust (../concepts/identity-and-trust.md)\nfor signing and opaque-reference boundaries.\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "ad96eac46f44af0c3141ae3f9a6324ab5ff5b2896df55442e494700cd6c97a21"
  }
}