@byok-sdk/cloud 0.4.2 → 0.6.0

package/dist/stores/in-memory/device-directory.d.ts

@@ -7,7 +7,7 @@
  * so a revocation applied through the composite key is immediately visible to
  * `/byok/challenge` and `/byok/token` with no second copy to keep in sync.
  */
-import { type TenantId } from '@byok-sdk/core';
+import { type PresenceStore, type TenantId, type TenantReadiness } from '@byok-sdk/core';
 import type { DeviceDirectory, DeviceRecord, DeviceRegistration } from '../ports';
 export declare class InMemoryDeviceDirectory implements DeviceDirectory {
     #private;
@@ -15,5 +15,6 @@ export declare class InMemoryDeviceDirectory implements DeviceDirectory {
     get(tenant: TenantId, deviceId: string): Promise<DeviceRecord | undefined>;
     revoke(tenant: TenantId, deviceId: string): Promise<void>;
     list(tenant: TenantId): Promise<readonly DeviceRecord[]>;
+    readiness(tenant: TenantId, presence: PresenceStore): Promise<TenantReadiness>;
     resolveByDeviceId(deviceId: string): Promise<DeviceRecord | undefined>;
 }

package/dist/stores/in-memory/index.d.ts

@@ -19,6 +19,7 @@ export { InMemoryPairingCodeStore } from './pairing-codes';
 export { InMemoryRequestReceiptStore } from './receipts';
 export { InMemoryProofRequestReceiptStore } from './proof-receipts';
 export { InMemoryTaskAttemptStore } from './task-attempts';
+export { InMemoryTaskCancellationStore } from './task-cancellations';
 export { InMemoryActivityStore } from './activity';
 export { InMemoryApprovalTimelineStore } from './approval-timeline';
 /**
@@ -34,4 +35,4 @@ export interface InMemoryCloudComposition {
     readonly stores: CloudStores;
     readonly blobContentProxy: BlobContentProxy;
 }
-export declare function createInMemoryCloudStores(clock: Clock, crypto: CloudCrypto, objects: ObjectStore): InMemoryCloudComposition;
+export declare function createInMemoryCloudStores(clock: Clock, crypto: CloudCrypto, objects: ObjectStore, mailbox: import('@byok-sdk/core').MailboxStore): InMemoryCloudComposition;

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

@@ -19,12 +19,13 @@ import { type Clock, type TenantId } from '@byok-sdk/core';
 import type { TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '../ports';
 export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
     #private;
-    constructor(clock: Clock);
+    constructor(clock: Clock, state?: InMemoryTaskAttemptState);
     open(tenant: TenantId, input: {
         taskId: string;
         deviceId: string;
     }): Promise<TaskAttempt>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
+    getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     claim(tenant: TenantId, input: {
         taskId: string;
         deviceId: string;
@@ -34,3 +35,12 @@ export declare class InMemoryTaskAttemptStore implements TaskAttemptStore {
         status: TaskAttemptStatus;
     }): Promise<TaskAttempt | undefined>;
 }
+/** Shared mutable state for the task and cancellation reference ports. */
+export declare class InMemoryTaskAttemptState {
+    #private;
+    readonly attempts: Map<string, TaskAttempt>;
+    constructor(clock: Clock);
+    now(): string;
+    /** Serialize every state-changing operation for one tenant/task key. */
+    mutate<T>(key: string, operation: () => T | Promise<T>): Promise<T>;
+}

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

@@ -0,0 +1,9 @@
+import { type MailboxStore, type TenantId } from '@byok-sdk/core';
+import type { TaskCancellationMutation, TaskCancellationRequest, TaskCancellationStore } from '../ports';
+import { InMemoryTaskAttemptState } from './task-attempts';
+/** Failure-free reference composition of the atomic cancellation port. */
+export declare class InMemoryTaskCancellationStore implements TaskCancellationStore {
+    #private;
+    constructor(state: InMemoryTaskAttemptState, mailbox: MailboxStore);
+    request(tenant: TenantId, input: TaskCancellationRequest): Promise<TaskCancellationMutation | undefined>;
+}

package/dist/stores/ports.d.ts

@@ -34,7 +34,7 @@
  * because a composition backed by object storage physically cannot proxy
  * bytes (see the blobs section below).
  */
-import type { StorageReservation, TenantId } from '@byok-sdk/core';
+import type { MailboxBody, MailboxMessage, PresenceStore, StorageReservation, TenantId, TenantReadiness } from '@byok-sdk/core';
 import type { ActivityStore } from '../activity';
 import type { ApprovalTimelineStore } from '../approval-timeline';
 export interface DeviceRecord {
@@ -65,6 +65,8 @@ export interface DeviceDirectory {
     get(tenant: TenantId, deviceId: string): Promise<DeviceRecord | undefined>;
     revoke(tenant: TenantId, deviceId: string): Promise<void>;
     list(tenant: TenantId): Promise<readonly DeviceRecord[]>;
+    /** Set-wise tenant observation; revoked devices never contribute presence. */
+    readiness(tenant: TenantId, presence: PresenceStore): Promise<TenantReadiness>;
     /** Pre-tenant. Two callers only: `POST /byok/challenge` and `POST /byok/token`. Never exposed through the tenant facade. */
     resolveByDeviceId(deviceId: string): Promise<DeviceRecord | undefined>;
 }
@@ -115,7 +117,7 @@ export interface InboundDedupStore {
      */
     checkAndRecord(tenant: TenantId, deviceId: string, envelopeId: string): Promise<boolean>;
 }
-export declare const TASK_ATTEMPT_STATUSES: readonly ['offered', 'claimed', 'running', 'complete', 'failed', 'cancelled'];
+export declare const TASK_ATTEMPT_STATUSES: readonly ['offered', 'claimed', 'running', 'cancel_requested', 'complete', 'failed', 'cancelled'];
 export type TaskAttemptStatus = (typeof TASK_ATTEMPT_STATUSES)[number];
 export interface TaskAttempt {
     readonly tenantId: TenantId;
@@ -125,6 +127,11 @@ export interface TaskAttempt {
     /** Set by `task.claim`, and only by the first one. Until then the task has no owner and the gate lets any of this tenant's devices through, matching the reference server. */
     readonly ownerDeviceId?: string;
     readonly status: TaskAttemptStatus;
+    /** Durable host cancellation authority. Its presence outranks later device terminal receipts. */
+    readonly cancellation?: {
+        readonly requestedAt: string;
+        readonly reason?: string;
+    };
     readonly updatedAt: string;
 }
 export interface TaskAttemptStore {
@@ -134,6 +141,8 @@ export interface TaskAttemptStore {
         readonly deviceId: string;
     }): Promise<TaskAttempt>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
+    /** Batch lookup used by mailbox projection; implementations must not turn one poll into N queries. */
+    getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     /** First claim wins the ownership; a later claim by the same device is idempotent. No-op (returns `undefined`) for a task this tenant never offered. */
     claim(tenant: TenantId, input: {
         readonly taskId: string;
@@ -145,6 +154,24 @@ export interface TaskAttemptStore {
         readonly status: TaskAttemptStatus;
     }): Promise<TaskAttempt | undefined>;
 }
+export interface TaskCancellationRequest {
+    readonly taskId: string;
+    readonly proposedMessageId: string;
+    readonly reason?: string;
+    readonly materialize: (seq: number, messageId: string) => MailboxBody | Promise<MailboxBody>;
+}
+export interface TaskCancellationMutation {
+    readonly attempt: TaskAttempt;
+    /** Absent only when the task was already complete or failed before cancellation. */
+    readonly message?: MailboxMessage;
+}
+/**
+ * One atomic authority for the cancellation tombstone plus its durable device
+ * delivery. Implementations must commit both or neither.
+ */
+export interface TaskCancellationStore {
+    request(tenant: TenantId, input: TaskCancellationRequest): Promise<TaskCancellationMutation | undefined>;
+}
 export interface RequestReceipt {
     readonly tenantId: TenantId;
     readonly key: string;
@@ -288,11 +315,12 @@ export interface CloudStores {
     readonly nonces: NonceStore;
     readonly dedup: InboundDedupStore;
     readonly tasks: TaskAttemptStore;
+    readonly cancellations: TaskCancellationStore;
     readonly receipts: RequestReceiptStore;
     readonly proofReceipts: ProofRequestReceiptStore;
     readonly blobs: CloudBlobStore;
     readonly rateLimiter: InboundRateLimiter;
 }
 /** Names of every port in {@link CloudStores}, in contract order. */
-export declare const CLOUD_STORE_NAMES: readonly ['activity', 'approvals', 'devices', 'pairingCodes', 'nonces', 'dedup', 'tasks', 'receipts', 'proofReceipts', 'blobs', 'rateLimiter'];
+export declare const CLOUD_STORE_NAMES: readonly ['activity', 'approvals', 'devices', 'pairingCodes', 'nonces', 'dedup', 'tasks', 'cancellations', 'receipts', 'proofReceipts', 'blobs', 'rateLimiter'];
 export type CloudStoreName = (typeof CLOUD_STORE_NAMES)[number];

package/dist/tenant-stores.d.ts

@@ -21,10 +21,10 @@
  * presigned blob calls) are deliberately absent from this surface: a
  * device-facing handler must not be able to reach them.
  */
-import { type BoardClaimInput, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type BoardStatusUpdateInput, type BoardUnclaimInput, type CoreStores, type MailboxAdvanceCursorInput, type MailboxAppendInput, type MailboxCursorState, type MailboxMessage, type MailboxPage, type MailboxReadQuery, type Principal, type PresenceHint, type PresenceHintInput, type StorageFinalizeInput, type StorageFinalizeResult, type StorageReservation, type StorageReservationInput, type TenantId } from '@byok-sdk/core';
+import { type BoardClaimInput, type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type BoardStatusUpdateInput, type BoardUnclaimInput, type CoreStores, type MailboxAdvanceCursorInput, type MailboxAppendInput, type MailboxCursorState, type MailboxMessage, type MailboxPage, type MailboxReadQuery, type Principal, type PresenceHint, type PresenceHintInput, type TenantReadiness, type StorageFinalizeInput, type StorageFinalizeResult, type StorageReservation, type StorageReservationInput, type TenantId } from '@byok-sdk/core';
 import type { ActivityAppendInput, ActivityTail } from './activity';
 import type { ApprovalTimelineAppendInput, ApprovalTimelineTail } from './approval-timeline';
-import type { BlobObservation, CloudStores, DeviceRecord, RequestReceipt, TaskAttempt, TaskAttemptStatus } from './stores/ports';
+import type { BlobObservation, CloudStores, DeviceRecord, RequestReceipt, TaskCancellationMutation, TaskCancellationRequest, TaskAttempt, TaskAttemptStatus } from './stores/ports';
 export interface TenantBoundMailbox {
     append(input: MailboxAppendInput): Promise<MailboxMessage>;
     /** Pure read. Never advances the cursor — the daemon's next poll is the only ack. */
@@ -57,6 +57,7 @@ export interface TenantBoundDevices {
     get(deviceId: string): Promise<DeviceRecord | undefined>;
     list(): Promise<readonly DeviceRecord[]>;
     revoke(deviceId: string): Promise<void>;
+    readiness(): Promise<TenantReadiness>;
 }
 export interface TenantBoundTaskAttempts {
     open(input: {
@@ -64,6 +65,7 @@ export interface TenantBoundTaskAttempts {
         readonly deviceId: string;
     }): Promise<TaskAttempt>;
     get(taskId: string): Promise<TaskAttempt | undefined>;
+    getMany(taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     claim(input: {
         readonly taskId: string;
         readonly deviceId: string;
@@ -73,6 +75,9 @@ export interface TenantBoundTaskAttempts {
         readonly status: TaskAttemptStatus;
     }): Promise<TaskAttempt | undefined>;
 }
+export interface TenantBoundTaskCancellations {
+    request(input: TaskCancellationRequest): Promise<TaskCancellationMutation | undefined>;
+}
 export interface TenantBoundDedup {
     checkAndRecord(deviceId: string, envelopeId: string): Promise<boolean>;
 }
@@ -113,6 +118,7 @@ export interface TenantStores {
     readonly approvals: TenantBoundApprovalTimeline;
     readonly devices: TenantBoundDevices;
     readonly tasks: TenantBoundTaskAttempts;
+    readonly cancellations: TenantBoundTaskCancellations;
     readonly dedup: TenantBoundDedup;
     readonly receipts: TenantBoundReceipts;
     readonly blobs: TenantBoundBlobs;

package/dist/terminal-result.d.ts

@@ -1,4 +1,4 @@
-import { type BlobRef } from '@byok-sdk/protocol';
+import { type BlobRef, type TerminalInferenceUsage } from '@byok-sdk/protocol';
 import type { RequestReceipt } from './stores/ports';
 /**
  * The typed terminal read model — the hosted counterpart of the embedded
@@ -20,6 +20,12 @@ export interface TerminalResult {
      * `resultDocument` extractor.
      */
     readonly document?: unknown;
+    /**
+     * Device/runtime terminal observation copied from the canonical winning
+     * receipt. It is telemetry only — never cloud storage usage, billing, quota
+     * or entitlement authority.
+     */
+    readonly usage?: TerminalInferenceUsage;
     readonly reason?: string;
     readonly retryable?: boolean;
     /** When the receipt store wrote the terminal fact — the first one, by its own first-write-wins rule. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/cloud",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "BYOK SDK hosted device surface: stateless frozen-v1 HTTP handlers over tenant-first @byok-sdk/core ports",
   "type": "module",
   "license": "MIT",
@@ -44,8 +44,8 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@byok-sdk/core": "0.4.2",
-    "@byok-sdk/protocol": "0.4.2",
+    "@byok-sdk/core": "0.6.0",
+    "@byok-sdk/protocol": "0.6.0",
     "hono": "^4.12.30",
     "zod": "^4.4.3"
   }