@lostgradient/weft 0.18.0 → 0.20.0

package/dist/server/task-ledger-codec.js

@@ -0,0 +1,195 @@
+import { decode, encode } from "../core/codec.js";
+import { isJSONValue } from "../core/json.js";
+import {
+  MAX_TASK_HEADER_COUNT,
+  MAX_TASK_HEADER_VALUE_BYTES,
+  MAX_TASK_IDENTIFIER_BYTES,
+  MAX_TASK_REASON_BYTES,
+  MAX_TASK_RESULT_DIGEST_BYTES,
+  utf8ByteLength
+} from "./task-ledger-limits.js";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isBoundedIdentifier(value, maxBytes = MAX_TASK_IDENTIFIER_BYTES) {
+  return typeof value === "string" && value.length > 0 && utf8ByteLength(value) <= maxBytes;
+}
+function isBoundedOptionalIdentifier(value, maxBytes = MAX_TASK_IDENTIFIER_BYTES) {
+  return value === void 0 || isBoundedIdentifier(value, maxBytes);
+}
+function isBoundedReason(value) {
+  return typeof value === "string" && value.length > 0 && utf8ByteLength(value) <= MAX_TASK_REASON_BYTES;
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function isOptionalFiniteNumber(value) {
+  return value === void 0 || isFiniteNumber(value);
+}
+function isOptionalBoundedReason(value) {
+  return value === void 0 || isBoundedReason(value);
+}
+function isCompletedOrFailedStatus(value) {
+  return value === "completed" || value === "failed";
+}
+function isOptionalJSONValue(value) {
+  return value === void 0 || isJSONValue(value);
+}
+function isDurationLike(value) {
+  return typeof value === "number" || typeof value === "string";
+}
+export function isValidTaskHeaders(value) {
+  if (!isRecord(value))
+    return !1;
+  const entries = Object.entries(value);
+  if (entries.length > MAX_TASK_HEADER_COUNT)
+    return !1;
+  return entries.every(([key, headerValue]) => utf8ByteLength(key) <= MAX_TASK_HEADER_VALUE_BYTES && typeof headerValue === "string" && utf8ByteLength(headerValue) <= MAX_TASK_HEADER_VALUE_BYTES);
+}
+function isValidNonRetryableErrors(value) {
+  return value === void 0 || Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isValidRetryPolicy(value) {
+  if (value === void 0)
+    return !0;
+  if (!isRecord(value))
+    return !1;
+  return isFiniteNumber(value.maxAttempts) && isDurationLike(value.initialBackoff) && isFiniteNumber(value.backoffMultiplier) && isDurationLike(value.maxBackoff) && isValidNonRetryableErrors(value.nonRetryableErrors);
+}
+function isValidExecutionRequirement(value) {
+  if (value === void 0)
+    return !0;
+  if (!isRecord(value))
+    return !1;
+  return isBoundedOptionalIdentifier(value.deploymentName) && isBoundedOptionalIdentifier(value.buildId) && isBoundedOptionalIdentifier(value.artifactDigest) && isBoundedOptionalIdentifier(value.workflowRevision) && isBoundedOptionalIdentifier(value.activityContractHash);
+}
+const EXECUTION_IDENTITY_STRING_FIELDS = [
+  "workerId",
+  "manifestDigest",
+  "sdkVersion",
+  "runtimeName",
+  "runtimeVersion",
+  "deploymentName",
+  "buildId",
+  "artifactDigest",
+  "workflowType",
+  "workflowRevision",
+  "activityName",
+  "activityContractHash"
+];
+function isValidExecutionIdentity(value) {
+  if (!isRecord(value))
+    return !1;
+  return EXECUTION_IDENTITY_STRING_FIELDS.every((field) => isBoundedIdentifier(value[field])) && isFiniteNumber(value.protocolVersion);
+}
+function isOptionalExecutionIdentity(value) {
+  return value === void 0 || isValidExecutionIdentity(value);
+}
+function isValidTaskIdentityFields(value) {
+  return value.recordVersion === 1 && isBoundedIdentifier(value.operationId) && isBoundedOptionalIdentifier(value.workflowId) && isBoundedIdentifier(value.workflowType) && isBoundedOptionalIdentifier(value.workflowExecutionToken) && isBoundedIdentifier(value.activityName) && isBoundedIdentifier(value.queue);
+}
+function isValidTaskRoutingFields(value) {
+  return isOptionalFiniteNumber(value.priority) && isBoundedOptionalIdentifier(value.fairShareKey) && isBoundedOptionalIdentifier(value.stickyWorkflowId) && isValidExecutionRequirement(value.executionRequirement);
+}
+function isValidTaskPayloadFields(value) {
+  return isJSONValue(value.input) && isValidTaskHeaders(value.headers) && isValidTaskRoutingFields(value) && isFiniteNumber(value.visibilityTimeoutMilliseconds) && isValidRetryPolicy(value.retryPolicy) && isOptionalFiniteNumber(value.scheduleToCloseDeadline) && isFiniteNumber(value.createdAt) && isFiniteNumber(value.generation);
+}
+function isValidTaskBase(value) {
+  return isValidTaskIdentityFields(value) && isValidTaskPayloadFields(value);
+}
+function isValidAttemptFields(value) {
+  return isFiniteNumber(value.retryCount) && isFiniteNumber(value.requeueCount) && (value.lastRequeueReason === void 0 || isBoundedReason(value.lastRequeueReason));
+}
+function isValidLeaseHolderShape(value) {
+  return isValidAttemptFields(value) && isBoundedIdentifier(value.attemptToken) && isBoundedIdentifier(value.workerSessionId) && isOptionalExecutionIdentity(value.executionIdentity) && isFiniteNumber(value.attempt) && isFiniteNumber(value.leaseDeadline) && isFiniteNumber(value.firstQueuedAt) && isFiniteNumber(value.lastQueuedAt) && isFiniteNumber(value.startedAt) && isFiniteNumber(value.lastHeartbeatAt);
+}
+function isValidQueuedTimingFields(value) {
+  return isFiniteNumber(value.attempt) && isFiniteNumber(value.availableAt) && isFiniteNumber(value.firstQueuedAt) && isFiniteNumber(value.lastQueuedAt) && isOptionalFiniteNumber(value.lastDispatchedAt) && isOptionalFiniteNumber(value.startedAt);
+}
+export function isRemoteTaskQueued(value) {
+  if (!isRecord(value) || value.state !== "queued")
+    return !1;
+  return isValidTaskBase(value) && isValidAttemptFields(value) && isValidQueuedTimingFields(value);
+}
+export function isRemoteTaskLeased(value) {
+  if (!isRecord(value) || value.state !== "leased" || !isValidTaskBase(value))
+    return !1;
+  return isValidLeaseHolderShape(value);
+}
+export function isRemoteTaskCompleting(value) {
+  if (!isRecord(value) || value.state !== "completing")
+    return !1;
+  return isValidTaskBase(value) && isValidLeaseHolderShape(value) && isCompletedOrFailedStatus(value.pendingStatus) && isBoundedIdentifier(value.pendingResultDigest);
+}
+export function isRemoteTaskCancelling(value) {
+  if (!isRecord(value) || value.state !== "cancelling" || !isValidTaskBase(value))
+    return !1;
+  return isValidLeaseHolderShape(value) && isBoundedReason(value.cancellationReason) && isFiniteNumber(value.cancellationRequestedAt);
+}
+function isValidTerminalCommon(value) {
+  return isFiniteNumber(value.attempt) && isBoundedIdentifier(value.resultDigest, MAX_TASK_RESULT_DIGEST_BYTES) && isFiniteNumber(value.terminalAt) && typeof value.adopted === "boolean" && isOptionalFiniteNumber(value.adoptedAt) && isFiniteNumber(value.retentionGeneration);
+}
+function isTerminalDisposition(value, disposition) {
+  return value.state === "terminal" && value.disposition === disposition;
+}
+export function isRemoteTaskTerminalResolved(value) {
+  if (!isRecord(value) || !isTerminalDisposition(value, "resolved"))
+    return !1;
+  if (!isValidTaskBase(value) || !isValidTerminalCommon(value))
+    return !1;
+  return isBoundedIdentifier(value.attemptToken) && isCompletedOrFailedStatus(value.status) && isOptionalBoundedReason(value.error);
+}
+export function isRemoteTaskTerminalCancelled(value) {
+  if (!isRecord(value) || !isTerminalDisposition(value, "cancelled"))
+    return !1;
+  if (!isValidTaskBase(value) || !isValidTerminalCommon(value))
+    return !1;
+  return isBoundedOptionalIdentifier(value.attemptToken) && isBoundedReason(value.cancellationReason);
+}
+export function isRemoteTaskTerminalRetryExhausted(value) {
+  if (!isRecord(value) || !isTerminalDisposition(value, "retryExhausted"))
+    return !1;
+  if (!isValidTaskBase(value) || !isValidTerminalCommon(value))
+    return !1;
+  return isBoundedIdentifier(value.attemptToken) && isBoundedReason(value.error);
+}
+export function isRemoteTaskTerminal(value) {
+  return isRemoteTaskTerminalResolved(value) || isRemoteTaskTerminalCancelled(value) || isRemoteTaskTerminalRetryExhausted(value);
+}
+function isValidDeadLetteredResultFields(value) {
+  return isBoundedIdentifier(value.attemptToken) && isFiniteNumber(value.attempt) && isCompletedOrFailedStatus(value.pendingStatus) && isBoundedIdentifier(value.pendingResultDigest) && isOptionalJSONValue(value.value) && isOptionalBoundedReason(value.error);
+}
+export function isRemoteTaskDeadLettered(value) {
+  if (!isRecord(value) || value.state !== "deadLettered")
+    return !1;
+  return isValidTaskBase(value) && isValidAttemptFields(value) && isValidDeadLetteredResultFields(value) && isFiniteNumber(value.deadLetteredAt) && isBoundedReason(value.persistenceFailureReason);
+}
+export function isRemoteTaskRecord(value) {
+  if (!isRecord(value) || typeof value.state !== "string")
+    return !1;
+  switch (value.state) {
+    case "queued":
+      return isRemoteTaskQueued(value);
+    case "leased":
+      return isRemoteTaskLeased(value);
+    case "completing":
+      return isRemoteTaskCompleting(value);
+    case "cancelling":
+      return isRemoteTaskCancelling(value);
+    case "terminal":
+      return isRemoteTaskTerminal(value);
+    case "deadLettered":
+      return isRemoteTaskDeadLettered(value);
+    default:
+      return !1;
+  }
+}
+export function encodeRemoteTaskRecord(record) {
+  return encode(record);
+}
+export function decodeRemoteTaskRecord(bytes) {
+  if (bytes === null)
+    return null;
+  const decoded = decode(bytes);
+  return isRemoteTaskRecord(decoded) ? decoded : null;
+}

package/dist/server/task-ledger-keys.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Canonical storage key for the durable remote task ledger (WFT-25).
+ *
+ * One current-state key is authoritative per operation. `operationId` is
+ * caller-controlled (it flows from `TaskDispatch.operationId`), so it is
+ * encoded through {@link encodeStorageKeyComponent} the same way every other
+ * hostile key component in this codebase is — see `signalStorageKey` in
+ * `storage/interface.ts` for the established precedent.
+ *
+ * @module server/task-ledger-keys
+ */
+/** The single authoritative current-state key for one operation's task record. */
+export declare function taskLedgerKey(operationId: string): string;

package/dist/server/task-ledger-keys.js

@@ -0,0 +1,5 @@
+import { encodeStorageKeyComponent } from "../storage/interface.js";
+const TASK_LEDGER_KEY_PREFIX = "task-ledger:";
+export function taskLedgerKey(operationId) {
+  return `${TASK_LEDGER_KEY_PREFIX}${encodeStorageKeyComponent(operationId)}`;
+}

package/dist/server/task-ledger-limits.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Semantic bounds applied to a {@link RemoteTaskRecord} before it is decoded
+ * or admitted to storage (WFT-25).
+ *
+ * These bound the *semantic* shape a persisted or wire-derived task record
+ * may assert — operation/workflow identity strings, header counts and sizes,
+ * retry fields — independent of any transport-level frame ceiling. Server
+ * policy brief: "Bound operation IDs, workflow IDs, names, queues, header
+ * counts, header bytes, retry fields, and payload sizes before storage
+ * writes."
+ *
+ * @module server/task-ledger-limits
+ */
+/** UTF-8 byte length of `value`. */
+export declare function utf8ByteLength(value: string): number;
+/** Maximum UTF-8 byte length of any single identifier-shaped ledger string. */
+export declare const MAX_TASK_IDENTIFIER_BYTES = 512;
+/** Maximum number of header entries a single task record may carry. */
+export declare const MAX_TASK_HEADER_COUNT = 64;
+/** Maximum UTF-8 byte length of a single header name or value. */
+export declare const MAX_TASK_HEADER_VALUE_BYTES = 4096;
+/** Maximum UTF-8 byte length of a single free-text reason/error string. */
+export declare const MAX_TASK_REASON_BYTES = 4096;
+/**
+ * Maximum UTF-8 byte length of a terminal record's `resultDigest`.
+ *
+ * Wider than {@link MAX_TASK_IDENTIFIER_BYTES} because the ledger's own
+ * cancellation and retry-exhaustion transitions synthesize this field by
+ * concatenating an `operationId` and an `attemptToken` — each independently
+ * bounded to {@link MAX_TASK_IDENTIFIER_BYTES} — plus a short literal prefix.
+ * A tighter bound here would let two individually-valid identifiers combine
+ * into a `resultDigest` the codec's own decoder then rejects.
+ */
+export declare const MAX_TASK_RESULT_DIGEST_BYTES: number;

package/dist/server/task-ledger-limits.js

@@ -0,0 +1,5 @@
+const textEncoder = new TextEncoder;
+export function utf8ByteLength(value) {
+  return textEncoder.encode(value).byteLength;
+}
+export const MAX_TASK_IDENTIFIER_BYTES = 512, MAX_TASK_HEADER_COUNT = 64, MAX_TASK_HEADER_VALUE_BYTES = 4096, MAX_TASK_REASON_BYTES = 4096, MAX_TASK_RESULT_DIGEST_BYTES = 2 * MAX_TASK_IDENTIFIER_BYTES + 64;

package/dist/server/task-ledger-transition-helpers.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared result types and field pickers for the durable remote task ledger's
+ * pure conditional-transition functions (WFT-25) — split out of
+ * `task-ledger-transitions.ts` / `task-ledger-transitions-cancellation.ts`
+ * purely to keep both under this repository's file-size ceiling; there is no
+ * behavioral reason to import this module directly instead of one of those.
+ *
+ * @module server/task-ledger-transition-helpers
+ */
+import type { WorkerExecutionIdentity } from '../worker/manifest/types.ts';
+import type { RemoteTaskAttemptFields, RemoteTaskBase } from './task-ledger-types.ts';
+export type TaskLedgerTransitionResult<T> = Readonly<{
+    ok: true;
+    nextRecord: T;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+export type TaskLedgerPreconditionResult = Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    reason: string;
+}>;
+export declare function pickBase(record: RemoteTaskBase): RemoteTaskBase;
+export declare function pickAttemptFields(record: RemoteTaskAttemptFields): RemoteTaskAttemptFields;
+export type LeaseHolderFields = Readonly<{
+    attemptToken: string;
+    workerSessionId: string;
+    executionIdentity?: WorkerExecutionIdentity;
+    attempt: number;
+    leaseDeadline: number;
+    firstQueuedAt: number;
+    lastQueuedAt: number;
+    startedAt: number;
+    lastHeartbeatAt: number;
+}>;
+export declare function pickLeaseHolderFields(record: LeaseHolderFields): LeaseHolderFields;

package/dist/server/task-ledger-transition-helpers.js

@@ -0,0 +1,42 @@
+export function pickBase(record) {
+  return {
+    recordVersion: record.recordVersion,
+    operationId: record.operationId,
+    ...record.workflowId !== void 0 ? { workflowId: record.workflowId } : {},
+    workflowType: record.workflowType,
+    ...record.workflowExecutionToken !== void 0 ? { workflowExecutionToken: record.workflowExecutionToken } : {},
+    activityName: record.activityName,
+    queue: record.queue,
+    input: record.input,
+    headers: record.headers,
+    ...record.priority !== void 0 ? { priority: record.priority } : {},
+    ...record.fairShareKey !== void 0 ? { fairShareKey: record.fairShareKey } : {},
+    ...record.stickyWorkflowId !== void 0 ? { stickyWorkflowId: record.stickyWorkflowId } : {},
+    visibilityTimeoutMilliseconds: record.visibilityTimeoutMilliseconds,
+    ...record.retryPolicy !== void 0 ? { retryPolicy: record.retryPolicy } : {},
+    ...record.scheduleToCloseDeadline !== void 0 ? { scheduleToCloseDeadline: record.scheduleToCloseDeadline } : {},
+    ...record.executionRequirement !== void 0 ? { executionRequirement: record.executionRequirement } : {},
+    createdAt: record.createdAt,
+    generation: record.generation
+  };
+}
+export function pickAttemptFields(record) {
+  return {
+    retryCount: record.retryCount,
+    requeueCount: record.requeueCount,
+    ...record.lastRequeueReason !== void 0 ? { lastRequeueReason: record.lastRequeueReason } : {}
+  };
+}
+export function pickLeaseHolderFields(record) {
+  return {
+    attemptToken: record.attemptToken,
+    workerSessionId: record.workerSessionId,
+    ...record.executionIdentity !== void 0 ? { executionIdentity: record.executionIdentity } : {},
+    attempt: record.attempt,
+    leaseDeadline: record.leaseDeadline,
+    firstQueuedAt: record.firstQueuedAt,
+    lastQueuedAt: record.lastQueuedAt,
+    startedAt: record.startedAt,
+    lastHeartbeatAt: record.lastHeartbeatAt
+  };
+}

package/dist/server/task-ledger-transitions-cancellation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cancellation and terminal-adoption transitions for the durable remote task
+ * ledger (WFT-25) — rows 7-10 of the project brief's "Conditional transition
+ * contract" table. Split out of `task-ledger-transitions.ts` purely to keep
+ * both files under this repository's file-size ceiling; re-exported from
+ * `task-ledger-transitions.ts` so callers have one import surface. See that
+ * module's doc comment for the shared design notes (pure, storage-agnostic,
+ * `expectedValue` bytes are the caller's responsibility).
+ *
+ * @module server/task-ledger-transitions-cancellation
+ */
+import { type TaskLedgerPreconditionResult, type TaskLedgerTransitionResult } from './task-ledger-transition-helpers.ts';
+import type { RemoteTaskCancelling, RemoteTaskRecord, RemoteTaskTerminal, RemoteTaskTerminalCancelled } from './task-ledger-types.ts';
+export type RecordCancellationIntentInput = Readonly<{
+    expectedGeneration: number;
+    expectedAttempt: number;
+    cancellationReason: string;
+}>;
+export declare function recordCancellationIntent(current: RemoteTaskRecord | null, input: RecordCancellationIntentInput, now: number): TaskLedgerTransitionResult<RemoteTaskCancelling | RemoteTaskTerminalCancelled>;
+export type CommitCancellationInput = Readonly<{
+    attemptToken: string;
+}>;
+export declare function commitCancellation(current: RemoteTaskRecord | null, input: CommitCancellationInput, now: number): TaskLedgerTransitionResult<RemoteTaskTerminalCancelled>;
+export type MarkWorkflowResultAdoptedInput = Readonly<{
+    expectedResultDigest: string;
+}>;
+export declare function markWorkflowResultAdopted(current: RemoteTaskRecord | null, input: MarkWorkflowResultAdoptedInput, now: number): TaskLedgerTransitionResult<RemoteTaskTerminal>;
+export type DeleteRetainedTerminalTaskInput = Readonly<{
+    expectedRetentionGeneration: number;
+}>;
+export declare function canDeleteRetainedTerminalTask(current: RemoteTaskRecord | null, input: DeleteRetainedTerminalTaskInput): TaskLedgerPreconditionResult;

package/dist/server/task-ledger-transitions-cancellation.js

@@ -0,0 +1,73 @@
+import {
+  pickAttemptFields,
+  pickBase,
+  pickLeaseHolderFields
+} from "./task-ledger-transition-helpers.js";
+export function recordCancellationIntent(current, input, now) {
+  if (current === null || current.state !== "queued" && current.state !== "leased")
+    return { ok: !1, reason: 'expected task state "queued" or "leased"' };
+  if (current.generation !== input.expectedGeneration || current.attempt !== input.expectedAttempt)
+    return { ok: !1, reason: "generation or attempt mismatch" };
+  if (current.state === "queued")
+    return { ok: !0, nextRecord: {
+      ...pickBase(current),
+      generation: current.generation + 1,
+      state: "terminal",
+      disposition: "cancelled",
+      attempt: current.attempt,
+      cancellationReason: input.cancellationReason,
+      resultDigest: `cancelled:${current.operationId}:${String(current.generation)}`,
+      terminalAt: now,
+      adopted: !1,
+      retentionGeneration: 0
+    } };
+  return { ok: !0, nextRecord: {
+    ...pickBase(current),
+    ...pickAttemptFields(current),
+    ...pickLeaseHolderFields(current),
+    generation: current.generation + 1,
+    state: "cancelling",
+    cancellationReason: input.cancellationReason,
+    cancellationRequestedAt: now
+  } };
+}
+export function commitCancellation(current, input, now) {
+  if (current === null || current.state !== "cancelling")
+    return { ok: !1, reason: 'expected task state "cancelling"' };
+  if (current.attemptToken !== input.attemptToken)
+    return { ok: !1, reason: "attempt token mismatch" };
+  return { ok: !0, nextRecord: {
+    ...pickBase(current),
+    generation: current.generation + 1,
+    state: "terminal",
+    disposition: "cancelled",
+    attempt: current.attempt,
+    attemptToken: current.attemptToken,
+    cancellationReason: current.cancellationReason,
+    resultDigest: `cancelled:${current.operationId}:${current.attemptToken}`,
+    terminalAt: now,
+    adopted: !1,
+    retentionGeneration: 0
+  } };
+}
+export function markWorkflowResultAdopted(current, input, now) {
+  if (current === null || current.state !== "terminal")
+    return { ok: !1, reason: 'expected task state "terminal"' };
+  if (current.resultDigest !== input.expectedResultDigest)
+    return { ok: !1, reason: "result digest mismatch" };
+  return { ok: !0, nextRecord: {
+    ...current,
+    generation: current.generation + 1,
+    adopted: !0,
+    adoptedAt: now
+  } };
+}
+export function canDeleteRetainedTerminalTask(current, input) {
+  if (current === null || current.state !== "terminal")
+    return { ok: !1, reason: 'expected task state "terminal"' };
+  if (!current.adopted)
+    return { ok: !1, reason: "terminal task is not yet adopted" };
+  if (current.retentionGeneration !== input.expectedRetentionGeneration)
+    return { ok: !1, reason: "retention generation mismatch" };
+  return { ok: !0 };
+}

package/dist/server/task-ledger-transitions.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Pure conditional-transition precondition functions for the durable remote
+ * task ledger (WFT-25) — one function per row of the project brief's
+ * "Conditional transition contract" table.
+ *
+ * These functions are storage-agnostic by design: they take the currently
+ * decoded {@link RemoteTaskRecord} (or `null` when no record exists) and
+ * proposed inputs, and return either the next record to persist or a
+ * rejection reason. They never read or write storage, and they never see raw
+ * encoded bytes.
+ *
+ * That last point is deliberate. `storage.conditionalBatch`'s
+ * `ConditionalBatchCondition.expectedValue` is whole-value byte equality —
+ * `encode(decode(bytes))` is not guaranteed to reproduce the exact original
+ * bytes. The caller that actually commits a transition (the "Queue and Claim
+ * Coordinator" work, WFT-22) must keep the raw `Uint8Array` it read from
+ * storage and pass those exact bytes as the CAS `expectedValue`, using the
+ * `nextRecord` this module returns only for what to write, never for what to
+ * compare against.
+ *
+ * Twelve rows are covered. This module holds rows 1-6 (create through
+ * requeue) plus two WFT-24 additions at the end: `Completing --> DeadLettered`
+ * (dead-letter creation on exhausted result-persistence retries) and "Clear
+ * dead letter" (an operator discarding a dead-lettered diagnostic). Both
+ * appear in the state diagram but not the original ten-row
+ * transition-contract table — WFT-25 deliberately left them out as WFT-24
+ * ("Adoption, retention, and diagnostics") scope; see `commitDeadLetter`'s
+ * own doc comment for why they belong beside `commitTerminalResult` rather
+ * than in the cancellation file. Rows 7-10 (cancellation and terminal
+ * adoption) live in `task-ledger-transitions-cancellation.ts` and are
+ * re-exported below — the split exists only to keep both files under this
+ * repository's file-size ceiling.
+ *
+ * @module server/task-ledger-transitions
+ */
+import type { JSONValue } from '../core/json.ts';
+import type { WorkerExecutionIdentity } from '../worker/manifest/types.ts';
+import { type TaskLedgerPreconditionResult, type TaskLedgerTransitionResult } from './task-ledger-transition-helpers.ts';
+import type { RemoteTaskBase, RemoteTaskCompleting, RemoteTaskDeadLettered, RemoteTaskLeased, RemoteTaskQueued, RemoteTaskRecord, RemoteTaskTerminal, RemoteTaskTerminalRetryExhausted } from './task-ledger-types.ts';
+export type { TaskLedgerPreconditionResult, TaskLedgerTransitionResult, } from './task-ledger-transition-helpers.ts';
+export { canDeleteRetainedTerminalTask, commitCancellation, markWorkflowResultAdopted, recordCancellationIntent, type CommitCancellationInput, type DeleteRetainedTerminalTaskInput, type MarkWorkflowResultAdoptedInput, type RecordCancellationIntentInput, } from './task-ledger-transitions-cancellation.ts';
+export type CreateQueuedInput = Omit<RemoteTaskBase, 'generation'> & Readonly<{
+    availableAt?: number;
+}>;
+export declare function createQueued(current: RemoteTaskRecord | null, input: CreateQueuedInput, now: number): TaskLedgerTransitionResult<RemoteTaskQueued>;
+export type ClaimQueuedInput = Readonly<{
+    expectedGeneration: number;
+    attemptToken: string;
+    workerSessionId: string;
+    /** Omitted when the claiming worker has no registered manifest entry for this workflowType/activityName — see `RemoteTaskLeased.executionIdentity`'s doc comment. */
+    executionIdentity?: WorkerExecutionIdentity;
+    leaseDurationMilliseconds: number;
+}>;
+export declare function claimQueued(current: RemoteTaskRecord | null, input: ClaimQueuedInput, now: number): TaskLedgerTransitionResult<RemoteTaskLeased>;
+export type RenewAttemptLeaseInput = Readonly<{
+    attemptToken: string;
+    workerSessionId: string;
+    leaseDurationMilliseconds: number;
+}>;
+export declare function renewAttemptLease(current: RemoteTaskRecord | null, input: RenewAttemptLeaseInput, now: number): TaskLedgerTransitionResult<RemoteTaskLeased>;
+export type BeginCompletionInput = Readonly<{
+    attemptToken: string;
+    pendingStatus: 'completed' | 'failed';
+    pendingResultDigest: string;
+}>;
+export declare function beginCompletion(current: RemoteTaskRecord | null, input: BeginCompletionInput): TaskLedgerTransitionResult<RemoteTaskCompleting>;
+export type CommitTerminalResultInput = Readonly<{
+    attemptToken: string;
+    resultDigest: string;
+    error?: string;
+}>;
+export declare function commitTerminalResult(current: RemoteTaskRecord | null, input: CommitTerminalResultInput, now: number): TaskLedgerTransitionResult<RemoteTaskTerminal>;
+export type RequeueExpiredAttemptInput = Readonly<{
+    attemptToken: string;
+    requeueReason: string;
+    /**
+     * Skip the lease-deadline precondition. Worker disconnect forfeits the
+     * lease immediately rather than waiting for it to expire — the brief's
+     * "Disconnect races heartbeat -> One attempt-token transition wins" licenses
+     * a requeue here as long as the attempt token still matches, independent of
+     * whether the deadline has actually passed. Visibility-timeout-origin
+     * requeues never set this, since expiry genuinely requires the deadline
+     * precondition.
+     */
+    skipDeadlineCheck?: boolean;
+}>;
+export declare function requeueExpiredAttempt(current: RemoteTaskRecord | null, input: RequeueExpiredAttemptInput, now: number): TaskLedgerTransitionResult<RemoteTaskQueued | RemoteTaskTerminalRetryExhausted>;
+/**
+ * Terminal-adjacent, not terminal: a `deadLettered` record is not a
+ * `RemoteTaskTerminal` disposition. `commitTaskLedgerCompletion`
+ * (`server/runtime/task-ledger-completion.ts`) reaches this only after
+ * `beginCompletion` already landed the record durably in `completing` (or
+ * found it already there) and the *second* write — `commitTerminalResult` —
+ * exhausted its own CAS retry budget. That is a genuine, sustained storage
+ * write failure on this operation specifically, not a benign lost race
+ * against a legitimate concurrent writer: `commitTerminalResult`'s own
+ * precondition (state `completing`, matching attempt token and result
+ * digest) already guards against clobbering a result some other writer
+ * legitimately resolved out from under this one, so a caller reaching this
+ * transition has already confirmed, moments earlier, that nothing else
+ * should have been able to land instead.
+ *
+ * Preconditions mirror `commitTerminalResult`'s exactly (state, attempt
+ * token, result digest) rather than trusting the caller's exhausted-retry
+ * report at face value — a fresh read here could observe that some other
+ * writer *did* land a terminal result in the interim (e.g. the worker's own
+ * retried submission, resumed through `commitTaskLedgerCompletion`'s
+ * `resuming` branch, racing ahead of the exhausted attempt), in which case
+ * this correctly rejects rather than dead-lettering an already-resolved
+ * task.
+ */
+export type CommitDeadLetterInput = Readonly<{
+    attemptToken: string;
+    resultDigest: string;
+    value?: JSONValue;
+    error?: string;
+    persistenceFailureReason: string;
+}>;
+export declare function commitDeadLetter(current: RemoteTaskRecord | null, input: CommitDeadLetterInput, now: number): TaskLedgerTransitionResult<RemoteTaskDeadLettered>;
+/**
+ * Precondition for `weft.tasks.diagnostics.deadletters.clear`
+ * (`server/operations/get-task-diagnostics.ts`): an operator has seen the
+ * dead-lettered diagnostic and is discarding it, freeing the operationId
+ * for reuse (a later `createQueued` for the same operationId is otherwise
+ * rejected — its own precondition requires the current key be absent).
+ * Precondition-only, like `canDeleteRetainedTerminalTask` — the caller
+ * issues the delete.
+ */
+export declare function canClearDeadLetteredTask(current: RemoteTaskRecord | null): TaskLedgerPreconditionResult;