@lostgradient/weft 0.23.1 → 0.24.1

package/dist/core/mailbox-index-codec.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Encoding and fail-closed decoding for the application mailbox's index
+ * records (WFT-84): the per-mailbox header, idempotency bindings, and the
+ * entries of the delivery, listing, and terminal-retention indexes.
+ *
+ * Kept apart from the command-record codec so each stays under the repository's
+ * file ceiling while carrying its full rationale.
+ *
+ * @module core/mailbox-index-codec
+ */
+import type { ApplicationCommandIdempotencyRecord, MailboxRecord } from './mailbox-types.ts';
+/**
+ * Decode the per-mailbox header holding the FIFO allocator and backlog counter.
+ *
+ * @throws {PersistedDataCorruptError} When the stored bytes are malformed.
+ */
+export declare function decodeMailboxRecord(bytes: Uint8Array, key: string): MailboxRecord;
+/**
+ * Encode the per-mailbox header.
+ */
+export declare function encodeMailboxRecord(record: MailboxRecord): Uint8Array;
+/**
+ * Decode an idempotency index record.
+ *
+ * @throws {PersistedDataCorruptError} When the stored bytes are malformed.
+ */
+export declare function decodeApplicationCommandIdempotencyRecord(bytes: Uint8Array, key: string): ApplicationCommandIdempotencyRecord;
+/**
+ * Encode an idempotency index record.
+ */
+export declare function encodeApplicationCommandIdempotencyRecord(record: ApplicationCommandIdempotencyRecord): Uint8Array;
+/**
+ * Decode the command id stored in a FIFO delivery-index entry.
+ *
+ * @throws {PersistedDataCorruptError} When the entry is not a non-empty string.
+ */
+export declare function decodeApplicationReadyEntry(bytes: Uint8Array, key: string): string;
+/**
+ * Encode a FIFO delivery-index entry.
+ */
+export declare function encodeApplicationReadyEntry(commandId: string): Uint8Array;

package/dist/core/mailbox-index-codec.js

@@ -0,0 +1,71 @@
+import { KEYS } from "../storage/interface.js";
+import {
+  fail,
+  isRecordObject,
+  ownKey,
+  readIdentifier,
+  readInteger,
+  readString,
+  readVersion
+} from "./application-primitive-codec.js";
+import { decode, encode } from "./codec.js";
+import { MAILBOX_RECORD_VERSION } from "./mailbox-types.js";
+export function decodeMailboxRecord(bytes, key) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    fail(key);
+  }
+  if (!isRecordObject(decoded))
+    fail(key);
+  readVersion(decoded, key);
+  const namespace = readString(decoded, "namespace", key), resourceId = readString(decoded, "resourceId", key);
+  if (ownKey(() => KEYS.applicationMailbox(namespace, resourceId), key) !== key)
+    fail(key);
+  const nextSequence = readInteger(decoded, "nextSequence", key), openCount = readInteger(decoded, "openCount", key), admittedCount = readInteger(decoded, "admittedCount", key);
+  if (nextSequence !== admittedCount || openCount > admittedCount)
+    fail(key);
+  return {
+    recordVersion: MAILBOX_RECORD_VERSION,
+    namespace,
+    resourceId,
+    nextSequence,
+    openCount,
+    admittedCount
+  };
+}
+export function encodeMailboxRecord(record) {
+  return encode(record);
+}
+export function decodeApplicationCommandIdempotencyRecord(bytes, key) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    fail(key);
+  }
+  if (!isRecordObject(decoded))
+    fail(key);
+  readVersion(decoded, key);
+  return {
+    recordVersion: MAILBOX_RECORD_VERSION,
+    commandId: readIdentifier(decoded.commandId, key),
+    identityDigest: readString(decoded, "identityDigest", key)
+  };
+}
+export function encodeApplicationCommandIdempotencyRecord(record) {
+  return encode(record);
+}
+export function decodeApplicationReadyEntry(bytes, key) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    fail(key);
+  }
+  return readIdentifier(decoded, key);
+}
+export function encodeApplicationReadyEntry(commandId) {
+  return encode(commandId);
+}

package/dist/core/mailbox-internals.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Shared runtime context and projections for the application command mailbox
+ * (WFT-84).
+ *
+ * The public class and the maintenance pass both need the same bound storage
+ * keys, resolved policy, clock, commit path, and attempt-controller registry.
+ * Passing that context explicitly — rather than reaching into the class — keeps
+ * `mailbox-maintenance.ts` a set of ordinary functions that tests
+ * can drive directly.
+ *
+ * @module core/mailbox-internals
+ */
+import type { BatchOperation, ConditionalBatchCondition, Storage } from '../storage/interface.ts';
+import { AttemptRegistry } from './application-primitive-attempt-registry.ts';
+import type { ApplicationCommandReceipt, MailboxEventSink } from './mailbox-contract.ts';
+import { type MailboxKeys } from './mailbox-storage.ts';
+import type { ApplicationCommandRecord, ApplicationCommandTerminalRecord } from './mailbox-types.ts';
+import type { ResolvedMailboxPolicy } from './mailbox-validation.ts';
+import { WeftError } from './weft-error.ts';
+/**
+ * How many times a transition re-reads durable state and retries after losing a
+ * compare-and-swap.
+ *
+ * The mailbox header is deliberately a per-mailbox hot key — admission and every
+ * terminal transition both touch it, which is what makes backlog accounting
+ * exact — so a busy mailbox does see contention. The ceiling exists so a
+ * pathological loop surfaces as an error instead of spinning forever.
+ */
+export declare const MAX_MAILBOX_TRANSITION_ATTEMPTS = 25;
+/**
+ * How many scan pages one maintenance pass may walk.
+ *
+ * The pass reaches the whole keyspace by paging, but stops after this many pages
+ * so a very large mailbox cannot make one call run unboundedly. The next pass
+ * starts again from the beginning and picks up whatever is still due.
+ */
+export declare const MAILBOX_MAINTENANCE_MAX_PAGES = 200;
+/** Everything a mailbox operation needs that is fixed at construction. */
+export type MailboxRuntime = {
+    readonly storage: Storage;
+    readonly events: MailboxEventSink | undefined;
+    readonly policy: ResolvedMailboxPolicy;
+    readonly keys: MailboxKeys;
+    readonly now: () => number;
+    readonly generateId: () => string;
+    /**
+     * Abort controllers for attempts claimed in this process, keyed by attempt
+     * token — shared across every handle onto the same mailbox, so a cancellation
+     * raised through one handle reaches a claimant holding another.
+     */
+    readonly attemptControllers: AttemptRegistry;
+    /**
+     * Record an attempt this handle now owns, or report that disposal already won.
+     *
+     * Registering ownership in the caller's `await` continuation would race
+     * disposal: `dispose()` could run between the claim resolving and the token
+     * being recorded, see nothing to abort, and leave a live claim from a disposed
+     * mailbox. Doing both under one synchronous call closes that window.
+     */
+    readonly adoptAttempt: (attemptToken: string) => (() => void) | null;
+    /**
+     * Where the previous maintenance pass stopped, when its page cap cut it short.
+     *
+     * Process-local rather than durable: it is an optimisation for walking a very
+     * large keyspace across successive calls, and losing it on restart only means
+     * the next pass starts from the beginning, which is always correct.
+     */
+    readonly readMaintenanceCursor: () => string | undefined;
+    readonly writeMaintenanceCursor: (cursor: string | undefined) => void;
+};
+/**
+ * Attempt controllers, shared per `(storage, namespace, resourceId)` within one
+ * process.
+ *
+ * Two `Mailbox` handles onto the same durable mailbox are the same
+ * mailbox. Giving each its own registry would make the documented in-process
+ * cancellation channel silently fail whenever the claimant and the canceller
+ * held different handles — the claimant's signal would never fire and it would
+ * learn about cancellation only through renewal, which is supposed to be the
+ * *cross-process* fallback. Keyed by `Storage` identity in a `WeakMap` so a
+ * discarded backend takes its registries with it.
+ */
+/** The registry-scope tag for the mailbox, so it never shares a registry with another primitive. */
+export declare const MAILBOX_PRIMITIVE = "mailbox";
+/**
+ * Thrown when a transition keeps losing its compare-and-swap.
+ *
+ * Surfacing this beats looping forever: it means durable contention on this
+ * mailbox is real, and the caller — not a hidden retry loop — decides whether to
+ * back off, shed load, or shard the resource.
+ *
+ * @example
+ * ```ts
+ * import { MailboxContentionError } from '@lostgradient/weft';
+ *
+ * const error = new MailboxContentionError('admit', null);
+ * console.log(error.code); // 'MailboxContentionError'
+ * ```
+ */
+export declare class MailboxContentionError extends WeftError<'MailboxContentionError'> {
+    /** The mailbox operation that could not commit. */
+    readonly operation: string;
+    /** The command the operation targeted, or `null` for mailbox-wide operations. */
+    readonly commandId: string | null;
+    constructor(operation: string, commandId: string | null);
+}
+export declare function toApplicationCommandReceipt(record: ApplicationCommandRecord): ApplicationCommandReceipt;
+/**
+ * The durable fleet event that describes a transition.
+ *
+ * A retry is distinguished from an initial admission even though both land in
+ * `accepted`, so a consumer reading the feed can tell redelivery from first
+ * delivery without diffing receipts. The payload is deliberately bounded: no
+ * command payload, no failure details, nothing unbounded.
+ */
+export declare function describeCommandTransition(previous: ApplicationCommandRecord | null, next: ApplicationCommandRecord): {
+    readonly kind: string;
+    readonly payload: unknown;
+};
+/**
+ * Abort and forget the process-local controller for one attempt.
+ *
+ * Releasing a lease must never leave a live controller behind: the signal is
+ * attempt-scoped, so a later attempt on the same command gets a fresh one.
+ */
+export declare function releaseAttemptController(runtime: MailboxRuntime, attemptToken: string, reason: string, commandId?: string): void;
+/**
+ * Release every attempt this process holds for one command.
+ *
+ * For an observer that finds the command gone — retired by retention in
+ * another process, whose maintenance cannot reach this registry — every local
+ * attempt on it is over, whatever token it held.
+ */
+export declare function releaseAttemptsForCommand(runtime: MailboxRuntime, commandId: string, reason: string, currentToken?: string, observedAt?: number): void;
+/**
+ * Commit one command transition together with the index maintenance and
+ * backlog accounting it implies.
+ *
+ * Terminalizing a command decrements the mailbox's open count in the same
+ * conditional batch, so `capacity()` can never drift from the records it
+ * describes. Admission is the one transition that builds its own header
+ * operation, because it also allocates the FIFO sequence.
+ *
+ * Returns `false` when a compare-and-swap was lost; the caller re-reads and
+ * re-decides rather than retrying blindly with stale bytes.
+ */
+export declare function commitCommandTransition(runtime: MailboxRuntime, options: {
+    readonly previous: ApplicationCommandRecord | null;
+    readonly expectedBytes: Uint8Array | null;
+    readonly next: ApplicationCommandRecord;
+    readonly now: number;
+    readonly extraConditions?: readonly ConditionalBatchCondition[] | undefined;
+    readonly extraOperations?: readonly BatchOperation[] | undefined;
+}): Promise<boolean>;
+/** Whether a record occupies one of the four terminal dispositions. */
+export declare function isTerminalRecord(record: ApplicationCommandRecord): record is ApplicationCommandTerminalRecord;

package/dist/core/mailbox-internals.js

@@ -0,0 +1,154 @@
+import { AttemptRegistry } from "./application-primitive-attempt-registry.js";
+import {
+  commitMailboxTransition,
+  headerOperation,
+  loadMailboxHeader,
+  planCommandTransition
+} from "./mailbox-storage.js";
+import { isApplicationCommandLeased } from "./mailbox-types.js";
+import { WeftError } from "./weft-error.js";
+export const MAX_MAILBOX_TRANSITION_ATTEMPTS = 25, MAILBOX_MAINTENANCE_MAX_PAGES = 200, MAILBOX_PRIMITIVE = "mailbox";
+
+export class MailboxContentionError extends WeftError {
+  operation;
+  commandId;
+  constructor(operation, commandId) {
+    super("MailboxContentionError", `Application mailbox ${operation}${commandId === null ? "" : ` for command "${commandId}"`} lost its storage precondition after ${MAX_MAILBOX_TRANSITION_ATTEMPTS} attempts.`);
+    this.operation = operation;
+    this.commandId = commandId;
+  }
+}
+function receiptLeaseFields(record) {
+  if (!isApplicationCommandLeased(record))
+    return {};
+  return {
+    claimedAt: record.claimedAt,
+    visibilityExpiresAt: record.visibilityExpiresAt,
+    lastActivityAt: record.lastActivityAt,
+    progress: record.progress
+  };
+}
+function receiptTerminalFields(record) {
+  if (!isTerminalRecord(record))
+    return record.state === "cancellation-requested" ? {
+      cancellationRequestedAt: record.cancellationRequestedAt,
+      cancellationReason: record.cancellationReason
+    } : {};
+  return {
+    cancellationRequestedAt: record.cancellationRequestedAt,
+    cancellationReason: record.cancellationReason,
+    terminalAt: record.terminalAt,
+    outcome: record.outcome,
+    failure: record.failure,
+    cleanupPending: record.cleanupPending
+  };
+}
+function deepFreeze(value) {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value))
+    return value;
+  Object.freeze(value);
+  for (const nested of Object.values(value))
+    deepFreeze(nested);
+  return value;
+}
+export function toApplicationCommandReceipt(record) {
+  return deepFreeze({
+    commandId: record.commandId,
+    namespace: record.namespace,
+    resourceId: record.resourceId,
+    sequence: record.sequence,
+    state: record.state,
+    caller: record.caller,
+    target: record.target,
+    kind: record.kind,
+    payloadDigest: record.payloadDigest,
+    payloadForm: record.payload.form,
+    payloadMediaType: record.payloadMediaType,
+    payloadSchema: record.payloadSchema,
+    idempotencyKey: record.idempotencyKey,
+    causation: record.causation,
+    acceptedAt: record.acceptedAt,
+    availableAt: record.availableAt,
+    absoluteDeadlineAt: record.absoluteDeadlineAt,
+    attempt: record.attempt,
+    retryCount: record.retryCount,
+    maxAttempts: record.maxAttempts,
+    generation: record.generation,
+    ...receiptLeaseFields(record),
+    ...receiptTerminalFields(record)
+  });
+}
+const STATE_EVENT_KINDS = {
+  accepted: "mailbox:command-accepted",
+  available: "mailbox:command-available",
+  claimed: "mailbox:command-claimed",
+  "cancellation-requested": "mailbox:command-cancellation-requested",
+  applied: "mailbox:command-applied",
+  rejected: "mailbox:command-rejected",
+  cancelled: "mailbox:command-cancelled",
+  "dead-lettered": "mailbox:command-dead-lettered"
+};
+export function describeCommandTransition(previous, next) {
+  return {
+    kind: previous !== null && next.state === "accepted" && next.retryCount > previous.retryCount ? "mailbox:command-retry-scheduled" : STATE_EVENT_KINDS[next.state],
+    payload: {
+      namespace: next.namespace,
+      resourceId: next.resourceId,
+      commandId: next.commandId,
+      sequence: next.sequence,
+      state: next.state,
+      commandKind: next.kind,
+      target: next.target,
+      attempt: next.attempt,
+      retryCount: next.retryCount,
+      generation: next.generation,
+      previousState: previous === null ? null : previous.state
+    }
+  };
+}
+export function releaseAttemptController(runtime, attemptToken, reason, commandId) {
+  const registration = runtime.attemptControllers.get(attemptToken);
+  if (registration === void 0)
+    return;
+  if (commandId !== void 0 && registration.subjectId !== commandId)
+    return;
+  runtime.attemptControllers.delete(attemptToken);
+  registration.release();
+  if (!registration.controller.signal.aborted)
+    registration.controller.abort(Error(reason));
+}
+export function releaseAttemptsForCommand(runtime, commandId, reason, currentToken, observedAt) {
+  for (const attemptToken of runtime.attemptControllers.tokensFor(commandId)) {
+    const registration = runtime.attemptControllers.get(attemptToken);
+    if (registration === void 0 || attemptToken === currentToken)
+      continue;
+    if (registration.committedSerial === null)
+      continue;
+    if (observedAt !== void 0 && registration.committedSerial > observedAt)
+      continue;
+    releaseAttemptController(runtime, attemptToken, reason);
+  }
+}
+export async function commitCommandTransition(runtime, options) {
+  const closing = options.previous !== null && !isTerminalRecord(options.previous) && isTerminalRecord(options.next), extraConditions = [...options.extraConditions ?? []], extraOperations = [...options.extraOperations ?? []];
+  if (closing) {
+    const header = await loadMailboxHeader(runtime.storage, runtime.keys, runtime.policy.namespace, runtime.policy.resourceId);
+    extraConditions.push({ key: runtime.keys.header, expectedValue: header.bytes });
+    extraOperations.push(headerOperation(runtime.keys, {
+      ...header.record,
+      openCount: Math.max(0, header.record.openCount - 1)
+    }));
+  }
+  return commitMailboxTransition(runtime.storage, runtime.events, planCommandTransition(runtime.keys, {
+    previous: options.previous,
+    expectedBytes: options.expectedBytes,
+    next: options.next,
+    event: describeCommandTransition(options.previous, options.next),
+    now: options.now,
+    extraConditions,
+    extraOperations
+  }));
+}
+export function isTerminalRecord(record) {
+  return record.state === "applied" || record.state === "rejected" || record.state === "cancelled" || record.state === "dead-lettered";
+}

package/dist/core/mailbox-maintenance.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The bounded maintenance pass for the application command mailbox (WFT-84).
+ *
+ * Maintenance is the only thing that advances time-driven work: releasing a
+ * delayed command, reclaiming an expired lease at its original FIFO position,
+ * dead-lettering a command past its absolute deadline, and retiring terminal
+ * receipts past their retention window. Nothing here runs on a hidden timer — a
+ * host with `backgroundTasks: 'manual'` calls `runMaintenance()` and gets
+ * exactly one deterministic pass.
+ *
+ * Every pass is bounded. It walks the command keyspace in pages of
+ * `maintenanceBatchSize` records, up to {@link MAILBOX_MAINTENANCE_MAX_PAGES}
+ * pages per call, carrying its cursor to the next call when the cap cuts it
+ * short; and it retires at most `maintenanceBatchSize` terminal receipts. A large
+ * mailbox drains across several calls instead of one unbounded sweep.
+ *
+ * @module core/mailbox-maintenance
+ */
+import type { MailboxMaintenanceReport } from './mailbox-contract.ts';
+import { type MailboxRuntime } from './mailbox-internals.ts';
+/**
+ * Run one bounded maintenance pass.
+ *
+ * The scan decodes every command record it visits, so a single corrupt record
+ * raises `PersistedDataCorruptError` and halts the pass. That is deliberate: a
+ * mailbox whose durable state is untrustworthy must not keep reclaiming leases
+ * and dead-lettering commands around the damage.
+ */
+export declare function runMailboxMaintenance(runtime: MailboxRuntime, now: number): Promise<MailboxMaintenanceReport>;

package/dist/core/mailbox-maintenance.js

@@ -0,0 +1,196 @@
+import { formatSortableStorageTimestamp, storageConditionalBatch } from "../storage/interface.js";
+import { leaseCommitSerial } from "./application-primitive-attempt-registry.js";
+import { decodeApplicationCommandRecord } from "./mailbox-codec.js";
+import {
+  decodeApplicationCommandIdempotencyRecord,
+  decodeApplicationReadyEntry
+} from "./mailbox-index-codec.js";
+import {
+  commitCommandTransition,
+  isTerminalRecord,
+  MAILBOX_MAINTENANCE_MAX_PAGES,
+  MailboxContentionError,
+  MAX_MAILBOX_TRANSITION_ATTEMPTS,
+  releaseAttemptController,
+  releaseAttemptsForCommand
+} from "./mailbox-internals.js";
+import { loadCommand } from "./mailbox-storage.js";
+import { recoverExpiredCommand } from "./mailbox-transitions-recovery.js";
+import { isCommandPastDeadline, releaseWaitingCommand } from "./mailbox-transitions.js";
+import { isApplicationCommandLeased } from "./mailbox-types.js";
+function classify(record, now) {
+  if (isTerminalRecord(record))
+    return null;
+  if (isCommandPastDeadline(record, now))
+    return "recover";
+  if (record.state === "accepted" && now >= record.availableAt)
+    return "release";
+  if (isApplicationCommandLeased(record) && now >= record.visibilityExpiresAt)
+    return "recover";
+  return null;
+}
+function countTransition(counters, previous, next) {
+  if (next.state === "available" && previous.state === "accepted")
+    counters.released += 1;
+  else if (next.state === "accepted")
+    counters.reclaimed += 1;
+  else if (next.state === "dead-lettered")
+    counters.deadLettered += 1;
+  else if (next.state === "cancelled")
+    counters.cancelled += 1;
+}
+function reconcileLocalAttempts(runtime, commandId, record, observedAt) {
+  releaseAttemptsForCommand(runtime, commandId, "This attempt is no longer the current lease on its command.", record !== void 0 && isApplicationCommandLeased(record) ? record.attemptToken : void 0, observedAt);
+}
+async function advanceCommand(runtime, commandId, now, counters) {
+  for (let attempt = 1;attempt <= MAX_MAILBOX_TRANSITION_ATTEMPTS; attempt += 1) {
+    const observedAt = leaseCommitSerial(), loaded = await loadCommand(runtime.storage, runtime.keys, commandId);
+    if (loaded === null) {
+      reconcileLocalAttempts(runtime, commandId, void 0, observedAt);
+      return;
+    }
+    const due = classify(loaded.record, now);
+    if (due === null) {
+      reconcileLocalAttempts(runtime, commandId, loaded.record, observedAt);
+      return;
+    }
+    const transition = due === "release" ? releaseWaitingCommand(loaded.record, now) : recoverExpiredCommand(loaded.record, {
+      now,
+      retryBackoffMs: runtime.policy.retryBackoffMs,
+      maxRetryBackoffMs: runtime.policy.maxRetryBackoffMs
+    });
+    if (!transition.ok)
+      return;
+    if (!await commitCommandTransition(runtime, {
+      previous: loaded.record,
+      expectedBytes: loaded.bytes,
+      next: transition.next,
+      now
+    }))
+      continue;
+    if (isApplicationCommandLeased(loaded.record))
+      releaseAttemptController(runtime, loaded.record.attemptToken, "The application mailbox reclaimed this attempt after its lease expired.");
+    countTransition(counters, loaded.record, transition.next);
+    return;
+  }
+  throw new MailboxContentionError("maintenance", commandId);
+}
+async function retireOneReceipt(runtime, indexKey, indexBytes) {
+  const commandId = commandIdFromTerminalKey(indexKey), observedAt = leaseCommitSerial(), loaded = commandId === null ? null : await loadCommand(runtime.storage, runtime.keys, commandId);
+  if (commandId === null || loaded !== null && !ownsTerminalEntry(runtime, indexKey, loaded)) {
+    await discardTerminalEntry(runtime, indexKey, indexBytes);
+    return !1;
+  }
+  const operations = [{ type: "delete", key: indexKey }];
+  if (loaded === null)
+    return storageConditionalBatch(runtime.storage, [{ key: indexKey, expectedValue: indexBytes }], operations);
+  operations.push({ type: "delete", key: runtime.keys.command(commandId) });
+  const auxiliary = await ownedAuxiliaryEntries(runtime, loaded);
+  operations.push(...auxiliary.operations);
+  const retired = await storageConditionalBatch(runtime.storage, [
+    { key: runtime.keys.command(commandId), expectedValue: loaded.bytes },
+    ...auxiliary.conditions
+  ], operations);
+  if (retired)
+    releaseAttemptsForCommand(runtime, commandId, "This command was retired; its attempt is over.", void 0, observedAt);
+  return retired;
+}
+async function ownedAuxiliaryEntries(runtime, loaded) {
+  const conditions = [], operations = [], sequenceKey = runtime.keys.bySequence(loaded.record.sequence), sequenceBytes = await runtime.storage.get(sequenceKey);
+  if (sequenceBytes !== null && decodeApplicationReadyEntry(sequenceBytes, sequenceKey) === loaded.record.commandId) {
+    conditions.push({ key: sequenceKey, expectedValue: sequenceBytes });
+    operations.push({ type: "delete", key: sequenceKey });
+  }
+  if (loaded.record.idempotencyKey === void 0)
+    return { conditions, operations };
+  const bindingKey = runtime.keys.idempotency(loaded.record.idempotencyKey), bindingBytes = await runtime.storage.get(bindingKey);
+  if (bindingBytes !== null && decodeApplicationCommandIdempotencyRecord(bindingBytes, bindingKey).commandId === loaded.record.commandId) {
+    conditions.push({ key: bindingKey, expectedValue: bindingBytes });
+    operations.push({ type: "delete", key: bindingKey });
+  }
+  return { conditions, operations };
+}
+function ownsTerminalEntry(runtime, indexKey, loaded) {
+  return isTerminalRecord(loaded.record) && runtime.keys.terminal(loaded.record.terminalAt, loaded.record.commandId) === indexKey;
+}
+async function discardTerminalEntry(runtime, indexKey, indexBytes) {
+  await storageConditionalBatch(runtime.storage, [{ key: indexKey, expectedValue: indexBytes }], [{ type: "delete", key: indexKey }]);
+}
+async function retireTerminalReceipts(runtime, now, counters) {
+  const horizon = now - runtime.policy.terminalRetentionMs;
+  if (horizon < 0)
+    return;
+  const expired = [], malformed = [];
+  for await (const [key, value] of runtime.storage.scan(runtime.keys.terminalPrefix, {
+    limit: runtime.policy.maintenanceBatchSize
+  })) {
+    const terminalAt = parseTerminalAt(key, runtime.keys.terminalPrefix);
+    if (terminalAt === null) {
+      malformed.push([key, value]);
+      continue;
+    }
+    if (terminalAt >= horizon)
+      break;
+    expired.push([key, value]);
+  }
+  for (const [indexKey, bytes] of malformed)
+    await discardTerminalEntry(runtime, indexKey, bytes);
+  for (const [indexKey, bytes] of expired)
+    if (await retireOneReceipt(runtime, indexKey, bytes))
+      counters.retired += 1;
+}
+function parseTerminalAt(key, prefix) {
+  const suffix = key.slice(prefix.length), separator = suffix.indexOf(":");
+  if (separator === -1)
+    return null;
+  const segment = suffix.slice(0, separator), parsed = Number(segment);
+  return Number.isSafeInteger(parsed) && formatSortableStorageTimestamp(parsed) === segment ? parsed : null;
+}
+function commandIdFromTerminalKey(key) {
+  const separator = key.lastIndexOf(":");
+  if (separator === -1)
+    return null;
+  try {
+    return decodeURIComponent(key.slice(separator + 1));
+  } catch {
+    return null;
+  }
+}
+async function collectDueCommands(runtime, now, startAfter) {
+  const batchSize = runtime.policy.maintenanceBatchSize, due = [];
+  let cursor = startAfter;
+  for (let page = 0;page < MAILBOX_MAINTENANCE_MAX_PAGES; page += 1) {
+    let seen = 0;
+    const options = cursor === void 0 ? { limit: batchSize } : { limit: batchSize, gt: cursor }, observedAt = leaseCommitSerial();
+    for await (const [key, value] of runtime.storage.scan(runtime.keys.commandPrefix, options)) {
+      seen += 1;
+      cursor = key;
+      const record = decodeApplicationCommandRecord(value, key);
+      reconcileLocalAttempts(runtime, record.commandId, record, observedAt);
+      if (classify(record, now) !== null)
+        due.push(record.commandId);
+    }
+    if (seen < batchSize)
+      return { due, nextCursor: void 0 };
+  }
+  return { due, nextCursor: cursor };
+}
+export async function runMailboxMaintenance(runtime, now) {
+  const counters = {
+    released: 0,
+    reclaimed: 0,
+    deadLettered: 0,
+    cancelled: 0,
+    retired: 0
+  }, previousCursor = runtime.readMaintenanceCursor(), scan = await collectDueCommands(runtime, now, previousCursor);
+  try {
+    for (const commandId of scan.due)
+      await advanceCommand(runtime, commandId, now, counters);
+  } catch (error) {
+    runtime.writeMaintenanceCursor(previousCursor);
+    throw error;
+  }
+  runtime.writeMaintenanceCursor(scan.nextCursor);
+  await retireTerminalReceipts(runtime, now, counters);
+  return Object.freeze({ ...counters });
+}