@byok-sdk/cloud-dataplane 0.5.0 → 0.6.1

package/dist/sql/0009_task_cancellation.sql

@@ -0,0 +1,6 @@
+-- Host cancellation tombstone and durable delivery identity.
+-- Additive and forward-only: existing task rows remain uncancelled.
+ALTER TABLE task
+  ADD COLUMN cancel_requested_at timestamptz,
+  ADD COLUMN cancel_reason text,
+  ADD COLUMN cancel_message_id text;

package/dist/sql/0010_tenant_readiness.sql

@@ -0,0 +1,21 @@
+-- U3 tenant readiness observation facts.
+--
+-- The row remains one lossy, TTL-bounded projection per (tenant, device). These
+-- fields are optional because older daemons cannot report them; absence is
+-- unknown, never a host-derived default.
+ALTER TABLE device_presence
+  ADD COLUMN client_version text;
+
+ALTER TABLE device_presence
+  ADD COLUMN protocol_versions jsonb;
+
+ALTER TABLE device_presence
+  ADD COLUMN runtimes jsonb;
+
+ALTER TABLE device_presence
+  ADD CONSTRAINT device_presence_protocol_versions_shape
+  CHECK (protocol_versions IS NULL OR jsonb_typeof(protocol_versions) = 'array');
+
+ALTER TABLE device_presence
+  ADD CONSTRAINT device_presence_runtimes_shape
+  CHECK (runtimes IS NULL OR jsonb_typeof(runtimes) = 'array');

package/dist/sql/0011_tenant_erasure.sql

@@ -0,0 +1,46 @@
+-- 0011_tenant_erasure.sql — package-owned, resumable operator evidence.
+--
+-- This ledger is deliberately NOT tenant product data. It records one operator
+-- operation and its progress so a caller can resume after an R2/database/crash
+-- boundary, and a completed receipt remains auditable after every tenant-owned
+-- product row and R2 object is gone. The erasure implementation is the only
+-- writer; hosts do not receive raw SQL/table-order authority.
+
+CREATE TABLE tenant_erasure_operation (
+  tenant_id             text        NOT NULL,
+  operation_id          text        NOT NULL,
+  state                 text        NOT NULL,
+  revision              bigint      NOT NULL DEFAULT 0,
+  lease_token           text,
+  lease_expires_at      timestamptz,
+  r2_cursor             text,
+  r2_complete           boolean     NOT NULL DEFAULT false,
+  sql_table_index       integer     NOT NULL DEFAULT 0,
+  r2_objects_deleted    bigint      NOT NULL DEFAULT 0,
+  sql_rows_deleted      bigint      NOT NULL DEFAULT 0,
+  started_at            timestamptz NOT NULL,
+  updated_at            timestamptz NOT NULL,
+  completed_at          timestamptz,
+  last_error_code       text,
+  PRIMARY KEY (tenant_id, operation_id),
+  CONSTRAINT tenant_erasure_operation_state CHECK (state IN ('running', 'completed')),
+  CONSTRAINT tenant_erasure_operation_revision_nonnegative CHECK (revision >= 0),
+  CONSTRAINT tenant_erasure_operation_sql_table_index_nonnegative CHECK (sql_table_index >= 0),
+  CONSTRAINT tenant_erasure_operation_counters_nonnegative CHECK (
+    r2_objects_deleted >= 0 AND sql_rows_deleted >= 0
+  ),
+  CONSTRAINT tenant_erasure_operation_completed_receipt CHECK (
+    (state = 'running' AND completed_at IS NULL)
+    OR (state = 'completed' AND completed_at IS NOT NULL AND r2_complete)
+  )
+);
+
+-- At most one unfinished erasure can own a tenant. Completed receipts do not
+-- participate, so a future explicitly authorized erasure operation still has
+-- an idempotency key of its own without deleting its predecessor's evidence.
+CREATE UNIQUE INDEX tenant_erasure_operation_one_running
+  ON tenant_erasure_operation (tenant_id)
+  WHERE state = 'running';
+
+CREATE INDEX tenant_erasure_operation_readback
+  ON tenant_erasure_operation (tenant_id, state, updated_at);

package/dist/sql/0012_agent_home_contract.sql

@@ -0,0 +1,41 @@
+-- 0012_agent_home_contract.sql — durable Agent capability and attempt identity.
+--
+-- Additive only. Existing legacy device/task rows remain valid with NULL
+-- Agent fields and therefore cannot accidentally acquire Agent semantics.
+-- The hosted gate treats a NULL capability snapshot as unknown and refuses an
+-- Agent offer before either a mailbox row or a task attempt is created.
+
+ALTER TABLE device
+  ADD COLUMN capabilities jsonb;
+
+ALTER TABLE device
+  ADD CONSTRAINT device_capabilities_shape
+  CHECK (capabilities IS NULL OR jsonb_typeof(capabilities) = 'array');
+
+ALTER TABLE task
+  ADD COLUMN agent_id text,
+  ADD COLUMN agent_profile_revision text,
+  ADD COLUMN terminal_cause text;
+
+ALTER TABLE task
+  ADD CONSTRAINT task_agent_ref_pair
+  CHECK ((agent_id IS NULL) = (agent_profile_revision IS NULL));
+
+ALTER TABLE task
+  ADD CONSTRAINT task_agent_ref_bounded
+  CHECK (
+    agent_id IS NULL
+    OR (
+      octet_length(agent_id) BETWEEN 1 AND 160
+      AND octet_length(agent_profile_revision) BETWEEN 1 AND 160
+      AND position('/' IN agent_id) = 0
+      AND position(E'\\' IN agent_id) = 0
+      AND position(':' IN agent_id) = 0
+      AND agent_id !~ '[<>"|?*]'
+      AND agent_id NOT IN ('.', '..')
+      AND agent_id !~ '[. ]$'
+      AND lower(split_part(agent_id, '.', 1)) !~ '^(con|prn|aux|nul|com[1-9]|lpt[1-9])$'
+      AND agent_id !~ '[[:cntrl:]]'
+      AND agent_profile_revision !~ '[[:cntrl:]]'
+    )
+  );

package/dist/sql/0013_agent_egress_contract.sql

@@ -0,0 +1,47 @@
+-- 0013_agent_egress_contract.sql — first-write-wins reliable Agent egress facts.
+--
+-- The typed policy never authorizes raw workspace/transcript/artifact bytes to
+-- this table. `payload_json` is the daemon's sanitized JSON projection; exact
+-- AgentRef, session, cursor, content hash, and cloud receipt identity remain
+-- independently addressable so a readback never has to reinterpret an opaque
+-- envelope body.
+
+CREATE TABLE agent_egress_event (
+  tenant_id              text        NOT NULL,
+  device_id              text        NOT NULL,
+  event_id               uuid        NOT NULL,
+  agent_id               text        NOT NULL,
+  agent_profile_revision text        NOT NULL,
+  session_ref            text        NOT NULL,
+  policy_revision        text        NOT NULL,
+  cursor                 bigint      NOT NULL,
+  payload_json           jsonb       NOT NULL,
+  content_hash           text        NOT NULL,
+  byte_count             integer     NOT NULL,
+  receipt_id             uuid        NOT NULL,
+  recorded_at            timestamptz NOT NULL,
+  PRIMARY KEY (tenant_id, device_id, event_id),
+  CONSTRAINT agent_egress_event_cursor_positive CHECK (cursor > 0 AND cursor <= 2147483647),
+  CONSTRAINT agent_egress_event_byte_count CHECK (byte_count >= 0 AND byte_count <= 262144),
+  CONSTRAINT agent_egress_event_hash_shape CHECK (content_hash ~ '^sha256:[a-f0-9]{64}$'),
+  CONSTRAINT agent_egress_event_agent_ref_bounded CHECK (
+    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:]]'
+  ),
+  CONSTRAINT agent_egress_event_session_bounded CHECK (
+    octet_length(session_ref) BETWEEN 1 AND 512
+    AND session_ref !~ '[[:cntrl:]]'
+  ),
+  CONSTRAINT agent_egress_event_policy_bounded CHECK (
+    octet_length(policy_revision) BETWEEN 1 AND 160
+    AND policy_revision !~ '[[:cntrl:]]'
+  )
+);
+
+-- Readback and operational inspection preserve the same tenant/device/session
+-- partition as the wire cursor. This is intentionally not unique: event id is
+-- the reliable idempotency authority, and cursor is an exact observation.
+CREATE INDEX agent_egress_event_cursor_idx
+  ON agent_egress_event (tenant_id, device_id, agent_id, agent_profile_revision, session_ref, cursor);

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

@@ -0,0 +1,14 @@
+import type { AgentEgressRecord, AgentEgressStore } from '@byok-sdk/cloud';
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+/** Postgres implementation of the immutable reliable Agent egress receipt fact. */
+export declare class PostgresAgentEgressStore implements AgentEgressStore {
+    private readonly pool;
+    private readonly clock;
+    constructor(pool: Pool, clock: Clock);
+    record(tenant: TenantId, input: Omit<AgentEgressRecord, 'tenantId' | 'recordedAt'>): Promise<{
+        readonly record: AgentEgressRecord;
+        readonly created: boolean;
+    }>;
+    get(tenant: TenantId, deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+}

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

@@ -21,6 +21,19 @@
  */
 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 { 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 {
+    readonly tenant_id: string;
+    readonly device_id: string;
+    readonly seq: bigint;
+    readonly message_id: string;
+    readonly body: string;
+    readonly body_hash: string;
+    readonly byte_size: bigint;
+    readonly state: string;
+    readonly appended_at: string;
+}
+export declare function toMailboxMessage(row: OutboxRow): MailboxMessage;
 export declare class PostgresMailboxStore implements MailboxStore {
     #private;
     constructor(pool: Pool, clock: Clock);

package/dist/stores/devices.d.ts

@@ -9,15 +9,20 @@
  * guessed. One row, two access paths, never two copies to keep in sync — a
  * stale pre-tenant index would be a revoked device that can still get a token.
  */
-import type { TenantId } from '@byok-sdk/core';
+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';
 export declare class PostgresDeviceDirectory implements DeviceDirectory {
     #private;
-    constructor(pool: Pool);
+    constructor(pool: Pool, clock?: Clock);
     register(tenant: TenantId, input: DeviceRegistration): Promise<DeviceRecord>;
     get(tenant: TenantId, deviceId: string): Promise<DeviceRecord | undefined>;
     revoke(tenant: TenantId, deviceId: string): Promise<void>;
+    recordCapabilities(tenant: TenantId, input: {
+        readonly deviceId: string;
+        readonly capabilities: readonly string[];
+    }): Promise<DeviceRecord | undefined>;
     list(tenant: TenantId): Promise<readonly DeviceRecord[]>;
+    readiness(tenant: TenantId, _presence: PresenceStore): Promise<TenantReadiness>;
     resolveByDeviceId(deviceId: string): Promise<DeviceRecord | undefined>;
 }

package/dist/stores/index.d.ts

@@ -31,13 +31,15 @@ export { PostgresPairingCodeStore } from './pairing-codes';
 export { PostgresRequestReceiptStore } from './receipts';
 export { PostgresProofRequestReceiptStore } from './proof-receipts';
 export { PostgresTaskAttemptStore } from './task-attempts';
+export { PostgresTaskCancellationStore } from './task-cancellations';
 export { PostgresActivityStore } from './activity';
 export { PostgresApprovalTimelineStore } from './approval-timeline';
+export { PostgresAgentEgressStore } from './agent-egress';
 export { PostgresDeviceAssertionReplayAuthority } from './device-assertion-replay';
 export { DEFAULT_MAX_ATTEMPTS, DEFAULT_PRESIGN_TTL_SECONDS, DEFAULT_RETRY_DELAY_MS, MAX_PRESIGN_TTL_SECONDS, MIN_PRESIGN_TTL_SECONDS, ObjectStoreRequestError, R2_BLOB_ERROR_CODES, R2BlobStoreError, R2CloudBlobStore, R2ObjectMaintenanceStore, } from './r2-blobs';
 export type { ObjectStoreFetch, R2BlobErrorCode, R2BlobStoreOptions } from './r2-blobs';
 export type { R2DeleteResult, R2ListedObject, R2ObjectMaintenance, R2ObjectMaintenanceOptions, R2ObjectPage, } from './r2-blobs';
-/** Every cloud-local port. All eleven, or it is not a composition. */
+/** Every cloud-local port. All twelve, or it is not a composition. */
 export type PostgresCloudStores = CloudStores;
 /** Everything the blob store needs that is not already a composition-wide input. */
 export type PostgresObjectStorageOptions = Omit<R2BlobStoreOptions, 'objects'>;

package/dist/stores/r2-blobs.d.ts

@@ -179,7 +179,7 @@ export interface R2BlobStoreOptions {
 /** One tenant-prefixed R2 key returned by ListObjectsV2. */
 export interface R2ListedObject {
     readonly key: string;
-    /** Present only when the key is exactly `<tenant>/sha256/<64 lowercase hex>`. */
+    /** Present only when the key is exactly `tenants/<tenant>/objects/sha256/<64 lowercase hex>`. */
     readonly hash?: ContentHash;
     readonly byteSize: bigint;
 }

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

@@ -14,17 +14,43 @@
  * `claim` and `recordStatus` on a task this tenant never offered write nothing
  * and return `undefined`.
  */
-import type { TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '@byok-sdk/cloud';
+import type { AgentRef, TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '@byok-sdk/cloud';
 import type { Clock, TenantId } from '@byok-sdk/core';
 import type { Pool } from 'pg';
+export interface TaskRow {
+    readonly tenant_id: string;
+    readonly task_id: string;
+    readonly device_id: string;
+    readonly agent_id: string | null;
+    readonly agent_profile_revision: string | null;
+    readonly owner_device_id: string | null;
+    readonly status: string;
+    readonly terminal_cause: string | null;
+    readonly cancel_requested_at: Date | null;
+    readonly cancel_reason: string | null;
+    readonly cancel_message_id: string | 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 function taskRowToAttempt(row: TaskRow): TaskAttempt;
 export declare class PostgresTaskAttemptStore implements TaskAttemptStore {
     #private;
     constructor(pool: Pool, clock: Clock);
     open(tenant: TenantId, input: {
         readonly taskId: string;
         readonly deviceId: string;
+        readonly agentRef?: AgentRef;
     }): Promise<TaskAttempt>;
+    reserveAgentOffer(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly agentRef: AgentRef;
+    }): Promise<{
+        readonly attempt: TaskAttempt;
+        readonly created: boolean;
+    }>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
+    getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     claim(tenant: TenantId, input: {
         readonly taskId: string;
         readonly deviceId: string;
@@ -32,5 +58,7 @@ export declare class PostgresTaskAttemptStore implements TaskAttemptStore {
     recordStatus(tenant: TenantId, input: {
         readonly taskId: string;
         readonly status: TaskAttemptStatus;
+        readonly agentRef?: AgentRef;
+        readonly terminalCause?: string;
     }): Promise<TaskAttempt | undefined>;
 }

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

@@ -0,0 +1,9 @@
+import type { TaskCancellationMutation, TaskCancellationRequest, TaskCancellationStore } from '@byok-sdk/cloud';
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+/** PostgreSQL atomic authority for host cancellation state plus mailbox delivery. */
+export declare class PostgresTaskCancellationStore implements TaskCancellationStore {
+    #private;
+    constructor(pool: Pool, clock: Clock);
+    request(tenant: TenantId, input: TaskCancellationRequest): Promise<TaskCancellationMutation | undefined>;
+}

package/dist/tenant-erasure.d.ts

@@ -0,0 +1,77 @@
+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 0013, 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_egress_event', 'device_request_receipts', 'proof_request_receipt', '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';
+    readonly tenant_erasure_object_key_invalid: 'tenant_erasure_object_key_invalid';
+    readonly tenant_erasure_storage_failure: 'tenant_erasure_storage_failure';
+    readonly tenant_erasure_database_failure: 'tenant_erasure_database_failure';
+    readonly tenant_erasure_cas_lost: 'tenant_erasure_cas_lost';
+};
+export type TenantErasureErrorCode = (typeof TENANT_ERASURE_ERROR_CODES)[keyof typeof TENANT_ERASURE_ERROR_CODES];
+export declare class TenantErasureError extends Error {
+    readonly code: TenantErasureErrorCode;
+    constructor(code: TenantErasureErrorCode, message: string, options?: ErrorOptions);
+}
+export type TenantErasureStatus = 'outstanding' | 'partial' | 'completed';
+export interface TenantErasureReadback {
+    readonly status: TenantErasureStatus;
+    readonly tenantId: TenantId;
+    readonly operationId: string;
+    readonly startedAt: string;
+    readonly updatedAt: string;
+    readonly completedAt?: string;
+    readonly r2Complete: boolean;
+    readonly sqlTableIndex: number;
+    readonly r2ObjectsDeleted: bigint;
+    readonly sqlRowsDeleted: bigint;
+    /** A closed, audit-safe class. Remote messages and object names are never retained. */
+    readonly errorCode?: TenantErasureErrorCode;
+}
+export interface TenantErasureConflict {
+    readonly status: 'conflict';
+    readonly tenantId: TenantId;
+    readonly operationId: string;
+    readonly activeOperationId: string;
+}
+export type TenantErasureResult = TenantErasureReadback | TenantErasureConflict;
+export interface PostgresTenantErasureOptions {
+    /** A Node direct-DSN pool. The host owns pool lifetime and write quiescence. */
+    readonly pool: Pool;
+    readonly clock: Clock;
+    readonly objectStorage: R2ObjectMaintenance;
+    /** ListObjectsV2 and one SQL DELETE use this bound; valid range is 1..1000. */
+    readonly batchSize?: number;
+    /** Maximum R2/SQL pages one operator invocation may advance; valid range is 1..100. */
+    readonly maxPagesPerRun?: number;
+    /** Crash-recovery lease; a retry may take an expired lease using the operation CAS. */
+    readonly leaseMs?: number;
+}
+export interface PostgresTenantErasureCompositionOptions {
+    readonly pool: Pool;
+    readonly clock: Clock;
+    readonly objectStorage: Omit<R2BlobStoreOptions, 'objects'>;
+    readonly batchSize?: number;
+    readonly maxPagesPerRun?: number;
+    readonly leaseMs?: number;
+}
+/**
+ * The Node-only erasure authority. It has no raw-table or raw-key API: the
+ * static inventory and canonical R2 adapter are the only deletion authority.
+ */
+export declare class PostgresTenantErasure {
+    #private;
+    constructor(options: PostgresTenantErasureOptions);
+    /** Read a durable operation receipt without advancing it. */
+    readTenantErasure(tenant: TenantId, operationId: string): Promise<TenantErasureReadback | undefined>;
+    /**
+     * Advance one bounded operation slice. Calls with a completed id replay its
+     * receipt; another running id for the same tenant gets a typed conflict.
+     */
+    eraseTenant(tenant: TenantId, operationId: string): Promise<TenantErasureResult>;
+}
+/** Build the Node maintenance composition against the same direct Postgres/R2 authorities. */
+export declare function createPostgresTenantErasure(options: PostgresTenantErasureCompositionOptions): PostgresTenantErasure;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/cloud-dataplane",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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.5.0",
-    "@byok-sdk/core": "0.5.0",
-    "@byok-sdk/protocol": "0.5.0",
+    "@byok-sdk/cloud": "0.6.1",
+    "@byok-sdk/core": "0.6.1",
+    "@byok-sdk/protocol": "0.6.1",
     "aws4fetch": "1.0.20",
     "fast-xml-parser": "^5.10.1",
     "pg": "^8.22.0"