@lostgradient/weft 0.23.0 → 0.24.0

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

@@ -0,0 +1,251 @@
+/**
+ * Claim, settlement, cancellation, and maintenance result types for the durable
+ * application command mailbox (WFT-84).
+ *
+ * Split from `mailbox-contract.ts` only to keep both files under
+ * this repository's file-size ceiling; every type here is re-exported from
+ * there, so callers still have one import path.
+ *
+ * The same two rules shape these signatures. Expected outcomes are
+ * discriminated results rather than exceptions — a stale attempt token, an
+ * already-terminal command, and an unknown command id are all ordinary control
+ * flow. And no read here consumes delivery: a snapshot never claims or starts
+ * work.
+ *
+ * @module core/mailbox-claims
+ */
+import type { ApplicationCommandReceipt } from './mailbox-contract.ts';
+/**
+ * A payload handed to a claimant.
+ *
+ * For an inline payload the mailbox recomputes the digest at claim time and
+ * fails closed on a mismatch, so `verified` is `true`. For a reference payload
+ * Weft holds only the locator and the caller-supplied digest and never
+ * dereferences either, so `verified` is `false` and verification is the
+ * consumer's job.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandClaimedPayload } from '@lostgradient/weft';
+ *
+ * declare const payload: ApplicationCommandClaimedPayload;
+ * if (payload.form === 'inline') console.log(payload.verified); // true
+ * ```
+ */
+export type ApplicationCommandClaimedPayload = {
+    readonly form: 'inline';
+    readonly value: unknown;
+    readonly digest: string;
+    readonly verified: true;
+} | {
+    readonly form: 'reference';
+    readonly reference: string;
+    readonly digest: string;
+    readonly byteLength?: number | undefined;
+    readonly verified: false;
+};
+/**
+ * An open lease on one command.
+ *
+ * `signal` aborts when cancellation is requested in this process, when the
+ * lease is released, or when the mailbox is disposed. It is process-local: a
+ * claimant in another process learns about cancellation from
+ * `renew()`'s `cancellationRequested` flag instead.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandClaim } from '@lostgradient/weft';
+ *
+ * declare const claim: ApplicationCommandClaim;
+ * console.log(claim.attemptToken, claim.signal.aborted);
+ * ```
+ */
+export type ApplicationCommandClaim = Readonly<{
+    receipt: ApplicationCommandReceipt;
+    payload: ApplicationCommandClaimedPayload;
+    /** Opaque fencing token. Every later mutation from this attempt must present it. */
+    attemptToken: string;
+    attempt: number;
+    visibilityExpiresAt: number;
+    absoluteDeadlineAt: number;
+    /** Attempt-scoped abort signal for an in-process claimant. */
+    signal: AbortSignal;
+}>;
+/**
+ * The outcome of asking for work.
+ *
+ * `held` means the FIFO head exists but is not due yet. This mailbox preserves
+ * strict FIFO order, so a later command never overtakes a delayed head.
+ *
+ * @example
+ * ```ts
+ * import type { MailboxClaimResult } from '@lostgradient/weft';
+ *
+ * declare const result: MailboxClaimResult;
+ * if (result.status === 'claimed') console.log(result.claim.attemptToken);
+ * ```
+ */
+export type MailboxClaimResult = {
+    readonly status: 'claimed';
+    readonly claim: ApplicationCommandClaim;
+} | {
+    readonly status: 'empty';
+} | {
+    readonly status: 'held';
+    readonly availableAt: number;
+};
+/** Result of renewing a lease and reporting liveness.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandRenewalResult } from '@lostgradient/weft';
+ *
+ * declare const result: ApplicationCommandRenewalResult;
+ * if (result.status === 'renewed' && result.cancellationRequested) console.log('wind down');
+ * ```
+ */
+export type ApplicationCommandRenewalResult = {
+    readonly status: 'renewed';
+    readonly visibilityExpiresAt: number;
+    /** True once cancellation is durably requested — the cross-process cancellation channel. */
+    readonly cancellationRequested: boolean;
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'stale';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    /** The absolute command deadline passed; no attempt may extend or settle it. */
+    readonly status: 'deadline-exceeded';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * Result of settling a claimed command.
+ *
+ * `deadline-exceeded` is reported separately from `stale` on purpose: `stale`
+ * means another attempt owns the command and this one should stop, while
+ * `deadline-exceeded` means the command itself is over and no attempt will
+ * settle it. Maintenance dead-letters the record.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandSettleResult } from '@lostgradient/weft';
+ *
+ * declare const result: ApplicationCommandSettleResult;
+ * if (result.status === 'settled') console.log(result.receipt.state);
+ * ```
+ */
+export type ApplicationCommandSettleResult = {
+    readonly status: 'settled';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'retrying';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'stale';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'deadline-exceeded';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * The outcome of requesting cancellation.
+ *
+ * The four dispositions are distinct on purpose: an unclaimed command cancels
+ * immediately with nothing to clean up, a claimed one records the request and
+ * leaves the lease alone, an already-terminal one is reported as such without
+ * being rewritten, and an unknown command id is never confused with any of
+ * those.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandCancellationResult } from '@lostgradient/weft';
+ *
+ * declare const result: ApplicationCommandCancellationResult;
+ * if (result.status === 'requested') console.log(result.cleanupPending); // true
+ * ```
+ */
+export type ApplicationCommandCancellationResult = {
+    readonly status: 'cancelled';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'requested';
+    readonly receipt: ApplicationCommandReceipt;
+    /** Always true: an attempt still holds the command and has not settled. */
+    readonly cleanupPending: true;
+} | {
+    readonly status: 'already-terminal';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * The bounded outcome of waiting for a cancelled command's claimant to finish.
+ *
+ * A `pending` status means the mailbox stopped waiting — never that the handler
+ * stopped.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationCommandCleanupResult } from '@lostgradient/weft';
+ *
+ * declare const cleanup: ApplicationCommandCleanupResult;
+ * console.log(cleanup.status === 'pending'); // the mailbox stopped waiting
+ * ```
+ */
+export type ApplicationCommandCleanupResult = {
+    readonly status: 'settled';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'pending';
+    readonly receipt: ApplicationCommandReceipt;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * What one maintenance pass did. Counts only — deliberately low-cardinality.
+ *
+ * @example
+ * ```ts
+ * import type { MailboxMaintenanceReport } from '@lostgradient/weft';
+ *
+ * declare const report: MailboxMaintenanceReport;
+ * console.log(report.released, report.reclaimed, report.deadLettered);
+ * ```
+ */
+export type MailboxMaintenanceReport = Readonly<{
+    /** `accepted` records whose `availableAt` passed and are now `available`. */
+    released: number;
+    /** Expired leases returned to the delivery index at their original FIFO position. */
+    reclaimed: number;
+    /** Commands terminalized for exhausted attempts or a passed absolute deadline. */
+    deadLettered: number;
+    /** Cancelled commands whose abandoned lease expired. */
+    cancelled: number;
+    /** Terminal receipts deleted by the retention sweep. */
+    retired: number;
+}>;
+/**
+ * Options for the abortable wait for new available work.
+ *
+ * `timeoutMs` defaults to `0`: with no options the wait checks once and returns
+ * immediately instead of blocking.
+ *
+ * @example
+ * ```ts
+ * import type { MailboxWaitOptions } from '@lostgradient/weft';
+ *
+ * const options: MailboxWaitOptions = { timeoutMs: 5_000, pollIntervalMs: 50 };
+ * console.log(options.timeoutMs); // 5000
+ * ```
+ */
+export type MailboxWaitOptions = {
+    readonly signal?: AbortSignal | undefined;
+    /** How long to keep polling. Default `0` — one check, no wait. */
+    readonly timeoutMs?: number | undefined;
+    /** Gap between durable polls. Default 50. */
+    readonly pollIntervalMs?: number | undefined;
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Encoding and fail-closed decoding for the durable application mailbox's
+ * command records (WFT-84). Index records live in
+ * `mailbox-index-codec.ts`; shared readers in
+ * `mailbox-codec-primitives.ts`.
+ *
+ * Decoding is deliberately paranoid. A mailbox record is the authority for
+ * delivery, fencing, and terminal disposition, so a truncated, hand-edited, or
+ * cross-version record must raise `PersistedDataCorruptError` rather than be
+ * coerced into a plausible-looking state — silently treating a corrupt record
+ * as `available` would redeliver work that already applied.
+ *
+ * @module core/mailbox-codec
+ */
+import type { ApplicationCommandRecord } from './mailbox-types.ts';
+import { isApplicationCommandLeased } from './mailbox-types.ts';
+/**
+ * Decode one persisted command record, failing closed on anything unexpected.
+ *
+ * @throws {PersistedDataCorruptError} When the stored bytes are not a
+ * well-formed current-version command record.
+ */
+export declare function decodeApplicationCommandRecord(bytes: Uint8Array, key: string): ApplicationCommandRecord;
+/**
+ * Encode a command record for storage.
+ */
+export declare function encodeApplicationCommandRecord(record: ApplicationCommandRecord): Uint8Array;
+/**
+ * Whether a decoded record still holds an attempt lease. Re-exported here so
+ * storage callers need only one import.
+ */
+export { isApplicationCommandLeased };

package/dist/core/mailbox-codec.js

@@ -0,0 +1,221 @@
+import { KEYS } from "../storage/interface.js";
+import {
+  fail,
+  isRecordObject,
+  ownKey,
+  readIdentifier,
+  readInteger,
+  readOptionalInteger,
+  readOptionalString,
+  readPositiveInteger,
+  readString,
+  readVersion
+} from "./application-primitive-codec.js";
+import { decode, encode } from "./codec.js";
+import { isJSONValue } from "./json.js";
+import {
+  MAILBOX_RECORD_VERSION,
+  isApplicationCommandLeased,
+  isApplicationCommandTerminalState
+} from "./mailbox-types.js";
+const COMMAND_STATES = new Set([
+  "accepted",
+  "available",
+  "claimed",
+  "cancellation-requested",
+  "applied",
+  "rejected",
+  "cancelled",
+  "dead-lettered"
+]), FAILURE_REASONS = new Set([
+  "application",
+  "attempts-exhausted",
+  "deadline-exceeded",
+  "cancelled"
+]), PERSISTED_HEX_DIGEST = /^[0-9a-f]{64}$/;
+function readPayloadFields(source, key) {
+  const payload = readPayload(source, key), payloadDigest = readString(source, "payloadDigest", key);
+  if (payload.form === "reference" && payload.digest !== payloadDigest)
+    fail(key);
+  return { payload, payloadDigest };
+}
+function readPayload(source, key) {
+  const payload = source.payload;
+  if (!isRecordObject(payload))
+    fail(key);
+  if (payload.form === "inline") {
+    if (!("value" in payload))
+      fail(key);
+    return { form: "inline", value: payload.value };
+  }
+  if (payload.form !== "reference")
+    fail(key);
+  const reference = readString(payload, "reference", key), digest = readString(payload, "digest", key);
+  if (!PERSISTED_HEX_DIGEST.test(digest))
+    fail(key);
+  const byteLength = readOptionalInteger(payload, "byteLength", key);
+  return byteLength === void 0 ? { form: "reference", reference, digest } : { form: "reference", reference, digest, byteLength };
+}
+function readCausation(source, key) {
+  const causation = source.causation;
+  if (causation === void 0)
+    return;
+  if (!isRecordObject(causation))
+    fail(key);
+  return {
+    correlationId: readOptionalString(causation, "correlationId", key),
+    causationId: readOptionalString(causation, "causationId", key),
+    traceparent: readOptionalString(causation, "traceparent", key)
+  };
+}
+function readFailure(source, key) {
+  const failure = source.failure;
+  if (failure === void 0)
+    return;
+  if (!isRecordObject(failure))
+    fail(key);
+  const reason = readString(failure, "reason", key);
+  if (!FAILURE_REASONS.has(reason))
+    fail(key);
+  return {
+    reason,
+    message: readOptionalString(failure, "message", key),
+    details: readOptionalJSONValue(failure, "details", key)
+  };
+}
+function readBase(source, key) {
+  return {
+    recordVersion: MAILBOX_RECORD_VERSION,
+    namespace: readString(source, "namespace", key),
+    resourceId: readString(source, "resourceId", key),
+    commandId: readString(source, "commandId", key),
+    sequence: readInteger(source, "sequence", key),
+    idempotencyKey: source.idempotencyKey === void 0 ? void 0 : readIdentifier(source.idempotencyKey, key),
+    caller: readString(source, "caller", key),
+    target: readString(source, "target", key),
+    kind: readString(source, "kind", key),
+    ...readPayloadFields(source, key),
+    payloadMediaType: readOptionalString(source, "payloadMediaType", key),
+    payloadSchema: readOptionalString(source, "payloadSchema", key),
+    causation: readCausation(source, key),
+    acceptedAt: readInteger(source, "acceptedAt", key),
+    availableAt: readInteger(source, "availableAt", key),
+    absoluteDeadlineAt: readInteger(source, "absoluteDeadlineAt", key),
+    maxAttempts: readPositiveInteger(source, "maxAttempts", key),
+    visibilityTimeoutMs: readPositiveInteger(source, "visibilityTimeoutMs", key),
+    generation: readInteger(source, "generation", key),
+    attempt: readInteger(source, "attempt", key),
+    retryCount: readInteger(source, "retryCount", key),
+    firstClaimedAt: readOptionalInteger(source, "firstClaimedAt", key)
+  };
+}
+function readOptionalJSONValue(source, field, key) {
+  const value = source[field];
+  if (value === void 0)
+    return;
+  if (!isJSONValue(value))
+    fail(key);
+  return value;
+}
+function readLeasedBase(source, key) {
+  const base = readBase(source, key);
+  if (base.attempt < 1 || base.attempt > base.maxAttempts)
+    fail(key);
+  const lease = readLease(source, key), expected = Math.min(lease.lastActivityAt + base.visibilityTimeoutMs, base.absoluteDeadlineAt);
+  if (lease.visibilityExpiresAt !== expected)
+    fail(key);
+  return { ...base, ...lease };
+}
+function readLease(source, key) {
+  return {
+    attemptToken: readString(source, "attemptToken", key),
+    claimedAt: readInteger(source, "claimedAt", key),
+    visibilityExpiresAt: readInteger(source, "visibilityExpiresAt", key),
+    lastActivityAt: readInteger(source, "lastActivityAt", key),
+    progress: readOptionalJSONValue(source, "progress", key)
+  };
+}
+function failureMatchesState(state, reason) {
+  switch (state) {
+    case "applied":
+      return reason === void 0;
+    case "rejected":
+      return reason === "application";
+    case "cancelled":
+      return reason === "cancelled";
+    default:
+      return reason === "attempts-exhausted" || reason === "deadline-exceeded";
+  }
+}
+function decodeTerminalRecord(decoded, key, state) {
+  const cleanupPending = decoded.cleanupPending;
+  if (cleanupPending !== void 0 && typeof cleanupPending !== "boolean")
+    fail(key);
+  const failure = readFailure(decoded, key);
+  if (!failureMatchesState(state, failure?.reason))
+    fail(key);
+  const abandoned = readOptionalString(decoded, "abandonedAttemptToken", key);
+  if (!cleanupFieldsMatchState(state, cleanupPending === !0, abandoned))
+    fail(key);
+  return {
+    ...readBase(decoded, key),
+    state,
+    terminalAt: readInteger(decoded, "terminalAt", key),
+    outcome: readOptionalJSONValue(decoded, "outcome", key),
+    failure,
+    cancellationRequestedAt: readOptionalInteger(decoded, "cancellationRequestedAt", key),
+    cancellationReason: readOptionalString(decoded, "cancellationReason", key),
+    cleanupPending,
+    abandonedAttemptToken: abandoned
+  };
+}
+function cleanupFieldsMatchState(state, cleanupPending, abandonedAttemptToken) {
+  if (cleanupPending !== (abandonedAttemptToken !== void 0))
+    return !1;
+  return !cleanupPending || state === "cancelled" || state === "dead-lettered";
+}
+function assertIdentityMatchesKey(decoded, key) {
+  const namespace = readString(decoded, "namespace", key), resourceId = readString(decoded, "resourceId", key), commandId = readString(decoded, "commandId", key);
+  if (ownKey(() => KEYS.applicationCommand(namespace, resourceId, commandId), key) !== key)
+    fail(key);
+}
+function readWaitingRecord(decoded, key, state) {
+  const base = readBase(decoded, key);
+  if (base.attempt >= base.maxAttempts)
+    fail(key);
+  return { ...base, state };
+}
+export function decodeApplicationCommandRecord(bytes, key) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    fail(key);
+  }
+  if (!isRecordObject(decoded))
+    fail(key);
+  readVersion(decoded, key);
+  assertIdentityMatchesKey(decoded, key);
+  const state = decoded.state;
+  if (typeof state !== "string" || !COMMAND_STATES.has(state))
+    fail(key);
+  if (state === "accepted" || state === "available")
+    return readWaitingRecord(decoded, key, state);
+  if (state === "claimed")
+    return { ...readLeasedBase(decoded, key), state };
+  if (state === "cancellation-requested")
+    return {
+      ...readLeasedBase(decoded, key),
+      state,
+      cancellationRequestedAt: readInteger(decoded, "cancellationRequestedAt", key),
+      cancellationReason: readOptionalString(decoded, "cancellationReason", key)
+    };
+  if (!isApplicationCommandTerminalState(state))
+    fail(key);
+  return decodeTerminalRecord(decoded, key, state);
+}
+export function encodeApplicationCommandRecord(record) {
+  return encode(record);
+}
+
+export { isApplicationCommandLeased };