@creatornader/agent-bridge 0.3.1 → 0.5.0

package/docs/deployment.md

@@ -0,0 +1,349 @@
+# Deploy Agent Bridge
+
+The repository includes a Compose stack for local development and a production image
+definition. The Compose file is intentionally bound to loopback. It is useful for
+evaluation, integration work, and the repository acceptance test. It is not a public
+TLS deployment.
+
+## Development stack
+
+Requirements:
+
+- Docker Engine or Docker Desktop with Compose v2.
+- Node.js 22.23.1 or newer to generate private development secrets and run operator
+  commands from the source checkout.
+- Free loopback ports 8787 and 54329, or explicit replacement values.
+
+Create two independent passwords. Keep the files out of version control.
+
+```bash
+mkdir -m 700 .secrets
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" > .secrets/postgres_password
+node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))" > .secrets/runtime_password
+chmod 600 .secrets/*
+```
+
+Build and start the stack:
+
+```bash
+docker compose build --pull gateway
+docker compose up --wait gateway
+curl --fail http://127.0.0.1:8787/readyz
+```
+
+The services start in this order:
+
+1. PostgreSQL becomes healthy.
+2. `migrate` applies the ordered schema with the schema-owner login and exits.
+3. `bootstrap-runtime` creates or updates `agent_bridge_gateway`, grants the
+   database-derived runtime role, and exits.
+4. `gateway` starts with the restricted login and must pass `/readyz`.
+
+The stack stores PostgreSQL data in the `postgres_data` named volume. `docker compose
+down` removes containers and keeps the volume. `docker compose down --volumes` deletes
+the development database. Inspect the project name and volume before using the second
+command.
+
+The default bindings are `127.0.0.1:8787` for the gateway and `127.0.0.1:54329` for
+PostgreSQL. Override them without editing the file:
+
+```bash
+AGENT_BRIDGE_PORT=18787 \
+AGENT_BRIDGE_POSTGRES_PORT=15432 \
+docker compose up --wait gateway
+```
+
+Use the [owner enrollment workflow](../README.md#gateway-setup) to
+create principal-bound credentials. Do not put a gateway token in the shared backend
+config. Each installed client receives its own private backend file.
+
+Run the same disposable proof as CI after building the TypeScript artifacts:
+
+```bash
+npm ci
+npm run build
+./scripts/compose-smoke.sh
+```
+
+The script creates a unique Compose project name that callers cannot override. It also
+creates temporary database passwords, a temporary operator, and two principal
+credentials. It proves source and workspace binding, targeted delivery, lease
+settlement, short-password rejection, denied runtime access to credential hashes, and
+message persistence through a full stack restart with a fresh edge cache. Its exit trap
+removes the project volume, image tag, credentials, and temporary files.
+
+## Production requirements
+
+Use the image stages and service boundaries as inputs to the deployment platform. Do
+not expose the checked-in Compose stack unchanged.
+
+### Network and TLS
+
+- Keep PostgreSQL on a private network. Do not publish port 5432 to the internet.
+- Put every non-loopback gateway behind a TLS terminator. Forward only from the trusted
+  proxy or ingress layer to the gateway's HTTP port.
+- Restrict administrative database access to migration, owner-control, archive,
+  backup, and restore jobs. Clients use the HTTPS gateway, not PostgreSQL.
+- Apply request size, connection, and upstream timeouts at the proxy without retrying
+  ambiguous mutations. Agent Bridge uses idempotency keys for safe publication replay.
+
+### Images and process policy
+
+- Build from the pinned Node base image and deploy an immutable image digest.
+- Run the gateway with a read-only root filesystem, a small writable temporary
+  filesystem, and `no-new-privileges`. The final gateway process must run as the
+  non-root image user with no effective Linux capabilities.
+- Compose file secrets retain host ownership on native Linux. The migration and gateway
+  services therefore start a small Node entrypoint as root with `DAC_OVERRIDE`,
+  `SETUID`, and `SETGID`. It reads the one granted secret, drops supplementary groups
+  and UID/GID to 1000, then imports the requested module. The final process has no
+  effective capabilities. The one-shot runtime bootstrap keeps `DAC_OVERRIDE`,
+  `SETUID`, and `SETGID` while it reads the two secret files, then `gosu` runs its fixed
+  SQL script as the PostgreSQL account. A production
+  secret injector may mount the secret directly for the runtime UID and omit this
+  handoff.
+- Allow at least 30 seconds for graceful shutdown. Stop accepting traffic before
+  terminating the process.
+- Gate traffic on `/readyz`. Liveness alone does not prove migration, row-isolation,
+  role, or protected-catalog readiness.
+
+### Secrets and database roles
+
+Keep these authorities separate:
+
+| Authority | Purpose | Long-lived gateway access |
+| --- | --- | --- |
+| Schema owner | Ordered migrations and trusted role registration | Never |
+| Runtime login | Gateway requests and readiness | Required |
+| Control operator | Credential provision, inventory, rotation, and revocation | Never |
+| Archive operator | Portable PostgreSQL archive operations | Never |
+| Backup and restore | Native DR backup or restore | Never |
+
+The schema owner may be a true PostgreSQL superuser or a managed-provider
+administrator with `CREATEROLE` and the database privileges reported by the production
+preflight. `CREATEROLE` is sufficient for migrations. Native backup requires the
+schema owner to be a true superuser or hold `BYPASSRLS`. A restore target validates the
+intentionally suspended restored schema-owner shell through its superuser session. Migrations create internal
+roles with safe defaults and reject unsafe preexisting roles instead of trying to demote
+them. PostgreSQL 16 and newer may store the schema owner's effective admin, inherit,
+and set authority in two physical grant rows. A native DR restore may recreate it as one
+combined bootstrap-superuser grant. Agent Bridge validates both forms and their
+effective authority. The restricted runtime login must never receive either schema-owner
+authority or `BYPASSRLS`.
+
+Migration 021 creates a database-derived `NOLOGIN` backup-reader role. It receives
+`SELECT` on Agent Bridge tables and sequences and is granted only to the schema owner.
+This lets a managed schema owner retain `BYPASSRLS` while producing a complete native
+backup. Do not grant the reader to the runtime login, control members, archive members,
+or another external principal. Native backup and restore require this attestation.
+Gateway runtime readiness does not, so an owner-only backup fault cannot stop normal
+gateway traffic.
+
+Use the platform's secret manager or private mounted secret files. Do not put raw
+passwords, tokens, or complete database URLs in image layers, source control, command
+arguments, deployment logs, or shared client config. Rotate each authority on its own
+schedule and after any suspected exposure.
+
+The runtime database password must contain at least 32 characters. The bootstrap job
+fails before role creation or alteration when the mounted value is shorter.
+
+## Fly.io reference hosting
+
+[`deploy/fly.toml`](../deploy/fly.toml) is the maintained Fly gateway contract. It has
+no app name, region, or release command. The operator chooses the account, app, region,
+PostgreSQL service, and public hostname. Fly terminates HTTPS and forwards to port
+8787. The service keeps at least one `shared-cpu-1x` machine with 512 MB running, checks
+`GET /readyz`, and gives the Node process 30 seconds after SIGTERM to close listeners
+and database pools.
+
+Run the repository check before any Fly action:
+
+```bash
+npm run preflight:fly -- --json
+```
+
+The local check verifies Node, the Dockerfile, and the static Fly contract. If the app
+already exists, add its name:
+
+```bash
+npm run preflight:fly -- --app <app> --json
+```
+
+With `--app`, the command invokes only read-only Fly commands. It observes the active
+account, app status, effective config, machines, and secret names. Its JSON includes
+names and check results but never environment-variable values. A passing local check
+does not prove that an external resource exists or that deployment is safe.
+
+The long-running Fly machine may receive only the restricted
+`AGENT_BRIDGE_RUNTIME_DATABASE_URL` database authority. Do not give it
+`AGENT_BRIDGE_DATABASE_URL`, `AGENT_BRIDGE_OPERATOR_DATABASE_URL`,
+`AGENT_BRIDGE_RUNTIME_PASSWORD`, a client bearer token, or a Supabase client key. The
+preflight rejects those names. Keep schema-owner, control-operator, archive, and DR
+authority in separate operator jobs.
+
+### Operator order and gates
+
+The following actions change external state and require an operator gate. The
+repository does not perform them:
+
+1. Create or select the Fly app and PostgreSQL authority. Keep PostgreSQL private.
+2. Run the read-only production database preflight before any backup or migration:
+
+   ```bash
+   AGENT_BRIDGE_DATABASE_URL="..." npm run preflight:postgres:production -- --json --require-ssl
+   ```
+
+   The command opens a read-only transaction and reports only nonsecret capability
+   and schema facts. `authority.roles` reports migration authority. `authority.native_dr`
+   reports whether the source schema owner is a true superuser or has `BYPASSRLS`. A
+   `CREATEROLE` role can pass the migration check while failing the native DR check.
+   The command also checks supported server majors, migration-ledger drift, derived-role
+   collisions, and the legacy import shape. The PostgreSQL 15 through 18 test matrix
+   separately applies the full migration plan as both a superuser and a
+   managed-provider-style `CREATEROLE` administrator. `--require-ssl` is required for a
+   public database endpoint. The preflight cannot prove that later DDL will succeed. For
+   a session pooler, it checks the client TLS socket because PostgreSQL reports the
+   pooler's separate database connection.
+3. Take and verify a native DR backup when upgrading an existing authority.
+4. Run `agent-bridge migrate` once in an isolated job with
+   `AGENT_BRIDGE_DATABASE_URL`. Drain old gateways first when the migration notes
+   require it.
+5. Run [`deploy/bootstrap-runtime.sql`](../deploy/bootstrap-runtime.sql) through a
+   separate trusted PostgreSQL session. Supply the schema-owner connection and the
+   runtime password to that job only. The bootstrap is transactional and changes an
+   existing login only when its attributes, ownership, and membership graph already
+   match the recorded runtime contract. It never adopts a restored `NOLOGIN` shell.
+6. Construct the restricted runtime URL, set only
+   `AGENT_BRIDGE_RUNTIME_DATABASE_URL` on the Fly app, and run the app-aware read-only
+   preflight.
+7. Deploy the immutable image with `fly deploy --config deploy/fly.toml --app <app>`.
+   Require `/readyz` before routing clients.
+8. Run authenticated capability and status probes, then publish, pull, claim, and
+   settle a disposable targeted delivery.
+9. Move clients only after the gateway proof passes. Preserve every source edge store
+   until its outbox is empty.
+
+App creation, database provisioning, secret writes, migration, bootstrap, deployment,
+traffic changes, and client cutover are all gated external actions. The preflight is
+read-only and cannot authorize any of them.
+
+### Fly rollback boundary
+
+Before migration, stop a failed deployment and keep the prior image and authority. A
+failed image rollout after a compatible migration can return traffic to the prior
+image only if that image accepts the current schema. Never assume that an older image
+can run against newer migrations.
+
+After clients publish through the new gateway, preserve both authorities and every
+edge database. Stop the cutover, drain queued outboxes, and reconcile authoritative
+messages before choosing one authority. If schema or data recovery is required,
+restore the verified native DR bundle into a fresh target and switch authority once.
+Do not run the source and restored database as active authorities at the same time.
+
+The manual `gateway production proof` GitHub Actions workflow runs this acceptance
+proof against an existing HTTPS gateway. GitHub restricts it to `main`, and every job
+uses the approval-protected `agent-bridge-production-proof` environment. Configure
+`PROOF_SENDER_TOKEN`, `PROOF_RECEIVER_TOKEN`, `PROOF_HOST_SALT`, and `FLY_API_TOKEN` as
+environment secrets. The sender and receiver credentials must bind the requested
+workspace to the dedicated `proof-sender` and `proof-receiver` principals. The
+sender credential needs `messages:write` and `messages:read`. The receiver needs
+`messages:read`, `deliveries:claim`, `deliveries:settle`, and `deliveries:read`.
+
+Run the workflow only when the Fly app has exactly one gateway machine. The cycle job
+restarts that machine and queries the Fly Machines API before and after. It fails
+unless the machine ID stays fixed, the runtime `instance_id` changes, the machine
+returns to `started`, and `/readyz` succeeds. This changes production compute and
+requires environment approval. It does not migrate the database or change secrets.
+
+The sender first uses an unreachable loopback origin to force a leased publication
+into its private SQLite outbox. It then synchronizes that row to the supplied gateway
+and repeats the publication with the same idempotency key. A separate host finds the
+exact message through `proof-receiver`, claims its delivery, and acknowledges it.
+After the Fly machine cycle, the verifier uses a fresh instance key, edge database,
+and cursor. It reads the immutable message and confirms that the prior delivery is
+still `acked`.
+
+Each phase writes an `agent-bridge-production-proof-v1` receipt. The runner rejects
+unknown fields at the phase boundary and checks every receipt before use. Receipts may
+record IDs, timestamps, principal and workspace labels, the gateway origin, boolean
+checks, and salted SHA-256 host evidence. They never record bearer values, database
+URLs, environment values, message content, lease tokens, cursor files, or edge
+databases. Download all four workflow artifacts for the operator record. A passing
+repository test still does not replace a completed external workflow run.
+
+### Persistent data and backup
+
+A database volume or managed PostgreSQL disk keeps runtime state. It does not protect
+against operator error, catalog drift, account loss, or regional failure.
+
+- Schedule native PostgreSQL DR backups with the exact PostgreSQL major tools.
+- Store verified bundles on a separate failure domain.
+- Record retention and deletion policy separately from message immutability.
+- Run restore drills into a fresh database with the same name and PostgreSQL major.
+- Never activate the source and restored target as authorities at the same time.
+
+Portable archives complement native DR when an operator needs one workspace's messages
+and eligible read receipts. They do not contain credentials, delivery state,
+owner-control state, or security events.
+
+## Upgrade procedure
+
+1. Confirm the target image supports the deployed PostgreSQL major and current protocol
+   clients.
+2. Drain or preserve each gateway client's SQLite outbox. Do not discard an edge store
+   with queued publications.
+3. Drain old gateway instances or remove them from traffic before migration 017, then
+   keep them out of traffic before migration 018. An old process can serve ordinary
+   requests until it exits even though its `/readyz` probe
+   fails after the newer migration is applied.
+4. Create and verify a native DR backup.
+5. Stop schema-changing jobs other than the selected migration job.
+6. Run the new image's migration command once with schema-owner authority.
+7. Run the runtime bootstrap with separate runtime-login credentials.
+8. Start the new gateway and require `/readyz`, an authenticated capability probe, and
+   an authenticated status probe.
+9. Send, read, claim, and settle a disposable targeted delivery.
+10. Roll clients forward only after the gateway proof passes.
+11. Keep the previous authority available but inactive until the observation window
+    closes.
+
+Run one migration job at a time. The migration ledger makes ordered application
+idempotent, but it does not make concurrent deployment orchestration desirable.
+
+## Rollback boundaries
+
+| Failure point | Safe response |
+| --- | --- |
+| Before schema migration | Stop the new gateway and return to the prior image and configuration. |
+| After migration, before client rollout | Keep clients on the old authority. Apply a forward fix, or restore the verified backup into a fresh target. |
+| After clients have published through the new gateway | Stop further cutover. Preserve every edge database and credential until queued outboxes are zero. Reconcile authoritative messages before switching back. |
+| Database corruption or unrecoverable catalog drift | Restore native DR into a fresh target, verify readiness, then switch authority once. |
+
+An older gateway may refuse a database with a newer migration plan. Starting the old
+image is therefore not a general schema rollback. A volume snapshot is also not enough
+unless its consistency and restore procedure have been proved for the database setup.
+Migration 017 makes this readiness failure explicit for an old compiled migration
+plan. It does not terminate an already-running old gateway. Drain it before applying
+the migration.
+
+## Operational checks
+
+- `/healthz` proves the HTTP process is alive.
+- `/readyz` proves the gateway can use the restricted database and that required
+  security attestations still match.
+- `agent-bridge doctor --json` probes a configured client's remote path.
+- `agent-bridge status` is passive and reports remote reachability as unknown until a
+  probe occurs.
+- Gateway metrics require a credential with `gateway:metrics`.
+
+Alert on readiness failure, repeated authorization denial, rate-limit pressure,
+database connection exhaustion, due or blocked outbox rows, dead-letter growth, backup
+failure, and restore-test failure. Keep tokens, database URLs, message content, and DR
+bundle paths out of telemetry.
+
+Related references:
+
+- [Architecture](architecture-v2.md)
+- [Security policy](../SECURITY.md)
+- [Troubleshooting](troubleshooting.md)
+- [Portable archives and native DR](../README.md#portable-archives)

package/docs/troubleshooting.md

@@ -81,6 +81,29 @@ Queued sends retain their idempotency keys. Long-lived MCP clients retry them, a
 `agent-bridge sync` triggers the same bounded replay manually. Claims, lease changes,
 delivery settlement, presence, and read-receipt writes still require the gateway.
 
+## Migration gate reported by status or doctor
+
+`clients migrate stage` does not begin a drain. `clients migrate cutover
+<stage-operation-id> --exclusive-edge --apply` changes the source edge to `draining`
+after it verifies both live gateways and their route challenge. In that state, normal
+publication is blocked while the recorded lease worker completes existing outbox work.
+`doctor` reports `draining` as degraded. A `retired` scope rejects new publication and
+`doctor` reports it as failed.
+
+Do not delete the edge database, alter the gate tables, or reopen a retired scope by
+hand. Inspect the operation ID reported by status. Resume the matching v6 operation
+with `clients resume <operation-id> [--recover-lock]`. A new worker cannot take an
+unexpired drain lease. It must wait for the lease to expire. Reverse before the
+predecessor grace cutoff is not supported. To return to the earlier endpoint, first
+rotate a new owner credential for that endpoint, then run an ordinary forward cutover
+with it as the successor. Finalization after grace retires the source. If no matching
+operation exists, preserve the database and stop rather than changing the gate
+manually.
+
+A dry migration plan refuses an edge with live `-wal` or `-shm` sidecars. Stop the
+writer and let SQLite checkpoint its state, then retry the plan. The plan never opens
+the edge in write mode to inspect it.
+
 ## Report a defect
 
 Include the client name, operating system, package version, sanitized `doctor --json`

package/llms.txt

@@ -11,6 +11,10 @@ History uses mailbox `inbox` (default), `sent`, or `all`. Receipt state is `any`
 - `npm install --global @creatornader/agent-bridge`
 - `agent-bridge init --provider local`
 - `agent-bridge demo`
+- Development gateway: create `.secrets/postgres_password` and
+  `.secrets/runtime_password`, then run `docker compose up --build --wait gateway`.
+  Both checked-in port bindings are loopback-only. See `docs/deployment.md` before a
+  non-loopback deployment.
 
 If an MCP client cannot attach, run `agent-bridge doctor --json` and see
 `docs/troubleshooting.md`. Normal client installation resolves the MCP launch command;
@@ -30,6 +34,7 @@ services can call the CLI or HTTPS API or embed the Node library without a host
 ## Commands
 
 - `agent-bridge --version` or `agent-bridge -V`: print the installed package version without loading backend configuration.
+- `agent-bridge --help`, `agent-bridge -h`, or a command followed by either help flag: print help without loading backend configuration or dispatching the command.
 - `agent-bridge capabilities`: print the canonical v2 operation and protocol capability document.
 
 - agent-bridge init --provider local
@@ -38,14 +43,52 @@ services can call the CLI or HTTPS API or embed the Node library without a host
 - `agent-bridge doctor`: active named checks; exits 0 ok, 2 degraded, 1 failed. Blocked outbox rows cannot be healthy.
 - agent-bridge pending
 - agent-bridge send, inbox, history, acknowledge
-- agent-bridge claim, extend, ack, nack, deliveries, delivery-events, cancel, requeue
+- agent-bridge claim [--message-id <uuid>], extend, ack, nack, deliveries, delivery-events, cancel, requeue
 - agent-bridge sync, watch, join, presence
 - agent-bridge clients install <runtime> --identity <principal>
+- agent-bridge clients inspect <runtime> --identity <principal> --instance <stable-key> --backend-config <absolute path>
+- agent-bridge clients adopt <runtime> --identity <principal> --instance <stable-key> --backend-config <absolute path> [--apply]
+- agent-bridge clients repair <runtime> --identity <principal> --instance <stable-key> [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge clients update <runtime> --identity <principal> --instance <stable-key> [--command <command>] [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge clients uninstall <runtime> --identity <principal> --instance <stable-key> [--apply] [--resume <uuid>] [--recover-lock]
+- agent-bridge clients rollback <update-operation-id> --identity <principal> [--apply] [--recover-lock]
+- agent-bridge clients migrate stage <runtime> --identity <principal> --instance <stable-key> --enrollment-file <private-path> [--apply] [--recover-lock]
+- agent-bridge clients migrate cutover <stage-operation-id> --exclusive-edge [--apply] [--recover-lock]
+- agent-bridge clients migrate finalize <cutover-operation-id> --exclusive-edge [--apply] [--recover-lock]
+- agent-bridge clients resume <operation-id> [--recover-lock]  # resumes recorded v3, supported v4, v5 stage, or v6 migration authority
+- agent-bridge clients operations [<operation-id>]  # read-only resumable/classification-required/blocked/complete summaries
 - agent-bridge owner provision|inventory|rotate|revoke
 - agent-bridge clients install <runtime> --enrollment-file <private path>
 - agent-bridge archive export|verify|import
 - agent-bridge dr backup|verify|restore
 
+Client inspection is local, read-only, secret-free, and reports absent, unmanaged,
+managed, or drifted. Adoption is a plan unless `--apply` is explicit. It writes only
+owner-private credential-free management metadata after the identity, stable instance,
+backend path, scope, and launch contract match exactly; it never rewrites the host
+registration or backend file. Enrollment-based first-time provisioning continues to
+refuse registration and backend-file collisions. Metadata binds Desktop to its
+normalized config path and Codex to its active profile config. Claude Code local and
+project scope bind to the invocation directory because its native CLI exposes no
+stronger registration target.
+The backend and its immediate parent must pass the owner-only no-link policy. Codex
+registration comparison ignores diagnostic fields and JSON property order but requires
+exactly AGENT_BRIDGE_AGENT, AGENT_BRIDGE_INSTANCE, and AGENT_BRIDGE_CONFIG. Claude Code
+connectivity status is not registration state. Desktop inspection uses the installer's
+validated absolute launch resolver, and applied adoption re-inspects its postcondition.
+Only Claude Code accepts `--scope`; only Claude Desktop accepts `--config-path` for
+inspect and adopt. Repair, update, and uninstall derive those locators from strict managed metadata.
+They reject backend, scope, and config-path authority flags. `--identity` binds the
+metadata record and immutable request. Repair restores the recorded launch contract.
+Update records a normalized credential-free launch request, including only fixed Agent
+Bridge environment key names. Native commands are one executable contract and reject
+arguments, URL-like selectors, and credential surfaces. Plan-only calls create no lock
+or operation. Native changes prove remove then add. Desktop replaces only the Agent
+Bridge config entry through a private operation-scoped temporary file. Its same-user
+writer race is advisory because Node cannot provide an OS transaction. Resume requires
+the same action and managed identity. Lock recovery requires
+same-host process-death proof.
+
 Archive export moves one workspace's immutable messages and read receipts between
 canonical local SQLite and PostgreSQL stores. Import defaults to a rollback-backed dry
 run and requires `--apply` to commit. PostgreSQL archive authority comes only from
@@ -75,14 +118,20 @@ excludes transient request, rate-limit, instance, and archive-authorization rows
 normalizes claimed deliveries on restore. Never run source and restored target at the
 same time. The package API is @creatornader/agent-bridge/dr. Bundle hashes detect
 changed bytes but do not encrypt or authenticate the source.
+The immutable PostgreSQL gateway authority UUID is preserved by native DR. It identifies
+one logical authority across restore but does not fence a live clone.
 
 ## MCP tools
 
 - `capabilities`: return operations, required scopes, provider-specific enforcement, and supported protocol versions. Gateway access needs an active credential but no named scope for this operation.
 - Production gateway capabilities report `requestAuthority: true` and `rowIsolation: true` only after the migration and live catalog, role, policy, privilege, and function checks pass. PostgreSQL forces RLS on messages, receipts, deliveries, delivery events, and presence. Lease transitions and target-to-delivery membership remain service-enforced.
+- Authenticated gateway `/v2/status` returns optional `gatewayAuthorityId` and
+  `credentialId` fields when PostgreSQL request authority is active. They are additive
+  in HTTP 2.1 and do not appear in capabilities.
 
 Compatibility: post_context, get_context, ack_context.
 Reliable messaging: send, history, claim, extend, acknowledge, negative_acknowledge, heartbeat, presence, sync.
+Claim selects the next due delivery unless HTTP 2.1, MCP, or CLI supplies one messageId. The exact form atomically selects and maintains only that eligible recipient delivery. HTTP 2.0 rejects the additive field.
 Publisher delivery intent: `deliveryPolicy` mode `mailbox|leased` with `maxAttempts`, `retryBaseDelayMs`, `retryMaxDelayMs`, `retryJitterRatio`, and optional `notBefore`. MCP delivery controls: `list_deliveries`, `list_delivery_events`, `cancel_delivery`, `requeue_delivery`. Consumer `maxAttempts` and `retryPolicy` are validated but ignored for one compatibility release.
 
 Gateway MCP clients sync automatically and expose manual sync for bounded outbox replay and inbox cache refresh. Offline unacknowledged results are degraded candidates with unknown acknowledgement state, not proof that messages are unread or that no remote work exists.
@@ -122,6 +171,24 @@ workspace, and live MCP registration matches. Consumed-file deletion and lock re
 report retained, missing, durable, and durability-unknown outcomes without claiming that
 an unlinked path was retained.
 
+`clients migrate stage` is a plan-first gateway migration preparation command. An
+applied stage creates an owner-private successor backend and credential-free operation
+record. It leaves the active registration, active backend, and source edge scope
+active after initializing its gate. Staging requires an absolute, normalized source
+edge database path and rejects `:memory:`.
+
+`clients migrate cutover` requires a committed v5 stage and `--exclusive-edge`. Initial
+preflight checks exact HTTP 2.1 status bindings at both gateways, one immutable
+authority ID, the successor's `status:read` and `messages:write` grants, and a direct
+predecessor-to-successor route challenge. Once it creates the journal, it uses a
+retained normalized source URL and the successor credential for every route proof and
+source outbox replay through the target gateway. `finalize` requires a fresh assertion
+after grace expires and retires the source. To return to a former endpoint, rotate a
+new owner credential and run an ordinary forward cutover to that endpoint. Dry runs
+read private edge state without SQLite writes or gateway requests. They refuse live WAL
+sidecars rather than read uncheckpointed outbox state. Resume uses only the retained v6
+request and waits for an unexpired drain lease instead of taking it over.
+
 Project is an optional immutable message label, not a tenant or identity selector. Omitted project reads include labeled and unlabeled messages. Exact project filters are supported by CLI, MCP, HTTP, and stores. Gateway workspace assertions must match the bound credential before network access.
 Local CLI calls may override workspace for one invocation. The legacy Supabase schema is global and always reports workspace `*`; use project labels for legacy filtering.
 
@@ -132,6 +199,7 @@ Local CLI calls may override workspace for one invocation. The legacy Supabase s
 - SECURITY.md: reporting process and security boundaries
 - docs/ecosystem.md: relationship to adjacent protocols, brokers, and runtimes
 - docs/troubleshooting.md: MCP startup and client recovery
+- docs/deployment.md: Compose development stack and production deployment constraints
 - docs/decisions/0001-protocol-layers-and-acknowledgment-semantics.md: protocol layers and acknowledgment semantics
 - docs/decisions/0002-canonical-operation-contract-registry.md: generated contracts and version negotiation
 - docs/decisions/0003-host-adapters-and-consumer-instance-keys.md: host layers and instance-key semantics