@lostgradient/weft 0.23.0 → 0.24.0

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

@@ -0,0 +1,307 @@
+/**
+ * Claim, settlement, cancellation, operator, maintenance, wait, and drain
+ * result types for the durable application delivery outbox (WFT-85).
+ *
+ * Split from `outbox-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.
+ *
+ * @module core/outbox-claims
+ */
+import type { ApplicationDeliveryReceipt, OutboxCapacity } from './outbox-contract.ts';
+/**
+ * A payload handed to a claimant: digest-verified when inline, unverified when
+ * a reference Weft never dereferences.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryClaimedPayload } from '@lostgradient/weft';
+ *
+ * declare const payload: ApplicationDeliveryClaimedPayload;
+ * if (payload.form === 'inline') console.log(payload.verified); // true
+ * ```
+ */
+export type ApplicationDeliveryClaimedPayload = {
+    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 delivery.
+ *
+ * `signal` aborts when cancellation is requested in this process, when the
+ * attempt is released or refused, and when the outbox is disposed. It is
+ * process-local. The attempt deadline does not arm a timer on it: a host that
+ * drives claims itself learns the deadline has passed from `heartbeat()` or
+ * `settle()` returning `deadline-exceeded`, and `deliverNext()` stops waiting
+ * for the adapter at the deadline and aborts the signal as it releases the
+ * attempt.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryClaim } from '@lostgradient/weft';
+ *
+ * declare const claim: ApplicationDeliveryClaim;
+ * console.log(claim.attemptToken, claim.signal.aborted);
+ * ```
+ */
+export type ApplicationDeliveryClaim = Readonly<{
+    receipt: ApplicationDeliveryReceipt;
+    payload: ApplicationDeliveryClaimedPayload;
+    /** Present only to the claimant; never on a receipt. */
+    credentialRef?: string | undefined;
+    attemptToken: string;
+    attempt: number;
+    visibilityExpiresAt: number;
+    attemptDeadlineAt: number;
+    signal: AbortSignal;
+}>;
+/**
+ * The outcome of asking for work. `held` means deliveries exist but none is
+ * due yet; `availableAt` is the earliest.
+ *
+ * @example
+ * ```ts
+ * import type { OutboxClaimResult } from '@lostgradient/weft';
+ *
+ * declare const result: OutboxClaimResult;
+ * if (result.status === 'claimed') console.log(result.claim.attemptToken);
+ * ```
+ */
+export type OutboxClaimResult = {
+    readonly status: 'claimed';
+    readonly claim: ApplicationDeliveryClaim;
+} | {
+    readonly status: 'empty';
+} | {
+    readonly status: 'held';
+    readonly availableAt: number;
+};
+/**
+ * Result of a heartbeat: liveness recorded and visibility extended, clamped to
+ * the fixed attempt deadline.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryHeartbeatResult } from '@lostgradient/weft';
+ *
+ * declare const result: ApplicationDeliveryHeartbeatResult;
+ * if (result.status === 'renewed' && result.cancellationRequested) console.log('stop sending');
+ * ```
+ */
+export type ApplicationDeliveryHeartbeatResult = {
+    readonly status: 'renewed';
+    readonly visibilityExpiresAt: number;
+    readonly attemptDeadlineAt: number;
+    readonly cancellationRequested: boolean;
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'stale';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'deadline-exceeded';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * Result of marking an attempt as begun, or of settling it.
+ *
+ * `deadline-exceeded` is distinct from `stale`: the attempt itself is over and
+ * maintenance recovers the delivery, while `stale` means another attempt owns
+ * it.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliverySettleResult } from '@lostgradient/weft';
+ *
+ * declare const result: ApplicationDeliverySettleResult;
+ * if (result.status === 'settled') console.log(result.receipt.state);
+ * ```
+ */
+export type ApplicationDeliverySettleResult = {
+    readonly status: 'settled';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'retrying';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'stale';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'deadline-exceeded';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * Result of `deliverNext()`: one delivery run through the adapter and settled,
+ * or nothing to do.
+ *
+ * @example
+ * ```ts
+ * import type { OutboxDeliverResult } from '@lostgradient/weft';
+ *
+ * declare const result: OutboxDeliverResult;
+ * if (result.status === 'settled') console.log(result.receipt.state);
+ * ```
+ */
+export type OutboxDeliverResult = {
+    readonly status: 'settled';
+    readonly receipt: ApplicationDeliveryReceipt;
+    /**
+     * Whether this call committed the receipt's disposition. `false` when
+     * another actor moved the delivery first (a cancellation or recovery that
+     * refused this runner's begin or settlement), when the caller aborted
+     * before the send began, or when the outbox was disposed mid-send and the
+     * lease was left for maintenance; the receipt is then the current durable
+     * state, not this runner's work.
+     */
+    readonly committed: boolean;
+} | {
+    readonly status: 'empty';
+} | {
+    readonly status: 'held';
+    readonly availableAt: number;
+};
+/**
+ * The outcome of requesting cancellation.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryCancellationResult } from '@lostgradient/weft';
+ *
+ * declare const result: ApplicationDeliveryCancellationResult;
+ * if (result.status === 'requested') console.log(result.cleanupPending); // true
+ * ```
+ */
+export type ApplicationDeliveryCancellationResult = {
+    readonly status: 'cancelled';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'requested';
+    readonly receipt: ApplicationDeliveryReceipt;
+    readonly cleanupPending: true;
+} | {
+    readonly status: 'already-terminal';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * The bounded outcome of waiting for a cancelled delivery's attempt to settle.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryCleanupResult } from '@lostgradient/weft';
+ *
+ * declare const cleanup: ApplicationDeliveryCleanupResult;
+ * console.log(cleanup.status === 'pending'); // the outbox stopped waiting
+ * ```
+ */
+export type ApplicationDeliveryCleanupResult = {
+    readonly status: 'settled';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'pending';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * The outcome of an operator `retry()` or `deadLetter()`.
+ *
+ * @example
+ * ```ts
+ * import type { ApplicationDeliveryOperatorResult } from '@lostgradient/weft';
+ *
+ * declare const result: ApplicationDeliveryOperatorResult;
+ * if (result.status === 'applied') console.log(result.receipt.state);
+ * ```
+ */
+export type ApplicationDeliveryOperatorResult = {
+    readonly status: 'applied';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    readonly status: 'not-applicable';
+    readonly receipt: ApplicationDeliveryReceipt;
+} | {
+    /** Reopening would exceed `maxBacklog`; nothing was written. */
+    readonly status: 'rejected';
+    readonly reason: 'backlog-full';
+    readonly capacity: OutboxCapacity;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * What one maintenance pass did. Counts only.
+ *
+ * @example
+ * ```ts
+ * import type { OutboxMaintenanceReport } from '@lostgradient/weft';
+ *
+ * declare const report: OutboxMaintenanceReport;
+ * console.log(report.rescheduled, report.parked, report.retired);
+ * ```
+ */
+export type OutboxMaintenanceReport = Readonly<{
+    /** Expired `claimed` leases returned to the due index. */
+    rescheduled: number;
+    /** Expired `attempting` leases parked as `unknown-outcome`. */
+    parked: number;
+    /** Deliveries terminalized as `dead-lettered`. */
+    deadLettered: number;
+    /** Terminal receipts deleted by the retention sweep. */
+    retired: number;
+}>;
+/** Options for the abortable wait for due work. `timeoutMs` defaults to `0`.
+ *
+ * @example
+ * ```ts
+ * import type { OutboxWaitOptions } from '@lostgradient/weft';
+ *
+ * const options: OutboxWaitOptions = { timeoutMs: 5_000 };
+ * console.log(options.timeoutMs); // 5000
+ * ```
+ */
+export type OutboxWaitOptions = {
+    readonly signal?: AbortSignal | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly pollIntervalMs?: number | undefined;
+};
+/**
+ * What a bounded drain did. `pending` is what remained open when the drain
+ * stopped; every other count is a durable disposition the drain committed.
+ *
+ * @example
+ * ```ts
+ * import type { OutboxDrainReport } from '@lostgradient/weft';
+ *
+ * declare const report: OutboxDrainReport;
+ * console.log(report.acknowledged, report.pending);
+ * ```
+ */
+export type OutboxDrainReport = Readonly<{
+    acknowledged: number;
+    rejected: number;
+    retryScheduled: number;
+    deadLettered: number;
+    cancelled: number;
+    unknown: number;
+    /**
+     * Deliveries still open when the drain stopped, as durable storage last
+     * reported it, kept current with the dispositions this drain committed.
+     * `null` when the drain stopped before storage ever answered its first
+     * header read: nothing was observed, so nothing is claimed.
+     */
+    pending: number | null;
+    /** Whether the drain stopped because nothing was left to do, rather than budget or abort. */
+    drained: boolean;
+}>;

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

@@ -0,0 +1,24 @@
+/**
+ * Encoding and fail-closed decoding for the durable application outbox's
+ * delivery records (WFT-85). Index records live in
+ * `outbox-index-codec.ts`.
+ *
+ * Decoding is deliberately paranoid, as the mailbox's is. A delivery record is
+ * the authority for fencing, disposition, and whether an effect may already
+ * have happened, so a truncated, hand-edited, or cross-version record must
+ * raise `PersistedDataCorruptError` rather than be coerced into a plausible
+ * state — silently treating a corrupt record as `queued` would resend work
+ * that already reached its destination.
+ *
+ * @module core/outbox-codec
+ */
+import type { ApplicationDeliveryRecord } from './outbox-types.ts';
+/**
+ * Decode one persisted delivery record, failing closed on anything unexpected.
+ *
+ * @throws {PersistedDataCorruptError} When the stored bytes are not a
+ * well-formed current-version delivery record.
+ */
+export declare function decodeApplicationDeliveryRecord(bytes: Uint8Array, key: string): ApplicationDeliveryRecord;
+/** Encode a delivery record for storage. */
+export declare function encodeApplicationDeliveryRecord(record: ApplicationDeliveryRecord): Uint8Array;

package/dist/core/outbox-codec.js

@@ -0,0 +1,257 @@
+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 { OUTBOX_RECORD_VERSION, isApplicationDeliveryTerminalState } from "./outbox-types.js";
+const DELIVERY_STATES = new Set([
+  "queued",
+  "retry-scheduled",
+  "claimed",
+  "attempting",
+  "cancellation-requested",
+  "acknowledged",
+  "rejected",
+  "cancelled",
+  "unknown-outcome",
+  "dead-lettered"
+]), FAILURE_REASONS = new Set([
+  "application",
+  "retryable",
+  "attempts-exhausted",
+  "unknown-outcome",
+  "cancelled"
+]), POLICIES = new Set([
+  "park",
+  "dead-letter",
+  "retry-with-idempotency"
+]), 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, field, key) {
+  const failure = source[field];
+  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 readPolicy(source, key) {
+  const policy = readString(source, "unknownOutcomePolicy", key);
+  if (!POLICIES.has(policy))
+    fail(key);
+  return policy;
+}
+function readOptionalIdentifier(source, field, key) {
+  return source[field] === void 0 ? void 0 : readIdentifier(source[field], key);
+}
+function readBase(source, key) {
+  const externalIdempotencyKey = readOptionalIdentifier(source, "externalIdempotencyKey", key), unknownOutcomePolicy = readPolicy(source, key);
+  if (unknownOutcomePolicy === "retry-with-idempotency" && externalIdempotencyKey === void 0)
+    fail(key);
+  return {
+    recordVersion: OUTBOX_RECORD_VERSION,
+    namespace: readString(source, "namespace", key),
+    ownerId: readString(source, "ownerId", key),
+    deliveryId: readString(source, "deliveryId", key),
+    sequence: readInteger(source, "sequence", key),
+    idempotencyKey: readOptionalIdentifier(source, "idempotencyKey", key),
+    destinationRef: readString(source, "destinationRef", key),
+    credentialRef: readOptionalString(source, "credentialRef", key),
+    kind: readString(source, "kind", key),
+    ...readPayloadFields(source, key),
+    payloadMediaType: readOptionalString(source, "payloadMediaType", key),
+    payloadSchema: readOptionalString(source, "payloadSchema", key),
+    causation: readCausation(source, key),
+    externalIdempotencyKey,
+    unknownOutcomePolicy,
+    enqueuedAt: readInteger(source, "enqueuedAt", key),
+    availableAt: readInteger(source, "availableAt", key),
+    maxAttempts: readPositiveInteger(source, "maxAttempts", key),
+    visibilityTimeoutMs: readPositiveInteger(source, "visibilityTimeoutMs", key),
+    attemptTimeoutMs: readPositiveInteger(source, "attemptTimeoutMs", 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 = {
+    attemptToken: readString(source, "attemptToken", key),
+    claimedAt: readInteger(source, "claimedAt", key),
+    visibilityExpiresAt: readInteger(source, "visibilityExpiresAt", key),
+    attemptDeadlineAt: readInteger(source, "attemptDeadlineAt", key),
+    lastActivityAt: readInteger(source, "lastActivityAt", key),
+    transportActivity: readOptionalJSONValue(source, "transportActivity", key)
+  };
+  if (lease.attemptDeadlineAt !== lease.claimedAt + base.attemptTimeoutMs)
+    fail(key);
+  const expected = Math.min(lease.lastActivityAt + base.visibilityTimeoutMs, lease.attemptDeadlineAt);
+  if (lease.visibilityExpiresAt !== expected)
+    fail(key);
+  return { ...base, ...lease };
+}
+function failureMatchesState(state, reason) {
+  switch (state) {
+    case "acknowledged":
+      return reason === void 0;
+    case "rejected":
+      return reason === "application";
+    case "cancelled":
+      return reason === "cancelled";
+    case "unknown-outcome":
+      return reason === "unknown-outcome";
+    default:
+      return reason === "attempts-exhausted" || reason === "unknown-outcome";
+  }
+}
+function cleanupFieldsMatchState(state, cleanupPending, abandonedAttemptToken) {
+  if (cleanupPending !== (abandonedAttemptToken !== void 0))
+    return !1;
+  return !cleanupPending || state === "unknown-outcome" || state === "dead-lettered";
+}
+function decodeTerminalRecord(decoded, key, state) {
+  const cleanupPending = decoded.cleanupPending;
+  if (cleanupPending !== void 0 && typeof cleanupPending !== "boolean")
+    fail(key);
+  const failure = readFailure(decoded, "failure", 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),
+    evidence: readOptionalJSONValue(decoded, "evidence", key),
+    failure,
+    cancellationRequestedAt: readOptionalInteger(decoded, "cancellationRequestedAt", key),
+    cancellationReason: readOptionalString(decoded, "cancellationReason", key),
+    cleanupPending,
+    abandonedAttemptToken: abandoned
+  };
+}
+function assertIdentityMatchesKey(decoded, key) {
+  const namespace = readString(decoded, "namespace", key), ownerId = readString(decoded, "ownerId", key), deliveryId = readString(decoded, "deliveryId", key);
+  if (ownKey(() => KEYS.applicationDelivery(namespace, ownerId, deliveryId), key) !== key)
+    fail(key);
+}
+function readWaitingRecord(decoded, key, state) {
+  const base = readBase(decoded, key);
+  if (base.attempt >= base.maxAttempts)
+    fail(key);
+  if (state === "queued")
+    return { ...base, state };
+  const lastFailure = readFailure(decoded, "lastFailure", key);
+  if (lastFailure === void 0 || lastFailure.reason !== "retryable" && lastFailure.reason !== "unknown-outcome")
+    fail(key);
+  return { ...base, state, lastFailure };
+}
+function readEnvelope(bytes, key) {
+  let decoded;
+  try {
+    decoded = decode(bytes);
+  } catch {
+    fail(key);
+  }
+  if (!isRecordObject(decoded))
+    fail(key);
+  readVersion(decoded, key, OUTBOX_RECORD_VERSION);
+  return decoded;
+}
+export function decodeApplicationDeliveryRecord(bytes, key) {
+  const decoded = readEnvelope(bytes, key);
+  assertIdentityMatchesKey(decoded, key);
+  const state = decoded.state;
+  if (!isDeliveryState(state))
+    fail(key);
+  if (state === "queued" || state === "retry-scheduled")
+    return readWaitingRecord(decoded, key, state);
+  if (isApplicationDeliveryTerminalState(state))
+    return decodeTerminalRecord(decoded, key, state);
+  return decodeLeasedRecord(decoded, key, state);
+}
+function isDeliveryState(state) {
+  return typeof state === "string" && DELIVERY_STATES.has(state);
+}
+function decodeLeasedRecord(decoded, key, state) {
+  const base = readLeasedBase(decoded, key);
+  if (state === "claimed")
+    return { ...base, state };
+  const attemptStartedAt = readInteger(decoded, "attemptStartedAt", key);
+  if (state === "attempting")
+    return { ...base, state, attemptStartedAt };
+  return {
+    ...base,
+    state,
+    attemptStartedAt,
+    cancellationRequestedAt: readInteger(decoded, "cancellationRequestedAt", key),
+    cancellationReason: readOptionalString(decoded, "cancellationReason", key)
+  };
+}
+export function encodeApplicationDeliveryRecord(record) {
+  return encode(record);
+}