@byok-sdk/cloud-dataplane 0.11.0 → 0.13.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/sql/0018_task_attempt_claimed_runtime.sql

@@ -0,0 +1,23 @@
+-- The claim-time runtime snapshot on the task attempt.
+--
+-- Two columns, one fact: what the daemon that WON the ownership CAS reported
+-- about itself on its own `task.claim` — its runtime id and that adapter's own
+-- capability block. Both are written by the guarded claim UPDATE and by nothing
+-- else, so they are set exactly once, at the `offered -> claimed` transition,
+-- and a redelivered or losing claim can never restamp them.
+--
+-- They are ATTRIBUTION, not execution state: they stop changing the moment
+-- ownership is decided, which is what keeps them inside what ADR-028 allows the
+-- coordination plane to hold. `ByokCloud.steerTask` reads
+-- `claimed_runtime_capabilities` as the single input to its steer gate; the
+-- connection-level capability snapshot on the device row is deliberately not an
+-- input, because it describes a device build rather than the adapter that took
+-- this task.
+--
+-- Additive and nullable with NO backfill, deliberately. A task claimed before
+-- this migration has no snapshot to reconstruct — the claim that carried it is
+-- long gone — and inventing one would open the steer gate on a guess. NULL
+-- means "unknown", and the gate refuses an unknown.
+
+ALTER TABLE task ADD COLUMN claimed_runtime text;
+ALTER TABLE task ADD COLUMN claimed_runtime_capabilities jsonb;

package/dist/sql/0019_agent_ref_replay_keys.sql

@@ -0,0 +1,36 @@
+-- Strict Agent reliability identities.
+--
+-- A device may host many Agents. The old device-plus-envelope/event primary
+-- keys therefore let Agent A suppress Agent B when they independently used
+-- the same reliable id. This migration cuts those keys forward: physical facts
+-- retain the empty Agent scope, while every Agent-bound caller must supply the
+-- exact AgentRef. The empty pair is not an AgentRef and is never a read
+-- fallback; it is the explicit keyspace for facts such as conn.hello that have
+-- no Agent authority.
+
+ALTER TABLE inbound_dedup
+  ADD COLUMN agent_id text NOT NULL DEFAULT '',
+  ADD COLUMN agent_profile_revision text NOT NULL DEFAULT '';
+
+ALTER TABLE inbound_dedup
+  ADD CONSTRAINT inbound_dedup_agent_scope_shape CHECK (
+    (agent_id = '' AND agent_profile_revision = '') OR
+    (
+      octet_length(agent_id) BETWEEN 1 AND 160
+      AND octet_length(agent_profile_revision) BETWEEN 1 AND 160
+      AND agent_id !~ '[[:cntrl:]]'
+      AND agent_profile_revision !~ '[[:cntrl:]]'
+    )
+  );
+
+ALTER TABLE inbound_dedup DROP CONSTRAINT inbound_dedup_pkey;
+ALTER TABLE inbound_dedup
+  ADD PRIMARY KEY (tenant_id, device_id, agent_id, agent_profile_revision, envelope_id);
+
+DROP INDEX inbound_dedup_reclaim_idx;
+CREATE INDEX inbound_dedup_reclaim_idx
+  ON inbound_dedup (tenant_id, device_id, agent_id, agent_profile_revision, recorded_seq);
+
+ALTER TABLE agent_egress_event DROP CONSTRAINT agent_egress_event_pkey;
+ALTER TABLE agent_egress_event
+  ADD PRIMARY KEY (tenant_id, device_id, agent_id, agent_profile_revision, event_id);

package/dist/sql/0020_agent_ref_request_keys.sql

@@ -0,0 +1,7 @@
+-- Agent reliability identities are exact to the attempt's AgentRef. The
+-- task-bound primary key already supplies that authority through `task`; a
+-- device-wide message-id uniqueness constraint would instead let one Agent
+-- suppress another active Agent on the same device.
+
+ALTER TABLE agent_message_admission
+  DROP CONSTRAINT agent_message_admission_tenant_id_device_id_message_id_key;

package/dist/stores/agent-egress.d.ts

@@ -1,3 +1,4 @@
+import { type AgentEgressReliablePayload } from '@byok-sdk/protocol';
 import type { AgentEgressRecord, AgentEgressStore } from '@byok-sdk/cloud';
 import type { Clock, TenantId } from '@byok-sdk/core';
 import type { Pool } from 'pg';
@@ -10,5 +11,5 @@ export declare class PostgresAgentEgressStore implements AgentEgressStore {
         readonly record: AgentEgressRecord;
         readonly created: boolean;
     }>;
-    get(tenant: TenantId, deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+    get(tenant: TenantId, deviceId: string, agentRef: AgentEgressReliablePayload['agentRef'], eventId: string): Promise<AgentEgressRecord | undefined>;
 }

package/dist/stores/approval-timeline.d.ts

@@ -1,4 +1,4 @@
-import { type ApprovalTimelineAppendInput, type ApprovalTimelineStore, type ApprovalTimelineTail } from '@byok-sdk/cloud';
+import { type ApprovalTimelineAppendInput, type ApprovalTimelineResolvePendingInput, type ApprovalTimelineResolvePendingResult, type ApprovalTimelineStore, type ApprovalTimelineTail } from '@byok-sdk/cloud';
 import type { Clock, TenantId } from '@byok-sdk/core';
 import type { Pool } from 'pg';
 export declare class PostgresApprovalTimelineStore implements ApprovalTimelineStore {
@@ -6,5 +6,6 @@ export declare class PostgresApprovalTimelineStore implements ApprovalTimelineSt
     private readonly clock;
     constructor(pool: Pool, clock: Clock);
     append(tenant: TenantId, input: ApprovalTimelineAppendInput): Promise<ApprovalTimelineTail>;
+    resolvePending(tenant: TenantId, input: ApprovalTimelineResolvePendingInput): Promise<ApprovalTimelineResolvePendingResult>;
     read(tenant: TenantId, taskId: string): Promise<ApprovalTimelineTail | undefined>;
 }

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/dedup.d.ts

@@ -6,17 +6,20 @@
  * primary key does the deciding, and zero returned rows means "already seen".
  *
  * Reclaim runs only on the path that actually grew the table, and it deletes
- * oldest-first down to `DEDUP_RING_CAPACITY` rows for that device — the same
- * bound the in-memory ring holds. The ids most likely to be redelivered are the
- * recent ones, so dropping the oldest is the retention that matches the wire's
- * behavior. An unbounded set would pass every duplicate assertion and still let
- * one chatty device grow this table without limit.
+ * oldest-first down to `DEDUP_RING_CAPACITY` rows for that exact physical or
+ * Agent-bound key — the same bound the in-memory ring holds. The ids most
+ * likely to be redelivered are the recent ones, so dropping the oldest is the
+ * retention that matches the wire's behavior. An unbounded set would pass every
+ * duplicate assertion and still let one chatty device or Agent grow this table
+ * without limit.
  */
 import { type InboundDedupStore } from '@byok-sdk/cloud';
 import type { TenantId } from '@byok-sdk/core';
+import type { AgentRef } from '@byok-sdk/protocol';
 import type { Pool } from 'pg';
 export declare class PostgresInboundDedupStore implements InboundDedupStore {
     #private;
     constructor(pool: Pool, capacity?: number);
     checkAndRecord(tenant: TenantId, deviceId: string, envelopeId: string): Promise<boolean>;
+    checkAndRecordAgent(tenant: TenantId, deviceId: string, agentRef: AgentRef, envelopeId: string): Promise<boolean>;
 }

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,8 +14,9 @@
  * `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 TaskAttemptListQuery, type TaskAttemptPage, type TaskAttemptStatus, type TaskAttemptStore } from '@byok-sdk/cloud';
 import type { Clock, TenantId } from '@byok-sdk/core';
+import type { RuntimeCapabilities, RuntimeId } from '@byok-sdk/protocol';
 import type { Pool } from 'pg';
 export interface TaskRow {
     readonly tenant_id: string;
@@ -29,9 +30,11 @@ export interface TaskRow {
     readonly cancel_requested_at: Date | null;
     readonly cancel_reason: string | null;
     readonly cancel_message_id: string | null;
+    readonly claimed_runtime: string | null;
+    readonly claimed_runtime_capabilities: RuntimeCapabilities | null;
     readonly updated_at: Date;
 }
-export declare const TASK_SELECT_COLUMNS = "tenant_id, task_id, device_id, agent_id, agent_profile_revision, owner_device_id, status, terminal_cause, cancel_requested_at, cancel_reason, cancel_message_id, updated_at";
+export declare const TASK_SELECT_COLUMNS = "tenant_id, task_id, device_id, agent_id, agent_profile_revision, owner_device_id, status, terminal_cause, cancel_requested_at, cancel_reason, cancel_message_id, claimed_runtime, claimed_runtime_capabilities, updated_at";
 export declare function taskRowToAttempt(row: TaskRow): TaskAttempt;
 export declare class PostgresTaskAttemptStore implements TaskAttemptStore {
     #private;
@@ -49,11 +52,33 @@ 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[]>;
+    list(tenant: TenantId, query: TaskAttemptListQuery): Promise<TaskAttemptPage>;
     claim(tenant: TenantId, input: {
         readonly taskId: string;
         readonly deviceId: string;
+        readonly runtime?: RuntimeId;
+        readonly capabilities?: RuntimeCapabilities;
     }): Promise<TaskAttempt | undefined>;
     recordStatus(tenant: TenantId, input: {
         readonly taskId: string;

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.13.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.13.0",
+    "@byok-sdk/core": "0.13.0",
+    "@byok-sdk/protocol": "0.13.0",
     "aws4fetch": "1.0.20",
     "fast-xml-parser": "^5.10.1",
     "pg": "^8.22.0"