@byok-sdk/core 0.26.0 → 0.27.0-rc.2

package/README.md

@@ -16,3 +16,5 @@ hosted production composition must inject durable atomic storage. The assertion
 authorizes one exchange only and is not a connector session or refresh token.
 
 MIT licensed. Node.js 24.15.0 or newer.
+
+Runtime dependencies and size budgets: [entry dependency contract](../../README.md#entry-dependencies).

package/dist/blob.d.ts

@@ -1,3 +1,4 @@
+import type { CollectExpiredInput, CollectExpiredResult } from './retention';
 import type { TenantId } from './tenant';
 /** `sha256:<64 lowercase hex>`. The only content-address form core accepts. */
 export declare const CONTENT_HASH_PATTERN: RegExp;
@@ -141,6 +142,7 @@ export interface ObjectListQuery {
  * `deletePendingBefore` is not a canonical ISO-8601 UTC instant).
  */
 export interface ObjectStore {
+    collectExpired(tenant: TenantId, input: ObjectCollectExpiredInput): Promise<CollectExpiredResult>;
     /** Creates or returns the `pending` row for `hash`. Idempotent per (tenant, hash). */
     putManifest(tenant: TenantId, input: ObjectManifestInput): Promise<ObjectManifestEntry>;
     /** `pending` → `committed` after verifying observed size/type. */
@@ -155,3 +157,6 @@ export interface ObjectStore {
     /** Tombstone step 3: the object store delete succeeded. */
     markDeleted(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry>;
 }
+export interface ObjectCollectExpiredInput extends CollectExpiredInput {
+    readonly orphanBefore: string;
+}

package/dist/device-assertion.d.ts

@@ -1,3 +1,4 @@
+import type { CollectExpiredInput, CollectExpiredResult } from './retention';
 /**
  * Device assertion envelope, canonical signing bytes, and verifier
  * (plan `device-assertion-broker`, P3 ①-⑤).
@@ -289,6 +290,7 @@ export interface DeviceAssertionReplayConsumeInput {
  * never be translated into authenticated success.
  */
 export interface DeviceAssertionReplayAuthority {
+    collectExpired(tenant: TenantId, input: CollectExpiredInput): Promise<CollectExpiredResult>;
     consume(input: DeviceAssertionReplayConsumeInput): Promise<boolean>;
 }
 export interface AuthenticateDeviceAssertionDeps {

package/dist/errors.d.ts

@@ -29,6 +29,8 @@
  * - the five `storage_*` codes (§12.7.7, see `quota.ts`)
  */
 export declare const CORE_ERROR_CODES: {
+    readonly retention_input_invalid: 'retention_input_invalid';
+    readonly retention_collect_failed: 'retention_collect_failed';
     readonly tenant_id_invalid: 'tenant_id_invalid';
     readonly content_hash_invalid: 'content_hash_invalid';
     readonly timestamp_not_canonical: 'timestamp_not_canonical';

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

@@ -1,3 +1,6 @@
+import { InMemoryStorageLedger } from './storage-ledger';
+import { type CollectExpiredResult } from '../retention';
+import type { ObjectCollectExpiredInput } from '../blob';
 /**
  * In-memory {@link ObjectStore} reference (§12.7.4, §12.7.8).
  *
@@ -12,7 +15,11 @@ import type { Clock } from '../stores';
 import { type TenantId } from '../tenant';
 export declare class InMemoryObjectStore implements ObjectStore {
     #private;
-    constructor(clock: Clock);
+    private readonly maintenance;
+    constructor(clock: Clock, maintenance: {
+        readonly ledger: InMemoryStorageLedger;
+        readonly bytes: InMemoryObjectBytes;
+    });
     putManifest(tenant: TenantId, input: ObjectManifestInput): Promise<ObjectManifestEntry>;
     commit(tenant: TenantId, input: ObjectCommitInput): Promise<ObjectManifestEntry>;
     get(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry | undefined>;
@@ -21,4 +28,8 @@ export declare class InMemoryObjectStore implements ObjectStore {
     removeReference(tenant: TenantId, input: ObjectReferenceInput): Promise<ObjectManifestEntry>;
     markDeletePending(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry>;
     markDeleted(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry>;
+    collectExpired(tenant: TenantId, input: ObjectCollectExpiredInput): Promise<CollectExpiredResult>;
+}
+export interface InMemoryObjectBytes {
+    deleteObject(tenant: TenantId, hash: ContentHash): void;
 }

package/dist/in-memory/device-assertion-replay.d.ts

@@ -1,8 +1,9 @@
+import { type CollectExpiredInput, type CollectExpiredResult } from '../retention';
+import type { TenantId } from '../tenant';
 import type { DeviceAssertionReplayConsumeInput, DeviceAssertionReplayAuthority } from '../device-assertion';
 /** Process-local reference authority. Production runtimes need durable atomic storage. */
 export declare class InMemoryDeviceAssertionReplayAuthority implements DeviceAssertionReplayAuthority {
     #private;
     consume(input: DeviceAssertionReplayConsumeInput): Promise<boolean>;
-    /** Delete at most `limit` keys whose assertion lifetime ended at or before `before`. */
-    deleteExpired(before: Date, limit: number): Promise<number>;
+    collectExpired(tenant: TenantId, input: CollectExpiredInput): Promise<CollectExpiredResult>;
 }

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

@@ -1,3 +1,4 @@
+import type { InMemoryObjectBytes } from './blob';
 import type { Clock, CoreStores, MutableClock } from '../stores';
 export { createMutableClock, IN_MEMORY_CLOCK_EPOCH } from './clock';
 export { InMemoryMailboxStore } from './mailbox';
@@ -9,6 +10,7 @@ export { InMemoryQuotaStore } from './quota';
 export { InMemorySkillPackStore } from './skill-pack';
 export { InMemoryDeviceAssertionReplayAuthority } from './device-assertion-replay';
 export interface InMemoryCoreOptions {
+    readonly objectBytes: InMemoryObjectBytes;
     /** Defaults to a fresh {@link createMutableClock}, so TTL behavior is deterministic. */
     readonly clock?: Clock;
 }
@@ -17,9 +19,11 @@ export interface InMemoryCoreComposition {
     /** The clock the stores read. Mutable only when the caller did not inject its own. */
     readonly clock: Clock;
 }
-export declare function createInMemoryCoreStores(options?: InMemoryCoreOptions): InMemoryCoreComposition;
+export declare function createInMemoryCoreStores(options: InMemoryCoreOptions): InMemoryCoreComposition;
 /** Convenience for tests that need to move time: returns the composition and its mutable clock. */
-export declare function createInMemoryCoreCompositionWithClock(): {
+export declare function createInMemoryCoreCompositionWithClock(objectBytes: InMemoryObjectBytes): {
     readonly stores: CoreStores;
     readonly clock: MutableClock;
 };
+export { InMemoryStorageLedger } from './storage-ledger';
+export type { InMemoryObjectBytes } from './blob';

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

@@ -1,13 +1,17 @@
-import type { MailboxAdvanceCursorInput, MailboxAppendInput, MailboxCursorState, MailboxMessage, MailboxPage, MailboxReadQuery, MailboxRecordDeliveryInput, MailboxRetentionInput, MailboxRetentionResult, MailboxStore } from '../mailbox';
+import { type CollectExpiredResult } from '../retention';
+import type { MailboxAdvanceCursorInput, MailboxAppendInput, MailboxCursorState, MailboxMessage, MailboxPage, MailboxReadQuery, MailboxRecordDeliveryInput, MailboxCollectExpiredInput, MailboxStore, MailboxUsage } from '../mailbox';
+import type { QuotaStore } from '../quota';
 import type { Clock } from '../stores';
 import { type TenantId } from '../tenant';
 export declare class InMemoryMailboxStore implements MailboxStore {
     #private;
-    constructor(clock: Clock);
+    /** The mailbox reads its limit from quota; quota never reads the mailbox. */
+    constructor(clock: Clock, quota: Pick<QuotaStore, 'readEntitlement'>);
     append(tenant: TenantId, input: MailboxAppendInput): Promise<MailboxMessage>;
+    readUsage(tenant: TenantId): Promise<MailboxUsage>;
     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>;
+    collectExpired(tenant: TenantId, input: MailboxCollectExpiredInput): Promise<CollectExpiredResult>;
 }

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

@@ -1,3 +1,4 @@
+import { type CollectExpiredInput, type CollectExpiredResult } from '../retention';
 import { type PresenceHint, type PresenceHintInput, type PresenceStore } from '../presence';
 import type { Clock } from '../stores';
 import { type TenantId } from '../tenant';
@@ -7,4 +8,5 @@ export declare class InMemoryPresenceStore implements PresenceStore {
     publish(tenant: TenantId, input: PresenceHintInput): Promise<PresenceHint>;
     read(tenant: TenantId, deviceId: string): Promise<PresenceHint | undefined>;
     list(tenant: TenantId): Promise<readonly PresenceHint[]>;
+    collectExpired(tenant: TenantId, input: CollectExpiredInput): Promise<CollectExpiredResult>;
 }

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

@@ -1,10 +1,14 @@
+import { InMemoryStorageLedger } from './storage-ledger';
+import { type CollectExpiredResult } from '../retention';
+import type { QuotaCollectExpiredInput } from '../quota';
 import type { ObjectStore } from '../blob';
-import type { MailboxUsageDeltaInput, StorageFinalizeInput, StorageFinalizeResult, StorageReservation, StorageReservationInput, StorageStatus, QuotaStore, TenantStorageEntitlement, TenantStorageEntitlementInput, TenantStorageUsage } from '../quota';
+import type { StorageFinalizeInput, StorageFinalizeResult, StorageReservation, StorageReservationInput, StorageStatus, QuotaStore, TenantStorageEntitlement, TenantStorageEntitlementInput, TenantStorageUsage } from '../quota';
 import type { Clock } from '../stores';
 import { type TenantId } from '../tenant';
 export declare class InMemoryQuotaStore implements QuotaStore {
     #private;
-    constructor(clock: Clock, objects: ObjectStore);
+    private readonly ledger;
+    constructor(clock: Clock, objects: ObjectStore, ledger: InMemoryStorageLedger);
     readEntitlement(tenant: TenantId): Promise<TenantStorageEntitlement | undefined>;
     writeEntitlement(tenant: TenantId, input: TenantStorageEntitlementInput): Promise<TenantStorageEntitlement>;
     readUsage(tenant: TenantId): Promise<TenantStorageUsage>;
@@ -13,6 +17,5 @@ export declare class InMemoryQuotaStore implements QuotaStore {
     reserve(tenant: TenantId, input: StorageReservationInput): Promise<StorageReservation>;
     finalizeReservation(tenant: TenantId, input: StorageFinalizeInput): Promise<StorageFinalizeResult>;
     abortReservation(tenant: TenantId, reservationId: string): Promise<StorageReservation>;
-    expireReservations(tenant: TenantId): Promise<readonly StorageReservation[]>;
-    applyMailboxDelta(tenant: TenantId, input: MailboxUsageDeltaInput): Promise<TenantStorageUsage>;
+    collectExpired(tenant: TenantId, input: QuotaCollectExpiredInput): Promise<CollectExpiredResult>;
 }

package/dist/in-memory/storage-ledger.d.ts

@@ -0,0 +1,29 @@
+import type { Clock } from '../stores';
+import type { ContentHash } from '../blob';
+import type { StorageReservation, TenantStorageUsage } from '../quota';
+import type { TenantId } from '../tenant';
+export interface ReservationRecord {
+    readonly reservation: StorageReservation;
+    readonly deduplicated: boolean;
+}
+/** Shared authority for reservations, object accounting and quota reads. */
+export declare class InMemoryStorageLedger {
+    #private;
+    private readonly clock;
+    constructor(clock: Clock);
+    readReservation(key: string): ReservationRecord | undefined;
+    writeReservation(key: string, record: ReservationRecord): void;
+    deleteReservation(key: string): void;
+    reservations(): IterableIterator<[string, ReservationRecord]>;
+    readUsage(tenant: TenantId): TenantStorageUsage;
+    writeUsage(tenant: TenantId, usage: TenantStorageUsage): void;
+    isCounted(tenant: TenantId, hash: string): boolean;
+    recordCommitted(tenant: TenantId, reservation: StorageReservation): void;
+    hasReservedObject(tenant: TenantId, hash: ContentHash): boolean;
+    reservedObjectHashes(tenant: TenantId): readonly string[];
+    prepareCollectedObjectRelease(tenant: TenantId, hash: ContentHash, byteSize: bigint, now: string): {
+        readonly releasedBytes: bigint;
+        readonly commit: () => void;
+    };
+    releaseCollectedObject(tenant: TenantId, hash: ContentHash, byteSize: bigint, now: string): bigint;
+}

package/dist/index.d.ts

@@ -20,7 +20,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, MailboxRecordDeliveryInput, MailboxRetentionInput, MailboxRetentionResult, MailboxStore, } from './mailbox';
+export type { MailboxAdmission, MailboxAdvanceCursorInput, MailboxAppendInput, MailboxBody, MailboxCursorState, MailboxMessage, MailboxMessageState, MailboxPage, MailboxReadQuery, MailboxRecordDeliveryInput, MailboxCollectExpiredInput, MailboxStore, MailboxUsage, } 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';
@@ -30,7 +30,7 @@ export type { PresenceHint, PresenceHintInput, PresenceLevel, PresenceRuntimeFac
 export { CONTENT_HASH_PATTERN, OBJECT_KEY_PREFIX_PATTERN, OBJECT_STATES, OBJECT_STATE_TRANSITIONS, contentHash, isContentHash, isLegalObjectTransition, objectKeyPrefix, tenantObjectKey, } from './blob';
 export type { ContentHash, ObjectCommitInput, ObjectKeyPrefix, ObjectListQuery, ObjectManifestEntry, ObjectManifestInput, ObjectReference, ObjectReferenceInput, ObjectState, ObjectStore, } from './blob';
 export { STORAGE_ERROR_CODES, STORAGE_ERROR_HTTP_STATUS, STORAGE_RESERVATION_STATES, STORAGE_WRITE_KINDS, STORAGE_WRITE_POSTURES, } from './quota';
-export type { MailboxUsageDeltaInput, QuotaStore, StorageErrorCode, StorageFinalizeInput, StorageFinalizeResult, StorageReservation, StorageReservationInput, StorageReservationState, StorageStatus, StorageWriteKind, StorageWritePosture, TenantStorageEntitlement, TenantStorageEntitlementInput, TenantStorageUsage, } from './quota';
+export type { QuotaStore, StorageErrorCode, StorageFinalizeInput, StorageFinalizeResult, StorageReservation, StorageReservationInput, StorageReservationState, StorageStatus, StorageWriteKind, StorageWritePosture, TenantStorageEntitlement, TenantStorageEntitlementInput, TenantStorageUsage, } from './quota';
 export { CAPABILITY_DECLARATION_SCHEMA_ID, CAPABILITY_NAME_PATTERN, CapabilityDeclarationSchema, assertCapability, hasCapability, parseCapabilityDeclaration, } from './capabilities';
 export type { CapabilityDeclaration } from './capabilities';
 export { SKILL_FRONTMATTER_FIELDS, SKILL_PACK_DESCRIPTION_MAX_LENGTH, SKILL_PACK_ENTRY_PATH, SKILL_PACK_FILE_MAX_BYTES, SKILL_PACK_FILE_PATH_MAX_LENGTH, SKILL_PACK_FILE_PATH_PATTERN, SKILL_PACK_FORBIDDEN_FIELDS, SKILL_PACK_MANIFEST_SCHEMA_ID, SKILL_PACK_MAX_BYTES, SKILL_PACK_MAX_FILES, SKILL_PACK_NAME_MAX_LENGTH, SKILL_PACK_NAME_PATTERN, SKILL_PACK_REJECTIONS, SKILL_PACK_VERSION_PATTERN, SkillPackFileSchema, SkillPackManifestSchema, checkSkillPackEntry, checkSkillPackFileContent, checkSkillPackManifest, isSkillPackPathSafe, parseSkillFrontmatter, parseSkillPackManifest, skillPackContentHashInput, } from './skill-pack';
@@ -50,3 +50,9 @@ export type { AgentMemoryIntentDigestInput } from './agent-memory-intent';
 export { NONCE_SIGNING_DOMAIN, nonceSigningBytes } from './pairing';
 export { IN_MEMORY_CLOCK_EPOCH, InMemoryBoardStore, InMemoryMailboxStore, InMemoryDeviceAssertionReplayAuthority, InMemoryObjectStore, InMemoryPresenceStore, InMemoryQuotaStore, InMemorySkillPackStore, InMemoryTruthStore, createInMemoryCoreStores, createInMemoryCoreCompositionWithClock, createMutableClock, } from './in-memory/index';
 export type { InMemoryCoreComposition, InMemoryCoreOptions } from './in-memory/index';
+export { assertCollectExpiredInput, CollectExpiredFailure } from './retention';
+export type { CollectExpiredInput, CollectExpiredCounts, CollectExpiredResult } from './retention';
+export type { QuotaCollectExpiredInput } from './quota';
+export type { ObjectCollectExpiredInput } from './blob';
+export { InMemoryStorageLedger } from './in-memory/storage-ledger';
+export type { InMemoryObjectBytes } from './in-memory/blob';