@byok-sdk/cloud-dataplane 0.11.0 → 0.13.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import pg from 'pg';
-import { DEDUP_RING_CAPACITY, NONCE_TTL_MS, validateActivityAppend, projectTimelineEvents, ByokCloudError, validateApprovalTimelineAppend, ApprovalObservationSchema, AllowAllRateLimiter, TruthCommitError, TruthCommitResponseSchema, truthRecordMetadata, TRUTH_REQUEST_ID_MAX_LENGTH, parseTimelineEvents, activityCursor, parseApprovalObservations, approvalTimelineCursor } from '@byok-sdk/cloud';
+import { DEDUP_RING_CAPACITY, NONCE_TTL_MS, assertTaskAttemptListLimit, validateActivityAppend, projectTimelineEvents, activitySourceBatchState, ByokCloudError, validateApprovalTimelineAppend, ApprovalObservationSchema, validateApprovalTimelineResolve, AllowAllRateLimiter, TruthCommitError, TruthCommitResponseSchema, truthRecordMetadata, TRUTH_REQUEST_ID_MAX_LENGTH, parseTimelineEvents, activityCursor, parseApprovalObservations, approvalTimelineCursor } from '@byok-sdk/cloud';
 import { contentHash, ByokCoreError, assertCanonicalTimestamp, isContentHash, tenantObjectKey, objectKeyPrefix, CoreConflictError, isLegalBoardTransition, checkSkillPackManifest, checkSkillPackEntry, SKILL_PACK_ENTRY_PATH, tenantId, SKILL_PACK_MANIFEST_SCHEMA_ID } from '@byok-sdk/core';
 import { AwsClient } from 'aws4fetch';
 import { XMLParser } from 'fast-xml-parser';
@@ -826,6 +826,57 @@ async function rollback(client) {
   } catch {
   }
 }
+async function registerDeviceOnClient(client, tenant, input) {
+  if (input.machineId !== void 0) {
+    const superseded = await client.query(
+      `DELETE FROM device
+        WHERE tenant_id = $1 AND product_id = $2 AND machine_id = $3 AND device_id <> $4
+      RETURNING device_id`,
+      [tenant, input.productId, input.machineId, input.deviceId]
+    );
+    await deleteDeviceState(
+      client,
+      tenant,
+      superseded.rows.map((row) => row.device_id)
+    );
+  }
+  const result = await client.query(
+    `INSERT INTO device (
+       tenant_id, device_id, product_id, device_name, device_public_key,
+       proof_key_id, proof_key_epoch, revoked, machine_id
+     )
+     VALUES ($1, $2, $3, $4, $5, $6, $7, false, $8)
+     ON CONFLICT (tenant_id, device_id) DO UPDATE
+       SET product_id = EXCLUDED.product_id,
+           device_name = EXCLUDED.device_name,
+           device_public_key = EXCLUDED.device_public_key,
+           proof_key_id = EXCLUDED.proof_key_id,
+           proof_key_epoch = EXCLUDED.proof_key_epoch,
+           revoked = false,
+           machine_id = EXCLUDED.machine_id,
+           capabilities = NULL
+     RETURNING ${SELECT_COLUMNS}`,
+    [
+      tenant,
+      input.deviceId,
+      input.productId,
+      input.deviceName,
+      input.devicePublicKey,
+      input.proofKeyId,
+      input.proofKeyEpoch,
+      input.machineId ?? null
+    ]
+  );
+  return toRecord(result.rows[0]);
+}
+async function getDeviceOnClient(client, tenant, deviceId) {
+  const result = await client.query(
+    `SELECT ${SELECT_COLUMNS} FROM device WHERE tenant_id = $1 AND device_id = $2`,
+    [tenant, deviceId]
+  );
+  const row = result.rows[0];
+  return row === void 0 ? void 0 : toRecord(row);
+}
 var PostgresDeviceDirectory = class {
   #pool;
   #clock;
@@ -837,48 +888,9 @@ var PostgresDeviceDirectory = class {
     const client = await this.#pool.connect();
     try {
       await client.query("BEGIN");
-      if (input.machineId !== void 0) {
-        const superseded = await client.query(
-          `DELETE FROM device
-            WHERE tenant_id = $1 AND product_id = $2 AND machine_id = $3 AND device_id <> $4
-          RETURNING device_id`,
-          [tenant, input.productId, input.machineId, input.deviceId]
-        );
-        await deleteDeviceState(
-          client,
-          tenant,
-          superseded.rows.map((row) => row.device_id)
-        );
-      }
-      const result = await client.query(
-        `INSERT INTO device (
-           tenant_id, device_id, product_id, device_name, device_public_key,
-           proof_key_id, proof_key_epoch, revoked, machine_id
-         )
-         VALUES ($1, $2, $3, $4, $5, $6, $7, false, $8)
-         ON CONFLICT (tenant_id, device_id) DO UPDATE
-           SET product_id = EXCLUDED.product_id,
-               device_name = EXCLUDED.device_name,
-               device_public_key = EXCLUDED.device_public_key,
-               proof_key_id = EXCLUDED.proof_key_id,
-               proof_key_epoch = EXCLUDED.proof_key_epoch,
-               revoked = false,
-               machine_id = EXCLUDED.machine_id,
-               capabilities = NULL
-         RETURNING ${SELECT_COLUMNS}`,
-        [
-          tenant,
-          input.deviceId,
-          input.productId,
-          input.deviceName,
-          input.devicePublicKey,
-          input.proofKeyId,
-          input.proofKeyEpoch,
-          input.machineId ?? null
-        ]
-      );
+      const record = await registerDeviceOnClient(client, tenant, input);
       await client.query("COMMIT");
-      return toRecord(result.rows[0]);
+      return record;
     } catch (cause) {
       await rollback(client);
       throw cause;
@@ -887,12 +899,12 @@ var PostgresDeviceDirectory = class {
     }
   }
   async get(tenant, deviceId) {
-    const result = await this.#pool.query(
-      `SELECT ${SELECT_COLUMNS} FROM device WHERE tenant_id = $1 AND device_id = $2`,
-      [tenant, deviceId]
-    );
-    const row = result.rows[0];
-    return row === void 0 ? void 0 : toRecord(row);
+    const client = await this.#pool.connect();
+    try {
+      return await getDeviceOnClient(client, tenant, deviceId);
+    } finally {
+      client.release();
+    }
   }
   /**
    * Revocation removes the registration and the device-scoped state that only
@@ -1026,23 +1038,31 @@ var PostgresInboundDedupStore = class {
     this.#capacity = capacity;
   }
   async checkAndRecord(tenant, deviceId, envelopeId) {
+    return this.#checkAndRecord(tenant, deviceId, "", "", envelopeId);
+  }
+  async checkAndRecordAgent(tenant, deviceId, agentRef, envelopeId) {
+    return this.#checkAndRecord(tenant, deviceId, agentRef.agentId, agentRef.profileRevision, envelopeId);
+  }
+  async #checkAndRecord(tenant, deviceId, agentId, agentProfileRevision, envelopeId) {
     const inserted = await this.#pool.query(
-      `INSERT INTO inbound_dedup (tenant_id, device_id, envelope_id)
-       VALUES ($1, $2, $3)
-       ON CONFLICT (tenant_id, device_id, envelope_id) DO NOTHING
+      `INSERT INTO inbound_dedup (tenant_id, device_id, agent_id, agent_profile_revision, envelope_id)
+       VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (tenant_id, device_id, agent_id, agent_profile_revision, envelope_id) DO NOTHING
        RETURNING 1`,
-      [tenant, deviceId, envelopeId]
+      [tenant, deviceId, agentId, agentProfileRevision, envelopeId]
     );
     if (inserted.rowCount === 0) return true;
     await this.#pool.query(
       `DELETE FROM inbound_dedup
         WHERE tenant_id = $1 AND device_id = $2
+          AND agent_id = $3 AND agent_profile_revision = $4
           AND recorded_seq <= (
             SELECT recorded_seq FROM inbound_dedup
              WHERE tenant_id = $1 AND device_id = $2
+               AND agent_id = $3 AND agent_profile_revision = $4
              ORDER BY recorded_seq DESC
-             OFFSET $3 LIMIT 1)`,
-      [tenant, deviceId, this.#capacity]
+             OFFSET $5 LIMIT 1)`,
+      [tenant, deviceId, agentId, agentProfileRevision, this.#capacity]
     );
     return false;
   }
@@ -1074,24 +1094,58 @@ var PostgresNonceStore = class {
     );
     return nonce;
   }
-  async validate(tenant, deviceId, nonce) {
+  async consumeIfValid(tenant, deviceId, nonce) {
     const result = await this.#pool.query(
-      `SELECT 1 FROM auth_nonce
-        WHERE tenant_id = $1 AND device_id = $2 AND nonce = $3
-          AND used = false AND expires_at >= $4`,
+      `UPDATE auth_nonce
+         SET used = true
+       WHERE tenant_id = $1 AND device_id = $2 AND nonce = $3
+         AND used = false AND expires_at >= $4
+       RETURNING nonce`,
       [tenant, deviceId, nonce, this.#clock.now().toISOString()]
     );
     return result.rowCount === 1;
   }
-  async markUsed(tenant, nonce) {
-    await this.#pool.query("UPDATE auth_nonce SET used = true WHERE tenant_id = $1 AND nonce = $2", [
-      tenant,
-      nonce
-    ]);
-  }
 };
 
 // src/stores/pairing-codes.ts
+function bindingOf(input) {
+  return {
+    deviceName: input.deviceName,
+    devicePublicKey: input.devicePublicKey,
+    proofKeyId: input.proofKeyId,
+    proofKeyEpoch: input.proofKeyEpoch,
+    ...input.machineId === void 0 ? {} : { machineId: input.machineId }
+  };
+}
+async function completionKey(pairingCode) {
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(`byok-pairing-completion-v1\0${pairingCode}`)
+  ));
+  const hex = [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `pairing-completion:v1:sha256:${hex}`;
+}
+function sameBinding(left, right) {
+  return left.deviceName === right.deviceName && left.devicePublicKey === right.devicePublicKey && left.proofKeyId === right.proofKeyId && left.proofKeyEpoch === right.proofKeyEpoch && left.machineId === right.machineId;
+}
+function sameDevice(device, claims, binding) {
+  return device.tenantId === claims.tenant_id && device.productId === claims.product_id && device.deviceName === binding.deviceName && device.devicePublicKey === binding.devicePublicKey && device.proofKeyId === binding.proofKeyId && device.proofKeyEpoch === binding.proofKeyEpoch && device.machineId === binding.machineId;
+}
+function parseCompletion(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed.deviceId !== "string" || parsed.binding === void 0 || typeof parsed.binding.deviceName !== "string" || typeof parsed.binding.devicePublicKey !== "string" || typeof parsed.binding.proofKeyId !== "string" || typeof parsed.binding.proofKeyEpoch !== "number" || parsed.binding.machineId !== void 0 && typeof parsed.binding.machineId !== "string") return void 0;
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function rollback2(client) {
+  try {
+    await client.query("ROLLBACK");
+  } catch {
+  }
+}
 var PostgresPairingCodeStore = class {
   #pool;
   #clock;
@@ -1100,30 +1154,102 @@ var PostgresPairingCodeStore = class {
     this.#clock = clock;
   }
   async issue(tenant, input) {
-    await this.#pool.query(
-      `INSERT INTO pairing_code (code, tenant_id, product_id, expires_at, redeemed_at)
-       VALUES ($1, $2, $3, $4, NULL)
-       ON CONFLICT (code) DO UPDATE
-         SET tenant_id = EXCLUDED.tenant_id,
-             product_id = EXCLUDED.product_id,
-             expires_at = EXCLUDED.expires_at,
-             redeemed_at = NULL`,
-      [input.code, tenant, input.productId, input.expiresAt]
-    );
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      const previous = await client.query(
+        "SELECT tenant_id FROM pairing_code WHERE code = $1 FOR UPDATE",
+        [input.code]
+      );
+      const key = await completionKey(input.code);
+      const previousTenant = previous.rows[0]?.tenant_id;
+      if (previousTenant !== void 0) {
+        await client.query(
+          "DELETE FROM device_request_receipts WHERE tenant_id = $1 AND key = $2",
+          [previousTenant, key]
+        );
+      }
+      await client.query(
+        `INSERT INTO pairing_code (code, tenant_id, product_id, expires_at, redeemed_at)
+         VALUES ($1, $2, $3, $4, NULL)
+         ON CONFLICT (code) DO UPDATE
+           SET tenant_id = EXCLUDED.tenant_id,
+               product_id = EXCLUDED.product_id,
+               expires_at = EXCLUDED.expires_at,
+               redeemed_at = NULL`,
+        [input.code, tenant, input.productId, input.expiresAt]
+      );
+      await client.query("COMMIT");
+    } catch (cause) {
+      await rollback2(client);
+      throw cause;
+    } finally {
+      client.release();
+    }
     return { code: input.code, expiresAt: input.expiresAt };
   }
-  async redeem(code) {
-    const now = this.#clock.now().toISOString();
-    const result = await this.#pool.query(
-      `UPDATE pairing_code
-          SET redeemed_at = $2
-        WHERE code = $1 AND redeemed_at IS NULL AND expires_at >= $2
-      RETURNING tenant_id, product_id`,
-      [code, now]
-    );
-    const row = result.rows[0];
-    if (row === void 0) return void 0;
-    return { tenantId: row.tenant_id, productId: row.product_id };
+  async redeemAndRegister(input) {
+    const now = this.#clock.now();
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      const selected = await client.query(
+        `SELECT tenant_id, product_id, expires_at, redeemed_at
+           FROM pairing_code WHERE code = $1 FOR UPDATE`,
+        [input.pairingCode]
+      );
+      const claims = selected.rows[0];
+      if (claims === void 0) {
+        await client.query("COMMIT");
+        return void 0;
+      }
+      const tenant = claims.tenant_id;
+      const binding = bindingOf(input);
+      if (claims.redeemed_at !== null) {
+        const stored = await client.query(
+          "SELECT body FROM device_request_receipts WHERE tenant_id = $1 AND key = $2",
+          [tenant, await completionKey(input.pairingCode)]
+        );
+        const completion2 = stored.rows[0] === void 0 ? void 0 : parseCompletion(stored.rows[0].body);
+        if (completion2 === void 0 || !sameBinding(completion2.binding, binding)) {
+          await client.query("COMMIT");
+          return void 0;
+        }
+        const device2 = await getDeviceOnClient(client, tenant, completion2.deviceId);
+        await client.query("COMMIT");
+        return device2 === void 0 || !sameDevice(device2, claims, binding) ? void 0 : device2;
+      }
+      if (claims.expires_at.getTime() < now.getTime()) {
+        await client.query("COMMIT");
+        return void 0;
+      }
+      await client.query(
+        "UPDATE pairing_code SET redeemed_at = $2 WHERE code = $1 AND redeemed_at IS NULL",
+        [input.pairingCode, now.toISOString()]
+      );
+      const device = await registerDeviceOnClient(client, tenant, {
+        productId: claims.product_id,
+        deviceId: input.deviceId,
+        deviceName: input.deviceName,
+        devicePublicKey: input.devicePublicKey,
+        proofKeyId: input.proofKeyId,
+        proofKeyEpoch: input.proofKeyEpoch,
+        ...input.machineId === void 0 ? {} : { machineId: input.machineId }
+      });
+      const completion = { deviceId: device.deviceId, binding };
+      await client.query(
+        `INSERT INTO device_request_receipts (tenant_id, key, body, recorded_at)
+         VALUES ($1, $2, $3, $4)`,
+        [tenant, await completionKey(input.pairingCode), JSON.stringify(completion), now.toISOString()]
+      );
+      await client.query("COMMIT");
+      return device;
+    } catch (cause) {
+      await rollback2(client);
+      throw cause;
+    } finally {
+      client.release();
+    }
   }
 };
 
@@ -1230,9 +1356,15 @@ var PostgresProofRequestReceiptStore = class {
     return row === void 0 ? void 0 : toReceipt2(row);
   }
 };
-
-// src/stores/task-attempts.ts
-var TASK_SELECT_COLUMNS = "tenant_id, task_id, device_id, agent_id, agent_profile_revision, owner_device_id, status, terminal_cause, cancel_requested_at, cancel_reason, cancel_message_id, updated_at";
+var TASK_SELECT_COLUMNS = "tenant_id, task_id, device_id, agent_id, agent_profile_revision, owner_device_id, status, terminal_cause, cancel_requested_at, cancel_reason, cancel_message_id, claimed_runtime, claimed_runtime_capabilities, updated_at";
+var AGENT_MESSAGE_ADMISSION_SELECT_COLUMNS = "message_id, payload_body, terminal_body";
+function admissionRowToRecord(row) {
+  return {
+    messageId: row.message_id,
+    payloadBody: row.payload_body,
+    ...row.terminal_body === null ? {} : { terminalBody: row.terminal_body }
+  };
+}
 function taskRowToAttempt(row) {
   return {
     tenantId: row.tenant_id,
@@ -1250,6 +1382,10 @@ function taskRowToAttempt(row) {
     // former.
     ...row.owner_device_id === null ? {} : { ownerDeviceId: row.owner_device_id },
     status: row.status,
+    // `claimed_runtime` is written only by the guarded claim UPDATE below, so a
+    // non-null value here is always the winning claim's own self-report.
+    ...row.claimed_runtime === null ? {} : { claimedRuntime: row.claimed_runtime },
+    ...row.claimed_runtime_capabilities === null ? {} : { claimedRuntimeCapabilities: row.claimed_runtime_capabilities },
     ...row.terminal_cause == null ? {} : { terminalCause: row.terminal_cause },
     ...row.cancel_requested_at === null ? {} : {
       cancellation: {
@@ -1308,6 +1444,80 @@ var PostgresTaskAttemptStore = class {
     if (existing === void 0) throw new Error(`task ${input.taskId} vanished during Agent offer reservation`);
     return { attempt: existing, created: false };
   }
+  async reserveAgentMessage(tenant, input) {
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      const selected = await client.query(
+        `SELECT ${TASK_SELECT_COLUMNS} FROM task
+          WHERE tenant_id = $1 AND task_id = $2 FOR UPDATE`,
+        [tenant, input.taskId]
+      );
+      const attempt = selected.rows[0];
+      const existing = await client.query(
+        `SELECT message_id, payload_body FROM agent_message_admission
+          WHERE tenant_id = $1 AND device_id = $2 AND task_id = $3`,
+        [tenant, input.deviceId, input.taskId]
+      );
+      const admission = existing.rows[0];
+      if (admission !== void 0) {
+        await client.query("COMMIT");
+        return admission.message_id === input.messageId && admission.payload_body === input.payloadBody ? "pending" : "rejected";
+      }
+      if (attempt === void 0 || attempt.device_id !== input.deviceId || attempt.cancel_requested_at !== null || !["offered", "claimed", "running"].includes(attempt.status)) {
+        await client.query("COMMIT");
+        return "rejected";
+      }
+      const inserted = await client.query(
+        `INSERT INTO agent_message_admission (
+           tenant_id, device_id, task_id, message_id, payload_body
+         ) VALUES ($1, $2, $3, $4, $5)
+         ON CONFLICT (tenant_id, device_id, task_id) DO NOTHING
+         RETURNING payload_body`,
+        [tenant, input.deviceId, input.taskId, input.messageId, input.payloadBody]
+      );
+      if (inserted.rows[0] !== void 0) {
+        await client.query("COMMIT");
+        return "reserved";
+      }
+      const raced = await client.query(
+        `SELECT message_id, payload_body FROM agent_message_admission
+          WHERE tenant_id = $1 AND device_id = $2 AND task_id = $3`,
+        [tenant, input.deviceId, input.taskId]
+      );
+      const racedAdmission = raced.rows[0];
+      await client.query("COMMIT");
+      return racedAdmission?.message_id === input.messageId && racedAdmission.payload_body === input.payloadBody ? "pending" : "rejected";
+    } catch (cause) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      throw cause;
+    } finally {
+      client.release();
+    }
+  }
+  async readAgentMessage(tenant, input) {
+    const result = await this.#pool.query(
+      `SELECT ${AGENT_MESSAGE_ADMISSION_SELECT_COLUMNS}
+         FROM agent_message_admission
+        WHERE tenant_id = $1 AND device_id = $2 AND task_id = $3`,
+      [tenant, input.deviceId, input.taskId]
+    );
+    const row = result.rows[0];
+    return row !== void 0 && row.message_id === input.messageId && row.payload_body === input.payloadBody ? admissionRowToRecord(row) : void 0;
+  }
+  async finalizeAgentMessage(tenant, input) {
+    const terminalized = await this.#pool.query(
+      `UPDATE agent_message_admission
+          SET terminal_body = $6
+        WHERE tenant_id = $1 AND device_id = $2 AND task_id = $3
+          AND message_id = $4 AND payload_body = $5 AND terminal_body IS NULL
+      RETURNING ${AGENT_MESSAGE_ADMISSION_SELECT_COLUMNS}`,
+      [tenant, input.deviceId, input.taskId, input.messageId, input.payloadBody, input.terminalBody]
+    );
+    const row = terminalized.rows[0];
+    return row === void 0 ? this.readAgentMessage(tenant, input) : admissionRowToRecord(row);
+  }
   async get(tenant, taskId) {
     const result = await this.#pool.query(
       `SELECT ${TASK_SELECT_COLUMNS} FROM task WHERE tenant_id = $1 AND task_id = $2`,
@@ -1324,14 +1534,44 @@ var PostgresTaskAttemptStore = class {
     );
     return result.rows.map(taskRowToAttempt);
   }
+  async list(tenant, query) {
+    assertTaskAttemptListLimit(query.limit);
+    const result = await this.#pool.query(
+      `SELECT ${TASK_SELECT_COLUMNS}
+         FROM task
+        WHERE tenant_id = $1 AND ($2::text IS NULL OR task_id > $2)
+        ORDER BY task_id
+        LIMIT $3`,
+      [tenant, query.cursor ?? null, query.limit + 1]
+    );
+    const rows = result.rows.slice(0, query.limit);
+    const attempts = rows.map(taskRowToAttempt);
+    const hasMore = result.rows.length > rows.length;
+    const last = attempts.at(-1);
+    return {
+      attempts,
+      ...hasMore && last !== void 0 ? { nextCursor: last.taskId } : {}
+    };
+  }
   async claim(tenant, input) {
     const claimed = await this.#pool.query(
       `UPDATE task
-          SET owner_device_id = $3, status = 'claimed', updated_at = $4
+          SET owner_device_id = $3,
+              status = 'claimed',
+              claimed_runtime = $5,
+              claimed_runtime_capabilities = $6::jsonb,
+              updated_at = $4
         WHERE tenant_id = $1 AND task_id = $2 AND owner_device_id IS NULL
           AND cancel_requested_at IS NULL AND status = 'offered'
       RETURNING ${TASK_SELECT_COLUMNS}`,
-      [tenant, input.taskId, input.deviceId, this.#now()]
+      [
+        tenant,
+        input.taskId,
+        input.deviceId,
+        this.#now(),
+        input.runtime ?? null,
+        input.capabilities === void 0 ? null : JSON.stringify(input.capabilities)
+      ]
     );
     const won = claimed.rows[0];
     if (won !== void 0) return taskRowToAttempt(won);
@@ -1496,20 +1736,63 @@ var PostgresMailboxStore = class {
       // Nothing above was mutated, so an identical call replays the same page.
       // The returned position is a READ cursor and moves no ack.
       nextSeq: page.at(-1)?.seq ?? query.afterSeq,
-      hasMore: result.rows.length > page.length
+      hasMore: result.rows.length > page.length,
+      recoverableFrom: await this.#recoverableFrom(tenant, query.deviceId)
     };
   }
+  /**
+   * One past the highest row this device lost, which is exactly the highest
+   * `expired` seq — `1` when it has lost nothing.
+   *
+   * No column and no migration, because `collectRetired` never deletes an
+   * unacked row: §12.7.5 keeps the dead letter, so the loss is already durable
+   * in `outbox` and a stored floor would be a second authority free to drift
+   * from the sweep that moved it. Whatever eventually reaps dead letters (S4B,
+   * O-009) is the change that has to carry this floor forward instead.
+   *
+   * `acked` rows are not counted: a consumed row is not a lost one.
+   *
+   * Read AFTER the page on purpose. A sweep landing between the two reads can
+   * only report a floor HIGHER than the page it accompanies, which makes the
+   * caller fail closed over a page that may already be missing rows; reading
+   * the floor first would report one too low and serve that gap silently.
+   */
+  async #recoverableFrom(tenant, deviceId) {
+    const result = await this.#pool.query(
+      `SELECT (COALESCE(MAX(seq), 0) + 1)::bigint AS recoverable_from
+         FROM outbox
+        WHERE tenant_id = $1 AND device_id = $2 AND state = 'expired'`,
+      [tenant, deviceId]
+    );
+    return Number(result.rows[0].recoverable_from);
+  }
   async advanceCursor(tenant, input) {
     this.#requireDeviceId(input.deviceId);
     const now = this.#now();
     const moved = await this.#pool.query(
-      `WITH moved AS (
-         INSERT INTO device_stream (tenant_id, device_id, next_seq, acked_seq, acked_at)
-         VALUES ($1, $2, 1, $3::bigint, $4)
+      `WITH moved_zero AS (
+         INSERT INTO device_stream (
+           tenant_id, device_id, next_seq, acked_seq, acked_at, delivered_seq
+         )
+         SELECT $1, $2, 1, 0, $4, 0
+          WHERE $3::bigint = 0
          ON CONFLICT (tenant_id, device_id) DO UPDATE
-            SET acked_seq = EXCLUDED.acked_seq, acked_at = EXCLUDED.acked_at
-          WHERE device_stream.acked_seq <= EXCLUDED.acked_seq
-         RETURNING acked_seq, acked_at
+            SET acked_seq = 0, acked_at = EXCLUDED.acked_at
+          WHERE device_stream.acked_seq <= 0
+            AND device_stream.delivered_seq >= 0
+         RETURNING acked_seq, acked_at, delivered_seq
+       ), moved_positive AS (
+         UPDATE device_stream
+            SET acked_seq = $3::bigint, acked_at = $4
+          WHERE tenant_id = $1 AND device_id = $2
+            AND $3::bigint > 0
+            AND acked_seq <= $3::bigint
+            AND delivered_seq >= $3::bigint
+         RETURNING acked_seq, acked_at, delivered_seq
+       ), moved AS (
+         SELECT acked_seq, acked_at, delivered_seq FROM moved_zero
+         UNION ALL
+         SELECT acked_seq, acked_at, delivered_seq FROM moved_positive
        ), marked AS (
          UPDATE outbox
             SET state = 'acked'
@@ -1517,7 +1800,7 @@ var PostgresMailboxStore = class {
             AND seq <= (SELECT acked_seq FROM moved)
          RETURNING 1
        )
-       SELECT acked_seq, acked_at FROM moved`,
+       SELECT acked_seq, acked_at, delivered_seq FROM moved`,
       [tenant, input.deviceId, input.ackedSeq, now]
     );
     const row = moved.rows[0];
@@ -1525,21 +1808,51 @@ var PostgresMailboxStore = class {
       return {
         tenantId: tenant,
         deviceId: input.deviceId,
+        deliveredSeq: Number(row.delivered_seq),
         ackedSeq: Number(row.acked_seq),
         updatedAt: row.acked_at ?? now
       };
     }
     const current = await this.readCursor(tenant, input.deviceId);
+    if (input.ackedSeq < current.ackedSeq) {
+      throw new CoreConflictError(
+        "mailbox_cursor_regression",
+        `Cursor for device ${input.deviceId} is at ${current.ackedSeq}; refusing to move it back to ${input.ackedSeq}.`,
+        current,
+        this.#now()
+      );
+    }
     throw new CoreConflictError(
-      "mailbox_cursor_regression",
-      `Cursor for device ${input.deviceId} is at ${current.ackedSeq}; refusing to move it back to ${input.ackedSeq}.`,
+      "mailbox_cursor_ahead_of_delivery",
+      `Cursor for device ${input.deviceId} was delivered through ${current.deliveredSeq}; refusing to acknowledge future cursor ${input.ackedSeq}.`,
       current,
       this.#now()
     );
   }
+  async recordDelivery(tenant, input) {
+    this.#requireDeviceId(input.deviceId);
+    const recorded = await this.#pool.query(
+      `INSERT INTO device_stream (
+         tenant_id, device_id, next_seq, acked_seq, acked_at, delivered_seq
+       )
+       VALUES ($1, $2, 1, 0, NULL, $3::bigint)
+       ON CONFLICT (tenant_id, device_id) DO UPDATE
+          SET delivered_seq = GREATEST(device_stream.delivered_seq, EXCLUDED.delivered_seq)
+       RETURNING acked_seq, acked_at, delivered_seq`,
+      [tenant, input.deviceId, input.deliveredSeq]
+    );
+    const row = recorded.rows[0];
+    return {
+      tenantId: tenant,
+      deviceId: input.deviceId,
+      deliveredSeq: Number(row.delivered_seq),
+      ackedSeq: Number(row.acked_seq),
+      updatedAt: row.acked_at ?? this.#now()
+    };
+  }
   async readCursor(tenant, deviceId) {
     const result = await this.#pool.query(
-      `SELECT acked_seq, acked_at FROM device_stream
+      `SELECT acked_seq, acked_at, delivered_seq FROM device_stream
         WHERE tenant_id = $1 AND device_id = $2`,
       [tenant, deviceId]
     );
@@ -1547,6 +1860,7 @@ var PostgresMailboxStore = class {
     return {
       tenantId: tenant,
       deviceId,
+      deliveredSeq: row === void 0 ? 0 : Number(row.delivered_seq),
       ackedSeq: row === void 0 ? 0 : Number(row.acked_seq),
       updatedAt: row?.acked_at ?? this.#now()
     };
@@ -1712,8 +2026,35 @@ var PostgresActivityStore = class {
     const receivedAt = now.toISOString();
     const incoming = projectTimelineEvents(input, receivedAt);
     const expiresAt = new Date(now.getTime() + input.ttlMs).toISOString();
-    const result = await this.pool.query(
-      `WITH incoming AS (
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        `SELECT pg_advisory_xact_lock(hashtextextended($1 || E'\\x1f' || $2, 0))`,
+        [tenant, input.taskId]
+      );
+      const locked = await client.query(
+        `SELECT tenant_id, task_id, entries, dropped, capacity, expires_at
+           FROM activity_tail
+          WHERE tenant_id = $1 AND task_id = $2
+          FOR UPDATE`,
+        [tenant, input.taskId]
+      );
+      const stored = locked.rows[0];
+      const live = stored !== void 0 && receivedAt < stored.expires_at ? toTail(stored) : void 0;
+      const sourceState = activitySourceBatchState(live?.entries ?? [], input);
+      if (sourceState === "same") {
+        await client.query("COMMIT");
+        return live;
+      }
+      if (sourceState === "conflict") {
+        throw new ByokCloudError(
+          "coordination_input_invalid",
+          `Activity source envelope ${input.sourceEnvelopeId} already belongs to another canonical batch.`
+        );
+      }
+      const result = await client.query(
+        `WITH incoming AS (
          SELECT entry
            FROM jsonb_array_elements($4::jsonb) AS element(entry)
        ), trimmed AS (
@@ -1780,16 +2121,24 @@ var PostgresActivityStore = class {
               )
            )
        RETURNING tenant_id, task_id, entries, dropped, capacity, expires_at`,
-      [tenant, input.taskId, receivedAt, JSON.stringify(incoming), input.dropped, capacity, expiresAt]
-    );
-    const row = result.rows[0];
-    if (row === void 0) {
-      throw new ByokCloudError(
-        "coordination_input_invalid",
-        `Activity batch ${input.batchSeq} conflicts with the existing typed tail authority.`
+        [tenant, input.taskId, receivedAt, JSON.stringify(incoming), input.dropped, capacity, expiresAt]
       );
+      const row = result.rows[0];
+      if (row === void 0) {
+        throw new ByokCloudError(
+          "coordination_input_invalid",
+          `Activity batch ${input.batchSeq} conflicts with the existing typed tail authority.`
+        );
+      }
+      await client.query("COMMIT");
+      return toTail(row);
+    } catch (caught) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      throw caught;
+    } finally {
+      client.release();
     }
-    return toTail(row);
   }
   async read(tenant, taskId) {
     const result = await this.pool.query(
@@ -1908,6 +2257,79 @@ var PostgresApprovalTimelineStore = class {
       client.release();
     }
   }
+  async resolvePending(tenant, input) {
+    const { capacity, ttlMs, event } = validateApprovalTimelineResolve(input);
+    const now = this.clock.now();
+    const receivedAt = now.toISOString();
+    const expiresAt = new Date(now.getTime() + ttlMs).toISOString();
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(
+        `SELECT pg_advisory_xact_lock(hashtextextended($1 || E'\\x1f' || $2, 0))`,
+        [tenant, input.taskId]
+      );
+      const stored = await readLocked(client, tenant, input.taskId);
+      const live = stored !== void 0 && receivedAt < stored.expires_at ? toTail2(stored) : void 0;
+      if (live === void 0) {
+        await client.query("COMMIT");
+        return { status: "absent" };
+      }
+      const duplicate = live.entries.find((entry) => entry.sourceEnvelopeId === input.sourceEnvelopeId);
+      if (duplicate !== void 0) {
+        await client.query("COMMIT");
+        return JSON.stringify(duplicate.event) === JSON.stringify(event) ? { status: "replayed", tail: live } : { status: "conflict", tail: live };
+      }
+      const pending = pendingObservation(live.entries);
+      if (pending === void 0) {
+        await client.query("COMMIT");
+        return { status: "absent", tail: live };
+      }
+      if (pending.sourceEnvelopeId !== input.expectedSourceEnvelopeId || pending.revision !== input.expectedRevision) {
+        await client.query("COMMIT");
+        return { status: "superseded", tail: live };
+      }
+      const revision = Number(stored.next_revision);
+      const expectedRevision = (live.cursor ?? 0) + 1;
+      if (!Number.isSafeInteger(revision) || revision <= 0 || revision !== expectedRevision) {
+        throw new ByokCloudError(
+          "coordination_input_invalid",
+          "Approval timeline revision authority is malformed."
+        );
+      }
+      const observation = ApprovalObservationSchema.parse({
+        taskId: input.taskId,
+        sourceEnvelopeId: input.sourceEnvelopeId,
+        revision,
+        receivedAt,
+        event
+      });
+      const allEntries = [...live.entries, observation];
+      const evicted = Math.max(allEntries.length - capacity, 0);
+      const entries = allEntries.slice(evicted);
+      const dropped = live.dropped + evicted;
+      const result = await client.query(
+        `INSERT INTO approval_timeline_tail
+           (tenant_id, task_id, entries, next_revision, dropped, capacity, expires_at)
+         VALUES ($1, $2, $3::jsonb, $4, $5, $6, $7)
+         ON CONFLICT (tenant_id, task_id) DO UPDATE
+           SET entries = EXCLUDED.entries,
+               next_revision = EXCLUDED.next_revision,
+               dropped = EXCLUDED.dropped,
+               capacity = EXCLUDED.capacity,
+               expires_at = EXCLUDED.expires_at
+         RETURNING tenant_id, task_id, entries, next_revision, dropped, capacity, expires_at`,
+        [tenant, input.taskId, JSON.stringify(entries), revision + 1, dropped, capacity, expiresAt]
+      );
+      await client.query("COMMIT");
+      return { status: "applied", tail: toTail2(result.rows[0]) };
+    } catch (caught) {
+      await client.query("ROLLBACK");
+      throw caught;
+    } finally {
+      client.release();
+    }
+  }
   async read(tenant, taskId) {
     const result = await this.pool.query(
       `SELECT tenant_id, task_id, entries, next_revision, dropped, capacity, expires_at
@@ -1919,6 +2341,19 @@ var PostgresApprovalTimelineStore = class {
     return row === void 0 ? void 0 : toTail2(row);
   }
 };
+function pendingObservation(entries) {
+  let pending;
+  for (const entry of entries) {
+    if (entry.event.type === "approval_requested") {
+      pending = entry;
+      continue;
+    }
+    if (pending !== void 0 && (pending.event.approvalId === void 0 || pending.event.approvalId === entry.event.approvalId)) {
+      pending = void 0;
+    }
+  }
+  return pending;
+}
 var SELECT_COLUMNS4 = [
   "tenant_id",
   "device_id",
@@ -1965,7 +2400,7 @@ var PostgresAgentEgressStore = class {
     const inserted = await this.pool.query(
       `INSERT INTO agent_egress_event (${SELECT_COLUMNS4})
        VALUES ($1, $2, $3::uuid, $4, $5, $6, $7, $8::bigint, $9::jsonb, $10, $11::integer, $12::uuid, $13)
-       ON CONFLICT (tenant_id, device_id, event_id) DO NOTHING
+       ON CONFLICT (tenant_id, device_id, agent_id, agent_profile_revision, event_id) DO NOTHING
        RETURNING ${SELECT_COLUMNS4}`,
       [
         tenant,
@@ -1985,16 +2420,18 @@ var PostgresAgentEgressStore = class {
     );
     const row = inserted.rows[0];
     if (row !== void 0) return { record: toRecord2(row), created: true };
-    const existing = await this.get(tenant, input.deviceId, payload.eventId);
+    const existing = await this.get(tenant, input.deviceId, payload.agentRef, payload.eventId);
     if (existing === void 0) throw new Error(`Agent egress ${payload.eventId} vanished during first-write record.`);
     return { record: existing, created: false };
   }
-  async get(tenant, deviceId, eventId) {
+  async get(tenant, deviceId, agentRef, eventId) {
     const result = await this.pool.query(
       `SELECT ${SELECT_COLUMNS4}
          FROM agent_egress_event
-        WHERE tenant_id = $1 AND device_id = $2 AND event_id = $3::uuid`,
-      [tenant, deviceId, eventId]
+        WHERE tenant_id = $1 AND device_id = $2
+          AND agent_id = $3 AND agent_profile_revision = $4
+          AND event_id = $5::uuid`,
+      [tenant, deviceId, agentRef.agentId, agentRef.profileRevision, eventId]
     );
     const row = result.rows[0];
     return row === void 0 ? void 0 : toRecord2(row);
@@ -2151,7 +2588,7 @@ var PostgresAgentMemoryProjectionStore = class {
         }
       });
     } catch (cause) {
-      await rollback2(client);
+      await rollback3(client);
       throw cause;
     } finally {
       client.release();
@@ -2188,7 +2625,7 @@ var PostgresAgentMemoryProjectionStore = class {
       await client.query("COMMIT");
       return AgentMemoryProjectionEraseResultSchema.parse({ nextWriterEpoch });
     } catch (cause) {
-      await rollback2(client);
+      await rollback3(client);
       throw cause;
     } finally {
       client.release();
@@ -2325,7 +2762,7 @@ function toBase64(bytes) {
 function toBase64Url(bytes) {
   return toBase64(bytes).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
 }
-async function rollback2(client) {
+async function rollback3(client) {
   try {
     await client.query("ROLLBACK");
   } catch {
@@ -2384,11 +2821,16 @@ var PostgresDeviceAssertionReplayAuthority = class {
 // src/stores/index.ts
 function createPostgresCloudStores(options) {
   const { pool, clock, crypto } = options;
+  const devices = new PostgresDeviceDirectory(pool, clock);
+  const pairing = new PostgresPairingCodeStore(pool, clock);
   return {
     activity: new PostgresActivityStore(pool, clock),
     approvals: new PostgresApprovalTimelineStore(pool, clock),
-    devices: new PostgresDeviceDirectory(pool, clock),
-    pairingCodes: new PostgresPairingCodeStore(pool, clock),
+    devices,
+    // One durable code authority, projected into issuance and enrollment ports
+    // so consumers cannot reopen the old redeem-then-register sequence.
+    pairingCodes: { issue: pairing.issue.bind(pairing) },
+    pairing: { redeemAndRegister: pairing.redeemAndRegister.bind(pairing) },
     nonces: new PostgresNonceStore(pool, clock, crypto),
     dedup: new PostgresInboundDedupStore(pool),
     tasks: new PostgresTaskAttemptStore(pool, clock),
@@ -3677,7 +4119,7 @@ function toReceipt4(tenant, row) {
     recordedAt: row.recorded_at.toISOString()
   };
 }
-function sameBinding(receipt, input) {
+function sameBinding2(receipt, input) {
   return receipt.operation === input.operation && receipt.resource === input.resource && receipt.bodySha256 === input.proofBodySha256 && receipt.bodySize === input.proofBodySize;
 }
 function bodyColumns2(body) {
@@ -3716,7 +4158,7 @@ var PostgresTruthCommitter = class {
       ]);
       const replay = await this.#readReceipt(client, tenant, input.deviceId, input.requestId);
       if (replay !== void 0) {
-        if (!sameBinding(replay, input)) {
+        if (!sameBinding2(replay, input)) {
           throw new TruthCommitError(
             "proof_request_conflict",
             `Request ${input.requestId} was already used with a different binding.`
@@ -4779,6 +5221,10 @@ var PostgresCloudCleanup = class {
          ), receipts AS (
            DELETE FROM device_request_receipts
             WHERE tenant_id = $1 AND recorded_at < $5::timestamptz
+              -- Pairing completion is an immutable enrollment authority, not
+              -- a TTL-bound request receipt. Removing it would turn an exact
+              -- bearer-code retry into a new/failed enrollment after cleanup.
+              AND key NOT LIKE 'pairing-completion:v1:%'
            RETURNING 1
          ), presence AS (
            DELETE FROM device_presence
@@ -5309,6 +5755,7 @@ var TENANT_ERASURE_TABLES = [
   "agent_egress_event",
   "device_request_receipts",
   "proof_request_receipt",
+  "agent_message_admission",
   "task",
   "device_presence",
   "device_assertion_replay",