@lostgradient/weft 0.23.0 → 0.24.0

package/dist/core/mailbox-waits.js

@@ -0,0 +1,97 @@
+import { WaitBudgetElapsedError, raceAbortWithin } from "./application-primitive-abort.js";
+import { delayUnlessAborted } from "./application-primitive-timing.js";
+import { decodeApplicationReadyEntry } from "./mailbox-index-codec.js";
+import { readCleanupState } from "./mailbox-settlement.js";
+import { isWaitingState, loadCommand } from "./mailbox-storage.js";
+import {
+  requireClockInstant,
+  requireDerivedInstant,
+  requireWaitBudget
+} from "./mailbox-validation.js";
+export { DEFAULT_WAIT_POLL_INTERVAL_MS as DEFAULT_MAILBOX_POLL_INTERVAL_MS } from "./mailbox-validation.js";
+export { delayUnlessAborted };
+export async function hasDueWork(runtime) {
+  for await (const [key, value] of runtime.storage.scan(runtime.keys.readyPrefix, {
+    limit: DUE_WORK_LOOKAHEAD
+  })) {
+    const loaded = await loadCommand(runtime.storage, runtime.keys, decodeApplicationReadyEntry(value, key));
+    if (loaded === null || !isWaitingState(loaded.record))
+      continue;
+    if (key !== runtime.keys.ready(loaded.record.sequence))
+      continue;
+    const now = runtime.now();
+    if (now >= loaded.record.absoluteDeadlineAt)
+      continue;
+    return now >= loaded.record.availableAt;
+  }
+  return !1;
+}
+const DUE_WORK_LOOKAHEAD = 8;
+export async function waitForAvailableWork(runtime, disposal, options) {
+  const { timeoutMs, pollIntervalMs } = requireWaitBudget(options ?? {}), deadline = requireDerivedInstant(requireClockInstant(runtime.now()) + timeoutMs, "deadline");
+  let remaining = 0;
+  do {
+    const observed = await observeDueWork(runtime, disposal, options?.signal, timeoutMs, deadline);
+    if (observed === null || isAborted(disposal, options?.signal))
+      return !1;
+    if (observed)
+      return observedInTime(timeoutMs, deadline, runtime.now());
+    remaining = deadline - runtime.now();
+    if (remaining <= 0)
+      return !1;
+  } while (await delayUnlessAborted(Math.min(pollIntervalMs, remaining), disposal, options?.signal));
+  return !1;
+}
+async function observeDueWork(runtime, disposal, signal, timeoutMs, deadline) {
+  if (budgetSpent(timeoutMs, deadline, runtime.now()))
+    return null;
+  const observed = await raceAbortWithin(() => hasDueWork(runtime), budgetFor(timeoutMs, deadline, runtime.now()), disposal, signal);
+  return observed.aborted ? null : observed.value;
+}
+function budgetSpent(timeoutMs, deadline, now) {
+  return timeoutMs > 0 && now >= deadline;
+}
+function budgetFor(timeoutMs, deadline, now) {
+  if (timeoutMs === 0)
+    return null;
+  const remaining = deadline - now;
+  return remaining > 0 ? remaining : null;
+}
+function observedInTime(timeoutMs, deadline, now) {
+  return timeoutMs === 0 || now <= deadline;
+}
+function isAborted(disposal, signal) {
+  return disposal.aborted || signal?.aborted === !0;
+}
+export async function waitForCleanup(runtime, disposal, options) {
+  const { timeoutMs, pollIntervalMs } = requireWaitBudget(options), deadline = requireDerivedInstant(requireClockInstant(runtime.now()) + timeoutMs, "deadline"), first = await readUnlessAborted(runtime, options.commandId, disposal, options.signal, budgetFor(timeoutMs, deadline, runtime.now()));
+  if (first === null)
+    throw new WaitBudgetElapsedError;
+  let latest = first;
+  if (latest.status === "pending" && latest.receipt.terminalAt !== void 0)
+    return latest;
+  while (latest.status === "pending") {
+    const remaining = deadline - runtime.now();
+    if (remaining <= 0)
+      break;
+    if (!await delayUnlessAborted(Math.min(pollIntervalMs, remaining), disposal, options.signal)) {
+      options.signal?.throwIfAborted();
+      break;
+    }
+    if (budgetSpent(timeoutMs, deadline, runtime.now()))
+      break;
+    const next = await readUnlessAborted(runtime, options.commandId, disposal, options.signal, budgetFor(timeoutMs, deadline, runtime.now()));
+    if (next === null)
+      break;
+    latest = next;
+  }
+  return latest;
+}
+async function readUnlessAborted(runtime, commandId, disposal, signal, budgetMs) {
+  const raced = await raceAbortWithin(() => readCleanupState(runtime, commandId), budgetMs, disposal, signal);
+  if (!raced.aborted)
+    return raced.value;
+  if (raced.reason instanceof WaitBudgetElapsedError)
+    return null;
+  throw raced.reason;
+}

package/dist/core/mailbox.d.ts

@@ -0,0 +1,163 @@
+/**
+ * The durable application command mailbox (WFT-84).
+ *
+ * A mailbox is a storage-backed, strictly FIFO command queue scoped to one
+ * opaque `(namespace, resourceId)` pair. Admission returns a durable receipt
+ * that survives process restart; delivery is attempt-fenced so two consumers
+ * can never both hold a valid claim; cancellation is durable before it reaches
+ * anyone; and every state transition commits atomically with its fleet event
+ * when an event sink is configured.
+ *
+ * What it is not: a message broker. There are no topics, no consumer groups, no
+ * cross-mailbox ordering, and no cross-region replication. Ordering is defined
+ * within one mailbox and nowhere else.
+ *
+ * @module core/mailbox
+ */
+import type { Storage } from '../storage/interface.ts';
+import type { JSONValue } from './json.ts';
+import type { ApplicationCommandAdmission, ApplicationCommandCancellationResult, ApplicationCommandCleanupResult, ApplicationCommandInput, ApplicationCommandReceipt, ApplicationCommandRejection, ApplicationCommandRenewalResult, ApplicationCommandSettleResult, MailboxCapacity, MailboxClaimResult, MailboxListOptions, MailboxMaintenanceReport, MailboxOptions, MailboxWaitOptions } from './mailbox-contract.ts';
+/**
+ * A durable, strictly FIFO application command mailbox.
+ *
+ * @example
+ * ```ts
+ * import { Mailbox, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * using mailbox = new Mailbox({ storage, namespace: 'bureau', resourceId: 'agent-7' });
+ *
+ * const admission = await mailbox.admit({
+ *   caller: 'user:42',
+ *   target: 'agent:7',
+ *   kind: 'steer',
+ *   payload: { form: 'inline', value: { text: 'stop' } },
+ *   idempotencyKey: 'steer-1',
+ * });
+ * console.log(admission.status); // 'admitted'
+ *
+ * const claimed = await mailbox.claim();
+ * console.log(claimed.status); // 'claimed'
+ * ```
+ */
+export declare class Mailbox {
+    #private;
+    constructor(options: MailboxOptions);
+    /** The opaque application namespace this mailbox is scoped to. */
+    get namespace(): string;
+    /** The opaque resource identifier this mailbox is scoped to. */
+    get resourceId(): string;
+    /** The durable backend every transition compares and swaps against. */
+    get storage(): Storage;
+    /**
+     * Offer a command to the mailbox.
+     *
+     * An exact retry of the same idempotency identity returns the original
+     * receipt without creating a second command. Reusing the key with a different
+     * caller, target, kind, or payload digest returns a conflict and leaves the
+     * original command untouched. A full backlog is rejected before anything is
+     * persisted.
+     */
+    admit(command: ApplicationCommandInput): Promise<ApplicationCommandAdmission>;
+    /** Read one command's immutable receipt, or `null` when it is unknown or retired. */
+    receipt(commandId: string): Promise<ApplicationCommandReceipt | null>;
+    /**
+     * List receipts in this mailbox, bounded and non-consuming.
+     *
+     * Listing never claims, starts, or advances work, so any number of observers
+     * can call it concurrently without interfering with delivery.
+     */
+    list(options?: MailboxListOptions): Promise<ApplicationCommandReceipt[]>;
+    /** Current backlog accounting. Deliberately low-cardinality: counts only. */
+    capacity(): Promise<MailboxCapacity>;
+    /**
+     * Lease the FIFO head of this mailbox to one attempt.
+     *
+     * Strict FIFO is the contract: when the head is not due yet, `claim()` reports
+     * `held` rather than skipping ahead to a later command. The returned claim
+     * carries an attempt-scoped `AbortSignal` that fires on cancellation, lease
+     * release, or mailbox disposal.
+     */
+    claim(options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<MailboxClaimResult>;
+    /** Extend a lease and report liveness for the current attempt. */
+    renew(options: {
+        readonly commandId: string;
+        readonly attemptToken: string;
+        readonly progress?: JSONValue | undefined;
+    }): Promise<ApplicationCommandRenewalResult>;
+    /** Settle a claimed command successfully. */
+    acknowledge(options: {
+        readonly commandId: string;
+        readonly attemptToken: string;
+        readonly outcome?: JSONValue | undefined;
+    }): Promise<ApplicationCommandSettleResult>;
+    /** Settle a claimed command as failed, optionally scheduling a retry. */
+    reject(options: {
+        readonly commandId: string;
+        readonly attemptToken: string;
+        readonly failure: ApplicationCommandRejection;
+        readonly retry?: boolean | undefined;
+    }): Promise<ApplicationCommandSettleResult>;
+    /** Durably request cancellation and abort an in-process claimant. */
+    requestCancellation(options: {
+        readonly commandId: string;
+        readonly reason?: string | undefined;
+    }): Promise<ApplicationCommandCancellationResult>;
+    /**
+     * Read whether a cancelled command's claimant has finished. Non-consuming and
+     * safe to call from any number of observers.
+     */
+    cleanupState(commandId: string): Promise<ApplicationCommandCleanupResult>;
+    /**
+     * Wait, bounded, for a cancelled command's claimant to settle.
+     *
+     * A `pending` result means this mailbox stopped waiting — never that the
+     * handler stopped. A caller signal that aborts at any point — before a read,
+     * during one, or during the sleep between polls — rejects the wait with that
+     * signal's reason; disposing the mailbox during a read rejects with the
+     * disposal error, and during a sleep returns the last observation. The
+     * budget bounds the reads themselves as well as the sleeps between them: a
+     * budget that runs out during a later read returns the last observation, and
+     * one that runs out during the first read, with nothing observed yet,
+     * rejects with `WaitBudgetElapsedError`.
+     */
+    awaitCleanup(options: {
+        readonly commandId: string;
+        readonly timeoutMs: number;
+        readonly signal?: AbortSignal | undefined;
+        readonly pollIntervalMs?: number | undefined;
+    }): Promise<ApplicationCommandCleanupResult>;
+    /**
+     * Wait, bounded and abortably, until this mailbox has work due for delivery.
+     *
+     * Returns `true` when the FIFO head is claimable. Aborting, disposal, or the
+     * timeout returns `false` and releases every process-local resource without
+     * touching durable work.
+     *
+     * `timeoutMs` defaults to `0`, so calling this with no options checks once and
+     * returns immediately rather than blocking. Pass a timeout to actually wait.
+     */
+    waitForAvailable(options?: MailboxWaitOptions): Promise<boolean>;
+    /**
+     * Run one bounded maintenance pass: release due commands, reclaim expired
+     * leases at their original FIFO position, dead-letter commands past their
+     * absolute deadline, and retire terminal receipts past retention.
+     *
+     * Nothing in this mailbox runs on a hidden timer, so a host configured with
+     * `backgroundTasks: 'manual'` drives every time-based transition through this
+     * one call.
+     */
+    runMaintenance(now?: number): Promise<MailboxMaintenanceReport>;
+    /**
+     * Release every process-local resource: abort in-flight waits and every
+     * attempt-scoped signal this process holds.
+     *
+     * Disposal never deletes durable work. A claim this process held stays leased
+     * until its visibility expires and maintenance reclaims it.
+     */
+    dispose(): void;
+    /** `using`-compatible disposal. */
+    [Symbol.dispose](): void;
+}

package/dist/core/mailbox.js

@@ -0,0 +1,211 @@
+import {
+  attemptControllerRegistry,
+  releaseAttemptControllerRegistry
+} from "./application-primitive-attempt-registry.js";
+import { admitCommand, capacityOf } from "./mailbox-admission.js";
+import { claimNextCommand } from "./mailbox-delivery.js";
+import { decodeApplicationReadyEntry } from "./mailbox-index-codec.js";
+import {
+  MAILBOX_PRIMITIVE,
+  toApplicationCommandReceipt
+} from "./mailbox-internals.js";
+import { runMailboxMaintenance } from "./mailbox-maintenance.js";
+import {
+  acknowledgeClaim,
+  readCleanupState,
+  rejectClaim,
+  renewClaim,
+  requestCancellation
+} from "./mailbox-settlement.js";
+import { createMailboxKeys, loadCommand, loadMailboxHeader } from "./mailbox-storage.js";
+import {
+  ApplicationCommandValidationError,
+  clampListLimit,
+  requireClockInstant,
+  requireMaintenanceInstant,
+  resolveMailboxPolicy,
+  validateCancellationReason,
+  validateCommandIdentifier,
+  validateDurableJSONValue,
+  validateFailure
+} from "./mailbox-validation.js";
+import { waitForAvailableWork, waitForCleanup } from "./mailbox-waits.js";
+import { PersistedDataCorruptError } from "./persisted-data-incompatible-error.js";
+const MAILBOX_LIST_PAGE_SIZE = 200, MAILBOX_LIST_SCAN_CEILING = 5000;
+
+export class Mailbox {
+  #runtime;
+  #disposal = new AbortController;
+  #ownAttempts = new Set;
+  #maintenanceCursor;
+  #disposed = !1;
+  constructor(options) {
+    const policy = resolveMailboxPolicy(options), capabilities = options.storage.capabilities();
+    if (!capabilities.conditionalBatch)
+      throw new ApplicationCommandValidationError("Application mailboxes require storage with conditional batch support: every transition is a compare-and-swap.");
+    if (capabilities.scanConsistency !== "snapshot")
+      throw new ApplicationCommandValidationError("Application mailboxes require storage with snapshot scan consistency: strict FIFO delivery reads the index head, and a best-effort scan can return a later command ahead of an earlier one.");
+    if (capabilities.readAfterWrite !== "linearizable")
+      throw new ApplicationCommandValidationError("Application mailboxes require storage with linearizable read-after-write: strict FIFO delivery across processes needs every consumer to see every durable admission.");
+    this.#runtime = {
+      storage: options.storage,
+      events: options.events,
+      policy,
+      keys: createMailboxKeys(policy.namespace, policy.resourceId),
+      now: () => requireClockInstant((options.now ?? Date.now)()),
+      generateId: options.generateId ?? (() => crypto.randomUUID()),
+      attemptControllers: attemptControllerRegistry(options.storage, MAILBOX_PRIMITIVE, policy.namespace, policy.resourceId),
+      adoptAttempt: (attemptToken) => {
+        if (this.#disposed)
+          return null;
+        this.#ownAttempts.add(attemptToken);
+        return () => {
+          this.#ownAttempts.delete(attemptToken);
+        };
+      },
+      readMaintenanceCursor: () => this.#maintenanceCursor,
+      writeMaintenanceCursor: (cursor) => {
+        this.#maintenanceCursor = cursor;
+      }
+    };
+  }
+  get namespace() {
+    return this.#runtime.policy.namespace;
+  }
+  get resourceId() {
+    return this.#runtime.policy.resourceId;
+  }
+  get storage() {
+    return this.#runtime.storage;
+  }
+  #assertLive() {
+    if (this.#disposed)
+      throw new ApplicationCommandValidationError("This application mailbox has been disposed.");
+  }
+  async admit(command) {
+    this.#assertLive();
+    return admitCommand(this.#runtime, command);
+  }
+  async receipt(commandId) {
+    this.#assertLive();
+    const loaded = await loadCommand(this.#runtime.storage, this.#runtime.keys, validateCommandIdentifier(commandId));
+    return loaded === null ? null : toApplicationCommandReceipt(loaded.record);
+  }
+  async list(options) {
+    this.#assertLive();
+    const limit = clampListLimit(options?.limit), states = options?.states === void 0 ? null : new Set(options.states), receipts = [];
+    let cursor, examined = 0;
+    while (receipts.length < limit && examined < MAILBOX_LIST_SCAN_CEILING) {
+      const page = await this.#readListingPage(cursor, limit - receipts.length, states);
+      receipts.push(...page.receipts);
+      examined += page.examined;
+      cursor = page.cursor;
+      if (page.exhausted)
+        break;
+    }
+    return receipts;
+  }
+  async#readListingPage(cursor, remaining, states) {
+    const receipts = [], scanOptions = cursor === void 0 ? { limit: MAILBOX_LIST_PAGE_SIZE } : { limit: MAILBOX_LIST_PAGE_SIZE, gt: cursor };
+    let seen = 0, nextCursor = cursor;
+    for await (const [indexKey, indexValue] of this.#runtime.storage.scan(this.#runtime.keys.bySequencePrefix, scanOptions)) {
+      seen += 1;
+      nextCursor = indexKey;
+      const commandId = decodeApplicationReadyEntry(indexValue, indexKey), loaded = await loadCommand(this.#runtime.storage, this.#runtime.keys, commandId);
+      if (loaded === null)
+        continue;
+      if (indexKey !== this.#runtime.keys.bySequence(loaded.record.sequence))
+        throw new PersistedDataCorruptError(indexKey);
+      if (states !== null && !states.has(loaded.record.state))
+        continue;
+      receipts.push(toApplicationCommandReceipt(loaded.record));
+      if (receipts.length >= remaining)
+        break;
+    }
+    return {
+      receipts,
+      cursor: nextCursor,
+      exhausted: seen < MAILBOX_LIST_PAGE_SIZE,
+      examined: seen
+    };
+  }
+  async capacity() {
+    this.#assertLive();
+    const header = await loadMailboxHeader(this.#runtime.storage, this.#runtime.keys, this.#runtime.policy.namespace, this.#runtime.policy.resourceId);
+    return capacityOf(this.#runtime, header.record.openCount, header.record.admittedCount);
+  }
+  async claim(options) {
+    this.#assertLive();
+    return claimNextCommand(this.#runtime, options);
+  }
+  async renew(options) {
+    this.#assertLive();
+    return renewClaim(this.#runtime, {
+      commandId: validateCommandIdentifier(options.commandId),
+      attemptToken: options.attemptToken,
+      progress: validateDurableJSONValue(options.progress, "progress")
+    });
+  }
+  async acknowledge(options) {
+    this.#assertLive();
+    return acknowledgeClaim(this.#runtime, {
+      commandId: validateCommandIdentifier(options.commandId),
+      attemptToken: options.attemptToken,
+      outcome: validateDurableJSONValue(options.outcome, "outcome")
+    });
+  }
+  async reject(options) {
+    this.#assertLive();
+    return rejectClaim(this.#runtime, {
+      commandId: validateCommandIdentifier(options.commandId),
+      attemptToken: options.attemptToken,
+      failure: validateFailure(options.failure),
+      retry: options.retry ?? !1
+    });
+  }
+  async requestCancellation(options) {
+    this.#assertLive();
+    return requestCancellation(this.#runtime, {
+      commandId: validateCommandIdentifier(options.commandId),
+      reason: validateCancellationReason(options.reason)
+    });
+  }
+  async cleanupState(commandId) {
+    this.#assertLive();
+    return readCleanupState(this.#runtime, validateCommandIdentifier(commandId));
+  }
+  async awaitCleanup(options) {
+    this.#assertLive();
+    return waitForCleanup(this.#runtime, this.#disposal.signal, {
+      ...options,
+      commandId: validateCommandIdentifier(options.commandId)
+    });
+  }
+  async waitForAvailable(options) {
+    this.#assertLive();
+    return waitForAvailableWork(this.#runtime, this.#disposal.signal, options);
+  }
+  async runMaintenance(now = this.#runtime.now()) {
+    this.#assertLive();
+    return runMailboxMaintenance(this.#runtime, requireMaintenanceInstant(now));
+  }
+  dispose() {
+    if (this.#disposed)
+      return;
+    this.#disposed = !0;
+    for (const attemptToken of this.#ownAttempts) {
+      const registration = this.#runtime.attemptControllers.get(attemptToken);
+      if (registration === void 0)
+        continue;
+      this.#runtime.attemptControllers.delete(attemptToken);
+      if (!registration.controller.signal.aborted)
+        registration.controller.abort(Error("The application mailbox was disposed while this attempt was open."));
+    }
+    this.#ownAttempts.clear();
+    this.#disposal.abort(Error("The application mailbox was disposed."));
+    releaseAttemptControllerRegistry(this.#runtime.storage, MAILBOX_PRIMITIVE, this.#runtime.policy.namespace, this.#runtime.policy.resourceId);
+  }
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+}