@byok-sdk/core 0.11.0 → 0.13.0

package/dist/errors.d.ts

@@ -39,6 +39,7 @@ export declare const CORE_ERROR_CODES: {
     readonly assertion_envelope_invalid: 'assertion_envelope_invalid';
     readonly mailbox_message_not_found: 'mailbox_message_not_found';
     readonly mailbox_cursor_regression: 'mailbox_cursor_regression';
+    readonly mailbox_cursor_ahead_of_delivery: 'mailbox_cursor_ahead_of_delivery';
     readonly board_item_not_found: 'board_item_not_found';
     readonly board_item_exists: 'board_item_exists';
     readonly board_transition_invalid: 'board_transition_invalid';

package/dist/in-memory/mailbox.d.ts

@@ -1,4 +1,4 @@
-import type { MailboxAdvanceCursorInput, MailboxAppendInput, MailboxCursorState, MailboxMessage, MailboxPage, MailboxReadQuery, MailboxRetentionInput, MailboxRetentionResult, MailboxStore } from '../mailbox';
+import type { MailboxAdvanceCursorInput, MailboxAppendInput, MailboxCursorState, MailboxMessage, MailboxPage, MailboxReadQuery, MailboxRecordDeliveryInput, MailboxRetentionInput, MailboxRetentionResult, MailboxStore } from '../mailbox';
 import type { Clock } from '../stores';
 import { type TenantId } from '../tenant';
 export declare class InMemoryMailboxStore implements MailboxStore {
@@ -7,6 +7,7 @@ export declare class InMemoryMailboxStore 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/index.d.ts

@@ -18,7 +18,7 @@ export { ByokCoreError, CoreConflictError, CORE_ERROR_CODES, isCoreError, isCore
 export type { CoreErrorCode } from './errors';
 export { CANONICAL_TIMESTAMP_PATTERN, assertCanonicalTimestamp, isCanonicalTimestamp, } from './time';
 export { MAILBOX_MESSAGE_STATES } from './mailbox';
-export type { MailboxAdvanceCursorInput, MailboxAppendInput, MailboxBody, MailboxCursorState, MailboxMessage, MailboxMessageState, MailboxPage, MailboxReadQuery, MailboxRetentionInput, MailboxRetentionResult, MailboxStore, } from './mailbox';
+export type { MailboxAdvanceCursorInput, MailboxAppendInput, MailboxBody, MailboxCursorState, MailboxMessage, MailboxMessageState, MailboxPage, MailboxReadQuery, MailboxRecordDeliveryInput, MailboxRetentionInput, MailboxRetentionResult, MailboxStore, } from './mailbox';
 export { BOARD_STATUSES, BOARD_TRANSITIONS, isLegalBoardTransition } from './board';
 export type { BoardAssignee, BoardClaimInput, BoardItem, BoardItemInput, BoardListQuery, BoardPage, BoardStatus, BoardStatusUpdateInput, BoardStore, BoardUnclaimInput, } from './board';
 export { TRUTH_RECORD_KINDS } from './truth';

package/dist/index.js

@@ -22,6 +22,7 @@ var CORE_ERROR_CODES = {
   // mailbox (§12.7.3)
   mailbox_message_not_found: "mailbox_message_not_found",
   mailbox_cursor_regression: "mailbox_cursor_regression",
+  mailbox_cursor_ahead_of_delivery: "mailbox_cursor_ahead_of_delivery",
   // board coordination (§12.3)
   board_item_not_found: "board_item_not_found",
   board_item_exists: "board_item_exists",
@@ -536,7 +537,7 @@ var CORE_STORE_NAMES = [
 // src/ports-contract.ts
 var CORE_NON_COMPOSITION_PORT_NAMES = [];
 var CORE_PORT_METHODS = {
-  mailbox: ["append", "readAfter", "advanceCursor", "readCursor", "collectRetired"],
+  mailbox: ["append", "readAfter", "recordDelivery", "advanceCursor", "readCursor", "collectRetired"],
   board: ["create", "get", "list", "claim", "unclaim", "updateStatus"],
   truth: ["writeTerminal", "writeSnapshot", "getRecord", "listManifest"],
   presence: ["publish", "read", "list"],
@@ -1228,7 +1229,7 @@ var InMemoryMailboxStore = class {
     const device = this.#devices.get(tenantKey(tenant, query.deviceId));
     const limit = query.limit ?? DEFAULT_READ_LIMIT;
     if (device === void 0) {
-      return { messages: [], nextSeq: query.afterSeq, hasMore: false };
+      return { messages: [], nextSeq: query.afterSeq, hasMore: false, recoverableFrom: 1 };
     }
     const pending = device.messages.filter((message) => message.state === "pending" && message.seq > query.afterSeq).sort((left, right) => left.seq - right.seq);
     const page = pending.slice(0, limit);
@@ -1238,7 +1239,11 @@ var InMemoryMailboxStore = class {
       // Reading is not acknowledging: the returned position is a *read* cursor.
       // Nothing above was mutated, so an identical call replays the same page.
       nextSeq: last?.seq ?? query.afterSeq,
-      hasMore: pending.length > page.length
+      hasMore: pending.length > page.length,
+      // Computed over the WHOLE mailbox, not the queried slice: the floor is a
+      // property of the device's history, and reporting it relative to
+      // `afterSeq` would make every cursor look recoverable from itself.
+      recoverableFrom: this.#recoverableFrom(device)
     };
   }
   async advanceCursor(tenant, input) {
@@ -1252,6 +1257,14 @@ var InMemoryMailboxStore = class {
           this.#now()
         );
       }
+      if (input.ackedSeq > device.deliveredSeq) {
+        throw new CoreConflictError(
+          "mailbox_cursor_ahead_of_delivery",
+          `Cursor for device ${input.deviceId} was delivered through ${device.deliveredSeq}; refusing to acknowledge future cursor ${input.ackedSeq}.`,
+          this.#cursorState(tenant, input.deviceId, device),
+          this.#now()
+        );
+      }
       device.ackedSeq = input.ackedSeq;
       device.cursorUpdatedAt = this.#now();
       for (const [index, message] of device.messages.entries()) {
@@ -1268,10 +1281,24 @@ var InMemoryMailboxStore = class {
     );
     return advanced;
   }
+  async recordDelivery(tenant, input) {
+    const device = this.#device(tenant, input.deviceId);
+    const recorded = device.mutationTail.then(() => {
+      if (input.deliveredSeq > device.deliveredSeq) {
+        device.deliveredSeq = input.deliveredSeq;
+      }
+      return this.#cursorState(tenant, input.deviceId, device);
+    });
+    device.mutationTail = recorded.then(
+      () => void 0,
+      () => void 0
+    );
+    return recorded;
+  }
   async readCursor(tenant, deviceId) {
     const device = this.#devices.get(tenantKey(tenant, deviceId));
     if (device === void 0) {
-      return { tenantId: tenant, deviceId, ackedSeq: 0, updatedAt: this.#now() };
+      return { tenantId: tenant, deviceId, deliveredSeq: 0, ackedSeq: 0, updatedAt: this.#now() };
     }
     return this.#cursorState(tenant, deviceId, device);
   }
@@ -1312,6 +1339,7 @@ var InMemoryMailboxStore = class {
     if (existing !== void 0) return existing;
     const created = {
       nextSeq: 1,
+      deliveredSeq: 0,
       ackedSeq: 0,
       cursorUpdatedAt: this.#now(),
       mutationTail: Promise.resolve(),
@@ -1321,10 +1349,27 @@ var InMemoryMailboxStore = class {
     this.#devices.set(key, created);
     return created;
   }
+  /**
+   * One past the highest row this device lost, which is exactly the highest
+   * `expired` seq: dead-lettered rows are kept rather than deleted (§12.7.5),
+   * so the loss stays observable and needs no column of its own to remember it.
+   *
+   * `acked` is deliberately not counted. A consumed row is not a lost one, and
+   * counting it would turn a daemon re-polling from an old cursor — which the
+   * at-least-once contract explicitly allows — into a hard failure.
+   */
+  #recoverableFrom(device) {
+    let lost = 0;
+    for (const message of device.messages) {
+      if (message.state === "expired" && message.seq > lost) lost = message.seq;
+    }
+    return lost + 1;
+  }
   #cursorState(tenant, deviceId, device) {
     return {
       tenantId: tenant,
       deviceId,
+      deliveredSeq: device.deliveredSeq,
       ackedSeq: device.ackedSeq,
       updatedAt: device.cursorUpdatedAt
     };