task-manager-logic 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-manager-logic",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "description": "Runtime-first TaskSpace transition processors and backend-neutral in-memory owner",
   "type": "module",

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './errors.js';
 export * from './statusMachine.js';
 export * from './validation.js';
+export * from './owner-admission.js';
 export * from './memory-owner.js';
 export * from './processors.js';

package/src/memory-owner.ts

@@ -10,9 +10,12 @@ import type {
   TaskSpaceOwnerPort,
   TaskSpaceSnapshot,
 } from 'task-manager-contract';
-import { canonicalOwnDataDigest } from 'task-manager-contract';
 import { TaskManagerError } from './errors.js';
-import { assertArtifactBody, assertArtifactRef, deepImmutableClone } from './validation.js';
+import {
+  validateTaskSpaceCommitAdmission,
+  validateTaskSpaceCommitCommand,
+} from './owner-admission.js';
+import { deepImmutableClone } from './validation.js';
 
 interface MemoryTaskSpaceState {
   readonly snapshot: TaskSpaceSnapshot;
@@ -52,7 +55,7 @@ export class InMemoryTaskSpaceOwner implements TaskSpaceOwnerPort {
 
   async compareAndSwap(commit: TaskSpaceCommit): Promise<TaskSpaceCommitResult> {
     commit = deepImmutableClone(commit);
-    const submittedCommandDigest = validateSubmittedCommand(commit);
+    const submittedCommandDigest = validateTaskSpaceCommitCommand(commit);
     const current = this.#spaces.get(commit.taskSpaceId);
     const replay = current?.receiptsByCommand.get(commit.commandId);
     if (current && replay) {
@@ -78,7 +81,10 @@ export class InMemoryTaskSpaceOwner implements TaskSpaceOwnerPort {
       });
     }
 
-    const receipt = validateCommit(commit, current);
+    const receipt = validateTaskSpaceCommitAdmission(commit, {
+      ...(current === undefined ? {} : { currentSnapshot: current.snapshot }),
+      existingArtifacts: current?.artifacts ?? new Map(),
+    });
     const receiptsByCommand = new Map(current?.receiptsByCommand ?? []);
     for (const candidate of commit.receipts) receiptsByCommand.set(candidate.commandId, deepImmutableClone(candidate));
     const artifacts = new Map(current?.artifacts ?? []);
@@ -106,95 +112,6 @@ export class InMemoryTaskSpaceOwner implements TaskSpaceOwnerPort {
   }
 }
 
-function validateSubmittedCommand(commit: TaskSpaceCommit): `sha256:${string}` {
-  if (commit.kind !== 'task-space-commit'
-    || commit.command.commandId !== commit.commandId
-    || commit.command.taskSpaceId !== commit.taskSpaceId) {
-    throw new TaskManagerError('command-receipt-mismatch', 'submitted command identity does not match its CAS envelope');
-  }
-  const commandDigest = canonicalOwnDataDigest(commit.command);
-  if (commandDigest !== commit.commandDigest) {
-    throw new TaskManagerError(
-      'command-receipt-mismatch',
-      `command ${commit.commandId} digest does not match the submitted canonical command`,
-    );
-  }
-  return commandDigest;
-}
-
-function validateCommit(
-  commit: TaskSpaceCommit,
-  current: MemoryTaskSpaceState | undefined,
-): 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) {
-    invalid('commit snapshot identity or revision is inconsistent');
-  }
-  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.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');
-  if (receipt.fromRevision !== (commit.expectedRevision ?? 0)) invalid('receipt fromRevision does not match CAS');
-
-  const priorHistoryIds = current?.snapshot.historyEventIds ?? [];
-  const expectedHistoryIds = [...priorHistoryIds, ...commit.events.map(({ eventId }) => eventId)];
-  if (!sameStrings(commit.snapshot.historyEventIds, expectedHistoryIds)) invalid('snapshot history is not append-only');
-  const priorReceiptIds = current?.snapshot.issuedReceiptIds ?? [];
-  const expectedReceiptIds = [...priorReceiptIds, ...commit.receipts.map(({ receiptId }) => receiptId)];
-  if (!sameStrings(commit.snapshot.issuedReceiptIds, expectedReceiptIds)) invalid('snapshot receipt history is not append-only');
-
-  const seenEvents = new Set(priorHistoryIds);
-  for (let index = 0; index < commit.events.length; index += 1) {
-    const event = commit.events[index]!;
-    if (event.taskSpaceId !== commit.taskSpaceId
-      || event.commandId !== commit.commandId
-      || event.sequence !== priorHistoryIds.length + index
-      || event.fromRevision !== (commit.expectedRevision ?? 0)
-      || event.toRevision !== expectedNextRevision
-      || seenEvents.has(event.eventId)) {
-      invalid(`event ${event.eventId} violates append-only commit identity`);
-    }
-    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;
-}
-
-function sameStrings(left: readonly string[], right: readonly string[]): boolean {
-  return left.length === right.length && left.every((value, index) => value === right[index]);
-}
-
 function sameArtifact(left: TaskArtifactBody, right: TaskArtifactBody): boolean {
   return left.digest === right.digest
     && left.mediaType === right.mediaType
@@ -202,7 +119,3 @@ function sameArtifact(left: TaskArtifactBody, right: TaskArtifactBody): boolean
     && left.encoding === right.encoding
     && left.data === right.data;
 }
-
-function invalid(message: string): never {
-  throw new TaskManagerError('invalid-commit', message);
-}

package/src/owner-admission.ts

@@ -0,0 +1,189 @@
+import type {
+  TaskArtifactBody,
+  TaskArtifactDigest,
+  TaskArtifactRef,
+  TaskCommandDigest,
+  TaskCommandReceipt,
+  TaskSpaceCommit,
+  TaskSpaceSnapshot,
+} from 'task-manager-contract';
+import { canonicalOwnDataDigest } from 'task-manager-contract';
+import { TaskManagerError } from './errors.js';
+import { assertArtifactBody, assertArtifactRef } from './validation.js';
+
+export interface TaskSpaceCommitAdmissionContext {
+  readonly currentSnapshot?: TaskSpaceSnapshot;
+  readonly existingArtifacts: ReadonlyMap<TaskArtifactDigest, TaskArtifactBody>;
+}
+
+/**
+ * Validates the command envelope before either owner performs replay lookup.
+ * This keeps replay authentication identical across backend adapters.
+ */
+export function validateTaskSpaceCommitCommand(commit: TaskSpaceCommit): TaskCommandDigest {
+  if (commit.kind !== 'task-space-commit'
+    || commit.command.commandId !== commit.commandId
+    || commit.command.taskSpaceId !== commit.taskSpaceId) {
+    throw new TaskManagerError(
+      'command-receipt-mismatch',
+      'submitted command identity does not match its CAS envelope',
+    );
+  }
+  const commandDigest = canonicalOwnDataDigest(commit.command);
+  if (commandDigest !== commit.commandDigest) {
+    throw new TaskManagerError(
+      'command-receipt-mismatch',
+      `command ${commit.commandId} digest does not match the submitted canonical command`,
+    );
+  }
+  return commandDigest;
+}
+
+/**
+ * Backend-neutral authority for a non-replay TaskSpace CAS admission.
+ * Storage implementations add only their own lock, containment, material and
+ * recovery checks around this shared identity/append-only/artifact validator.
+ */
+export function validateTaskSpaceCommitAdmission(
+  commit: TaskSpaceCommit,
+  context: TaskSpaceCommitAdmissionContext,
+): TaskCommandReceipt {
+  const commandDigest = validateTaskSpaceCommitCommand(commit);
+  const current = context.currentSnapshot;
+  const nextRevision = commit.expectedRevision === null ? 0 : commit.expectedRevision + 1;
+  if (commit.snapshot.taskSpaceId !== commit.taskSpaceId
+    || commit.snapshot.definition.taskSpaceId !== commit.taskSpaceId
+    || commit.snapshot.revision !== nextRevision) {
+    invalid('snapshot identity or revision disagrees with CAS');
+  }
+  assertSnapshotIdentity(commit.snapshot);
+
+  if (commit.receipts.length !== 1) invalid('one CAS command must issue exactly one receipt');
+  const receipt = commit.receipts[0]!;
+  if (receipt.commandId !== commit.commandId
+    || receipt.commandDigest !== commandDigest
+    || receipt.taskSpaceId !== commit.taskSpaceId
+    || receipt.fromRevision !== (commit.expectedRevision ?? 0)
+    || receipt.toRevision !== nextRevision) {
+    invalid('receipt identity or revision disagrees with CAS');
+  }
+
+  const priorHistoryIds = current?.historyEventIds ?? [];
+  const priorReceiptIds = current?.issuedReceiptIds ?? [];
+  const eventIds = commit.events.map(({ eventId }) => eventId);
+  if (!sameStrings(commit.snapshot.historyEventIds, [...priorHistoryIds, ...eventIds])) {
+    invalid('history prefix was rewritten');
+  }
+  if (!sameStrings(commit.snapshot.issuedReceiptIds, [...priorReceiptIds, receipt.receiptId])) {
+    invalid('receipt prefix was rewritten');
+  }
+  if (priorReceiptIds.includes(receipt.receiptId)) invalid(`receipt ${receipt.receiptId} is not append-only`);
+  if (!sameStrings(receipt.eventIds, eventIds)) invalid('receipt does not name the admitted event set');
+
+  const seenEvents = new Set(priorHistoryIds);
+  commit.events.forEach((event, index) => {
+    if (event.taskSpaceId !== commit.taskSpaceId
+      || event.commandId !== commit.commandId
+      || event.sequence !== priorHistoryIds.length + index
+      || event.fromRevision !== (commit.expectedRevision ?? 0)
+      || event.toRevision !== nextRevision
+      || seenEvents.has(event.eventId)) {
+      invalid(`event ${event.eventId} violates append-only admission`);
+    }
+    seenEvents.add(event.eventId);
+  });
+
+  validateArtifactAuthority(commit, context);
+  return receipt;
+}
+
+export function taskArtifactRefsOfSnapshot(snapshot: TaskSpaceSnapshot): readonly TaskArtifactRef[] {
+  return [
+    ...snapshot.definition.tasks.flatMap(({ inputArtifacts }) => inputArtifacts),
+    ...snapshot.tasks.flatMap(({ outputArtifacts }) => outputArtifacts),
+  ];
+}
+
+function assertSnapshotIdentity(snapshot: TaskSpaceSnapshot): void {
+  if (snapshot.kind !== 'task-space-snapshot') invalid('snapshot kind is invalid');
+  const definitions = new Map(snapshot.definition.tasks.map((task) => [task.taskId, task]));
+  if (definitions.size !== snapshot.definition.tasks.length || snapshot.tasks.length !== definitions.size) {
+    invalid('snapshot tree/task identity is invalid');
+  }
+  const seen = new Set<string>();
+  for (const task of snapshot.tasks) {
+    const definition = definitions.get(task.taskId);
+    if (task.taskSpaceId !== snapshot.taskSpaceId
+      || !definition
+      || seen.has(task.taskId)
+      || canonicalOwnDataDigest(definition) !== canonicalOwnDataDigest(task.definition)) {
+      invalid(`snapshot task ${task.taskId} disagrees with its tree definition`);
+    }
+    seen.add(task.taskId);
+  }
+}
+
+function validateArtifactAuthority(
+  commit: TaskSpaceCommit,
+  context: TaskSpaceCommitAdmissionContext,
+): void {
+  const availableArtifacts = new Map(context.existingArtifacts);
+  for (const body of commit.artifacts) {
+    assertArtifactBody(body, `artifact body ${body.digest}`);
+    const prior = availableArtifacts.get(body.digest);
+    if (prior && canonicalOwnDataDigest(prior) !== canonicalOwnDataDigest(body)) {
+      conflict(`artifact ${body.digest} has conflicting content`);
+    }
+    availableArtifacts.set(body.digest, body);
+  }
+
+  const priorRefs = refsByDigest(context.currentSnapshot ? taskArtifactRefsOfSnapshot(context.currentSnapshot) : []);
+  const nextRefs = refsByDigest(taskArtifactRefsOfSnapshot(commit.snapshot));
+  for (const [digest, nextRef] of nextRefs) {
+    const priorRef = priorRefs.get(digest);
+    if (priorRef && !sameArtifactRef(priorRef, nextRef)) {
+      conflict(`artifact ${digest} conflicts with the previously admitted reference`);
+    }
+    const body = availableArtifacts.get(digest);
+    if (!body) {
+      throw new TaskManagerError('artifact-not-found', `artifact ${digest} is not present in owner CAS`);
+    }
+    if (body.digest !== nextRef.digest
+      || body.mediaType !== nextRef.mediaType
+      || body.sizeBytes !== nextRef.sizeBytes) {
+      conflict(`artifact ${digest} metadata disagrees with owner body`);
+    }
+  }
+}
+
+function refsByDigest(refs: readonly TaskArtifactRef[]): Map<TaskArtifactDigest, TaskArtifactRef> {
+  const result = new Map<TaskArtifactDigest, TaskArtifactRef>();
+  for (const ref of refs) {
+    assertArtifactRef(ref, `artifact ref ${ref.digest}`);
+    const prior = result.get(ref.digest);
+    if (prior && !sameArtifactRef(prior, ref)) {
+      conflict(`artifact ${ref.digest} has conflicting complete references`);
+    }
+    result.set(ref.digest, ref);
+  }
+  return result;
+}
+
+function sameArtifactRef(left: TaskArtifactRef, right: TaskArtifactRef): boolean {
+  return left.digest === right.digest
+    && left.name === right.name
+    && left.mediaType === right.mediaType
+    && left.sizeBytes === right.sizeBytes;
+}
+
+function sameStrings(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function invalid(message: string): never {
+  throw new TaskManagerError('invalid-commit', message);
+}
+
+function conflict(message: string): never {
+  throw new TaskManagerError('artifact-conflict', message);
+}

package/src/processors.ts

@@ -497,15 +497,10 @@ export async function replanTask(
     tasks: input.plan.tasks,
     relations: input.plan.relations,
   };
+  assertReplanDurableTasksImmutable(snapshot, definition);
   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)) {
-      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 };
@@ -714,6 +709,40 @@ function replaceTask(snapshot: TaskSpaceSnapshot, replacement: TaskRecord): Task
   return snapshot.tasks.map((task) => task.taskId === replacement.taskId ? replacement : task);
 }
 
+function assertReplanDurableTasksImmutable(
+  snapshot: TaskSpaceSnapshot,
+  nextDefinition: TaskSpaceDefinition,
+): void {
+  for (const prior of snapshot.tasks) {
+    const next = nextDefinition.tasks.find(({ taskId }) => taskId === prior.taskId);
+    if (!next) {
+      if (isTerminal(prior.status) || prior.activeClaim) {
+        throw new TaskManagerError('terminal-task-immutable', `replan cannot remove durable task ${prior.taskId}`);
+      }
+      continue;
+    }
+    if (!isTerminal(prior.status)) continue;
+    const priorRelations = incidentRelations(snapshot.definition, prior.taskId);
+    const nextRelations = incidentRelations(nextDefinition, prior.taskId);
+    if (canonicalOwnDataDigest(prior.definition) !== canonicalOwnDataDigest(next)
+      || canonicalOwnDataDigest(priorRelations) !== canonicalOwnDataDigest(nextRelations)) {
+      throw new TaskManagerError(
+        'terminal-task-immutable',
+        `replan cannot rewrite terminal task ${prior.taskId} definition, profile, identity or relations`,
+      );
+    }
+  }
+}
+
+function incidentRelations(
+  definition: TaskSpaceDefinition,
+  taskId: TaskId,
+): TaskSpaceDefinition['relations'] {
+  return definition.relations.filter((relation) => relation.kind === 'parent-child'
+    ? relation.parentTaskId === taskId || relation.childTaskId === taskId
+    : relation.predecessorTaskId === taskId || relation.successorTaskId === taskId);
+}
+
 function dependenciesSucceeded(
   completionGraph: TaskCompletionGraph,
   tasks: readonly TaskRecord[],