@byok-sdk/cloud-dataplane 0.5.0 → 0.6.0

package/dist/index.js

@@ -1,9 +1,9 @@
 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 { ByokCoreError, assertCanonicalTimestamp, contentHash, isContentHash, tenantObjectKey, objectKeyPrefix, CoreConflictError, isLegalBoardTransition, checkSkillPackManifest, checkSkillPackEntry, SKILL_PACK_ENTRY_PATH, tenantId, SKILL_PACK_MANIFEST_SCHEMA_ID } from '@byok-sdk/core';
+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';
-import { createHash } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import { readdir, readFile } from 'fs/promises';
 import { join } from 'path';
 import { fileURLToPath } from 'url';
@@ -596,7 +596,7 @@ var R2ObjectMaintenanceStore = class {
         `A ListObjectsV2 page limit of ${String(limit)} is not a whole number in [1, 1000].`
       );
     }
-    const prefix = `${tenant}/sha256/`;
+    const prefix = tenantObjectKey(tenant, LIST_PREFIX_HASH, this.#keyPrefix).slice(0, -LIST_HASH_HEX_LENGTH);
     const url = new URL(`${this.#origin}/${this.#bucket}`);
     url.searchParams.set("list-type", "2");
     url.searchParams.set("prefix", prefix);
@@ -780,6 +780,8 @@ function parseListObjectsV2(xml, prefix, attempts) {
   return { objects, nextContinuationToken };
 }
 var HASH_KEY_SUFFIX = /^[0-9a-f]{64}$/;
+var LIST_HASH_HEX_LENGTH = 64;
+var LIST_PREFIX_HASH = contentHash(`sha256:${"0".repeat(LIST_HASH_HEX_LENGTH)}`);
 function asRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
 }
@@ -791,8 +793,6 @@ function requiredText(record, field, attempts) {
     attempts
   );
 }
-
-// src/stores/devices.ts
 function toRecord(row) {
   return {
     tenantId: row.tenant_id,
@@ -808,8 +808,10 @@ function toRecord(row) {
 var SELECT_COLUMNS = "tenant_id, device_id, product_id, device_name, device_public_key, proof_key_id, proof_key_epoch, revoked";
 var PostgresDeviceDirectory = class {
   #pool;
-  constructor(pool) {
+  #clock;
+  constructor(pool, clock) {
     this.#pool = pool;
+    this.#clock = clock;
   }
   async register(tenant, input) {
     const result = await this.#pool.query(
@@ -859,6 +861,73 @@ var PostgresDeviceDirectory = class {
     );
     return result.rows.map(toRecord);
   }
+  async readiness(tenant, _presence) {
+    const result = await this.#pool.query(
+      `SELECT
+         d.device_id,
+         d.product_id,
+         d.device_name,
+         d.revoked,
+         CASE WHEN NOT d.revoked THEN p.level END AS presence_level,
+         CASE WHEN NOT d.revoked THEN p.detail END AS presence_detail,
+         CASE WHEN NOT d.revoked THEN p.configured_toolsets END AS presence_configured_toolsets,
+         CASE WHEN NOT d.revoked THEN p.client_version END AS presence_client_version,
+         CASE WHEN NOT d.revoked THEN p.protocol_versions END AS presence_protocol_versions,
+         CASE WHEN NOT d.revoked THEN p.runtimes END AS presence_runtimes,
+         CASE WHEN NOT d.revoked THEN p.observed_at END AS presence_observed_at,
+         CASE WHEN NOT d.revoked THEN p.expires_at END AS presence_expires_at,
+         (COUNT(*) FILTER (WHERE NOT d.revoked) OVER ())::int AS active_paired_device_count,
+         (COUNT(*) FILTER (WHERE d.revoked) OVER ())::int AS revoked_device_count,
+         (COUNT(*) FILTER (WHERE NOT d.revoked AND p.device_id IS NOT NULL) OVER ())::int AS observed_presence_count,
+         (COUNT(*) FILTER (WHERE NOT d.revoked AND p.level = 'online') OVER ())::int AS observed_online_count,
+         (COUNT(*) FILTER (WHERE NOT d.revoked AND p.level = 'thinking') OVER ())::int AS observed_thinking_count,
+         (COUNT(*) FILTER (WHERE NOT d.revoked AND p.level = 'working') OVER ())::int AS observed_working_count,
+         (COUNT(*) FILTER (WHERE NOT d.revoked AND p.level = 'error') OVER ())::int AS observed_error_count,
+         (COUNT(*) FILTER (WHERE NOT d.revoked AND p.level = 'offline') OVER ())::int AS observed_offline_count
+       FROM device d
+       LEFT JOIN device_presence p
+         ON p.tenant_id = d.tenant_id
+        AND p.device_id = d.device_id
+        AND p.expires_at > $2
+       WHERE d.tenant_id = $1
+       ORDER BY d.device_id`,
+      [tenant, this.#clock?.now().toISOString() ?? (/* @__PURE__ */ new Date()).toISOString()]
+    );
+    const row = result.rows[0];
+    const count = (value) => Number(value);
+    const devices = result.rows.map((device) => ({
+      deviceId: device.device_id,
+      productId: device.product_id,
+      deviceName: device.device_name,
+      revoked: device.revoked,
+      ...device.presence_level === null ? {} : {
+        presence: {
+          level: device.presence_level,
+          ...device.presence_detail === null ? {} : { detail: device.presence_detail },
+          ...device.presence_configured_toolsets === null ? {} : { configuredToolsets: Object.freeze([...device.presence_configured_toolsets]) },
+          ...device.presence_client_version === null ? {} : { clientVersion: device.presence_client_version },
+          ...device.presence_protocol_versions === null ? {} : { protocolVersions: Object.freeze([...device.presence_protocol_versions]) },
+          ...device.presence_runtimes === null ? {} : { runtimes: Object.freeze(device.presence_runtimes.map((runtime) => Object.freeze({ ...runtime }))) },
+          observedAt: device.presence_observed_at,
+          expiresAt: device.presence_expires_at
+        }
+      }
+    }));
+    return {
+      tenantId: tenant,
+      activePairedDeviceCount: count(row?.active_paired_device_count ?? 0),
+      revokedDeviceCount: count(row?.revoked_device_count ?? 0),
+      observedPresenceCount: count(row?.observed_presence_count ?? 0),
+      observedPresenceByLevel: {
+        online: count(row?.observed_online_count ?? 0),
+        thinking: count(row?.observed_thinking_count ?? 0),
+        working: count(row?.observed_working_count ?? 0),
+        error: count(row?.observed_error_count ?? 0),
+        offline: count(row?.observed_offline_count ?? 0)
+      },
+      devices
+    };
+  }
   async resolveByDeviceId(deviceId) {
     const result = await this.#pool.query(
       `SELECT ${SELECT_COLUMNS} FROM device WHERE device_id = $1`,
@@ -1082,8 +1151,8 @@ var PostgresProofRequestReceiptStore = class {
 };
 
 // src/stores/task-attempts.ts
-var SELECT_COLUMNS4 = "tenant_id, task_id, device_id, owner_device_id, status, updated_at";
-function toAttempt(row) {
+var TASK_SELECT_COLUMNS = "tenant_id, task_id, device_id, owner_device_id, status, cancel_requested_at, cancel_reason, cancel_message_id, updated_at";
+function taskRowToAttempt(row) {
   return {
     tenantId: row.tenant_id,
     taskId: row.task_id,
@@ -1094,6 +1163,12 @@ function toAttempt(row) {
     // former.
     ...row.owner_device_id === null ? {} : { ownerDeviceId: row.owner_device_id },
     status: row.status,
+    ...row.cancel_requested_at === null ? {} : {
+      cancellation: {
+        requestedAt: row.cancel_requested_at.toISOString(),
+        ...row.cancel_reason === null ? {} : { reason: row.cancel_reason }
+      }
+    },
     updatedAt: row.updated_at.toISOString()
   };
 }
@@ -1109,33 +1184,42 @@ var PostgresTaskAttemptStore = class {
       `INSERT INTO task (tenant_id, task_id, device_id, owner_device_id, status, updated_at)
        VALUES ($1, $2, $3, NULL, 'offered', $4)
        ON CONFLICT (tenant_id, task_id) DO NOTHING
-       RETURNING ${SELECT_COLUMNS4}`,
+       RETURNING ${TASK_SELECT_COLUMNS}`,
       [tenant, input.taskId, input.deviceId, this.#now()]
     );
     const created = inserted.rows[0];
-    if (created !== void 0) return toAttempt(created);
+    if (created !== void 0) return taskRowToAttempt(created);
     const existing = await this.get(tenant, input.taskId);
     if (existing === void 0) throw new Error(`task ${input.taskId} vanished during open`);
     return existing;
   }
   async get(tenant, taskId) {
     const result = await this.#pool.query(
-      `SELECT ${SELECT_COLUMNS4} FROM task WHERE tenant_id = $1 AND task_id = $2`,
+      `SELECT ${TASK_SELECT_COLUMNS} FROM task WHERE tenant_id = $1 AND task_id = $2`,
       [tenant, taskId]
     );
     const row = result.rows[0];
-    return row === void 0 ? void 0 : toAttempt(row);
+    return row === void 0 ? void 0 : taskRowToAttempt(row);
+  }
+  async getMany(tenant, taskIds) {
+    if (taskIds.length === 0) return [];
+    const result = await this.#pool.query(
+      `SELECT ${TASK_SELECT_COLUMNS} FROM task WHERE tenant_id = $1 AND task_id = ANY($2::text[])`,
+      [tenant, [...new Set(taskIds)]]
+    );
+    return result.rows.map(taskRowToAttempt);
   }
   async claim(tenant, input) {
     const claimed = await this.#pool.query(
       `UPDATE task
           SET owner_device_id = $3, status = 'claimed', updated_at = $4
         WHERE tenant_id = $1 AND task_id = $2 AND owner_device_id IS NULL
-      RETURNING ${SELECT_COLUMNS4}`,
+          AND cancel_requested_at IS NULL AND status = 'offered'
+      RETURNING ${TASK_SELECT_COLUMNS}`,
       [tenant, input.taskId, input.deviceId, this.#now()]
     );
     const won = claimed.rows[0];
-    if (won !== void 0) return toAttempt(won);
+    if (won !== void 0) return taskRowToAttempt(won);
     return this.get(tenant, input.taskId);
   }
   async recordStatus(tenant, input) {
@@ -1143,16 +1227,336 @@ var PostgresTaskAttemptStore = class {
       `UPDATE task
           SET status = $3, updated_at = $4
         WHERE tenant_id = $1 AND task_id = $2
-      RETURNING ${SELECT_COLUMNS4}`,
+          AND (
+            (cancel_requested_at IS NULL AND status NOT IN ('complete', 'failed', 'cancelled'))
+            OR (cancel_requested_at IS NOT NULL AND $3 = 'cancelled' AND status <> 'cancelled')
+          )
+      RETURNING ${TASK_SELECT_COLUMNS}`,
       [tenant, input.taskId, input.status, this.#now()]
     );
     const row = result.rows[0];
-    return row === void 0 ? void 0 : toAttempt(row);
+    return row === void 0 ? this.get(tenant, input.taskId) : taskRowToAttempt(row);
   }
   #now() {
     return this.#clock.now().toISOString();
   }
 };
+
+// src/stores/core/mailbox-sequence.ts
+async function allocateMailboxSequence(client, tenant, deviceId, now) {
+  const allocation = await client.query(
+    `INSERT INTO device_stream (tenant_id, device_id, next_seq, acked_seq, acked_at)
+     VALUES ($1, $2, 2, 0, $3)
+     ON CONFLICT (tenant_id, device_id) DO UPDATE
+        SET next_seq = device_stream.next_seq + 1
+     RETURNING next_seq - 1 AS seq`,
+    [tenant, deviceId, now]
+  );
+  return Number(allocation.rows[0].seq);
+}
+
+// src/stores/core/mailbox.ts
+var DEFAULT_READ_LIMIT = 50;
+var OUTBOX_COLUMNS = "tenant_id, device_id, seq, message_id, body, body_hash, byte_size, state, appended_at";
+function toMailboxMessage(row) {
+  return {
+    tenantId: row.tenant_id,
+    deviceId: row.device_id,
+    // `seq` is bigint in the column and `number` on the port, because it is the
+    // envelope `seq` on the wire. The column is wide so the counter cannot wrap
+    // into a redelivery bug; the narrowing happens once, here.
+    seq: Number(row.seq),
+    messageId: row.message_id,
+    body: row.body,
+    bodyHash: row.body_hash,
+    byteSize: row.byte_size,
+    state: row.state,
+    appendedAt: row.appended_at
+  };
+}
+var PostgresMailboxStore = class {
+  #pool;
+  #clock;
+  constructor(pool, clock) {
+    this.#pool = pool;
+    this.#clock = clock;
+  }
+  async append(tenant, input) {
+    this.#requireDeviceId(input.deviceId);
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      const existing = await client.query(
+        `SELECT ${OUTBOX_COLUMNS} FROM outbox
+          WHERE tenant_id = $1 AND device_id = $2 AND message_id = $3`,
+        [tenant, input.deviceId, input.messageId]
+      );
+      const replayed = existing.rows[0];
+      if (replayed !== void 0) {
+        await client.query("COMMIT");
+        return toMailboxMessage(replayed);
+      }
+      const seq = await allocateMailboxSequence(client, tenant, input.deviceId, this.#now());
+      const serializedExisting = await client.query(
+        `SELECT ${OUTBOX_COLUMNS} FROM outbox
+          WHERE tenant_id = $1 AND device_id = $2 AND message_id = $3`,
+        [tenant, input.deviceId, input.messageId]
+      );
+      const winnerAfterLock = serializedExisting.rows[0];
+      if (winnerAfterLock !== void 0) {
+        await client.query("ROLLBACK");
+        return toMailboxMessage(winnerAfterLock);
+      }
+      const materialized = await input.materialize(seq);
+      const now = this.#now();
+      const inserted = await client.query(
+        `INSERT INTO outbox (${OUTBOX_COLUMNS})
+         VALUES ($1, $2, $3::bigint, $4, $5, $6, $7::bigint, 'pending', $8)
+         ON CONFLICT (tenant_id, device_id, message_id) DO NOTHING
+         RETURNING ${OUTBOX_COLUMNS}`,
+        [
+          tenant,
+          input.deviceId,
+          seq,
+          input.messageId,
+          materialized.body,
+          materialized.bodyHash,
+          materialized.byteSize,
+          now
+        ]
+      );
+      const row = inserted.rows[0];
+      if (row !== void 0) {
+        await client.query("COMMIT");
+        return toMailboxMessage(row);
+      }
+      const winner = await client.query(
+        `SELECT ${OUTBOX_COLUMNS} FROM outbox
+          WHERE tenant_id = $1 AND device_id = $2 AND message_id = $3`,
+        [tenant, input.deviceId, input.messageId]
+      );
+      await client.query("ROLLBACK");
+      const won = winner.rows[0];
+      if (won === void 0) {
+        throw new ByokCoreError(
+          "mailbox_message_not_found",
+          `Message ${input.messageId} vanished during an idempotent append.`
+        );
+      }
+      return toMailboxMessage(won);
+    } catch (cause) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      throw cause;
+    } finally {
+      client.release();
+    }
+  }
+  async readAfter(tenant, query) {
+    const limit = query.limit ?? DEFAULT_READ_LIMIT;
+    const result = await this.#pool.query(
+      `SELECT ${OUTBOX_COLUMNS} FROM outbox
+        WHERE tenant_id = $1 AND device_id = $2 AND state = 'pending' AND seq > $3::bigint
+        ORDER BY seq
+        LIMIT $4`,
+      [tenant, query.deviceId, query.afterSeq, limit + 1]
+    );
+    const page = result.rows.slice(0, limit).map(toMailboxMessage);
+    return {
+      messages: page,
+      // 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
+    };
+  }
+  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)
+         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
+       ), marked AS (
+         UPDATE outbox
+            SET state = 'acked'
+          WHERE tenant_id = $1 AND device_id = $2 AND state = 'pending'
+            AND seq <= (SELECT acked_seq FROM moved)
+         RETURNING 1
+       )
+       SELECT acked_seq, acked_at FROM moved`,
+      [tenant, input.deviceId, input.ackedSeq, now]
+    );
+    const row = moved.rows[0];
+    if (row !== void 0) {
+      return {
+        tenantId: tenant,
+        deviceId: input.deviceId,
+        ackedSeq: Number(row.acked_seq),
+        updatedAt: row.acked_at ?? now
+      };
+    }
+    const current = await this.readCursor(tenant, input.deviceId);
+    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()
+    );
+  }
+  async readCursor(tenant, deviceId) {
+    const result = await this.#pool.query(
+      `SELECT acked_seq, acked_at FROM device_stream
+        WHERE tenant_id = $1 AND device_id = $2`,
+      [tenant, deviceId]
+    );
+    const row = result.rows[0];
+    return {
+      tenantId: tenant,
+      deviceId,
+      ackedSeq: row === void 0 ? 0 : Number(row.acked_seq),
+      updatedAt: row?.acked_at ?? this.#now()
+    };
+  }
+  async collectRetired(tenant, input) {
+    assertCanonicalTimestamp(input.ackedBefore, "ackedBefore");
+    assertCanonicalTimestamp(input.expireUnackedBefore, "expireUnackedBefore");
+    const swept = await this.#pool.query(
+      `WITH deleted AS (
+         DELETE FROM outbox
+          WHERE tenant_id = $1
+            AND ($2::text IS NULL OR device_id = $2::text)
+            AND state = 'acked'
+            AND appended_at < $3
+         RETURNING byte_size
+       ), expired AS (
+         UPDATE outbox
+            SET state = 'expired'
+          WHERE tenant_id = $1
+            AND ($2::text IS NULL OR device_id = $2::text)
+            AND state = 'pending'
+            AND appended_at < $4
+         RETURNING 1
+       )
+       SELECT (SELECT count(*) FROM deleted)                           AS deleted_count,
+              (SELECT count(*) FROM expired)                           AS expired_count,
+              (SELECT COALESCE(SUM(byte_size), 0) FROM deleted)::bigint AS released_bytes`,
+      [tenant, input.deviceId ?? null, input.ackedBefore, input.expireUnackedBefore]
+    );
+    const row = swept.rows[0];
+    return {
+      deletedCount: Number(row.deleted_count),
+      expiredCount: Number(row.expired_count),
+      releasedBytes: row.released_bytes
+    };
+  }
+  /**
+   * The in-memory reference refuses an empty device id rather than opening a
+   * mailbox nothing can address. Kept here so the two compositions answer the
+   * same way; the table itself would happily store the row.
+   */
+  #requireDeviceId(deviceId) {
+    if (deviceId.length === 0) {
+      throw new ByokCoreError("mailbox_message_not_found", "Device id must not be empty.");
+    }
+  }
+  #now() {
+    return this.#clock.now().toISOString();
+  }
+};
+
+// src/stores/task-cancellations.ts
+var PostgresTaskCancellationStore = class {
+  #pool;
+  #clock;
+  constructor(pool, clock) {
+    this.#pool = pool;
+    this.#clock = clock;
+  }
+  async request(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 current = selected.rows[0];
+      if (current === void 0) {
+        await client.query("ROLLBACK");
+        return void 0;
+      }
+      if (current.cancel_requested_at === null && (current.status === "complete" || current.status === "failed" || current.status === "cancelled")) {
+        await client.query("COMMIT");
+        return { attempt: taskRowToAttempt(current) };
+      }
+      if (current.cancel_message_id !== null) {
+        const replayed = await client.query(
+          `SELECT ${OUTBOX_COLUMNS} FROM outbox
+            WHERE tenant_id = $1 AND device_id = $2 AND message_id = $3`,
+          [tenant, current.device_id, current.cancel_message_id]
+        );
+        const message = replayed.rows[0];
+        if (message === void 0) {
+          if (current.status === "cancelled") {
+            await client.query("COMMIT");
+            return { attempt: taskRowToAttempt(current) };
+          }
+          throw new Error(`Cancellation delivery ${current.cancel_message_id} is missing for task ${input.taskId}`);
+        }
+        await client.query("COMMIT");
+        return { attempt: taskRowToAttempt(current), message: toMailboxMessage(message) };
+      }
+      const now = this.#clock.now().toISOString();
+      const messageId = input.proposedMessageId;
+      const seq = await allocateMailboxSequence(client, tenant, current.device_id, now);
+      const materialized = await input.materialize(seq, messageId);
+      const insertedMessage = await client.query(
+        `INSERT INTO outbox (${OUTBOX_COLUMNS})
+         VALUES ($1, $2, $3::bigint, $4, $5, $6, $7::bigint, 'pending', $8)
+         RETURNING ${OUTBOX_COLUMNS}`,
+        [
+          tenant,
+          current.device_id,
+          seq,
+          messageId,
+          materialized.body,
+          materialized.bodyHash,
+          materialized.byteSize,
+          now
+        ]
+      );
+      const updated = await client.query(
+        `UPDATE task
+            SET status = CASE WHEN owner_device_id IS NULL THEN 'cancelled' ELSE 'cancel_requested' END,
+                cancel_requested_at = $3,
+                cancel_reason = $4,
+                cancel_message_id = $5,
+                updated_at = $3
+          WHERE tenant_id = $1 AND task_id = $2
+        RETURNING ${TASK_SELECT_COLUMNS}`,
+        [tenant, input.taskId, now, input.reason ?? null, messageId]
+      );
+      await client.query("COMMIT");
+      return {
+        attempt: taskRowToAttempt(updated.rows[0]),
+        message: toMailboxMessage(insertedMessage.rows[0])
+      };
+    } catch (cause) {
+      await client.query("ROLLBACK").catch(() => {
+      });
+      throw cause;
+    } finally {
+      client.release();
+    }
+  }
+};
 function toTail(row) {
   const entries = parseTimelineEvents(row.entries);
   const cursor = activityCursor(entries);
@@ -1442,11 +1846,12 @@ function createPostgresCloudStores(options) {
   return {
     activity: new PostgresActivityStore(pool, clock),
     approvals: new PostgresApprovalTimelineStore(pool, clock),
-    devices: new PostgresDeviceDirectory(pool),
+    devices: new PostgresDeviceDirectory(pool, clock),
     pairingCodes: new PostgresPairingCodeStore(pool, clock),
     nonces: new PostgresNonceStore(pool, clock, crypto),
     dedup: new PostgresInboundDedupStore(pool),
     tasks: new PostgresTaskAttemptStore(pool, clock),
+    cancellations: new PostgresTaskCancellationStore(pool, clock),
     receipts: new PostgresRequestReceiptStore(pool, clock),
     proofReceipts: new PostgresProofRequestReceiptStore(pool, clock),
     // A second `PostgresObjectStore` instance, not a shared one: it is a
@@ -1460,7 +1865,7 @@ function createPostgresCloudStores(options) {
     rateLimiter: new AllowAllRateLimiter()
   };
 }
-var PRESENCE_COLUMNS = "tenant_id, device_id, level, detail, configured_toolsets, observed_at, expires_at";
+var PRESENCE_COLUMNS = "tenant_id, device_id, level, detail, configured_toolsets, client_version, protocol_versions, runtimes, observed_at, expires_at";
 function toHint(row) {
   return {
     tenantId: row.tenant_id,
@@ -1468,6 +1873,19 @@ function toHint(row) {
     level: row.level,
     ...row.detail === null ? {} : { detail: row.detail },
     ...row.configured_toolsets === null ? {} : { configuredToolsets: Object.freeze([...row.configured_toolsets]) },
+    ...row.client_version === null ? {} : { clientVersion: row.client_version },
+    ...row.protocol_versions === null ? {} : { protocolVersions: Object.freeze([...row.protocol_versions]) },
+    ...row.runtimes === null ? {} : {
+      runtimes: Object.freeze(
+        row.runtimes.map(
+          (runtime) => Object.freeze({
+            id: runtime.id,
+            ...runtime.version === void 0 ? {} : { version: runtime.version },
+            ...runtime.authPresent === void 0 ? {} : { authPresent: runtime.authPresent }
+          })
+        )
+      )
+    },
     observedAt: row.observed_at,
     expiresAt: row.expires_at
   };
@@ -1503,15 +1921,18 @@ var PostgresPresenceStore = class {
     const allowedBefore = new Date(now.getTime() - input.minimumIntervalMs).toISOString();
     const result = await this.#pool.query(
       `INSERT INTO device_presence (${PRESENCE_COLUMNS})
-       VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7)
+       VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7::jsonb, $8::jsonb, $9, $10)
        ON CONFLICT (tenant_id, device_id) DO UPDATE
           SET level       = EXCLUDED.level,
               detail      = EXCLUDED.detail,
               configured_toolsets = EXCLUDED.configured_toolsets,
+              client_version = EXCLUDED.client_version,
+              protocol_versions = EXCLUDED.protocol_versions,
+              runtimes    = EXCLUDED.runtimes,
               observed_at = EXCLUDED.observed_at,
               expires_at  = EXCLUDED.expires_at
         WHERE device_presence.expires_at <= EXCLUDED.observed_at
-           OR device_presence.observed_at <= $8
+           OR device_presence.observed_at <= $11
        RETURNING ${PRESENCE_COLUMNS}`,
       [
         tenant,
@@ -1519,6 +1940,9 @@ var PostgresPresenceStore = class {
         input.level,
         input.detail ?? null,
         input.configuredToolsets === void 0 ? null : JSON.stringify(input.configuredToolsets),
+        input.clientVersion ?? null,
+        input.protocolVersions === void 0 ? null : JSON.stringify(input.protocolVersions),
+        input.runtimes === void 0 ? null : JSON.stringify(input.runtimes),
         observedAt,
         new Date(now.getTime() + input.ttlMs).toISOString(),
         allowedBefore
@@ -1748,266 +2172,39 @@ var PostgresBoardStore = class {
       throw new CoreConflictError(
         "board_transition_invalid",
         `${input.expectedStatus} to ${input.status} is not a legal board transition.`,
-        current,
-        this.#now()
-      );
-    }
-    throw this.#statusConflict(input.itemId, current, input.expectedStatus);
-  }
-  /**
-   * One statement, its own transaction, lock released immediately. See the file
-   * header for why this is not a CTE inside the write it feeds.
-   */
-  async #allocateSeq(tenant) {
-    const result = await this.#pool.query(
-      `INSERT INTO tenant_stream (tenant_id, board_seq)
-       VALUES ($1, 1)
-       ON CONFLICT (tenant_id) DO UPDATE SET board_seq = tenant_stream.board_seq + 1
-       RETURNING board_seq`,
-      [tenant]
-    );
-    return result.rows[0].board_seq;
-  }
-  #itemNotFound(itemId) {
-    return new ByokCoreError(
-      "board_item_not_found",
-      `Board item ${itemId} does not exist in this tenant.`
-    );
-  }
-  #statusConflict(itemId, current, expected) {
-    return new CoreConflictError(
-      "board_status_conflict",
-      `Board item ${itemId} is ${current.status}, not ${expected}.`,
-      current,
-      this.#now()
-    );
-  }
-  #now() {
-    return this.#clock.now().toISOString();
-  }
-};
-
-// src/stores/core/mailbox-sequence.ts
-async function allocateMailboxSequence(client, tenant, deviceId, now) {
-  const allocation = await client.query(
-    `INSERT INTO device_stream (tenant_id, device_id, next_seq, acked_seq, acked_at)
-     VALUES ($1, $2, 2, 0, $3)
-     ON CONFLICT (tenant_id, device_id) DO UPDATE
-        SET next_seq = device_stream.next_seq + 1
-     RETURNING next_seq - 1 AS seq`,
-    [tenant, deviceId, now]
-  );
-  return Number(allocation.rows[0].seq);
-}
-
-// src/stores/core/mailbox.ts
-var DEFAULT_READ_LIMIT = 50;
-var OUTBOX_COLUMNS = "tenant_id, device_id, seq, message_id, body, body_hash, byte_size, state, appended_at";
-function toMessage(row) {
-  return {
-    tenantId: row.tenant_id,
-    deviceId: row.device_id,
-    // `seq` is bigint in the column and `number` on the port, because it is the
-    // envelope `seq` on the wire. The column is wide so the counter cannot wrap
-    // into a redelivery bug; the narrowing happens once, here.
-    seq: Number(row.seq),
-    messageId: row.message_id,
-    body: row.body,
-    bodyHash: row.body_hash,
-    byteSize: row.byte_size,
-    state: row.state,
-    appendedAt: row.appended_at
-  };
-}
-var PostgresMailboxStore = class {
-  #pool;
-  #clock;
-  constructor(pool, clock) {
-    this.#pool = pool;
-    this.#clock = clock;
-  }
-  async append(tenant, input) {
-    this.#requireDeviceId(input.deviceId);
-    const client = await this.#pool.connect();
-    try {
-      await client.query("BEGIN");
-      const existing = await client.query(
-        `SELECT ${OUTBOX_COLUMNS} FROM outbox
-          WHERE tenant_id = $1 AND device_id = $2 AND message_id = $3`,
-        [tenant, input.deviceId, input.messageId]
-      );
-      const replayed = existing.rows[0];
-      if (replayed !== void 0) {
-        await client.query("COMMIT");
-        return toMessage(replayed);
-      }
-      const seq = await allocateMailboxSequence(client, tenant, input.deviceId, this.#now());
-      const serializedExisting = await client.query(
-        `SELECT ${OUTBOX_COLUMNS} FROM outbox
-          WHERE tenant_id = $1 AND device_id = $2 AND message_id = $3`,
-        [tenant, input.deviceId, input.messageId]
-      );
-      const winnerAfterLock = serializedExisting.rows[0];
-      if (winnerAfterLock !== void 0) {
-        await client.query("ROLLBACK");
-        return toMessage(winnerAfterLock);
-      }
-      const materialized = await input.materialize(seq);
-      const now = this.#now();
-      const inserted = await client.query(
-        `INSERT INTO outbox (${OUTBOX_COLUMNS})
-         VALUES ($1, $2, $3::bigint, $4, $5, $6, $7::bigint, 'pending', $8)
-         ON CONFLICT (tenant_id, device_id, message_id) DO NOTHING
-         RETURNING ${OUTBOX_COLUMNS}`,
-        [
-          tenant,
-          input.deviceId,
-          seq,
-          input.messageId,
-          materialized.body,
-          materialized.bodyHash,
-          materialized.byteSize,
-          now
-        ]
-      );
-      const row = inserted.rows[0];
-      if (row !== void 0) {
-        await client.query("COMMIT");
-        return toMessage(row);
-      }
-      const winner = await client.query(
-        `SELECT ${OUTBOX_COLUMNS} FROM outbox
-          WHERE tenant_id = $1 AND device_id = $2 AND message_id = $3`,
-        [tenant, input.deviceId, input.messageId]
-      );
-      await client.query("ROLLBACK");
-      const won = winner.rows[0];
-      if (won === void 0) {
-        throw new ByokCoreError(
-          "mailbox_message_not_found",
-          `Message ${input.messageId} vanished during an idempotent append.`
-        );
-      }
-      return toMessage(won);
-    } catch (cause) {
-      await client.query("ROLLBACK").catch(() => {
-      });
-      throw cause;
-    } finally {
-      client.release();
-    }
-  }
-  async readAfter(tenant, query) {
-    const limit = query.limit ?? DEFAULT_READ_LIMIT;
-    const result = await this.#pool.query(
-      `SELECT ${OUTBOX_COLUMNS} FROM outbox
-        WHERE tenant_id = $1 AND device_id = $2 AND state = 'pending' AND seq > $3::bigint
-        ORDER BY seq
-        LIMIT $4`,
-      [tenant, query.deviceId, query.afterSeq, limit + 1]
-    );
-    const page = result.rows.slice(0, limit).map(toMessage);
-    return {
-      messages: page,
-      // 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
-    };
-  }
-  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)
-         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
-       ), marked AS (
-         UPDATE outbox
-            SET state = 'acked'
-          WHERE tenant_id = $1 AND device_id = $2 AND state = 'pending'
-            AND seq <= (SELECT acked_seq FROM moved)
-         RETURNING 1
-       )
-       SELECT acked_seq, acked_at FROM moved`,
-      [tenant, input.deviceId, input.ackedSeq, now]
-    );
-    const row = moved.rows[0];
-    if (row !== void 0) {
-      return {
-        tenantId: tenant,
-        deviceId: input.deviceId,
-        ackedSeq: Number(row.acked_seq),
-        updatedAt: row.acked_at ?? now
-      };
-    }
-    const current = await this.readCursor(tenant, input.deviceId);
-    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()
-    );
+        current,
+        this.#now()
+      );
+    }
+    throw this.#statusConflict(input.itemId, current, input.expectedStatus);
   }
-  async readCursor(tenant, deviceId) {
+  /**
+   * One statement, its own transaction, lock released immediately. See the file
+   * header for why this is not a CTE inside the write it feeds.
+   */
+  async #allocateSeq(tenant) {
     const result = await this.#pool.query(
-      `SELECT acked_seq, acked_at FROM device_stream
-        WHERE tenant_id = $1 AND device_id = $2`,
-      [tenant, deviceId]
+      `INSERT INTO tenant_stream (tenant_id, board_seq)
+       VALUES ($1, 1)
+       ON CONFLICT (tenant_id) DO UPDATE SET board_seq = tenant_stream.board_seq + 1
+       RETURNING board_seq`,
+      [tenant]
     );
-    const row = result.rows[0];
-    return {
-      tenantId: tenant,
-      deviceId,
-      ackedSeq: row === void 0 ? 0 : Number(row.acked_seq),
-      updatedAt: row?.acked_at ?? this.#now()
-    };
+    return result.rows[0].board_seq;
   }
-  async collectRetired(tenant, input) {
-    assertCanonicalTimestamp(input.ackedBefore, "ackedBefore");
-    assertCanonicalTimestamp(input.expireUnackedBefore, "expireUnackedBefore");
-    const swept = await this.#pool.query(
-      `WITH deleted AS (
-         DELETE FROM outbox
-          WHERE tenant_id = $1
-            AND ($2::text IS NULL OR device_id = $2::text)
-            AND state = 'acked'
-            AND appended_at < $3
-         RETURNING byte_size
-       ), expired AS (
-         UPDATE outbox
-            SET state = 'expired'
-          WHERE tenant_id = $1
-            AND ($2::text IS NULL OR device_id = $2::text)
-            AND state = 'pending'
-            AND appended_at < $4
-         RETURNING 1
-       )
-       SELECT (SELECT count(*) FROM deleted)                           AS deleted_count,
-              (SELECT count(*) FROM expired)                           AS expired_count,
-              (SELECT COALESCE(SUM(byte_size), 0) FROM deleted)::bigint AS released_bytes`,
-      [tenant, input.deviceId ?? null, input.ackedBefore, input.expireUnackedBefore]
+  #itemNotFound(itemId) {
+    return new ByokCoreError(
+      "board_item_not_found",
+      `Board item ${itemId} does not exist in this tenant.`
     );
-    const row = swept.rows[0];
-    return {
-      deletedCount: Number(row.deleted_count),
-      expiredCount: Number(row.expired_count),
-      releasedBytes: row.released_bytes
-    };
   }
-  /**
-   * The in-memory reference refuses an empty device id rather than opening a
-   * mailbox nothing can address. Kept here so the two compositions answer the
-   * same way; the table itself would happily store the row.
-   */
-  #requireDeviceId(deviceId) {
-    if (deviceId.length === 0) {
-      throw new ByokCoreError("mailbox_message_not_found", "Device id must not be empty.");
-    }
+  #statusConflict(itemId, current, expected) {
+    return new CoreConflictError(
+      "board_status_conflict",
+      `Board item ${itemId} is ${current.status}, not ${expected}.`,
+      current,
+      this.#now()
+    );
   }
   #now() {
     return this.#clock.now().toISOString();
@@ -3357,6 +3554,11 @@ var PostgresTruthCommitter = class {
     return this.#clock.now().toISOString();
   }
 };
+function migrationsDir() {
+  return fileURLToPath(new URL("./sql", import.meta.url));
+}
+
+// src/migrate.ts
 var MIGRATION_ADVISORY_LOCK_KEY = "4021960801";
 var MIGRATION_FILENAME_PATTERN = /^(\d{4})[_-].+\.sql$/;
 var LEDGER_DDL = `
@@ -3365,6 +3567,28 @@ CREATE TABLE IF NOT EXISTS byok_schema_migration (
   checksum    text        NOT NULL,
   applied_at  timestamptz NOT NULL
 )`;
+var MIGRATION_LEDGER_TABLE = "byok_schema_migration";
+var LEDGER_READ_SQL = "SELECT version, checksum FROM byok_schema_migration";
+var MigrationStateMismatchError = class extends Error {
+  issues;
+  constructor(issues, options) {
+    const detail = issues.map((issue) => {
+      switch (issue.kind) {
+        case "missing":
+          return `missing ${issue.version}`;
+        case "unexpected":
+          return `unexpected ${issue.version}`;
+        case "checksum_mismatch":
+          return `checksum mismatch ${issue.version}`;
+        case "ledger_missing":
+          return `ledger table missing ${issue.table}`;
+      }
+    }).join("; ");
+    super(`Migration state does not match package files: ${detail}`, options);
+    this.name = "MigrationStateMismatchError";
+    this.issues = Object.freeze([...issues]);
+  }
+};
 var MigrationChecksumMismatchError = class extends Error {
   version;
   expectedChecksum;
@@ -3423,11 +3647,65 @@ async function readMigrationFiles(directory) {
   }
   return files;
 }
+async function readLedgerRows(client) {
+  const result = await client.query(LEDGER_READ_SQL);
+  return result.rows;
+}
 async function readLedger(client) {
-  const result = await client.query(
-    "SELECT version, checksum FROM byok_schema_migration"
-  );
-  return new Map(result.rows.map((row) => [row.version, row.checksum]));
+  const rows = await readLedgerRows(client);
+  return new Map(rows.map((row) => [row.version, row.checksum]));
+}
+function isMissingLedgerTable(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "42P01";
+}
+function compareVersions(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+async function verifyMigrations(pool, directory = migrationsDir()) {
+  const files = await readMigrationFiles(directory);
+  const client = await pool.connect();
+  try {
+    let ledgerRows;
+    try {
+      ledgerRows = await readLedgerRows(client);
+    } catch (error) {
+      if (!isMissingLedgerTable(error)) throw error;
+      throw new MigrationStateMismatchError(
+        [{ kind: "ledger_missing", table: MIGRATION_LEDGER_TABLE }],
+        { cause: error }
+      );
+    }
+    const ledger = new Map(ledgerRows.map((row) => [row.version, row.checksum]));
+    const expectedVersions = new Set(files.map((file) => file.version));
+    const issues = [];
+    for (const file of files) {
+      const actualChecksum = ledger.get(file.version);
+      if (actualChecksum === void 0) {
+        issues.push({
+          kind: "missing",
+          version: file.version,
+          expectedChecksum: file.checksum
+        });
+      } else if (actualChecksum !== file.checksum) {
+        issues.push({
+          kind: "checksum_mismatch",
+          version: file.version,
+          expectedChecksum: file.checksum,
+          actualChecksum
+        });
+      }
+    }
+    const unexpectedRows = ledgerRows.filter((row) => !expectedVersions.has(row.version)).slice().sort((left, right) => compareVersions(left.version, right.version));
+    for (const row of unexpectedRows) {
+      issues.push({ kind: "unexpected", version: row.version, actualChecksum: row.checksum });
+    }
+    if (issues.length > 0) throw new MigrationStateMismatchError(issues);
+    return files.map(({ version, checksum }) => ({ version, checksum }));
+  } finally {
+    client.release();
+  }
 }
 async function migrate(pool, directory) {
   const files = await readMigrationFiles(directory);
@@ -3471,9 +3749,6 @@ async function migrate(pool, directory) {
     client.release();
   }
 }
-function migrationsDir() {
-  return fileURLToPath(new URL("./sql", import.meta.url));
-}
 var DEFAULT_BATCH_SIZE = 100;
 var MAX_BATCH_SIZE = 1e3;
 var ADVISORY_LOCK_NAMESPACE = 1106736963;
@@ -3644,7 +3919,7 @@ var PostgresCloudCleanup = class {
       ]
     );
     return {
-      messages: listed.rows.slice(0, limit).map(toMailboxMessage),
+      messages: listed.rows.slice(0, limit).map(toMailboxMessage2),
       hasMore: listed.rows.length > limit
     };
   }
@@ -3682,7 +3957,7 @@ var PostgresCloudCleanup = class {
               `Replay id ${input.replayMessageId} already binds a different replay delivery.`
             );
           } else {
-            result = toMailboxMessage(existing);
+            result = toMailboxMessage2(existing);
           }
         } else {
           const entitlement = await client.query(
@@ -3707,7 +3982,7 @@ var PostgresCloudCleanup = class {
                 `Replay id ${input.replayMessageId} already binds a different replay delivery.`
               );
             } else {
-              result = toMailboxMessage(winner);
+              result = toMailboxMessage2(winner);
             }
           } else if (capacity === void 0) {
             rejection = new CloudCleanupError(
@@ -3735,7 +4010,7 @@ var PostgresCloudCleanup = class {
                   `Replay id ${input.replayMessageId} already binds a different replay delivery.`
                 );
               } else {
-                result = toMailboxMessage(appendWinner);
+                result = toMailboxMessage2(appendWinner);
               }
             } else {
               const rebound = materializeReplayBody(original, seq);
@@ -3767,7 +4042,7 @@ var PostgresCloudCleanup = class {
                     WHERE tenant_id = $1`,
                   [tenant, rebound.byteSize, this.#now()]
                 );
-                result = toMailboxMessage(inserted.rows[0]);
+                result = toMailboxMessage2(inserted.rows[0]);
               }
             }
           }
@@ -3838,7 +4113,7 @@ var PostgresCloudCleanup = class {
       client.release();
     }
     if (rejection !== void 0) throw rejection;
-    return toMailboxMessage(row);
+    return toMailboxMessage2(row);
   }
   /**
    * Explicit recovery operation: rebuild object accounting from committed
@@ -4372,7 +4647,7 @@ function toCleanupResult(row) {
     ...row.error_message === null ? {} : { errorMessage: row.error_message }
   };
 }
-function toMailboxMessage(row) {
+function toMailboxMessage2(row) {
   return {
     tenantId: tenantId(row.tenant_id),
     deviceId: row.device_id,
@@ -4463,7 +4738,484 @@ function deadLetterMissing(ref) {
     `Expired mailbox row ${ref.deviceId}/${String(ref.seq)} was not found.`
   );
 }
+var DEFAULT_BATCH_SIZE2 = 100;
+var DEFAULT_MAX_PAGES_PER_RUN = 10;
+var DEFAULT_LEASE_MS = 3e4;
+var MAX_BATCH_SIZE2 = 1e3;
+var MAX_PAGES_PER_RUN = 100;
+var MAX_LEASE_MS = 5 * 6e4;
+var TENANT_ERASURE_TABLES = [
+  "object_reference",
+  "object_manifest",
+  "storage_reservation",
+  "storage_usage",
+  "storage_entitlement",
+  "gc_cursor",
+  "cleanup_job",
+  "tenant_retention_policy",
+  "skill_pack_file",
+  "skill_pack",
+  "approval_timeline_tail",
+  "activity_tail",
+  "attested_record",
+  "board_item",
+  "tenant_stream",
+  "outbox",
+  "device_request_receipts",
+  "proof_request_receipt",
+  "task",
+  "device_presence",
+  "device_assertion_replay",
+  "device_stream",
+  "inbound_dedup",
+  "auth_nonce",
+  "pairing_code",
+  "device"
+];
+var TENANT_ERASURE_TABLE_SET = new Set(TENANT_ERASURE_TABLES);
+var TENANT_ERASURE_ERROR_CODES = {
+  tenant_erasure_invalid_input: "tenant_erasure_invalid_input",
+  tenant_erasure_schema_drift: "tenant_erasure_schema_drift",
+  tenant_erasure_object_key_invalid: "tenant_erasure_object_key_invalid",
+  tenant_erasure_storage_failure: "tenant_erasure_storage_failure",
+  tenant_erasure_database_failure: "tenant_erasure_database_failure",
+  tenant_erasure_cas_lost: "tenant_erasure_cas_lost"
+};
+var TenantErasureError = class extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "TenantErasureError";
+    this.code = code;
+  }
+};
+var OPERATION_COLUMNS = [
+  "tenant_id",
+  "operation_id",
+  "state",
+  "revision",
+  "lease_token",
+  "lease_expires_at",
+  "r2_cursor",
+  "r2_complete",
+  "sql_table_index",
+  "r2_objects_deleted",
+  "sql_rows_deleted",
+  "started_at",
+  "updated_at",
+  "completed_at",
+  "last_error_code"
+].join(", ");
+var PostgresTenantErasure = class {
+  #pool;
+  #clock;
+  #objectStorage;
+  #batchSize;
+  #maxPagesPerRun;
+  #leaseMs;
+  constructor(options) {
+    this.#pool = options.pool;
+    this.#clock = options.clock;
+    this.#objectStorage = options.objectStorage;
+    this.#batchSize = assertBoundedWhole(options.batchSize ?? DEFAULT_BATCH_SIZE2, "batchSize", MAX_BATCH_SIZE2);
+    this.#maxPagesPerRun = assertBoundedWhole(
+      options.maxPagesPerRun ?? DEFAULT_MAX_PAGES_PER_RUN,
+      "maxPagesPerRun",
+      MAX_PAGES_PER_RUN
+    );
+    this.#leaseMs = assertBoundedWhole(options.leaseMs ?? DEFAULT_LEASE_MS, "leaseMs", MAX_LEASE_MS);
+  }
+  /** Read a durable operation receipt without advancing it. */
+  async readTenantErasure(tenant, operationId) {
+    assertOperationId(operationId);
+    const row = await this.#readOperation(tenant, operationId);
+    return row === void 0 ? void 0 : toReadback(row);
+  }
+  /**
+   * Advance one bounded operation slice. Calls with a completed id replay its
+   * receipt; another running id for the same tenant gets a typed conflict.
+   */
+  async eraseTenant(tenant, operationId) {
+    assertOperationId(operationId);
+    let existing;
+    try {
+      existing = await this.#readOperation(tenant, operationId);
+    } catch (cause) {
+      throw databaseFailure("reading tenant erasure operation", cause);
+    }
+    if (existing?.state === "completed") return toReadback(existing);
+    await this.#assertSchemaInventory();
+    let row;
+    try {
+      const opened = await this.#openOperation(tenant, operationId);
+      if ("status" in opened) return opened;
+      row = opened;
+    } catch (cause) {
+      throw databaseFailure("opening tenant erasure operation", cause);
+    }
+    if (row.state === "completed") return toReadback(row);
+    const leaseToken = randomUUID();
+    let claimed;
+    try {
+      claimed = await this.#claim(tenant, operationId, row.revision, leaseToken);
+      if (claimed === void 0) return await this.#readConflictOrReceipt(tenant, operationId);
+      for (let page = 0; page < this.#maxPagesPerRun; page += 1) {
+        if (!claimed.r2_complete) {
+          claimed = await this.#eraseR2Page(tenant, claimed, leaseToken);
+          continue;
+        }
+        if (claimed.sql_table_index < TENANT_ERASURE_TABLES.length) {
+          claimed = await this.#eraseSqlPage(tenant, claimed, leaseToken);
+          continue;
+        }
+        claimed = await this.#verifyAndComplete(tenant, claimed, leaseToken);
+        if (claimed.state === "completed") return toReadback(claimed);
+      }
+      return toReadback(await this.#release(tenant, operationId, claimed.revision, leaseToken));
+    } catch (cause) {
+      if (claimed === void 0) throw databaseFailure("claiming tenant erasure operation", cause);
+      const code = cause instanceof TenantErasureError ? cause.code : TENANT_ERASURE_ERROR_CODES.tenant_erasure_database_failure;
+      try {
+        return toReadback(await this.#recordPartial(tenant, operationId, claimed.revision, leaseToken, code));
+      } catch (recordCause) {
+        throw databaseFailure("recording tenant erasure partial outcome", recordCause);
+      }
+    }
+  }
+  async #assertSchemaInventory() {
+    const found = await this.#pool.query(
+      `SELECT t.relname
+         FROM pg_class t
+         JOIN pg_namespace n ON n.oid = t.relnamespace
+        WHERE n.nspname = current_schema()
+          AND t.relkind = 'r'
+          AND t.relname NOT IN ('byok_schema_migration', 'tenant_erasure_operation')
+        ORDER BY t.relname`
+    );
+    const actual = new Set(found.rows.map((row) => row.relname));
+    const missing = TENANT_ERASURE_TABLES.filter((name) => !actual.has(name));
+    const unexpected = [...actual].filter((name) => !TENANT_ERASURE_TABLE_SET.has(name));
+    if (missing.length === 0 && unexpected.length === 0 && actual.size === TENANT_ERASURE_TABLES.length) return;
+    throw new TenantErasureError(
+      "tenant_erasure_schema_drift",
+      `Tenant erasure inventory drift: missing=[${missing.join(",")}], unexpected=[${unexpected.join(",")}].`
+    );
+  }
+  async #openOperation(tenant, operationId) {
+    const now = this.#clock.now();
+    try {
+      await this.#pool.query(
+        `INSERT INTO tenant_erasure_operation (
+           tenant_id, operation_id, state, started_at, updated_at
+         ) VALUES ($1, $2, 'running', $3, $3)
+         ON CONFLICT (tenant_id, operation_id) DO NOTHING`,
+        [tenant, operationId, now]
+      );
+    } catch (cause) {
+      if (postgresCode(cause) !== "23505") throw cause;
+      return this.#conflict(tenant, operationId);
+    }
+    const own = await this.#readOperation(tenant, operationId);
+    if (own !== void 0) return own;
+    return this.#conflict(tenant, operationId);
+  }
+  async #claim(tenant, operationId, revision, leaseToken) {
+    const now = this.#clock.now();
+    const leaseExpiresAt = new Date(now.getTime() + this.#leaseMs);
+    const result = await this.#pool.query(
+      `UPDATE tenant_erasure_operation
+          SET lease_token = $1,
+              lease_expires_at = $2,
+              revision = revision + 1,
+              updated_at = $3,
+              last_error_code = NULL
+        WHERE tenant_id = $4
+          AND operation_id = $5
+          AND state = 'running'
+          AND revision = $6::bigint
+          AND (lease_token IS NULL OR lease_expires_at <= $3)
+      RETURNING ${OPERATION_COLUMNS}`,
+      [leaseToken, leaseExpiresAt, now, tenant, operationId, revision]
+    );
+    return result.rows[0];
+  }
+  async #eraseR2Page(tenant, row, leaseToken) {
+    let page;
+    try {
+      page = await this.#objectStorage.listTenantObjects(
+        tenant,
+        row.r2_cursor ?? void 0,
+        this.#batchSize
+      );
+    } catch (cause) {
+      throw storageFailure("listing the tenant R2 namespace", cause);
+    }
+    for (const object of page.objects) {
+      if (object.hash === void 0) {
+        throw new TenantErasureError(
+          "tenant_erasure_object_key_invalid",
+          "Tenant R2 namespace contains a non-canonical object key; erasure refused before SQL deletion."
+        );
+      }
+      try {
+        await this.#objectStorage.deleteObject(tenant, object.hash);
+      } catch (cause) {
+        throw storageFailure("deleting a tenant R2 object", cause);
+      }
+    }
+    return this.#casUpdate(
+      tenant,
+      row.operation_id,
+      row.revision,
+      leaseToken,
+      `r2_cursor = $1,
+       r2_complete = $2,
+       r2_objects_deleted = r2_objects_deleted + $3::bigint`,
+      [page.nextContinuationToken ?? null, page.nextContinuationToken === void 0, page.objects.length]
+    );
+  }
+  async #eraseSqlPage(tenant, row, leaseToken) {
+    const table = TENANT_ERASURE_TABLES[row.sql_table_index];
+    if (table === void 0) {
+      throw new TenantErasureError("tenant_erasure_cas_lost", "Tenant erasure SQL progress escaped its static inventory.");
+    }
+    let deleted;
+    try {
+      const result = await this.#pool.query(
+        `WITH deleted AS (
+           DELETE FROM ${table}
+            WHERE ctid IN (
+              SELECT ctid FROM ${table}
+               WHERE tenant_id = $1
+               LIMIT $2
+            )
+           RETURNING 1
+         )
+         SELECT count(*)::bigint AS deleted FROM deleted`,
+        [tenant, this.#batchSize]
+      );
+      deleted = result.rows[0].deleted;
+    } catch (cause) {
+      throw databaseFailure(`deleting tenant rows from ${table}`, cause);
+    }
+    const nextTableIndex = deleted < BigInt(this.#batchSize) ? row.sql_table_index + 1 : row.sql_table_index;
+    return this.#casUpdate(
+      tenant,
+      row.operation_id,
+      row.revision,
+      leaseToken,
+      `sql_table_index = $1,
+       sql_rows_deleted = sql_rows_deleted + $2::bigint`,
+      [nextTableIndex, deleted]
+    );
+  }
+  async #verifyAndComplete(tenant, row, leaseToken) {
+    try {
+      const r2 = await this.#objectStorage.listTenantObjects(tenant, void 0, 1);
+      if (r2.objects.length > 0) {
+        return this.#casUpdate(
+          tenant,
+          row.operation_id,
+          row.revision,
+          leaseToken,
+          "r2_cursor = NULL, r2_complete = false",
+          []
+        );
+      }
+    } catch (cause) {
+      throw storageFailure("verifying the tenant R2 namespace is empty", cause);
+    }
+    for (const table of TENANT_ERASURE_TABLES) {
+      let present;
+      try {
+        const result = await this.#pool.query(
+          `SELECT EXISTS (SELECT 1 FROM ${table} WHERE tenant_id = $1) AS present`,
+          [tenant]
+        );
+        present = result.rows[0].present;
+      } catch (cause) {
+        throw databaseFailure(`verifying tenant rows in ${table}`, cause);
+      }
+      if (present) {
+        return this.#casUpdate(
+          tenant,
+          row.operation_id,
+          row.revision,
+          leaseToken,
+          "sql_table_index = 0",
+          []
+        );
+      }
+    }
+    const now = this.#clock.now();
+    return this.#casUpdate(
+      tenant,
+      row.operation_id,
+      row.revision,
+      leaseToken,
+      `state = 'completed',
+       completed_at = $1,
+       lease_token = NULL,
+       lease_expires_at = NULL,
+       last_error_code = NULL`,
+      [now],
+      false
+    );
+  }
+  async #release(tenant, operationId, revision, leaseToken) {
+    return this.#casUpdate(
+      tenant,
+      operationId,
+      revision,
+      leaseToken,
+      "lease_token = NULL, lease_expires_at = NULL",
+      [],
+      false
+    );
+  }
+  async #recordPartial(tenant, operationId, revision, leaseToken, errorCode) {
+    return this.#casUpdate(
+      tenant,
+      operationId,
+      revision,
+      leaseToken,
+      `lease_token = NULL,
+       lease_expires_at = NULL,
+       last_error_code = $1`,
+      [errorCode],
+      false
+    );
+  }
+  async #casUpdate(tenant, operationId, revision, leaseToken, setClause, setValues, refreshLease = true) {
+    const now = this.#clock.now();
+    const values = [...setValues];
+    let refreshClause = "";
+    if (refreshLease) {
+      values.push(new Date(now.getTime() + this.#leaseMs));
+      refreshClause = `, lease_expires_at = $${String(values.length)}`;
+    }
+    values.push(now, tenant, operationId, revision, leaseToken);
+    const updatedAtIndex = values.length - 4;
+    const tenantIndex = values.length - 3;
+    const operationIndex = values.length - 2;
+    const revisionIndex = values.length - 1;
+    const leaseIndex = values.length;
+    const result = await this.#pool.query(
+      `UPDATE tenant_erasure_operation
+          SET ${setClause}${refreshClause},
+              revision = revision + 1,
+              updated_at = $${String(updatedAtIndex)}
+        WHERE tenant_id = $${String(tenantIndex)}
+          AND operation_id = $${String(operationIndex)}
+          AND state = 'running'
+          AND revision = $${String(revisionIndex)}::bigint
+          AND lease_token = $${String(leaseIndex)}
+      RETURNING ${OPERATION_COLUMNS}`,
+      values
+    );
+    const row = result.rows[0];
+    if (row !== void 0) return row;
+    throw new TenantErasureError(
+      "tenant_erasure_cas_lost",
+      "Tenant erasure operation no longer owns its durable progress lease."
+    );
+  }
+  async #readOperation(tenant, operationId) {
+    const result = await this.#pool.query(
+      `SELECT ${OPERATION_COLUMNS}
+         FROM tenant_erasure_operation
+        WHERE tenant_id = $1 AND operation_id = $2`,
+      [tenant, operationId]
+    );
+    return result.rows[0];
+  }
+  async #readConflictOrReceipt(tenant, operationId) {
+    const own = await this.#readOperation(tenant, operationId);
+    if (own?.state === "completed") return toReadback(own);
+    if (own !== void 0 && own.lease_token !== null && own.lease_expires_at !== null && own.lease_expires_at > this.#clock.now()) {
+      return { status: "conflict", tenantId: tenant, operationId, activeOperationId: own.operation_id };
+    }
+    if (own !== void 0) return toReadback(own);
+    return this.#conflict(tenant, operationId);
+  }
+  async #conflict(tenant, operationId) {
+    const active = await this.#pool.query(
+      `SELECT operation_id
+         FROM tenant_erasure_operation
+        WHERE tenant_id = $1 AND state = 'running'`,
+      [tenant]
+    );
+    const winner = active.rows[0];
+    if (winner === void 0) {
+      throw new TenantErasureError(
+        "tenant_erasure_cas_lost",
+        "Tenant erasure operation changed while acquiring its receipt; retry with the same operation id."
+      );
+    }
+    return { status: "conflict", tenantId: tenant, operationId, activeOperationId: winner.operation_id };
+  }
+};
+function createPostgresTenantErasure(options) {
+  return new PostgresTenantErasure({
+    pool: options.pool,
+    clock: options.clock,
+    objectStorage: new R2ObjectMaintenanceStore(options.objectStorage),
+    ...options.batchSize === void 0 ? {} : { batchSize: options.batchSize },
+    ...options.maxPagesPerRun === void 0 ? {} : { maxPagesPerRun: options.maxPagesPerRun },
+    ...options.leaseMs === void 0 ? {} : { leaseMs: options.leaseMs }
+  });
+}
+function toReadback(row) {
+  const status = row.state === "completed" ? "completed" : row.last_error_code === null ? "outstanding" : "partial";
+  return {
+    status,
+    tenantId: tenantId(row.tenant_id),
+    operationId: row.operation_id,
+    startedAt: row.started_at.toISOString(),
+    updatedAt: row.updated_at.toISOString(),
+    ...row.completed_at === null ? {} : { completedAt: row.completed_at.toISOString() },
+    r2Complete: row.r2_complete,
+    sqlTableIndex: row.sql_table_index,
+    r2ObjectsDeleted: row.r2_objects_deleted,
+    sqlRowsDeleted: row.sql_rows_deleted,
+    ...row.last_error_code === null ? {} : { errorCode: row.last_error_code }
+  };
+}
+function assertOperationId(operationId) {
+  if (operationId.length === 0 || operationId.length > 256 || operationId.trim() !== operationId) {
+    throw new TenantErasureError(
+      "tenant_erasure_invalid_input",
+      "operationId must be a non-empty, unpadded string no longer than 256 characters."
+    );
+  }
+}
+function assertBoundedWhole(value, field, max) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > max) {
+    throw new TenantErasureError(
+      "tenant_erasure_invalid_input",
+      `${field} must be a whole number in [1, ${String(max)}].`
+    );
+  }
+  return value;
+}
+function postgresCode(cause) {
+  return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string" ? cause.code : void 0;
+}
+function storageFailure(action, cause) {
+  return new TenantErasureError(
+    "tenant_erasure_storage_failure",
+    `Tenant erasure could not finish ${action}; no SQL progress was advanced.`,
+    { cause }
+  );
+}
+function databaseFailure(action, cause) {
+  return cause instanceof TenantErasureError ? cause : new TenantErasureError(
+    "tenant_erasure_database_failure",
+    `Tenant erasure could not finish ${action}; retry with the same operation id.`,
+    { cause }
+  );
+}
 
-export { CLOUD_CLEANUP_ERROR_CODES, CloudCleanupError, DEFAULT_MAX_ATTEMPTS, DEFAULT_PRESIGN_TTL_SECONDS, DEFAULT_RETRY_DELAY_MS, MAX_PRESIGN_TTL_SECONDS, MIN_PRESIGN_TTL_SECONDS, MigrationChecksumMismatchError, MigrationFilenameError, ObjectStoreRequestError, PostgresActivityStore, PostgresApprovalTimelineStore, PostgresBoardStore, PostgresCloudCleanup, PostgresDeviceAssertionReplayAuthority, PostgresDeviceDirectory, PostgresInboundDedupStore, PostgresMailboxStore, PostgresNonceStore, PostgresObjectStore, PostgresPairingCodeStore, PostgresPresenceStore, PostgresProofRequestReceiptStore, PostgresQuotaStore, PostgresRequestReceiptStore, PostgresSkillPackStore, PostgresTaskAttemptStore, PostgresTruthCommitter, PostgresTruthStore, R2BlobStoreError, R2CloudBlobStore, R2ObjectMaintenanceStore, R2_BLOB_ERROR_CODES, createByokPool, createPostgresCloudMaintenance, createPostgresCloudStores, createPostgresCoreStores, migrate, migrationsDir, readMigrationFiles };
+export { CLOUD_CLEANUP_ERROR_CODES, CloudCleanupError, DEFAULT_MAX_ATTEMPTS, DEFAULT_PRESIGN_TTL_SECONDS, DEFAULT_RETRY_DELAY_MS, MAX_PRESIGN_TTL_SECONDS, MIN_PRESIGN_TTL_SECONDS, MigrationChecksumMismatchError, MigrationFilenameError, MigrationStateMismatchError, ObjectStoreRequestError, PostgresActivityStore, PostgresApprovalTimelineStore, PostgresBoardStore, PostgresCloudCleanup, PostgresDeviceAssertionReplayAuthority, PostgresDeviceDirectory, PostgresInboundDedupStore, PostgresMailboxStore, PostgresNonceStore, PostgresObjectStore, PostgresPairingCodeStore, PostgresPresenceStore, PostgresProofRequestReceiptStore, PostgresQuotaStore, PostgresRequestReceiptStore, PostgresSkillPackStore, PostgresTaskAttemptStore, PostgresTaskCancellationStore, PostgresTenantErasure, PostgresTruthCommitter, PostgresTruthStore, R2BlobStoreError, R2CloudBlobStore, R2ObjectMaintenanceStore, R2_BLOB_ERROR_CODES, TENANT_ERASURE_ERROR_CODES, TENANT_ERASURE_TABLES, TenantErasureError, createByokPool, createPostgresCloudMaintenance, createPostgresCloudStores, createPostgresCoreStores, createPostgresTenantErasure, migrate, migrationsDir, readMigrationFiles, verifyMigrations };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map