@byok-sdk/core 0.26.1 → 0.27.0

package/dist/mailbox.d.ts

@@ -1,3 +1,4 @@
+import type { CollectExpiredInput, CollectExpiredResult } from './retention';
 /**
  * Hosted mailbox contract (§12.7.3).
  *
@@ -41,6 +42,22 @@ export interface MailboxBody {
     readonly bodyHash: ContentHash;
     readonly byteSize: bigint;
 }
+/**
+ * How an append is admitted against the tenant's `mailboxLimitBytes`.
+ *
+ * Mailbox bytes have one authority: the retained rows. Usage is the tenant's
+ * `SUM(byteSize)` over every retained row in any state, and the limit is
+ * checked in the same serialized unit that inserts the row — there is no
+ * counter for a writer to forget, so deleting a row needs no accounting.
+ *
+ * - `limited`: refused with `storage_quota_exceeded` when `used + byteSize`
+ *   exceeds the limit, and with `storage_entitlement_missing` when the tenant
+ *   has no entitlement. A refused append consumes no `seq`.
+ * - `cancellation`: always admitted and still counted. Reserved for the one
+ *   cancellation row a task can own, so a full mailbox never blocks
+ *   `cancelTask`.
+ */
+export type MailboxAdmission = 'limited' | 'cancellation';
 export interface MailboxAppendInput {
     readonly deviceId: string;
     /**
@@ -57,6 +74,16 @@ export interface MailboxAppendInput {
      * out of order and let an ack skip a late lower sequence.
      */
     readonly materialize: (seq: number) => MailboxBody | Promise<MailboxBody>;
+    /**
+     * Limit admission for a NEW row. An existing `messageId` returns its row
+     * before any check, so a retry is never refused for capacity.
+     */
+    readonly admission: MailboxAdmission;
+}
+/** Tenant mailbox usage, derived from the retained rows on every read. */
+export interface MailboxUsage {
+    /** `SUM(byteSize)` over every retained row (`pending`, `acked`, `expired`). */
+    readonly bytes: bigint;
 }
 export interface MailboxReadQuery {
     readonly deviceId: string;
@@ -90,7 +117,7 @@ export interface MailboxPage {
      * 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.
+     * `collectExpired` decides what is retained, this reports what it cost.
      */
     readonly recoverableFrom: number;
 }
@@ -123,18 +150,12 @@ export interface MailboxCursorState {
  * `timestamptz` comparison read differently is the worst place to guess — see
  * `time.ts`.
  */
-export interface MailboxRetentionInput {
-    readonly deviceId?: string;
+export interface MailboxCollectExpiredInput extends CollectExpiredInput {
     /** Acked rows appended before this instant are deleted. */
     readonly ackedBefore: string;
     /** Unacked rows appended before this instant move to `expired`, never deleted here. */
     readonly expireUnackedBefore: string;
 }
-export interface MailboxRetentionResult {
-    readonly deletedCount: number;
-    readonly expiredCount: number;
-    readonly releasedBytes: bigint;
-}
 /**
  * Mailbox port. Tenant-first, async.
  *
@@ -143,10 +164,13 @@ export interface MailboxRetentionResult {
  * `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).
+ * ISO-8601 UTC instant), `storage_quota_exceeded` and
+ * `storage_entitlement_missing` (a `limited` append refused at admission).
  */
 export interface MailboxStore {
     append(tenant: TenantId, input: MailboxAppendInput): Promise<MailboxMessage>;
+    /** The tenant's mailbox bytes, summed from the retained rows. */
+    readUsage(tenant: TenantId): Promise<MailboxUsage>;
     /** Pure read. Never advances the cursor, never deletes, never marks acked. */
     readAfter(tenant: TenantId, query: MailboxReadQuery): Promise<MailboxPage>;
     /** Records the highest cursor a device-facing response is about to return. */
@@ -155,5 +179,5 @@ export interface MailboxStore {
     advanceCursor(tenant: TenantId, input: MailboxAdvanceCursorInput): Promise<MailboxCursorState>;
     readCursor(tenant: TenantId, deviceId: string): Promise<MailboxCursorState>;
     /** Retention hook: delete acked rows, dead-letter unacked ones. */
-    collectRetired(tenant: TenantId, input: MailboxRetentionInput): Promise<MailboxRetentionResult>;
+    collectExpired(tenant: TenantId, input: MailboxCollectExpiredInput): Promise<CollectExpiredResult>;
 }

package/dist/presence.d.ts

@@ -1,3 +1,4 @@
+import type { CollectExpiredInput, CollectExpiredResult } from './retention';
 /**
  * Presence hints (§12.3).
  *
@@ -100,6 +101,7 @@ export interface PresenceHintInput {
  * expired hint is indistinguishable from one that was never written.
  */
 export interface PresenceStore {
+    collectExpired(tenant: TenantId, input: CollectExpiredInput): Promise<CollectExpiredResult>;
     publish(tenant: TenantId, input: PresenceHintInput): Promise<PresenceHint>;
     read(tenant: TenantId, deviceId: string): Promise<PresenceHint | undefined>;
     list(tenant: TenantId): Promise<readonly PresenceHint[]>;

package/dist/quota.d.ts

@@ -1,3 +1,4 @@
+import type { CollectExpiredInput, CollectExpiredResult } from './retention';
 /**
  * Tenant storage entitlement, usage, reservation and retention (§12.7.6-12.7.7).
  *
@@ -47,7 +48,6 @@ export interface TenantStorageUsage {
     committedObjectBytes: bigint;
     committedInlineBytes: bigint;
     reservedBytes: bigint;
-    mailboxBytes: bigint;
     objectCount: bigint;
     updatedAt: string;
 }
@@ -146,10 +146,6 @@ export declare const STORAGE_ERROR_HTTP_STATUS: {
     readonly storage_integrity_mismatch: 422;
     readonly storage_write_suspended: 423;
 };
-export interface MailboxUsageDeltaInput {
-    /** Signed. Negative deltas release bytes after retention deletes rows. */
-    readonly deltaBytes: bigint;
-}
 /**
  * Quota port. Tenant-first, async.
  *
@@ -158,6 +154,7 @@ export interface MailboxUsageDeltaInput {
  * `storage_reservation_not_found`, and the five wire-stable codes above.
  */
 export interface QuotaStore {
+    collectExpired(tenant: TenantId, input: QuotaCollectExpiredInput): Promise<CollectExpiredResult>;
     readEntitlement(tenant: TenantId): Promise<TenantStorageEntitlement | undefined>;
     /**
      * Version CAS: a write at or below the stored version is rejected with the
@@ -182,8 +179,7 @@ export interface QuotaStore {
     finalizeReservation(tenant: TenantId, input: StorageFinalizeInput): Promise<StorageFinalizeResult>;
     /** Idempotent release. Already-settled reservations return their settled row. */
     abortReservation(tenant: TenantId, reservationId: string): Promise<StorageReservation>;
-    /** Cleanup hook: expires reservations past their TTL and releases their bytes. */
-    expireReservations(tenant: TenantId): Promise<readonly StorageReservation[]>;
-    /** Mailbox bytes are platform-protection accounting, bounded by `mailboxLimitBytes`. */
-    applyMailboxDelta(tenant: TenantId, input: MailboxUsageDeltaInput): Promise<TenantStorageUsage>;
+}
+export interface QuotaCollectExpiredInput extends CollectExpiredInput {
+    readonly settledBefore: string;
 }

package/dist/retention.d.ts

@@ -0,0 +1,21 @@
+import { ByokCoreError } from './errors';
+export interface CollectExpiredInput {
+    readonly now: string;
+    readonly limit: number;
+}
+export interface CollectExpiredCounts {
+    readonly removed: number;
+    readonly expired: number;
+    readonly releasedBytes: bigint;
+}
+export interface CollectExpiredResult extends CollectExpiredCounts {
+    readonly more: boolean;
+}
+export declare function assertCollectExpiredInput(input: CollectExpiredInput): void;
+/** A committed partial result remains visible when external deletion fails. */
+export declare class CollectExpiredFailure extends ByokCoreError {
+    readonly committed: CollectExpiredCounts;
+    readonly failedRows: number;
+    readonly more?: boolean | undefined;
+    constructor(committed: CollectExpiredCounts, failedRows: number, more?: boolean | undefined, options?: ErrorOptions);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/core",
-  "version": "0.26.1",
+  "version": "0.27.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",