@lostgradient/weft 0.23.0 → 0.24.0

package/dist/core/outbox-internals.js

@@ -0,0 +1,159 @@
+import {
+  commitOutboxTransition,
+  headerOperation,
+  loadOutboxHeader,
+  planDeliveryTransition
+} from "./outbox-storage.js";
+import { isTerminalDeliveryRecord } from "./outbox-transition-helpers.js";
+import { isApplicationDeliveryLeased } from "./outbox-types.js";
+import { WeftError } from "./weft-error.js";
+export const MAX_OUTBOX_TRANSITION_ATTEMPTS = 25, OUTBOX_MAINTENANCE_MAX_PAGES = 200, OUTBOX_PRIMITIVE = "outbox";
+
+export class OutboxContentionError extends WeftError {
+  operation;
+  deliveryId;
+  constructor(operation, deliveryId) {
+    super("OutboxContentionError", `Application outbox ${operation}${deliveryId === null ? "" : ` for delivery "${deliveryId}"`} lost its storage precondition after ${MAX_OUTBOX_TRANSITION_ATTEMPTS} attempts.`);
+    this.operation = operation;
+    this.deliveryId = deliveryId;
+  }
+}
+function receiptLeaseFields(record) {
+  if (!isApplicationDeliveryLeased(record))
+    return {};
+  return {
+    claimedAt: record.claimedAt,
+    visibilityExpiresAt: record.visibilityExpiresAt,
+    attemptDeadlineAt: record.attemptDeadlineAt,
+    lastActivityAt: record.lastActivityAt,
+    transportActivity: record.transportActivity,
+    ...record.state === "claimed" ? {} : { attemptStartedAt: record.attemptStartedAt },
+    ...record.state === "cancellation-requested" ? {
+      cancellationRequestedAt: record.cancellationRequestedAt,
+      cancellationReason: record.cancellationReason
+    } : {}
+  };
+}
+function receiptTerminalFields(record) {
+  if (record.state === "retry-scheduled")
+    return { lastFailure: record.lastFailure };
+  if (!isTerminalDeliveryRecord(record))
+    return {};
+  return {
+    cancellationRequestedAt: record.cancellationRequestedAt,
+    cancellationReason: record.cancellationReason,
+    terminalAt: record.terminalAt,
+    evidence: record.evidence,
+    failure: record.failure,
+    cleanupPending: record.cleanupPending
+  };
+}
+function deepFreeze(value) {
+  if (typeof value !== "object" || value === null || Object.isFrozen(value))
+    return value;
+  Object.freeze(value);
+  for (const nested of Object.values(value))
+    deepFreeze(nested);
+  return value;
+}
+export function toApplicationDeliveryReceipt(record) {
+  return deepFreeze({
+    deliveryId: record.deliveryId,
+    namespace: record.namespace,
+    ownerId: record.ownerId,
+    sequence: record.sequence,
+    state: record.state,
+    destinationRef: record.destinationRef,
+    kind: record.kind,
+    payloadDigest: record.payloadDigest,
+    payloadForm: record.payload.form,
+    payloadMediaType: record.payloadMediaType,
+    payloadSchema: record.payloadSchema,
+    idempotencyKey: record.idempotencyKey,
+    externalIdempotencyKey: record.externalIdempotencyKey,
+    unknownOutcomePolicy: record.unknownOutcomePolicy,
+    causation: record.causation,
+    enqueuedAt: record.enqueuedAt,
+    availableAt: record.availableAt,
+    attempt: record.attempt,
+    retryCount: record.retryCount,
+    maxAttempts: record.maxAttempts,
+    generation: record.generation,
+    ...receiptLeaseFields(record),
+    ...receiptTerminalFields(record)
+  });
+}
+const STATE_EVENT_KINDS = {
+  queued: "outbox:delivery-queued",
+  "retry-scheduled": "outbox:delivery-retry-scheduled",
+  claimed: "outbox:delivery-claimed",
+  attempting: "outbox:delivery-attempting",
+  "cancellation-requested": "outbox:delivery-cancellation-requested",
+  acknowledged: "outbox:delivery-acknowledged",
+  rejected: "outbox:delivery-rejected",
+  cancelled: "outbox:delivery-cancelled",
+  "unknown-outcome": "outbox:delivery-unknown-outcome",
+  "dead-lettered": "outbox:delivery-dead-lettered"
+};
+export function describeDeliveryTransition(previous, next) {
+  return {
+    kind: previous !== null && isTerminalDeliveryRecord(previous) && next.state === "queued" ? "outbox:delivery-retried" : STATE_EVENT_KINDS[next.state],
+    payload: {
+      namespace: next.namespace,
+      ownerId: next.ownerId,
+      deliveryId: next.deliveryId,
+      sequence: next.sequence,
+      state: next.state,
+      deliveryKind: next.kind,
+      attempt: next.attempt,
+      retryCount: next.retryCount,
+      generation: next.generation,
+      previousState: previous === null ? null : previous.state
+    }
+  };
+}
+export function releaseAttemptController(runtime, attemptToken, reason, deliveryId) {
+  const registration = runtime.attemptControllers.get(attemptToken);
+  if (registration === void 0)
+    return;
+  if (deliveryId !== void 0 && registration.subjectId !== deliveryId)
+    return;
+  runtime.attemptControllers.delete(attemptToken);
+  registration.release();
+  if (!registration.controller.signal.aborted)
+    registration.controller.abort(Error(reason));
+}
+export function releaseAttemptsForDelivery(runtime, deliveryId, reason, currentToken, observedAt) {
+  for (const attemptToken of runtime.attemptControllers.tokensFor(deliveryId)) {
+    const registration = runtime.attemptControllers.get(attemptToken);
+    if (registration === void 0 || attemptToken === currentToken)
+      continue;
+    if (registration.committedSerial === null)
+      continue;
+    if (observedAt !== void 0 && registration.committedSerial > observedAt)
+      continue;
+    releaseAttemptController(runtime, attemptToken, reason);
+  }
+}
+export async function commitDeliveryTransition(runtime, options) {
+  const previousTerminal = options.previous !== null && isTerminalDeliveryRecord(options.previous), nextTerminal = isTerminalDeliveryRecord(options.next), delta = options.previous === null ? 0 : Number(previousTerminal) - Number(nextTerminal), extraConditions = [...options.extraConditions ?? []], extraOperations = [...options.extraOperations ?? []];
+  if (delta !== 0) {
+    const header = options.header ?? await loadOutboxHeader(runtime.storage, runtime.keys, runtime.policy.namespace, runtime.policy.ownerId);
+    if (runtime.disposal.aborted)
+      return !1;
+    extraConditions.push({ key: runtime.keys.header, expectedValue: header.bytes });
+    extraOperations.push(headerOperation(runtime.keys, {
+      ...header.record,
+      openCount: Math.max(0, header.record.openCount + delta)
+    }));
+  }
+  return commitOutboxTransition(runtime.storage, runtime.events, planDeliveryTransition(runtime.keys, {
+    previous: options.previous,
+    expectedBytes: options.expectedBytes,
+    next: options.next,
+    event: describeDeliveryTransition(options.previous, options.next),
+    now: options.now,
+    extraConditions,
+    extraOperations
+  }));
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Bounded, non-consuming listing for the application delivery outbox
+ * (WFT-85): walking the sequence-ordered index rather than the delivery
+ * records, so `limit` bounds the storage reads and not only the returned
+ * slice.
+ *
+ * @module core/outbox-listing
+ */
+import type { ApplicationDeliveryReceipt, OutboxListOptions } from './outbox-contract.ts';
+import { type OutboxRuntime } from './outbox-internals.ts';
+/** List receipts in enqueue order, bounded by `limit` and the scan ceiling. */
+export declare function listDeliveries(runtime: OutboxRuntime, options: OutboxListOptions | undefined): Promise<ApplicationDeliveryReceipt[]>;

package/dist/core/outbox-listing.js

@@ -0,0 +1,38 @@
+import { clampListLimit } from "./outbox-guards.js";
+import { decodeApplicationDeliveryEntry } from "./outbox-index-codec.js";
+import { toApplicationDeliveryReceipt } from "./outbox-internals.js";
+import { loadDelivery } from "./outbox-storage.js";
+import { PersistedDataCorruptError } from "./persisted-data-incompatible-error.js";
+const OUTBOX_LIST_PAGE_SIZE = 200, OUTBOX_LIST_SCAN_CEILING = 5000;
+export async function listDeliveries(runtime, options) {
+  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 < OUTBOX_LIST_SCAN_CEILING) {
+    const page = await readListingPage(runtime, cursor, limit - receipts.length, states);
+    receipts.push(...page.receipts);
+    examined += page.examined;
+    cursor = page.cursor;
+    if (page.exhausted)
+      break;
+  }
+  return receipts;
+}
+async function readListingPage(runtime, cursor, remaining, states) {
+  const receipts = [], scanOptions = cursor === void 0 ? { limit: OUTBOX_LIST_PAGE_SIZE } : { limit: OUTBOX_LIST_PAGE_SIZE, gt: cursor };
+  let seen = 0, nextCursor = cursor;
+  for await (const [indexKey, indexValue] of runtime.storage.scan(runtime.keys.bySequencePrefix, scanOptions)) {
+    seen += 1;
+    nextCursor = indexKey;
+    const deliveryId = decodeApplicationDeliveryEntry(indexValue, indexKey), loaded = await loadDelivery(runtime.storage, runtime.keys, deliveryId);
+    if (loaded === null)
+      continue;
+    if (indexKey !== runtime.keys.bySequence(loaded.record.sequence))
+      throw new PersistedDataCorruptError(indexKey);
+    if (states !== null && !states.has(loaded.record.state))
+      continue;
+    receipts.push(toApplicationDeliveryReceipt(loaded.record));
+    if (receipts.length >= remaining)
+      break;
+  }
+  return { receipts, cursor: nextCursor, exhausted: seen < OUTBOX_LIST_PAGE_SIZE, examined: seen };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * The bounded maintenance pass for the application delivery outbox (WFT-85):
+ * recovering lapsed leases and retiring terminal receipts past retention.
+ *
+ * Nothing here runs on a hidden timer under `backgroundTasks: 'manual'`. A
+ * pass walks the delivery keyspace in pages of `maintenanceBatchSize`, up to
+ * {@link OUTBOX_MAINTENANCE_MAX_PAGES} pages per call, carrying its cursor to
+ * the next call when the cap cuts it short.
+ *
+ * Unlike the mailbox, the outbox has no `accepted → available` release step:
+ * the due index is time-keyed, so a delivery becomes claimable by the clock
+ * alone, without a maintenance write.
+ *
+ * @module core/outbox-maintenance
+ */
+import type { OutboxMaintenanceReport } from './outbox-contract.ts';
+import { type OutboxRuntime } from './outbox-internals.ts';
+/** The time-keyed indexes encode `…:<16-digit instant>:<encoded deliveryId>`. */
+export declare function parseSortableInstant(key: string, prefix: string): number | null;
+/**
+ * Run one bounded maintenance pass: recover lapsed leases and retire terminal
+ * receipts past retention.
+ *
+ * A corrupt record halts the pass with `PersistedDataCorruptError`: an outbox
+ * whose durable state is untrustworthy must not keep recovering and parking
+ * deliveries around the damage.
+ */
+export declare function runOutboxMaintenance(runtime: OutboxRuntime, now: number, stop?: AbortSignal): Promise<OutboxMaintenanceReport>;

package/dist/core/outbox-maintenance.js

@@ -0,0 +1,191 @@
+import { formatSortableStorageTimestamp, storageConditionalBatch } from "../storage/interface.js";
+import { leaseCommitSerial } from "./application-primitive-attempt-registry.js";
+import { decodeApplicationDeliveryRecord } from "./outbox-codec.js";
+import {
+  decodeApplicationDeliveryEntry,
+  decodeApplicationDeliveryIdempotencyRecord
+} from "./outbox-index-codec.js";
+import {
+  commitDeliveryTransition,
+  MAX_OUTBOX_TRANSITION_ATTEMPTS,
+  OUTBOX_MAINTENANCE_MAX_PAGES,
+  OutboxContentionError,
+  releaseAttemptController,
+  releaseAttemptsForDelivery
+} from "./outbox-internals.js";
+import { loadDelivery } from "./outbox-storage.js";
+import { isTerminalDeliveryRecord } from "./outbox-transition-helpers.js";
+import { isDeliveryLeaseExpired, recoverExpiredDelivery } from "./outbox-transitions-recovery.js";
+import { isApplicationDeliveryLeased } from "./outbox-types.js";
+function halted(runtime, stop) {
+  return runtime.disposal.aborted || stop?.aborted === !0;
+}
+function countTransition(counters, next) {
+  if (next.state === "retry-scheduled")
+    counters.rescheduled += 1;
+  else if (next.state === "unknown-outcome")
+    counters.parked += 1;
+  else if (next.state === "dead-lettered")
+    counters.deadLettered += 1;
+}
+function reconcileLocalAttempts(runtime, deliveryId, record, observedAt) {
+  releaseAttemptsForDelivery(runtime, deliveryId, "This attempt is no longer the current lease on its delivery.", record !== void 0 && isApplicationDeliveryLeased(record) ? record.attemptToken : void 0, observedAt);
+}
+async function recoverDelivery(runtime, deliveryId, now, counters, stop) {
+  for (let attempt = 1;attempt <= MAX_OUTBOX_TRANSITION_ATTEMPTS; attempt += 1) {
+    if (halted(runtime, stop))
+      return;
+    const observedAt = leaseCommitSerial(), loaded = await loadDelivery(runtime.storage, runtime.keys, deliveryId);
+    if (loaded === null) {
+      reconcileLocalAttempts(runtime, deliveryId, void 0, observedAt);
+      return;
+    }
+    if (halted(runtime, stop))
+      return;
+    if (!isDeliveryLeaseExpired(loaded.record, now)) {
+      reconcileLocalAttempts(runtime, deliveryId, loaded.record, observedAt);
+      return;
+    }
+    const transition = recoverExpiredDelivery(loaded.record, {
+      now,
+      retryBackoffMs: runtime.policy.retryBackoffMs,
+      maxRetryBackoffMs: runtime.policy.maxRetryBackoffMs
+    });
+    if (!transition.ok)
+      return;
+    if (!await commitDeliveryTransition(runtime, {
+      previous: loaded.record,
+      expectedBytes: loaded.bytes,
+      next: transition.next,
+      now
+    }))
+      continue;
+    if (isApplicationDeliveryLeased(loaded.record))
+      releaseAttemptController(runtime, loaded.record.attemptToken, "The application outbox recovered this attempt after its lease lapsed.");
+    countTransition(counters, transition.next);
+    return;
+  }
+  throw new OutboxContentionError("maintenance", deliveryId);
+}
+async function retireOneReceipt(runtime, indexKey, indexBytes) {
+  const deliveryId = deliveryIdFromTerminalKey(indexKey), observedAt = leaseCommitSerial(), loaded = deliveryId === null ? null : await loadDelivery(runtime.storage, runtime.keys, deliveryId);
+  if (deliveryId === null || loaded !== null && !ownsTerminalEntry(runtime, indexKey, loaded)) {
+    await discardTerminalEntry(runtime, indexKey, indexBytes);
+    return !1;
+  }
+  const operations = [{ type: "delete", key: indexKey }];
+  if (loaded === null)
+    return storageConditionalBatch(runtime.storage, [{ key: indexKey, expectedValue: indexBytes }], operations);
+  operations.push({ type: "delete", key: runtime.keys.delivery(deliveryId) });
+  const auxiliary = await ownedAuxiliaryEntries(runtime, loaded);
+  operations.push(...auxiliary.operations);
+  const retired = await storageConditionalBatch(runtime.storage, [
+    { key: runtime.keys.delivery(deliveryId), expectedValue: loaded.bytes },
+    ...auxiliary.conditions
+  ], operations);
+  if (retired)
+    releaseAttemptsForDelivery(runtime, deliveryId, "This delivery was retired; its attempt is over.", void 0, observedAt);
+  return retired;
+}
+async function ownedAuxiliaryEntries(runtime, loaded) {
+  const conditions = [], operations = [], sequenceKey = runtime.keys.bySequence(loaded.record.sequence), sequenceBytes = await runtime.storage.get(sequenceKey);
+  if (sequenceBytes !== null && decodeApplicationDeliveryEntry(sequenceBytes, sequenceKey) === loaded.record.deliveryId) {
+    conditions.push({ key: sequenceKey, expectedValue: sequenceBytes });
+    operations.push({ type: "delete", key: sequenceKey });
+  }
+  if (loaded.record.idempotencyKey === void 0)
+    return { conditions, operations };
+  const bindingKey = runtime.keys.idempotency(loaded.record.idempotencyKey), bindingBytes = await runtime.storage.get(bindingKey);
+  if (bindingBytes !== null && decodeApplicationDeliveryIdempotencyRecord(bindingBytes, bindingKey).deliveryId === loaded.record.deliveryId) {
+    conditions.push({ key: bindingKey, expectedValue: bindingBytes });
+    operations.push({ type: "delete", key: bindingKey });
+  }
+  return { conditions, operations };
+}
+function ownsTerminalEntry(runtime, indexKey, loaded) {
+  return isTerminalDeliveryRecord(loaded.record) && runtime.keys.terminal(loaded.record.terminalAt, loaded.record.deliveryId) === indexKey;
+}
+async function discardTerminalEntry(runtime, indexKey, indexBytes) {
+  await storageConditionalBatch(runtime.storage, [{ key: indexKey, expectedValue: indexBytes }], [{ type: "delete", key: indexKey }]);
+}
+async function retireTerminalReceipts(runtime, now, counters, stop) {
+  const horizon = now - runtime.policy.terminalRetentionMs;
+  if (horizon < 0)
+    return;
+  const expired = [], malformed = [];
+  for await (const [key, value] of runtime.storage.scan(runtime.keys.terminalPrefix, {
+    limit: runtime.policy.maintenanceBatchSize
+  })) {
+    const terminalAt = parseSortableInstant(key, runtime.keys.terminalPrefix);
+    if (terminalAt === null) {
+      malformed.push([key, value]);
+      continue;
+    }
+    if (terminalAt >= horizon)
+      break;
+    expired.push([key, value]);
+  }
+  for (const [indexKey, bytes] of malformed) {
+    if (halted(runtime, stop))
+      return;
+    await discardTerminalEntry(runtime, indexKey, bytes);
+  }
+  for (const [indexKey, bytes] of expired) {
+    if (halted(runtime, stop))
+      return;
+    if (await retireOneReceipt(runtime, indexKey, bytes))
+      counters.retired += 1;
+  }
+}
+export function parseSortableInstant(key, prefix) {
+  const suffix = key.slice(prefix.length), separator = suffix.indexOf(":");
+  if (separator === -1)
+    return null;
+  const segment = suffix.slice(0, separator), parsed = Number(segment);
+  return Number.isSafeInteger(parsed) && formatSortableStorageTimestamp(parsed) === segment ? parsed : null;
+}
+function deliveryIdFromTerminalKey(key) {
+  try {
+    return decodeURIComponent(key.slice(key.lastIndexOf(":") + 1));
+  } catch {
+    return null;
+  }
+}
+async function collectLapsedDeliveries(runtime, now, startAfter, stop) {
+  const batchSize = runtime.policy.maintenanceBatchSize, lapsed = [];
+  let cursor = startAfter;
+  for (let page = 0;page < OUTBOX_MAINTENANCE_MAX_PAGES; page += 1) {
+    let seen = 0;
+    const options = cursor === void 0 ? { limit: batchSize } : { limit: batchSize, gt: cursor }, observedAt = leaseCommitSerial();
+    if (halted(runtime, stop))
+      return { lapsed: [], nextCursor: startAfter };
+    for await (const [key, value] of runtime.storage.scan(runtime.keys.deliveryPrefix, options)) {
+      seen += 1;
+      cursor = key;
+      const record = decodeApplicationDeliveryRecord(value, key);
+      reconcileLocalAttempts(runtime, record.deliveryId, record, observedAt);
+      if (isDeliveryLeaseExpired(record, now))
+        lapsed.push(record.deliveryId);
+    }
+    if (seen < batchSize)
+      return { lapsed, nextCursor: void 0 };
+  }
+  return { lapsed, nextCursor: cursor };
+}
+export async function runOutboxMaintenance(runtime, now, stop) {
+  const counters = { rescheduled: 0, parked: 0, deadLettered: 0, retired: 0 }, previousCursor = runtime.readMaintenanceCursor(), scan = await collectLapsedDeliveries(runtime, now, previousCursor, stop);
+  try {
+    for (const deliveryId of scan.lapsed) {
+      if (halted(runtime, stop))
+        return Object.freeze({ ...counters });
+      await recoverDelivery(runtime, deliveryId, now, counters, stop);
+    }
+  } catch (error) {
+    runtime.writeMaintenanceCursor(previousCursor);
+    throw error;
+  }
+  runtime.writeMaintenanceCursor(scan.nextCursor);
+  if (!halted(runtime, stop))
+    await retireTerminalReceipts(runtime, now, counters, stop);
+  return Object.freeze({ ...counters });
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Operator transitions for the application delivery outbox (WFT-85): retrying
+ * a parked, dead-lettered, or rejected delivery, and closing a parked one for
+ * good.
+ *
+ * Both are ordinary compare-and-swap transitions on a terminal record. A retry
+ * reopens the delivery — its open-count and due-index maintenance ride in the
+ * same batch — and a dead-letter moves its retention entry to the new terminal
+ * instant.
+ *
+ * @module core/outbox-operations
+ */
+import type { ApplicationDeliveryOperatorResult } from './outbox-contract.ts';
+import { type OutboxRuntime } from './outbox-internals.ts';
+/** Return a parked, dead-lettered, or rejected delivery to the due index with at least one more attempt: an unspent budget is kept, a spent one is raised by one. */
+export declare function retryDelivery(runtime: OutboxRuntime, deliveryId: string): Promise<ApplicationDeliveryOperatorResult>;
+/** Close a parked `unknown-outcome` delivery as dead-lettered. */
+export declare function deadLetterDelivery(runtime: OutboxRuntime, deliveryId: string, reason: string | undefined): Promise<ApplicationDeliveryOperatorResult>;

package/dist/core/outbox-operations.js

@@ -0,0 +1,46 @@
+import { capacityOf } from "./outbox-enqueue.js";
+import {
+  commitDeliveryTransition,
+  MAX_OUTBOX_TRANSITION_ATTEMPTS,
+  OutboxContentionError,
+  toApplicationDeliveryReceipt
+} from "./outbox-internals.js";
+import { loadDelivery, loadOutboxHeader } from "./outbox-storage.js";
+import { isTerminalDeliveryRecord } from "./outbox-transition-helpers.js";
+import {
+  deadLetterDeliveryByOperator,
+  retryDeliveryByOperator
+} from "./outbox-transitions.js";
+async function operate(runtime, deliveryId, operation, decide) {
+  for (let attempt = 1;attempt <= MAX_OUTBOX_TRANSITION_ATTEMPTS; attempt += 1) {
+    const loaded = await loadDelivery(runtime.storage, runtime.keys, deliveryId);
+    if (loaded === null)
+      return { status: "unknown" };
+    const now = runtime.now(), transition = decide(loaded.record, now);
+    if (!transition.ok)
+      return { status: "not-applicable", receipt: toApplicationDeliveryReceipt(loaded.record) };
+    const header = await loadOutboxHeader(runtime.storage, runtime.keys, runtime.policy.namespace, runtime.policy.ownerId);
+    if (!isTerminalDeliveryRecord(transition.next) && header.record.openCount >= runtime.policy.maxBacklog)
+      return {
+        status: "rejected",
+        reason: "backlog-full",
+        capacity: capacityOf(runtime, header.record.openCount, header.record.enqueuedCount)
+      };
+    if (!await commitDeliveryTransition(runtime, {
+      previous: loaded.record,
+      expectedBytes: loaded.bytes,
+      next: transition.next,
+      now,
+      header
+    }))
+      continue;
+    return { status: "applied", receipt: toApplicationDeliveryReceipt(transition.next) };
+  }
+  throw new OutboxContentionError(operation, deliveryId);
+}
+export function retryDelivery(runtime, deliveryId) {
+  return operate(runtime, deliveryId, "retry", (record, now) => retryDeliveryByOperator(record, { now }));
+}
+export function deadLetterDelivery(runtime, deliveryId, reason) {
+  return operate(runtime, deliveryId, "deadLetter", (record, now) => deadLetterDeliveryByOperator(record, { now, reason }));
+}

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

@@ -0,0 +1,30 @@
+/**
+ * The adapter runner for the application delivery outbox (WFT-85): one due
+ * delivery claimed, durably marked `attempting`, handed to the configured
+ * transport, and settled on what the transport reported. The bounded drain
+ * that repeats it lives in `outbox-drain.ts`.
+ *
+ * The runner never trusts the adapter's completion as a disposition. It
+ * validates the outcome, then commits the matching transition fenced on the
+ * attempt token and the `attempting` bytes; only that commit moves the record.
+ * A thrown adapter error is an unknown outcome, because the request may have
+ * left the process. When the attempt deadline elapses while the send is in
+ * flight the runner stops waiting, treats the result as unknown, and aborts
+ * the adapter's signal as it releases the attempt.
+ *
+ * @module core/outbox-runner
+ */
+import type { ApplicationDeliveryAdapter, OutboxDeliverResult } from './outbox-contract.ts';
+import { type OutboxRuntime } from './outbox-internals.ts';
+/**
+ * Claim the earliest due delivery, run it through the adapter, and settle it.
+ *
+ * The `attempting` commit happens before the adapter is called; a claim whose
+ * begin is refused (cancelled or reclaimed between the two) is released
+ * without calling the transport.
+ */
+export declare function deliverNext(runtime: OutboxRuntime, options?: {
+    readonly signal?: AbortSignal | undefined;
+}): Promise<OutboxDeliverResult>;
+/** The configured adapter, or the caller-mistake diagnostic when there is none. */
+export declare function requireAdapter(runtime: OutboxRuntime): ApplicationDeliveryAdapter;