@creatornader/agent-bridge 0.3.1 → 0.4.0

package/dist/sqlite.d.ts

@@ -1,81 +1,7 @@
-import { b as BridgeMessage, c as BridgePrincipal, B as BridgeDelivery, g as DeliveryState, R as RetryPolicy, A as AgentPresence, a as BridgeDeliveryEvent } from './bridge-domain-CBX3IVqC.js';
-import { d as MessageQuery, M as MessagePage, B as BridgeDiagnostics, I as InsertMessageResult, a as BridgeStore, C as ClaimOptions, c as DeliveryQuery, b as DeliveryPage, D as DeliveryEventPage } from './bridge-store-DPVSCwfs.js';
-
-type PendingMessage = Omit<BridgeMessage, "sequence" | "createdAt">;
-interface EdgeScope {
-    endpoint: string;
-    principal: BridgePrincipal;
-}
-interface EdgeOutboxRecord {
-    position: number;
-    draft: PendingMessage;
-    payloadHash: string;
-    attempts: number;
-    leaseToken: string;
-    createdAt: string;
-}
-interface EdgeEnqueueResult {
-    draft: PendingMessage;
-    created: boolean;
-}
-interface EdgeStats {
-    pending: number;
-    due: number;
-    scheduled: number;
-    leased: number;
-    blocked: number;
-    cached: number;
-    pullCursor?: string;
-    lastSyncAt?: string;
-    lastError?: string;
-    oldestDueAt?: string;
-    queueLagMs: number;
-    oldestBlockedAt?: string;
-    blockedAgeMs: number | null;
-    blockedMaxAttempts: number;
-    blockedLastError?: string;
-    nextRetryAt?: string;
-    lastOutboundSyncAt?: string;
-    lastInboundSyncAt?: string;
-    lastAttemptAt?: string;
-}
-declare class EdgeConflictError extends Error {
-    readonly code = "edge_idempotency_conflict";
-}
-declare function edgeMessageFingerprint(message: PendingMessage | BridgeMessage): string;
-declare function stableIdempotency(message: PendingMessage): PendingMessage;
-declare function edgeScopeKey(scope: EdgeScope): string;
-declare class SQLiteEdgeStore {
-    private readonly path;
-    private readonly scope;
-    private readonly busyTimeoutMs;
-    private readonly db;
-    private readonly databasePath;
-    private readonly preexistingFiles;
-    private readonly key;
-    private initialized;
-    private initialization?;
-    constructor(path: string, scope: EdgeScope, busyTimeoutMs?: number);
-    private restrictFiles;
-    get scopeKey(): string;
-    initialize(): Promise<void>;
-    private initializeOnce;
-    private ready;
-    enqueue(input: PendingMessage, now?: Date): Promise<EdgeEnqueueResult>;
-    claimNext(now?: Date, leaseMs?: number): Promise<EdgeOutboxRecord | undefined>;
-    retry(record: EdgeOutboxRecord, error: string, availableAt: Date): Promise<void>;
-    block(record: EdgeOutboxRecord, error: string, now?: Date): Promise<void>;
-    commit(record: EdgeOutboxRecord, message: BridgeMessage, now?: Date): Promise<void>;
-    private cacheOne;
-    cachePage(messages: BridgeMessage[], cursor: string | undefined, now?: Date): Promise<void>;
-    cacheLatest(messages: BridgeMessage[], now?: Date): Promise<void>;
-    list(query?: MessageQuery): Promise<MessagePage>;
-    pullCursor(): Promise<string | undefined>;
-    noteError(error: string): Promise<void>;
-    noteAttempt(now?: Date): Promise<void>;
-    stats(now?: Date): Promise<EdgeStats>;
-    close(): Promise<void>;
-}
+import { c as BridgePrincipal, B as BridgeDelivery, g as DeliveryState, R as RetryPolicy, A as AgentPresence, b as BridgeMessage, a as BridgeDeliveryEvent } from './bridge-domain-CBX3IVqC.js';
+import { M as MessagePage, B as BridgeDiagnostics, I as InsertMessageResult, a as BridgeStore, d as MessageQuery, C as ClaimOptions, c as DeliveryQuery, b as DeliveryPage, D as DeliveryEventPage } from './bridge-store-Boaj-ZbO.js';
+import { e as EdgeMigrationGateState, S as SQLiteEdgeStore, a as EdgeDrainLease, P as PendingMessage } from './sqlite-edge-store-Bc15DvpX.js';
+export { E as EdgeConflictError, b as EdgeEnqueueResult, c as EdgeMigrationDrainingError, d as EdgeMigrationGate, f as EdgeMigrationLeaseError, g as EdgeMigrationRetiredError, h as EdgeOutboxRecord, i as EdgeReadOnlyInspection, j as EdgeScope, k as EdgeStats, l as edgeMessageFingerprint, m as edgeScopeKey, n as inspectEdgeScopeReadOnly, s as stableIdempotency } from './sqlite-edge-store-Bc15DvpX.js';
 
 interface SyncInsertResult extends InsertMessageResult {
     disposition: "committed" | "queued";
@@ -100,6 +26,9 @@ interface SyncReport {
     lastSyncedAt?: string;
     lastError?: string;
     failureRetryable?: boolean;
+    migrationState?: EdgeMigrationGateState;
+    migrationOperationId?: string;
+    migrationLeaseExpiresAt?: string;
 }
 interface SyncDiagnostics extends BridgeDiagnostics {
     remoteReachable: boolean | null;
@@ -121,9 +50,12 @@ interface SyncDiagnostics extends BridgeDiagnostics {
     lastOutboundSyncAt?: string;
     lastInboundSyncAt?: string;
     lastSyncAttemptAt?: string;
-    syncLoopState: "disabled" | "idle" | "running" | "backoff" | "stopped" | "failed";
+    syncLoopState: "disabled" | "idle" | "running" | "backoff" | "paused" | "stopped" | "failed";
     syncLoopError?: string;
     remoteError?: string;
+    migrationState: EdgeMigrationGateState;
+    migrationOperationId?: string;
+    migrationLeaseExpiresAt?: string;
 }
 interface SyncingBridgeStoreOptions {
     now?: () => Date;
@@ -133,6 +65,9 @@ interface SyncingBridgeStoreOptions {
     leaseMs?: number;
     autoSync?: boolean;
     idleDelayMs?: number;
+    edgeDrainLease?: EdgeDrainLease;
+    /** A maintenance caller may retain the edge while closing the sync wrapper. */
+    closeEdge?: boolean;
 }
 declare function isRetryableSyncError(error: unknown): boolean;
 declare class SyncingBridgeStore implements BridgeStore {
@@ -146,6 +81,8 @@ declare class SyncingBridgeStore implements BridgeStore {
     private readonly leaseMs;
     private readonly autoSync;
     private readonly idleDelayMs;
+    private edgeDrainLease?;
+    private readonly closeEdge;
     private remoteReady;
     private stopped;
     private wakeTimer;
@@ -158,6 +95,8 @@ declare class SyncingBridgeStore implements BridgeStore {
     private loopState;
     constructor(edge: SQLiteEdgeStore, remote: BridgeStore, principal: BridgePrincipal, options?: SyncingBridgeStoreOptions);
     initialize(): Promise<void>;
+    /** Replace a renewed maintenance lease without creating another edge wrapper. */
+    setDrainLease(lease: EdgeDrainLease | undefined): void;
     private startTransportLoop;
     private wait;
     private wakeTransport;
@@ -235,4 +174,4 @@ declare class SQLiteBridgeStore implements BridgeStore {
     close(): Promise<void>;
 }
 
-export { type CachedMessagePage, EdgeConflictError, type EdgeEnqueueResult, type EdgeOutboxRecord, type EdgeScope, type EdgeStats, type PendingMessage, SQLiteBridgeStore, SQLiteEdgeStore, type SyncDiagnostics, type SyncInsertResult, type SyncReport, SyncingBridgeStore, type SyncingBridgeStoreOptions, edgeMessageFingerprint, edgeScopeKey, isRetryableSyncError, stableIdempotency };
+export { type CachedMessagePage, EdgeDrainLease, EdgeMigrationGateState, PendingMessage, SQLiteBridgeStore, SQLiteEdgeStore, type SyncDiagnostics, type SyncInsertResult, type SyncReport, SyncingBridgeStore, type SyncingBridgeStoreOptions, isRetryableSyncError };

package/dist/sqlite.js

@@ -1,26 +1,34 @@
 #!/usr/bin/env node
 import {
   EdgeConflictError,
+  EdgeMigrationDrainingError,
+  EdgeMigrationLeaseError,
+  EdgeMigrationRetiredError,
   SQLiteEdgeStore,
   SyncingBridgeStore,
   edgeMessageFingerprint,
   edgeScopeKey,
+  inspectEdgeScopeReadOnly,
   isRetryableSyncError,
   stableIdempotency
-} from "./chunk-Q6PPMXJC.js";
+} from "./chunk-SV3SVBYS.js";
 import {
   SQLiteBridgeStore
-} from "./chunk-5GMB3A77.js";
-import "./chunk-NCO7RLBM.js";
+} from "./chunk-DQOZJJZ2.js";
+import "./chunk-GTK4KOED.js";
 import "./chunk-VOQIDTCJ.js";
 import "./chunk-BZLMF5O5.js";
 export {
   EdgeConflictError,
+  EdgeMigrationDrainingError,
+  EdgeMigrationLeaseError,
+  EdgeMigrationRetiredError,
   SQLiteBridgeStore,
   SQLiteEdgeStore,
   SyncingBridgeStore,
   edgeMessageFingerprint,
   edgeScopeKey,
+  inspectEdgeScopeReadOnly,
   isRetryableSyncError,
   stableIdempotency
 };

package/docs/architecture-v2.md

@@ -1,6 +1,6 @@
 # Agent Bridge v2 architecture
 
-Status: living architecture. Version 0.3.0 was released on July 15, 2026.
+Status: living architecture for the 0.4.x package line.
 
 ## Product boundary
 
@@ -31,6 +31,26 @@ A standalone Agent Bridge API sits between remote clients and PostgreSQL. Client
 
 Supabase can still host the database. Existing direct PostgREST deployments remain available through an explicitly named legacy adapter while they migrate.
 
+### Deployment separates schema and request authority
+
+The schema-owner connection runs migrations as an explicit one-shot operation. A
+separate bootstrap step creates or updates a restricted runtime login and grants only
+the database-derived runtime role. The gateway starts only after both steps succeed and
+receives no schema-owner authority. Its readiness check fails on an incomplete
+migration plan, unsupported PostgreSQL major, row-isolation drift, protected catalog
+drift, or an invalid owner-control membership graph.
+
+The repository Compose stack publishes the gateway and PostgreSQL on loopback for
+development. Production deployments put PostgreSQL on a private network, terminate TLS
+before every non-loopback gateway, and source credentials from the platform's secret
+manager. A persistent volume is runtime storage, not a backup.
+
+Upgrade order is database backup, migration, runtime bootstrap, readiness, then client
+or gateway rollout. Because an older image may reject the newer migration plan, schema
+rollback cannot rely on starting the previous container image. Operators apply a
+forward fix or restore a verified native DR bundle into a fresh target before switching
+authority. [The deployment guide](deployment.md) records the operational procedure.
+
 ### SQLite is local storage
 
 SQLite WAL provides local-only operation, a durable outbox, an inbox cache, cursor state, and a cheap pending-work check. Outbox writes use `synchronous=FULL`. It is not the canonical multi-machine database.
@@ -39,7 +59,17 @@ The gateway outbox queues immutable message publication. Receipt and lease mutat
 
 Long-lived gateway MCP clients own a cancellable transport loop that replays publications and refreshes the inbox cache with bounded exponential backoff. It is transport maintenance, not agent monitoring. Manual MCP and CLI sync use the same replay path. A publication timeout after the gateway may have committed remains queued under its stable idempotency key. A retry resolves to the original immutable message instead of publishing a duplicate.
 
-Local initialization must be idempotent. Every connection uses a bounded busy timeout. The minimum supported SQLite build must include the WAL-reset corruption fix. Node 22.23.1 on the current development machine embeds SQLite 3.51.3, which includes that fix.
+Local initialization must be idempotent. Concurrent initialization and schema upgrade
+use a 15-second minimum busy-retry window. Normal database operations retain the
+configured timeout. The minimum supported SQLite build must include the WAL-reset
+corruption fix. Node 22.23.1 on the current development machine embeds SQLite 3.51.3,
+which includes that fix.
+
+On Windows, an opening store verifies the private parent and main database before it
+connects. It applies and verifies explicit ACLs on live WAL and shared-memory sidecars
+after the connection establishes WAL and completes the serialized schema transaction.
+This avoids first-open sidecar churn between concurrent processes. A sidecar that is
+replaced during one ACL validation still fails closed.
 
 ### Portable archives cross storage engines without copying runtime state
 
@@ -123,10 +153,15 @@ PostgreSQL backup takes a repeatable-read exported snapshot while holding the na
 advisory fence. `pg_dump` captures only the `agent_bridge` schema. A separate canonical
 role inventory records the bounded role shells, membership options, and global or
 schema-scoped default ACLs that a schema-only dump omits. The dump excludes data for
-agent instances, rate-limit buckets, request authorities, and archive transaction
-authorizations. The manifest binds migration inventory, table counts, claimed-delivery
-count, tool major, role inventory, and the security, row-isolation, owner-control, and
-portable-archive readiness definitions.
+agent instances, rate-limit buckets, request authorities, endpoint-migration challenge
+rows, and archive transaction authorizations. The manifest binds migration
+inventory, table counts, claimed-delivery count, tool major, role inventory, and the
+security, row-isolation, owner-control, and portable-archive readiness definitions.
+
+The immutable gateway authority UUID is ordinary PostgreSQL data, so native backup and
+restore preserve it. The UUID proves that a restored target represents the same logical
+authority. It does not fence a live clone. Operators must still keep the source and
+restored target from serving traffic at the same time.
 
 PostgreSQL restore requires a dedicated fresh database, the same database name and
 server major, an exact-major `pg_restore`, and superuser authority. It restores role
@@ -250,6 +285,189 @@ Protocol logic depends on a `BridgeStore` interface, not a provider SDK. The ini
 
 Host and wakeup adapters are independent from storage. A client manifest declares identity injection, supported wake modes, config locations, health checks, and install actions for Codex, Claude Code, Claude Desktop, OpenClaw, or a generic MCP client. The v1 manifest key named `runtime` identifies an installation target for compatibility. It does not identify a unique running process. The `codex` adapter configures the profile shared by the Codex CLI and the Codex surface in the ChatGPT desktop app. Scripts, CI jobs, daemons, and application services may instead call the CLI or HTTPS API or embed the Node library without pretending to be a harness adapter.
 
+Client lifecycle ownership is separate from registration existence. Local inspection
+classifies a requested Codex, Claude Code, or Claude Desktop contract as absent,
+unmanaged, managed, or drifted by comparing the exact identity, stable instance key,
+backend path, scope, launch contract, and nonsecret registration locator. Desktop
+locators name the normalized host config, Codex locators name the active profile
+config, and Claude Code local or project locators include the invocation directory
+because the native CLI exposes no stronger target. Adoption is plan-first and writes
+only owner-private, credential-free metadata when `--apply` is explicit and the
+unmanaged registration is exact. Backend files and their immediate parents must pass
+the owner-only no-link policy. Codex JSON comparisons ignore diagnostic/status fields
+and property order but require exactly the three Agent Bridge environment keys;
+Claude Code connectivity status is not registration state. Claude Desktop inspection
+shares the installer's validated absolute launch resolver. Applied adoption
+re-inspects its postcondition. It does not read backend values or mutate the
+registration.
+Enrollment-based first-time provisioning retains strict registration and backend-file
+collision refusal. See
+[ADR 0004](decisions/0004-client-lifecycle-and-endpoint-migration.md).
+
+Managed-client repair, update, and uninstall use a local crash-safe substrate. Strict
+owner-private metadata is the mutation authority. Runtime plus stable instance locate
+the metadata, and identity must match both the record and the immutable repair or
+update request. Uninstall also binds the identity. Repair restores its launch contract. Update validates a new launch
+before it creates the journal and stores only the identity, normalized command,
+arguments, scope, and fixed Agent Bridge environment key names.
+Caller backend, scope, and host-config flags are rejected. Owner-private revisioned
+manifests live under
+`~/.agent-bridge/operations/<uuid>` with private snapshots and an exclusive lock keyed
+by runtime plus stable instance. Manifest publication fsyncs files, atomically renames,
+verifies private paths, and fsyncs directories where supported. Snapshot publication
+uses atomic no-replace links, so residue from an interrupted manifest update cannot be
+overwritten. Sensitive file access pins its immediate directory. Operation-root and
+target identities remain pinned throughout creation and destructive cleanup. The root
+and locks identities remain pinned throughout stale recovery, and the artifact-directory
+identity remains pinned across enumeration and every read. A typed credential-agnostic
+request and immutable plan record non-sensitive locators, unique no-replace before and
+after artifacts, and expected digests. Backend artifacts contain only a role, file
+identity, and private or repairable policy state. They never contain backend bytes,
+credentials, URLs, or workspace values. Begin is lock-covered and refuses another
+unfinished operation; any blocked journal fences new mutation, including resume. Resume
+is same-host only. The journal advances through prepared,
+snapshotted, in-progress, applied, cleaning, and committed. Inspection separately
+reports resumable, classification-required, blocked, or complete.
+
+Repair and uninstall journals use operation format version 3. New update and reverse
+rollback journals use v4. A v4 update request and terminal completion retain a bounded
+credential-free inverse contract: prior managed metadata, prior exact registration
+contract, and forward metadata and registration digests. Version 2 manifests retain
+their released request interpretation and remain inspectable. A non-terminal version 2
+record is blocked because it cannot prove the identity-bound request needed for these
+public mutations.
+
+Before a mutation, repair, update, and uninstall compare the full strict metadata record after
+acquiring the lock. Each non-metadata step repeats that authority check. Registration
+proofs include a bounded observation of the Agent Bridge entry and its full target
+contract. Unknown environment keys, malformed values, unsafe arguments, an unexpected
+scope, or an opaque registration shape stop before a journal is created.
+
+Native repair and update remove the managed entry, prove absence, add the exact target,
+and change metadata last when the launch changes. A native update command is one
+executable contract. Bare commands cannot contain argument separators, while absolute
+paths must resolve to executable files before an update is journaled. Codex runs get,
+remove, and add with the recorded profile home over the supplied environment. Claude
+Code uses its recorded scope, working directory, and supplied environment. Claude
+Desktop reads its recorded config without following links or link ancestors, replaces
+only `mcpServers.agent-bridge`, writes through an operation-scoped private temporary
+file, and verifies the published entry. Node cannot make that update atomic with an
+uncooperative same-user Desktop writer. The code pins and rechecks the file and parent
+identities immediately before rename, but this is an advisory race boundary, not an OS
+transaction guarantee. Windows accepts an already owner-private backend path and
+refuses a non-private backend instead of claiming a safe permission tightening.
+
+Uninstall removes a managed registration, proves its absence, deletes the private
+backend file, then deletes the management metadata. It does not tighten an unsafe
+backend before deletion. A backend that is not already private stops the plan before
+it removes the registration. Uninstall never rolls a completed step back. Desktop
+deletes only `mcpServers.agent-bridge` and preserves unrelated JSON. Before a backend
+or metadata unlink, the code checks the private parent and file identities. POSIX
+syncs that parent after deletion. Windows reports verified deletion with unavailable
+directory durability. Node pathname deletion cannot make this atomic against an
+uncooperative same-user writer, so that race remains advisory.
+
+Rollback is an explicit update-only operation. `clients rollback` locates authority
+only from a committed same-host v4 update record and requires the recorded identity as
+an assertion. It rejects a changed forward registration or metadata state before it
+creates a new reverse journal. Native rollback removes the forward registration,
+proves absence, adds the prior registration, proves it, and writes prior metadata last.
+Desktop replaces only `mcpServers.agent-bridge` and writes prior metadata last. The
+reverse journal retains its source operation UUID and inverse contract so generic
+resume needs no caller-provided backend, scope, command, runtime, or instance. A
+failed forward update is never compensated automatically. Repair has no rollback, and
+uninstall recovery requires re-enrollment.
+
+Native Windows ACL checks start uncached for each acquired or resumed mutation lock.
+While that lock remains held, later directory checks may reuse the result only for the
+same directory path, device, and inode. File checks always use the native policy.
+Passive inspection starts without a cache, and POSIX mode checks run on every access.
+A same-user process can still change an ACL on an unchanged directory or replace it
+with a directory that reuses the same filesystem identity. Local mode already treats
+that OS user as trusted. Agent Bridge does not delete a cached directory during a
+successful managed-client mutation.
+
+Cleanup durably records per-artifact intent, verifies and unlinks the pinned artifact,
+then records POSIX directory sync or explicit Windows unavailability. An absent file
+is resumable only when intent predates the cleanup attempt. Inspection also recognizes
+one verified after artifact left by an interrupted manifest publication. Other missing
+or extra files block. Committed means verified writes and removed artifacts. Its
+manifest drops requests, steps, locators, digests, and artifact metadata. A v4 update
+completion retains only its inverse contract. A v5 stage and a v6 migration phase
+retain bounded credential-free contracts. Other terminal completions retain the
+operation kind, step count, completion time, and cleanup durability for audit. Uninstall
+adds no rolled-back state. Physical erasure remains outside the filesystem contract.
+
+`clients resume <operation-id>` accepts stored v3 repair, update, and uninstall
+operations, supported v4 update and rollback operations, a committed v5 migration
+stage, and v6 endpoint-migration operations, with optional same-host stale-lock
+recovery. It derives authority from the immutable request. It rejects v2 records and
+cannot take replacement caller authority. Generic resume finishes an uninstall
+interrupted after metadata deletion and a reverse rollback interrupted after any
+recorded boundary.
+
+### Gateway client migration staging prepares a later cutover
+
+`clients migrate stage <runtime>` creates a private successor backend and a
+credential-free stage record. It leaves the managed registration, active backend, and
+source edge gate state unchanged after initializing the gate schema. It requires a
+rotation enrollment that keeps the predecessor valid through a future grace cutoff.
+The stage record binds the managed
+identity, source and target endpoint digests, both credential IDs, the source edge
+database path and scope key, and the grace cutoff. It does not store either token or a
+raw gateway URL.
+
+The source backend must bind an absolute, normalized edge database file. Relative and
+in-memory paths cannot identify the same durable outbox across harness working
+directories, so staging rejects them.
+
+An applied stage probes the active and staged bearer credentials, records the
+enrollment credential IDs, initializes the recorded source edge database, and requires
+its migration gate to be active. SQLite rejects a new outbox insert as soon as that
+gate begins draining, including inserts from a client that had already opened the
+database. These checks prepare a later drain and cutover. They do not authorize either
+action.
+
+The stage does not prove that source and target reach the same database authority. A
+later endpoint cutover may use alternate URLs only after it dynamically attests one
+logical authority. The authority identifier must survive clone and restore. Moving to
+an independent database requires a separate owner-mediated fence and is outside this
+staging command. A copied authority identifier does not prove that a live clone is
+fenced.
+
+### Endpoint cutover uses a separate v6 journal
+
+`clients migrate cutover <stage-operation-id> --exclusive-edge --apply` accepts only a
+committed v5 stage with its retained contract. It checks both live gateway status
+responses under HTTP 2.1. Each response must bind the recorded workspace, principal,
+and credential ID, and both must return the recorded immutable authority ID. The
+successor must grant `status:read` and `messages:write`. The source issues a direct
+predecessor-to-successor route challenge that the target consumes before the command
+changes an edge gate or host registration.
+
+The forward journal records full credential-free source and target metadata and
+registration proofs, source and target edge paths, a normalized credential-free source
+gateway URL, the v5 stage contract, and digest bindings for each proof. Once that
+journal exists, every mutation uses a fresh same-successor route proof issued from the
+retained source URL and consumed by the target. The source edge replays through the
+target gateway with the successor credential. It creates a durable source drain lease.
+The edge rejects new outbox inserts while draining. The lease worker must publish all
+work and prove a zero outbox before a native remove or add, a Desktop replacement, or
+the metadata-last switch. The command renews and reasserts the lease immediately before
+each host write. It rechecks the live target authority before every mutation. Source
+and target edge files must be distinct private regular files. The command rejects a
+managed cohort that shares the source edge, including a hardlink alias.
+`--exclusive-edge` covers unmanaged publishers that cannot be enumerated.
+
+Finalization requires a fresh assertion after the grace cutoff. It verifies the
+successor's live status binding and retires the retained source edge. Returning to a
+former endpoint requires a new owner credential rotation and a separate forward
+cutover. Cutover and finalization use exact durable before and after proofs for restart
+classification. A replacement worker can resume a draining edge only after the prior
+lease expires. Dry runs use read-only edge inspection. They do not initialize SQLite,
+create sidecars, or contact gateways. A dry run refuses an edge with live WAL sidecars
+because an immutable read could miss uncheckpointed outbox state.
+
 ### v1 compatibility is additive
 
 The MCP tools `post_context`, `get_context`, and `ack_context` remain available. Existing CLI verbs and flags remain accepted. Text responses remain present while v2 adds structured result data.
@@ -314,6 +532,33 @@ The stored definition is scoped to the control plane and its dependencies. It in
 
 Migration 012 removes direct runtime reads of credential digest material and establishes transaction-bound request authority. Node computes the credential hash, so PostgreSQL never receives the raw bearer credential. Request authority, security accounting, and domain work use one checked-out PostgreSQL client and one explicit transaction. A security-definer opener matches the credential ID and hash against current revocation, expiry, successor-grace, agent, and workspace state in one locked statement, then records the database-derived credential, workspace, principal, and scopes for that backend and transaction. Instance remains validated same-principal attribution and never establishes authority. Claim, cancel, and requeue reuse the outer transaction without nested `BEGIN`.
 
+Migration 017 adds an immutable singleton authority UUID and a separate bound opener.
+The released opener retains its original result shape. The bound opener returns the
+same credential, workspace, principal, and scopes with the authority UUID in the same
+request transaction. Runtime readiness checks the singleton row, mutation trigger,
+function catalog, and direct table and column privileges. The UUID is returned only by
+authenticated gateway status. It is not a capability field, log field, or readiness
+field.
+
+Migration 018 adds issue and consume operations for a gateway-only HTTP 2.1
+endpoint-migration challenge. The issuer provides a lowercase 64-character hexadecimal
+challenge, expected authority UUID, and direct active successor credential. The
+successor consumes the same commitment with its active transaction-bound authority.
+PostgreSQL hashes the challenge with a domain separator before persistence and retains
+no raw challenge in records, events, or replies. Challenges expire within 60 seconds,
+can be consumed once, and do not permit endpoint cutover. The migration 018
+predecessor-to-successor relation alone does not prove that two distinct URLs share
+live database state. The migration extends the credential-security catalog and records
+endpoint and owner-control v5 attestations before readiness succeeds.
+
+Migration 019 keeps the direct predecessor-to-successor challenge for initial
+preflight and also permits one active successor credential to issue and consume a
+challenge across the retained source and target URLs. It preserves the migration 018
+challenge data, events, security boundaries, and native DR treatment. Endpoint v2 and
+owner-control v6 attestations seal the updated catalog. Authenticated HTTP 2.1
+capabilities report the credential's granted scopes so cutover can reject a successor
+that lacks `status:read` or `messages:write` before it begins a journal.
+
 The domain savepoint separates expected rejected domain work from security effects: expected scope and rate accounting can commit while failed domain mutations are rolled back. An abort before commit rolls the whole request back. Once commit dispatch begins, the gateway never retries and reports `mutation_outcome_unknown` if the outcome is ambiguous. A failed rollback discards the pooled connection.
 
 Migration 013 enables and forces RLS on the five domain tables: messages, receipts, deliveries, delivery events, and agent instances. A database-specific no-login role owns those tables. Two more no-login roles isolate request-context reads and delivery-event writes. The gateway login inherits only the runtime role, which has `NOBYPASSRLS` and cannot inherit any of the owner roles. Zero-argument stable context functions read the workspace and principal from the authority row bound to the current backend, transaction ID, and session user. Policies call those functions through scalar subqueries so PostgreSQL evaluates them as InitPlans rather than once per row.
@@ -330,7 +575,7 @@ Limits apply to content bytes, payload bytes, metadata depth, target count, batc
 
 The CLI provides `init`, `doctor`, `status`, `demo`, `send`, `inbox`, `history`, `claim`, `ack`, `nack`, `watch`, `sync`, portable archive, and migration commands. Existing `post` and `get` aliases remain available.
 
-`/readyz` reports storage and schema readiness. Authenticated HTTP status reports the bound principal, provider schema, delivery counts, and the oldest due delivery. CLI `doctor` and `status` use a separate client-status contract that also reports local edge state and remote gateway reachability.
+`/readyz` reports storage and schema readiness. Authenticated HTTP status reports the bound principal, provider schema, delivery counts, and the oldest due delivery. When production request authority is active, it also returns additive `gatewayAuthorityId` and `credentialId` fields. They are optional in HTTP 2.1. CLI `doctor` and `status` use a separate client-status contract that also reports local edge state and remote gateway reachability.
 
 Gateway responses carry a request ID, including stable error envelopes. Scope failures return required scopes under `error.details`. Rate failures return a rounded retry delay in both the HTTP header and error details. Authenticated Prometheus output counts requests, errors, timeouts, and authentication failures. Responses, metrics, and append-only security events exclude bearer tokens, hashes, database URLs, payload bodies, arbitrary metadata, and credential material.
 
@@ -346,10 +591,11 @@ source, a tag-to-version check, and npm provenance. The npm environment does not
 currently require a human reviewer, so the release process must not claim a manual
 approval gate.
 
-GitHub immutable releases are enabled, and GitHub reports release `v0.3.0` as
+GitHub immutable releases are enabled, and GitHub reports release `v0.3.1` as
 immutable. A tag ruleset also blocks update and deletion of `v*` tags with no bypass
-actor. Future recovery dispatches must run the workflow at the release tag ref so the
-provenance workflow identity and checked-out source commit do not diverge.
+actor. Recovery dispatches must run the workflow at the release tag ref so the
+provenance workflow identity and checked-out source commit do not diverge. Release
+packaging also waits for the exact commit to pass the full `test.yml` matrix on `main`.
 
 ## Acceptance checks