@byok-sdk/cloud-dataplane 0.11.0 → 0.12.0

package/dist/sql/0016_mailbox_delivery_watermark.sql

@@ -0,0 +1,20 @@
+-- 0016_mailbox_delivery_watermark.sql — server-owned mailbox delivery bound.
+--
+-- Client acknowledgement is allowed only through the highest cursor the
+-- server has returned to that exact tenant/device. Enqueue allocation is not
+-- delivery authority: next_seq may be far ahead while no response has exposed
+-- those rows. Existing acknowledged rows are the one safe backfill fact — an
+-- acknowledgement already persisted before this migration necessarily came
+-- from the historical delivery path.
+
+ALTER TABLE device_stream
+  ADD COLUMN delivered_seq bigint NOT NULL DEFAULT 0;
+
+UPDATE device_stream
+   SET delivered_seq = acked_seq;
+
+ALTER TABLE device_stream
+  ADD CONSTRAINT device_stream_delivery_nonnegative
+  CHECK (delivered_seq >= 0),
+  ADD CONSTRAINT device_stream_ack_within_delivery
+  CHECK (acked_seq <= delivered_seq);

package/dist/sql/0017_agent_message_admission.sql

@@ -0,0 +1,23 @@
+-- Durable first-message admission serialized with task cancellation.
+--
+-- This one row records both the admission and the immutable final disposition:
+-- exactly one new agent.message.publish may cross from a live task into the
+-- product consumer. A pending row is deliberately fail-closed: elapsed time
+-- cannot prove that an external consumer stopped, so retries never invoke it
+-- again or synthesize a terminal result. The task row is locked by the
+-- application transaction before inserting here, so cancellation and first
+-- message admission have one durable winner.
+
+CREATE TABLE agent_message_admission (
+  tenant_id text NOT NULL,
+  device_id text NOT NULL,
+  task_id text NOT NULL,
+  message_id text NOT NULL,
+  payload_body text NOT NULL,
+  terminal_body text,
+  PRIMARY KEY (tenant_id, device_id, task_id),
+  UNIQUE (tenant_id, device_id, message_id),
+  FOREIGN KEY (tenant_id, task_id)
+    REFERENCES task (tenant_id, task_id)
+    ON DELETE CASCADE
+);

package/dist/stores/core/mailbox.d.ts

@@ -4,9 +4,9 @@
  * The load-bearing rule, and the one a composition can break silently:
  * **reading is not acknowledging.** `readAfter` is a `SELECT` and nothing else.
  * The only ack is `advanceCursor`, which the daemon calls after it has durably
- * journaled the envelope, and it is monotonic — a lower cursor is refused with
- * the cursor it lost to rather than quietly re-delivering work the device has
- * already run.
+ * journaled the envelope. It is monotonic and bounded by `recordDelivery`:
+ * regression and future cursors are refused with the cursor state they lost
+ * to rather than re-delivering or silently skipping work.
  *
  * `collectRetired` deletes acked rows and **marks** unacked ones `expired`. It
  * never deletes an unacked row. §12.7.5 requires an envelope that aged out
@@ -19,7 +19,7 @@
  * the SQL expression of §12.6.2 layer 3: there is no bare device index to
  * accidentally query.
  */
-import { type Clock, type MailboxAdvanceCursorInput, type MailboxAppendInput, type MailboxCursorState, type MailboxMessage, type MailboxPage, type MailboxReadQuery, type MailboxRetentionInput, type MailboxRetentionResult, type MailboxStore, type TenantId } from '@byok-sdk/core';
+import { type Clock, type MailboxAdvanceCursorInput, type MailboxAppendInput, type MailboxCursorState, type MailboxMessage, type MailboxPage, type MailboxReadQuery, type MailboxRecordDeliveryInput, type MailboxRetentionInput, type MailboxRetentionResult, type MailboxStore, type TenantId } from '@byok-sdk/core';
 import type { Pool } from 'pg';
 export declare const OUTBOX_COLUMNS = "tenant_id, device_id, seq, message_id, body, body_hash, byte_size, state, appended_at";
 export interface OutboxRow {
@@ -40,6 +40,7 @@ export declare class PostgresMailboxStore implements MailboxStore {
     append(tenant: TenantId, input: MailboxAppendInput): Promise<MailboxMessage>;
     readAfter(tenant: TenantId, query: MailboxReadQuery): Promise<MailboxPage>;
     advanceCursor(tenant: TenantId, input: MailboxAdvanceCursorInput): Promise<MailboxCursorState>;
+    recordDelivery(tenant: TenantId, input: MailboxRecordDeliveryInput): Promise<MailboxCursorState>;
     readCursor(tenant: TenantId, deviceId: string): Promise<MailboxCursorState>;
     collectRetired(tenant: TenantId, input: MailboxRetentionInput): Promise<MailboxRetentionResult>;
 }

package/dist/stores/devices.d.ts

@@ -19,7 +19,16 @@
  */
 import { type Clock, type PresenceStore, type TenantId, type TenantReadiness } from '@byok-sdk/core';
 import type { DeviceDirectory, DeviceRecord, DeviceRegistration } from '@byok-sdk/cloud';
-import type { Pool } from 'pg';
+import type { Pool, PoolClient } from 'pg';
+/**
+ * The client-scoped registration mutation shared by standalone device
+ * registration and pairing enrollment. Its caller owns the transaction so the
+ * guarded pairing-code update, machine supersession cleanup, and insert can
+ * commit or roll back together.
+ */
+export declare function registerDeviceOnClient(client: PoolClient, tenant: TenantId, input: DeviceRegistration): Promise<DeviceRecord>;
+/** Read one active device while a caller-owned transaction still holds its authority lock. */
+export declare function getDeviceOnClient(client: PoolClient, tenant: TenantId, deviceId: string): Promise<DeviceRecord | undefined>;
 export declare class PostgresDeviceDirectory implements DeviceDirectory {
     #private;
     constructor(pool: Pool, clock?: Clock);

package/dist/stores/nonces.d.ts

@@ -21,6 +21,5 @@ export declare class PostgresNonceStore implements NonceStore {
     #private;
     constructor(pool: Pool, clock: Clock, crypto: CloudCrypto, ttlMs?: number);
     issue(tenant: TenantId, deviceId: string): Promise<string>;
-    validate(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
-    markUsed(tenant: TenantId, nonce: string): Promise<void>;
+    consumeIfValid(tenant: TenantId, deviceId: string, nonce: string): Promise<boolean>;
 }

package/dist/stores/pairing-codes.d.ts

@@ -2,12 +2,11 @@
  * Postgres {@link PairingCodeStore}: single-use codes bound to the tenant and
  * product they were minted for.
  *
- * Redemption is one guarded statement. `UPDATE ... WHERE redeemed_at IS NULL
- * AND expires_at >= $now RETURNING ...` consumes and reports in the same
- * round trip, and zero rows is the typed rejection. A read-then-write would let
- * two concurrent redemptions both observe an unused code, and single-use is
- * exactly what makes the caller's "redeem, then register the device" sequence
- * exclusive.
+ * Enrollment is one transaction. `UPDATE ... WHERE redeemed_at IS NULL AND
+ * expires_at >= $now RETURNING ...` claims the code only inside the same client
+ * transaction that applies machine supersession/state cleanup and inserts the
+ * device. A read-then-write would let two callers observe an unused code; an
+ * autocommitted redemption would strand a code when registration fails.
  *
  * Unknown, expired, and already-used all answer `undefined`. The reference
  * server distinguishes them in its 401 text; a hosted multi-tenant surface
@@ -16,11 +15,19 @@
  * difference an attacker enumerating codes would pay for.
  */
 import type { Clock, TenantId } from '@byok-sdk/core';
-import type { PairingCodeClaims, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore } from '@byok-sdk/cloud';
+import type { DeviceRecord, PairingCodeInfo, PairingCodeIssueInput, PairingCodeStore } from '@byok-sdk/cloud';
 import type { Pool } from 'pg';
 export declare class PostgresPairingCodeStore implements PairingCodeStore {
     #private;
     constructor(pool: Pool, clock: Clock);
     issue(tenant: TenantId, input: PairingCodeIssueInput): Promise<PairingCodeInfo>;
-    redeem(code: string): Promise<PairingCodeClaims | undefined>;
+    redeemAndRegister(input: {
+        readonly pairingCode: string;
+        readonly deviceId: string;
+        readonly deviceName: string;
+        readonly devicePublicKey: string;
+        readonly proofKeyId: string;
+        readonly proofKeyEpoch: number;
+        readonly machineId?: string;
+    }): Promise<DeviceRecord | undefined>;
 }

package/dist/stores/task-attempts.d.ts

@@ -14,7 +14,7 @@
  * `claim` and `recordStatus` on a task this tenant never offered write nothing
  * and return `undefined`.
  */
-import type { AgentRef, TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '@byok-sdk/cloud';
+import { type AgentMessageAdmission, type AgentRef, type TaskAttempt, type TaskAttemptStatus, type TaskAttemptStore } from '@byok-sdk/cloud';
 import type { Clock, TenantId } from '@byok-sdk/core';
 import type { Pool } from 'pg';
 export interface TaskRow {
@@ -49,6 +49,25 @@ export declare class PostgresTaskAttemptStore implements TaskAttemptStore {
         readonly attempt: TaskAttempt;
         readonly created: boolean;
     }>;
+    reserveAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<'reserved' | 'pending' | 'rejected'>;
+    readAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
+    finalizeAgentMessage(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly messageId: string;
+        readonly payloadBody: string;
+        readonly terminalBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     claim(tenant: TenantId, input: {

package/dist/tenant-erasure.d.ts

@@ -1,8 +1,8 @@
 import { type Clock, type TenantId } from '@byok-sdk/core';
 import type { Pool } from 'pg';
 import { type R2BlobStoreOptions, type R2ObjectMaintenance } from './stores/r2-blobs';
-/** Every tenant-owned table as of 0014, in child-before-parent deletion order. */
-export declare const TENANT_ERASURE_TABLES: readonly ['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', 'agent_memory_projection_metering_receipt', 'agent_memory_projection_head', 'agent_memory_projection_erase_fence', 'agent_egress_event', 'device_request_receipts', 'proof_request_receipt', 'task', 'device_presence', 'device_assertion_replay', 'device_stream', 'inbound_dedup', 'auth_nonce', 'pairing_code', 'device'];
+/** Every tenant-owned table as of 0017, in child-before-parent deletion order. */
+export declare const TENANT_ERASURE_TABLES: readonly ['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', 'agent_memory_projection_metering_receipt', 'agent_memory_projection_head', 'agent_memory_projection_erase_fence', 'agent_egress_event', 'device_request_receipts', 'proof_request_receipt', 'agent_message_admission', 'task', 'device_presence', 'device_assertion_replay', 'device_stream', 'inbound_dedup', 'auth_nonce', 'pairing_code', 'device'];
 export declare const TENANT_ERASURE_ERROR_CODES: {
     readonly tenant_erasure_invalid_input: 'tenant_erasure_invalid_input';
     readonly tenant_erasure_schema_drift: 'tenant_erasure_schema_drift';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/cloud-dataplane",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "BYOK SDK hosted data plane: canonical Postgres + R2 stores, migrations, truth transactions, and maintenance",
   "type": "module",
   "license": "MIT",
@@ -49,9 +49,9 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@byok-sdk/cloud": "0.11.0",
-    "@byok-sdk/core": "0.11.0",
-    "@byok-sdk/protocol": "0.11.0",
+    "@byok-sdk/cloud": "0.12.0",
+    "@byok-sdk/core": "0.12.0",
+    "@byok-sdk/protocol": "0.12.0",
     "aws4fetch": "1.0.20",
     "fast-xml-parser": "^5.10.1",
     "pg": "^8.22.0"