@byok-sdk/core 0.11.0 → 0.13.0

package/dist/mailbox.d.ts

@@ -73,16 +73,44 @@ export interface MailboxPage {
      */
     readonly nextSeq: number;
     readonly hasMore: boolean;
+    /**
+     * The earliest seq a reader can still recover from: one past the highest row
+     * this device LOST. A caller at `recoverableFrom - 1` can still be handed
+     * the first row it has any claim to; a caller below that has a gap it cannot
+     * see, and resuming it would hand back a partial tail indistinguishable from
+     * a complete one.
+     *
+     * Lost means `expired` — a row that aged out before anyone acked it. An
+     * `acked` row is consumed, not lost, so acking never moves this and never
+     * turns a re-poll from an old cursor into a failure; that distinction is the
+     * whole point of the field.
+     *
+     * `1` for a mailbox that has lost nothing, so a fresh device's cursor `0` is
+     * always inside the window. Monotonic for as long as dead-lettered rows are
+     * retained, which §12.7.5 requires.
+     *
+     * This is a READ of the retained window, never a second retention authority:
+     * `collectRetired` decides what is retained, this reports what it cost.
+     */
+    readonly recoverableFrom: number;
 }
 export interface MailboxAdvanceCursorInput {
     readonly deviceId: string;
     /** Highest seq the device has durably journaled. */
     readonly ackedSeq: number;
 }
-/** The device's durable acknowledgement position. */
+/** Server-owned proof that a cursor was returned to this device. */
+export interface MailboxRecordDeliveryInput {
+    readonly deviceId: string;
+    /** Highest cursor the server has returned to this device. */
+    readonly deliveredSeq: number;
+}
+/** The device's durable delivery and acknowledgement positions. */
 export interface MailboxCursorState {
     readonly tenantId: TenantId;
     readonly deviceId: string;
+    /** Highest cursor the server has returned to this device. */
+    readonly deliveredSeq: number;
     readonly ackedSeq: number;
     readonly updatedAt: string;
 }
@@ -112,6 +140,8 @@ export interface MailboxRetentionResult {
  *
  * Raises: `mailbox_cursor_regression` (an ack that moves the cursor backwards,
  * which would silently re-deliver already-journaled work),
+ * `mailbox_cursor_ahead_of_delivery` (an ack beyond the highest cursor the
+ * server has returned to that device),
  * `timestamp_not_canonical` (a retention cutoff that is not a canonical
  * ISO-8601 UTC instant).
  */
@@ -119,7 +149,9 @@ export interface MailboxStore {
     append(tenant: TenantId, input: MailboxAppendInput): Promise<MailboxMessage>;
     /** Pure read. Never advances the cursor, never deletes, never marks acked. */
     readAfter(tenant: TenantId, query: MailboxReadQuery): Promise<MailboxPage>;
-    /** The one and only ack. Monotonic; a lower `ackedSeq` is rejected. */
+    /** Records the highest cursor a device-facing response is about to return. */
+    recordDelivery(tenant: TenantId, input: MailboxRecordDeliveryInput): Promise<MailboxCursorState>;
+    /** The one and only ack. Monotonic and bounded by the recorded delivery watermark. */
     advanceCursor(tenant: TenantId, input: MailboxAdvanceCursorInput): Promise<MailboxCursorState>;
     readCursor(tenant: TenantId, deviceId: string): Promise<MailboxCursorState>;
     /** Retention hook: delete acked rows, dead-letter unacked ones. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/core",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "BYOK SDK platform contracts: branded tenant identity, tenant-first store ports, device proof canonicalization, and the composition conformance reference",
   "type": "module",
   "license": "MIT",