task-manager-logic 0.1.1 → 0.1.3

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "task-manager-logic",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "private": false,
-  "description": "任务管理实现：状态机、组聚合、任务树存储",
+  "description": "Runtime-first TaskSpace transition processors and backend-neutral in-memory owner",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "task-manager-contract": "0.1.1"
+    "task-manager-contract": "0.1.3"
   },
   "files": [
     "src"

package/src/errors.ts

@@ -0,0 +1,32 @@
+export type TaskManagerErrorCode =
+  | 'artifact-conflict'
+  | 'artifact-not-found'
+  | 'canonical-data-invalid'
+  | 'claim-expired'
+  | 'claim-not-expired'
+  | 'claim-token-mismatch'
+  | 'command-receipt-mismatch'
+  | 'cross-space-identity'
+  | 'cyclic-task-forest'
+  | 'duplicate-task-identity'
+  | 'invalid-commit'
+  | 'invalid-task-definition'
+  | 'invalid-task-transition'
+  | 'lease-out-of-range'
+  | 'revision-conflict'
+  | 'task-not-found'
+  | 'task-not-ready'
+  | 'task-space-already-exists'
+  | 'task-space-not-found'
+  | 'terminal-task-immutable';
+
+export class TaskManagerError extends Error {
+  readonly name = 'TaskManagerError';
+
+  constructor(
+    readonly code: TaskManagerErrorCode,
+    message: string,
+  ) {
+    super(`[${code}] ${message}`);
+  }
+}

package/src/index.ts

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

package/src/memory-owner.ts

@@ -0,0 +1,191 @@
+import type {
+  TaskArtifactBody,
+  TaskArtifactDigest,
+  TaskCommandId,
+  TaskCommandReceipt,
+  TaskHistoryEvent,
+  TaskSpaceCommit,
+  TaskSpaceCommitResult,
+  TaskSpaceId,
+  TaskSpaceOwnerPort,
+  TaskSpaceSnapshot,
+} from 'task-manager-contract';
+import { canonicalOwnDataDigest } from 'task-manager-contract';
+import { TaskManagerError } from './errors.js';
+import { assertArtifactBody, assertArtifactRef, deepImmutableClone } from './validation.js';
+
+interface MemoryTaskSpaceState {
+  readonly snapshot: TaskSpaceSnapshot;
+  readonly history: readonly TaskHistoryEvent[];
+  readonly receiptsByCommand: ReadonlyMap<TaskCommandId, TaskCommandReceipt>;
+  readonly artifacts: ReadonlyMap<TaskArtifactDigest, TaskArtifactBody>;
+}
+
+/** Deterministic effect adapter for tests and embedded single-process use. */
+export class InMemoryTaskSpaceOwner implements TaskSpaceOwnerPort {
+  readonly #spaces = new Map<TaskSpaceId, MemoryTaskSpaceState>();
+
+  async readSnapshot(taskSpaceId: TaskSpaceId): Promise<TaskSpaceSnapshot | undefined> {
+    const snapshot = this.#spaces.get(taskSpaceId)?.snapshot;
+    return snapshot === undefined ? undefined : deepImmutableClone(snapshot);
+  }
+
+  async readReceiptByCommand(
+    taskSpaceId: TaskSpaceId,
+    commandId: TaskCommandId,
+  ): Promise<TaskCommandReceipt | undefined> {
+    const receipt = this.#spaces.get(taskSpaceId)?.receiptsByCommand.get(commandId);
+    return receipt === undefined ? undefined : deepImmutableClone(receipt);
+  }
+
+  async readHistory(taskSpaceId: TaskSpaceId): Promise<readonly TaskHistoryEvent[]> {
+    return deepImmutableClone(this.#spaces.get(taskSpaceId)?.history ?? []);
+  }
+
+  async readArtifact(
+    taskSpaceId: TaskSpaceId,
+    digest: TaskArtifactDigest,
+  ): Promise<TaskArtifactBody | undefined> {
+    const artifact = this.#spaces.get(taskSpaceId)?.artifacts.get(digest);
+    return artifact === undefined ? undefined : deepImmutableClone(artifact);
+  }
+
+  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,
+        revision: current.snapshot.revision,
+        snapshot: current.snapshot,
+        receipt: replay,
+      });
+    }
+
+    const actualRevision = current?.snapshot.revision ?? null;
+    if (actualRevision !== commit.expectedRevision) {
+      return deepImmutableClone({
+        kind: 'revision-conflict',
+        taskSpaceId: commit.taskSpaceId,
+        expectedRevision: commit.expectedRevision,
+        actualRevision,
+      });
+    }
+
+    const receipt = validateCommit(commit, current);
+    const receiptsByCommand = new Map(current?.receiptsByCommand ?? []);
+    for (const candidate of commit.receipts) receiptsByCommand.set(candidate.commandId, deepImmutableClone(candidate));
+    const artifacts = new Map(current?.artifacts ?? []);
+    for (const artifact of commit.artifacts) {
+      const prior = artifacts.get(artifact.digest);
+      if (prior && !sameArtifact(prior, artifact)) {
+        throw new TaskManagerError('artifact-conflict', `digest ${artifact.digest} has conflicting content`);
+      }
+      artifacts.set(artifact.digest, deepImmutableClone(artifact));
+    }
+    const next: MemoryTaskSpaceState = {
+      snapshot: deepImmutableClone(commit.snapshot),
+      history: deepImmutableClone([...(current?.history ?? []), ...commit.events]),
+      receiptsByCommand,
+      artifacts,
+    };
+    this.#spaces.set(commit.taskSpaceId, next);
+    return deepImmutableClone({
+      kind: 'commit-accepted',
+      taskSpaceId: commit.taskSpaceId,
+      revision: next.snapshot.revision,
+      snapshot: next.snapshot,
+      receipt,
+    });
+  }
+}
+
+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
+    && left.sizeBytes === right.sizeBytes
+    && left.encoding === right.encoding
+    && left.data === right.data;
+}
+
+function invalid(message: string): never {
+  throw new TaskManagerError('invalid-commit', message);
+}