@vercel/factory 0.0.14 → 0.0.16

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

package/dist/store/task-messages.mjs

@@ -0,0 +1,475 @@
+import { taskIdSchema } from "../schema/id.mjs";
+import "../schema/common.mjs";
+import { taskAttemptRefSchema } from "../schema/execution.mjs";
+import { RecordExistsError, VersionConflictError } from "./driver.mjs";
+import { sendTaskMessageInputSchema, taskInboxSchema, taskMessageClaimSchema, taskMessageDiscardSchema, taskMessageIdSchema, taskMessagePrincipalSchema, taskMessageProcessingSchema, taskMessageReservationSchema, taskMessageSchema } from "../schema/task-message.mjs";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { isDeepStrictEqual } from "node:util";
+//#region src/store/task-messages.ts
+/** Base error for Task message admission, authorization, and processing failures. */
+var TaskMessageError = class extends Error {};
+/** Error raised when an idempotency key is reused with different message intent. */
+var TaskMessageConflictError = class extends TaskMessageError {};
+/** Error raised when a configured Task message policy does not grant an operation. */
+var TaskMessageAuthorizationError = class extends TaskMessageError {};
+/** Error raised when a Task inbox claim is expired, replaced, or otherwise invalid. */
+var TaskMessageLeaseError = class extends TaskMessageError {};
+/** Error raised when an inbox head belongs to a stale or cancelled source attempt. */
+var TaskMessageSourceFenceError = class extends TaskMessageError {
+	messageId;
+	source;
+	currentAttempt;
+	sourceState;
+	constructor(messageId, source, currentAttempt, sourceState) {
+		super(`Inbox blocked by message ${messageId}: source ${source.taskId} attempt ${source.attempt}, current attempt ${currentAttempt}, state ${sourceState}. Message remains pending; an explicitly authorized discard is required to unblock this inbox.`);
+		this.messageId = messageId;
+		this.source = source;
+		this.currentAttempt = currentAttempt;
+		this.sourceState = sourceState;
+		this.name = "TaskMessageSourceFenceError";
+	}
+};
+/**
+* Authorizes recipient-local operations and direct parent-child sends for a trusted
+* Task-bound principal while denying result delivery and discard.
+*/
+const taskBoundMessagePolicy = ({ principal, action, fromTask, toTask }) => {
+	if (action === "discard" || action === "send_result") return false;
+	if (action !== "send") return principal.taskId === toTask.id;
+	if (!fromTask || !principal.taskId) return false;
+	return principal.taskId === fromTask.id && (fromTask.parentTaskId === toTask.id || toTask.parentTaskId === fromTask.id);
+};
+const claimOptionsSchema = z.strictObject({
+	leaseMs: z.number().int().min(1).max(3e5).describe("Processing lease duration, at most five minutes."),
+	recoverCompleted: z.boolean().default(false).describe("Trusted recovery of an exact existing decision on a succeeded/failed recipient at the same attempt; not permission for new effects or cancelled Tasks.")
+});
+const acknowledgmentSchema = z.strictObject({ effectsCommitted: z.literal(true).describe("Effects committed before this acknowledgment.") });
+const hash = (parts) => createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+const messageIdFor = (source, operation) => taskMessageIdSchema.parse(`msg_${hash([source, operation])}`);
+const messageContent = ({ createdAt: _createdAt, ...content }) => content;
+const retryable = (error) => error instanceof VersionConflictError || error instanceof RecordExistsError;
+/** Creates the trusted, CAS-backed Task message and recipient-inbox store. */
+function createTaskMessageStore(options) {
+	const { driver, now, getTask, protocols, authorize } = options;
+	if (typeof authorize !== "function") throw new TaskMessageAuthorizationError("Task messages require an explicit authorize callback; no access is granted by default");
+	async function task(id) {
+		const value = await getTask(taskIdSchema.parse(id));
+		if (!value || value.id !== id) throw new TaskMessageError(`Missing Task ${id}`);
+		taskIdSchema.parse(value.rootTaskId);
+		return value;
+	}
+	async function scope(principal, action, toTaskId, fromTaskId) {
+		const toTask = await task(toTaskId);
+		const fromTask = fromTaskId === void 0 ? void 0 : await task(fromTaskId);
+		if (fromTask && fromTask.rootTaskId !== toTask.rootTaskId) throw new TaskMessageAuthorizationError("Cross-root Task messages are not permitted");
+		if ((action === "send" || action === "send_result") && principal.taskId !== void 0 && principal.taskId !== fromTaskId) throw new TaskMessageAuthorizationError("Task-bound sender must equal fromTaskId");
+		if (await authorize(structuredClone({
+			principal,
+			action,
+			fromTask,
+			toTask
+		})) !== true) throw new TaskMessageAuthorizationError(`Task message ${action} denied for ${principal.id}`);
+		return {
+			fromTask,
+			toTask
+		};
+	}
+	function matchingAttempt(value, expected) {
+		if (value.attempt !== expected) throw new TaskMessageError(`Task ${value.id} requires current attempt ${value.attempt}; received ${expected}`);
+	}
+	function activeAttempt(value, expected) {
+		if (value.attempt !== expected || ![
+			"queued",
+			"running",
+			"needs_human"
+		].includes(value.state)) throw new TaskMessageError(`Task ${value.id} requires current attempt ${value.attempt} and queued, running, or needs_human state`);
+	}
+	function resultAttempt(value, expected) {
+		matchingAttempt(value, expected);
+		if (![
+			"succeeded",
+			"failed",
+			"cancelled"
+		].includes(value.state)) throw new TaskMessageError(`Task ${value.id} requires a persisted succeeded, failed, or cancelled outcome for result delivery`);
+	}
+	function claimableAttempt(value, expected, recoverCompleted) {
+		if (recoverCompleted && (value.state === "succeeded" || value.state === "failed")) matchingAttempt(value, expected);
+		else activeAttempt(value, expected);
+	}
+	function parseMessage(value) {
+		const { causationId, delivery, ...message } = taskMessageSchema.parse(value);
+		if (message.id !== messageIdFor(message.fromTaskId, message.operationId)) throw new TaskMessageConflictError("Stored message ID does not match its source and operation");
+		return {
+			...message,
+			...causationId === void 0 ? {} : { causationId },
+			...delivery === void 0 ? {} : { delivery },
+			payload: protocols.validateStored(message.type, message.payload)
+		};
+	}
+	function correlateMessage(message, type) {
+		if (message.type.id !== type.id || message.type.version !== type.version) throw new TaskMessageConflictError("Message protocol differs from its send intent");
+		const payload = protocols.validateStored(type, message.payload);
+		return structuredClone({
+			...message,
+			payload
+		});
+	}
+	async function deliveredMessage(intent) {
+		const stored = await driver.get("taskMessages", intent.id);
+		if (!stored) return null;
+		const delivered = parseMessage(stored.value);
+		if (!isDeepStrictEqual(messageContent(delivered), messageContent(intent))) throw new TaskMessageConflictError(`Operation ${intent.operationId} was reused with different content or attempt`);
+		return delivered;
+	}
+	async function immutable(collection, id, value, parse) {
+		const validated = parse(value);
+		try {
+			await driver.insert({
+				collection,
+				id,
+				value: validated
+			});
+		} catch (error) {
+			if (!(error instanceof RecordExistsError)) throw error;
+			const stored = await driver.get(collection, id);
+			if (!stored || !isDeepStrictEqual(parse(stored.value), validated)) throw new TaskMessageConflictError(`Immutable record ${id} has different content`);
+		}
+		return validated;
+	}
+	async function inbox(toTaskId) {
+		const stored = await driver.get("taskInboxes", toTaskId);
+		const value = stored ? taskInboxSchema.parse(stored.value) : taskInboxSchema.parse({
+			schemaVersion: 1,
+			toTaskId,
+			generation: 0,
+			pending: []
+		});
+		if (value.toTaskId !== toTaskId) throw new TaskMessageError("Stored inbox recipient mismatch");
+		value.pending = value.pending.map(parseMessage);
+		return {
+			value,
+			version: stored?.version
+		};
+	}
+	async function saveInbox(value, version) {
+		const validated = taskInboxSchema.parse(value);
+		try {
+			if (version === void 0) await driver.insert({
+				collection: "taskInboxes",
+				id: value.toTaskId,
+				value: validated
+			});
+			else await driver.update({
+				collection: "taskInboxes",
+				id: value.toTaskId,
+				value: validated,
+				expectedVersion: version
+			});
+			return true;
+		} catch (error) {
+			if (retryable(error)) return false;
+			throw error;
+		}
+	}
+	async function repair(principal, toTaskId, action, targetId) {
+		for (;;) {
+			await scope(principal, action, toTaskId);
+			const current = await inbox(toTaskId);
+			for (const message of current.value.pending) {
+				if (targetId !== void 0 && message.id !== targetId) continue;
+				await immutable("taskMessages", message.id, message, parseMessage);
+			}
+			const { completion, rejection } = current.value;
+			const resolved = completion ?? rejection;
+			if (!resolved || targetId !== void 0 && resolved.messageId !== targetId) return current;
+			if (completion) await immutable("taskMessageProcessing", completion.messageId, completion, (value) => taskMessageProcessingSchema.parse(value));
+			if (rejection) await immutable("taskMessageDiscards", rejection.messageId, rejection, (value) => taskMessageDiscardSchema.parse(value));
+			if (await saveInbox({
+				...current.value,
+				pending: current.value.pending.filter((message) => message.id !== resolved.messageId),
+				lease: void 0,
+				completion: void 0,
+				rejection: void 0
+			}, current.version)) continue;
+		}
+	}
+	async function reserve(message, expectAttempt) {
+		const key = `reservation_${message.id}`;
+		const reservation = taskMessageReservationSchema.parse({
+			schemaVersion: 1,
+			message,
+			expectAttempt
+		});
+		try {
+			await driver.insert({
+				collection: "taskMessageProcessing",
+				id: key,
+				value: reservation
+			});
+			return message;
+		} catch (error) {
+			if (!(error instanceof RecordExistsError)) throw error;
+			const stored = await driver.get("taskMessageProcessing", key);
+			if (!stored) throw new TaskMessageConflictError(`Missing operation reservation ${message.id}`);
+			const existing = taskMessageReservationSchema.parse(stored.value);
+			const original = parseMessage(existing.message);
+			if (existing.expectAttempt !== expectAttempt || !isDeepStrictEqual(messageContent(original), messageContent(message))) throw new TaskMessageConflictError(`Operation ${message.operationId} was reused with different content or attempt`);
+			return original;
+		}
+	}
+	async function readMessage(principal, toTaskId, messageId, action) {
+		taskMessageIdSchema.parse(messageId);
+		await scope(principal, action, toTaskId);
+		await repair(principal, toTaskId, action, messageId);
+		const stored = await driver.get("taskMessages", messageId);
+		if (!stored) return null;
+		const message = parseMessage(stored.value);
+		if (message.id !== messageId || message.toTaskId !== toTaskId) throw new TaskMessageAuthorizationError("Message does not belong to this recipient");
+		await scope(principal, action, toTaskId, message.fromTaskId);
+		return message;
+	}
+	async function processingRecord(messageId) {
+		const stored = await driver.get("taskMessageProcessing", messageId);
+		if (!stored) return null;
+		const record = taskMessageProcessingSchema.parse(stored.value);
+		if (record.messageId !== messageId) throw new TaskMessageError("Processing record identity mismatch");
+		return record;
+	}
+	async function discardRecord(messageId) {
+		const stored = await driver.get("taskMessageDiscards", messageId);
+		if (!stored) return null;
+		const record = taskMessageDiscardSchema.parse(stored.value);
+		if (record.messageId !== messageId) throw new TaskMessageError("Discard record identity mismatch");
+		return record;
+	}
+	async function requireLiveClaim(principal, claim, current) {
+		if (principal.id !== claim.principalId) throw new TaskMessageAuthorizationError("Only the claiming principal may validate this lease");
+		matchingAttempt(await task(claim.toTaskId), claim.attempt);
+		const time = now();
+		if (current.completion || current.rejection || current.generation !== claim.generation || !isDeepStrictEqual(current.lease, claim) || Date.parse(claim.expiresAt) <= time.getTime()) throw new TaskMessageLeaseError("Lease expired, resolved, or was replaced; claim again before processing");
+		return time;
+	}
+	function requireClaim(record, claim) {
+		const { schemaVersion: _schemaVersion, completedAt: _completedAt, effectsCommitted: _effectsCommitted, ...accepted } = record;
+		if (!isDeepStrictEqual(accepted, claim)) throw new TaskMessageLeaseError("Processing acknowledgment belongs to a different lease generation");
+		return record;
+	}
+	async function send(context, input, delivery) {
+		const principal = taskMessagePrincipalSchema.parse(context);
+		const parsed = sendTaskMessageInputSchema.parse(input);
+		const payload = protocols.validate(input.type, parsed.payload);
+		const { expectAttempt } = parsed;
+		const action = delivery === "result" ? "send_result" : "send";
+		await scope(principal, action, parsed.toTaskId, parsed.fromTaskId);
+		const intent = correlateMessage(parseMessage({
+			...parsed,
+			payload,
+			delivery,
+			schemaVersion: 1,
+			id: messageIdFor(parsed.fromTaskId, parsed.operationId),
+			createdAt: now().toISOString()
+		}), input.type);
+		const delivered = await deliveredMessage(intent);
+		if (delivery === "result") resultAttempt(await task(parsed.fromTaskId), expectAttempt);
+		if (delivered) return correlateMessage(delivered, input.type);
+		if (delivery !== "result") activeAttempt(await task(parsed.fromTaskId), expectAttempt);
+		const recipient = await task(parsed.toTaskId);
+		activeAttempt(recipient, recipient.attempt);
+		if (parsed.causationId) {
+			const stored = await driver.get("taskMessages", parsed.causationId);
+			if (!stored) throw new TaskMessageError("Causation message must already be durably delivered");
+			const cause = parseMessage(stored.value);
+			await scope(principal, "read", cause.toTaskId, cause.fromTaskId);
+			if ((await task(cause.toTaskId)).rootTaskId !== recipient.rootTaskId) throw new TaskMessageAuthorizationError("Causation must stay within the Task root");
+		}
+		const message = correlateMessage(await reserve(intent, expectAttempt), input.type);
+		for (;;) {
+			await scope(principal, action, message.toTaskId, message.fromTaskId);
+			const current = await inbox(message.toTaskId);
+			const delivered = await deliveredMessage(message);
+			if (delivery === "result") resultAttempt(await task(message.fromTaskId), expectAttempt);
+			if (delivered) return correlateMessage(delivered, input.type);
+			if (delivery !== "result") activeAttempt(await task(message.fromTaskId), expectAttempt);
+			const recipient = await task(message.toTaskId);
+			activeAttempt(recipient, recipient.attempt);
+			const pending = current.value.pending.find((entry) => entry.id === message.id);
+			if (pending) {
+				if (!isDeepStrictEqual(pending, message)) throw new TaskMessageConflictError("Inbox message differs from reserved intent");
+			} else {
+				if (current.value.pending.length >= 256) throw new TaskMessageError(`Recipient inbox is full; maximum 256 pending messages`);
+				if (!await saveInbox({
+					...current.value,
+					pending: [...current.value.pending, message]
+				}, current.version)) continue;
+			}
+			return correlateMessage(await immutable("taskMessages", message.id, message, parseMessage), input.type);
+		}
+	}
+	async function sendAndNotify(principal, input, delivery) {
+		const message = await send(principal, input, delivery);
+		if (options.notify) {
+			const recipient = await task(message.toTaskId);
+			await options.notify({
+				rootTaskId: recipient.rootTaskId,
+				key: `message:${message.id}`
+			});
+		}
+		return message;
+	}
+	return {
+		send: ({ principal, message }) => sendAndNotify(principal, message),
+		sendResult: ({ principal, message }) => sendAndNotify(principal, message, "result"),
+		async get({ principal: context, toTaskId, messageId }) {
+			return readMessage(taskMessagePrincipalSchema.parse(context), toTaskId, messageId, "read");
+		},
+		async pending({ principal: context, toTaskId }) {
+			const principal = taskMessagePrincipalSchema.parse(context);
+			const current = await repair(principal, toTaskId, "read");
+			for (const message of current.value.pending) await scope(principal, "read", toTaskId, message.fromTaskId);
+			return current.value.pending;
+		},
+		async claim({ principal: context, task: inputTask, ...input }) {
+			const principal = taskMessagePrincipalSchema.parse(context);
+			const { taskId: toTaskId, attempt } = taskAttemptRefSchema.parse(inputTask);
+			const { leaseMs, recoverCompleted } = claimOptionsSchema.parse(input);
+			for (;;) {
+				const current = await repair(principal, toTaskId, "claim");
+				const message = current.value.pending[0];
+				if (message) await scope(principal, "claim", toTaskId, message.fromTaskId);
+				const recipient = await task(toTaskId);
+				claimableAttempt(recipient, attempt, recoverCompleted);
+				if (current.value.lease && current.value.lease.attempt === recipient.attempt && Date.parse(current.value.lease.expiresAt) > now().getTime()) return null;
+				if (!message) return null;
+				const source = await task(message.fromTaskId);
+				if (protocols.sourceFence(message.type) === "attempt" && source.attempt !== message.expectAttempt || source.state === "cancelled" && message.delivery !== "result") throw new TaskMessageSourceFenceError(message.id, {
+					taskId: source.id,
+					attempt: message.expectAttempt
+				}, source.attempt, source.state);
+				claimableAttempt(await task(toTaskId), attempt, recoverCompleted);
+				const time = now();
+				const claim = taskMessageClaimSchema.parse({
+					messageId: message.id,
+					toTaskId,
+					generation: current.value.generation + 1,
+					principalId: principal.id,
+					attempt,
+					expiresAt: new Date(time.getTime() + leaseMs).toISOString()
+				});
+				if (await saveInbox({
+					...current.value,
+					generation: claim.generation,
+					lease: claim
+				}, current.version)) return {
+					claim,
+					message
+				};
+			}
+		},
+		async complete({ principal: context, claim: input, effectsCommitted }) {
+			const principal = taskMessagePrincipalSchema.parse(context);
+			const claim = taskMessageClaimSchema.parse(input);
+			acknowledgmentSchema.parse({ effectsCommitted });
+			if (principal.id !== claim.principalId) throw new TaskMessageAuthorizationError("Only the claiming principal may acknowledge processing");
+			const message = await readMessage(principal, claim.toTaskId, claim.messageId, "complete");
+			if (!message) throw new TaskMessageLeaseError("Claimed message does not exist");
+			for (;;) {
+				await scope(principal, "complete", claim.toTaskId, message.fromTaskId);
+				const current = await inbox(claim.toTaskId);
+				const completed = await processingRecord(claim.messageId);
+				if (completed) return requireClaim(completed, claim);
+				if (current.value.completion) {
+					requireClaim(current.value.completion, claim);
+					await repair(principal, claim.toTaskId, "complete", claim.messageId);
+					continue;
+				}
+				const time = await requireLiveClaim(principal, claim, current.value);
+				const completion = taskMessageProcessingSchema.parse({
+					...claim,
+					schemaVersion: 1,
+					effectsCommitted: true,
+					completedAt: time.toISOString()
+				});
+				if (!await saveInbox({
+					...current.value,
+					completion
+				}, current.version)) continue;
+				await repair(principal, claim.toTaskId, "complete", claim.messageId);
+				return completion;
+			}
+		},
+		async assertClaim({ principal: context, claim: input }) {
+			const principal = taskMessagePrincipalSchema.parse(context);
+			const claim = taskMessageClaimSchema.parse(input);
+			if (principal.id !== claim.principalId) throw new TaskMessageAuthorizationError("Only the claiming principal may validate this lease");
+			await scope(principal, "claim", claim.toTaskId);
+			const stored = await driver.get("taskMessages", claim.messageId);
+			if (!stored) throw new TaskMessageLeaseError("Claimed message does not exist");
+			const message = parseMessage(stored.value);
+			if (message.id !== claim.messageId || message.toTaskId !== claim.toTaskId) throw new TaskMessageAuthorizationError("Claim does not belong to this recipient");
+			await scope(principal, "claim", claim.toTaskId, message.fromTaskId);
+			await scope(principal, "complete", claim.toTaskId, message.fromTaskId);
+			const completed = await processingRecord(claim.messageId);
+			if (completed) {
+				requireClaim(completed, claim);
+				throw new TaskMessageLeaseError("Message processing is already complete; the claim is no longer active");
+			}
+			await requireLiveClaim(principal, claim, (await inbox(claim.toTaskId)).value);
+		},
+		async discard({ principal: context, toTaskId, messageId, reason: inputReason }) {
+			const principal = taskMessagePrincipalSchema.parse(context);
+			const reason = taskMessageDiscardSchema.shape.reason.parse(inputReason);
+			const message = await readMessage(principal, toTaskId, messageId, "discard");
+			if (!message) throw new TaskMessageError("Cannot discard a missing message");
+			for (;;) {
+				await scope(principal, "discard", toTaskId, message.fromTaskId);
+				const current = await repair(principal, toTaskId, "discard", messageId);
+				const discarded = await discardRecord(messageId);
+				if (discarded) {
+					if (discarded.toTaskId !== toTaskId || discarded.reason !== reason || !isDeepStrictEqual(discarded.by, principal)) throw new TaskMessageConflictError("Message already has a different discard decision");
+					return;
+				}
+				if (await processingRecord(messageId)) throw new TaskMessageConflictError("Processed messages cannot be discarded");
+				if (current.value.pending[0]?.id !== messageId) throw new TaskMessageError("Only the pending inbox head may be discarded");
+				const time = now();
+				if (current.value.lease && Date.parse(current.value.lease.expiresAt) > time.getTime()) throw new TaskMessageLeaseError("Cannot discard while the recipient has an unexpired lease, including a prior Task attempt");
+				const rejection = taskMessageDiscardSchema.parse({
+					schemaVersion: 1,
+					messageId,
+					toTaskId,
+					reason,
+					by: principal,
+					discardedAt: time.toISOString()
+				});
+				if (!await saveInbox({
+					...current.value,
+					lease: void 0,
+					rejection
+				}, current.version)) continue;
+				await repair(principal, toTaskId, "discard", messageId);
+				return;
+			}
+		},
+		async discarded({ principal: context, toTaskId, messageId }) {
+			if (!await readMessage(taskMessagePrincipalSchema.parse(context), toTaskId, messageId, "read")) return null;
+			const record = await discardRecord(messageId);
+			if (record && record.toTaskId !== toTaskId) throw new TaskMessageError("Discard record recipient mismatch");
+			return record;
+		},
+		async processing({ principal: context, toTaskId, messageId }) {
+			if (!await readMessage(taskMessagePrincipalSchema.parse(context), toTaskId, messageId, "read")) return null;
+			const record = await processingRecord(messageId);
+			if (record && record.toTaskId !== toTaskId) throw new TaskMessageError("Processing record recipient mismatch");
+			return record;
+		},
+		effectKey({ messageId, operation }) {
+			taskMessageIdSchema.parse(messageId);
+			z.string().min(1).max(256).parse(operation);
+			return `effect_${hash([messageId, operation])}`;
+		}
+	};
+}
+//#endregion
+export { TaskMessageAuthorizationError, TaskMessageConflictError, TaskMessageError, TaskMessageLeaseError, TaskMessageSourceFenceError, createTaskMessageStore, taskBoundMessagePolicy };
+
+//# sourceMappingURL=task-messages.mjs.map