task-manager-logic 0.1.1 → 0.1.3

package/src/statusMachine.ts

@@ -1,43 +1,36 @@
-/**
- * 任务状态机（BP-1）：转移合法性 + started_at/ended_at 语义。
- */
-import {
-  OPERATION_TARGET,
-  TASK_TRANSITIONS,
-  TERMINAL_STATUSES,
-  type TaskDTO,
-  type TaskOperation,
-  type TaskStatus,
-} from 'task-manager-contract';
+import type { TaskStatus } from 'task-manager-contract';
+import { TaskManagerError } from './errors.js';
 
-export class TaskTransitionError extends Error {
-  constructor(public taskId: string, public from: TaskStatus, public to: TaskStatus) {
-    super(`illegal task transition ${from} -> ${to} (task ${taskId})`);
-  }
-}
+export const TASK_TRANSITIONS: Readonly<Record<TaskStatus, readonly TaskStatus[]>> = Object.freeze({
+  Pending: Object.freeze(['Ready', 'Cancelled'] as const),
+  Ready: Object.freeze(['Claimed', 'Cancelled', 'Pending'] as const),
+  Claimed: Object.freeze(['Running', 'Ready', 'Cancelled'] as const),
+  Running: Object.freeze(['Waiting', 'Ready', 'Succeeded', 'Failed', 'Cancelled'] as const),
+  Waiting: Object.freeze(['Running', 'Ready', 'Succeeded', 'Failed', 'Cancelled'] as const),
+  Succeeded: Object.freeze([] as const),
+  Failed: Object.freeze([] as const),
+  Cancelled: Object.freeze([] as const),
+});
+
+export const TERMINAL_STATUSES: ReadonlySet<TaskStatus> = new Set<TaskStatus>([
+  'Succeeded',
+  'Failed',
+  'Cancelled',
+]);
 
 export function canTransition(from: TaskStatus, to: TaskStatus): boolean {
   return TASK_TRANSITIONS[from].includes(to);
 }
 
-export function isTerminal(status: TaskStatus): boolean {
+export function isTerminal(status: TaskStatus): status is Extract<TaskStatus, 'Succeeded' | 'Failed' | 'Cancelled'> {
   return TERMINAL_STATUSES.has(status);
 }
 
-/** 应用一次人工操作；非法转移抛 TaskTransitionError。返回同一 task 对象（原地更新）。 */
-export function applyOperation(
-  task: TaskDTO,
-  operation: TaskOperation,
-  operatorAccount: string,
-  nowMs: number,
-): TaskDTO {
-  const to = OPERATION_TARGET[operation];
-  if (!canTransition(task.status, to)) throw new TaskTransitionError(task.id, task.status, to);
-  const from = task.status;
-  task.status = to;
-  task.operatorAccount = operatorAccount;
-  if (to === 'Active' && from !== 'Active') task.startedAtMs ??= nowMs;
-  if (isTerminal(to)) task.endedAtMs = nowMs;
-  if (operation === 'delegate' || operation === 'forward') task.transferredBy = operatorAccount;
-  return task;
+export function assertTaskTransition(taskId: string, from: TaskStatus, to: TaskStatus): void {
+  if (isTerminal(from)) {
+    throw new TaskManagerError('terminal-task-immutable', `task ${taskId} is terminal (${from})`);
+  }
+  if (!canTransition(from, to)) {
+    throw new TaskManagerError('invalid-task-transition', `task ${taskId} cannot transition ${from} -> ${to}`);
+  }
 }

package/src/validation.ts

@@ -0,0 +1,278 @@
+import type {
+  TaskArtifactBody,
+  TaskArtifactRef,
+  TaskClaimToken,
+  TaskDefinition,
+  TaskId,
+  TaskNodeDefinition,
+  TaskProfileEnvelope,
+  TaskRecord,
+  TaskRelation,
+  TaskSpaceDefinition,
+  TaskSpaceSnapshot,
+  TaskTimestamp,
+} from 'task-manager-contract';
+import { deepFrozenCanonicalOwnDataClone, sha256Hex } from 'task-manager-contract';
+import { TaskManagerError } from './errors.js';
+
+export interface TaskProcessorConfig {
+  readonly maxTasks?: number;
+  readonly maxRelations?: number;
+  readonly maxLeaseDurationMs?: number;
+}
+
+export interface NormalizedTaskProcessorConfig {
+  readonly maxTasks: number;
+  readonly maxRelations: number;
+  readonly maxLeaseDurationMs: number;
+}
+
+export function normalizeTaskProcessorConfig(config: TaskProcessorConfig): NormalizedTaskProcessorConfig {
+  return {
+    maxTasks: positiveInteger(config.maxTasks ?? 10_000, 'maxTasks'),
+    maxRelations: positiveInteger(config.maxRelations ?? 50_000, 'maxRelations'),
+    maxLeaseDurationMs: positiveInteger(config.maxLeaseDurationMs ?? 86_400_000, 'maxLeaseDurationMs'),
+  };
+}
+
+export function validateTaskSpaceDefinition(
+  definition: TaskSpaceDefinition,
+  config: NormalizedTaskProcessorConfig,
+): void {
+  assertNonEmpty(definition.taskSpaceId, 'taskSpaceId');
+  assertNonEmpty(definition.name, 'TaskSpace name');
+  if (!Number.isSafeInteger(definition.schemaVersion) || definition.schemaVersion < 1) {
+    invalid('schemaVersion must be a positive safe integer');
+  }
+  if (definition.tasks.length === 0) invalid('TaskSpace must contain at least one task');
+  if (definition.tasks.length > config.maxTasks) invalid(`TaskSpace exceeds maxTasks=${config.maxTasks}`);
+  if (definition.relations.length > config.maxRelations) invalid(`TaskSpace exceeds maxRelations=${config.maxRelations}`);
+
+  const tasks = new Map<TaskId, TaskNodeDefinition>();
+  for (const task of definition.tasks) {
+    assertTaskDefinition(task);
+    if (tasks.has(task.taskId)) {
+      throw new TaskManagerError('duplicate-task-identity', `duplicate taskId ${task.taskId}`);
+    }
+    tasks.set(task.taskId, task);
+  }
+
+  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');
+    if (relationIds.has(relation.relationId)) invalid(`duplicate relationId ${relation.relationId}`);
+    relationIds.add(relation.relationId);
+    if (relation.kind === 'parent-child') {
+      if (!tasks.has(relation.childTaskId)) invalid(`parent relation references missing child ${relation.childTaskId}`);
+      if (parentByChild.has(relation.childTaskId)) invalid(`task ${relation.childTaskId} has multiple parents`);
+      if (!Number.isSafeInteger(relation.order) || relation.order < 0) invalid(`invalid order for ${relation.relationId}`);
+      if (relation.parentTaskId !== null) {
+        const parent = tasks.get(relation.parentTaskId);
+        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;
+    }
+    if (!tasks.has(relation.predecessorTaskId) || !tasks.has(relation.successorTaskId)) {
+      invalid(`dependency ${relation.relationId} references a missing task`);
+    }
+    if (relation.predecessorTaskId === relation.successorTaskId) cyclic(`task ${relation.successorTaskId} depends on itself`);
+    const successors = dependencyEdges.get(relation.predecessorTaskId) ?? [];
+    successors.push(relation.successorTaskId);
+    dependencyEdges.set(relation.predecessorTaskId, successors);
+  }
+
+  for (const taskId of tasks.keys()) {
+    if (!parentByChild.has(taskId)) invalid(`task ${taskId} has no parent-child relation`);
+  }
+  assertAcyclic(tasks.keys(), (id) => {
+    const parent = parentByChild.get(id);
+    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(
+  definition: TaskSpaceDefinition,
+  taskId: TaskId,
+): TaskNodeDefinition | undefined {
+  return definition.tasks.find((task) => task.taskId === taskId);
+}
+
+export function taskRecordById(snapshot: TaskSpaceSnapshot, taskId: TaskId): TaskRecord | undefined {
+  return snapshot.tasks.find((task) => task.taskId === taskId);
+}
+
+export function predecessorIds(definition: TaskSpaceDefinition, taskId: TaskId): readonly TaskId[] {
+  return definition.relations
+    .filter((relation): relation is Extract<TaskRelation, { kind: 'dependency' }> =>
+      relation.kind === 'dependency' && relation.successorTaskId === taskId)
+    .map((relation) => relation.predecessorTaskId);
+}
+
+export function validateTimestamp(value: TaskTimestamp, field: string): number {
+  const millis = Date.parse(value);
+  if (!Number.isFinite(millis) || new Date(millis).toISOString() !== value) {
+    invalid(`${field} must be a canonical ISO-8601 timestamp`);
+  }
+  return millis;
+}
+
+export function assertClaimIdentity(
+  snapshot: TaskSpaceSnapshot,
+  claim: TaskClaimToken,
+  taskId?: TaskId,
+): TaskRecord {
+  if (claim.taskSpaceId !== snapshot.taskSpaceId) {
+    throw new TaskManagerError('cross-space-identity', `claim belongs to ${claim.taskSpaceId}, not ${snapshot.taskSpaceId}`);
+  }
+  if (taskId !== undefined && claim.taskId !== taskId) {
+    throw new TaskManagerError('cross-space-identity', `claim task ${claim.taskId} does not match ${taskId}`);
+  }
+  const record = taskRecordById(snapshot, claim.taskId);
+  if (!record) throw new TaskManagerError('task-not-found', `task ${claim.taskId} not found`);
+  if (!record.activeClaim || !sameClaim(record.activeClaim, claim)) {
+    throw new TaskManagerError('claim-token-mismatch', `claim ${claim.claimId} is not the exact live token`);
+  }
+  return record;
+}
+
+export function assertClaimLive(claim: TaskClaimToken, at: TaskTimestamp): void {
+  const atMs = validateTimestamp(at, 'occurredAt');
+  const expiresAtMs = validateTimestamp(claim.expiresAt, 'claim.expiresAt');
+  if (atMs >= expiresAtMs) {
+    throw new TaskManagerError('claim-expired', `claim ${claim.claimId} expired at ${claim.expiresAt}`);
+  }
+}
+
+export function sameClaim(left: TaskClaimToken, right: TaskClaimToken): boolean {
+  return left.kind === right.kind
+    && left.claimId === right.claimId
+    && left.taskSpaceId === right.taskSpaceId
+    && left.taskId === right.taskId
+    && left.assigneeRef === right.assigneeRef
+    && left.attempt === right.attempt
+    && left.leaseEpoch === right.leaseEpoch
+    && left.claimedAt === right.claimedAt
+    && left.heartbeatAt === right.heartbeatAt
+    && left.expiresAt === right.expiresAt;
+}
+
+export function deepImmutableClone<Value>(value: Value): 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> {
+  assertNonEmpty(task.taskId, 'taskId');
+  assertNonEmpty(task.name, `task ${task.taskId} name`);
+  if (!Number.isSafeInteger(task.order) || task.order < 0) invalid(`task ${task.taskId} has invalid order`);
+  if (task.kind === 'task-group' && !['sequential', 'all', 'any'].includes(task.mode)) {
+    invalid(`task-group ${task.taskId} has invalid mode`);
+  }
+  assertProfile(task.profile, task.taskId);
+  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`);
+  }
+}
+
+function assertProfile(profile: TaskProfileEnvelope, taskId: string): void {
+  if (profile.kind !== 'task-profile') invalid(`task ${taskId} has invalid profile envelope`);
+  assertNonEmpty(profile.profileKind, `task ${taskId} profileKind`);
+  if (!Number.isSafeInteger(profile.schemaVersion) || profile.schemaVersion < 1) {
+    invalid(`task ${taskId} has invalid profile schemaVersion`);
+  }
+}
+
+function assertAcyclic(ids: Iterable<TaskId>, outgoing: (id: TaskId) => readonly TaskId[]): void {
+  const visiting = new Set<TaskId>();
+  const visited = new Set<TaskId>();
+  const visit = (id: TaskId): void => {
+    if (visiting.has(id)) cyclic(`cycle includes task ${id}`);
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const successor of outgoing(id)) visit(successor);
+    visiting.delete(id);
+    visited.add(id);
+  };
+  for (const id of ids) visit(id);
+}
+
+function positiveInteger(value: number, field: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) invalid(`${field} must be a positive safe integer`);
+  return value;
+}
+
+function assertNonEmpty(value: string, field: string): void {
+  if (value.length === 0 || value.trim() !== value) invalid(`${field} must be non-empty and trimmed`);
+}
+
+function invalid(message: string): never {
+  throw new TaskManagerError('invalid-task-definition', message);
+}
+
+function cyclic(message: string): never {
+  throw new TaskManagerError('cyclic-task-forest', message);
+}

package/src/stores.ts

@@ -1,42 +0,0 @@
-/**
- * 任务树外置存储：内存 + 文件（JSON）。
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import type { TaskSpaceDTO, TaskSpaceStore } from 'task-manager-contract';
-
-export class InMemoryTaskSpaceStore implements TaskSpaceStore {
-  private spaces = new Map<string, TaskSpaceDTO>();
-  async load(spaceId: string): Promise<TaskSpaceDTO | undefined> {
-    const s = this.spaces.get(spaceId);
-    return s ? structuredClone(s) : undefined;
-  }
-  async save(spaceId: string, space: TaskSpaceDTO): Promise<void> {
-    this.spaces.set(spaceId, structuredClone(space));
-  }
-  async remove(spaceId: string): Promise<void> {
-    this.spaces.delete(spaceId);
-  }
-}
-
-export class FileTaskSpaceStore implements TaskSpaceStore {
-  constructor(private dir: string) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-  private file(spaceId: string) {
-    return path.join(this.dir, `${encodeURIComponent(spaceId)}.task-space.json`);
-  }
-  async load(spaceId: string): Promise<TaskSpaceDTO | undefined> {
-    const f = this.file(spaceId);
-    if (!fs.existsSync(f)) return undefined;
-    return JSON.parse(fs.readFileSync(f, 'utf8')) as TaskSpaceDTO;
-  }
-  async save(spaceId: string, space: TaskSpaceDTO): Promise<void> {
-    const f = this.file(spaceId);
-    fs.writeFileSync(f + '.tmp', JSON.stringify(space, null, 2));
-    fs.renameSync(f + '.tmp', f);
-  }
-  async remove(spaceId: string): Promise<void> {
-    fs.rmSync(this.file(spaceId), { force: true });
-  }
-}

package/src/tree.ts

@@ -1,100 +0,0 @@
-/**
- * 任务树查找与组聚合（executionMode 语义，BP-2/BP-4）。
- */
-import type { ExecutionMode, TaskDTO, TaskGroupDTO, TaskSpaceDTO, TaskStatus, TaskTreeNode } from 'task-manager-contract';
-import { isTerminal } from './statusMachine.js';
-
-export function findNode(space: TaskSpaceDTO, id: string): TaskTreeNode | undefined {
-  const walk = (nodes: TaskTreeNode[]): TaskTreeNode | undefined => {
-    for (const n of nodes) {
-      if (n.id === id) return n;
-      if (n.kind === 'group') {
-        const hit = walk(n.children);
-        if (hit) return hit;
-      }
-    }
-    return undefined;
-  };
-  return walk(space.children);
-}
-
-export function findTask(space: TaskSpaceDTO, id: string): TaskDTO | undefined {
-  const n = findNode(space, id);
-  return n?.kind === 'task' ? n : undefined;
-}
-
-export function listTasks(space: TaskSpaceDTO): TaskDTO[] {
-  const out: TaskDTO[] = [];
-  const walk = (nodes: TaskTreeNode[]) => {
-    for (const n of nodes) (n.kind === 'task' ? out.push(n) : walk(n.children));
-  };
-  walk(space.children);
-  return out;
-}
-
-/** 直接子节点 id 集合（TaskStep 只能绑定它们，BP-2） */
-export function directChildIds(space: TaskSpaceDTO): Set<string> {
-  return new Set(space.children.map((c) => c.id));
-}
-
-/**
- * 节点终态判定：Task 用自身状态；Group 按 executionMode 聚合。
- * 返回 undefined 表示尚未终态。
- * - SEQUENTIAL / ALL：全部子节点终态才终态；全 DONE（FORWARDED 视同 DONE）→ DONE，否则 REFUSED。
- * - ANY：任一 DONE/FORWARDED → DONE；全部终态且无 DONE → REFUSED。
- */
-export function terminalStatusOf(node: TaskTreeNode): TaskStatus | undefined {
-  if (node.kind === 'task') return isTerminal(node.status) ? node.status : undefined;
-  return aggregateGroup(node);
-}
-
-const doneLike = (s: TaskStatus) => s === 'Done' || s === 'Forwarded';
-
-function aggregateGroup(group: TaskGroupDTO): TaskStatus | undefined {
-  const childStatuses = group.children.map((c) => terminalStatusOf(c));
-  const mode: ExecutionMode = group.executionMode;
-  if (mode === 'ANY') {
-    if (childStatuses.some((s) => s !== undefined && doneLike(s))) return 'Done';
-    if (childStatuses.every((s) => s !== undefined)) return 'Refused';
-    return undefined;
-  }
-  // SEQUENTIAL / ALL
-  if (childStatuses.some((s) => s === undefined)) {
-    // 提前失败：任一 REFUSED/ABANDONED 即整体 REFUSED（不必等其余）
-    if (childStatuses.some((s) => s !== undefined && !doneLike(s))) return 'Refused';
-    return undefined;
-  }
-  return childStatuses.every((s) => doneLike(s!)) ? 'Done' : 'Refused';
-}
-
-/** SEQUENTIAL 组内可操作性：前序兄弟（按 order）必须 done-like */
-export function isOperable(space: TaskSpaceDTO, taskId: string): boolean {
-  const check = (nodes: TaskTreeNode[], mode: ExecutionMode | null): boolean => {
-    const sorted = [...nodes].sort((a, b) => a.order - b.order);
-    for (let i = 0; i < sorted.length; i++) {
-      const n = sorted[i];
-      if (n.id === taskId || (n.kind === 'group' && findInGroup(n, taskId))) {
-        if (mode === 'SEQUENTIAL') {
-          for (let j = 0; j < i; j++) {
-            const prev = terminalStatusOf(sorted[j]);
-            if (prev === undefined || !doneLike(prev)) return false;
-          }
-        }
-        return n.id === taskId ? true : check((n as TaskGroupDTO).children, (n as TaskGroupDTO).executionMode);
-      }
-    }
-    return false;
-  };
-  const findInGroup = (g: TaskGroupDTO, id: string): boolean => !!findNodeIn(g.children, id);
-  const findNodeIn = (nodes: TaskTreeNode[], id: string): TaskTreeNode | undefined => {
-    for (const n of nodes) {
-      if (n.id === id) return n;
-      if (n.kind === 'group') {
-        const hit = findNodeIn(n.children, id);
-        if (hit) return hit;
-      }
-    }
-    return undefined;
-  };
-  return check(space.children, null);
-}