@lostgradient/weft 0.23.0 → 0.24.0

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

@@ -0,0 +1,64 @@
+import {
+  applicationCommandIdentityFields,
+  computeRetryBackoffMs,
+  nonTerminalCommandRecord,
+  rejectedTransition,
+  succeededTransition
+} from "./mailbox-transition-helpers.js";
+import { requireDerivedInstant } from "./mailbox-validation.js";
+export function recoverExpiredCommand(record, options) {
+  const live = nonTerminalCommandRecord(record);
+  if (live === null)
+    return rejectedTransition("already-terminal");
+  if (options.now >= live.absoluteDeadlineAt)
+    return succeededTransition(deadlineExceededRecord(live, options.now));
+  if (live.state === "accepted" || live.state === "available")
+    return rejectedTransition("not-leased");
+  if (options.now < live.visibilityExpiresAt)
+    return rejectedTransition("not-due");
+  if (live.state === "cancellation-requested")
+    return succeededTransition({
+      ...applicationCommandIdentityFields(live),
+      state: "cancelled",
+      terminalAt: options.now,
+      failure: { reason: "cancelled" },
+      cancellationRequestedAt: live.cancellationRequestedAt,
+      cancellationReason: live.cancellationReason,
+      cleanupPending: !0,
+      abandonedAttemptToken: live.attemptToken
+    });
+  if (live.attempt >= live.maxAttempts)
+    return succeededTransition({
+      ...applicationCommandIdentityFields(live),
+      state: "dead-lettered",
+      terminalAt: options.now,
+      failure: { reason: "attempts-exhausted" },
+      cleanupPending: !0,
+      abandonedAttemptToken: live.attemptToken
+    });
+  return succeededTransition({
+    ...applicationCommandIdentityFields(live),
+    state: "accepted",
+    retryCount: live.retryCount + 1,
+    availableAt: requireDerivedInstant(options.now + computeRetryBackoffMs(live.attempt, options.retryBackoffMs, options.maxRetryBackoffMs), "availableAt")
+  });
+}
+function deadlineExceededRecord(record, now) {
+  const terminal = {
+    ...applicationCommandIdentityFields(record),
+    state: "dead-lettered",
+    terminalAt: now,
+    failure: { reason: "deadline-exceeded" }
+  };
+  if (record.state === "cancellation-requested")
+    return {
+      ...terminal,
+      cancellationRequestedAt: record.cancellationRequestedAt,
+      cancellationReason: record.cancellationReason,
+      cleanupPending: !0,
+      abandonedAttemptToken: record.attemptToken
+    };
+  if (record.state === "claimed")
+    return { ...terminal, cleanupPending: !0, abandonedAttemptToken: record.attemptToken };
+  return terminal;
+}

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

@@ -0,0 +1,138 @@
+/**
+ * Pure conditional-transition functions for the durable application command
+ * mailbox (WFT-84) — one function per legal edge of the mailbox state machine.
+ *
+ * These functions are storage-agnostic. They take the currently decoded
+ * {@link ApplicationCommandRecord} 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.
+ *
+ * That last point matters for correctness, not just tidiness.
+ * `storage.conditionalBatch` compares whole values byte-for-byte, and
+ * `encode(decode(bytes))` is not guaranteed to reproduce the original bytes. The
+ * caller that commits a transition must keep the raw `Uint8Array` it read and
+ * pass those exact bytes as the compare-and-swap `expectedValue`, using
+ * `next` only for what to write.
+ *
+ * The legal edges are:
+ *
+ * ```text
+ * (none)  --admit-->                accepted | available
+ * accepted --release(now>=due)-->   available
+ * accepted --claim(now>=due)-->     claimed
+ * available --claim-->              claimed
+ * claimed --acknowledge-->          applied
+ * claimed --reject(final)-->        rejected
+ * claimed --reject(retry)-->        accepted        (backoff, attempts remain)
+ * claimed --reject(retry)-->        dead-lettered   (attempts exhausted)
+ * claimed --expire-->               accepted | dead-lettered
+ * claimed --cancel-->               cancellation-requested
+ * cancellation-requested --settle--> cancelled
+ * cancellation-requested --expire--> cancelled      (cleanupPending)
+ * accepted | available --cancel-->  cancelled
+ * any non-terminal --deadline-->    dead-lettered
+ * ```
+ *
+ * @module core/mailbox-transitions
+ */
+import type { JSONValue } from './json.ts';
+import { type MailboxTransition } from './mailbox-transition-helpers.ts';
+import type { ApplicationCommandAccepted, ApplicationCommandAvailable, ApplicationCommandCancelling, ApplicationCommandClaimed, ApplicationCommandFailure, ApplicationCommandLeasedRecord, ApplicationCommandRecord, ApplicationCommandTerminalRecord, ApplicationCommandWaitingRecord } from './mailbox-types.ts';
+import { type ValidatedCommandInput } from './mailbox-validation.ts';
+export { computeRetryBackoffMs, isTerminalCommandRecord, nonTerminalCommandRecord, } from './mailbox-transition-helpers.ts';
+export type { MailboxTransition, MailboxTransitionRejection, } from './mailbox-transition-helpers.ts';
+/**
+ * Build the record for a freshly admitted command.
+ *
+ * A command with no delay is admitted straight to `available`; one with a delay
+ * is admitted `accepted` and released later. Both are durable receipts.
+ */
+export declare function createAdmittedCommandRecord(input: ValidatedCommandInput, context: {
+    readonly namespace: string;
+    readonly resourceId: string;
+    readonly commandId: string;
+    readonly sequence: number;
+    readonly now: number;
+}): ApplicationCommandAccepted | ApplicationCommandAvailable;
+/**
+ * Release a delayed command for delivery once its `availableAt` has passed.
+ */
+export declare function releaseWaitingCommand(record: ApplicationCommandRecord, now: number): MailboxTransition<ApplicationCommandAvailable>;
+/**
+ * Lease a waiting command to one attempt.
+ *
+ * The lease never outlives the absolute command deadline: `visibilityExpiresAt`
+ * is clamped to it, so an attempt cannot hold work past the ceiling admission
+ * set.
+ */
+export declare function claimWaitingCommand(record: ApplicationCommandRecord, options: {
+    readonly now: number;
+    readonly attemptToken: string;
+}): MailboxTransition<ApplicationCommandClaimed>;
+/**
+ * Extend a lease and record liveness for the current attempt.
+ *
+ * Renewal is attempt-fenced and clamped: it can never move
+ * `absoluteDeadlineAt`, so an indefinitely renewing claimant still hits the
+ * command ceiling. `lastActivityAt` is transport liveness and stays separate
+ * from `progress`, which is caller-supplied semantic progress and is never used
+ * for fencing.
+ */
+export declare function renewCommandLease(record: ApplicationCommandRecord, options: {
+    readonly attemptToken: string;
+    readonly now: number;
+    readonly progress?: JSONValue | undefined;
+}): MailboxTransition<ApplicationCommandLeasedRecord>;
+/**
+ * Settle a claimed command successfully.
+ *
+ * A command whose cancellation was already requested settles as `cancelled`
+ * rather than `applied`: the claimant finished cleanup, so cleanup is settled,
+ * but the durable cancellation request is not overwritten by a success.
+ *
+ * The caller's `outcome` is still retained on that `cancelled` receipt. A
+ * claimant that completed the work before it observed the cancellation really
+ * did produce a result, and discarding it would lose evidence a reader may need
+ * to decide whether the effect already happened.
+ */
+export declare function acknowledgeCommand(record: ApplicationCommandRecord, options: {
+    readonly attemptToken: string;
+    readonly now: number;
+    readonly outcome?: JSONValue | undefined;
+}): MailboxTransition<ApplicationCommandTerminalRecord>;
+/**
+ * Settle a claimed command as failed, optionally scheduling a retry.
+ *
+ * A retry that still has attempts left returns the command to `accepted` at its
+ * original FIFO position with a backoff; one that does not is dead-lettered
+ * with `attempts-exhausted`. A cancellation-requested command always settles as
+ * `cancelled` — a failed cleanup is still cleanup.
+ */
+export declare function rejectCommand(record: ApplicationCommandRecord, options: {
+    readonly attemptToken: string;
+    readonly now: number;
+    readonly retry: boolean;
+    readonly failure: ApplicationCommandFailure;
+    readonly retryBackoffMs: number;
+    readonly maxRetryBackoffMs: number;
+}): MailboxTransition<ApplicationCommandAccepted | ApplicationCommandTerminalRecord>;
+/**
+ * Record a durable cancellation request.
+ *
+ * An unclaimed command cancels immediately with nothing to clean up. A claimed
+ * one keeps its lease and moves to `cancellation-requested`, so only the
+ * current attempt can settle it. Requesting cancellation twice is idempotent:
+ * the second request rejects with `not-leased` against a record already in
+ * `cancellation-requested`, which the caller reports as the same outcome.
+ */
+export declare function requestCommandCancellation(record: ApplicationCommandRecord, options: {
+    readonly now: number;
+    readonly reason?: string | undefined;
+}): MailboxTransition<ApplicationCommandCancelling | ApplicationCommandTerminalRecord>;
+/**
+ * Whether a waiting or leased record is past its absolute command deadline and
+ * must be terminalized before anything else can happen to it.
+ */
+export declare function isCommandPastDeadline(record: ApplicationCommandRecord, now: number): boolean;
+/** Narrowing helper for callers that already proved a record is waiting. */
+export declare function asWaitingRecord(record: ApplicationCommandRecord): ApplicationCommandWaitingRecord | null;

package/dist/core/mailbox-transitions.js

@@ -0,0 +1,180 @@
+import {
+  applicationCommandIdentityFields,
+  computeRetryBackoffMs,
+  nonTerminalCommandRecord,
+  rejectedTransition,
+  succeededTransition
+} from "./mailbox-transition-helpers.js";
+import { MAILBOX_RECORD_VERSION, isApplicationCommandTerminalState } from "./mailbox-types.js";
+import { requireDerivedInstant } from "./mailbox-validation.js";
+export {
+  computeRetryBackoffMs,
+  isTerminalCommandRecord,
+  nonTerminalCommandRecord
+} from "./mailbox-transition-helpers.js";
+export function createAdmittedCommandRecord(input, context) {
+  const availableAt = requireDerivedInstant(context.now + input.availableAfterMs, "availableAt"), absoluteDeadlineAt = requireDerivedInstant(context.now + input.commandTimeoutMs, "absoluteDeadlineAt"), base = {
+    recordVersion: MAILBOX_RECORD_VERSION,
+    namespace: context.namespace,
+    resourceId: context.resourceId,
+    commandId: context.commandId,
+    sequence: context.sequence,
+    idempotencyKey: input.idempotencyKey,
+    caller: input.caller,
+    target: input.target,
+    kind: input.kind,
+    payload: input.payload,
+    payloadDigest: input.payloadDigest,
+    payloadMediaType: input.payloadMediaType,
+    payloadSchema: input.payloadSchema,
+    causation: input.causation,
+    acceptedAt: context.now,
+    availableAt,
+    absoluteDeadlineAt,
+    maxAttempts: input.maxAttempts,
+    visibilityTimeoutMs: input.visibilityTimeoutMs,
+    generation: 0,
+    attempt: 0,
+    retryCount: 0
+  };
+  return availableAt <= context.now ? { ...base, state: "available" } : { ...base, state: "accepted" };
+}
+export function releaseWaitingCommand(record, now) {
+  const live = nonTerminalCommandRecord(record);
+  if (live === null)
+    return rejectedTransition("already-terminal");
+  if (live.state !== "accepted")
+    return rejectedTransition("not-waiting");
+  if (now < live.availableAt)
+    return rejectedTransition("not-due");
+  return succeededTransition({ ...applicationCommandIdentityFields(live), state: "available" });
+}
+export function claimWaitingCommand(record, options) {
+  const live = nonTerminalCommandRecord(record);
+  if (live === null)
+    return rejectedTransition("already-terminal");
+  if (live.state !== "accepted" && live.state !== "available")
+    return rejectedTransition("not-waiting");
+  if (options.now < live.availableAt)
+    return rejectedTransition("not-due");
+  if (options.now >= live.absoluteDeadlineAt)
+    return rejectedTransition("deadline-exceeded");
+  return succeededTransition({
+    ...applicationCommandIdentityFields(live),
+    state: "claimed",
+    attempt: live.attempt + 1,
+    firstClaimedAt: live.firstClaimedAt ?? options.now,
+    attemptToken: options.attemptToken,
+    claimedAt: options.now,
+    visibilityExpiresAt: Math.min(options.now + live.visibilityTimeoutMs, live.absoluteDeadlineAt),
+    lastActivityAt: options.now
+  });
+}
+function checkCurrentAttempt(record, attemptToken, now) {
+  if (isApplicationCommandTerminalState(record.state))
+    return { ok: !1, reason: "already-terminal" };
+  if (record.state !== "claimed" && record.state !== "cancellation-requested")
+    return { ok: !1, reason: "not-leased" };
+  if (record.attemptToken !== attemptToken)
+    return { ok: !1, reason: "stale-attempt" };
+  if (now >= record.absoluteDeadlineAt)
+    return { ok: !1, reason: "deadline-exceeded" };
+  return { ok: !0, leased: record };
+}
+export function renewCommandLease(record, options) {
+  const checked = checkCurrentAttempt(record, options.attemptToken, options.now);
+  if (!checked.ok)
+    return rejectedTransition(checked.reason);
+  const { leased } = checked, renewed = {
+    ...leased,
+    generation: leased.generation + 1,
+    lastActivityAt: options.now,
+    visibilityExpiresAt: Math.min(options.now + leased.visibilityTimeoutMs, leased.absoluteDeadlineAt),
+    progress: options.progress === void 0 ? leased.progress : options.progress
+  };
+  return succeededTransition(renewed);
+}
+export function acknowledgeCommand(record, options) {
+  const checked = checkCurrentAttempt(record, options.attemptToken, options.now);
+  if (!checked.ok)
+    return rejectedTransition(checked.reason);
+  const { leased } = checked, cancelling = leased.state === "cancellation-requested";
+  return succeededTransition({
+    ...applicationCommandIdentityFields(leased),
+    state: cancelling ? "cancelled" : "applied",
+    terminalAt: options.now,
+    outcome: options.outcome,
+    failure: cancelling ? { reason: "cancelled" } : void 0,
+    cancellationRequestedAt: cancelling ? leased.cancellationRequestedAt : void 0,
+    cancellationReason: cancelling ? leased.cancellationReason : void 0,
+    cleanupPending: cancelling ? !1 : void 0
+  });
+}
+export function rejectCommand(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 succeededTransition({
+      ...applicationCommandIdentityFields(leased),
+      state: "cancelled",
+      terminalAt: options.now,
+      failure: { reason: "cancelled" },
+      cancellationRequestedAt: leased.cancellationRequestedAt,
+      cancellationReason: leased.cancellationReason,
+      cleanupPending: !1
+    });
+  if (!options.retry)
+    return succeededTransition({
+      ...applicationCommandIdentityFields(leased),
+      state: "rejected",
+      terminalAt: options.now,
+      failure: options.failure
+    });
+  if (leased.attempt >= leased.maxAttempts)
+    return succeededTransition({
+      ...applicationCommandIdentityFields(leased),
+      state: "dead-lettered",
+      terminalAt: options.now,
+      failure: { ...options.failure, reason: "attempts-exhausted" }
+    });
+  return succeededTransition({
+    ...applicationCommandIdentityFields(leased),
+    state: "accepted",
+    retryCount: leased.retryCount + 1,
+    availableAt: requireDerivedInstant(options.now + computeRetryBackoffMs(leased.attempt, options.retryBackoffMs, options.maxRetryBackoffMs), "availableAt")
+  });
+}
+export function requestCommandCancellation(record, options) {
+  const live = nonTerminalCommandRecord(record);
+  if (live === null)
+    return rejectedTransition("already-terminal");
+  if (options.now >= live.absoluteDeadlineAt)
+    return rejectedTransition("deadline-exceeded");
+  if (live.state === "cancellation-requested")
+    return rejectedTransition("not-leased");
+  if (live.state === "claimed")
+    return succeededTransition({
+      ...live,
+      generation: live.generation + 1,
+      state: "cancellation-requested",
+      cancellationRequestedAt: options.now,
+      cancellationReason: options.reason
+    });
+  return succeededTransition({
+    ...applicationCommandIdentityFields(live),
+    state: "cancelled",
+    terminalAt: options.now,
+    failure: { reason: "cancelled" },
+    cancellationRequestedAt: options.now,
+    cancellationReason: options.reason,
+    cleanupPending: !1
+  });
+}
+export function isCommandPastDeadline(record, now) {
+  return !isApplicationCommandTerminalState(record.state) && now >= record.absoluteDeadlineAt;
+}
+export function asWaitingRecord(record) {
+  return record.state === "accepted" || record.state === "available" ? record : null;
+}