@vercel/factory 0.0.13 → 0.0.15

package/dist/store/task-effects.mjs

@@ -0,0 +1,118 @@
+import { taskIdSchema } from "../schema/id.mjs";
+import { isoDateTimeSchema } from "../schema/common.mjs";
+import { RecordExistsError, RecordNotFoundError, VersionConflictError } from "./driver.mjs";
+import { taskEffectKeySchema, taskEffectReferenceSchema, taskEffectSchema } from "../schema/task-effect.mjs";
+import { createHash } from "node:crypto";
+//#region src/store/task-effects.ts
+function recordId(taskId, key) {
+	return `effect_${createHash("sha256").update(JSON.stringify([
+		taskId,
+		key.namespace,
+		key.name
+	])).digest("hex").slice(0, 32)}`;
+}
+/** Creates a CAS-protected store for idempotent Task effect reconciliation. */
+function createTaskEffectStore(options) {
+	async function assertTask(taskId) {
+		if (await options.getTask(taskId) === null) throw new RecordNotFoundError("tasks", taskId);
+	}
+	async function read(taskId, key) {
+		const id = recordId(taskId, key);
+		const stored = await options.driver.get("taskEffects", id);
+		if (stored === null) return null;
+		const effect = taskEffectSchema.parse(stored.value);
+		if (effect.taskId !== taskId || effect.key.namespace !== key.namespace || effect.key.name !== key.name) throw new Error(`Task effect ${id} does not match its storage key`);
+		return {
+			effect,
+			id,
+			version: stored.version
+		};
+	}
+	return {
+		async get(input) {
+			return (await read(taskIdSchema.parse(input.taskId), taskEffectKeySchema.parse(input.key)))?.effect ?? null;
+		},
+		async record(input) {
+			const taskId = taskIdSchema.parse(input.taskId);
+			const key = taskEffectKeySchema.parse(input.key);
+			const reference = taskEffectReferenceSchema.parse(input.reference);
+			await assertTask(taskId);
+			for (;;) {
+				const existing = await read(taskId, key);
+				if (existing?.effect.reference !== void 0) return existing.effect;
+				const timestamp = options.now();
+				const next = taskEffectSchema.parse(existing === null ? {
+					schemaVersion: 1,
+					taskId,
+					key,
+					reference,
+					createdAt: timestamp,
+					updatedAt: timestamp
+				} : {
+					...existing.effect,
+					reference,
+					updatedAt: timestamp
+				});
+				try {
+					if (existing === null) await options.driver.insert({
+						collection: "taskEffects",
+						id: recordId(taskId, key),
+						value: next
+					});
+					else await options.driver.update({
+						collection: "taskEffects",
+						id: existing.id,
+						value: next,
+						expectedVersion: existing.version
+					});
+					return next;
+				} catch (error) {
+					if (!(error instanceof RecordExistsError || error instanceof VersionConflictError)) throw error;
+				}
+			}
+		},
+		async resolve(input) {
+			const taskId = taskIdSchema.parse(input.taskId);
+			const key = taskEffectKeySchema.parse(input.key);
+			const resolvedAt = isoDateTimeSchema.parse(input.at ?? options.now());
+			await assertTask(taskId);
+			for (;;) {
+				const existing = await read(taskId, key);
+				if (existing?.effect.resolvedAt !== void 0) return existing.effect;
+				const timestamp = options.now();
+				const next = taskEffectSchema.parse(existing === null ? {
+					schemaVersion: 1,
+					taskId,
+					key,
+					resolvedAt,
+					createdAt: timestamp,
+					updatedAt: timestamp
+				} : {
+					...existing.effect,
+					resolvedAt,
+					updatedAt: timestamp
+				});
+				try {
+					if (existing === null) await options.driver.insert({
+						collection: "taskEffects",
+						id: recordId(taskId, key),
+						value: next
+					});
+					else await options.driver.update({
+						collection: "taskEffects",
+						id: existing.id,
+						value: next,
+						expectedVersion: existing.version
+					});
+					return next;
+				} catch (error) {
+					if (!(error instanceof RecordExistsError || error instanceof VersionConflictError)) throw error;
+				}
+			}
+		}
+	};
+}
+//#endregion
+export { createTaskEffectStore };
+
+//# sourceMappingURL=task-effects.mjs.map

package/dist/store/task-effects.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-effects.mjs","names":[],"sources":["../../src/store/task-effects.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { SCHEMA_VERSION, isoDateTimeSchema, type IsoDateTimeClock } from \"../schema/common\";\nimport { taskIdSchema, type TaskId } from \"../schema/id\";\nimport type { Task } from \"../schema/task\";\nimport {\n  taskEffectKeySchema,\n  taskEffectReferenceSchema,\n  taskEffectSchema,\n  type TaskEffect,\n  type TaskEffectKey,\n  type TaskEffectReference,\n} from \"../schema/task-effect\";\nimport {\n  RecordExistsError,\n  RecordNotFoundError,\n  VersionConflictError,\n  type StoreDriver,\n} from \"./driver\";\n\n/** Persistence, clock, and Task lookup dependencies for the Task effect store. */\nexport interface CreateTaskEffectStoreOptions {\n  driver: StoreDriver;\n  now: IsoDateTimeClock;\n  getTask: (id: TaskId) => Promise<Task | null>;\n}\n\n/** Task identity and namespaced key identifying one durable external effect. */\nexport interface TaskEffectLookupInput {\n  readonly taskId: TaskId;\n  readonly key: TaskEffectKey;\n}\n\n/** Task-scoped effect key and first external-resource reference to record. */\nexport interface RecordTaskEffectInput extends TaskEffectLookupInput {\n  readonly reference: TaskEffectReference;\n}\n\n/** Task-scoped effect key and optional explicit resolution timestamp. */\nexport interface ResolveTaskEffectInput extends TaskEffectLookupInput {\n  readonly at?: string;\n}\n\n/** Durable, Task-scoped external-resource references and write-once resolution stamps. */\nexport interface TaskEffectStore {\n  get(input: TaskEffectLookupInput): Promise<TaskEffect | null>;\n  /** Record the first external resource created for this key. Replays return that first record. */\n  record(input: RecordTaskEffectInput): Promise<TaskEffect>;\n  /** Stamp the effect resolved once, including when no external resource was found. */\n  resolve(input: ResolveTaskEffectInput): Promise<TaskEffect>;\n}\n\nfunction recordId(taskId: TaskId, key: TaskEffectKey): string {\n  const digest = createHash(\"sha256\")\n    .update(JSON.stringify([taskId, key.namespace, key.name]))\n    .digest(\"hex\");\n  return `effect_${digest.slice(0, 32)}`;\n}\n\n/** Creates a CAS-protected store for idempotent Task effect reconciliation. */\nexport function createTaskEffectStore(options: CreateTaskEffectStoreOptions): TaskEffectStore {\n  async function assertTask(taskId: TaskId): Promise<void> {\n    if ((await options.getTask(taskId)) === null) throw new RecordNotFoundError(\"tasks\", taskId);\n  }\n\n  async function read(taskId: TaskId, key: TaskEffectKey) {\n    const id = recordId(taskId, key);\n    const stored = await options.driver.get(\"taskEffects\", id);\n    if (stored === null) return null;\n    const effect = taskEffectSchema.parse(stored.value);\n    if (\n      effect.taskId !== taskId ||\n      effect.key.namespace !== key.namespace ||\n      effect.key.name !== key.name\n    ) {\n      throw new Error(`Task effect ${id} does not match its storage key`);\n    }\n    return { effect, id, version: stored.version };\n  }\n\n  return {\n    async get(input) {\n      const taskId = taskIdSchema.parse(input.taskId);\n      const key = taskEffectKeySchema.parse(input.key);\n      return (await read(taskId, key))?.effect ?? null;\n    },\n\n    async record(input) {\n      const taskId = taskIdSchema.parse(input.taskId);\n      const key = taskEffectKeySchema.parse(input.key);\n      const reference = taskEffectReferenceSchema.parse(input.reference);\n      await assertTask(taskId);\n      for (;;) {\n        const existing = await read(taskId, key);\n        if (existing?.effect.reference !== undefined) return existing.effect;\n        const timestamp = options.now();\n        const next = taskEffectSchema.parse(\n          existing === null\n            ? {\n                schemaVersion: SCHEMA_VERSION,\n                taskId,\n                key,\n                reference,\n                createdAt: timestamp,\n                updatedAt: timestamp,\n              }\n            : { ...existing.effect, reference, updatedAt: timestamp },\n        );\n        try {\n          if (existing === null)\n            await options.driver.insert({\n              collection: \"taskEffects\",\n              id: recordId(taskId, key),\n              value: next,\n            });\n          else\n            await options.driver.update({\n              collection: \"taskEffects\",\n              id: existing.id,\n              value: next,\n              expectedVersion: existing.version,\n            });\n          return next;\n        } catch (error) {\n          if (!(error instanceof RecordExistsError || error instanceof VersionConflictError))\n            throw error;\n        }\n      }\n    },\n\n    async resolve(input) {\n      const taskId = taskIdSchema.parse(input.taskId);\n      const key = taskEffectKeySchema.parse(input.key);\n      const resolvedAt = isoDateTimeSchema.parse(input.at ?? options.now());\n      await assertTask(taskId);\n      for (;;) {\n        const existing = await read(taskId, key);\n        if (existing?.effect.resolvedAt !== undefined) return existing.effect;\n        const timestamp = options.now();\n        const next = taskEffectSchema.parse(\n          existing === null\n            ? {\n                schemaVersion: SCHEMA_VERSION,\n                taskId,\n                key,\n                resolvedAt,\n                createdAt: timestamp,\n                updatedAt: timestamp,\n              }\n            : { ...existing.effect, resolvedAt, updatedAt: timestamp },\n        );\n        try {\n          if (existing === null)\n            await options.driver.insert({\n              collection: \"taskEffects\",\n              id: recordId(taskId, key),\n              value: next,\n            });\n          else\n            await options.driver.update({\n              collection: \"taskEffects\",\n              id: existing.id,\n              value: next,\n              expectedVersion: existing.version,\n            });\n          return next;\n        } catch (error) {\n          if (!(error instanceof RecordExistsError || error instanceof VersionConflictError))\n            throw error;\n        }\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/store/task-graphs.d.mts

@@ -0,0 +1,60 @@
+import { TaskId } from "../schema/id.mjs";
+import { Task } from "../schema/task.mjs";
+import { WorkNotification } from "./work-notifications.mjs";
+import { IsoDateTimeClock } from "../schema/common.mjs";
+import { StoreDriver } from "./driver.mjs";
+import { TaskGraph } from "../schema/task-graph.mjs";
+//#region src/store/task-graphs.d.ts
+/** Engine-owned persistence and validation dependencies for canonical Task graphs. */
+interface CreateTaskGraphStoreOptions {
+  driver: StoreDriver;
+  now: IsoDateTimeClock;
+  getTask: (id: TaskId) => Promise<Task | null>;
+  validateTask: (task: Task) => void;
+  notify?: (event: WorkNotification) => Promise<void>;
+}
+/** Canonical bounded graph store for Task membership, ownership, and dependency edges. */
+interface TaskGraphStore {
+  admit(input: AdmitTaskGraphInput): Promise<void>;
+  get(rootTaskId: TaskId): Promise<TaskGraph | null>;
+  setDependencies(input: SetTaskGraphDependenciesInput): Promise<TaskGraph>;
+  dependenciesSatisfied(input: TaskGraphNodeRef): Promise<boolean>;
+  /** Call before every Task transition to running. First admission freezes edges, even if launch fails. */
+  seal(input: TaskGraphNodeRef): Promise<void>;
+}
+/** Canonical Task snapshot and initial dependency edges admitted atomically to its graph. */
+interface AdmitTaskGraphInput {
+  task: Task;
+  dependencies?: readonly TaskId[];
+}
+/** Identifies one Task within its canonical root graph. */
+interface TaskGraphNodeRef {
+  rootTaskId: TaskId;
+  taskId: TaskId;
+}
+/** Revision-fenced replacement of one queued Task's graph dependencies. */
+interface SetTaskGraphDependenciesInput extends TaskGraphNodeRef {
+  dependencies: readonly TaskId[];
+  expectedRevision: number;
+}
+/** Error raised when a creation retry differs from immutable graph admission intent. */
+declare class TaskGraphConflictError extends Error {
+  constructor(taskId: TaskId);
+}
+/** Canonical Task and immutable graph admission snapshot to compare. */
+interface AssertTaskAdmissionInput {
+  task: Task;
+  admission: Task;
+}
+/** Verifies that a canonical Task preserves the immutable identity admitted to its graph. */
+declare function assertTaskAdmission({ task, admission }: AssertTaskAdmissionInput): void;
+/**
+ * Trusted engine/workflow capability, not an agent tool or HTTP boundary: callers own
+ * authentication and workflow binding validation. The engine seals dependencies before
+ * transitioning to running; sealing survives a failed launch and rechecks prerequisites
+ * on retries. Succeeded prerequisites are terminal under the engine's transition rules.
+ */
+declare function createTaskGraphStore({ driver, now, getTask, validateTask, notify }: CreateTaskGraphStoreOptions): TaskGraphStore;
+//#endregion
+export { AdmitTaskGraphInput, AssertTaskAdmissionInput, CreateTaskGraphStoreOptions, SetTaskGraphDependenciesInput, TaskGraphConflictError, TaskGraphNodeRef, TaskGraphStore, assertTaskAdmission, createTaskGraphStore };
+//# sourceMappingURL=task-graphs.d.mts.map

package/dist/store/task-graphs.mjs

@@ -0,0 +1,212 @@
+import { taskIdSchema } from "../schema/id.mjs";
+import "../schema/common.mjs";
+import { taskSchema } from "../schema/task.mjs";
+import { RecordExistsError, RecordNotFoundError, VersionConflictError } from "./driver.mjs";
+import { taskGraphAdmissionSchema, taskGraphDependenciesSchema, taskGraphSchema } from "../schema/task-graph.mjs";
+import { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+//#region src/store/task-graphs.ts
+/** Error raised when a creation retry differs from immutable graph admission intent. */
+var TaskGraphConflictError = class extends Error {
+	constructor(taskId) {
+		super(`Task ${taskId} conflicts with its immutable graph admission; reuse the original creation intent`);
+		this.name = "TaskGraphConflictError";
+	}
+};
+function immutableTaskIdentity(task) {
+	const { id, rootTaskId, parentTaskId, repositoryIds, work, kind, origin, replyTo, area } = task;
+	return JSON.parse(JSON.stringify({
+		id,
+		rootTaskId,
+		parentTaskId,
+		repositoryIds,
+		work,
+		kind,
+		origin,
+		replyTo,
+		area
+	}));
+}
+/** Verifies that a canonical Task preserves the immutable identity admitted to its graph. */
+function assertTaskAdmission({ task, admission }) {
+	if (!isDeepStrictEqual(immutableTaskIdentity(task), immutableTaskIdentity(admission))) throw new TaskGraphConflictError(admission.id);
+}
+function creationIntent({ createdAt: _createdAt, updatedAt: _updatedAt, ...intent }) {
+	return JSON.parse(JSON.stringify(intent));
+}
+/**
+* Trusted engine/workflow capability, not an agent tool or HTTP boundary: callers own
+* authentication and workflow binding validation. The engine seals dependencies before
+* transitioning to running; sealing survives a failed launch and rechecks prerequisites
+* on retries. Succeeded prerequisites are terminal under the engine's transition rules.
+*/
+function createTaskGraphStore({ driver, now, getTask, validateTask, notify }) {
+	async function read(rootTaskId) {
+		taskIdSchema.parse(rootTaskId);
+		const record = await driver.get("taskGraphs", rootTaskId);
+		if (!record) return null;
+		const graph = taskGraphSchema.parse(record.value);
+		for (const node of graph.nodes) validateTask(node.admission);
+		if (graph.rootTaskId !== rootTaskId) throw new Error("Stored graph root does not match its storage key");
+		return {
+			graph,
+			version: record.version
+		};
+	}
+	async function canonical(node) {
+		const value = await getTask(node.taskId);
+		if (value === null) return null;
+		const task = taskSchema.parse(value);
+		validateTask(task);
+		assertTaskAdmission({
+			task,
+			admission: node.admission
+		});
+		return task;
+	}
+	async function satisfied(graph, node) {
+		for (const id of node.dependencies) {
+			const dependency = graph.nodes.find((entry) => entry.taskId === id);
+			if (!dependency || (await canonical(dependency))?.state !== "succeeded") return false;
+		}
+		return true;
+	}
+	return {
+		async admit(input) {
+			const task = structuredClone(taskGraphAdmissionSchema.parse(input.task));
+			validateTask(task);
+			const initialDependencies = taskGraphDependenciesSchema.parse(input.dependencies ?? []);
+			const rootTaskId = taskIdSchema.parse(task.rootTaskId);
+			const node = {
+				taskId: task.id,
+				...task.parentTaskId === void 0 ? {} : { parentTaskId: task.parentTaskId },
+				dependencies: initialDependencies,
+				sealed: false,
+				admissionDependencies: [...initialDependencies],
+				admission: task
+			};
+			await canonical(node);
+			for (;;) {
+				const current = await read(rootTaskId);
+				const existing = current?.graph.nodes.find((entry) => entry.taskId === task.id);
+				if (existing) {
+					if (!isDeepStrictEqual(creationIntent(existing.admission), creationIntent(task)) || !isDeepStrictEqual(existing.admissionDependencies, initialDependencies)) throw new TaskGraphConflictError(task.id);
+					return;
+				}
+				const timestamp = now();
+				const graph = taskGraphSchema.parse(current ? {
+					...current.graph,
+					revision: current.graph.revision + 1,
+					nodes: [...current.graph.nodes, node],
+					updatedAt: timestamp
+				} : {
+					schemaVersion: 1,
+					rootTaskId,
+					revision: 1,
+					nodes: [node],
+					createdAt: timestamp,
+					updatedAt: timestamp
+				});
+				try {
+					if (current) await driver.update({
+						collection: "taskGraphs",
+						id: rootTaskId,
+						value: graph,
+						expectedVersion: current.version
+					});
+					else await driver.insert({
+						collection: "taskGraphs",
+						id: rootTaskId,
+						value: graph
+					});
+					return;
+				} catch (error) {
+					if (!(error instanceof RecordExistsError || error instanceof VersionConflictError)) throw error;
+				}
+			}
+		},
+		async get(rootTaskId) {
+			return (await read(rootTaskId))?.graph ?? null;
+		},
+		async setDependencies(input) {
+			const { rootTaskId, taskId, dependencies, expectedRevision } = input;
+			taskIdSchema.parse(taskId);
+			z.number().int().positive().parse(expectedRevision);
+			const edges = taskGraphDependenciesSchema.parse(dependencies);
+			const current = await read(rootTaskId);
+			if (!current) throw new RecordNotFoundError("taskGraphs", rootTaskId);
+			if (current.graph.revision !== expectedRevision) throw new VersionConflictError("taskGraphs", rootTaskId, expectedRevision);
+			const node = current.graph.nodes.find((entry) => entry.taskId === taskId);
+			if (!node) throw new Error(`Task ${taskId} is not registered in graph ${rootTaskId}`);
+			if (node.sealed) throw new Error(`Task ${taskId} dependencies are sealed by first execution admission and cannot be changed`);
+			const task = await canonical(node);
+			if (!task) throw new RecordNotFoundError("tasks", taskId);
+			if (task.state !== "queued") throw new Error(`Task ${taskId} must be queued to change dependencies; current state is ${task.state}`);
+			const graph = taskGraphSchema.parse({
+				...current.graph,
+				revision: current.graph.revision + 1,
+				nodes: current.graph.nodes.map((entry) => entry.taskId === taskId ? {
+					...entry,
+					dependencies: edges
+				} : entry),
+				updatedAt: now()
+			});
+			await driver.update({
+				collection: "taskGraphs",
+				id: rootTaskId,
+				value: graph,
+				expectedVersion: current.version
+			});
+			await notify?.({
+				rootTaskId,
+				key: `dependencies:${rootTaskId}:${graph.revision}`
+			});
+			return graph;
+		},
+		async dependenciesSatisfied({ rootTaskId, taskId }) {
+			taskIdSchema.parse(taskId);
+			const current = await read(rootTaskId);
+			const node = current?.graph.nodes.find((entry) => entry.taskId === taskId);
+			if (!current || !node || !await canonical(node)) return false;
+			return satisfied(current.graph, node);
+		},
+		async seal({ rootTaskId, taskId }) {
+			taskIdSchema.parse(taskId);
+			for (;;) {
+				const current = await read(rootTaskId);
+				if (!current) throw new RecordNotFoundError("taskGraphs", rootTaskId);
+				const node = current.graph.nodes.find((entry) => entry.taskId === taskId);
+				if (!node) throw new Error(`Task ${taskId} is not registered in graph ${rootTaskId}`);
+				const task = await canonical(node);
+				if (!task) throw new RecordNotFoundError("tasks", taskId);
+				if (!node.sealed && task.state !== "queued") throw new Error(`Task ${taskId} must be queued for first execution admission; current state is ${task.state}`);
+				if (!await satisfied(current.graph, node)) throw new Error(`Task ${taskId} dependencies must all be succeeded before execution admission`);
+				if (node.sealed) return;
+				const graph = taskGraphSchema.parse({
+					...current.graph,
+					revision: current.graph.revision + 1,
+					nodes: current.graph.nodes.map((entry) => entry.taskId === taskId ? {
+						...entry,
+						sealed: true
+					} : entry),
+					updatedAt: now()
+				});
+				try {
+					await driver.update({
+						collection: "taskGraphs",
+						id: rootTaskId,
+						value: graph,
+						expectedVersion: current.version
+					});
+					return;
+				} catch (error) {
+					if (!(error instanceof VersionConflictError)) throw error;
+				}
+			}
+		}
+	};
+}
+//#endregion
+export { TaskGraphConflictError, assertTaskAdmission, createTaskGraphStore };
+
+//# sourceMappingURL=task-graphs.mjs.map

package/dist/store/task-graphs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-graphs.mjs","names":[],"sources":["../../src/store/task-graphs.ts"],"sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport type { WorkNotification } from \"./work-notifications\";\nimport { z } from \"zod\";\nimport { SCHEMA_VERSION } from \"../schema/common\";\nimport type { IsoDateTimeClock } from \"../schema/common\";\nimport { taskIdSchema, type TaskId } from \"../schema/id\";\nimport { taskSchema, type Task } from \"../schema/task\";\nimport {\n  taskGraphAdmissionSchema,\n  taskGraphDependenciesSchema,\n  taskGraphSchema,\n  type TaskGraph,\n  type TaskGraphNode,\n} from \"../schema/task-graph\";\nimport {\n  RecordExistsError,\n  RecordNotFoundError,\n  VersionConflictError,\n  type StoreDriver,\n} from \"./driver\";\n\n/** Engine-owned persistence and validation dependencies for canonical Task graphs. */\nexport interface CreateTaskGraphStoreOptions {\n  driver: StoreDriver;\n  now: IsoDateTimeClock;\n  getTask: (id: TaskId) => Promise<Task | null>;\n  validateTask: (task: Task) => void;\n  notify?: (event: WorkNotification) => Promise<void>;\n}\n\n/** Canonical bounded graph store for Task membership, ownership, and dependency edges. */\nexport interface TaskGraphStore {\n  admit(input: AdmitTaskGraphInput): Promise<void>;\n  get(rootTaskId: TaskId): Promise<TaskGraph | null>;\n  setDependencies(input: SetTaskGraphDependenciesInput): Promise<TaskGraph>;\n  dependenciesSatisfied(input: TaskGraphNodeRef): Promise<boolean>;\n  /** Call before every Task transition to running. First admission freezes edges, even if launch fails. */\n  seal(input: TaskGraphNodeRef): Promise<void>;\n}\n\n/** Canonical Task snapshot and initial dependency edges admitted atomically to its graph. */\nexport interface AdmitTaskGraphInput {\n  task: Task;\n  dependencies?: readonly TaskId[];\n}\n\n/** Identifies one Task within its canonical root graph. */\nexport interface TaskGraphNodeRef {\n  rootTaskId: TaskId;\n  taskId: TaskId;\n}\n\n/** Revision-fenced replacement of one queued Task's graph dependencies. */\nexport interface SetTaskGraphDependenciesInput extends TaskGraphNodeRef {\n  dependencies: readonly TaskId[];\n  expectedRevision: number;\n}\n\n/** Error raised when a creation retry differs from immutable graph admission intent. */\nexport class TaskGraphConflictError extends Error {\n  constructor(taskId: TaskId) {\n    super(\n      `Task ${taskId} conflicts with its immutable graph admission; reuse the original creation intent`,\n    );\n    this.name = \"TaskGraphConflictError\";\n  }\n}\n\n/** Canonical Task and immutable graph admission snapshot to compare. */\nexport interface AssertTaskAdmissionInput {\n  task: Task;\n  admission: Task;\n}\n\nfunction immutableTaskIdentity(task: Task): unknown {\n  const { id, rootTaskId, parentTaskId, repositoryIds, work, kind, origin, replyTo, area } = task;\n  // Omitted optional fields and explicit undefined have the same persisted identity.\n  return JSON.parse(\n    JSON.stringify({\n      id,\n      rootTaskId,\n      parentTaskId,\n      repositoryIds,\n      work,\n      kind,\n      origin,\n      replyTo,\n      area,\n    }),\n  );\n}\n\n/** Verifies that a canonical Task preserves the immutable identity admitted to its graph. */\nexport function assertTaskAdmission({ task, admission }: AssertTaskAdmissionInput): void {\n  if (!isDeepStrictEqual(immutableTaskIdentity(task), immutableTaskIdentity(admission))) {\n    throw new TaskGraphConflictError(admission.id);\n  }\n}\n\nfunction creationIntent({\n  createdAt: _createdAt,\n  updatedAt: _updatedAt,\n  ...intent\n}: Task): unknown {\n  // JSON persistence drops optional undefined fields; omitted and undefined have the same intent.\n  const value: unknown = JSON.parse(JSON.stringify(intent));\n  return value;\n}\n\n/**\n * Trusted engine/workflow capability, not an agent tool or HTTP boundary: callers own\n * authentication and workflow binding validation. The engine seals dependencies before\n * transitioning to running; sealing survives a failed launch and rechecks prerequisites\n * on retries. Succeeded prerequisites are terminal under the engine's transition rules.\n */\nexport function createTaskGraphStore({\n  driver,\n  now,\n  getTask,\n  validateTask,\n  notify,\n}: CreateTaskGraphStoreOptions): TaskGraphStore {\n  async function read(rootTaskId: TaskId) {\n    taskIdSchema.parse(rootTaskId);\n    const record = await driver.get(\"taskGraphs\", rootTaskId);\n    if (!record) return null;\n    const graph = taskGraphSchema.parse(record.value);\n    for (const node of graph.nodes) validateTask(node.admission);\n    if (graph.rootTaskId !== rootTaskId)\n      throw new Error(\"Stored graph root does not match its storage key\");\n    return { graph, version: record.version };\n  }\n\n  async function canonical(node: TaskGraphNode): Promise<Task | null> {\n    const value = await getTask(node.taskId);\n    if (value === null) return null;\n    const task = taskSchema.parse(value);\n    validateTask(task);\n    assertTaskAdmission({ task, admission: node.admission });\n    return task;\n  }\n\n  async function satisfied(graph: TaskGraph, node: TaskGraphNode): Promise<boolean> {\n    for (const id of node.dependencies) {\n      const dependency = graph.nodes.find((entry) => entry.taskId === id);\n      if (!dependency || (await canonical(dependency))?.state !== \"succeeded\") return false;\n    }\n    return true;\n  }\n\n  return {\n    async admit(input) {\n      // Zod's custom JSON schema validates but does not clone work.input.\n      const task = structuredClone(taskGraphAdmissionSchema.parse(input.task));\n      validateTask(task);\n      const initialDependencies = taskGraphDependenciesSchema.parse(input.dependencies ?? []);\n      const rootTaskId = taskIdSchema.parse(task.rootTaskId);\n      const node: TaskGraphNode = {\n        taskId: task.id,\n        ...(task.parentTaskId === undefined ? {} : { parentTaskId: task.parentTaskId }),\n        dependencies: initialDependencies,\n        sealed: false,\n        admissionDependencies: [...initialDependencies],\n        admission: task,\n      };\n      await canonical(node);\n      for (;;) {\n        const current = await read(rootTaskId);\n        const existing = current?.graph.nodes.find((entry) => entry.taskId === task.id);\n        if (existing) {\n          if (\n            !isDeepStrictEqual(creationIntent(existing.admission), creationIntent(task)) ||\n            !isDeepStrictEqual(existing.admissionDependencies, initialDependencies)\n          ) {\n            throw new TaskGraphConflictError(task.id);\n          }\n          return;\n        }\n        const timestamp = now();\n        const graph = taskGraphSchema.parse(\n          current\n            ? {\n                ...current.graph,\n                revision: current.graph.revision + 1,\n                nodes: [...current.graph.nodes, node],\n                updatedAt: timestamp,\n              }\n            : {\n                schemaVersion: SCHEMA_VERSION,\n                rootTaskId,\n                revision: 1,\n                nodes: [node],\n                createdAt: timestamp,\n                updatedAt: timestamp,\n              },\n        );\n        try {\n          if (current)\n            await driver.update({\n              collection: \"taskGraphs\",\n              id: rootTaskId,\n              value: graph,\n              expectedVersion: current.version,\n            });\n          else await driver.insert({ collection: \"taskGraphs\", id: rootTaskId, value: graph });\n          return;\n        } catch (error) {\n          if (!(error instanceof RecordExistsError || error instanceof VersionConflictError))\n            throw error;\n        }\n      }\n    },\n\n    async get(rootTaskId) {\n      return (await read(rootTaskId))?.graph ?? null;\n    },\n\n    async setDependencies(input) {\n      const { rootTaskId, taskId, dependencies, expectedRevision } = input;\n      taskIdSchema.parse(taskId);\n      z.number().int().positive().parse(expectedRevision);\n      const edges = taskGraphDependenciesSchema.parse(dependencies);\n      const current = await read(rootTaskId);\n      if (!current) throw new RecordNotFoundError(\"taskGraphs\", rootTaskId);\n      if (current.graph.revision !== expectedRevision) {\n        throw new VersionConflictError(\"taskGraphs\", rootTaskId, expectedRevision);\n      }\n      const node = current.graph.nodes.find((entry) => entry.taskId === taskId);\n      if (!node) throw new Error(`Task ${taskId} is not registered in graph ${rootTaskId}`);\n      if (node.sealed)\n        throw new Error(\n          `Task ${taskId} dependencies are sealed by first execution admission and cannot be changed`,\n        );\n      const task = await canonical(node);\n      if (!task) throw new RecordNotFoundError(\"tasks\", taskId);\n      if (task.state !== \"queued\")\n        throw new Error(\n          `Task ${taskId} must be queued to change dependencies; current state is ${task.state}`,\n        );\n      const graph = taskGraphSchema.parse({\n        ...current.graph,\n        revision: current.graph.revision + 1,\n        nodes: current.graph.nodes.map((entry) =>\n          entry.taskId === taskId ? { ...entry, dependencies: edges } : entry,\n        ),\n        updatedAt: now(),\n      });\n      // Deliberately do not retry: a losing editor must read the winning graph and replan.\n      await driver.update({\n        collection: \"taskGraphs\",\n        id: rootTaskId,\n        value: graph,\n        expectedVersion: current.version,\n      });\n      await notify?.({ rootTaskId, key: `dependencies:${rootTaskId}:${graph.revision}` });\n      return graph;\n    },\n\n    async dependenciesSatisfied({ rootTaskId, taskId }) {\n      taskIdSchema.parse(taskId);\n      const current = await read(rootTaskId);\n      const node = current?.graph.nodes.find((entry) => entry.taskId === taskId);\n      if (!current || !node || !(await canonical(node))) return false;\n      return satisfied(current.graph, node);\n    },\n\n    async seal({ rootTaskId, taskId }) {\n      taskIdSchema.parse(taskId);\n      for (;;) {\n        const current = await read(rootTaskId);\n        if (!current) throw new RecordNotFoundError(\"taskGraphs\", rootTaskId);\n        const node = current.graph.nodes.find((entry) => entry.taskId === taskId);\n        if (!node) throw new Error(`Task ${taskId} is not registered in graph ${rootTaskId}`);\n        const task = await canonical(node);\n        if (!task) throw new RecordNotFoundError(\"tasks\", taskId);\n        if (!node.sealed && task.state !== \"queued\") {\n          throw new Error(\n            `Task ${taskId} must be queued for first execution admission; current state is ${task.state}`,\n          );\n        }\n        if (!(await satisfied(current.graph, node))) {\n          throw new Error(\n            `Task ${taskId} dependencies must all be succeeded before execution admission`,\n          );\n        }\n        if (node.sealed) return;\n        const graph = taskGraphSchema.parse({\n          ...current.graph,\n          revision: current.graph.revision + 1,\n          nodes: current.graph.nodes.map((entry) =>\n            entry.taskId === taskId ? { ...entry, sealed: true } : entry,\n          ),\n          updatedAt: now(),\n        });\n        try {\n          await driver.update({\n            collection: \"taskGraphs\",\n            id: rootTaskId,\n            value: graph,\n            expectedVersion: current.version,\n          });\n          return;\n        } catch (error) {\n          // An edge edit may have won: re-read its dependencies and validate them before sealing.\n          if (!(error instanceof VersionConflictError)) throw error;\n        }\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/store/task-messages.d.mts

@@ -0,0 +1,136 @@
+import { TaskId } from "../schema/id.mjs";
+import { Task } from "../schema/task.mjs";
+import { SendTaskMessageInput, TaskMessage, TaskMessageClaim, TaskMessageDiscard, TaskMessageId, TaskMessagePrincipal, TaskMessageProcessing, TaskMessageProtocolBinding, TaskMessageProtocols } from "../schema/task-message.mjs";
+import { WorkNotification } from "./work-notifications.mjs";
+import { DateClock } from "../schema/common.mjs";
+import { TaskAttemptRef } from "../schema/execution.mjs";
+import { StoreDriver } from "./driver.mjs";
+//#region src/store/task-messages.d.ts
+/** Operation categories evaluated by the Task message authorization boundary. */
+type TaskMessageAction = "send" | "send_result" | "read" | "claim" | "complete" | "discard";
+/** Principal, requested action, and validated Task scope for one authorization decision. */
+interface TaskMessageAuthorizationInput {
+  readonly principal: TaskMessagePrincipal;
+  readonly action: TaskMessageAction;
+  readonly fromTask?: Task;
+  readonly toTask: Task;
+}
+/** Trusted application authorization, NOT HTTP authentication. Only literal true grants access. */
+type TaskMessageAuthorize = (input: TaskMessageAuthorizationInput) => boolean | Promise<boolean>;
+/** Engine-owned dependencies and deny-by-default policy used to create a Task message store. */
+interface CreateTaskMessageStoreOptions {
+  readonly driver: StoreDriver;
+  readonly now: DateClock;
+  /**
+   * Main engine supplies schema-validated snapshots. Task reads and inbox CAS are separate:
+   * cancellation/retry can race send, claim, and caller effects. The envelope retains expectAttempt;
+   * consumers must fence effects at their application boundary, not assume atomic cancellation here.
+   */
+  readonly getTask: (id: TaskId) => Promise<Task | null>;
+  readonly protocols: TaskMessageProtocols;
+  readonly authorize: TaskMessageAuthorize;
+  readonly notify?: (event: WorkNotification) => Promise<void>;
+}
+/** Authenticated principal and immutable message intent used for one send operation. */
+interface TaskMessageSendInput<Type extends TaskMessageProtocolBinding = TaskMessageProtocolBinding> {
+  readonly principal: TaskMessagePrincipal;
+  readonly message: SendTaskMessageInput<Type>;
+}
+/** Authenticated principal and recipient identifying one Task inbox. */
+interface TaskMessageRecipientInput {
+  readonly principal: TaskMessagePrincipal;
+  readonly toTaskId: TaskId;
+}
+/** Authenticated principal, recipient, and immutable message identifying one inbox record. */
+interface TaskMessageLookupInput extends TaskMessageRecipientInput {
+  readonly messageId: TaskMessageId;
+}
+/** Recipient attempt and bounded lease requested when claiming one Task message. */
+interface ClaimTaskMessageInput extends Pick<TaskMessageRecipientInput, "principal"> {
+  readonly task: TaskAttemptRef;
+  readonly leaseMs: number;
+  readonly recoverCompleted?: boolean;
+}
+/** Authenticated lease and committed-effects attestation used to acknowledge one message. */
+interface CompleteTaskMessageInput {
+  readonly principal: TaskMessagePrincipal;
+  readonly claim: TaskMessageClaim;
+  readonly effectsCommitted: true;
+}
+/** Authenticated lease whose current validity must be checked before an external effect. */
+interface AssertTaskMessageClaimInput {
+  readonly principal: TaskMessagePrincipal;
+  readonly claim: TaskMessageClaim;
+}
+/** Authorized reason for discarding one exact pending inbox head. */
+interface DiscardTaskMessageInput extends TaskMessageLookupInput {
+  readonly reason: string;
+}
+/** Message identity and stable operation name used to derive an external-effect key. */
+interface TaskMessageEffectKeyInput {
+  readonly messageId: TaskMessageId;
+  readonly operation: string;
+}
+/** Message and lease returned when one pending inbox head is claimed. */
+interface ClaimTaskMessageResult {
+  readonly claim: TaskMessageClaim;
+  readonly message: TaskMessage;
+}
+/** Trusted API for immutable Task messages, recipient inboxes, leases, and acknowledgments. */
+interface TaskMessageStore {
+  send<const Type extends TaskMessageProtocolBinding>(input: TaskMessageSendInput<Type>): Promise<TaskMessage<Type>>;
+  /** Trusted workflow delivery after the source outcome is persisted; requires separate send_result authorization. */
+  sendResult<const Type extends TaskMessageProtocolBinding>(input: TaskMessageSendInput<Type>): Promise<TaskMessage<Type>>;
+  get(input: TaskMessageLookupInput): Promise<TaskMessage | null>;
+  pending(input: TaskMessageRecipientInput): Promise<readonly TaskMessage[]>;
+  /**
+   * A stale attempt-fenced source or cancelled ordinary source raises TaskMessageSourceFenceError
+   * and leaves the head pending. Protocols default to attempt fencing; explicitly task-scoped
+   * protocols let workflow triggers survive source retries. Authorized discard can unblock the inbox.
+   * Source completion alone does not invalidate previously admitted messages from the same attempt.
+   * recoverCompleted defaults to false. It is a trusted application recovery capability for a
+   * succeeded/failed recipient: the caller must first validate an exact persisted decision for
+   * the pending message, then verify the claimed message matches it. It authorizes no new effects,
+   * never permits cancellation recovery, and does not bypass the authorization callback.
+   */
+  claim(input: ClaimTaskMessageInput): Promise<ClaimTaskMessageResult | null>;
+  /**
+   * Call only after effects commit. A matching recipient attempt may acknowledge in any state,
+   * including cancellation; acknowledgment authorizes no new effects. Leases are not exactly-once.
+   */
+  complete(input: CompleteTaskMessageInput): Promise<TaskMessageProcessing>;
+  /** Read-only claim/complete-authorized lease snapshot check, not a lease extension or external effect fence. Completed claims are invalid. */
+  assertClaim(input: AssertTaskMessageClaimInput): Promise<void>;
+  /** Discard only the pending head with no unexpired recipient lease, under explicit discard authorization. */
+  discard(input: DiscardTaskMessageInput): Promise<void>;
+  discarded(input: TaskMessageLookupInput): Promise<TaskMessageDiscard | null>;
+  processing(input: TaskMessageLookupInput): Promise<TaskMessageProcessing | null>;
+  /** Pure key derivation, not a read or an authorization capability. */
+  effectKey(input: TaskMessageEffectKeyInput): string;
+}
+/** Base error for Task message admission, authorization, and processing failures. */
+declare class TaskMessageError extends Error {}
+/** Error raised when an idempotency key is reused with different message intent. */
+declare class TaskMessageConflictError extends TaskMessageError {}
+/** Error raised when a configured Task message policy does not grant an operation. */
+declare class TaskMessageAuthorizationError extends TaskMessageError {}
+/** Error raised when a Task inbox claim is expired, replaced, or otherwise invalid. */
+declare class TaskMessageLeaseError extends TaskMessageError {}
+/** Error raised when an inbox head belongs to a stale or cancelled source attempt. */
+declare class TaskMessageSourceFenceError extends TaskMessageError {
+  readonly messageId: TaskMessageId;
+  readonly source: TaskAttemptRef;
+  readonly currentAttempt: number;
+  readonly sourceState: Task["state"];
+  constructor(messageId: TaskMessageId, source: TaskAttemptRef, currentAttempt: number, sourceState: Task["state"]);
+}
+/**
+ * Authorizes recipient-local operations and direct parent-child sends for a trusted
+ * Task-bound principal while denying result delivery and discard.
+ */
+declare const taskBoundMessagePolicy: TaskMessageAuthorize;
+/** Creates the trusted, CAS-backed Task message and recipient-inbox store. */
+declare function createTaskMessageStore(options: CreateTaskMessageStoreOptions): TaskMessageStore;
+//#endregion
+export { AssertTaskMessageClaimInput, ClaimTaskMessageInput, ClaimTaskMessageResult, CompleteTaskMessageInput, CreateTaskMessageStoreOptions, DiscardTaskMessageInput, TaskMessageAction, TaskMessageAuthorizationError, TaskMessageAuthorizationInput, TaskMessageAuthorize, TaskMessageConflictError, TaskMessageEffectKeyInput, TaskMessageError, TaskMessageLeaseError, TaskMessageLookupInput, TaskMessageRecipientInput, TaskMessageSendInput, TaskMessageSourceFenceError, TaskMessageStore, createTaskMessageStore, taskBoundMessagePolicy };
+//# sourceMappingURL=task-messages.d.mts.map