@lostgradient/weft 0.23.0 → 0.24.0

package/dist/core/outbox-validation.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Bounds and input validation for the durable application delivery outbox
+ * (WFT-85): construction options, offered deliveries, and adapter outcomes.
+ *
+ * Every bound here exists so a hostile or buggy caller — or a misbehaving
+ * transport — cannot grow durable storage without limit, push an unbounded
+ * string into a storage key, or write a record the decoder rejects. The outbox
+ * validates at the boundary, before any write, so a rejected input leaves no
+ * trace.
+ *
+ * @module core/outbox-validation
+ */
+import type { JSONValue } from './json.ts';
+import type { ApplicationDeliveryInput, OutboxOptions } from './outbox-contract.ts';
+import type { ApplicationDeliveryFailure, ApplicationDeliveryPayload, ApplicationDeliveryUnknownOutcomePolicy } from './outbox-types.ts';
+/** Outbox defaults resolved once at construction. */
+export type ResolvedOutboxPolicy = Readonly<{
+    namespace: string;
+    ownerId: string;
+    maxBacklog: number;
+    visibilityTimeoutMs: number;
+    attemptTimeoutMs: number;
+    maxAttempts: number;
+    retryBackoffMs: number;
+    maxRetryBackoffMs: number;
+    terminalRetentionMs: number;
+    maxInlinePayloadBytes: number;
+    maintenanceBatchSize: number;
+    unknownOutcomePolicy: ApplicationDeliveryUnknownOutcomePolicy;
+    backgroundTasks: 'automatic' | 'manual';
+    maintenanceIntervalMs: number;
+}>;
+/**
+ * Resolve and range-check the outbox construction options.
+ *
+ * `attemptTimeoutMs` and `maintenanceIntervalMs` are each scheduled as one
+ * timer, so they are bounded by the largest delay a timer honours rather than
+ * by the general duration ceiling: a larger value would be clamped to a tick by
+ * the runtime, and every attempt would abort at once.
+ *
+ * @throws {ApplicationDeliveryValidationError} When any option is out of range.
+ */
+export declare function resolveOutboxPolicy(options: OutboxOptions): ResolvedOutboxPolicy;
+/** A validated delivery input with its digest and effective per-delivery policy resolved. */
+export type ValidatedDeliveryInput = Readonly<{
+    destinationRef: string;
+    credentialRef?: string | undefined;
+    kind: string;
+    payload: ApplicationDeliveryPayload;
+    payloadDigest: string;
+    payloadMediaType?: string | undefined;
+    payloadSchema?: string | undefined;
+    idempotencyKey?: string | undefined;
+    externalIdempotencyKey?: string | undefined;
+    unknownOutcomePolicy: ApplicationDeliveryUnknownOutcomePolicy;
+    causation?: ApplicationDeliveryInput['causation'] | undefined;
+    availableAfterMs: number;
+    maxAttempts: number;
+    visibilityTimeoutMs: number;
+    attemptTimeoutMs: number;
+}>;
+/**
+ * Validate one delivery offered for enqueue and resolve its effective policy.
+ *
+ * The unknown-outcome policy and the external idempotency evidence are
+ * validated together here, so a record with `retry-with-idempotency` and no
+ * `externalIdempotencyKey` can never exist: recovery never has to decide what
+ * to do with a retry it cannot make safely.
+ *
+ * @throws {ApplicationDeliveryValidationError} When any field is missing,
+ * oversized, out of range, or the policy lacks its evidence.
+ */
+export declare function validateDeliveryInput(input: ApplicationDeliveryInput, policy: ResolvedOutboxPolicy): Promise<ValidatedDeliveryInput>;
+/** A transport outcome with every caller-supplied field validated and snapshotted. */
+export type ValidatedOutcome = {
+    readonly status: 'acknowledged';
+    readonly evidence: JSONValue | undefined;
+} | {
+    readonly status: 'retryable';
+    readonly failure: ApplicationDeliveryFailure;
+    readonly retryAfterMs: number | undefined;
+} | {
+    readonly status: 'rejected';
+    readonly failure: ApplicationDeliveryFailure;
+} | {
+    readonly status: 'unknown';
+    readonly failure: {
+        readonly reason: 'unknown-outcome';
+        readonly message?: string | undefined;
+    };
+};
+/**
+ * Validate what a transport reported before it becomes durable evidence.
+ *
+ * A malformed outcome — not an object, an unknown status, `NaN` for
+ * `retryAfterMs`, a `Map` as evidence — is not a caller mistake the outbox can
+ * refuse: the send may already have happened. It is therefore mapped to
+ * `unknown` with a diagnostic message, so the delivery follows the unknown-
+ * outcome policy instead of being retried on the strength of nothing.
+ */
+export declare function validateOutcome(outcome: unknown): ValidatedOutcome;

package/dist/core/outbox-validation.js

@@ -0,0 +1,127 @@
+import { createPayloadValidators } from "./application-primitive-payload.js";
+import {
+  ApplicationDeliveryValidationError,
+  MAX_APPLICATION_DELIVERY_ATTEMPTS,
+  MAX_APPLICATION_DELIVERY_IDEMPOTENCY_KEY_BYTES,
+  MAX_APPLICATION_IDENTITY_BYTES,
+  MAX_DELIVERY_FAILURE_MESSAGE_BYTES,
+  MAX_OUTBOX_BACKLOG,
+  MAX_TIMER_DELAY_MS,
+  optionalIdentityOf,
+  requireIdentity,
+  requireNonNegativeInteger,
+  requirePositiveInteger,
+  validateDurableJSONValue,
+  validateFailureEvidence
+} from "./outbox-guards.js";
+const { validatePayload, validateCausation } = createPayloadValidators(ApplicationDeliveryValidationError), UNKNOWN_OUTCOME_POLICIES = new Set([
+  "park",
+  "dead-letter",
+  "retry-with-idempotency"
+]), ONE_DAY_MS = 86400000, MAX_DURATION_MS = 31536000000;
+function requirePolicy(value, field) {
+  if (typeof value !== "string" || !UNKNOWN_OUTCOME_POLICIES.has(value))
+    throw new ApplicationDeliveryValidationError(`${field} must be one of ${[...UNKNOWN_OUTCOME_POLICIES].join(", ")}.`);
+  return value;
+}
+export function resolveOutboxPolicy(options) {
+  const backgroundTasks = options.backgroundTasks ?? "manual";
+  if (backgroundTasks !== "manual" && backgroundTasks !== "automatic")
+    throw new ApplicationDeliveryValidationError("backgroundTasks must be 'manual' or 'automatic'.");
+  return {
+    namespace: requireIdentity(options.namespace, "namespace", MAX_APPLICATION_IDENTITY_BYTES),
+    ownerId: requireIdentity(options.ownerId, "ownerId", MAX_APPLICATION_IDENTITY_BYTES),
+    ...resolveBounds(options),
+    unknownOutcomePolicy: requirePolicy(options.unknownOutcomePolicy ?? "park", "unknownOutcomePolicy"),
+    backgroundTasks
+  };
+}
+function positive(value, fallback, field, maximum) {
+  return requirePositiveInteger(value ?? fallback, field, maximum);
+}
+function resolveBounds(options) {
+  return {
+    maxBacklog: positive(options.maxBacklog, 1000, "maxBacklog", MAX_OUTBOX_BACKLOG),
+    visibilityTimeoutMs: positive(options.visibilityTimeoutMs, 30000, "visibilityTimeoutMs", MAX_DURATION_MS),
+    attemptTimeoutMs: positive(options.attemptTimeoutMs, 300000, "attemptTimeoutMs", MAX_TIMER_DELAY_MS),
+    maxAttempts: positive(options.maxAttempts, 3, "maxAttempts", MAX_APPLICATION_DELIVERY_ATTEMPTS),
+    retryBackoffMs: positive(options.retryBackoffMs, 1000, "retryBackoffMs", MAX_DURATION_MS),
+    maxRetryBackoffMs: positive(options.maxRetryBackoffMs, 60000, "maxRetryBackoffMs", MAX_DURATION_MS),
+    terminalRetentionMs: positive(options.terminalRetentionMs, ONE_DAY_MS, "terminalRetentionMs", MAX_DURATION_MS),
+    maxInlinePayloadBytes: positive(options.maxInlinePayloadBytes, 262144, "maxInlinePayloadBytes", 67108864),
+    maintenanceBatchSize: positive(options.maintenanceBatchSize, 500, "maintenanceBatchSize", 1e4),
+    maintenanceIntervalMs: positive(options.maintenanceIntervalMs, 1000, "maintenanceIntervalMs", MAX_TIMER_DELAY_MS)
+  };
+}
+export async function validateDeliveryInput(input, policy) {
+  if (typeof input !== "object" || input === null)
+    throw new ApplicationDeliveryValidationError("delivery must be an object.");
+  const { payload, digest } = await validatePayload(input.payload, policy.maxInlinePayloadBytes), unknownOutcomePolicy = requirePolicy(input.unknownOutcomePolicy ?? policy.unknownOutcomePolicy, "unknownOutcomePolicy"), externalIdempotencyKey = optionalIdentityOf(input.externalIdempotencyKey, "externalIdempotencyKey", MAX_APPLICATION_DELIVERY_IDEMPOTENCY_KEY_BYTES);
+  if (unknownOutcomePolicy === "retry-with-idempotency" && externalIdempotencyKey === void 0)
+    throw new ApplicationDeliveryValidationError("unknownOutcomePolicy 'retry-with-idempotency' requires externalIdempotencyKey: without stable external idempotency evidence a retry after an unknown outcome could duplicate the effect.");
+  return {
+    destinationRef: requireIdentity(input.destinationRef, "destinationRef", MAX_APPLICATION_IDENTITY_BYTES),
+    credentialRef: optionalIdentityOf(input.credentialRef, "credentialRef", MAX_APPLICATION_IDENTITY_BYTES),
+    kind: requireIdentity(input.kind, "kind", MAX_APPLICATION_IDENTITY_BYTES),
+    payload,
+    payloadDigest: digest,
+    payloadMediaType: optionalIdentityOf(input.payloadMediaType, "payloadMediaType", MAX_APPLICATION_IDENTITY_BYTES),
+    payloadSchema: optionalIdentityOf(input.payloadSchema, "payloadSchema", MAX_APPLICATION_IDENTITY_BYTES),
+    idempotencyKey: optionalIdentityOf(input.idempotencyKey, "idempotencyKey", MAX_APPLICATION_DELIVERY_IDEMPOTENCY_KEY_BYTES),
+    externalIdempotencyKey,
+    unknownOutcomePolicy,
+    causation: validateCausation(input.causation),
+    availableAfterMs: requireNonNegativeInteger(input.availableAfterMs ?? 0, "availableAfterMs", MAX_DURATION_MS),
+    maxAttempts: requirePositiveInteger(input.maxAttempts ?? policy.maxAttempts, "maxAttempts", MAX_APPLICATION_DELIVERY_ATTEMPTS),
+    visibilityTimeoutMs: requirePositiveInteger(input.visibilityTimeoutMs ?? policy.visibilityTimeoutMs, "visibilityTimeoutMs", MAX_DURATION_MS),
+    attemptTimeoutMs: requirePositiveInteger(input.attemptTimeoutMs ?? policy.attemptTimeoutMs, "attemptTimeoutMs", MAX_TIMER_DELAY_MS)
+  };
+}
+export function validateOutcome(outcome) {
+  try {
+    return readOutcome(outcome);
+  } catch (error) {
+    if (error instanceof ApplicationDeliveryValidationError)
+      return {
+        status: "unknown",
+        failure: {
+          reason: "unknown-outcome",
+          message: `The transport adapter returned a malformed outcome: ${error.message}`
+        }
+      };
+    throw error;
+  }
+}
+function readOutcome(outcome) {
+  if (typeof outcome !== "object" || outcome === null || !("status" in outcome))
+    throw new ApplicationDeliveryValidationError("outcome must be an object with a status.");
+  const candidate = outcome;
+  switch (candidate.status) {
+    case "acknowledged":
+      return {
+        status: "acknowledged",
+        evidence: validateDurableJSONValue(candidate.evidence, "evidence")
+      };
+    case "retryable":
+      return {
+        status: "retryable",
+        failure: validateFailureEvidence("retryable", candidate.message, candidate.details),
+        retryAfterMs: candidate.retryAfterMs === void 0 ? void 0 : requireNonNegativeInteger(candidate.retryAfterMs, "retryAfterMs", MAX_DURATION_MS)
+      };
+    case "rejected":
+      return {
+        status: "rejected",
+        failure: validateFailureEvidence("application", candidate.message, candidate.details)
+      };
+    case "unknown":
+      return {
+        status: "unknown",
+        failure: {
+          reason: "unknown-outcome",
+          message: optionalIdentityOf(candidate.message, "message", MAX_DELIVERY_FAILURE_MESSAGE_BYTES)
+        }
+      };
+    default:
+      throw new ApplicationDeliveryValidationError("outcome.status must be 'acknowledged', 'retryable', 'rejected', or 'unknown'.");
+  }
+}

package/dist/core/outbox-waits.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The abortable, bounded waits the application delivery outbox exposes
+ * (WFT-85): waiting for due work, and waiting for a cancelled delivery's
+ * attempt to settle.
+ *
+ * Both are polling waits, for the same reason the mailbox's are: another
+ * process's enqueue is visible only in durable storage. Every wait is bounded
+ * by a caller-supplied deadline, respects a caller-supplied `AbortSignal`, and
+ * unwinds cleanly on disposal. Waiting never claims, starts, or advances work.
+ *
+ * @module core/outbox-waits
+ */
+import { delayUnlessAborted } from './application-primitive-timing.ts';
+import type { ApplicationDeliveryCleanupResult, OutboxWaitOptions } from './outbox-contract.ts';
+import type { OutboxRuntime } from './outbox-internals.ts';
+export { delayUnlessAborted };
+/**
+ * Whether a delivery is claimable right now: the earliest genuine due entry
+ * is at or before the clock. Orphaned entries are looked past, bounded, since
+ * a wait mutates nothing and cannot make progress through them.
+ */
+export declare function hasDueWork(runtime: OutboxRuntime): Promise<boolean>;
+/**
+ * Wait, bounded and abortably, until this outbox has a delivery due.
+ * Returns `true` when one is claimable and `false` when the wait was aborted,
+ * the outbox disposed, or the timeout elapsed first.
+ */
+export declare function waitForDueWork(runtime: OutboxRuntime, options?: OutboxWaitOptions): Promise<boolean>;
+/**
+ * Wait, bounded, for a cancelled delivery's attempt to settle. A `pending`
+ * result means this outbox stopped waiting, never that the transport stopped.
+ * The semantics match the mailbox's `awaitCleanup`.
+ */
+export declare function waitForCleanup(runtime: OutboxRuntime, options: {
+    readonly deliveryId: string;
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal | undefined;
+    readonly pollIntervalMs?: number | undefined;
+}): Promise<ApplicationDeliveryCleanupResult>;

package/dist/core/outbox-waits.js

@@ -0,0 +1,88 @@
+import { WaitBudgetElapsedError, raceAbortWithin } from "./application-primitive-abort.js";
+import { delayUnlessAborted } from "./application-primitive-timing.js";
+import { DUE_HEAD_LOOKAHEAD } from "./outbox-delivery.js";
+import { requireClockInstant, requireDerivedInstant, requireWaitBudget } from "./outbox-guards.js";
+import { readCleanupState } from "./outbox-settlement.js";
+import { loadDelivery, loadDueHead } from "./outbox-storage.js";
+import { isApplicationDeliveryWaiting } from "./outbox-types.js";
+
+export { delayUnlessAborted };
+export async function hasDueWork(runtime) {
+  const entries = await loadDueHead(runtime.storage, runtime.keys, DUE_HEAD_LOOKAHEAD);
+  for (const entry of entries) {
+    const loaded = await loadDelivery(runtime.storage, runtime.keys, entry.deliveryId);
+    if (loaded === null || !isApplicationDeliveryWaiting(loaded.record))
+      continue;
+    if (entry.key !== runtime.keys.due(loaded.record.availableAt, loaded.record.deliveryId))
+      continue;
+    return runtime.now() >= loaded.record.availableAt;
+  }
+  return !1;
+}
+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 isAborted(disposal, signal) {
+  return disposal.aborted || signal?.aborted === !0;
+}
+export async function waitForDueWork(runtime, options) {
+  const { timeoutMs, pollIntervalMs } = requireWaitBudget(options ?? {}), deadline = requireDerivedInstant(requireClockInstant(runtime.now()) + timeoutMs, "deadline"), disposal = runtime.disposal;
+  let remaining = 0;
+  do {
+    const observed = await observeDueWork(runtime, options?.signal, timeoutMs, deadline);
+    if (observed === null)
+      return !1;
+    if (observed)
+      return timeoutMs === 0 || runtime.now() <= deadline;
+    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, signal, timeoutMs, deadline) {
+  if (budgetSpent(timeoutMs, deadline, runtime.now()))
+    return null;
+  const observed = await raceAbortWithin(() => hasDueWork(runtime), budgetFor(timeoutMs, deadline, runtime.now()), runtime.disposal, signal);
+  if (observed.aborted || isAborted(runtime.disposal, signal))
+    return null;
+  return observed.value;
+}
+export async function waitForCleanup(runtime, options) {
+  const { timeoutMs, pollIntervalMs } = requireWaitBudget(options), deadline = requireDerivedInstant(requireClockInstant(runtime.now()) + timeoutMs, "deadline"), disposal = runtime.disposal, first = await readUnlessAborted(runtime, options.deliveryId, 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.deliveryId, options.signal, budgetFor(timeoutMs, deadline, runtime.now()));
+    if (next === null)
+      break;
+    latest = next;
+  }
+  return latest;
+}
+async function readUnlessAborted(runtime, deliveryId, signal, budgetMs) {
+  const raced = await raceAbortWithin(() => readCleanupState(runtime, deliveryId), budgetMs, runtime.disposal, signal);
+  if (!raced.aborted)
+    return raced.value;
+  if (raced.reason instanceof WaitBudgetElapsedError)
+    return null;
+  throw raced.reason;
+}

package/dist/core/outbox.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The durable application delivery outbox (WFT-85).
+ *
+ * An outbox is a storage-backed, at-least-once delivery queue scoped to one
+ * opaque `(namespace, ownerId)` pair. Enqueue returns a durable receipt before
+ * any transport attempt begins; attempts are fenced so two workers can never
+ * both hold a valid claim; the send is durably marked `attempting` before the
+ * transport is called, so a lost result is never mistaken for a safe retry;
+ * cancellation is durable before it reaches anyone; and every transition
+ * commits atomically with its fleet event when an event sink is configured.
+ *
+ * What it does not do: manufacture exactly-once external effects. A transport
+ * write completing is evidence the adapter reports; only the durable
+ * disposition the outbox commits on it moves a delivery. An unknown outcome is
+ * retried only when the delivery carries external idempotency evidence and its
+ * policy allows it; otherwise it is parked or dead-lettered, never duplicated.
+ *
+ * @module core/outbox
+ */
+import type { Storage } from '../storage/interface.ts';
+import type { JSONValue } from './json.ts';
+import type { ApplicationDeliveryAdmission, ApplicationDeliveryCancellationResult, ApplicationDeliveryCleanupResult, ApplicationDeliveryHeartbeatResult, ApplicationDeliveryInput, ApplicationDeliveryOperatorResult, ApplicationDeliveryOutcome, ApplicationDeliveryReceipt, ApplicationDeliverySettleResult, OutboxCapacity, OutboxClaimResult, OutboxDeliverResult, OutboxDrainReport, OutboxListOptions, OutboxMaintenanceReport, OutboxOptions, OutboxWaitOptions } from './outbox-contract.ts';
+/**
+ * A durable, at-least-once application delivery outbox.
+ *
+ * @example
+ * ```ts
+ * import { Outbox, MemoryStorage } from '@lostgradient/weft';
+ *
+ * await using storage = new MemoryStorage();
+ * using outbox = new Outbox({
+ *   storage,
+ *   namespace: 'bureau',
+ *   ownerId: 'agent-7',
+ *   adapter: { async send() { return { status: 'acknowledged' }; } },
+ * });
+ *
+ * const admission = await outbox.enqueue({
+ *   destinationRef: 'webhook:orders',
+ *   kind: 'order.shipped',
+ *   payload: { form: 'inline', value: { orderId: 42 } },
+ *   idempotencyKey: 'order-42-shipped',
+ * });
+ * console.log(admission.status); // 'enqueued'
+ *
+ * const delivered = await outbox.deliverNext();
+ * console.log(delivered.status === 'settled' && delivered.receipt.state); // 'acknowledged'
+ * ```
+ */
+export declare class Outbox {
+    #private;
+    constructor(options: OutboxOptions);
+    /** The opaque application namespace this outbox is scoped to. */
+    get namespace(): string;
+    /** The opaque owner identifier this outbox is scoped to. */
+    get ownerId(): string;
+    /** The durable backend every transition compares and swaps against. */
+    get storage(): Storage;
+    /**
+     * Offer a delivery. An exact retry of the same idempotency identity returns
+     * the original receipt; a reused key with a different destination, kind, or
+     * payload returns a conflict; a full backlog is rejected before any write.
+     */
+    enqueue(delivery: ApplicationDeliveryInput): Promise<ApplicationDeliveryAdmission>;
+    /** Read one delivery's immutable receipt, or `null` when it is unknown or retired. */
+    receipt(deliveryId: string): Promise<ApplicationDeliveryReceipt | null>;
+    /** List receipts in enqueue order, bounded and non-consuming. */
+    list(options?: OutboxListOptions): Promise<ApplicationDeliveryReceipt[]>;
+    /** Current backlog accounting. Counts only. */
+    capacity(): Promise<OutboxCapacity>;
+    /**
+     * Lease the earliest due delivery to one attempt, for a host that drives the
+     * transport itself. Call `beginAttempt()` before sending and `settle()`
+     * after; heartbeat in between.
+     */
+    claim(options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<OutboxClaimResult>;
+    /** Durably mark the current attempt as about to call the transport. */
+    beginAttempt(options: {
+        readonly deliveryId: string;
+        readonly attemptToken: string;
+    }): Promise<ApplicationDeliverySettleResult>;
+    /** Record liveness and extend visibility, clamped to the fixed attempt deadline. */
+    heartbeat(options: {
+        readonly deliveryId: string;
+        readonly attemptToken: string;
+        readonly transportActivity?: JSONValue | undefined;
+    }): Promise<ApplicationDeliveryHeartbeatResult>;
+    /**
+     * Settle the current attempt on what the transport reported. A malformed
+     * outcome is treated as `unknown`, never as a retry.
+     */
+    settle(options: {
+        readonly deliveryId: string;
+        readonly attemptToken: string;
+        readonly outcome: ApplicationDeliveryOutcome;
+    }): Promise<ApplicationDeliverySettleResult>;
+    /** Claim, begin, send through the configured adapter, and settle one delivery. */
+    deliverNext(options?: {
+        readonly signal?: AbortSignal | undefined;
+    }): Promise<OutboxDeliverResult>;
+    /**
+     * Deliver everything due within a bounded budget, running maintenance
+     * between rounds. Reports counts only; `pending` is what the durable header
+     * still holds open when the drain stops.
+     */
+    drain(options: {
+        readonly timeoutMs: number;
+        readonly signal?: AbortSignal | undefined;
+        readonly pollIntervalMs?: number | undefined;
+    }): Promise<OutboxDrainReport>;
+    /** Durably request cancellation and abort an in-process attempt. */
+    requestCancellation(options: {
+        readonly deliveryId: string;
+        readonly reason?: string | undefined;
+    }): Promise<ApplicationDeliveryCancellationResult>;
+    /** Read whether a cancelled delivery's attempt has finished. Non-consuming. */
+    cleanupState(deliveryId: string): Promise<ApplicationDeliveryCleanupResult>;
+    /** Wait, bounded, for a cancelled delivery's attempt to settle. */
+    awaitCleanup(options: {
+        readonly deliveryId: string;
+        readonly timeoutMs: number;
+        readonly signal?: AbortSignal | undefined;
+        readonly pollIntervalMs?: number | undefined;
+    }): Promise<ApplicationDeliveryCleanupResult>;
+    /** Return a parked, dead-lettered, or rejected delivery to the queue with at least one more attempt: an unspent budget is kept, a spent one is raised by one. */
+    retry(options: {
+        readonly deliveryId: string;
+    }): Promise<ApplicationDeliveryOperatorResult>;
+    /** Close a parked `unknown-outcome` delivery as dead-lettered. */
+    deadLetter(options: {
+        readonly deliveryId: string;
+        readonly reason?: string | undefined;
+    }): Promise<ApplicationDeliveryOperatorResult>;
+    /**
+     * Wait, bounded and abortably, until a delivery is due. `timeoutMs` defaults
+     * to `0`: one check, no wait.
+     */
+    waitForDue(options?: OutboxWaitOptions): Promise<boolean>;
+    /**
+     * Run one bounded maintenance pass: recover lapsed leases and retire
+     * terminal receipts past retention. Under `backgroundTasks: 'manual'` this is
+     * the only thing that advances time-driven recovery.
+     */
+    runMaintenance(now?: number): Promise<OutboxMaintenanceReport>;
+    /**
+     * Release every process-local resource: the maintenance timer, in-flight
+     * waits, and every attempt-scoped signal this handle holds. Disposal never
+     * deletes durable work; a claim this process held stays leased until it
+     * lapses and maintenance recovers it.
+     */
+    dispose(): void;
+    /** `using`-compatible disposal. */
+    [Symbol.dispose](): void;
+}