@lostgradient/weft 0.23.1 → 0.24.0

package/dist/core/outbox-storage.js

@@ -0,0 +1,127 @@
+import { encodeStorageKeyComponent, KEYS } from "../storage/interface.js";
+import {
+  commitApplicationTransition
+} from "./application-primitive-commit.js";
+import {
+  decodeApplicationDeliveryRecord,
+  encodeApplicationDeliveryRecord
+} from "./outbox-codec.js";
+import {
+  decodeApplicationDeliveryEntry,
+  decodeApplicationDeliveryIdempotencyRecord,
+  decodeOutboxRecord,
+  encodeApplicationDeliveryEntry,
+  encodeOutboxRecord
+} from "./outbox-index-codec.js";
+import {
+  isApplicationDeliveryTerminalState,
+  isApplicationDeliveryWaiting,
+  OUTBOX_RECORD_VERSION
+} from "./outbox-types.js";
+import { PersistedDataCorruptError } from "./persisted-data-incompatible-error.js";
+export function createOutboxKeys(namespace, ownerId) {
+  return {
+    header: KEYS.applicationOutbox(namespace, ownerId),
+    sinkProbe: (nonce) => KEYS.applicationOutboxSinkProbe(namespace, ownerId, nonce),
+    deliveryPrefix: KEYS.applicationDeliveryPrefix(namespace, ownerId),
+    delivery: (deliveryId) => KEYS.applicationDelivery(namespace, ownerId, deliveryId),
+    duePrefix: KEYS.applicationDeliveryDuePrefix(namespace, ownerId),
+    due: (availableAt, deliveryId) => KEYS.applicationDeliveryDue(namespace, ownerId, availableAt, deliveryId),
+    bySequencePrefix: KEYS.applicationDeliveryBySequencePrefix(namespace, ownerId),
+    bySequence: (sequence) => KEYS.applicationDeliveryBySequence(namespace, ownerId, sequence),
+    idempotency: (key) => KEYS.applicationDeliveryIdempotency(namespace, ownerId, key),
+    terminalPrefix: KEYS.applicationDeliveryTerminalPrefix(namespace, ownerId),
+    terminal: (terminalAt, deliveryId) => KEYS.applicationDeliveryTerminal(namespace, ownerId, terminalAt, deliveryId)
+  };
+}
+export function emptyOutboxRecord(namespace, ownerId) {
+  return {
+    recordVersion: OUTBOX_RECORD_VERSION,
+    namespace,
+    ownerId,
+    nextSequence: 0,
+    openCount: 0,
+    enqueuedCount: 0
+  };
+}
+export async function loadOutboxHeader(storage, keys, namespace, ownerId) {
+  const bytes = await storage.get(keys.header);
+  if (bytes === null)
+    return { record: emptyOutboxRecord(namespace, ownerId), bytes: null };
+  return { record: decodeOutboxRecord(bytes, keys.header), bytes };
+}
+export async function loadDelivery(storage, keys, deliveryId) {
+  const key = keys.delivery(deliveryId), bytes = await storage.get(key);
+  if (bytes === null)
+    return null;
+  return { record: decodeApplicationDeliveryRecord(bytes, key), bytes };
+}
+export async function loadDeliveryIdempotencyBinding(storage, keys, idempotencyKey) {
+  const key = keys.idempotency(idempotencyKey), bytes = await storage.get(key);
+  if (bytes === null)
+    return null;
+  return { record: decodeApplicationDeliveryIdempotencyRecord(bytes, key), bytes };
+}
+export async function loadDueHead(storage, keys, limit) {
+  const entries = [];
+  for await (const [key, value] of storage.scan(keys.duePrefix, { limit })) {
+    const deliveryId = decodeApplicationDeliveryEntry(value, key);
+    if (!key.endsWith(`:${encodeStorageKeyComponent(deliveryId)}`))
+      throw new PersistedDataCorruptError(key);
+    entries.push({ key, bytes: value, deliveryId });
+  }
+  return entries;
+}
+export function indexOperationsFor(keys, previous, next) {
+  return [
+    ...dueIndexOperations(keys, previous, next),
+    ...terminalIndexOperations(keys, previous, next)
+  ];
+}
+function moveIndexEntry(before, after, deliveryId) {
+  if (before === after)
+    return [];
+  const operations = [];
+  if (before !== null)
+    operations.push({ type: "delete", key: before });
+  if (after !== null)
+    operations.push({ type: "put", key: after, value: encodeApplicationDeliveryEntry(deliveryId) });
+  return operations;
+}
+function dueIndexOperations(keys, previous, next) {
+  const before = previous !== null && isApplicationDeliveryWaiting(previous) ? keys.due(previous.availableAt, previous.deliveryId) : null, after = isApplicationDeliveryWaiting(next) ? keys.due(next.availableAt, next.deliveryId) : null;
+  return moveIndexEntry(before, after, next.deliveryId);
+}
+function terminalIndexOperations(keys, previous, next) {
+  const before = previous !== null && isTerminalRecord(previous) ? keys.terminal(previous.terminalAt, previous.deliveryId) : null, after = isTerminalRecord(next) ? keys.terminal(next.terminalAt, next.deliveryId) : null;
+  return moveIndexEntry(before, after, next.deliveryId);
+}
+function isTerminalRecord(record) {
+  return isApplicationDeliveryTerminalState(record.state);
+}
+export function commitOutboxTransition(storage, events, plan) {
+  return commitApplicationTransition(storage, events, plan, "application outbox");
+}
+export function planDeliveryTransition(keys, options) {
+  return {
+    sinkProbeKey: keys.sinkProbe(crypto.randomUUID()),
+    conditions: [
+      { key: keys.delivery(options.next.deliveryId), expectedValue: options.expectedBytes },
+      ...options.extraConditions ?? []
+    ],
+    operations: [
+      {
+        type: "put",
+        key: keys.delivery(options.next.deliveryId),
+        value: encodeApplicationDeliveryRecord(options.next)
+      },
+      ...indexOperationsFor(keys, options.previous, options.next),
+      ...options.extraOperations ?? []
+    ],
+    event: options.event,
+    now: options.now
+  };
+}
+export function headerOperation(keys, record) {
+  return { type: "put", key: keys.header, value: encodeOutboxRecord(record) };
+}

package/dist/core/outbox-transition-helpers.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The primitives every outbox transition shares (WFT-85): the
+ * rejection vocabulary, the transition result shape, non-terminal narrowing,
+ * identity-field carry-over, and retry scheduling.
+ *
+ * Extracted so `outbox-transitions.ts` and
+ * `outbox-transitions-recovery.ts` can both use them without
+ * importing each other.
+ *
+ * @module core/outbox-transition-helpers
+ */
+import { computeRetryBackoffMs } from './application-primitive-timing.ts';
+import type { ApplicationDeliveryFailure, ApplicationDeliveryLeasedRecord, ApplicationDeliveryRecord, ApplicationDeliveryRetryScheduled, ApplicationDeliveryTerminalRecord, ApplicationDeliveryWaitingRecord } from './outbox-types.ts';
+export { computeRetryBackoffMs };
+/**
+ * Why a proposed transition is illegal. Stable and low-cardinality, so callers
+ * can map each reason onto a discriminated result without string matching.
+ */
+export type OutboxTransitionRejection = 'stale-attempt' | 'not-leased' | 'not-waiting' | 'not-due' | 'not-attempting' | 'deadline-exceeded' | 'already-terminal' | 'cancellation-requested' | 'not-applicable';
+/** The outcome of a proposed transition: the record to persist, or why the edge is illegal. */
+export type OutboxTransition<TNext> = {
+    readonly ok: true;
+    readonly next: TNext;
+} | {
+    readonly ok: false;
+    readonly reason: OutboxTransitionRejection;
+};
+export declare function rejectedTransition<TNext>(reason: OutboxTransitionRejection): OutboxTransition<TNext>;
+export declare function succeededTransition<TNext>(next: TNext): OutboxTransition<TNext>;
+/** Narrow a record to a terminal disposition. */
+export declare function isTerminalDeliveryRecord(record: ApplicationDeliveryRecord): record is ApplicationDeliveryTerminalRecord;
+/** Narrow a record to the five non-terminal states, or `null`. */
+export declare function nonTerminalDeliveryRecord(record: ApplicationDeliveryRecord): ApplicationDeliveryWaitingRecord | ApplicationDeliveryLeasedRecord | null;
+/** Strip the state-specific fields so a transition rebuilds a record from identity alone. */
+export declare function applicationDeliveryIdentityFields(record: ApplicationDeliveryRecord): {
+    readonly recordVersion: 1;
+    readonly namespace: string;
+    readonly ownerId: string;
+    readonly deliveryId: string;
+    readonly sequence: number;
+    readonly idempotencyKey: string | undefined;
+    readonly destinationRef: string;
+    readonly credentialRef: string | undefined;
+    readonly kind: string;
+    readonly payload: import("./mailbox-types.ts").ApplicationCommandPayload;
+    readonly payloadDigest: string;
+    readonly payloadMediaType: string | undefined;
+    readonly payloadSchema: string | undefined;
+    readonly causation: Readonly<{
+        correlationId?: string | undefined;
+        causationId?: string | undefined;
+        traceparent?: string | undefined;
+    }> | undefined;
+    readonly externalIdempotencyKey: string | undefined;
+    readonly unknownOutcomePolicy: import("./outbox-types.ts").ApplicationDeliveryUnknownOutcomePolicy;
+    readonly enqueuedAt: number;
+    readonly maxAttempts: number;
+    readonly visibilityTimeoutMs: number;
+    readonly attemptTimeoutMs: number;
+    readonly generation: number;
+    readonly attempt: number;
+    readonly retryCount: number;
+    readonly firstClaimedAt: number | undefined;
+    readonly availableAt: number;
+};
+/** Backoff policy shared by every reschedule. */
+export type RetryPolicy = {
+    readonly retryBackoffMs: number;
+    readonly maxRetryBackoffMs: number;
+};
+/**
+ * Reschedule a leased delivery for another attempt, or dead-letter it when the
+ * attempt budget is spent.
+ *
+ * The delay is the outbox's own backoff or the transport's suggestion,
+ * whichever is longer: a transport asking for more time is honoured, one
+ * asking for less is not allowed to defeat the configured backoff.
+ */
+export declare function rescheduleOrDeadLetter(leased: ApplicationDeliveryLeasedRecord, options: {
+    readonly now: number;
+    readonly failure: ApplicationDeliveryFailure;
+    readonly retryAfterMs?: number | undefined;
+} & RetryPolicy): ApplicationDeliveryRetryScheduled | ApplicationDeliveryTerminalRecord;

package/dist/core/outbox-transition-helpers.js

@@ -0,0 +1,63 @@
+import { computeRetryBackoffMs } from "./application-primitive-timing.js";
+import { requireDerivedInstant } from "./outbox-guards.js";
+import { OUTBOX_RECORD_VERSION, isApplicationDeliveryTerminalState } from "./outbox-types.js";
+
+export { computeRetryBackoffMs };
+export function rejectedTransition(reason) {
+  return { ok: !1, reason };
+}
+export function succeededTransition(next) {
+  return { ok: !0, next };
+}
+export function isTerminalDeliveryRecord(record) {
+  return isApplicationDeliveryTerminalState(record.state);
+}
+export function nonTerminalDeliveryRecord(record) {
+  return isTerminalDeliveryRecord(record) ? null : record;
+}
+export function applicationDeliveryIdentityFields(record) {
+  return {
+    recordVersion: OUTBOX_RECORD_VERSION,
+    namespace: record.namespace,
+    ownerId: record.ownerId,
+    deliveryId: record.deliveryId,
+    sequence: record.sequence,
+    idempotencyKey: record.idempotencyKey,
+    destinationRef: record.destinationRef,
+    credentialRef: record.credentialRef,
+    kind: record.kind,
+    payload: record.payload,
+    payloadDigest: record.payloadDigest,
+    payloadMediaType: record.payloadMediaType,
+    payloadSchema: record.payloadSchema,
+    causation: record.causation,
+    externalIdempotencyKey: record.externalIdempotencyKey,
+    unknownOutcomePolicy: record.unknownOutcomePolicy,
+    enqueuedAt: record.enqueuedAt,
+    maxAttempts: record.maxAttempts,
+    visibilityTimeoutMs: record.visibilityTimeoutMs,
+    attemptTimeoutMs: record.attemptTimeoutMs,
+    generation: record.generation + 1,
+    attempt: record.attempt,
+    retryCount: record.retryCount,
+    firstClaimedAt: record.firstClaimedAt,
+    availableAt: record.availableAt
+  };
+}
+export function rescheduleOrDeadLetter(leased, options) {
+  if (leased.attempt >= leased.maxAttempts)
+    return {
+      ...applicationDeliveryIdentityFields(leased),
+      state: "dead-lettered",
+      terminalAt: options.now,
+      failure: { ...options.failure, reason: "attempts-exhausted" }
+    };
+  const backoff = computeRetryBackoffMs(leased.attempt, options.retryBackoffMs, options.maxRetryBackoffMs);
+  return {
+    ...applicationDeliveryIdentityFields(leased),
+    state: "retry-scheduled",
+    retryCount: leased.retryCount + 1,
+    availableAt: requireDerivedInstant(options.now + Math.max(backoff, options.retryAfterMs ?? 0), "availableAt"),
+    lastFailure: options.failure
+  };
+}

package/dist/core/outbox-transitions-recovery.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The time-driven recovery transition for the application delivery outbox
+ * (WFT-85): what happens to a lease nobody renewed.
+ *
+ * The state the lease expired in decides everything. A `claimed` lease never
+ * called the transport, so the delivery is safe to reschedule (or dead-letter
+ * when its attempt budget is spent). An `attempting` or cancellation-requested
+ * lease may have sent, so its outcome is unknown and the delivery's own
+ * unknown-outcome policy decides — never a blind retry.
+ *
+ * @module core/outbox-transitions-recovery
+ */
+import { type OutboxTransition, type RetryPolicy } from './outbox-transition-helpers.ts';
+import type { ApplicationDeliveryRecord, ApplicationDeliveryRetryScheduled, ApplicationDeliveryTerminalRecord } from './outbox-types.ts';
+/**
+ * Whether a leased record's lease has lapsed: its visibility expired or its
+ * attempt deadline passed, whichever came first.
+ */
+export declare function isDeliveryLeaseExpired(record: ApplicationDeliveryRecord, now: number): boolean;
+/**
+ * Recover a delivery whose lease lapsed.
+ *
+ * `cleanupPending: true` and `abandonedAttemptToken` are written whenever the
+ * lease is abandoned rather than settled by its holder, in every disposition:
+ * the outbox stopped waiting for that attempt, which is not a claim that the
+ * attempt stopped.
+ */
+export declare function recoverExpiredDelivery(record: ApplicationDeliveryRecord, options: {
+    readonly now: number;
+} & RetryPolicy): OutboxTransition<ApplicationDeliveryRetryScheduled | ApplicationDeliveryTerminalRecord>;

package/dist/core/outbox-transitions-recovery.js

@@ -0,0 +1,42 @@
+import {
+  nonTerminalDeliveryRecord,
+  rejectedTransition,
+  rescheduleOrDeadLetter,
+  succeededTransition
+} from "./outbox-transition-helpers.js";
+import { applyUnknownOutcomePolicy } from "./outbox-transitions.js";
+export function isDeliveryLeaseExpired(record, now) {
+  if (record.state !== "claimed" && record.state !== "attempting" && record.state !== "cancellation-requested")
+    return !1;
+  return now >= record.visibilityExpiresAt || now >= record.attemptDeadlineAt;
+}
+export function recoverExpiredDelivery(record, options) {
+  const live = nonTerminalDeliveryRecord(record);
+  if (live === null)
+    return rejectedTransition("already-terminal");
+  if (live.state === "queued" || live.state === "retry-scheduled")
+    return rejectedTransition("not-leased");
+  if (!isDeliveryLeaseExpired(live, options.now))
+    return rejectedTransition("not-due");
+  if (live.state === "claimed") {
+    const next = rescheduleOrDeadLetter(live, {
+      ...options,
+      failure: { reason: "retryable", message: "The attempt lease expired before the send began." }
+    });
+    if (next.state === "retry-scheduled")
+      return succeededTransition(next);
+    return succeededTransition({
+      ...next,
+      cleanupPending: !0,
+      abandonedAttemptToken: live.attemptToken
+    });
+  }
+  return succeededTransition(applyUnknownOutcomePolicy(live, {
+    ...options,
+    failure: {
+      reason: "unknown-outcome",
+      message: "The attempt lease expired after the send began; the transport result is unknown."
+    },
+    abandonedAttemptToken: live.attemptToken
+  }));
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Pure conditional-transition functions for the durable application delivery
+ * outbox (WFT-85) — one function per legal edge of the outbox state machine.
+ *
+ * These functions are storage-agnostic. They take the currently decoded
+ * {@link ApplicationDeliveryRecord} and proposed inputs and return either the
+ * next record to persist or a stable rejection reason. They never read or write
+ * storage and never see encoded bytes; the caller that commits a transition
+ * keeps the raw bytes it read as the compare-and-swap `expectedValue`.
+ *
+ * The legal edges are:
+ *
+ * ```text
+ * (none)  --enqueue-->                       queued
+ * queued | retry-scheduled --claim(due)-->   claimed
+ * claimed --begin-->                         attempting
+ * claimed | attempting | cancel-req --heartbeat--> (same state, visibility extended)
+ * attempting --settle(acknowledged)-->       acknowledged
+ * attempting --settle(rejected)-->           rejected
+ * attempting --settle(retryable)-->          retry-scheduled | dead-lettered
+ * attempting --settle(unknown)-->            unknown-outcome | dead-lettered | retry-scheduled
+ * cancellation-requested --settle(ack)-->    acknowledged      (the effect happened)
+ * cancellation-requested --settle(other)-->  cancelled | unknown-outcome | dead-lettered
+ * queued | retry-scheduled | claimed --cancel--> cancelled
+ * attempting --cancel-->                     cancellation-requested
+ * claimed --expire-->                        retry-scheduled | dead-lettered   (recovery)
+ * attempting | cancel-req --expire-->        unknown-outcome | dead-lettered | retry-scheduled
+ * unknown-outcome | dead-lettered | rejected --retry--> queued          (operator)
+ * unknown-outcome --deadLetter-->            dead-lettered                     (operator)
+ * ```
+ *
+ * @module core/outbox-transitions
+ */
+import type { JSONValue } from './json.ts';
+import { type OutboxTransition, type RetryPolicy } from './outbox-transition-helpers.ts';
+import type { ApplicationDeliveryAttempting, ApplicationDeliveryCancelling, ApplicationDeliveryClaimed, ApplicationDeliveryLeasedRecord, ApplicationDeliveryQueued, ApplicationDeliveryRecord, ApplicationDeliveryRetryScheduled, ApplicationDeliveryTerminalRecord } from './outbox-types.ts';
+import type { ValidatedDeliveryInput, ValidatedOutcome } from './outbox-validation.ts';
+export { isTerminalDeliveryRecord, nonTerminalDeliveryRecord, } from './outbox-transition-helpers.ts';
+export type { OutboxTransition, OutboxTransitionRejection } from './outbox-transition-helpers.ts';
+/** Build the record for a freshly enqueued delivery. */
+export declare function createEnqueuedDeliveryRecord(input: ValidatedDeliveryInput, context: {
+    readonly namespace: string;
+    readonly ownerId: string;
+    readonly deliveryId: string;
+    readonly sequence: number;
+    readonly now: number;
+}): ApplicationDeliveryQueued;
+/**
+ * Lease a waiting delivery to one attempt.
+ *
+ * The attempt deadline is fixed here, at `now + attemptTimeoutMs`, and nothing
+ * later moves it. Visibility starts at the lesser of the renewal window and
+ * that deadline.
+ */
+export declare function claimWaitingDelivery(record: ApplicationDeliveryRecord, options: {
+    readonly now: number;
+    readonly attemptToken: string;
+}): OutboxTransition<ApplicationDeliveryClaimed>;
+/**
+ * Durably mark that the current attempt is about to call the transport.
+ *
+ * This is the edge that makes recovery honest: a lease that expires in
+ * `claimed` provably sent nothing and is safe to retry, while one that expires
+ * in `attempting` may have, and follows the unknown-outcome policy.
+ */
+export declare function beginDeliveryAttempt(record: ApplicationDeliveryRecord, options: {
+    readonly attemptToken: string;
+    readonly now: number;
+}): OutboxTransition<ApplicationDeliveryAttempting>;
+/**
+ * Record liveness for the current attempt and extend its visibility, clamped
+ * to the fixed attempt deadline. `transportActivity` is evidence of transport
+ * progress — bytes written, a request id — and is never fencing.
+ */
+export declare function heartbeatDeliveryAttempt(record: ApplicationDeliveryRecord, options: {
+    readonly attemptToken: string;
+    readonly now: number;
+    readonly transportActivity?: JSONValue | undefined;
+}): OutboxTransition<ApplicationDeliveryLeasedRecord>;
+/**
+ * Apply the unknown-outcome policy to a leased delivery whose transport result
+ * is lost. Shared by settlement (adapter reported `unknown`) and recovery (the
+ * lease expired in `attempting`).
+ *
+ * A delivery whose cancellation was requested is never retried: `park` and
+ * `retry-with-idempotency` both park it, because a retry would send work the
+ * caller asked to stop. `abandonedAttemptToken` is set by recovery only.
+ */
+export declare function applyUnknownOutcomePolicy(leased: ApplicationDeliveryLeasedRecord, options: {
+    readonly now: number;
+    readonly failure: {
+        readonly reason: 'unknown-outcome';
+        readonly message?: string | undefined;
+    };
+    readonly abandonedAttemptToken?: string | undefined;
+} & RetryPolicy): ApplicationDeliveryRetryScheduled | ApplicationDeliveryTerminalRecord;
+/**
+ * Settle the current attempt on what the transport reported.
+ *
+ * Only an `attempting` (or cancellation-requested) delivery can settle: a
+ * `claimed` one never called the transport, so it has no outcome to record.
+ * An acknowledgement always wins, even after cancellation was requested — the
+ * effect happened and the receipt must say so. Any other outcome on a
+ * cancelling delivery honours the cancellation: `cancelled` when nothing was
+ * confirmed, the unknown-outcome policy when the result was lost.
+ */
+export declare function settleDeliveryAttempt(record: ApplicationDeliveryRecord, options: {
+    readonly attemptToken: string;
+    readonly now: number;
+    readonly outcome: ValidatedOutcome;
+} & RetryPolicy): OutboxTransition<ApplicationDeliveryRetryScheduled | ApplicationDeliveryTerminalRecord>;
+/**
+ * Record a durable cancellation request.
+ *
+ * A waiting or merely claimed delivery cancels at once: nothing has been sent.
+ * (The claimant's `attempting` commit then loses its compare-and-swap and it
+ * re-reads a terminal record.) An attempting delivery keeps its lease and moves
+ * to `cancellation-requested`, so only the current attempt can settle it.
+ * Requesting cancellation twice rejects with `not-leased` against a record
+ * already in `cancellation-requested`, which the caller reports as the same
+ * outcome.
+ */
+export declare function requestDeliveryCancellation(record: ApplicationDeliveryRecord, options: {
+    readonly now: number;
+    readonly reason?: string | undefined;
+}): OutboxTransition<ApplicationDeliveryCancelling | ApplicationDeliveryTerminalRecord>;
+/**
+ * Operator retry: return a parked, dead-lettered, or rejected delivery to the
+ * due index with at least one more attempt to spend.
+ *
+ * A budget the delivery never used up — a permanent rejection on its first
+ * attempt of five, say — is kept, so the reopened delivery may retry on its
+ * own up to `maxAttempts`; a spent budget is raised to `attempt + 1`, so the
+ * delivery can be claimed exactly once more, and a second operator retry
+ * grants one more again. The record's provenance (`attempt`, `retryCount`) is
+ * preserved.
+ */
+export declare function retryDeliveryByOperator(record: ApplicationDeliveryRecord, options: {
+    readonly now: number;
+}): OutboxTransition<ApplicationDeliveryQueued>;
+/** Operator dead-letter: close a parked `unknown-outcome` delivery for good. */
+export declare function deadLetterDeliveryByOperator(record: ApplicationDeliveryRecord, options: {
+    readonly now: number;
+    readonly reason?: string | undefined;
+}): OutboxTransition<ApplicationDeliveryTerminalRecord>;