@lostgradient/weft 0.23.1 → 0.24.1

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

@@ -0,0 +1,290 @@
+/**
+ * The public input, result, and option types for the durable application
+ * command mailbox (WFT-84).
+ *
+ * Two rules shape every signature here. First, expected outcomes are
+ * discriminated results, never exceptions: an idempotency conflict, a full
+ * backlog, a stale attempt token, and an already-terminal command are all
+ * ordinary control flow a caller must branch on. Exceptions are reserved for
+ * caller mistakes (`ApplicationCommandValidationError`) and corrupt persisted
+ * state (`PersistedDataCorruptError`). Second, every read is non-consuming:
+ * `receipt`, `list`, `capacity`, and `cleanupState` never claim, start, or
+ * advance work.
+ *
+ * @module core/mailbox-contract
+ */
+import type { BatchOperation, ConditionalBatchCondition, Storage } from '../storage/interface.ts';
+import type { JSONValue } from './json.ts';
+import type { ApplicationCommandCausation, ApplicationCommandFailure, ApplicationCommandPayload, ApplicationCommandRecord, ApplicationCommandState } from './mailbox-types.ts';
+/**
+ * The transaction-composable append contract the mailbox needs from a durable
+ * event feed (WFT-83).
+ *
+ * Declared structurally rather than imported from `server/fleet-event-feed.ts`
+ * so `src/core` keeps no runtime dependency on `src/server`. A real
+ * `FleetEventFeed` satisfies it as-is — pass one straight in.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage } from '@lostgradient/weft';
+ * import type { MailboxEventSink } from '@lostgradient/weft';
+ * import { createFleetEventFeed } from '@lostgradient/weft/server/handler';
+ *
+ * const events: MailboxEventSink = createFleetEventFeed(new MemoryStorage());
+ * void events;
+ * ```
+ */
+export type MailboxEventSink = {
+    append(event: {
+        readonly kind: string;
+        readonly emittedAtMs: number;
+        readonly payload: unknown;
+        readonly workflowId?: string | undefined;
+    }, options?: {
+        readonly conditions?: readonly ConditionalBatchCondition[] | undefined;
+        readonly operations?: readonly BatchOperation[] | undefined;
+    }): Promise<unknown>;
+};
+/**
+ * What a claimant may supply when rejecting a command: only the `application`
+ * reason. `attempts-exhausted`, `deadline-exceeded`, and `cancelled` each name
+ * a mailbox-owned terminal mechanism and are written by the transition that
+ * owns it; the broader `ApplicationCommandFailure` is what receipts carry.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandRejection } from '@lostgradient/weft';
+ *
+ * const rejection: ApplicationCommandRejection = { reason: 'application', message: 'unsupported kind' };
+ * console.log(rejection.reason); // 'application'
+ * ```
+ */
+export type ApplicationCommandRejection = Readonly<{
+    reason: 'application';
+    message?: string | undefined;
+    details?: JSONValue | undefined;
+}>;
+/**
+ * Construction options for one `(namespace, resourceId)` mailbox.
+ *
+ * @example
+ * ```ts
+ * import { MemoryStorage, type MailboxOptions } from '@lostgradient/weft';
+ *
+ * const options: MailboxOptions = {
+ *   storage: new MemoryStorage(),
+ *   namespace: 'bureau',
+ *   resourceId: 'agent-7',
+ *   maxBacklog: 512,
+ * };
+ * console.log(options.namespace); // 'bureau'
+ * ```
+ */
+export type MailboxOptions = {
+    /** Durable backend. Must report `conditionalBatch` support. */
+    readonly storage: Storage;
+    /** Opaque application namespace. Weft never interprets it. */
+    readonly namespace: string;
+    /** Opaque resource identifier. One mailbox, one FIFO order. */
+    readonly resourceId: string;
+    /**
+     * Optional durable event feed. When supplied, every state transition and its
+     * fleet event commit in one conditional batch, so no restart can expose one
+     * side without the other.
+     */
+    readonly events?: MailboxEventSink | undefined;
+    /** Maximum open (non-terminal) commands. Admission past it is rejected before any write. Default 1000. */
+    readonly maxBacklog?: number | undefined;
+    /** Default claim lease duration in milliseconds. Default 30000. */
+    readonly visibilityTimeoutMs?: number | undefined;
+    /** Default absolute per-command deadline in milliseconds from admission. Default 3600000. */
+    readonly commandTimeoutMs?: number | undefined;
+    /** Default maximum claims per command before dead-lettering. Default 3. */
+    readonly maxAttempts?: number | undefined;
+    /** Retry backoff base in milliseconds. Default 1000. */
+    readonly retryBackoffMs?: number | undefined;
+    /** Ceiling on retry backoff in milliseconds. Default 60000. */
+    readonly maxRetryBackoffMs?: number | undefined;
+    /** How long a terminal receipt is retained before a maintenance sweep may delete it. Default 86400000. */
+    readonly terminalRetentionMs?: number | undefined;
+    /** Maximum bytes an inline payload may encode to. Default 262144. */
+    readonly maxInlinePayloadBytes?: number | undefined;
+    /**
+     * How many command records one maintenance scan page reads. Default 500.
+     *
+     * A pass walks the whole keyspace in pages of this size, up to a bounded page
+     * count, then hands its cursor to the next pass. Lower it on a constrained
+     * runtime that cannot afford a large scan per call.
+     */
+    readonly maintenanceBatchSize?: number | undefined;
+    /** Injected clock. Defaults to `Date.now`. */
+    readonly now?: (() => number) | undefined;
+    /** Injected identifier source, for deterministic tests. Defaults to `crypto.randomUUID`. */
+    readonly generateId?: (() => string) | undefined;
+};
+/**
+ * A command offered to the mailbox.
+ *
+ * `commandId` is minted by the mailbox, not supplied here: `idempotencyKey` is
+ * the caller's only retry handle, and it binds to
+ * `(caller, target, kind, payloadDigest)`.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandInput } from '@lostgradient/weft';
+ *
+ * const command: ApplicationCommandInput = {
+ *   caller: 'user:42',
+ *   target: 'agent:7',
+ *   kind: 'steer',
+ *   payload: { form: 'inline', value: { text: 'stop' } },
+ *   idempotencyKey: 'steer-1',
+ * };
+ * console.log(command.kind); // 'steer'
+ * ```
+ */
+export type ApplicationCommandInput = {
+    /** Opaque caller identity. Part of the idempotency binding. */
+    readonly caller: string;
+    /** Opaque target within the resource. Part of the idempotency binding. */
+    readonly target: string;
+    /** Opaque command kind. Part of the idempotency binding. */
+    readonly kind: string;
+    readonly payload: ApplicationCommandPayload;
+    /** Retry handle. Absent means every admission creates a new command. */
+    readonly idempotencyKey?: string | undefined;
+    readonly payloadMediaType?: string | undefined;
+    readonly payloadSchema?: string | undefined;
+    readonly causation?: ApplicationCommandCausation | undefined;
+    /** Delay before the command is released for delivery. Default 0. */
+    readonly availableAfterMs?: number | undefined;
+    /** Per-command overrides of the mailbox defaults. */
+    readonly maxAttempts?: number | undefined;
+    readonly visibilityTimeoutMs?: number | undefined;
+    readonly commandTimeoutMs?: number | undefined;
+};
+/**
+ * The outcome of offering a command.
+ *
+ * `admitted` and `duplicate` both carry the authoritative receipt — a duplicate
+ * returns the original, never a second command. `conflict` means the
+ * idempotency key is already bound to a different
+ * `(caller, target, kind, payloadDigest)`; the original command is untouched.
+ * `rejected` means the backlog is full and nothing was persisted.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandAdmission } from '@lostgradient/weft';
+ *
+ * declare const admission: ApplicationCommandAdmission;
+ * if (admission.status === 'admitted') console.log(admission.receipt.commandId);
+ * ```
+ */
+export type ApplicationCommandAdmission = {
+    readonly status: 'admitted';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'duplicate';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'conflict';
+    readonly receipt: ApplicationCommandReceipt;
+    readonly reason: 'idempotency-identity-mismatch';
+} | {
+    readonly status: 'rejected';
+    readonly reason: 'backlog-full';
+    readonly capacity: MailboxCapacity;
+};
+/**
+ * An immutable point-in-time view of a command. Safe to share across observers:
+ * reading one never claims, starts, or advances work.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandReceipt } from '@lostgradient/weft';
+ *
+ * declare const receipt: ApplicationCommandReceipt;
+ * console.log(receipt.state, receipt.attempt);
+ * ```
+ */
+export type ApplicationCommandReceipt = Readonly<{
+    commandId: string;
+    namespace: string;
+    resourceId: string;
+    sequence: number;
+    state: ApplicationCommandState;
+    caller: string;
+    target: string;
+    kind: string;
+    payloadDigest: string;
+    payloadForm: ApplicationCommandPayload['form'];
+    payloadMediaType?: string | undefined;
+    payloadSchema?: string | undefined;
+    idempotencyKey?: string | undefined;
+    causation?: ApplicationCommandCausation | undefined;
+    acceptedAt: number;
+    availableAt: number;
+    absoluteDeadlineAt: number;
+    attempt: number;
+    retryCount: number;
+    maxAttempts: number;
+    generation: number;
+    /**
+     * Lease liveness, present only while an attempt holds the command.
+     *
+     * The attempt token itself is deliberately NOT here. It is a fencing
+     * credential, and a receipt is readable by any observer — publishing it would
+     * let a bystander settle work it never claimed.
+     */
+    claimedAt?: number | undefined;
+    visibilityExpiresAt?: number | undefined;
+    lastActivityAt?: number | undefined;
+    progress?: JSONValue | undefined;
+    cancellationRequestedAt?: number | undefined;
+    cancellationReason?: string | undefined;
+    terminalAt?: number | undefined;
+    outcome?: JSONValue | undefined;
+    failure?: ApplicationCommandFailure | undefined;
+    /** True when the command terminalized while an attempt still held it and never settled. */
+    cleanupPending?: boolean | undefined;
+}>;
+/** Bounded backlog accounting. Deliberately low-cardinality: no per-command detail.
+ *
+ * @example
+ * ```ts
+ * import type { MailboxCapacity } from '@lostgradient/weft';
+ *
+ * declare const capacity: MailboxCapacity;
+ * console.log(capacity.open, capacity.remaining, capacity.limit);
+ * ```
+ */
+export type MailboxCapacity = Readonly<{
+    /** Commands admitted and not yet terminal. */
+    open: number;
+    /** Configured ceiling on `open`. */
+    limit: number;
+    /** `limit - open`, floored at zero. */
+    remaining: number;
+    /** Lifetime admissions. */
+    admitted: number;
+}>;
+/** Bounded listing options. `limit` is clamped to 1000.
+ *
+ * @example
+ * ```ts
+ * import type { MailboxListOptions } from '@lostgradient/weft';
+ *
+ * const options: MailboxListOptions = { limit: 50, states: ['available'] };
+ * console.log(options.limit); // 50
+ * ```
+ */
+export type MailboxListOptions = {
+    readonly limit?: number | undefined;
+    readonly states?: readonly ApplicationCommandState[] | undefined;
+};
+export type { ApplicationCommandCancellationResult, ApplicationCommandClaim, ApplicationCommandClaimedPayload, ApplicationCommandCleanupResult, ApplicationCommandRenewalResult, ApplicationCommandSettleResult, MailboxClaimResult, MailboxMaintenanceReport, MailboxWaitOptions, } from './mailbox-claims.ts';
+/** Internal helper alias: the decoded record plus the exact bytes it was read as. */
+export type LoadedCommandRecord = {
+    readonly record: ApplicationCommandRecord;
+    readonly bytes: Uint8Array;
+};

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

@@ -0,0 +1,37 @@
+/**
+ * Delivery for the application command mailbox (WFT-84): leasing the FIFO head
+ * to one attempt and handing that attempt a digest-verified payload.
+ *
+ * Strict FIFO is the ordering contract. A claim only ever considers the
+ * lowest-sequence entry in the delivery index, so a later command never
+ * overtakes a delayed head — `claim()` reports `held` instead of skipping
+ * ahead. That also means head-of-line blocking is real and intended: a command
+ * in retry backoff holds its resource's queue until it is due or dead-lettered.
+ *
+ * @module core/mailbox-delivery
+ */
+import type { ApplicationCommandClaimedPayload, MailboxClaimResult } from './mailbox-contract.ts';
+import { type MailboxRuntime } from './mailbox-internals.ts';
+import type { ApplicationCommandRecord } from './mailbox-types.ts';
+/**
+ * Recompute an inline payload's digest and fail closed on a mismatch.
+ *
+ * A reference payload cannot be verified here — Weft never dereferences the
+ * locator — so the consumer receives the stored digest and `verified: false`
+ * rather than a guarantee the mailbox cannot back up.
+ *
+ * @throws {PersistedDataCorruptError} When a stored inline payload no longer
+ * matches the digest admission recorded for it.
+ */
+export declare function verifyClaimedPayload(runtime: MailboxRuntime, record: ApplicationCommandRecord): Promise<ApplicationCommandClaimedPayload>;
+/**
+ * Lease the FIFO head of a mailbox to one attempt.
+ *
+ * The returned claim carries an attempt-scoped `AbortSignal` registered in this
+ * process, so a cancellation request raised here reaches the claimant
+ * immediately. A claimant in another process learns about cancellation from
+ * `renew()` instead — the signal is process-local by construction.
+ */
+export declare function claimNextCommand(runtime: MailboxRuntime, options?: {
+    readonly signal?: AbortSignal | undefined;
+}): Promise<MailboxClaimResult>;

package/dist/core/mailbox-delivery.js

@@ -0,0 +1,193 @@
+import { storageConditionalBatch } from "../storage/interface.js";
+import { computePayloadDigest } from "./application-payload-digest.js";
+import { raceAbort } from "./application-primitive-abort.js";
+import {
+  nextLeaseCommitSerial
+} from "./application-primitive-attempt-registry.js";
+import {
+  commitCommandTransition,
+  MailboxContentionError,
+  MAX_MAILBOX_TRANSITION_ATTEMPTS,
+  toApplicationCommandReceipt
+} from "./mailbox-internals.js";
+import { isWaitingState, loadCommand, loadDeliveryHead } from "./mailbox-storage.js";
+import { recoverExpiredCommand } from "./mailbox-transitions-recovery.js";
+import { claimWaitingCommand } from "./mailbox-transitions.js";
+import { requireClockInstant, requireGeneratedIdentifier } from "./mailbox-validation.js";
+import { PersistedDataCorruptError } from "./persisted-data-incompatible-error.js";
+let localClaimSerial = 0;
+export async function verifyClaimedPayload(runtime, record) {
+  if (record.payload.form === "reference")
+    return {
+      form: "reference",
+      reference: record.payload.reference,
+      digest: record.payload.digest,
+      byteLength: record.payload.byteLength,
+      verified: !1
+    };
+  const digest = await computePayloadDigest(record.payload.value);
+  if (digest !== record.payloadDigest)
+    throw new PersistedDataCorruptError(runtime.keys.command(record.commandId));
+  return { form: "inline", value: record.payload.value, digest, verified: !0 };
+}
+function isOrphanedEntry(runtime, head, loaded) {
+  return !isWaitingState(loaded.record) || head.key !== runtime.keys.ready(loaded.record.sequence);
+}
+async function discardOrphanedEntry(runtime, head, observed) {
+  return storageConditionalBatch(runtime.storage, [
+    { key: head.key, expectedValue: head.bytes },
+    {
+      key: runtime.keys.command(head.commandId),
+      expectedValue: observed === null ? null : observed.bytes
+    }
+  ], [{ type: "delete", key: head.key }]);
+}
+async function terminalizeExpiredHead(runtime, loaded, now) {
+  const transition = recoverExpiredCommand(loaded.record, {
+    now,
+    retryBackoffMs: runtime.policy.retryBackoffMs,
+    maxRetryBackoffMs: runtime.policy.maxRetryBackoffMs
+  });
+  if (!transition.ok)
+    return !0;
+  return commitCommandTransition(runtime, {
+    previous: loaded.record,
+    expectedBytes: loaded.bytes,
+    next: transition.next,
+    now
+  });
+}
+async function resolveDeliverableHead(runtime, now) {
+  const head = await loadDeliveryHead(runtime.storage, runtime.keys);
+  if (head === null)
+    return { status: "empty" };
+  const loaded = await loadCommand(runtime.storage, runtime.keys, head.commandId);
+  if (loaded === null || isOrphanedEntry(runtime, head, loaded))
+    return { status: "retry", progressed: await discardOrphanedEntry(runtime, head, loaded) };
+  if (now >= loaded.record.absoluteDeadlineAt)
+    return { status: "retry", progressed: await terminalizeExpiredHead(runtime, loaded, now) };
+  if (now < loaded.record.availableAt)
+    return {
+      status: "held",
+      availableAt: Math.min(loaded.record.availableAt, loaded.record.absoluteDeadlineAt)
+    };
+  return { status: "claimable", loaded };
+}
+function registerAttemptController(runtime, attemptToken, commandId) {
+  const controller = new AbortController, release = runtime.adoptAttempt(attemptToken);
+  if (release === null) {
+    controller.abort(Error("The application mailbox was disposed while this claim committed."));
+    return { controller, registration: null };
+  }
+  const registration = {
+    controller,
+    release,
+    subjectId: commandId,
+    committedSerial: null
+  };
+  runtime.attemptControllers.set(attemptToken, registration);
+  return { controller, registration };
+}
+function releaseOwnRegistration(runtime, attemptToken, registration, reason) {
+  if (registration === null)
+    return;
+  if (runtime.attemptControllers.get(attemptToken) === registration)
+    runtime.attemptControllers.delete(attemptToken);
+  registration.release();
+  if (!registration.controller.signal.aborted)
+    registration.controller.abort(Error(reason));
+}
+export async function claimNextCommand(runtime, options) {
+  let losses = 0;
+  while (losses < MAX_MAILBOX_TRANSITION_ATTEMPTS) {
+    options?.signal?.throwIfAborted();
+    const outcome = await attemptClaim(runtime, options?.signal);
+    if ("status" in outcome)
+      return outcome;
+    if (outcome.lost)
+      losses += 1;
+  }
+  throw new MailboxContentionError("claim", null);
+}
+async function deadLetterCommittedLease(runtime, commandId) {
+  const loaded = await loadCommand(runtime.storage, runtime.keys, commandId);
+  if (loaded === null)
+    return;
+  const now = runtime.now(), transition = recoverExpiredCommand(loaded.record, {
+    now,
+    retryBackoffMs: runtime.policy.retryBackoffMs,
+    maxRetryBackoffMs: runtime.policy.maxRetryBackoffMs
+  });
+  if (!transition.ok)
+    return;
+  await commitCommandTransition(runtime, {
+    previous: loaded.record,
+    expectedBytes: loaded.bytes,
+    next: transition.next,
+    now
+  });
+}
+async function attemptClaim(runtime, signal) {
+  const now = runtime.now(), head = await observeHead(runtime, now, signal);
+  if (head.status === "empty")
+    return { status: "empty" };
+  if (head.status === "held")
+    return { status: "held", availableAt: head.availableAt };
+  if (head.status === "retry")
+    return { lost: !head.progressed };
+  return await leaseHead(runtime, head.loaded, signal) ?? { lost: !0 };
+}
+async function observeHead(runtime, now, signal) {
+  const observed = await raceAbort(() => resolveDeliverableHead(runtime, now), signal);
+  if (observed.aborted)
+    throw observed.reason;
+  signal?.throwIfAborted();
+  return observed.value;
+}
+async function leaseHead(runtime, loaded, requestSignal) {
+  const payload = await verifyClaimedPayload(runtime, loaded.record), committedAt = requireClockInstant(runtime.now());
+  requestSignal?.throwIfAborted();
+  const generated = requireGeneratedIdentifier(runtime.generateId(), "attemptToken");
+  localClaimSerial += 1;
+  const attemptToken = `${loaded.record.sequence}.${loaded.record.attempt + 1}.${localClaimSerial}.${generated}`, transition = claimWaitingCommand(loaded.record, { now: committedAt, attemptToken });
+  if (!transition.ok)
+    return null;
+  const { controller, registration } = registerAttemptController(runtime, attemptToken, loaded.record.commandId);
+  let committed;
+  try {
+    committed = await commitCommandTransition(runtime, {
+      previous: loaded.record,
+      expectedBytes: loaded.bytes,
+      next: transition.next,
+      now: committedAt
+    });
+  } catch (error) {
+    releaseOwnRegistration(runtime, attemptToken, registration, "The claim commit failed.");
+    throw error;
+  }
+  if (!committed) {
+    releaseOwnRegistration(runtime, attemptToken, registration, "The claim lost its compare-and-swap.");
+    return null;
+  }
+  if (registration !== null)
+    registration.committedSerial = nextLeaseCommitSerial();
+  if (runtime.now() >= transition.next.absoluteDeadlineAt) {
+    releaseOwnRegistration(runtime, attemptToken, registration, "The application mailbox dead-lettered this command at its absolute deadline.");
+    await deadLetterCommittedLease(runtime, transition.next.commandId);
+    return null;
+  }
+  if (requestSignal?.aborted === !0 && !controller.signal.aborted)
+    controller.abort(Error("The claim request was aborted while this claim committed."));
+  return {
+    status: "claimed",
+    claim: {
+      receipt: toApplicationCommandReceipt(transition.next),
+      payload,
+      attemptToken,
+      attempt: transition.next.attempt,
+      visibilityExpiresAt: transition.next.visibilityExpiresAt,
+      absoluteDeadlineAt: transition.next.absoluteDeadlineAt,
+      signal: controller.signal
+    }
+  };
+}

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

@@ -0,0 +1,78 @@
+/**
+ * Field-level guards for the durable application command mailbox (WFT-84).
+ *
+ * The generic checks — identities, durable JSON metadata, clock readings,
+ * generated identifiers, derived instants, wait budgets — live in
+ * `application-primitive-guards.ts` and are bound here to the mailbox's own
+ * validation error class, so a mailbox caller always sees
+ * `ApplicationCommandValidationError`. What remains here is what only the
+ * mailbox validates: its backlog and listing ceilings, a claimant's rejection,
+ * and a cancellation reason.
+ *
+ * Everything here is re-exported from `mailbox-validation.ts`, so
+ * mailbox callers keep one import path.
+ *
+ * @module core/mailbox-guards
+ */
+import type { ApplicationCommandRejection } from './mailbox-contract.ts';
+import type { ApplicationCommandFailure } from './mailbox-types.ts';
+import { WeftError } from './weft-error.ts';
+export { byteLengthOf, DEFAULT_WAIT_POLL_INTERVAL_MS, isWellFormedString, MAX_APPLICATION_IDENTITY_BYTES, MAX_DURABLE_METADATA_BYTES, MAX_TIMER_DELAY_MS, } from './application-primitive-guards.ts';
+/** Maximum bytes in an idempotency key. */
+export declare const MAX_APPLICATION_IDEMPOTENCY_KEY_BYTES = 256;
+/** Maximum bytes in a content-addressed payload reference. */
+export { MAX_APPLICATION_PAYLOAD_REFERENCE_BYTES } from './application-primitive-payload.ts';
+/** Maximum claims allowed for one command. */
+export declare const MAX_APPLICATION_COMMAND_ATTEMPTS = 100;
+/** Maximum open commands a mailbox may be configured to hold. */
+export declare const MAX_MAILBOX_BACKLOG = 1000000;
+/** Maximum receipts one `list()` call may return. */
+export declare const MAX_MAILBOX_LIST_LIMIT = 1000;
+/** Maximum bytes in a caller-supplied failure message. */
+export declare const MAX_FAILURE_MESSAGE_BYTES = 2048;
+/** Maximum bytes in a caller-supplied cancellation reason. */
+export declare const MAX_CANCELLATION_REASON_BYTES = 2048;
+/**
+ * Thrown when a caller hands the mailbox something it cannot admit: a missing
+ * or oversized identity component, an unusable payload, or an out-of-range
+ * policy value.
+ *
+ * This is a caller mistake, not an expected outcome — a full backlog and an
+ * idempotency conflict are returned as discriminated results instead.
+ *
+ * @example
+ * ```ts
+ * import { ApplicationCommandValidationError } from '@lostgradient/weft';
+ *
+ * const error = new ApplicationCommandValidationError('caller must be a non-empty string.');
+ * console.log(error.code); // 'ApplicationCommandValidationError'
+ * ```
+ */
+export declare class ApplicationCommandValidationError extends WeftError<'ApplicationCommandValidationError'> {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare const requireIdentity: (value: unknown, field: string, maxBytes: number) => string, optionalIdentityOf: (value: unknown, field: string, maxBytes: number) => string | undefined, requirePositiveInteger: (value: unknown, field: string, maximum: number) => number, requireNonNegativeInteger: (value: unknown, field: string, maximum: number) => number, validateDurableJSONValue: (value: unknown, field: string) => import("./json.ts").JSONValue | undefined, requireGeneratedIdentifier: (value: string, field: string) => string, requireClockInstant: (now: number, source?: string) => number, requireDerivedInstant: (instant: number, field: string) => number, requireMaintenanceInstant: (now: number) => number, requireWaitBudget: (options: {
+    readonly timeoutMs?: number | undefined;
+    readonly pollIntervalMs?: number | undefined;
+}) => {
+    readonly timeoutMs: number;
+    readonly pollIntervalMs: number;
+};
+/**
+ * Validate a caller-supplied failure record before it becomes terminal evidence.
+ *
+ * @throws {ApplicationCommandValidationError} When `details` is not JSON-safe.
+ */
+export declare function validateFailure(failure: ApplicationCommandRejection): ApplicationCommandFailure;
+/**
+ * Validate a caller-supplied cancellation reason before it becomes part of a
+ * durable record.
+ *
+ * @throws {ApplicationCommandValidationError} When the reason is oversized or
+ * not well-formed.
+ */
+export declare function validateCancellationReason(reason: string | undefined): string | undefined;
+/**
+ * Clamp a caller-supplied listing limit into the bounded range.
+ */
+export declare function clampListLimit(limit: number | undefined): number;

package/dist/core/mailbox-guards.js

@@ -0,0 +1,58 @@
+import { createApplicationGuards } from "./application-primitive-guards.js";
+import { WeftError } from "./weft-error.js";
+export {
+  byteLengthOf,
+  DEFAULT_WAIT_POLL_INTERVAL_MS,
+  isWellFormedString,
+  MAX_APPLICATION_IDENTITY_BYTES,
+  MAX_DURABLE_METADATA_BYTES,
+  MAX_TIMER_DELAY_MS
+} from "./application-primitive-guards.js";
+export const MAX_APPLICATION_IDEMPOTENCY_KEY_BYTES = 256;
+export { MAX_APPLICATION_PAYLOAD_REFERENCE_BYTES } from "./application-primitive-payload.js";
+export const MAX_APPLICATION_COMMAND_ATTEMPTS = 100, MAX_MAILBOX_BACKLOG = 1e6, MAX_MAILBOX_LIST_LIMIT = 1000, MAX_FAILURE_MESSAGE_BYTES = 2048, MAX_CANCELLATION_REASON_BYTES = 2048;
+
+export class ApplicationCommandValidationError extends WeftError {
+  constructor(message, options) {
+    super("ApplicationCommandValidationError", message, options);
+  }
+}
+const guards = createApplicationGuards(ApplicationCommandValidationError);
+export const {
+  requireIdentity,
+  optionalIdentityOf,
+  requirePositiveInteger,
+  requireNonNegativeInteger,
+  validateDurableJSONValue,
+  requireGeneratedIdentifier,
+  requireClockInstant,
+  requireDerivedInstant,
+  requireMaintenanceInstant,
+  requireWaitBudget
+} = guards;
+const CALLER_FAILURE_REASONS = new Set([
+  "application"
+]);
+export function validateFailure(failure) {
+  if (typeof failure !== "object" || failure === null)
+    throw new ApplicationCommandValidationError("failure must be an object.");
+  const reason = failure.reason;
+  if (!CALLER_FAILURE_REASONS.has(reason))
+    throw new ApplicationCommandValidationError(`failure.reason must be one of ${[...CALLER_FAILURE_REASONS].join(", ")}; attempts-exhausted, deadline-exceeded, and cancelled are assigned by the mailbox.`);
+  const details = validateDurableJSONValue(failure.details, "failure.details");
+  return {
+    reason,
+    message: optionalIdentityOf(failure.message, "failure.message", MAX_FAILURE_MESSAGE_BYTES),
+    details
+  };
+}
+export function validateCancellationReason(reason) {
+  return optionalIdentityOf(reason, "reason", MAX_CANCELLATION_REASON_BYTES);
+}
+export function clampListLimit(limit) {
+  if (limit === void 0)
+    return 100;
+  if (!Number.isSafeInteger(limit) || limit < 1)
+    throw new ApplicationCommandValidationError("limit must be a positive safe integer.");
+  return Math.min(limit, MAX_MAILBOX_LIST_LIMIT);
+}