task-manager-logic 0.1.0 → 0.1.2

package/src/processors.ts

@@ -0,0 +1,747 @@
+import type {
+  CancelTaskCommand,
+  ClaimTaskCommand,
+  CreateTaskSpaceCommand,
+  ExpireTaskClaimCommand,
+  FailTaskCommand,
+  HeartbeatTaskClaimCommand,
+  PatchTaskSpaceCommand,
+  ReplanTaskCommand,
+  SettleTaskCommand,
+  StartTaskCommand,
+  TaskArtifactBody,
+  TaskClaimReceipt,
+  TaskClaimToken,
+  TaskCommand,
+  TaskCommandReceipt,
+  TaskHistoryEvent,
+  TaskId,
+  TaskNodeDefinition,
+  TaskProfileEnvelope,
+  TaskRecord,
+  TaskReplanReceipt,
+  TaskSettlementReceipt,
+  TaskSpaceDefinition,
+  TaskSpaceOwnerPort,
+  TaskSpaceSnapshot,
+  TaskStatus,
+  TaskTimestamp,
+  TaskTransitionReceipt,
+  WaitTaskCommand,
+} from 'task-manager-contract';
+import { TaskManagerError } from './errors.js';
+import { assertTaskTransition, isTerminal } from './statusMachine.js';
+import {
+  assertClaimIdentity,
+  assertClaimLive,
+  deepImmutableClone,
+  normalizeTaskProcessorConfig,
+  predecessorIds,
+  taskRecordById,
+  validateTaskSpaceDefinition,
+  validateTimestamp,
+  type TaskProcessorConfig,
+} from './validation.js';
+
+export interface TaskManagerRuntime {
+  readonly owner: TaskSpaceOwnerPort;
+}
+
+export interface TaskProcessorResult<Receipt extends TaskCommandReceipt = TaskCommandReceipt> {
+  readonly snapshot: TaskSpaceSnapshot;
+  readonly receipt: Receipt;
+  readonly replayed: boolean;
+}
+
+export async function createTaskSpace<Profile extends TaskProfileEnvelope>(
+  runtime: TaskManagerRuntime,
+  input: CreateTaskSpaceCommand<Profile>,
+  config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  const replay = await replayed<TaskTransitionReceipt>(runtime, input, 'task-transition-receipt');
+  if (replay) return replay;
+  if (input.definition.taskSpaceId !== input.taskSpaceId) {
+    throw new TaskManagerError('cross-space-identity', 'definition and command TaskSpace identities differ');
+  }
+  if (await runtime.owner.readSnapshot(input.taskSpaceId)) {
+    throw new TaskManagerError('task-space-already-exists', `TaskSpace ${input.taskSpaceId} already exists`);
+  }
+  const normalized = normalizeTaskProcessorConfig(config);
+  validateTaskSpaceDefinition(input.definition, normalized);
+  validateTimestamp(input.createdAt, 'createdAt');
+
+  const tasks: TaskRecord[] = input.definition.tasks.map((definition) => ({
+    kind: 'task-record',
+    taskSpaceId: input.taskSpaceId,
+    taskId: definition.taskId,
+    definition,
+    profile: definition.profile,
+    status: predecessorIds(input.definition, definition.taskId).length === 0 ? 'Ready' : 'Pending',
+    attempt: 0,
+    leaseEpoch: 0,
+    activeClaim: null,
+    outputArtifacts: [],
+    createdAt: input.createdAt,
+    updatedAt: input.createdAt,
+  }));
+  const event = {
+    ...eventBase(input, 0, 0, 0, input.createdAt),
+    kind: 'task-space.created',
+  } as const;
+  const receipt: TaskTransitionReceipt = {
+    ...receiptBase(input, 0, 0, input.createdAt, [event.eventId]),
+    kind: 'task-transition-receipt',
+  };
+  const snapshot: TaskSpaceSnapshot = {
+    kind: 'task-space-snapshot',
+    taskSpaceId: input.taskSpaceId,
+    revision: 0,
+    definition: input.definition,
+    tasks,
+    historyEventIds: [event.eventId],
+    issuedReceiptIds: [receipt.receiptId],
+    createdAt: input.createdAt,
+    updatedAt: input.createdAt,
+  };
+  return admit(runtime, input, null, snapshot, [event], receipt, []);
+}
+
+export async function patchTaskSpace<Profile extends TaskProfileEnvelope>(
+  runtime: TaskManagerRuntime,
+  input: PatchTaskSpaceCommand<Profile>,
+  config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  const replay = await replayed<TaskTransitionReceipt>(runtime, input, 'task-transition-receipt');
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  validateTimestamp(input.patchedAt, 'patchedAt');
+  const patch = input.patch;
+  const current = requireTask(snapshot, patch.taskId);
+  let nextDefinition: TaskNodeDefinition;
+  if (patch.kind === 'rename-task') {
+    nextDefinition = {
+      ...current.definition,
+      name: patch.name,
+      ...(patch.description === undefined ? {} : { description: patch.description }),
+    };
+  } else if (patch.kind === 'replace-task-profile') {
+    nextDefinition = { ...current.definition, profile: patch.profile };
+  } else {
+    const hasArtifact = current.definition.inputArtifacts.some(({ digest }) => digest === patch.artifact.digest);
+    nextDefinition = {
+      ...current.definition,
+      inputArtifacts: hasArtifact
+        ? current.definition.inputArtifacts
+        : [...current.definition.inputArtifacts, patch.artifact],
+    };
+  }
+  const definition: TaskSpaceDefinition = {
+    ...snapshot.definition,
+    tasks: snapshot.definition.tasks.map((task) => task.taskId === current.taskId ? nextDefinition : task),
+  };
+  validateTaskSpaceDefinition(definition, normalizeTaskProcessorConfig(config));
+  const nextTasks = snapshot.tasks.map((task) => task.taskId === current.taskId
+    ? { ...task, definition: nextDefinition, profile: nextDefinition.profile, updatedAt: input.patchedAt }
+    : task);
+  const event = {
+    ...nextEventBase(snapshot, input, 0, input.patchedAt),
+    kind: 'task-space.patched',
+    taskId: current.taskId,
+  } as const;
+  const receipt: TaskTransitionReceipt = {
+    ...nextReceiptBase(snapshot, input, input.patchedAt, [event.eventId]),
+    kind: 'task-transition-receipt',
+    taskId: current.taskId,
+  };
+  return admitExisting(runtime, input, snapshot, definition, nextTasks, [event], receipt);
+}
+
+export async function claimTask(
+  runtime: TaskManagerRuntime,
+  input: ClaimTaskCommand,
+  config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskClaimReceipt>> {
+  const replay = await replayed<TaskClaimReceipt>(runtime, input, 'task-claim-receipt');
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  const task = requireTask(snapshot, input.taskId);
+  if (task.definition.kind !== 'task' || task.status !== 'Ready') {
+    throw new TaskManagerError('task-not-ready', `task ${task.taskId} is not a claimable Ready task`);
+  }
+  const normalized = normalizeTaskProcessorConfig(config);
+  if (!Number.isSafeInteger(input.leaseDurationMs)
+    || input.leaseDurationMs <= 0
+    || input.leaseDurationMs > normalized.maxLeaseDurationMs) {
+    throw new TaskManagerError('lease-out-of-range', `leaseDurationMs must be within 1..${normalized.maxLeaseDurationMs}`);
+  }
+  const claimedAtMs = validateTimestamp(input.claimedAt, 'claimedAt');
+  const attempt = task.attempt === 0 ? 1 : task.attempt;
+  const leaseEpoch = task.leaseEpoch === 0 ? 1 : task.leaseEpoch;
+  const claim: TaskClaimToken = {
+    kind: 'task-claim-token',
+    claimId: stableId('claim', input.commandId),
+    taskSpaceId: input.taskSpaceId,
+    taskId: input.taskId,
+    assigneeRef: nonEmpty(input.assigneeRef, 'assigneeRef'),
+    attempt,
+    leaseEpoch,
+    claimedAt: input.claimedAt,
+    heartbeatAt: input.claimedAt,
+    expiresAt: new Date(claimedAtMs + input.leaseDurationMs).toISOString(),
+  };
+  assertTaskTransition(task.taskId, task.status, 'Claimed');
+  const nextTask: TaskRecord = {
+    ...task,
+    status: 'Claimed',
+    attempt,
+    leaseEpoch,
+    activeClaim: claim,
+    updatedAt: input.claimedAt,
+  };
+  const event = {
+    ...stateEventBase(snapshot, input, 0, input.claimedAt, task, 'Claimed'),
+    kind: 'task.claimed',
+    claim,
+  } as const;
+  const receipt: TaskClaimReceipt = {
+    ...nextReceiptBase(snapshot, input, input.claimedAt, [event.eventId]),
+    kind: 'task-claim-receipt',
+    taskId: task.taskId,
+    claim,
+  };
+  return admitExisting(runtime, input, snapshot, snapshot.definition, replaceTask(snapshot, nextTask), [event], receipt);
+}
+
+export async function heartbeatTaskClaim(
+  runtime: TaskManagerRuntime,
+  input: HeartbeatTaskClaimCommand,
+  config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskClaimReceipt>> {
+  const replay = await replayed<TaskClaimReceipt>(runtime, input, 'task-claim-receipt');
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  const task = assertClaimIdentity(snapshot, input.claim);
+  const heartbeatAtMs = validateTimestamp(input.heartbeatAt, 'heartbeatAt');
+  const priorHeartbeatAtMs = validateTimestamp(input.claim.heartbeatAt, 'claim.heartbeatAt');
+  const priorExpiresAtMs = validateTimestamp(input.claim.expiresAt, 'claim.expiresAt');
+  if (heartbeatAtMs <= priorHeartbeatAtMs) {
+    throw new TaskManagerError('claim-token-mismatch', 'heartbeat must advance the live token timestamp');
+  }
+  if (heartbeatAtMs >= priorExpiresAtMs) {
+    throw new TaskManagerError('claim-expired', `claim ${input.claim.claimId} is already expired`);
+  }
+  const normalized = normalizeTaskProcessorConfig(config);
+  if (!Number.isSafeInteger(input.extendByMs)
+    || input.extendByMs <= 0
+    || input.extendByMs > normalized.maxLeaseDurationMs) {
+    throw new TaskManagerError('lease-out-of-range', `extendByMs must be within 1..${normalized.maxLeaseDurationMs}`);
+  }
+  const claim: TaskClaimToken = {
+    ...input.claim,
+    heartbeatAt: input.heartbeatAt,
+    expiresAt: new Date(heartbeatAtMs + input.extendByMs).toISOString(),
+  };
+  const nextTask: TaskRecord = { ...task, activeClaim: claim, updatedAt: input.heartbeatAt };
+  const event = {
+    ...nextEventBase(snapshot, input, 0, input.heartbeatAt),
+    kind: 'task.claim-heartbeat-recorded',
+    taskId: task.taskId,
+    previousClaim: input.claim,
+    claim,
+  } as const;
+  const receipt: TaskClaimReceipt = {
+    ...nextReceiptBase(snapshot, input, input.heartbeatAt, [event.eventId]),
+    kind: 'task-claim-receipt',
+    taskId: task.taskId,
+    claim,
+  };
+  return admitExisting(runtime, input, snapshot, snapshot.definition, replaceTask(snapshot, nextTask), [event], receipt);
+}
+
+export async function expireTaskClaim(
+  runtime: TaskManagerRuntime,
+  input: ExpireTaskClaimCommand,
+  _config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  const replay = await replayed<TaskTransitionReceipt>(runtime, input, 'task-transition-receipt');
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  const task = assertClaimIdentity(snapshot, input.claim);
+  const observedAtMs = validateTimestamp(input.observedAt, 'observedAt');
+  const expiresAtMs = validateTimestamp(input.claim.expiresAt, 'claim.expiresAt');
+  if (observedAtMs < expiresAtMs) {
+    throw new TaskManagerError('claim-not-expired', `claim ${input.claim.claimId} remains live until ${input.claim.expiresAt}`);
+  }
+  assertTaskTransition(task.taskId, task.status, 'Ready');
+  const nextAttempt = task.attempt + 1;
+  const nextLeaseEpoch = task.leaseEpoch + 1;
+  const nextTask: TaskRecord = {
+    ...task,
+    status: 'Ready',
+    attempt: nextAttempt,
+    leaseEpoch: nextLeaseEpoch,
+    activeClaim: null,
+    updatedAt: input.observedAt,
+  };
+  const event = {
+    ...stateEventBase(snapshot, input, 0, input.observedAt, task, 'Ready'),
+    kind: 'task.claim-expired',
+    expiredClaim: input.claim,
+    nextAttempt,
+    nextLeaseEpoch,
+  } as const;
+  const receipt: TaskTransitionReceipt = {
+    ...nextReceiptBase(snapshot, input, input.observedAt, [event.eventId]),
+    kind: 'task-transition-receipt',
+    taskId: task.taskId,
+  };
+  return admitExisting(runtime, input, snapshot, snapshot.definition, replaceTask(snapshot, nextTask), [event], receipt);
+}
+
+export async function startTask(
+  runtime: TaskManagerRuntime,
+  input: StartTaskCommand,
+  _config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  return claimedStateTransition(runtime, input, 'Running', 'task.started', 'task-transition-receipt');
+}
+
+export async function waitTask(
+  runtime: TaskManagerRuntime,
+  input: WaitTaskCommand,
+  _config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  const replay = await replayed<TaskTransitionReceipt>(runtime, input, 'task-transition-receipt');
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  const task = assertClaimIdentity(snapshot, input.claim);
+  assertClaimLive(input.claim, input.occurredAt);
+  assertTaskTransition(task.taskId, task.status, 'Waiting');
+  const nextTask: TaskRecord = {
+    ...task,
+    status: 'Waiting',
+    profile: input.profile ?? task.profile,
+    updatedAt: input.occurredAt,
+  };
+  const event = {
+    ...stateEventBase(snapshot, input, 0, input.occurredAt, task, 'Waiting'),
+    kind: 'task.waiting',
+    claimId: input.claim.claimId,
+    reason: nonEmpty(input.reason, 'reason'),
+    ...(input.details === undefined ? {} : { details: input.details }),
+  } as const;
+  const receipt: TaskTransitionReceipt = {
+    ...nextReceiptBase(snapshot, input, input.occurredAt, [event.eventId]),
+    kind: 'task-transition-receipt',
+    taskId: task.taskId,
+  };
+  return admitExisting(runtime, input, snapshot, snapshot.definition, replaceTask(snapshot, nextTask), [event], receipt);
+}
+
+export async function settleTask(
+  runtime: TaskManagerRuntime,
+  input: SettleTaskCommand,
+  _config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskSettlementReceipt>> {
+  const replay = await replayed<TaskSettlementReceipt>(runtime, input, 'task-settlement-receipt');
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  const task = assertClaimIdentity(snapshot, input.claim);
+  assertClaimLive(input.claim, input.occurredAt);
+  assertTaskTransition(task.taskId, task.status, 'Succeeded');
+  const settled: TaskRecord = {
+    ...task,
+    status: 'Succeeded',
+    profile: input.profile ?? task.profile,
+    activeClaim: null,
+    outputArtifacts: input.outputArtifacts,
+    updatedAt: input.occurredAt,
+  };
+  const tasks = replaceTask(snapshot, settled);
+  const events: TaskHistoryEvent[] = [{
+    ...stateEventBase(snapshot, input, 0, input.occurredAt, task, 'Succeeded'),
+    kind: 'task.settled',
+    claimId: input.claim.claimId,
+    outputArtifacts: input.outputArtifacts,
+    ...(input.result === undefined ? {} : { result: input.result }),
+  }];
+  for (const candidate of tasks) {
+    if (candidate.status !== 'Pending' || !dependenciesSucceeded(snapshot.definition, tasks, candidate.taskId)) continue;
+    const ready = { ...candidate, status: 'Ready' as const, updatedAt: input.occurredAt };
+    tasks.splice(tasks.findIndex(({ taskId }) => taskId === ready.taskId), 1, ready);
+    events.push({
+      ...stateEventBase(snapshot, input, events.length, input.occurredAt, candidate, 'Ready'),
+      kind: 'task.readied',
+    });
+  }
+  const receipt: TaskSettlementReceipt = {
+    ...nextReceiptBase(snapshot, input, input.occurredAt, events.map(({ eventId }) => eventId)),
+    kind: 'task-settlement-receipt',
+    taskId: task.taskId,
+    claimId: input.claim.claimId,
+    status: 'Succeeded',
+  };
+  return admitExisting(runtime, input, snapshot, snapshot.definition, tasks, events, receipt);
+}
+
+export async function failTask(
+  runtime: TaskManagerRuntime,
+  input: FailTaskCommand,
+  _config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskSettlementReceipt>> {
+  const replay = await replayed<TaskSettlementReceipt>(runtime, input, 'task-settlement-receipt');
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  const task = assertClaimIdentity(snapshot, input.claim);
+  assertClaimLive(input.claim, input.occurredAt);
+  assertTaskTransition(task.taskId, task.status, 'Failed');
+  const nextTask: TaskRecord = {
+    ...task,
+    status: 'Failed',
+    profile: input.profile ?? task.profile,
+    activeClaim: null,
+    updatedAt: input.occurredAt,
+  };
+  const event = {
+    ...stateEventBase(snapshot, input, 0, input.occurredAt, task, 'Failed'),
+    kind: 'task.failed',
+    claimId: input.claim.claimId,
+    failure: input.failure,
+  } as const;
+  const receipt: TaskSettlementReceipt = {
+    ...nextReceiptBase(snapshot, input, input.occurredAt, [event.eventId]),
+    kind: 'task-settlement-receipt',
+    taskId: task.taskId,
+    claimId: input.claim.claimId,
+    status: 'Failed',
+  };
+  return admitExisting(runtime, input, snapshot, snapshot.definition, replaceTask(snapshot, nextTask), [event], receipt);
+}
+
+export async function cancelTask(
+  runtime: TaskManagerRuntime,
+  input: CancelTaskCommand,
+  _config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskSettlementReceipt>> {
+  const replay = await replayed<TaskSettlementReceipt>(runtime, input, 'task-settlement-receipt');
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  const task = requireTask(snapshot, input.taskId);
+  if (isTerminal(task.status)) {
+    throw new TaskManagerError('terminal-task-immutable', `task ${task.taskId} is terminal (${task.status})`);
+  }
+  validateTimestamp(input.cancelledAt, 'cancelledAt');
+  if (input.claim) assertClaimIdentity(snapshot, input.claim, task.taskId);
+  assertTaskTransition(task.taskId, task.status, 'Cancelled');
+  const nextTask: TaskRecord = {
+    ...task,
+    status: 'Cancelled',
+    profile: input.profile ?? task.profile,
+    activeClaim: null,
+    updatedAt: input.cancelledAt,
+  };
+  const event = {
+    ...stateEventBase(snapshot, input, 0, input.cancelledAt, task, 'Cancelled'),
+    kind: 'task.cancelled',
+    ...(input.claim === undefined ? {} : { claimId: input.claim.claimId }),
+    reason: nonEmpty(input.reason, 'reason'),
+  } as const;
+  const receipt: TaskSettlementReceipt = {
+    ...nextReceiptBase(snapshot, input, input.cancelledAt, [event.eventId]),
+    kind: 'task-settlement-receipt',
+    taskId: task.taskId,
+    ...(input.claim === undefined ? {} : { claimId: input.claim.claimId }),
+    status: 'Cancelled',
+  };
+  return admitExisting(runtime, input, snapshot, snapshot.definition, replaceTask(snapshot, nextTask), [event], receipt);
+}
+
+export async function replanTask(
+  runtime: TaskManagerRuntime,
+  input: ReplanTaskCommand,
+  config: TaskProcessorConfig,
+): Promise<TaskProcessorResult<TaskReplanReceipt>> {
+  const replay = await replayed<TaskReplanReceipt>(runtime, input, 'task-replan-receipt');
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  validateTimestamp(input.replannedAt, 'replannedAt');
+  const definition: TaskSpaceDefinition = {
+    ...snapshot.definition,
+    tasks: input.plan.tasks,
+    relations: input.plan.relations,
+  };
+  validateTaskSpaceDefinition(definition, normalizeTaskProcessorConfig(config));
+  const nextIds = new Set(definition.tasks.map(({ taskId }) => taskId));
+  for (const prior of snapshot.tasks) {
+    if (!nextIds.has(prior.taskId) && (isTerminal(prior.status) || prior.activeClaim)) {
+      throw new TaskManagerError('terminal-task-immutable', `replan cannot remove durable task ${prior.taskId}`);
+    }
+  }
+  const provisional: TaskRecord[] = definition.tasks.map((nextDefinition) => {
+    const prior = taskRecordById(snapshot, nextDefinition.taskId);
+    if (prior) return { ...prior, definition: nextDefinition, updatedAt: input.replannedAt };
+    return {
+      kind: 'task-record',
+      taskSpaceId: snapshot.taskSpaceId,
+      taskId: nextDefinition.taskId,
+      definition: nextDefinition,
+      profile: nextDefinition.profile,
+      status: 'Pending',
+      attempt: 0,
+      leaseEpoch: 0,
+      activeClaim: null,
+      outputArtifacts: [],
+      createdAt: input.replannedAt,
+      updatedAt: input.replannedAt,
+    };
+  });
+  const nextTasks: TaskRecord[] = provisional.map((task) => {
+    if (isTerminal(task.status) || task.activeClaim || task.status === 'Running' || task.status === 'Waiting') return task;
+    const status: TaskStatus = dependenciesSucceeded(definition, provisional, task.taskId) ? 'Ready' : 'Pending';
+    return { ...task, status };
+  });
+  const affectedTaskIds = [...new Set([...snapshot.tasks.map(({ taskId }) => taskId), ...nextTasks.map(({ taskId }) => taskId)])].sort();
+  const event = {
+    ...nextEventBase(snapshot, input, 0, input.replannedAt),
+    kind: 'task.replanned',
+    planId: input.plan.planId,
+    affectedTaskIds,
+  } as const;
+  const receipt: TaskReplanReceipt = {
+    ...nextReceiptBase(snapshot, input, input.replannedAt, [event.eventId]),
+    kind: 'task-replan-receipt',
+    planId: input.plan.planId,
+    affectedTaskIds,
+  };
+  return admitExisting(runtime, input, snapshot, definition, nextTasks, [event], receipt);
+}
+
+async function claimedStateTransition(
+  runtime: TaskManagerRuntime,
+  input: StartTaskCommand,
+  toStatus: 'Running',
+  eventKind: 'task.started',
+  receiptKind: 'task-transition-receipt',
+): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  const replay = await replayed<TaskTransitionReceipt>(runtime, input, receiptKind);
+  if (replay) return replay;
+  const snapshot = await loadExpected(runtime, input);
+  const task = assertClaimIdentity(snapshot, input.claim);
+  assertClaimLive(input.claim, input.occurredAt);
+  assertTaskTransition(task.taskId, task.status, toStatus);
+  const nextTask: TaskRecord = {
+    ...task,
+    status: toStatus,
+    profile: input.profile ?? task.profile,
+    updatedAt: input.occurredAt,
+  };
+  const event = {
+    ...stateEventBase(snapshot, input, 0, input.occurredAt, task, toStatus),
+    kind: eventKind,
+    claimId: input.claim.claimId,
+  } as const;
+  const receipt: TaskTransitionReceipt = {
+    ...nextReceiptBase(snapshot, input, input.occurredAt, [event.eventId]),
+    kind: receiptKind,
+    taskId: task.taskId,
+  };
+  return admitExisting(runtime, input, snapshot, snapshot.definition, replaceTask(snapshot, nextTask), [event], receipt);
+}
+
+async function replayed<Receipt extends TaskCommandReceipt>(
+  runtime: TaskManagerRuntime,
+  input: TaskCommand,
+  receiptKind: Receipt['kind'],
+): Promise<TaskProcessorResult<Receipt> | undefined> {
+  const receipt = await runtime.owner.readReceiptByCommand(input.taskSpaceId, input.commandId);
+  if (!receipt) return undefined;
+  if (receipt.kind !== receiptKind) {
+    throw new TaskManagerError('command-receipt-mismatch', `command ${input.commandId} was already used for ${receipt.kind}`);
+  }
+  const snapshot = await runtime.owner.readSnapshot(input.taskSpaceId);
+  if (!snapshot) {
+    throw new TaskManagerError('task-space-not-found', `receipt exists without TaskSpace ${input.taskSpaceId}`);
+  }
+  return deepImmutableClone({ snapshot, receipt: receipt as Receipt, replayed: true });
+}
+
+async function loadExpected(
+  runtime: TaskManagerRuntime,
+  input: Exclude<TaskCommand, CreateTaskSpaceCommand>,
+): Promise<TaskSpaceSnapshot> {
+  const snapshot = await runtime.owner.readSnapshot(input.taskSpaceId);
+  if (!snapshot) throw new TaskManagerError('task-space-not-found', `TaskSpace ${input.taskSpaceId} not found`);
+  if (snapshot.taskSpaceId !== input.taskSpaceId || snapshot.definition.taskSpaceId !== input.taskSpaceId) {
+    throw new TaskManagerError('cross-space-identity', 'snapshot contains a cross-space identity');
+  }
+  if (snapshot.revision !== input.expectedRevision) {
+    throw new TaskManagerError(
+      'revision-conflict',
+      `TaskSpace ${input.taskSpaceId} expected revision ${input.expectedRevision}, actual ${snapshot.revision}`,
+    );
+  }
+  return snapshot;
+}
+
+async function admitExisting<Receipt extends TaskCommandReceipt>(
+  runtime: TaskManagerRuntime,
+  input: Exclude<TaskCommand, CreateTaskSpaceCommand>,
+  prior: TaskSpaceSnapshot,
+  definition: TaskSpaceDefinition,
+  tasks: readonly TaskRecord[],
+  events: readonly TaskHistoryEvent[],
+  receipt: Receipt,
+): Promise<TaskProcessorResult<Receipt>> {
+  const snapshot: TaskSpaceSnapshot = {
+    ...prior,
+    revision: prior.revision + 1,
+    definition,
+    tasks,
+    historyEventIds: [...prior.historyEventIds, ...events.map(({ eventId }) => eventId)],
+    issuedReceiptIds: [...prior.issuedReceiptIds, receipt.receiptId],
+    updatedAt: events.at(-1)?.occurredAt ?? prior.updatedAt,
+  };
+  return admit(runtime, input, prior.revision, snapshot, events, receipt, []);
+}
+
+async function admit<Receipt extends TaskCommandReceipt>(
+  runtime: TaskManagerRuntime,
+  input: TaskCommand,
+  expectedRevision: number | null,
+  snapshot: TaskSpaceSnapshot,
+  events: readonly TaskHistoryEvent[],
+  receipt: Receipt,
+  artifacts: readonly TaskArtifactBody[],
+): Promise<TaskProcessorResult<Receipt>> {
+  const result = await runtime.owner.compareAndSwap({
+    kind: 'task-space-commit',
+    taskSpaceId: input.taskSpaceId,
+    expectedRevision,
+    commandId: input.commandId,
+    snapshot,
+    events,
+    receipts: [receipt],
+    artifacts,
+  });
+  if (result.kind === 'revision-conflict') {
+    throw new TaskManagerError(
+      'revision-conflict',
+      `TaskSpace ${input.taskSpaceId} expected revision ${String(result.expectedRevision)}, actual ${String(result.actualRevision)}`,
+    );
+  }
+  if (result.receipt.kind !== receipt.kind) {
+    throw new TaskManagerError('command-receipt-mismatch', `owner returned ${result.receipt.kind}, expected ${receipt.kind}`);
+  }
+  return deepImmutableClone({
+    snapshot: result.snapshot,
+    receipt: result.receipt as Receipt,
+    replayed: result.kind === 'command-replayed',
+  });
+}
+
+function requireTask(snapshot: TaskSpaceSnapshot, taskId: TaskId): TaskRecord {
+  const task = taskRecordById(snapshot, taskId);
+  if (!task) throw new TaskManagerError('task-not-found', `task ${taskId} not found`);
+  if (task.taskSpaceId !== snapshot.taskSpaceId) {
+    throw new TaskManagerError('cross-space-identity', `task ${taskId} belongs to ${task.taskSpaceId}`);
+  }
+  return task;
+}
+
+function replaceTask(snapshot: TaskSpaceSnapshot, replacement: TaskRecord): TaskRecord[] {
+  return snapshot.tasks.map((task) => task.taskId === replacement.taskId ? replacement : task);
+}
+
+function dependenciesSucceeded(
+  definition: TaskSpaceDefinition,
+  tasks: readonly TaskRecord[],
+  taskId: TaskId,
+): boolean {
+  const predecessors = predecessorIds(definition, taskId);
+  return predecessors.length === 0 || predecessors.every((predecessorId) =>
+    tasks.find((task) => task.taskId === predecessorId)?.status === 'Succeeded');
+}
+
+function eventBase(
+  input: TaskCommand,
+  index: number,
+  fromRevision: number,
+  toRevision: number,
+  occurredAt: TaskTimestamp,
+) {
+  return {
+    eventId: stableId('event', input.commandId, index),
+    commandId: input.commandId,
+    taskSpaceId: input.taskSpaceId,
+    sequence: index,
+    fromRevision,
+    toRevision,
+    occurredAt,
+  } as const;
+}
+
+function nextEventBase(
+  snapshot: TaskSpaceSnapshot,
+  input: TaskCommand,
+  index: number,
+  occurredAt: TaskTimestamp,
+) {
+  return {
+    ...eventBase(input, index, snapshot.revision, snapshot.revision + 1, occurredAt),
+    sequence: snapshot.historyEventIds.length + index,
+  } as const;
+}
+
+function stateEventBase(
+  snapshot: TaskSpaceSnapshot,
+  input: TaskCommand,
+  index: number,
+  occurredAt: TaskTimestamp,
+  task: TaskRecord,
+  toStatus: TaskStatus,
+) {
+  return {
+    ...nextEventBase(snapshot, input, index, occurredAt),
+    taskId: task.taskId,
+    fromStatus: task.status,
+    toStatus,
+  } as const;
+}
+
+function receiptBase(
+  input: TaskCommand,
+  fromRevision: number,
+  toRevision: number,
+  committedAt: TaskTimestamp,
+  eventIds: readonly string[],
+) {
+  return {
+    receiptId: stableId('receipt', input.commandId),
+    commandId: input.commandId,
+    taskSpaceId: input.taskSpaceId,
+    fromRevision,
+    toRevision,
+    eventIds,
+    committedAt,
+  } as const;
+}
+
+function nextReceiptBase(
+  snapshot: TaskSpaceSnapshot,
+  input: TaskCommand,
+  committedAt: TaskTimestamp,
+  eventIds: readonly string[],
+) {
+  return receiptBase(input, snapshot.revision, snapshot.revision + 1, committedAt, eventIds);
+}
+
+function stableId(namespace: string, commandId: string, index?: number): string {
+  return `${namespace}:${encodeURIComponent(commandId)}${index === undefined ? '' : `:${index}`}`;
+}
+
+function nonEmpty(value: string, field: string): string {
+  if (value.length === 0 || value.trim() !== value) {
+    throw new TaskManagerError('invalid-task-definition', `${field} must be non-empty and trimmed`);
+  }
+  return value;
+}