@lostgradient/weft 0.23.1 → 0.24.1

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

@@ -0,0 +1,69 @@
+/**
+ * Attempt-fenced settlement for the application command mailbox (WFT-84):
+ * lease renewal, acknowledgement, rejection, cancellation, and the bounded
+ * cleanup wait.
+ *
+ * Every function here proves the caller holds the current attempt before it
+ * writes anything, and every one re-reads durable state after a lost
+ * compare-and-swap rather than retrying with stale bytes. A stale claimant
+ * therefore cannot acknowledge, reject, cancel, extend, or heartbeat a newer
+ * attempt — it gets a `stale` result carrying the authoritative receipt.
+ *
+ * Renewal is the one mutation that emits no fleet event. It is liveness
+ * evidence, not a state transition: the record's disposition is unchanged, so
+ * publishing an event per heartbeat would flood the feed without telling a
+ * consumer anything a receipt read does not already say.
+ *
+ * @module core/mailbox-settlement
+ */
+import type { JSONValue } from './json.ts';
+import type { ApplicationCommandCancellationResult, ApplicationCommandCleanupResult, ApplicationCommandRenewalResult, ApplicationCommandSettleResult } from './mailbox-contract.ts';
+import { type MailboxRuntime } from './mailbox-internals.ts';
+import type { ApplicationCommandFailure } from './mailbox-types.ts';
+/**
+ * Extend a lease and report liveness for the current attempt.
+ *
+ * The returned `cancellationRequested` flag is the cross-process cancellation
+ * channel. A claimant in another process never sees the attempt-scoped
+ * `AbortSignal`, so renewal is where it learns that cancellation was requested.
+ */
+export declare function renewClaim(runtime: MailboxRuntime, options: {
+    readonly commandId: string;
+    readonly attemptToken: string;
+    readonly progress?: JSONValue | undefined;
+}): Promise<ApplicationCommandRenewalResult>;
+/** Settle a claimed command successfully. */
+export declare function acknowledgeClaim(runtime: MailboxRuntime, options: {
+    readonly commandId: string;
+    readonly attemptToken: string;
+    readonly outcome?: JSONValue | undefined;
+}): Promise<ApplicationCommandSettleResult>;
+/**
+ * Settle a claimed command as failed, optionally scheduling a retry at the
+ * command's original FIFO position.
+ */
+export declare function rejectClaim(runtime: MailboxRuntime, options: {
+    readonly commandId: string;
+    readonly attemptToken: string;
+    readonly failure: ApplicationCommandFailure;
+    readonly retry: boolean;
+}): Promise<ApplicationCommandSettleResult>;
+/**
+ * Record a durable cancellation request and, when the claimant is in this
+ * process, abort its attempt-scoped signal.
+ *
+ * Cancellation is durable before any acknowledgement: the abort fires only
+ * after the record commits, so a crash between the two cannot leave a claimant
+ * aborted without the request being persisted.
+ */
+export declare function requestCancellation(runtime: MailboxRuntime, options: {
+    readonly commandId: string;
+    readonly reason?: string | undefined;
+}): Promise<ApplicationCommandCancellationResult>;
+/**
+ * Read whether a cancelled command's claimant has finished.
+ *
+ * `pending` means the mailbox has not seen the attempt settle. It never claims
+ * the handler stopped — only that cleanup is still outstanding.
+ */
+export declare function readCleanupState(runtime: MailboxRuntime, commandId: string): Promise<ApplicationCommandCleanupResult>;

package/dist/core/mailbox-settlement.js

@@ -0,0 +1,206 @@
+import { leaseCommitSerial } from "./application-primitive-attempt-registry.js";
+import {
+  commitCommandTransition,
+  isTerminalRecord,
+  MailboxContentionError,
+  MAX_MAILBOX_TRANSITION_ATTEMPTS,
+  releaseAttemptController,
+  releaseAttemptsForCommand,
+  toApplicationCommandReceipt
+} from "./mailbox-internals.js";
+import { commitMailboxTransition, loadCommand, planCommandTransition } from "./mailbox-storage.js";
+import { recoverExpiredCommand } from "./mailbox-transitions-recovery.js";
+import {
+  acknowledgeCommand,
+  rejectCommand,
+  renewCommandLease,
+  requestCommandCancellation
+} from "./mailbox-transitions.js";
+import { isApplicationCommandLeased } from "./mailbox-types.js";
+export async function renewClaim(runtime, options) {
+  for (let attempt = 1;attempt <= MAX_MAILBOX_TRANSITION_ATTEMPTS; attempt += 1) {
+    const loaded = await loadCommand(runtime.storage, runtime.keys, options.commandId);
+    if (loaded === null)
+      return { status: "unknown" };
+    const now = runtime.now(), transition = renewCommandLease(loaded.record, {
+      attemptToken: options.attemptToken,
+      now,
+      progress: options.progress
+    });
+    if (!transition.ok) {
+      releaseAttemptController(runtime, options.attemptToken, "This attempt is no longer current: its renewal was refused.", options.commandId);
+      return {
+        status: transition.reason === "deadline-exceeded" ? "deadline-exceeded" : "stale",
+        receipt: toApplicationCommandReceipt(loaded.record)
+      };
+    }
+    if (!await commitMailboxTransition(runtime.storage, runtime.events, {
+      ...planCommandTransition(runtime.keys, {
+        previous: loaded.record,
+        expectedBytes: loaded.bytes,
+        next: transition.next,
+        event: null,
+        now
+      })
+    }))
+      continue;
+    if (runtime.now() >= transition.next.absoluteDeadlineAt) {
+      const receipt = await deadLetterRenewed(runtime, options.commandId, toApplicationCommandReceipt(transition.next));
+      releaseAttemptController(runtime, options.attemptToken, "The application mailbox dead-lettered this command at its absolute deadline.", options.commandId);
+      return { status: "deadline-exceeded", receipt };
+    }
+    return {
+      status: "renewed",
+      visibilityExpiresAt: transition.next.visibilityExpiresAt,
+      cancellationRequested: transition.next.state === "cancellation-requested",
+      receipt: toApplicationCommandReceipt(transition.next)
+    };
+  }
+  throw new MailboxContentionError("renew", options.commandId);
+}
+async function deadLetterRenewed(runtime, commandId, renewed) {
+  const loaded = await loadCommand(runtime.storage, runtime.keys, commandId);
+  if (loaded === null)
+    return renewed;
+  const receipt = await deadLetterExpired(runtime, loaded, runtime.now());
+  if (receipt !== null)
+    return receipt;
+  const current = await loadCommand(runtime.storage, runtime.keys, commandId);
+  return current === null ? renewed : toApplicationCommandReceipt(current.record);
+}
+export async function acknowledgeClaim(runtime, options) {
+  return settle(runtime, options.commandId, options.attemptToken, "acknowledge", (record, now) => acknowledgeCommand(record, {
+    attemptToken: options.attemptToken,
+    now,
+    outcome: options.outcome
+  }));
+}
+export async function rejectClaim(runtime, options) {
+  return settle(runtime, options.commandId, options.attemptToken, "reject", (record, now) => rejectCommand(record, {
+    attemptToken: options.attemptToken,
+    now,
+    retry: options.retry,
+    failure: options.failure,
+    retryBackoffMs: runtime.policy.retryBackoffMs,
+    maxRetryBackoffMs: runtime.policy.maxRetryBackoffMs
+  }));
+}
+async function settle(runtime, commandId, attemptToken, operation, decide) {
+  for (let attempt = 1;attempt <= MAX_MAILBOX_TRANSITION_ATTEMPTS; attempt += 1) {
+    const loaded = await loadCommand(runtime.storage, runtime.keys, commandId);
+    if (loaded === null) {
+      releaseRefusedAttempt(runtime, commandId, attemptToken);
+      return { status: "unknown" };
+    }
+    const now = runtime.now(), transition = decide(loaded.record, now);
+    if (!transition.ok) {
+      releaseRefusedAttempt(runtime, commandId, attemptToken);
+      return {
+        status: transition.reason === "deadline-exceeded" ? "deadline-exceeded" : "stale",
+        receipt: toApplicationCommandReceipt(loaded.record)
+      };
+    }
+    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 released this attempt when the command settled.");
+    return {
+      status: isTerminalRecord(transition.next) ? "settled" : "retrying",
+      receipt: toApplicationCommandReceipt(transition.next)
+    };
+  }
+  throw new MailboxContentionError(operation, commandId);
+}
+function releaseTerminalAttempts(runtime, commandId, observedAt) {
+  releaseAttemptsForCommand(runtime, commandId, "This command is terminal; its attempt is over.", void 0, observedAt);
+}
+function releaseRefusedAttempt(runtime, commandId, attemptToken) {
+  releaseAttemptController(runtime, attemptToken, "This attempt is no longer current: its settlement was refused.", commandId);
+}
+export async function requestCancellation(runtime, options) {
+  for (let attempt = 1;attempt <= MAX_MAILBOX_TRANSITION_ATTEMPTS; attempt += 1) {
+    const observedAt = leaseCommitSerial(), loaded = await loadCommand(runtime.storage, runtime.keys, options.commandId);
+    if (loaded === null) {
+      releaseTerminalAttempts(runtime, options.commandId, observedAt);
+      return { status: "unknown" };
+    }
+    const now = runtime.now(), transition = requestCommandCancellation(loaded.record, { now, reason: options.reason });
+    if (!transition.ok) {
+      if (transition.reason === "deadline-exceeded") {
+        const expired = await deadLetterExpired(runtime, loaded, now);
+        if (expired === null)
+          continue;
+        releaseTerminalAttempts(runtime, options.commandId, observedAt);
+        return { status: "already-terminal", receipt: expired };
+      }
+      if (transition.reason === "not-leased" && isApplicationCommandLeased(loaded.record)) {
+        abortLocalClaimant(runtime, loaded.record.attemptToken);
+        return {
+          status: "requested",
+          receipt: toApplicationCommandReceipt(loaded.record),
+          cleanupPending: !0
+        };
+      }
+      releaseTerminalAttempts(runtime, options.commandId, observedAt);
+      return { status: "already-terminal", receipt: toApplicationCommandReceipt(loaded.record) };
+    }
+    if (!await commitCommandTransition(runtime, {
+      previous: loaded.record,
+      expectedBytes: loaded.bytes,
+      next: transition.next,
+      now
+    }))
+      continue;
+    if (transition.next.state === "cancellation-requested") {
+      abortLocalClaimant(runtime, transition.next.attemptToken);
+      return {
+        status: "requested",
+        receipt: toApplicationCommandReceipt(transition.next),
+        cleanupPending: !0
+      };
+    }
+    return { status: "cancelled", receipt: toApplicationCommandReceipt(transition.next) };
+  }
+  throw new MailboxContentionError("cancel", options.commandId);
+}
+async function deadLetterExpired(runtime, loaded, now) {
+  const transition = recoverExpiredCommand(loaded.record, {
+    now,
+    retryBackoffMs: runtime.policy.retryBackoffMs,
+    maxRetryBackoffMs: runtime.policy.maxRetryBackoffMs
+  });
+  if (!transition.ok)
+    return null;
+  if (!await commitCommandTransition(runtime, {
+    previous: loaded.record,
+    expectedBytes: loaded.bytes,
+    next: transition.next,
+    now
+  }))
+    return null;
+  if (isApplicationCommandLeased(loaded.record))
+    releaseAttemptController(runtime, loaded.record.attemptToken, "The application mailbox dead-lettered this command at its absolute deadline.");
+  return toApplicationCommandReceipt(transition.next);
+}
+function abortLocalClaimant(runtime, attemptToken) {
+  const registration = runtime.attemptControllers.get(attemptToken);
+  if (registration !== void 0 && !registration.controller.signal.aborted)
+    registration.controller.abort(Error("The application mailbox cancelled this command."));
+}
+export async function readCleanupState(runtime, commandId) {
+  const observedAt = leaseCommitSerial(), loaded = await loadCommand(runtime.storage, runtime.keys, commandId);
+  if (loaded === null) {
+    releaseAttemptsForCommand(runtime, commandId, "This command no longer exists; its receipt was retired.", void 0, observedAt);
+    return { status: "unknown" };
+  }
+  releaseAttemptsForCommand(runtime, commandId, "This attempt is no longer the current lease on its command.", isApplicationCommandLeased(loaded.record) ? loaded.record.attemptToken : void 0, observedAt);
+  const receipt = toApplicationCommandReceipt(loaded.record);
+  if (receipt.terminalAt !== void 0 && receipt.cleanupPending !== !0)
+    return { status: "settled", receipt };
+  return { status: "pending", receipt };
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Durable reads, index maintenance, and the atomic state-plus-event commit for
+ * the application command mailbox (WFT-84).
+ *
+ * Every mutation goes through {@link commitMailboxTransition}, the mailbox's binding
+ * of the shared `commitApplicationTransition`. When the mailbox
+ * was built with an event sink, the caller's state operations and the sink's own
+ * event write land in one `conditionalBatch`, so no restart can expose the state
+ * transition without its event or the other way round. Without a sink the same
+ * operations commit through `storageConditionalBatch` directly, which keeps the
+ * atomicity guarantee and makes a lost compare-and-swap exactly detectable.
+ *
+ * @module core/mailbox-storage
+ */
+import { type BatchOperation, type ConditionalBatchCondition, type Storage } from '../storage/interface.ts';
+import { type ApplicationCommitPlan, type ApplicationEventSink } from './application-primitive-commit.ts';
+import type { LoadedCommandRecord } from './mailbox-contract.ts';
+import { type ApplicationCommandIdempotencyRecord, type ApplicationCommandRecord, type MailboxRecord } from './mailbox-types.ts';
+/** Every key builder for one `(namespace, resourceId)` mailbox, bound once. */
+export type MailboxKeys = Readonly<{
+    header: string;
+    sinkProbe: (nonce: string) => string;
+    commandPrefix: string;
+    command: (commandId: string) => string;
+    readyPrefix: string;
+    ready: (sequence: number) => string;
+    bySequencePrefix: string;
+    bySequence: (sequence: number) => string;
+    idempotency: (key: string) => string;
+    terminalPrefix: string;
+    terminal: (terminalAt: number, commandId: string) => string;
+}>;
+/**
+ * Bind every mailbox storage key to one namespace and resource.
+ */
+export declare function createMailboxKeys(namespace: string, resourceId: string): MailboxKeys;
+/** The empty header a mailbox starts from, so a first admission has something to compare against. */
+export declare function emptyMailboxRecord(namespace: string, resourceId: string): MailboxRecord;
+/** A header read together with the exact bytes it decoded from, for compare-and-swap. */
+export type LoadedMailboxRecord = {
+    readonly record: MailboxRecord;
+    /** `null` when the mailbox has never been written — the condition for a first admission. */
+    readonly bytes: Uint8Array | null;
+};
+/**
+ * Read the per-mailbox header, treating an absent key as a fresh mailbox.
+ *
+ * @throws {PersistedDataCorruptError} When the stored header is malformed.
+ */
+export declare function loadMailboxHeader(storage: Storage, keys: MailboxKeys, namespace: string, resourceId: string): Promise<LoadedMailboxRecord>;
+/**
+ * Read one command record with the exact bytes it decoded from.
+ *
+ * @throws {PersistedDataCorruptError} When the stored record is malformed.
+ */
+export declare function loadCommand(storage: Storage, keys: MailboxKeys, commandId: string): Promise<LoadedCommandRecord | null>;
+/**
+ * Read the idempotency binding for a retry key.
+ *
+ * @throws {PersistedDataCorruptError} When the stored binding is malformed.
+ */
+export declare function loadIdempotencyBinding(storage: Storage, keys: MailboxKeys, idempotencyKey: string): Promise<{
+    readonly record: ApplicationCommandIdempotencyRecord;
+    readonly bytes: Uint8Array;
+} | null>;
+/**
+ * Read the FIFO head: the lowest-sequence entry still in the delivery index.
+ *
+ * Strict FIFO is the mailbox's ordering contract, so the head is the only entry
+ * a claim may consider. A later command never overtakes a delayed head.
+ *
+ * @throws {PersistedDataCorruptError} When an index entry is malformed.
+ */
+export declare function loadDeliveryHead(storage: Storage, keys: MailboxKeys): Promise<{
+    readonly key: string;
+    readonly bytes: Uint8Array;
+    readonly commandId: string;
+} | null>;
+/**
+ * Put/delete operations that keep the delivery and terminal indexes consistent
+ * with a record's new state.
+ *
+ * The delivery entry is keyed by the command's original admission sequence, so
+ * a redelivered command re-enters the queue at the position it was first
+ * admitted to rather than at the back.
+ */
+export declare function indexOperationsFor(keys: MailboxKeys, previous: ApplicationCommandRecord | null, next: ApplicationCommandRecord): BatchOperation[];
+/** Whether a record is in the delivery index: admitted or released, not yet claimed or settled. */
+export declare function isWaitingState(record: ApplicationCommandRecord): boolean;
+/**
+ * Commit one mailbox transition, atomically with its fleet event when a sink is
+ * configured. The mailbox's binding of the shared commit: see
+ * `application-primitive-commit.ts` for the compare-and-swap classification and
+ * the sink probe.
+ */
+export declare function commitMailboxTransition(storage: Storage, events: ApplicationEventSink | undefined, plan: ApplicationCommitPlan): Promise<boolean>;
+/**
+ * Persist a command record plus its index maintenance as one plan.
+ *
+ * `expectedBytes` must be the exact bytes the record was read as — not a
+ * re-encoding of the decoded value, which `conditionalBatch`'s whole-value byte
+ * comparison would reject.
+ */
+export declare function planCommandTransition(keys: MailboxKeys, options: {
+    readonly previous: ApplicationCommandRecord | null;
+    readonly expectedBytes: Uint8Array | null;
+    readonly next: ApplicationCommandRecord;
+    readonly event: {
+        readonly kind: string;
+        readonly payload: unknown;
+    } | null;
+    readonly now: number;
+    readonly extraConditions?: readonly ConditionalBatchCondition[] | undefined;
+    readonly extraOperations?: readonly BatchOperation[] | undefined;
+}): ApplicationCommitPlan;
+/** The put operation that advances the mailbox header. */
+export declare function headerOperation(keys: MailboxKeys, record: MailboxRecord): BatchOperation;

package/dist/core/mailbox-storage.js

@@ -0,0 +1,115 @@
+import {
+  KEYS
+} from "../storage/interface.js";
+import {
+  commitApplicationTransition
+} from "./application-primitive-commit.js";
+import { decodeApplicationCommandRecord, encodeApplicationCommandRecord } from "./mailbox-codec.js";
+import {
+  decodeApplicationCommandIdempotencyRecord,
+  decodeApplicationReadyEntry,
+  decodeMailboxRecord,
+  encodeApplicationReadyEntry,
+  encodeMailboxRecord
+} from "./mailbox-index-codec.js";
+import {
+  MAILBOX_RECORD_VERSION
+} from "./mailbox-types.js";
+export function createMailboxKeys(namespace, resourceId) {
+  return {
+    header: KEYS.applicationMailbox(namespace, resourceId),
+    sinkProbe: (nonce) => KEYS.applicationMailboxSinkProbe(namespace, resourceId, nonce),
+    commandPrefix: KEYS.applicationCommandPrefix(namespace, resourceId),
+    command: (commandId) => KEYS.applicationCommand(namespace, resourceId, commandId),
+    readyPrefix: KEYS.applicationCommandReadyPrefix(namespace, resourceId),
+    ready: (sequence) => KEYS.applicationCommandReady(namespace, resourceId, sequence),
+    bySequencePrefix: KEYS.applicationCommandBySequencePrefix(namespace, resourceId),
+    bySequence: (sequence) => KEYS.applicationCommandBySequence(namespace, resourceId, sequence),
+    idempotency: (key) => KEYS.applicationCommandIdempotency(namespace, resourceId, key),
+    terminalPrefix: KEYS.applicationCommandTerminalPrefix(namespace, resourceId),
+    terminal: (terminalAt, commandId) => KEYS.applicationCommandTerminal(namespace, resourceId, terminalAt, commandId)
+  };
+}
+export function emptyMailboxRecord(namespace, resourceId) {
+  return {
+    recordVersion: MAILBOX_RECORD_VERSION,
+    namespace,
+    resourceId,
+    nextSequence: 0,
+    openCount: 0,
+    admittedCount: 0
+  };
+}
+export async function loadMailboxHeader(storage, keys, namespace, resourceId) {
+  const bytes = await storage.get(keys.header);
+  if (bytes === null)
+    return { record: emptyMailboxRecord(namespace, resourceId), bytes: null };
+  return { record: decodeMailboxRecord(bytes, keys.header), bytes };
+}
+export async function loadCommand(storage, keys, commandId) {
+  const key = keys.command(commandId), bytes = await storage.get(key);
+  if (bytes === null)
+    return null;
+  return { record: decodeApplicationCommandRecord(bytes, key), bytes };
+}
+export async function loadIdempotencyBinding(storage, keys, idempotencyKey) {
+  const key = keys.idempotency(idempotencyKey), bytes = await storage.get(key);
+  if (bytes === null)
+    return null;
+  return { record: decodeApplicationCommandIdempotencyRecord(bytes, key), bytes };
+}
+export async function loadDeliveryHead(storage, keys) {
+  for await (const [key, value] of storage.scan(keys.readyPrefix, { limit: 1 }))
+    return { key, bytes: value, commandId: decodeApplicationReadyEntry(value, key) };
+  return null;
+}
+export function indexOperationsFor(keys, previous, next) {
+  const operations = [], wasWaiting = previous !== null && isWaitingState(previous), willWait = isWaitingState(next);
+  if (wasWaiting && !willWait)
+    operations.push({ type: "delete", key: keys.ready(next.sequence) });
+  if (willWait && !wasWaiting)
+    operations.push({
+      type: "put",
+      key: keys.ready(next.sequence),
+      value: encodeApplicationReadyEntry(next.commandId)
+    });
+  if (isTerminalState(next) && (previous === null || !isTerminalState(previous)))
+    operations.push({
+      type: "put",
+      key: keys.terminal(next.terminalAt, next.commandId),
+      value: encodeApplicationReadyEntry(next.commandId)
+    });
+  return operations;
+}
+export function isWaitingState(record) {
+  return record.state === "accepted" || record.state === "available";
+}
+function isTerminalState(record) {
+  return record.state === "applied" || record.state === "rejected" || record.state === "cancelled" || record.state === "dead-lettered";
+}
+export function commitMailboxTransition(storage, events, plan) {
+  return commitApplicationTransition(storage, events, plan, "application mailbox");
+}
+export function planCommandTransition(keys, options) {
+  return {
+    sinkProbeKey: keys.sinkProbe(crypto.randomUUID()),
+    conditions: [
+      { key: keys.command(options.next.commandId), expectedValue: options.expectedBytes },
+      ...options.extraConditions ?? []
+    ],
+    operations: [
+      {
+        type: "put",
+        key: keys.command(options.next.commandId),
+        value: encodeApplicationCommandRecord(options.next)
+      },
+      ...indexOperationsFor(keys, options.previous, options.next),
+      ...options.extraOperations ?? []
+    ],
+    event: options.event,
+    now: options.now
+  };
+}
+export function headerOperation(keys, record) {
+  return { type: "put", key: keys.header, value: encodeMailboxRecord(record) };
+}

package/dist/core/mailbox-transition-helpers.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The primitives every mailbox transition shares (WFT-84):
+ * the rejection vocabulary, the transition result shape, non-terminal
+ * narrowing, identity-field carry-over, and retry backoff.
+ *
+ * Extracted so `mailbox-transitions.ts` and
+ * `mailbox-transitions-recovery.ts` can both use them without
+ * importing each other — a runtime cycle this repository forbids outright.
+ *
+ * @module core/mailbox-transition-helpers
+ */
+import { computeRetryBackoffMs } from './application-primitive-timing.ts';
+import type { ApplicationCommandAccepted, ApplicationCommandAvailable, ApplicationCommandCancelling, ApplicationCommandClaimed, ApplicationCommandRecord, ApplicationCommandTerminalRecord } from './mailbox-types.ts';
+export { computeRetryBackoffMs };
+/**
+ * Why a proposed transition is illegal. Stable and low-cardinality, so callers
+ * can map each reason onto a discriminated result without string matching.
+ */
+export type MailboxTransitionRejection = 'stale-attempt' | 'not-leased' | 'not-waiting' | 'not-due' | 'deadline-exceeded' | 'already-terminal';
+/**
+ * The outcome of a proposed transition: the record to persist, or why the edge
+ * is illegal.
+ */
+export type MailboxTransition<TNext> = {
+    readonly ok: true;
+    readonly next: TNext;
+} | {
+    readonly ok: false;
+    readonly reason: MailboxTransitionRejection;
+};
+export declare function rejectedTransition<TNext>(reason: MailboxTransitionRejection): MailboxTransition<TNext>;
+export declare function succeededTransition<TNext>(next: TNext): MailboxTransition<TNext>;
+/**
+ * Narrow a record to the four non-terminal states.
+ *
+ * `isApplicationCommandTerminalState` narrows the `state` string but not the
+ * record it came from, so every transition below needs this to stay cast-free.
+ */
+export declare function isTerminalCommandRecord(record: ApplicationCommandRecord): record is ApplicationCommandTerminalRecord;
+export declare function nonTerminalCommandRecord(record: ApplicationCommandRecord): ApplicationCommandAccepted | ApplicationCommandAvailable | ApplicationCommandClaimed | ApplicationCommandCancelling | null;
+/** Strip the state-specific fields so a transition rebuilds a record from identity alone. */
+export declare function applicationCommandIdentityFields(record: ApplicationCommandRecord): {
+    readonly recordVersion: 1;
+    readonly namespace: string;
+    readonly resourceId: string;
+    readonly commandId: string;
+    readonly sequence: number;
+    readonly idempotencyKey: string | undefined;
+    readonly caller: string;
+    readonly target: string;
+    readonly kind: string;
+    readonly payload: import("./mailbox-types.ts").ApplicationCommandPayload;
+    readonly payloadDigest: string;
+    readonly payloadMediaType: string | undefined;
+    readonly payloadSchema: string | undefined;
+    readonly causation: Readonly<{
+        correlationId?: string | undefined;
+        causationId?: string | undefined;
+        traceparent?: string | undefined;
+    }> | undefined;
+    readonly acceptedAt: number;
+    readonly absoluteDeadlineAt: number;
+    readonly maxAttempts: number;
+    readonly visibilityTimeoutMs: number;
+    readonly generation: number;
+    readonly attempt: number;
+    readonly retryCount: number;
+    readonly firstClaimedAt: number | undefined;
+    readonly availableAt: number;
+};

package/dist/core/mailbox-transition-helpers.js

@@ -0,0 +1,43 @@
+import { computeRetryBackoffMs } from "./application-primitive-timing.js";
+import { MAILBOX_RECORD_VERSION, isApplicationCommandTerminalState } from "./mailbox-types.js";
+
+export { computeRetryBackoffMs };
+export function rejectedTransition(reason) {
+  return { ok: !1, reason };
+}
+export function succeededTransition(next) {
+  return { ok: !0, next };
+}
+export function isTerminalCommandRecord(record) {
+  return isApplicationCommandTerminalState(record.state);
+}
+export function nonTerminalCommandRecord(record) {
+  return isTerminalCommandRecord(record) ? null : record;
+}
+export function applicationCommandIdentityFields(record) {
+  return {
+    recordVersion: MAILBOX_RECORD_VERSION,
+    namespace: record.namespace,
+    resourceId: record.resourceId,
+    commandId: record.commandId,
+    sequence: record.sequence,
+    idempotencyKey: record.idempotencyKey,
+    caller: record.caller,
+    target: record.target,
+    kind: record.kind,
+    payload: record.payload,
+    payloadDigest: record.payloadDigest,
+    payloadMediaType: record.payloadMediaType,
+    payloadSchema: record.payloadSchema,
+    causation: record.causation,
+    acceptedAt: record.acceptedAt,
+    absoluteDeadlineAt: record.absoluteDeadlineAt,
+    maxAttempts: record.maxAttempts,
+    visibilityTimeoutMs: record.visibilityTimeoutMs,
+    generation: record.generation + 1,
+    attempt: record.attempt,
+    retryCount: record.retryCount,
+    firstClaimedAt: record.firstClaimedAt,
+    availableAt: record.availableAt
+  };
+}

package/dist/core/mailbox-transitions-recovery.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The time-driven recovery transitions for the application command mailbox
+ * (WFT-84): reclaiming an expired lease and terminalizing a command past its
+ * absolute deadline.
+ *
+ * Split out of `mailbox-transitions.ts` only to keep both files
+ * under this repository's file-size ceiling; `recoverExpiredCommand` is
+ * re-exported from there so callers still have one import.
+ *
+ * @module core/mailbox-transitions-recovery
+ */
+import { type MailboxTransition } from './mailbox-transition-helpers.ts';
+import type { ApplicationCommandAccepted, ApplicationCommandRecord, ApplicationCommandTerminalRecord } from './mailbox-types.ts';
+/**
+ * Recover a command whose lease expired or whose absolute deadline passed.
+ *
+ * A claimed command returns to `accepted` at its original FIFO position while
+ * attempts remain, and is dead-lettered once they are gone. A
+ * cancellation-requested command becomes `cancelled` with `cleanupPending:
+ * true` — the mailbox stopped waiting for the claimant, which is not the same
+ * as the claimant having stopped. Any non-terminal command past its absolute
+ * deadline is dead-lettered regardless of remaining attempts.
+ */
+export declare function recoverExpiredCommand(record: ApplicationCommandRecord, options: {
+    readonly now: number;
+    readonly retryBackoffMs: number;
+    readonly maxRetryBackoffMs: number;
+}): MailboxTransition<ApplicationCommandAccepted | ApplicationCommandTerminalRecord>;