@lostgradient/weft 0.23.1 → 0.24.0

package/dist/core/outbox-drain.js

@@ -0,0 +1,158 @@
+import {
+  raceAbort,
+  raceAbortWithin,
+  WaitBudgetElapsedError
+} from "./application-primitive-abort.js";
+import { delayUnlessAborted } from "./application-primitive-timing.js";
+import { requireWaitBudget } from "./outbox-guards.js";
+import { runOutboxMaintenance } from "./outbox-maintenance.js";
+import { deliverNext, requireAdapter } from "./outbox-runner.js";
+import { loadOutboxHeader } from "./outbox-storage.js";
+function count(counters, receipt) {
+  switch (receipt.state) {
+    case "acknowledged":
+      counters.acknowledged += 1;
+      return !0;
+    case "rejected":
+      counters.rejected += 1;
+      return !0;
+    case "retry-scheduled":
+      counters.retryScheduled += 1;
+      return !1;
+    case "dead-lettered":
+      counters.deadLettered += 1;
+      return !0;
+    case "cancelled":
+      counters.cancelled += 1;
+      return !0;
+    case "unknown-outcome":
+      counters.unknown += 1;
+      return !0;
+    default:
+      return !1;
+  }
+}
+export async function drainOutbox(runtime, options) {
+  requireAdapter(runtime);
+  const { timeoutMs, pollIntervalMs } = requireWaitBudget(options), deadline = runtime.now() + timeoutMs, counters = {
+    acknowledged: 0,
+    rejected: 0,
+    retryScheduled: 0,
+    deadLettered: 0,
+    cancelled: 0,
+    unknown: 0
+  }, stop = drainStopSignal(options.signal, timeoutMs);
+  let drained = !1;
+  try {
+    let lastKnownPending = await readOpenCount(runtime, stop.signal);
+    lastKnownPending = subtract(lastKnownPending, await maintainOutbox(runtime, counters, stop.signal));
+    while (drainActive(runtime, stop.signal) && !budgetSpent(timeoutMs, deadline, runtime.now())) {
+      const result = await deliverUnlessStopped(runtime, stop.signal);
+      if (result === null)
+        break;
+      if (result.status === "settled") {
+        lastKnownPending = absorbDelivery(counters, result, lastKnownPending);
+        continue;
+      }
+      const round = await pauseBeforeNextRound(runtime, result, {
+        counters,
+        deadline,
+        pending: lastKnownPending,
+        pollIntervalMs,
+        stop: stop.signal
+      });
+      lastKnownPending = round.pending;
+      drained = round.status === "drained";
+      if (round.status !== "again")
+        break;
+    }
+    const pending = runtime.disposal.aborted ? lastKnownPending : await readOpenCount(runtime, stop.signal) ?? lastKnownPending;
+    return Object.freeze({ ...counters, pending, drained });
+  } finally {
+    stop.release();
+  }
+}
+function drainStopSignal(callerSignal, timeoutMs) {
+  const controller = new AbortController, onCallerAbort = () => {
+    controller.abort(callerSignal?.reason);
+  };
+  if (callerSignal?.aborted === !0)
+    onCallerAbort();
+  else
+    callerSignal?.addEventListener("abort", onCallerAbort, { once: !0 });
+  const timer = timeoutMs > 0 ? setTimeout(() => {
+    controller.abort(new WaitBudgetElapsedError);
+  }, timeoutMs) : null;
+  timer?.unref?.();
+  return {
+    signal: controller.signal,
+    release: () => {
+      callerSignal?.removeEventListener("abort", onCallerAbort);
+      if (timer !== null)
+        clearTimeout(timer);
+    }
+  };
+}
+async function deliverUnlessStopped(runtime, stop) {
+  const delivery = deliverNext(runtime, { signal: stop }), raced = await raceAbort(() => delivery, stop);
+  if (raced.aborted) {
+    delivery.catch(() => {
+      return;
+    });
+    return null;
+  }
+  return raced.value;
+}
+function absorbDelivery(counters, result, pending) {
+  if (!result.committed)
+    return pending;
+  return count(counters, result.receipt) ? subtract(pending, 1) : pending;
+}
+function subtract(pending, closed) {
+  return pending === null ? null : Math.max(0, pending - (closed ?? 0));
+}
+function drainActive(runtime, stop) {
+  return !runtime.disposal.aborted && !stop.aborted;
+}
+function budgetSpent(timeoutMs, deadline, now) {
+  return timeoutMs > 0 && now >= deadline;
+}
+async function readOpenCount(runtime, stop) {
+  const raced = await raceAbortWithin(() => loadOutboxHeader(runtime.storage, runtime.keys, runtime.policy.namespace, runtime.policy.ownerId), null, stop);
+  return raced.aborted ? null : raced.value.record.openCount;
+}
+async function maintainOutbox(runtime, counters, stop) {
+  const pass = runOutboxMaintenance(runtime, runtime.now(), stop), raced = await raceAbort(() => pass, stop);
+  if (raced.aborted) {
+    pass.catch(() => {
+      return;
+    });
+    return null;
+  }
+  const report = raced.value;
+  counters.unknown += report.parked;
+  counters.deadLettered += report.deadLettered;
+  counters.retryScheduled += report.rescheduled;
+  return report.parked + report.deadLettered;
+}
+async function pauseBeforeNextRound(runtime, result, context) {
+  if (!drainActive(runtime, context.stop))
+    return { status: "stop", pending: context.pending };
+  const closed = await maintainOutbox(runtime, context.counters, context.stop), cached = subtract(context.pending, closed);
+  if (closed === null || runtime.disposal.aborted)
+    return { status: "stop", pending: cached };
+  const pending = await readOpenCount(runtime, context.stop);
+  if (pending === null)
+    return { status: "stop", pending: cached };
+  if (pending === 0)
+    return { status: "drained", pending };
+  const remaining = context.deadline - runtime.now();
+  if (remaining <= 0)
+    return { status: "stop", pending };
+  const wait = nextWait(result, remaining, context.pollIntervalMs, runtime.now());
+  return { status: await delayUnlessAborted(wait, runtime.disposal, context.stop) ? "again" : "stop", pending };
+}
+function nextWait(result, remaining, pollIntervalMs, now) {
+  const untilDue = result.status === "held" ? Math.max(1, result.availableAt - now) : pollIntervalMs;
+  return Math.min(remaining, pollIntervalMs, untilDue);
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Enqueue for the application delivery outbox (WFT-85): validating an offered
+ * delivery, resolving its idempotency identity, enforcing backlog capacity,
+ * and committing the record with its indexes and fleet event.
+ *
+ * Enqueue is the one transition that also allocates: it advances the outbox
+ * header's sequence and open count in the same conditional batch as the record
+ * itself, so backlog accounting can never drift from the records it describes.
+ *
+ * @module core/outbox-enqueue
+ */
+import type { ApplicationDeliveryAdmission, ApplicationDeliveryInput, OutboxCapacity } from './outbox-contract.ts';
+import { type OutboxRuntime } from './outbox-internals.ts';
+/** Backlog accounting, shared by enqueue rejection and the public `capacity()`. */
+export declare function capacityOf(runtime: OutboxRuntime, open: number, enqueued: number): OutboxCapacity;
+/**
+ * Offer a delivery to the outbox.
+ *
+ * An exact retry of the same idempotency identity returns the original
+ * receipt. Reusing the key with a different destination, kind, or payload
+ * digest returns a conflict and leaves the original untouched. A full backlog
+ * is rejected before anything is persisted.
+ */
+export declare function enqueueDelivery(runtime: OutboxRuntime, delivery: ApplicationDeliveryInput): Promise<ApplicationDeliveryAdmission>;

package/dist/core/outbox-enqueue.js

@@ -0,0 +1,115 @@
+import { computeIdentityDigest } from "./application-payload-digest.js";
+import { ApplicationDeliveryValidationError, requireGeneratedIdentifier } from "./outbox-guards.js";
+import {
+  encodeApplicationDeliveryEntry,
+  encodeApplicationDeliveryIdempotencyRecord
+} from "./outbox-index-codec.js";
+import {
+  describeDeliveryTransition,
+  MAX_OUTBOX_TRANSITION_ATTEMPTS,
+  OutboxContentionError,
+  toApplicationDeliveryReceipt
+} from "./outbox-internals.js";
+import {
+  commitOutboxTransition,
+  headerOperation,
+  loadDelivery,
+  loadDeliveryIdempotencyBinding,
+  loadOutboxHeader,
+  planDeliveryTransition
+} from "./outbox-storage.js";
+import { createEnqueuedDeliveryRecord } from "./outbox-transitions.js";
+import { OUTBOX_RECORD_VERSION } from "./outbox-types.js";
+import { validateDeliveryInput } from "./outbox-validation.js";
+import { PersistedDataCorruptError } from "./persisted-data-incompatible-error.js";
+export function capacityOf(runtime, open, enqueued) {
+  const limit = runtime.policy.maxBacklog;
+  return Object.freeze({ open, limit, remaining: Math.max(0, limit - open), enqueued });
+}
+function identityOf(record) {
+  return computeIdentityDigest([record.destinationRef, record.kind, record.payloadDigest]);
+}
+export async function enqueueDelivery(runtime, delivery) {
+  const input = await validateDeliveryInput(delivery, runtime.policy), identityDigest = await identityOf(input);
+  for (let attempt = 1;attempt <= MAX_OUTBOX_TRANSITION_ATTEMPTS; attempt += 1) {
+    let expectedBinding = null;
+    if (input.idempotencyKey !== void 0) {
+      const resolved = await resolveIdempotency(runtime, input.idempotencyKey, identityDigest);
+      if (resolved.admission !== null)
+        return resolved.admission;
+      expectedBinding = resolved.staleBindingBytes;
+    }
+    const header = await loadOutboxHeader(runtime.storage, runtime.keys, runtime.policy.namespace, runtime.policy.ownerId);
+    if (header.record.openCount >= runtime.policy.maxBacklog)
+      return {
+        status: "rejected",
+        reason: "backlog-full",
+        capacity: capacityOf(runtime, header.record.openCount, header.record.enqueuedCount)
+      };
+    if (header.record.nextSequence >= Number.MAX_SAFE_INTEGER)
+      throw new ApplicationDeliveryValidationError("This outbox has exhausted its sequence allocator; no further deliveries can be enqueued under this namespace and owner id.");
+    const now = runtime.now(), record = createEnqueuedDeliveryRecord(input, {
+      namespace: runtime.policy.namespace,
+      ownerId: runtime.policy.ownerId,
+      deliveryId: requireGeneratedIdentifier(runtime.generateId(), "deliveryId"),
+      sequence: header.record.nextSequence,
+      now
+    }), idempotencyKey = input.idempotencyKey;
+    if (!await commitOutboxTransition(runtime.storage, runtime.events, planDeliveryTransition(runtime.keys, {
+      previous: null,
+      expectedBytes: null,
+      next: record,
+      event: describeDeliveryTransition(null, record),
+      now,
+      extraConditions: [
+        { key: runtime.keys.header, expectedValue: header.bytes },
+        ...idempotencyKey === void 0 ? [] : [{ key: runtime.keys.idempotency(idempotencyKey), expectedValue: expectedBinding }]
+      ],
+      extraOperations: [
+        {
+          type: "put",
+          key: runtime.keys.bySequence(record.sequence),
+          value: encodeApplicationDeliveryEntry(record.deliveryId)
+        },
+        headerOperation(runtime.keys, {
+          ...header.record,
+          nextSequence: header.record.nextSequence + 1,
+          openCount: header.record.openCount + 1,
+          enqueuedCount: header.record.enqueuedCount + 1
+        }),
+        ...idempotencyKey === void 0 ? [] : [
+          {
+            type: "put",
+            key: runtime.keys.idempotency(idempotencyKey),
+            value: encodeApplicationDeliveryIdempotencyRecord({
+              recordVersion: OUTBOX_RECORD_VERSION,
+              deliveryId: record.deliveryId,
+              identityDigest
+            })
+          }
+        ]
+      ]
+    })))
+      continue;
+    return { status: "enqueued", receipt: toApplicationDeliveryReceipt(record) };
+  }
+  throw new OutboxContentionError("enqueue", null);
+}
+async function resolveIdempotency(runtime, idempotencyKey, identityDigest) {
+  const binding = await loadDeliveryIdempotencyBinding(runtime.storage, runtime.keys, idempotencyKey);
+  if (binding === null)
+    return { admission: null, staleBindingBytes: null };
+  const loaded = await loadDelivery(runtime.storage, runtime.keys, binding.record.deliveryId);
+  if (loaded === null)
+    return { admission: null, staleBindingBytes: binding.bytes };
+  const ownDigest = await identityOf(loaded.record);
+  if (loaded.record.idempotencyKey !== idempotencyKey || ownDigest !== binding.record.identityDigest)
+    throw new PersistedDataCorruptError(runtime.keys.idempotency(idempotencyKey));
+  const receipt = toApplicationDeliveryReceipt(loaded.record);
+  if (binding.record.identityDigest !== identityDigest)
+    return {
+      admission: { status: "conflict", receipt, reason: "idempotency-identity-mismatch" },
+      staleBindingBytes: null
+    };
+  return { admission: { status: "duplicate", receipt }, staleBindingBytes: null };
+}

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

@@ -0,0 +1,76 @@
+/**
+ * The delivery outbox's binding of the shared application guards (WFT-85),
+ * plus the ceilings and checks only the outbox needs.
+ *
+ * Every guard throws `ApplicationDeliveryValidationError`, so a caller mistake
+ * surfaces as the outbox's own typed diagnostic rather than as the mailbox's.
+ *
+ * @module core/outbox-guards
+ */
+import type { ApplicationDeliveryFailure } from './outbox-types.ts';
+import { WeftError } from './weft-error.ts';
+export { DEFAULT_WAIT_POLL_INTERVAL_MS, MAX_APPLICATION_IDENTITY_BYTES, MAX_DURABLE_METADATA_BYTES, MAX_TIMER_DELAY_MS, } from './application-primitive-guards.ts';
+export { MAX_APPLICATION_PAYLOAD_REFERENCE_BYTES } from './application-primitive-payload.ts';
+/**
+ * Maximum bytes in an idempotency key or an external idempotency key. Matches
+ * the persisted-identifier ceiling the record decoder enforces, so a key
+ * admission accepts can never be one every later read rejects as corrupt.
+ */
+export declare const MAX_APPLICATION_DELIVERY_IDEMPOTENCY_KEY_BYTES = 256;
+/** Maximum attempts any one delivery may be configured for. */
+export declare const MAX_APPLICATION_DELIVERY_ATTEMPTS = 100;
+/** Maximum open deliveries any one outbox may be configured for. */
+export declare const MAX_OUTBOX_BACKLOG = 1000000;
+/** Ceiling on a `list()` limit. */
+export declare const MAX_OUTBOX_LIST_LIMIT = 1000;
+/** Maximum bytes in a failure message. */
+export declare const MAX_DELIVERY_FAILURE_MESSAGE_BYTES = 4096;
+/** Maximum bytes in a cancellation reason. */
+export declare const MAX_DELIVERY_CANCELLATION_REASON_BYTES = 1024;
+/**
+ * Thrown when a caller supplies an invalid delivery, option, identifier, or
+ * outcome, or calls a disposed outbox.
+ *
+ * @example
+ * ```ts
+ * import { ApplicationDeliveryValidationError } from '@lostgradient/weft';
+ *
+ * const error = new ApplicationDeliveryValidationError('destinationRef must be a non-empty string.');
+ * console.log(error.code); // 'ApplicationDeliveryValidationError'
+ * ```
+ */
+export declare class ApplicationDeliveryValidationError extends WeftError<'ApplicationDeliveryValidationError'> {
+    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 the message and details a transport attached to an outcome before
+ * they become durable evidence. The reason is assigned by the outbox from the
+ * outcome's status, never taken from the caller.
+ *
+ * @throws {ApplicationDeliveryValidationError} When `details` is not JSON-safe
+ * or `message` is oversized.
+ */
+export declare function validateFailureEvidence(reason: ApplicationDeliveryFailure['reason'], message: unknown, details: unknown): ApplicationDeliveryFailure;
+/**
+ * Bound a diagnostic string the outbox composes itself (an adapter's thrown
+ * error, say) to the failure-message ceiling, cutting on a character boundary
+ * and keeping the result well-formed, so a misbehaving transport cannot grow
+ * a delivery record without limit.
+ */
+export declare function boundFailureMessage(text: string): string;
+/** Validate a caller-supplied cancellation reason before it becomes durable. */
+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;
+/**
+ * Validate a caller-supplied delivery id before it reaches key construction,
+ * where an unpaired surrogate would escape as a raw `URIError`.
+ */
+export declare function validateDeliveryIdentifier(deliveryId: unknown): string;

package/dist/core/outbox-guards.js

@@ -0,0 +1,60 @@
+import {
+  byteLengthOf,
+  createApplicationGuards,
+  MAX_APPLICATION_IDENTITY_BYTES
+} from "./application-primitive-guards.js";
+import { WeftError } from "./weft-error.js";
+export {
+  DEFAULT_WAIT_POLL_INTERVAL_MS,
+  MAX_APPLICATION_IDENTITY_BYTES,
+  MAX_DURABLE_METADATA_BYTES,
+  MAX_TIMER_DELAY_MS
+} from "./application-primitive-guards.js";
+export { MAX_APPLICATION_PAYLOAD_REFERENCE_BYTES } from "./application-primitive-payload.js";
+export const MAX_APPLICATION_DELIVERY_IDEMPOTENCY_KEY_BYTES = MAX_APPLICATION_IDENTITY_BYTES, MAX_APPLICATION_DELIVERY_ATTEMPTS = 100, MAX_OUTBOX_BACKLOG = 1e6, MAX_OUTBOX_LIST_LIMIT = 1000, MAX_DELIVERY_FAILURE_MESSAGE_BYTES = 4096, MAX_DELIVERY_CANCELLATION_REASON_BYTES = 1024;
+
+export class ApplicationDeliveryValidationError extends WeftError {
+  constructor(message, options) {
+    super("ApplicationDeliveryValidationError", message, options);
+  }
+}
+export const {
+  requireIdentity,
+  optionalIdentityOf,
+  requirePositiveInteger,
+  requireNonNegativeInteger,
+  validateDurableJSONValue,
+  requireGeneratedIdentifier,
+  requireClockInstant,
+  requireDerivedInstant,
+  requireMaintenanceInstant,
+  requireWaitBudget
+} = createApplicationGuards(ApplicationDeliveryValidationError);
+export function validateFailureEvidence(reason, message, details) {
+  return {
+    reason,
+    message: optionalIdentityOf(message, "message", MAX_DELIVERY_FAILURE_MESSAGE_BYTES),
+    details: validateDurableJSONValue(details, "details")
+  };
+}
+export function boundFailureMessage(text) {
+  let bounded = text.toWellFormed();
+  while (byteLengthOf(bounded) > MAX_DELIVERY_FAILURE_MESSAGE_BYTES) {
+    const excess = byteLengthOf(bounded) - MAX_DELIVERY_FAILURE_MESSAGE_BYTES;
+    bounded = bounded.slice(0, -Math.max(1, Math.ceil(excess / 4))).toWellFormed();
+  }
+  return bounded;
+}
+export function validateCancellationReason(reason) {
+  return optionalIdentityOf(reason, "reason", MAX_DELIVERY_CANCELLATION_REASON_BYTES);
+}
+export function clampListLimit(limit) {
+  if (limit === void 0)
+    return 100;
+  if (!Number.isSafeInteger(limit) || limit < 1)
+    throw new ApplicationDeliveryValidationError("limit must be a positive safe integer.");
+  return Math.min(limit, MAX_OUTBOX_LIST_LIMIT);
+}
+export function validateDeliveryIdentifier(deliveryId) {
+  return requireIdentity(deliveryId, "deliveryId", 256);
+}

package/dist/core/outbox-index-codec.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Encoding and fail-closed decoding for the application outbox's index
+ * records (WFT-85): the per-outbox header, the idempotency binding, and the
+ * delivery-id entries the due, listing, and terminal indexes hold.
+ *
+ * @module core/outbox-index-codec
+ */
+import type { ApplicationDeliveryIdempotencyRecord, OutboxRecord } from './outbox-types.ts';
+/**
+ * Decode the per-outbox header.
+ *
+ * @throws {PersistedDataCorruptError} When the stored bytes are malformed or
+ * name a different outbox than the key does.
+ */
+export declare function decodeOutboxRecord(bytes: Uint8Array, key: string): OutboxRecord;
+/** Encode the per-outbox header. */
+export declare function encodeOutboxRecord(record: OutboxRecord): Uint8Array;
+/**
+ * Decode an idempotency binding.
+ *
+ * @throws {PersistedDataCorruptError} When the stored bytes are malformed.
+ */
+export declare function decodeApplicationDeliveryIdempotencyRecord(bytes: Uint8Array, key: string): ApplicationDeliveryIdempotencyRecord;
+/** Encode an idempotency binding. */
+export declare function encodeApplicationDeliveryIdempotencyRecord(record: ApplicationDeliveryIdempotencyRecord): Uint8Array;
+/**
+ * Decode a due, listing, or terminal index entry: the delivery id it points at.
+ *
+ * @throws {PersistedDataCorruptError} When the entry is not a usable identifier.
+ */
+export declare function decodeApplicationDeliveryEntry(bytes: Uint8Array, key: string): string;
+/** Encode a due, listing, or terminal index entry. */
+export declare function encodeApplicationDeliveryEntry(deliveryId: string): Uint8Array;

package/dist/core/outbox-index-codec.js

@@ -0,0 +1,71 @@
+import { KEYS } from "../storage/interface.js";
+import {
+  fail,
+  isRecordObject,
+  ownKey,
+  readIdentifier,
+  readInteger,
+  readString,
+  readVersion
+} from "./application-primitive-codec.js";
+import { decode, encode } from "./codec.js";
+import { OUTBOX_RECORD_VERSION } from "./outbox-types.js";
+export function decodeOutboxRecord(bytes, key) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    fail(key);
+  }
+  if (!isRecordObject(decoded))
+    fail(key);
+  readVersion(decoded, key, OUTBOX_RECORD_VERSION);
+  const namespace = readString(decoded, "namespace", key), ownerId = readString(decoded, "ownerId", key);
+  if (ownKey(() => KEYS.applicationOutbox(namespace, ownerId), key) !== key)
+    fail(key);
+  const nextSequence = readInteger(decoded, "nextSequence", key), openCount = readInteger(decoded, "openCount", key), enqueuedCount = readInteger(decoded, "enqueuedCount", key);
+  if (openCount > enqueuedCount || nextSequence < enqueuedCount)
+    fail(key);
+  return {
+    recordVersion: OUTBOX_RECORD_VERSION,
+    namespace,
+    ownerId,
+    nextSequence,
+    openCount,
+    enqueuedCount
+  };
+}
+export function encodeOutboxRecord(record) {
+  return encode(record);
+}
+export function decodeApplicationDeliveryIdempotencyRecord(bytes, key) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    fail(key);
+  }
+  if (!isRecordObject(decoded))
+    fail(key);
+  readVersion(decoded, key, OUTBOX_RECORD_VERSION);
+  return {
+    recordVersion: OUTBOX_RECORD_VERSION,
+    deliveryId: readIdentifier(decoded.deliveryId, key),
+    identityDigest: readString(decoded, "identityDigest", key)
+  };
+}
+export function encodeApplicationDeliveryIdempotencyRecord(record) {
+  return encode(record);
+}
+export function decodeApplicationDeliveryEntry(bytes, key) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    fail(key);
+  }
+  return readIdentifier(decoded, key);
+}
+export function encodeApplicationDeliveryEntry(deliveryId) {
+  return encode(deliveryId);
+}

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

@@ -0,0 +1,99 @@
+/**
+ * Shared runtime plumbing for the application delivery outbox (WFT-85): the
+ * per-instance runtime, the contention error, receipt projection, fleet event
+ * description, process-local attempt release, and the commit that keeps the
+ * header's backlog accounting consistent with every transition.
+ *
+ * @module core/outbox-internals
+ */
+import type { BatchOperation, ConditionalBatchCondition, Storage } from '../storage/interface.ts';
+import type { AttemptRegistry } from './application-primitive-attempt-registry.ts';
+import type { ApplicationDeliveryAdapter, ApplicationDeliveryReceipt, OutboxEventSink } from './outbox-contract.ts';
+import { type LoadedOutboxRecord, type OutboxKeys } from './outbox-storage.ts';
+import { type ApplicationDeliveryRecord } from './outbox-types.ts';
+import type { ResolvedOutboxPolicy } from './outbox-validation.ts';
+import { WeftError } from './weft-error.ts';
+/** How many times one operation re-reads and retries a lost compare-and-swap. */
+export declare const MAX_OUTBOX_TRANSITION_ATTEMPTS = 25;
+/** How many scan pages one maintenance pass may walk. */
+export declare const OUTBOX_MAINTENANCE_MAX_PAGES = 200;
+/** The registry-scope tag for the outbox, so it never shares a registry with the mailbox. */
+export declare const OUTBOX_PRIMITIVE = "outbox";
+/** Everything an outbox operation needs that is fixed at construction. */
+export type OutboxRuntime = {
+    readonly storage: Storage;
+    readonly events: OutboxEventSink | undefined;
+    readonly adapter: ApplicationDeliveryAdapter | undefined;
+    readonly policy: ResolvedOutboxPolicy;
+    readonly keys: OutboxKeys;
+    readonly now: () => number;
+    readonly generateId: () => string;
+    /** The process-local disposal signal every wait and attempt races. */
+    readonly disposal: AbortSignal;
+    readonly attemptControllers: AttemptRegistry;
+    /** Record an attempt this handle now owns, or report that disposal already won. */
+    readonly adoptAttempt: (attemptToken: string) => (() => void) | null;
+    readonly readMaintenanceCursor: () => string | undefined;
+    readonly writeMaintenanceCursor: (cursor: string | undefined) => void;
+};
+/**
+ * Thrown when a transition keeps losing its compare-and-swap: durable
+ * contention on this outbox is real, and the caller decides whether to back
+ * off, shed load, or shard the owner.
+ *
+ * @example
+ * ```ts
+ * import { OutboxContentionError } from '@lostgradient/weft';
+ *
+ * const error = new OutboxContentionError('enqueue', null);
+ * console.log(error.code); // 'OutboxContentionError'
+ * ```
+ */
+export declare class OutboxContentionError extends WeftError<'OutboxContentionError'> {
+    /** The outbox operation that could not commit. */
+    readonly operation: string;
+    /** The delivery the operation targeted, or `null` for outbox-wide operations. */
+    readonly deliveryId: string | null;
+    constructor(operation: string, deliveryId: string | null);
+}
+/**
+ * Project a durable record into the immutable public receipt. The attempt
+ * token and the credential reference are never projected.
+ */
+export declare function toApplicationDeliveryReceipt(record: ApplicationDeliveryRecord): ApplicationDeliveryReceipt;
+/**
+ * The durable fleet event that describes a transition. Bounded and free of
+ * secrets: no payload, no evidence, no failure details, and neither the
+ * destination nor the credential reference.
+ */
+export declare function describeDeliveryTransition(previous: ApplicationDeliveryRecord | null, next: ApplicationDeliveryRecord): {
+    readonly kind: string;
+    readonly payload: unknown;
+};
+/** Abort and forget the process-local controller for one attempt. */
+export declare function releaseAttemptController(runtime: OutboxRuntime, attemptToken: string, reason: string, deliveryId?: string): void;
+/**
+ * Release every attempt this process holds for one delivery that is not its
+ * current lease, fenced by the lease-commit serial the snapshot was read at.
+ */
+export declare function releaseAttemptsForDelivery(runtime: OutboxRuntime, deliveryId: string, reason: string, currentToken?: string, observedAt?: number): void;
+/**
+ * Commit one delivery transition together with the index maintenance and
+ * backlog accounting it implies.
+ *
+ * Closing a delivery decrements the header's open count and an operator
+ * retry that reopens one increments it, each in the same conditional batch as
+ * the record, so `capacity()` can never drift from the records it describes.
+ * Enqueue builds its own header operation because it also allocates the
+ * sequence.
+ */
+export declare function commitDeliveryTransition(runtime: OutboxRuntime, options: {
+    readonly previous: ApplicationDeliveryRecord | null;
+    readonly expectedBytes: Uint8Array | null;
+    readonly next: ApplicationDeliveryRecord;
+    readonly now: number;
+    readonly extraConditions?: readonly ConditionalBatchCondition[] | undefined;
+    readonly extraOperations?: readonly BatchOperation[] | undefined;
+    /** A header the caller already read and decided on; the commit fences on these bytes. */
+    readonly header?: LoadedOutboxRecord | undefined;
+}): Promise<boolean>;