task-manager-logic 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-manager-logic",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "description": "Runtime-first TaskSpace transition processors and backend-neutral in-memory owner",
   "type": "module",
@@ -9,7 +9,7 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "task-manager-contract": "0.1.2"
+    "task-manager-contract": "0.1.3"
   },
   "files": [
     "src"

package/src/errors.ts

@@ -1,5 +1,7 @@
 export type TaskManagerErrorCode =
   | 'artifact-conflict'
+  | 'artifact-not-found'
+  | 'canonical-data-invalid'
   | 'claim-expired'
   | 'claim-not-expired'
   | 'claim-token-mismatch'
@@ -28,4 +30,3 @@ export class TaskManagerError extends Error {
     super(`[${code}] ${message}`);
   }
 }
-

package/src/memory-owner.ts

@@ -10,8 +10,9 @@ import type {
   TaskSpaceOwnerPort,
   TaskSpaceSnapshot,
 } from 'task-manager-contract';
+import { canonicalOwnDataDigest } from 'task-manager-contract';
 import { TaskManagerError } from './errors.js';
-import { deepImmutableClone } from './validation.js';
+import { assertArtifactBody, assertArtifactRef, deepImmutableClone } from './validation.js';
 
 interface MemoryTaskSpaceState {
   readonly snapshot: TaskSpaceSnapshot;
@@ -50,9 +51,13 @@ export class InMemoryTaskSpaceOwner implements TaskSpaceOwnerPort {
   }
 
   async compareAndSwap(commit: TaskSpaceCommit): Promise<TaskSpaceCommitResult> {
+    commit = deepImmutableClone(commit);
     const current = this.#spaces.get(commit.taskSpaceId);
     const replay = current?.receiptsByCommand.get(commit.commandId);
     if (current && replay) {
+      if (replay.commandDigest !== commit.commandDigest) {
+        throw new TaskManagerError('command-receipt-mismatch', `command ${commit.commandId} digest does not match prior admission`);
+      }
       return deepImmutableClone({
         kind: 'command-replayed',
         taskSpaceId: commit.taskSpaceId,
@@ -64,12 +69,12 @@ export class InMemoryTaskSpaceOwner implements TaskSpaceOwnerPort {
 
     const actualRevision = current?.snapshot.revision ?? null;
     if (actualRevision !== commit.expectedRevision) {
-      return {
+      return deepImmutableClone({
         kind: 'revision-conflict',
         taskSpaceId: commit.taskSpaceId,
         expectedRevision: commit.expectedRevision,
         actualRevision,
-      };
+      });
     }
 
     const receipt = validateCommit(commit, current);
@@ -106,6 +111,9 @@ function validateCommit(
 ): TaskCommandReceipt {
   const expectedNextRevision = commit.expectedRevision === null ? 0 : commit.expectedRevision + 1;
   if (commit.kind !== 'task-space-commit'
+    || commit.command.commandId !== commit.commandId
+    || commit.command.taskSpaceId !== commit.taskSpaceId
+    || canonicalOwnDataDigest(commit.command) !== commit.commandDigest
     || commit.snapshot.taskSpaceId !== commit.taskSpaceId
     || commit.snapshot.definition.taskSpaceId !== commit.taskSpaceId
     || commit.snapshot.revision !== expectedNextRevision) {
@@ -113,7 +121,10 @@ function validateCommit(
   }
   if (commit.receipts.length !== 1) invalid('one command admission must contain exactly one receipt');
   const receipt = commit.receipts[0];
-  if (!receipt || receipt.commandId !== commit.commandId || receipt.taskSpaceId !== commit.taskSpaceId) {
+  if (!receipt
+    || receipt.commandId !== commit.commandId
+    || receipt.commandDigest !== commit.commandDigest
+    || receipt.taskSpaceId !== commit.taskSpaceId) {
     invalid('commit receipt does not match command identity');
   }
   if (receipt.toRevision !== expectedNextRevision) invalid('receipt toRevision does not match snapshot');
@@ -139,6 +150,27 @@ function validateCommit(
     }
     seenEvents.add(event.eventId);
   }
+  const availableArtifacts = new Map(current?.artifacts ?? []);
+  for (const body of commit.artifacts) {
+    assertArtifactBody(body, `artifact body ${body.digest}`);
+    const prior = availableArtifacts.get(body.digest);
+    if (prior && canonicalOwnDataDigest(prior) !== canonicalOwnDataDigest(body)) {
+      throw new TaskManagerError('artifact-conflict', `artifact ${body.digest} has conflicting content`);
+    }
+    availableArtifacts.set(body.digest, body);
+  }
+  const refs = [
+    ...commit.snapshot.definition.tasks.flatMap(({ inputArtifacts }) => inputArtifacts),
+    ...commit.snapshot.tasks.flatMap(({ outputArtifacts }) => outputArtifacts),
+  ];
+  for (const ref of refs) {
+    assertArtifactRef(ref, `artifact ref ${ref.digest}`);
+    const body = availableArtifacts.get(ref.digest);
+    if (!body) throw new TaskManagerError('artifact-not-found', `artifact ${ref.digest} is not present in owner CAS`);
+    if (body.mediaType !== ref.mediaType || body.sizeBytes !== ref.sizeBytes) {
+      throw new TaskManagerError('artifact-conflict', `artifact ${ref.digest} metadata disagrees with owner body`);
+    }
+  }
   return receipt;
 }
 
@@ -157,4 +189,3 @@ function sameArtifact(left: TaskArtifactBody, right: TaskArtifactBody): boolean
 function invalid(message: string): never {
   throw new TaskManagerError('invalid-commit', message);
 }
-

package/src/processors.ts

@@ -10,6 +10,7 @@ import type {
   SettleTaskCommand,
   StartTaskCommand,
   TaskArtifactBody,
+  TaskArtifactRef,
   TaskClaimReceipt,
   TaskClaimToken,
   TaskCommand,
@@ -29,11 +30,14 @@ import type {
   TaskTransitionReceipt,
   WaitTaskCommand,
 } from 'task-manager-contract';
+import { canonicalOwnDataDigest } from 'task-manager-contract';
 import { TaskManagerError } from './errors.js';
 import { assertTaskTransition, isTerminal } from './statusMachine.js';
 import {
   assertClaimIdentity,
   assertClaimLive,
+  assertArtifactBody,
+  assertArtifactRef,
   deepImmutableClone,
   normalizeTaskProcessorConfig,
   predecessorIds,
@@ -58,6 +62,7 @@ export async function createTaskSpace<Profile extends TaskProfileEnvelope>(
   input: CreateTaskSpaceCommand<Profile>,
   config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  input = canonicalCommand(input);
   const replay = await replayed<TaskTransitionReceipt>(runtime, input, 'task-transition-receipt');
   if (replay) return replay;
   if (input.definition.taskSpaceId !== input.taskSpaceId) {
@@ -70,13 +75,16 @@ export async function createTaskSpace<Profile extends TaskProfileEnvelope>(
   validateTaskSpaceDefinition(input.definition, normalized);
   validateTimestamp(input.createdAt, 'createdAt');
 
-  const tasks: TaskRecord[] = input.definition.tasks.map((definition) => ({
+  const artifactBodies = input.artifactBodies ?? [];
+  await assertArtifactAuthority(runtime.owner, input.taskSpaceId, input.definition.tasks.flatMap(({ inputArtifacts }) => inputArtifacts), artifactBodies);
+
+  const provisional: 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',
+    status: 'Pending',
     attempt: 0,
     leaseEpoch: 0,
     activeClaim: null,
@@ -84,6 +92,7 @@ export async function createTaskSpace<Profile extends TaskProfileEnvelope>(
     createdAt: input.createdAt,
     updatedAt: input.createdAt,
   }));
+  const tasks = stabilizeTaskProjection(input.definition, provisional);
   const event = {
     ...eventBase(input, 0, 0, 0, input.createdAt),
     kind: 'task-space.created',
@@ -103,7 +112,7 @@ export async function createTaskSpace<Profile extends TaskProfileEnvelope>(
     createdAt: input.createdAt,
     updatedAt: input.createdAt,
   };
-  return admit(runtime, input, null, snapshot, [event], receipt, []);
+  return admit(runtime, input, null, snapshot, [event], receipt, artifactBodies);
 }
 
 export async function patchTaskSpace<Profile extends TaskProfileEnvelope>(
@@ -111,12 +120,22 @@ export async function patchTaskSpace<Profile extends TaskProfileEnvelope>(
   input: PatchTaskSpaceCommand<Profile>,
   config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  input = canonicalCommand(input);
   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);
+  if (patch.kind === 'replace-task-profile' && isTerminal(current.status)) {
+    throw new TaskManagerError('terminal-task-immutable', `task ${current.taskId} is terminal (${current.status})`);
+  }
+  if (patch.kind === 'replace-task-profile') {
+    throw new TaskManagerError(
+      'invalid-task-transition',
+      `task ${current.taskId} profile may change only through a kernel lifecycle Processor`,
+    );
+  }
   let nextDefinition: TaskNodeDefinition;
   if (patch.kind === 'rename-task') {
     nextDefinition = {
@@ -124,8 +143,6 @@ export async function patchTaskSpace<Profile extends TaskProfileEnvelope>(
       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 = {
@@ -140,6 +157,8 @@ export async function patchTaskSpace<Profile extends TaskProfileEnvelope>(
     tasks: snapshot.definition.tasks.map((task) => task.taskId === current.taskId ? nextDefinition : task),
   };
   validateTaskSpaceDefinition(definition, normalizeTaskProcessorConfig(config));
+  const artifactBodies = input.artifactBodies ?? [];
+  await assertArtifactAuthority(runtime.owner, input.taskSpaceId, definition.tasks.flatMap(({ inputArtifacts }) => inputArtifacts), artifactBodies);
   const nextTasks = snapshot.tasks.map((task) => task.taskId === current.taskId
     ? { ...task, definition: nextDefinition, profile: nextDefinition.profile, updatedAt: input.patchedAt }
     : task);
@@ -153,7 +172,7 @@ export async function patchTaskSpace<Profile extends TaskProfileEnvelope>(
     kind: 'task-transition-receipt',
     taskId: current.taskId,
   };
-  return admitExisting(runtime, input, snapshot, definition, nextTasks, [event], receipt);
+  return admitExisting(runtime, input, snapshot, definition, nextTasks, [event], receipt, artifactBodies);
 }
 
 export async function claimTask(
@@ -161,6 +180,7 @@ export async function claimTask(
   input: ClaimTaskCommand,
   config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskClaimReceipt>> {
+  input = canonicalCommand(input);
   const replay = await replayed<TaskClaimReceipt>(runtime, input, 'task-claim-receipt');
   if (replay) return replay;
   const snapshot = await loadExpected(runtime, input);
@@ -217,6 +237,7 @@ export async function heartbeatTaskClaim(
   input: HeartbeatTaskClaimCommand,
   config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskClaimReceipt>> {
+  input = canonicalCommand(input);
   const replay = await replayed<TaskClaimReceipt>(runtime, input, 'task-claim-receipt');
   if (replay) return replay;
   const snapshot = await loadExpected(runtime, input);
@@ -263,6 +284,7 @@ export async function expireTaskClaim(
   input: ExpireTaskClaimCommand,
   _config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  input = canonicalCommand(input);
   const replay = await replayed<TaskTransitionReceipt>(runtime, input, 'task-transition-receipt');
   if (replay) return replay;
   const snapshot = await loadExpected(runtime, input);
@@ -303,6 +325,7 @@ export async function startTask(
   input: StartTaskCommand,
   _config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  input = canonicalCommand(input);
   return claimedStateTransition(runtime, input, 'Running', 'task.started', 'task-transition-receipt');
 }
 
@@ -311,6 +334,7 @@ export async function waitTask(
   input: WaitTaskCommand,
   _config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskTransitionReceipt>> {
+  input = canonicalCommand(input);
   const replay = await replayed<TaskTransitionReceipt>(runtime, input, 'task-transition-receipt');
   if (replay) return replay;
   const snapshot = await loadExpected(runtime, input);
@@ -343,12 +367,15 @@ export async function settleTask(
   input: SettleTaskCommand,
   _config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskSettlementReceipt>> {
+  input = canonicalCommand(input);
   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 artifactBodies = input.artifactBodies ?? [];
+  await assertArtifactAuthority(runtime.owner, input.taskSpaceId, input.outputArtifacts, artifactBodies);
   const settled: TaskRecord = {
     ...task,
     status: 'Succeeded',
@@ -365,15 +392,6 @@ export async function settleTask(
     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',
@@ -381,7 +399,7 @@ export async function settleTask(
     claimId: input.claim.claimId,
     status: 'Succeeded',
   };
-  return admitExisting(runtime, input, snapshot, snapshot.definition, tasks, events, receipt);
+  return admitExisting(runtime, input, snapshot, snapshot.definition, tasks, events, receipt, artifactBodies);
 }
 
 export async function failTask(
@@ -389,6 +407,7 @@ export async function failTask(
   input: FailTaskCommand,
   _config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskSettlementReceipt>> {
+  input = canonicalCommand(input);
   const replay = await replayed<TaskSettlementReceipt>(runtime, input, 'task-settlement-receipt');
   if (replay) return replay;
   const snapshot = await loadExpected(runtime, input);
@@ -423,6 +442,7 @@ export async function cancelTask(
   input: CancelTaskCommand,
   _config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskSettlementReceipt>> {
+  input = canonicalCommand(input);
   const replay = await replayed<TaskSettlementReceipt>(runtime, input, 'task-settlement-receipt');
   if (replay) return replay;
   const snapshot = await loadExpected(runtime, input);
@@ -461,6 +481,7 @@ export async function replanTask(
   input: ReplanTaskCommand,
   config: TaskProcessorConfig,
 ): Promise<TaskProcessorResult<TaskReplanReceipt>> {
+  input = canonicalCommand(input);
   const replay = await replayed<TaskReplanReceipt>(runtime, input, 'task-replan-receipt');
   if (replay) return replay;
   const snapshot = await loadExpected(runtime, input);
@@ -471,6 +492,8 @@ export async function replanTask(
     relations: input.plan.relations,
   };
   validateTaskSpaceDefinition(definition, normalizeTaskProcessorConfig(config));
+  const artifactBodies = input.artifactBodies ?? [];
+  await assertArtifactAuthority(runtime.owner, input.taskSpaceId, definition.tasks.flatMap(({ inputArtifacts }) => inputArtifacts), artifactBodies);
   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)) {
@@ -513,7 +536,7 @@ export async function replanTask(
     planId: input.plan.planId,
     affectedTaskIds,
   };
-  return admitExisting(runtime, input, snapshot, definition, nextTasks, [event], receipt);
+  return admitExisting(runtime, input, snapshot, definition, nextTasks, [event], receipt, artifactBodies);
 }
 
 async function claimedStateTransition(
@@ -555,8 +578,12 @@ async function replayed<Receipt extends TaskCommandReceipt>(
 ): 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 commandDigest = canonicalOwnDataDigest(input);
+  if (receipt.kind !== receiptKind || receipt.commandDigest !== commandDigest) {
+    throw new TaskManagerError(
+      'command-receipt-mismatch',
+      `command ${input.commandId} was already used for a different canonical command`,
+    );
   }
   const snapshot = await runtime.owner.readSnapshot(input.taskSpaceId);
   if (!snapshot) {
@@ -591,17 +618,43 @@ async function admitExisting<Receipt extends TaskCommandReceipt>(
   tasks: readonly TaskRecord[],
   events: readonly TaskHistoryEvent[],
   receipt: Receipt,
+  artifacts: readonly TaskArtifactBody[] = [],
 ): Promise<TaskProcessorResult<Receipt>> {
+  const occurredAt = events.at(-1)?.occurredAt ?? prior.updatedAt;
+  const stabilizedTasks = stabilizeTaskProjection(definition, tasks, occurredAt);
+  const projectedEvents: TaskHistoryEvent[] = [];
+  for (const next of stabilizedTasks) {
+    const previous = prior.tasks.find(({ taskId }) => taskId === next.taskId);
+    if (!previous || previous.status === next.status) continue;
+    if (events.some((event) => 'taskId' in event && event.taskId === next.taskId && 'toStatus' in event && event.toStatus === next.status)) {
+      continue;
+    }
+    const index = events.length + projectedEvents.length;
+    projectedEvents.push(next.definition.kind === 'task-group'
+      ? {
+        ...stateEventBase(prior, input, index, occurredAt, previous, next.status),
+        kind: 'task.group-status-projected',
+      }
+      : {
+        ...stateEventBase(prior, input, index, occurredAt, previous, next.status),
+        kind: 'task.readied',
+      });
+  }
+  const admittedEvents = [...events, ...projectedEvents];
+  const admittedReceipt = {
+    ...receipt,
+    eventIds: admittedEvents.map(({ eventId }) => eventId),
+  } as 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,
+    tasks: stabilizedTasks,
+    historyEventIds: [...prior.historyEventIds, ...admittedEvents.map(({ eventId }) => eventId)],
+    issuedReceiptIds: [...prior.issuedReceiptIds, admittedReceipt.receiptId],
+    updatedAt: occurredAt,
   };
-  return admit(runtime, input, prior.revision, snapshot, events, receipt, []);
+  return admit(runtime, input, prior.revision, snapshot, admittedEvents, admittedReceipt, artifacts);
 }
 
 async function admit<Receipt extends TaskCommandReceipt>(
@@ -618,6 +671,8 @@ async function admit<Receipt extends TaskCommandReceipt>(
     taskSpaceId: input.taskSpaceId,
     expectedRevision,
     commandId: input.commandId,
+    commandDigest: canonicalOwnDataDigest(input),
+    command: input,
     snapshot,
     events,
     receipts: [receipt],
@@ -657,7 +712,7 @@ function dependenciesSucceeded(
   tasks: readonly TaskRecord[],
   taskId: TaskId,
 ): boolean {
-  const predecessors = predecessorIds(definition, taskId);
+  const predecessors = effectivePredecessorIds(definition, taskId);
   return predecessors.length === 0 || predecessors.every((predecessorId) =>
     tasks.find((task) => task.taskId === predecessorId)?.status === 'Succeeded');
 }
@@ -718,6 +773,7 @@ function receiptBase(
   return {
     receiptId: stableId('receipt', input.commandId),
     commandId: input.commandId,
+    commandDigest: canonicalOwnDataDigest(input),
     taskSpaceId: input.taskSpaceId,
     fromRevision,
     toRevision,
@@ -745,3 +801,121 @@ function nonEmpty(value: string, field: string): string {
   }
   return value;
 }
+
+function canonicalCommand<Command extends TaskCommand>(input: Command): Command {
+  return deepImmutableClone(input);
+}
+
+async function assertArtifactAuthority(
+  owner: TaskSpaceOwnerPort,
+  taskSpaceId: string,
+  refs: readonly TaskArtifactRef[],
+  bodies: readonly TaskArtifactBody[],
+): Promise<void> {
+  const supplied = new Map<string, TaskArtifactBody>();
+  for (const body of bodies) {
+    assertArtifactBody(body, `artifact body ${body.digest}`);
+    const prior = supplied.get(body.digest);
+    if (prior && canonicalOwnDataDigest(prior) !== canonicalOwnDataDigest(body)) {
+      throw new TaskManagerError('artifact-conflict', `artifact ${body.digest} has conflicting bodies`);
+    }
+    supplied.set(body.digest, body);
+  }
+  for (const ref of refs) {
+    assertArtifactRef(ref, `artifact ref ${ref.digest}`);
+    const body = supplied.get(ref.digest) ?? await owner.readArtifact(taskSpaceId, ref.digest);
+    if (!body) throw new TaskManagerError('artifact-not-found', `artifact ${ref.digest} is not present in this owner admission`);
+    if (body.digest !== ref.digest || body.mediaType !== ref.mediaType || body.sizeBytes !== ref.sizeBytes) {
+      throw new TaskManagerError('artifact-conflict', `artifact ${ref.digest} metadata disagrees with its body`);
+    }
+  }
+}
+
+function effectivePredecessorIds(definition: TaskSpaceDefinition, taskId: TaskId): readonly TaskId[] {
+  const result = new Set(predecessorIds(definition, taskId));
+  const parentByChild = new Map<TaskId, TaskId | null>();
+  const childrenByParent = new Map<TaskId, { readonly taskId: TaskId; readonly order: number }[]>();
+  for (const relation of definition.relations) {
+    if (relation.kind !== 'parent-child') continue;
+    parentByChild.set(relation.childTaskId, relation.parentTaskId);
+    if (relation.parentTaskId !== null) {
+      const children = childrenByParent.get(relation.parentTaskId) ?? [];
+      children.push({ taskId: relation.childTaskId, order: relation.order });
+      childrenByParent.set(relation.parentTaskId, children);
+    }
+  }
+  let current: TaskId | null | undefined = taskId;
+  while (current !== null && current !== undefined) {
+    const parent = parentByChild.get(current);
+    if (parent === null || parent === undefined) break;
+    for (const predecessor of predecessorIds(definition, parent)) result.add(predecessor);
+    const parentDefinition = definition.tasks.find(({ taskId: candidate }) => candidate === parent);
+    if (parentDefinition?.kind === 'task-group' && parentDefinition.mode === 'sequential') {
+      const siblings = [...(childrenByParent.get(parent) ?? [])]
+        .sort((left, right) => left.order - right.order || left.taskId.localeCompare(right.taskId));
+      const index = siblings.findIndex(({ taskId: candidate }) => candidate === current);
+      if (index > 0) result.add(siblings[index - 1]!.taskId);
+    }
+    current = parent;
+  }
+  return [...result];
+}
+
+function stabilizeTaskProjection(
+  definition: TaskSpaceDefinition,
+  inputTasks: readonly TaskRecord[],
+  projectedAt?: TaskTimestamp,
+): TaskRecord[] {
+  let tasks = inputTasks.map((task) => ({ ...task }));
+  const childrenByParent = new Map<TaskId, TaskId[]>();
+  for (const relation of definition.relations) {
+    if (relation.kind !== 'parent-child' || relation.parentTaskId === null) continue;
+    const children = childrenByParent.get(relation.parentTaskId) ?? [];
+    children.push(relation.childTaskId);
+    childrenByParent.set(relation.parentTaskId, children);
+  }
+  for (let iteration = 0; iteration <= tasks.length * 2; iteration += 1) {
+    let changed = false;
+    const next = tasks.map((task) => {
+      let status = task.status;
+      if (task.definition.kind === 'task') {
+        if (status === 'Pending' || status === 'Ready') {
+          status = dependenciesSucceeded(definition, tasks, task.taskId) ? 'Ready' : 'Pending';
+        }
+      } else {
+        const childStatuses = (childrenByParent.get(task.taskId) ?? [])
+          .map((childId) => tasks.find(({ taskId }) => taskId === childId)!.status);
+        status = projectGroupStatus(task.definition.mode, childStatuses,
+          dependenciesSucceeded(definition, tasks, task.taskId));
+        if (isTerminal(task.status) && status !== task.status) {
+          throw new TaskManagerError('terminal-task-immutable', `task-group ${task.taskId} is terminal (${task.status})`);
+        }
+      }
+      if (status === task.status) return task;
+      changed = true;
+      return { ...task, status, ...(projectedAt === undefined ? {} : { updatedAt: projectedAt }) };
+    });
+    tasks = next;
+    if (!changed) return tasks;
+  }
+  throw new TaskManagerError('cyclic-task-forest', 'TaskGroup projection did not converge');
+}
+
+function projectGroupStatus(
+  mode: 'sequential' | 'all' | 'any',
+  childStatuses: readonly TaskStatus[],
+  dependenciesAreSatisfied: boolean,
+): TaskStatus {
+  if (!dependenciesAreSatisfied) return 'Pending';
+  if (mode === 'any') {
+    if (childStatuses.some((status) => status === 'Succeeded')) return 'Succeeded';
+    if (childStatuses.every(isTerminal)) return 'Failed';
+  } else {
+    if (childStatuses.some((status) => status === 'Failed' || status === 'Cancelled')) return 'Failed';
+    if (childStatuses.every((status) => status === 'Succeeded')) return 'Succeeded';
+  }
+  if (childStatuses.some((status) => status === 'Claimed' || status === 'Running')) return 'Running';
+  if (childStatuses.some((status) => status === 'Waiting')) return 'Waiting';
+  if (childStatuses.some((status) => status === 'Ready')) return 'Ready';
+  return 'Pending';
+}

package/src/validation.ts

@@ -1,4 +1,6 @@
 import type {
+  TaskArtifactBody,
+  TaskArtifactRef,
   TaskClaimToken,
   TaskDefinition,
   TaskId,
@@ -10,6 +12,7 @@ import type {
   TaskSpaceSnapshot,
   TaskTimestamp,
 } from 'task-manager-contract';
+import { deepFrozenCanonicalOwnDataClone, sha256Hex } from 'task-manager-contract';
 import { TaskManagerError } from './errors.js';
 
 export interface TaskProcessorConfig {
@@ -56,6 +59,7 @@ export function validateTaskSpaceDefinition(
 
   const relationIds = new Set<string>();
   const parentByChild = new Map<TaskId, TaskId | null>();
+  const childrenByParent = new Map<TaskId, TaskId[]>();
   const dependencyEdges = new Map<TaskId, TaskId[]>();
   for (const relation of definition.relations) {
     assertNonEmpty(relation.relationId, 'relationId');
@@ -70,6 +74,9 @@ export function validateTaskSpaceDefinition(
         if (!parent) invalid(`parent relation references missing parent ${relation.parentTaskId}`);
         if (parent.kind !== 'task-group') invalid(`parent ${relation.parentTaskId} is not a task-group`);
         if (relation.parentTaskId === relation.childTaskId) cyclic(`task ${relation.childTaskId} parents itself`);
+        const children = childrenByParent.get(relation.parentTaskId) ?? [];
+        children.push(relation.childTaskId);
+        childrenByParent.set(relation.parentTaskId, children);
       }
       parentByChild.set(relation.childTaskId, relation.parentTaskId);
       continue;
@@ -91,6 +98,33 @@ export function validateTaskSpaceDefinition(
     return parent === null || parent === undefined ? [] : [parent];
   });
   assertAcyclic(tasks.keys(), (id) => dependencyEdges.get(id) ?? []);
+
+  for (const task of tasks.values()) {
+    if (task.kind === 'task-group' && (childrenByParent.get(task.taskId)?.length ?? 0) === 0) {
+      invalid(`task-group ${task.taskId} must contain at least one child`);
+    }
+  }
+  const authorityEdges = new Map<TaskId, TaskId[]>();
+  const addAuthorityEdge = (from: TaskId, to: TaskId): void => {
+    const outgoing = authorityEdges.get(from) ?? [];
+    outgoing.push(to);
+    authorityEdges.set(from, outgoing);
+  };
+  for (const [parent, children] of childrenByParent) {
+    for (const child of children) addAuthorityEdge(child, parent);
+  }
+  const descendants = (taskId: TaskId): TaskId[] => (childrenByParent.get(taskId) ?? [])
+    .flatMap((child) => [child, ...descendants(child)]);
+  for (const relation of definition.relations) {
+    if (relation.kind !== 'dependency') continue;
+    addAuthorityEdge(relation.predecessorTaskId, relation.successorTaskId);
+    if (tasks.get(relation.successorTaskId)?.kind === 'task-group') {
+      for (const descendant of descendants(relation.successorTaskId)) {
+        addAuthorityEdge(relation.predecessorTaskId, descendant);
+      }
+    }
+  }
+  assertAcyclic(tasks.keys(), (id) => authorityEdges.get(id) ?? []);
 }
 
 export function taskDefinitionById(
@@ -160,7 +194,11 @@ export function sameClaim(left: TaskClaimToken, right: TaskClaimToken): boolean
 }
 
 export function deepImmutableClone<Value>(value: Value): Value {
-  return deepFreeze(structuredClone(value));
+  try {
+    return deepFrozenCanonicalOwnDataClone(value);
+  } catch (error) {
+    throw new TaskManagerError('canonical-data-invalid', String(error));
+  }
 }
 
 function assertTaskDefinition(task: TaskNodeDefinition): asserts task is TaskDefinition | Exclude<TaskNodeDefinition, TaskDefinition> {
@@ -171,13 +209,32 @@ function assertTaskDefinition(task: TaskNodeDefinition): asserts task is TaskDef
     invalid(`task-group ${task.taskId} has invalid mode`);
   }
   assertProfile(task.profile, task.taskId);
-  for (const artifact of task.inputArtifacts) {
-    if (!artifact.digest.startsWith('sha256:') || artifact.digest.length <= 'sha256:'.length) {
-      invalid(`task ${task.taskId} has invalid artifact digest`);
-    }
-    if (!Number.isSafeInteger(artifact.sizeBytes) || artifact.sizeBytes < 0) {
-      invalid(`task ${task.taskId} has invalid artifact size`);
-    }
+  for (const artifact of task.inputArtifacts) assertArtifactRef(artifact, `task ${task.taskId} input artifact`);
+}
+
+export function assertArtifactRef(artifact: TaskArtifactRef, field: string): void {
+  if (artifact.kind !== 'task-artifact-ref' || !/^sha256:[a-f0-9]{64}$/.test(artifact.digest)) {
+    invalid(`${field} has invalid digest`);
+  }
+  assertNonEmpty(artifact.mediaType, `${field} mediaType`);
+  if (!Number.isSafeInteger(artifact.sizeBytes) || artifact.sizeBytes < 0) invalid(`${field} has invalid size`);
+  if (artifact.name !== undefined) assertNonEmpty(artifact.name, `${field} name`);
+}
+
+export function assertArtifactBody(body: TaskArtifactBody, field: string): void {
+  if (body.kind !== 'task-artifact-body' || body.encoding !== 'base64') invalid(`${field} has invalid encoding`);
+  assertNonEmpty(body.mediaType, `${field} mediaType`);
+  if (!Number.isSafeInteger(body.sizeBytes) || body.sizeBytes < 0) invalid(`${field} has invalid size`);
+  let binary: string;
+  try {
+    binary = atob(body.data);
+  } catch {
+    invalid(`${field} has invalid base64`);
+  }
+  if (btoa(binary) !== body.data) invalid(`${field} base64 is not canonical`);
+  const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+  if (bytes.byteLength !== body.sizeBytes || `sha256:${sha256Hex(bytes)}` !== body.digest) {
+    invalid(`${field} digest or size mismatch`);
   }
 }
 
@@ -219,12 +276,3 @@ function invalid(message: string): never {
 function cyclic(message: string): never {
   throw new TaskManagerError('cyclic-task-forest', message);
 }
-
-function deepFreeze<Value>(value: Value): Value {
-  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
-    for (const child of Object.values(value as Record<string, unknown>)) deepFreeze(child);
-    Object.freeze(value);
-  }
-  return value;
-}
-