@lostgradient/weft 0.23.0 → 0.24.0

package/dist/core/outbox-transitions.js

@@ -0,0 +1,236 @@
+import { requireDerivedInstant } from "./outbox-guards.js";
+import {
+  applicationDeliveryIdentityFields,
+  nonTerminalDeliveryRecord,
+  rejectedTransition,
+  rescheduleOrDeadLetter,
+  succeededTransition
+} from "./outbox-transition-helpers.js";
+import {
+  OUTBOX_RECORD_VERSION,
+  isApplicationDeliveryLeased,
+  isApplicationDeliveryTerminalState
+} from "./outbox-types.js";
+export {
+  isTerminalDeliveryRecord,
+  nonTerminalDeliveryRecord
+} from "./outbox-transition-helpers.js";
+export function createEnqueuedDeliveryRecord(input, context) {
+  return {
+    recordVersion: OUTBOX_RECORD_VERSION,
+    namespace: context.namespace,
+    ownerId: context.ownerId,
+    deliveryId: context.deliveryId,
+    sequence: context.sequence,
+    idempotencyKey: input.idempotencyKey,
+    destinationRef: input.destinationRef,
+    credentialRef: input.credentialRef,
+    kind: input.kind,
+    payload: input.payload,
+    payloadDigest: input.payloadDigest,
+    payloadMediaType: input.payloadMediaType,
+    payloadSchema: input.payloadSchema,
+    causation: input.causation,
+    externalIdempotencyKey: input.externalIdempotencyKey,
+    unknownOutcomePolicy: input.unknownOutcomePolicy,
+    enqueuedAt: context.now,
+    availableAt: requireDerivedInstant(context.now + input.availableAfterMs, "availableAt"),
+    maxAttempts: input.maxAttempts,
+    visibilityTimeoutMs: input.visibilityTimeoutMs,
+    attemptTimeoutMs: input.attemptTimeoutMs,
+    generation: 0,
+    attempt: 0,
+    retryCount: 0,
+    state: "queued"
+  };
+}
+export function claimWaitingDelivery(record, options) {
+  const live = nonTerminalDeliveryRecord(record);
+  if (live === null)
+    return rejectedTransition("already-terminal");
+  if (live.state !== "queued" && live.state !== "retry-scheduled")
+    return rejectedTransition("not-waiting");
+  if (options.now < live.availableAt)
+    return rejectedTransition("not-due");
+  const attemptDeadlineAt = requireDerivedInstant(options.now + live.attemptTimeoutMs, "attemptDeadlineAt");
+  return succeededTransition({
+    ...applicationDeliveryIdentityFields(live),
+    state: "claimed",
+    attempt: live.attempt + 1,
+    firstClaimedAt: live.firstClaimedAt ?? options.now,
+    attemptToken: options.attemptToken,
+    claimedAt: options.now,
+    attemptDeadlineAt,
+    visibilityExpiresAt: Math.min(options.now + live.visibilityTimeoutMs, attemptDeadlineAt),
+    lastActivityAt: options.now
+  });
+}
+function checkCurrentAttempt(record, attemptToken, now) {
+  if (isApplicationDeliveryTerminalState(record.state))
+    return { ok: !1, reason: "already-terminal" };
+  if (!isApplicationDeliveryLeased(record))
+    return { ok: !1, reason: "not-leased" };
+  if (record.attemptToken !== attemptToken)
+    return { ok: !1, reason: "stale-attempt" };
+  if (now >= record.attemptDeadlineAt)
+    return { ok: !1, reason: "deadline-exceeded" };
+  return { ok: !0, leased: record };
+}
+export function beginDeliveryAttempt(record, options) {
+  const checked = checkCurrentAttempt(record, options.attemptToken, options.now);
+  if (!checked.ok)
+    return rejectedTransition(checked.reason);
+  const { leased } = checked;
+  if (leased.state === "cancellation-requested")
+    return rejectedTransition("cancellation-requested");
+  if (leased.state !== "claimed")
+    return rejectedTransition("not-applicable");
+  return succeededTransition({
+    ...leased,
+    generation: leased.generation + 1,
+    state: "attempting",
+    attemptStartedAt: options.now,
+    lastActivityAt: options.now,
+    visibilityExpiresAt: Math.min(options.now + leased.visibilityTimeoutMs, leased.attemptDeadlineAt)
+  });
+}
+export function heartbeatDeliveryAttempt(record, options) {
+  const checked = checkCurrentAttempt(record, options.attemptToken, options.now);
+  if (!checked.ok)
+    return rejectedTransition(checked.reason);
+  const { leased } = checked;
+  return succeededTransition({
+    ...leased,
+    generation: leased.generation + 1,
+    lastActivityAt: options.now,
+    visibilityExpiresAt: Math.min(options.now + leased.visibilityTimeoutMs, leased.attemptDeadlineAt),
+    transportActivity: options.transportActivity === void 0 ? leased.transportActivity : options.transportActivity
+  });
+}
+function cancellationFields(leased) {
+  return leased.state === "cancellation-requested" ? {
+    cancellationRequestedAt: leased.cancellationRequestedAt,
+    cancellationReason: leased.cancellationReason
+  } : {};
+}
+export function applyUnknownOutcomePolicy(leased, options) {
+  const cancelling = leased.state === "cancellation-requested", abandoned = options.abandonedAttemptToken === void 0 ? {} : { cleanupPending: !0, abandonedAttemptToken: options.abandonedAttemptToken };
+  if (leased.unknownOutcomePolicy === "dead-letter")
+    return {
+      ...applicationDeliveryIdentityFields(leased),
+      state: "dead-lettered",
+      terminalAt: options.now,
+      failure: options.failure,
+      ...cancellationFields(leased),
+      ...abandoned
+    };
+  if (leased.unknownOutcomePolicy === "retry-with-idempotency" && !cancelling) {
+    const next = rescheduleOrDeadLetter(leased, { ...options, failure: options.failure });
+    return next.state === "dead-lettered" ? { ...next, ...abandoned } : next;
+  }
+  return {
+    ...applicationDeliveryIdentityFields(leased),
+    state: "unknown-outcome",
+    terminalAt: options.now,
+    failure: options.failure,
+    ...cancellationFields(leased),
+    ...abandoned
+  };
+}
+export function settleDeliveryAttempt(record, options) {
+  const checked = checkCurrentAttempt(record, options.attemptToken, options.now);
+  if (!checked.ok)
+    return rejectedTransition(checked.reason);
+  const { leased } = checked;
+  if (leased.state === "claimed")
+    return rejectedTransition("not-attempting");
+  const { outcome } = options;
+  if (outcome.status === "acknowledged")
+    return succeededTransition({
+      ...applicationDeliveryIdentityFields(leased),
+      state: "acknowledged",
+      terminalAt: options.now,
+      evidence: outcome.evidence,
+      ...cancellationFields(leased)
+    });
+  if (outcome.status === "unknown")
+    return succeededTransition(applyUnknownOutcomePolicy(leased, {
+      now: options.now,
+      retryBackoffMs: options.retryBackoffMs,
+      maxRetryBackoffMs: options.maxRetryBackoffMs,
+      failure: { reason: "unknown-outcome", message: outcome.failure.message }
+    }));
+  if (leased.state === "cancellation-requested")
+    return succeededTransition({
+      ...applicationDeliveryIdentityFields(leased),
+      state: "cancelled",
+      terminalAt: options.now,
+      failure: { reason: "cancelled" },
+      ...cancellationFields(leased),
+      cleanupPending: !1
+    });
+  if (outcome.status === "rejected")
+    return succeededTransition({
+      ...applicationDeliveryIdentityFields(leased),
+      state: "rejected",
+      terminalAt: options.now,
+      failure: outcome.failure
+    });
+  return succeededTransition(rescheduleOrDeadLetter(leased, {
+    ...options,
+    failure: outcome.failure,
+    retryAfterMs: outcome.retryAfterMs
+  }));
+}
+export function requestDeliveryCancellation(record, options) {
+  const live = nonTerminalDeliveryRecord(record);
+  if (live === null)
+    return rejectedTransition("already-terminal");
+  if (live.state === "cancellation-requested")
+    return rejectedTransition("not-leased");
+  if (live.state === "attempting")
+    return succeededTransition({
+      ...live,
+      generation: live.generation + 1,
+      state: "cancellation-requested",
+      cancellationRequestedAt: options.now,
+      cancellationReason: options.reason
+    });
+  return succeededTransition({
+    ...applicationDeliveryIdentityFields(live),
+    state: "cancelled",
+    terminalAt: options.now,
+    failure: { reason: "cancelled" },
+    cancellationRequestedAt: options.now,
+    cancellationReason: options.reason,
+    cleanupPending: !1
+  });
+}
+export function retryDeliveryByOperator(record, options) {
+  if (record.state !== "unknown-outcome" && record.state !== "dead-lettered" && record.state !== "rejected")
+    return rejectedTransition("not-applicable");
+  return succeededTransition({
+    ...applicationDeliveryIdentityFields(record),
+    state: "queued",
+    maxAttempts: Math.max(record.maxAttempts, record.attempt + 1),
+    availableAt: options.now
+  });
+}
+export function deadLetterDeliveryByOperator(record, options) {
+  if (record.state !== "unknown-outcome")
+    return rejectedTransition("not-applicable");
+  return succeededTransition({
+    ...applicationDeliveryIdentityFields(record),
+    state: "dead-lettered",
+    terminalAt: options.now,
+    failure: {
+      reason: "unknown-outcome",
+      message: options.reason ?? record.failure?.message,
+      details: record.failure?.details
+    },
+    cancellationRequestedAt: record.cancellationRequestedAt,
+    cancellationReason: record.cancellationReason,
+    cleanupPending: record.cleanupPending,
+    abandonedAttemptToken: record.abandonedAttemptToken
+  });
+}

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

@@ -0,0 +1,400 @@
+/**
+ * Durable record types for the application delivery outbox (WFT-85).
+ *
+ * A delivery is one intent to send one payload to one opaque destination. Its
+ * record is the single authority for what has been attempted, what the
+ * transport reported, and what disposition the outbox committed on that
+ * evidence. Transport completion is never a disposition on its own: a socket
+ * or HTTP write finishing is evidence the adapter reports, and only the
+ * durable settlement the outbox commits on it moves the record.
+ *
+ * The shapes mirror the command mailbox's; what differs is the vocabulary:
+ * `attempting` is a durable disposition committed before the adapter runs,
+ * `unknown-outcome` parks a lost transport result, and there is no
+ * per-delivery deadline — each attempt has its own.
+ *
+ * @module core/outbox-types
+ */
+import type { JSONValue } from './json.ts';
+import type { ApplicationCommandCausation, ApplicationCommandPayload } from './mailbox-types.ts';
+/** The record schema version every outbox record carries. */
+export declare const OUTBOX_RECORD_VERSION = 1;
+/**
+ * The payload of a delivery: the same inline-or-reference shape the command
+ * mailbox uses, so one content-addressed store can back both primitives.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryPayload } from '@lostgradient/weft';
+ *
+ * const payload: ApplicationDeliveryPayload = { form: 'inline', value: { event: 'task.completed' } };
+ * console.log(payload.form); // 'inline'
+ * ```
+ */
+export type ApplicationDeliveryPayload = ApplicationCommandPayload;
+/**
+ * Causal metadata carried on a delivery, identical in shape to the mailbox's.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryCausation } from '@lostgradient/weft';
+ *
+ * const causation: ApplicationDeliveryCausation = { correlationId: 'run-1' };
+ * console.log(causation.correlationId); // 'run-1'
+ * ```
+ */
+export type ApplicationDeliveryCausation = ApplicationCommandCausation;
+/**
+ * Every disposition a delivery record can occupy.
+ *
+ * ```text
+ * queued / retry-scheduled  waiting in the due index
+ * claimed                   leased; the adapter has NOT been called
+ * attempting                leased; the adapter call durably began
+ * cancellation-requested    attempting, with cancellation durably requested
+ * acknowledged              terminal: the transport reported acknowledgement
+ * rejected                  terminal: the transport reported a permanent refusal
+ * cancelled                 terminal: cancelled before any effect was confirmed
+ * unknown-outcome           terminal: the transport result was lost; parked
+ * dead-lettered             terminal: attempts exhausted, or unknown by policy
+ * ```
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryState } from '@lostgradient/weft';
+ *
+ * const state: ApplicationDeliveryState = 'queued';
+ * console.log(state); // 'queued'
+ * ```
+ */
+export type ApplicationDeliveryState = 'queued' | 'retry-scheduled' | 'claimed' | 'attempting' | 'cancellation-requested' | 'acknowledged' | 'rejected' | 'cancelled' | 'unknown-outcome' | 'dead-lettered';
+/**
+ * The terminal subset of {@link ApplicationDeliveryState}.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryTerminalState } from '@lostgradient/weft';
+ *
+ * const state: ApplicationDeliveryTerminalState = 'acknowledged';
+ * console.log(state); // 'acknowledged'
+ * ```
+ */
+export type ApplicationDeliveryTerminalState = 'acknowledged' | 'rejected' | 'cancelled' | 'unknown-outcome' | 'dead-lettered';
+/** Every terminal state, in a stable order. */
+export declare const APPLICATION_DELIVERY_TERMINAL_STATES: readonly ApplicationDeliveryTerminalState[];
+/**
+ * What the outbox does when a transport result is lost — an adapter that
+ * reported `unknown`, threw, or whose attempt lease expired after the send
+ * durably began.
+ *
+ * `park` leaves the delivery in `unknown-outcome` for an operator to `retry()`
+ * or `deadLetter()`. `dead-letter` terminalizes it at once. `retry-with-
+ * idempotency` schedules another attempt, and is accepted at enqueue only when
+ * the delivery carries an `externalIdempotencyKey`: without stable external
+ * idempotency evidence a retry could duplicate an effect that already happened.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryUnknownOutcomePolicy } from '@lostgradient/weft';
+ *
+ * const policy: ApplicationDeliveryUnknownOutcomePolicy = 'park';
+ * console.log(policy); // 'park'
+ * ```
+ */
+export type ApplicationDeliveryUnknownOutcomePolicy = 'park' | 'dead-letter' | 'retry-with-idempotency';
+/**
+ * Why a delivery failed, rescheduled, or parked. Every reason names one
+ * outbox-owned mechanism except `application`, which the transport supplied.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryFailure } from '@lostgradient/weft';
+ *
+ * const failure: ApplicationDeliveryFailure = { reason: 'retryable', message: '503' };
+ * console.log(failure.reason); // 'retryable'
+ * ```
+ */
+export type ApplicationDeliveryFailure = Readonly<{
+    reason: 'application' | 'retryable' | 'attempts-exhausted' | 'unknown-outcome' | 'cancelled';
+    message?: string | undefined;
+    details?: JSONValue | undefined;
+}>;
+/**
+ * Fields every delivery record carries in every state: the identity and policy
+ * fixed at enqueue. Only `maxAttempts` is ever rewritten, by an operator
+ * `retry()` granting one more attempt. `credentialRef` is persisted because
+ * every attempt needs it and is projected into no receipt, event, or diagnostic.
+ */
+export type ApplicationDeliveryBase = Readonly<{
+    recordVersion: typeof OUTBOX_RECORD_VERSION;
+    namespace: string;
+    ownerId: string;
+    deliveryId: string;
+    /** Enqueue order within the outbox. Listing order only; never a delivery order. */
+    sequence: number;
+    idempotencyKey?: string | undefined;
+    destinationRef: string;
+    credentialRef?: string | undefined;
+    kind: string;
+    payload: ApplicationDeliveryPayload;
+    payloadDigest: string;
+    payloadMediaType?: string | undefined;
+    payloadSchema?: string | undefined;
+    causation?: ApplicationDeliveryCausation | undefined;
+    /** Stable external idempotency evidence the transport can present on a retry. */
+    externalIdempotencyKey?: string | undefined;
+    unknownOutcomePolicy: ApplicationDeliveryUnknownOutcomePolicy;
+    enqueuedAt: number;
+    maxAttempts: number;
+    /** Lease renewal window in milliseconds. Heartbeat extends visibility by this much. */
+    visibilityTimeoutMs: number;
+    /** Ceiling on one attempt in milliseconds from its claim. Heartbeat cannot move it. */
+    attemptTimeoutMs: number;
+    /** Monotonic transition counter. Diagnostic provenance; whole-record byte equality is the real fence. */
+    generation: number;
+}>;
+/** Attempt provenance preserved across claim, expiry, retry, and recovery. */
+export type ApplicationDeliveryAttemptFields = Readonly<{
+    /** Number of claims issued so far. `0` until the first claim. */
+    attempt: number;
+    /** Number of reschedules caused by retryable outcomes, unknown outcomes, or lease expiry. */
+    retryCount: number;
+    /** First time any attempt claimed this delivery. Absent until the first claim. */
+    firstClaimedAt?: number | undefined;
+}>;
+/** A delivery waiting for its first attempt.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryQueued } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryQueued;
+ * console.log(record.state, record.availableAt); // 'queued', when it is due
+ * ```
+ */
+export type ApplicationDeliveryQueued = ApplicationDeliveryBase & ApplicationDeliveryAttemptFields & Readonly<{
+    state: 'queued';
+    availableAt: number;
+}>;
+/** A delivery waiting for a further attempt after a retryable, unknown, or expired one.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryRetryScheduled } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryRetryScheduled;
+ * console.log(record.lastFailure?.reason);
+ * ```
+ */
+export type ApplicationDeliveryRetryScheduled = ApplicationDeliveryBase & ApplicationDeliveryAttemptFields & Readonly<{
+    state: 'retry-scheduled';
+    availableAt: number;
+    /** Why the previous attempt did not acknowledge. */
+    lastFailure: ApplicationDeliveryFailure;
+}>;
+/** Lease fields held while one attempt owns a delivery. */
+export type ApplicationDeliveryLeaseFields = Readonly<{
+    /** Opaque per-attempt fencing token. Every mutation from a claimant must present it. */
+    attemptToken: string;
+    claimedAt: number;
+    /** When an unrenewed claim becomes reclaimable. Never later than `attemptDeadlineAt`. */
+    visibilityExpiresAt: number;
+    /** The ceiling on this attempt. Fixed at claim; heartbeat clamps to it and never moves it. */
+    attemptDeadlineAt: number;
+    /** Latest liveness evidence from the claimant. Distinct from acknowledgement. */
+    lastActivityAt: number;
+    /** Optional bounded transport activity evidence (bytes written, a request id). Never used for fencing. */
+    transportActivity?: JSONValue | undefined;
+}>;
+/** A delivery leased to an attempt that has not yet durably begun its send.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryClaimed } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryClaimed;
+ * console.log(record.attemptToken, record.attemptDeadlineAt);
+ * ```
+ */
+export type ApplicationDeliveryClaimed = ApplicationDeliveryBase & ApplicationDeliveryAttemptFields & ApplicationDeliveryLeaseFields & Readonly<{
+    state: 'claimed';
+    availableAt: number;
+}>;
+/**
+ * A delivery whose attempt durably began its send. From here on a lost result
+ * is an unknown outcome, never a safe retry.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryAttempting } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryAttempting;
+ * console.log(record.attemptStartedAt);
+ * ```
+ */
+export type ApplicationDeliveryAttempting = ApplicationDeliveryBase & ApplicationDeliveryAttemptFields & ApplicationDeliveryLeaseFields & Readonly<{
+    state: 'attempting';
+    availableAt: number;
+    attemptStartedAt: number;
+}>;
+/**
+ * An attempting delivery whose cancellation is durably requested and whose
+ * claimant has not yet settled; only the current attempt can report what the
+ * transport did.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryCancelling } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryCancelling;
+ * console.log(record.cancellationRequestedAt);
+ * ```
+ */
+export type ApplicationDeliveryCancelling = ApplicationDeliveryBase & ApplicationDeliveryAttemptFields & ApplicationDeliveryLeaseFields & Readonly<{
+    state: 'cancellation-requested';
+    availableAt: number;
+    attemptStartedAt: number;
+    cancellationRequestedAt: number;
+    cancellationReason?: string | undefined;
+}>;
+/**
+ * A delivery in a terminal disposition. `cleanupPending` is `true` when an
+ * attempt still held it and never settled; `abandonedAttemptToken` names that
+ * attempt. The outbox records that it stopped waiting, never that the transport
+ * stopped.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryTerminalRecord } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryTerminalRecord;
+ * console.log(record.state, record.terminalAt);
+ * ```
+ */
+export type ApplicationDeliveryTerminalRecord = ApplicationDeliveryBase & ApplicationDeliveryAttemptFields & Readonly<{
+    state: ApplicationDeliveryTerminalState;
+    availableAt: number;
+    terminalAt: number;
+    /** Bounded acknowledgement evidence the transport returned. */
+    evidence?: JSONValue | undefined;
+    failure?: ApplicationDeliveryFailure | undefined;
+    cancellationRequestedAt?: number | undefined;
+    cancellationReason?: string | undefined;
+    cleanupPending?: boolean | undefined;
+    abandonedAttemptToken?: string | undefined;
+}>;
+/**
+ * The canonical durable record for one delivery, in whichever state it
+ * currently occupies.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryRecord } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryRecord;
+ * console.log(record.deliveryId, record.state);
+ * ```
+ */
+export type ApplicationDeliveryRecord = ApplicationDeliveryQueued | ApplicationDeliveryRetryScheduled | ApplicationDeliveryClaimed | ApplicationDeliveryAttempting | ApplicationDeliveryCancelling | ApplicationDeliveryTerminalRecord;
+/**
+ * Any record still holding a lease.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryLeasedRecord } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryLeasedRecord;
+ * console.log(record.attemptToken, record.attemptDeadlineAt);
+ * ```
+ */
+export type ApplicationDeliveryLeasedRecord = ApplicationDeliveryClaimed | ApplicationDeliveryAttempting | ApplicationDeliveryCancelling;
+/**
+ * Any record waiting in the due index.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryWaitingRecord } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryWaitingRecord;
+ * console.log(record.availableAt);
+ * ```
+ */
+export type ApplicationDeliveryWaitingRecord = ApplicationDeliveryQueued | ApplicationDeliveryRetryScheduled;
+/**
+ * The per-outbox header holding the listing sequence allocator and the
+ * open-backlog counter enqueue backpressure reads.
+ *
+ * @example
+ * ```ts
+ * import type { OutboxRecord } from '@lostgradient/weft';
+ *
+ * declare const header: OutboxRecord;
+ * console.log(header.nextSequence, header.openCount);
+ * ```
+ */
+export type OutboxRecord = Readonly<{
+    recordVersion: typeof OUTBOX_RECORD_VERSION;
+    namespace: string;
+    ownerId: string;
+    nextSequence: number;
+    /** Deliveries enqueued and not yet terminal. */
+    openCount: number;
+    /** Lifetime enqueues. Never decremented; diagnostic provenance only. */
+    enqueuedCount: number;
+}>;
+/** The idempotency index record binding a retry identity to one enqueued delivery. */
+export type ApplicationDeliveryIdempotencyRecord = Readonly<{
+    recordVersion: typeof OUTBOX_RECORD_VERSION;
+    deliveryId: string;
+    /** The digest of `(destinationRef, kind, payloadDigest)` this key is bound to. */
+    identityDigest: string;
+}>;
+/**
+ * Whether a delivery state is terminal.
+ *
+ * @example
+ * ```ts
+ * import { isApplicationDeliveryTerminalState } from '@lostgradient/weft';
+ *
+ * console.log(isApplicationDeliveryTerminalState('acknowledged')); // true
+ * console.log(isApplicationDeliveryTerminalState('attempting')); // false
+ * ```
+ */
+export declare function isApplicationDeliveryTerminalState(state: string): state is ApplicationDeliveryTerminalState;
+/**
+ * Whether a record still holds an attempt lease.
+ *
+ * @example
+ * ```ts
+ * import { isApplicationDeliveryLeased, type ApplicationDeliveryRecord } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryRecord;
+ * if (isApplicationDeliveryLeased(record)) console.log(record.attemptToken);
+ * ```
+ */
+export declare function isApplicationDeliveryLeased(record: ApplicationDeliveryRecord): record is ApplicationDeliveryLeasedRecord;
+/**
+ * Whether a record is waiting in the due index.
+ *
+ * @example
+ * ```ts
+ * import { isApplicationDeliveryWaiting, type ApplicationDeliveryRecord } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryRecord;
+ * if (isApplicationDeliveryWaiting(record)) console.log(record.availableAt);
+ * ```
+ */
+export declare function isApplicationDeliveryWaiting(record: ApplicationDeliveryRecord): record is ApplicationDeliveryWaitingRecord;
+/**
+ * Whether a record's attempt durably began its send, so a lost result is an
+ * unknown outcome rather than a safe retry.
+ *
+ * @example
+ * ```ts
+ * import { isApplicationDeliveryAttempting, type ApplicationDeliveryRecord } from '@lostgradient/weft';
+ *
+ * declare const record: ApplicationDeliveryRecord;
+ * if (isApplicationDeliveryAttempting(record)) console.log(record.attemptStartedAt);
+ * ```
+ */
+export declare function isApplicationDeliveryAttempting(record: ApplicationDeliveryRecord): record is ApplicationDeliveryAttempting | ApplicationDeliveryCancelling;

package/dist/core/outbox-types.js

@@ -0,0 +1,20 @@
+export const OUTBOX_RECORD_VERSION = 1, APPLICATION_DELIVERY_TERMINAL_STATES = [
+  "acknowledged",
+  "rejected",
+  "cancelled",
+  "unknown-outcome",
+  "dead-lettered"
+];
+const TERMINAL_STATE_SET = new Set(APPLICATION_DELIVERY_TERMINAL_STATES);
+export function isApplicationDeliveryTerminalState(state) {
+  return TERMINAL_STATE_SET.has(state);
+}
+export function isApplicationDeliveryLeased(record) {
+  return record.state === "claimed" || record.state === "attempting" || record.state === "cancellation-requested";
+}
+export function isApplicationDeliveryWaiting(record) {
+  return record.state === "queued" || record.state === "retry-scheduled";
+}
+export function isApplicationDeliveryAttempting(record) {
+  return record.state === "attempting" || record.state === "cancellation-requested";
+}