@byok-sdk/cloud-dataplane 0.8.1 → 0.9.0

package/dist/index.js

@@ -3,7 +3,7 @@ import { DEDUP_RING_CAPACITY, NONCE_TTL_MS, validateActivityAppend, projectTimel
 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 { decodeEnvelope, isServerToDaemonType, EnvelopeSchema, encodeEnvelope, AgentEgressReliablePayloadSchema } from '@byok-sdk/protocol';
+import { AgentMemoryProjectionMutationSchema, AgentMemoryProjectionReceiptSchema, AGENT_MEMORY_PROJECTION_MAX_ORDERING_VALUE, AgentMemoryProjectionEraseResultSchema, AGENT_MEMORY_PROJECTION_MAX_REDACTED_BYTES, decodeEnvelope, isServerToDaemonType, EnvelopeSchema, encodeEnvelope, AgentEgressReliablePayloadSchema } from '@byok-sdk/protocol';
 import { createHash, randomUUID } from 'crypto';
 import { readdir, readFile } from 'fs/promises';
 import { join } from 'path';
@@ -1932,6 +1932,337 @@ var PostgresAgentEgressStore = class {
     return row === void 0 ? void 0 : toRecord2(row);
   }
 };
+var RECEIPT_COLUMNS = [
+  "tenant_id",
+  "agent_id",
+  "writer_epoch",
+  "source_seq",
+  "mutation_id",
+  "device_id",
+  "task_id",
+  "agent_profile_revision",
+  "session_ref",
+  "runtime_id",
+  "grant_ref",
+  "policy_revision",
+  "redacted_hash",
+  "redacted_byte_count",
+  "metering_receipt_id",
+  "recorded_at"
+].join(", ");
+var PostgresAgentMemoryProjectionStore = class {
+  #pool;
+  #clock;
+  #crypto;
+  constructor(options) {
+    this.#pool = options.pool;
+    this.#clock = options.clock;
+    this.#crypto = options.crypto;
+  }
+  async commit(input) {
+    const mutation = AgentMemoryProjectionMutationSchema.parse(input.mutation);
+    await this.#assertRedactedSnapshot(
+      input.redactedBytes,
+      mutation.snapshot.redactedBytes,
+      mutation.snapshot.redactedByteCount,
+      mutation.snapshot.redactedHash
+    );
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      await lockAgentMutation(client, input.tenantId, mutation.agentRef.agentId);
+      const receipt = await this.#readReceipt(client, input.tenantId, mutation.agentRef.agentId, mutation.writerEpoch, mutation.sourceSeq);
+      if (receipt !== void 0) {
+        if (!sameReceiptBinding(receipt, input, mutation)) {
+          throw replayMismatch();
+        }
+        await client.query("COMMIT");
+        return toReceipt3(receipt, "idempotent");
+      }
+      const existingMutation = await this.#readReceiptByMutationId(
+        client,
+        input.tenantId,
+        mutation.agentRef.agentId,
+        mutation.writerEpoch,
+        mutation.mutationId
+      );
+      if (existingMutation !== void 0) throw replayMismatch();
+      const head = await this.#readHeadForUpdate(client, input.tenantId, mutation.agentRef.agentId);
+      const fence = await this.#readEraseFenceForUpdate(client, input.tenantId, mutation.agentRef.agentId);
+      assertNextMutation(head, fence, mutation.writerEpoch, mutation.sourceSeq);
+      const now = this.#clock.now();
+      const meteringReceiptId = this.#crypto.randomUuid();
+      await client.query(
+        `INSERT INTO agent_memory_projection_metering_receipt (${RECEIPT_COLUMNS})
+         VALUES ($1, $2, $3, $4, $5::uuid, $6, $7, $8, $9, $10, $11, $12, $13, $14::integer, $15::uuid, $16)`,
+        [
+          input.tenantId,
+          mutation.agentRef.agentId,
+          mutation.writerEpoch,
+          mutation.sourceSeq,
+          mutation.mutationId,
+          input.deviceId,
+          mutation.taskId,
+          mutation.agentRef.profileRevision,
+          mutation.sessionRef,
+          mutation.runtimeId,
+          mutation.grantRef,
+          mutation.policyRevision,
+          mutation.snapshot.redactedHash,
+          mutation.snapshot.redactedByteCount,
+          meteringReceiptId,
+          now
+        ]
+      );
+      await client.query(
+        `INSERT INTO agent_memory_projection_head (
+           tenant_id, agent_id, writer_epoch, source_seq, mutation_id,
+           device_id, task_id, agent_profile_revision, session_ref, runtime_id,
+           grant_ref, policy_revision, redacted_hash, redacted_snapshot,
+           redacted_byte_count, committed_at
+         ) VALUES (
+           $1, $2, $3, $4, $5::uuid,
+           $6, $7, $8, $9, $10,
+           $11, $12, $13, decode($14, 'base64'),
+           $15::integer, $16
+         )
+         ON CONFLICT (tenant_id, agent_id) DO UPDATE SET
+           writer_epoch = EXCLUDED.writer_epoch,
+           source_seq = EXCLUDED.source_seq,
+           mutation_id = EXCLUDED.mutation_id,
+           device_id = EXCLUDED.device_id,
+           task_id = EXCLUDED.task_id,
+           agent_profile_revision = EXCLUDED.agent_profile_revision,
+           session_ref = EXCLUDED.session_ref,
+           runtime_id = EXCLUDED.runtime_id,
+           grant_ref = EXCLUDED.grant_ref,
+           policy_revision = EXCLUDED.policy_revision,
+           redacted_hash = EXCLUDED.redacted_hash,
+           redacted_snapshot = EXCLUDED.redacted_snapshot,
+           redacted_byte_count = EXCLUDED.redacted_byte_count,
+           committed_at = EXCLUDED.committed_at`,
+        [
+          input.tenantId,
+          mutation.agentRef.agentId,
+          mutation.writerEpoch,
+          mutation.sourceSeq,
+          mutation.mutationId,
+          input.deviceId,
+          mutation.taskId,
+          mutation.agentRef.profileRevision,
+          mutation.sessionRef,
+          mutation.runtimeId,
+          mutation.grantRef,
+          mutation.policyRevision,
+          mutation.snapshot.redactedHash,
+          toBase64(input.redactedBytes),
+          mutation.snapshot.redactedByteCount,
+          now
+        ]
+      );
+      await client.query("COMMIT");
+      return AgentMemoryProjectionReceiptSchema.parse({
+        outcome: "accepted",
+        tenantId: input.tenantId,
+        deviceId: input.deviceId,
+        taskId: mutation.taskId,
+        agentRef: mutation.agentRef,
+        sessionRef: mutation.sessionRef,
+        runtimeId: mutation.runtimeId,
+        grantRef: mutation.grantRef,
+        writerEpoch: mutation.writerEpoch,
+        sourceSeq: mutation.sourceSeq,
+        mutationId: mutation.mutationId,
+        policyRevision: mutation.policyRevision,
+        redactedHash: mutation.snapshot.redactedHash,
+        redactedByteCount: mutation.snapshot.redactedByteCount,
+        metering: {
+          meteringReceiptId,
+          acceptedRedactedBytes: mutation.snapshot.redactedByteCount,
+          recordedAt: now.toISOString()
+        }
+      });
+    } catch (cause) {
+      await rollback(client);
+      throw cause;
+    } finally {
+      client.release();
+    }
+  }
+  /** Delete body/receipts but retain a body-free epoch fence under one source lock. */
+  async erase(input) {
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      await lockAgentMutation(client, input.tenantId, input.agentId);
+      const head = await this.#readHeadForUpdate(client, input.tenantId, input.agentId);
+      const fence = await this.#readEraseFenceForUpdate(client, input.tenantId, input.agentId);
+      const nextWriterEpoch = Math.max(fence?.next_writer_epoch ?? 1, (head?.writer_epoch ?? 0) + 1);
+      if (nextWriterEpoch > AGENT_MEMORY_PROJECTION_MAX_ORDERING_VALUE) {
+        throw new ByokCloudError("agent_memory_projection_epoch_exhausted", "The memory projection writerEpoch cannot advance after erase.");
+      }
+      await client.query(
+        "DELETE FROM agent_memory_projection_metering_receipt WHERE tenant_id = $1 AND agent_id = $2",
+        [input.tenantId, input.agentId]
+      );
+      await client.query(
+        "DELETE FROM agent_memory_projection_head WHERE tenant_id = $1 AND agent_id = $2",
+        [input.tenantId, input.agentId]
+      );
+      await client.query(
+        `INSERT INTO agent_memory_projection_erase_fence (tenant_id, agent_id, next_writer_epoch, erased_at)
+         VALUES ($1, $2, $3::integer, $4)
+         ON CONFLICT (tenant_id, agent_id) DO UPDATE SET
+           next_writer_epoch = GREATEST(agent_memory_projection_erase_fence.next_writer_epoch, EXCLUDED.next_writer_epoch),
+           erased_at = EXCLUDED.erased_at`,
+        [input.tenantId, input.agentId, nextWriterEpoch, this.#clock.now()]
+      );
+      await client.query("COMMIT");
+      return AgentMemoryProjectionEraseResultSchema.parse({ nextWriterEpoch });
+    } catch (cause) {
+      await rollback(client);
+      throw cause;
+    } finally {
+      client.release();
+    }
+  }
+  async #assertRedactedSnapshot(bytes, portableBody, byteCount, expectedHash) {
+    if (bytes.byteLength !== byteCount || bytes.byteLength > AGENT_MEMORY_PROJECTION_MAX_REDACTED_BYTES) {
+      throw hashMismatch("Decoded redacted snapshot bytes do not match redactedByteCount.");
+    }
+    if (portableBody !== toBase64Url(bytes)) {
+      throw hashMismatch("Decoded redacted snapshot bytes do not match the portable redactedBytes body.");
+    }
+    if (await this.#crypto.sha256(bytes) !== expectedHash) {
+      throw hashMismatch("Decoded redacted snapshot bytes do not match redactedHash.");
+    }
+  }
+  async #readHeadForUpdate(client, tenant, agentId) {
+    const result = await client.query(
+      `SELECT tenant_id, agent_id, writer_epoch, source_seq
+         FROM agent_memory_projection_head
+        WHERE tenant_id = $1 AND agent_id = $2
+        FOR UPDATE`,
+      [tenant, agentId]
+    );
+    return result.rows[0];
+  }
+  async #readEraseFenceForUpdate(client, tenant, agentId) {
+    const result = await client.query(
+      `SELECT next_writer_epoch
+         FROM agent_memory_projection_erase_fence
+        WHERE tenant_id = $1 AND agent_id = $2
+        FOR UPDATE`,
+      [tenant, agentId]
+    );
+    return result.rows[0];
+  }
+  async #readReceipt(client, tenant, agentId, writerEpoch, sourceSeq) {
+    const result = await client.query(
+      `SELECT ${RECEIPT_COLUMNS}
+         FROM agent_memory_projection_metering_receipt
+        WHERE tenant_id = $1 AND agent_id = $2 AND writer_epoch = $3 AND source_seq = $4`,
+      [tenant, agentId, writerEpoch, sourceSeq]
+    );
+    return result.rows[0];
+  }
+  async #readReceiptByMutationId(client, tenant, agentId, writerEpoch, mutationId) {
+    const result = await client.query(
+      `SELECT ${RECEIPT_COLUMNS}
+         FROM agent_memory_projection_metering_receipt
+        WHERE tenant_id = $1 AND agent_id = $2 AND writer_epoch = $3 AND mutation_id = $4::uuid`,
+      [tenant, agentId, writerEpoch, mutationId]
+    );
+    return result.rows[0];
+  }
+};
+function createPostgresAgentMemoryProjectionStore(options) {
+  return new PostgresAgentMemoryProjectionStore(options);
+}
+function assertNextMutation(head, fence, writerEpoch, sourceSeq) {
+  if (fence !== void 0 && writerEpoch < fence.next_writer_epoch) {
+    throw erasedEpoch();
+  }
+  if (head === void 0) {
+    if (sourceSeq !== 1) throw sequenceGap("The first memory projection mutation must use sourceSeq 1.");
+    return;
+  }
+  if (writerEpoch < head.writer_epoch) {
+    throw new ByokCloudError("agent_memory_projection_stale_epoch", "The memory projection writerEpoch is stale.");
+  }
+  if (writerEpoch > head.writer_epoch) {
+    if (sourceSeq !== 1) throw sequenceGap("A new memory projection writerEpoch must start at sourceSeq 1.");
+    return;
+  }
+  if (sourceSeq !== head.source_seq + 1) {
+    throw sequenceGap("A memory projection mutation must advance sourceSeq exactly by one.");
+  }
+}
+function sameReceiptBinding(receipt, input, mutation) {
+  return receipt.tenant_id === input.tenantId && receipt.agent_id === mutation.agentRef.agentId && receipt.device_id === input.deviceId && receipt.task_id === mutation.taskId && receipt.agent_profile_revision === mutation.agentRef.profileRevision && receipt.session_ref === mutation.sessionRef && receipt.runtime_id === mutation.runtimeId && receipt.grant_ref === mutation.grantRef && receipt.writer_epoch === mutation.writerEpoch && receipt.source_seq === mutation.sourceSeq && receipt.mutation_id === mutation.mutationId && receipt.policy_revision === mutation.policyRevision && receipt.redacted_hash === mutation.snapshot.redactedHash && receipt.redacted_byte_count === mutation.snapshot.redactedByteCount;
+}
+function toReceipt3(row, outcome) {
+  return AgentMemoryProjectionReceiptSchema.parse({
+    outcome,
+    tenantId: row.tenant_id,
+    deviceId: row.device_id,
+    taskId: row.task_id,
+    agentRef: { agentId: row.agent_id, profileRevision: row.agent_profile_revision },
+    sessionRef: row.session_ref,
+    runtimeId: row.runtime_id,
+    grantRef: row.grant_ref,
+    writerEpoch: row.writer_epoch,
+    sourceSeq: row.source_seq,
+    mutationId: row.mutation_id,
+    policyRevision: row.policy_revision,
+    redactedHash: row.redacted_hash,
+    redactedByteCount: row.redacted_byte_count,
+    metering: {
+      meteringReceiptId: row.metering_receipt_id,
+      acceptedRedactedBytes: row.redacted_byte_count,
+      recordedAt: row.recorded_at.toISOString()
+    }
+  });
+}
+async function lockAgentMutation(client, tenant, agentId) {
+  await client.query(
+    `SELECT pg_advisory_xact_lock(
+       hashtextextended(length($1)::text || ':' || $1 || length($2)::text || ':' || $2, 0)
+     )`,
+    [tenant, agentId]
+  );
+}
+function hashMismatch(message) {
+  return new ByokCloudError("agent_memory_projection_hash_mismatch", message);
+}
+function sequenceGap(message) {
+  return new ByokCloudError("agent_memory_projection_sequence_gap", message);
+}
+function erasedEpoch() {
+  return new ByokCloudError("agent_memory_projection_erased_epoch", "The memory projection writerEpoch was erased and cannot be replayed.");
+}
+function replayMismatch() {
+  return new ByokCloudError(
+    "agent_memory_projection_replay_mismatch",
+    "A memory projection epoch and source sequence already names a different immutable mutation."
+  );
+}
+function toBase64(bytes) {
+  const chunks = [];
+  for (let offset = 0; offset < bytes.length; offset += 32 * 1024) {
+    chunks.push(String.fromCharCode(...bytes.subarray(offset, offset + 32 * 1024)));
+  }
+  return btoa(chunks.join(""));
+}
+function toBase64Url(bytes) {
+  return toBase64(bytes).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+async function rollback(client) {
+  try {
+    await client.query("ROLLBACK");
+  } catch {
+  }
+}
 
 // src/stores/device-assertion-replay.ts
 var PostgresDeviceAssertionReplayAuthority = class {
@@ -3246,7 +3577,7 @@ function createPostgresCoreStores(options) {
   };
 }
 var RECORD_COLUMNS2 = "tenant_id, kind, subject_id, rev, content_hash, byte_size, body_kind, body_inline, body_object_hash, label, request_id, written_at";
-var RECEIPT_COLUMNS = "tenant_id, device_id, request_id, operation, resource, body_sha256, body_size, response_status, response_body, recorded_at";
+var RECEIPT_COLUMNS2 = "tenant_id, device_id, request_id, operation, resource, body_sha256, body_size, response_status, response_body, recorded_at";
 function toBody2(row) {
   return row.body_kind === "inline" ? { kind: "inline", body: row.body_inline ?? "" } : { kind: "object", hash: row.body_object_hash ?? "" };
 }
@@ -3264,7 +3595,7 @@ function toRecord4(tenant, row) {
     writtenAt: row.written_at
   };
 }
-function toReceipt3(tenant, row) {
+function toReceipt4(tenant, row) {
   return {
     tenantId: tenant,
     deviceId: row.device_id,
@@ -3344,7 +3675,7 @@ var PostgresTruthCommitter = class {
         snapshots: applied.slice(1).map((entry) => truthRecordMetadata(entry.record))
       };
       await client.query(
-        `INSERT INTO proof_request_receipt (${RECEIPT_COLUMNS})
+        `INSERT INTO proof_request_receipt (${RECEIPT_COLUMNS2})
          VALUES ($1, $2, $3, $4, $5, $6, $7::bigint, 200, $8, $9)`,
         [
           tenant,
@@ -3403,12 +3734,12 @@ var PostgresTruthCommitter = class {
   }
   async #readReceipt(client, tenant, deviceId, requestId) {
     const result = await client.query(
-      `SELECT ${RECEIPT_COLUMNS} FROM proof_request_receipt
+      `SELECT ${RECEIPT_COLUMNS2} FROM proof_request_receipt
         WHERE tenant_id = $1 AND device_id = $2 AND request_id = $3`,
       [tenant, deviceId, requestId]
     );
     const row = result.rows[0];
-    return row === void 0 ? void 0 : toReceipt3(tenant, row);
+    return row === void 0 ? void 0 : toReceipt4(tenant, row);
   }
   async #lockCurrentRecords(client, tenant, writes) {
     const current = /* @__PURE__ */ new Map();
@@ -4904,6 +5235,9 @@ var TENANT_ERASURE_TABLES = [
   "board_item",
   "tenant_stream",
   "outbox",
+  "agent_memory_projection_metering_receipt",
+  "agent_memory_projection_head",
+  "agent_memory_projection_erase_fence",
   "agent_egress_event",
   "device_request_receipts",
   "proof_request_receipt",
@@ -5360,6 +5694,6 @@ function databaseFailure(action, 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, 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 };
+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, PostgresAgentMemoryProjectionStore, 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, createPostgresAgentMemoryProjectionStore, createPostgresCloudMaintenance, createPostgresCloudStores, createPostgresCoreStores, createPostgresTenantErasure, migrate, migrationsDir, readMigrationFiles, verifyMigrations };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map