@vercel/factory 0.0.15 → 0.0.16

package/dist/store/memory.d.mts

@@ -1,6 +1,23 @@
 import { StoreDriver } from "./driver.mjs";
 //#region src/store/memory.d.ts
-/** Creates a process-local, non-durable StoreDriver for development and tests. */
+/**
+ * Creates an isolated process-local StoreDriver for development, examples, and tests.
+ *
+ * @remarks
+ * Every call creates a new empty store. Records survive only for the lifetime of the returned
+ * object and are cloned at the driver boundary, so mutating caller-owned values cannot mutate
+ * stored state. Use a persistent adapter from `@vercel/factory/storage/blob` or
+ * `@vercel/factory/storage/postgres` in deployed runtimes.
+ *
+ * @returns A new empty driver whose `name` is `memory`.
+ *
+ * @example
+ * ```ts
+ * import { createInMemoryDriver, createStores } from "@vercel/factory/storage";
+ *
+ * const stores = createStores({ driver: createInMemoryDriver() });
+ * ```
+ */
 declare function createInMemoryDriver(): StoreDriver;
 //#endregion
 export { createInMemoryDriver };

package/dist/store/memory.mjs

@@ -1,6 +1,23 @@
 import { RecordExistsError, RecordNotFoundError, VersionConflictError } from "./driver.mjs";
 //#region src/store/memory.ts
-/** Creates a process-local, non-durable StoreDriver for development and tests. */
+/**
+* Creates an isolated process-local StoreDriver for development, examples, and tests.
+*
+* @remarks
+* Every call creates a new empty store. Records survive only for the lifetime of the returned
+* object and are cloned at the driver boundary, so mutating caller-owned values cannot mutate
+* stored state. Use a persistent adapter from `@vercel/factory/storage/blob` or
+* `@vercel/factory/storage/postgres` in deployed runtimes.
+*
+* @returns A new empty driver whose `name` is `memory`.
+*
+* @example
+* ```ts
+* import { createInMemoryDriver, createStores } from "@vercel/factory/storage";
+*
+* const stores = createStores({ driver: createInMemoryDriver() });
+* ```
+*/
 function createInMemoryDriver() {
 	const collections = /* @__PURE__ */ new Map();
 	function collection(name) {

package/dist/store/memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"memory.mjs","names":[],"sources":["../../src/store/memory.ts"],"sourcesContent":["import {\n  RecordExistsError,\n  RecordNotFoundError,\n  VersionConflictError,\n  type CollectionName,\n  type StoredEntry,\n  type StoredRecord,\n  type StoreDriver,\n} from \"./driver\";\n\n/** Creates a process-local, non-durable StoreDriver for development and tests. */\nexport function createInMemoryDriver(): StoreDriver {\n  const collections = new Map<CollectionName, Map<string, StoredRecord>>();\n\n  function collection(name: CollectionName): Map<string, StoredRecord> {\n    let existing = collections.get(name);\n    if (existing === undefined) {\n      existing = new Map();\n      collections.set(name, existing);\n    }\n    return existing;\n  }\n\n  return {\n    name: \"memory\",\n\n    get(name, id) {\n      const record = collection(name).get(id);\n      return Promise.resolve(record === undefined ? null : structuredClone(record));\n    },\n\n    insert({ collection: name, id, value }) {\n      const records = collection(name);\n      if (records.has(id)) {\n        return Promise.reject(new RecordExistsError(name, id));\n      }\n      records.set(id, { value: structuredClone(value), version: 1 });\n      return Promise.resolve();\n    },\n\n    update({ collection: name, id, value, expectedVersion }) {\n      const records = collection(name);\n      const existing = records.get(id);\n      if (existing === undefined) {\n        return Promise.reject(new RecordNotFoundError(name, id));\n      }\n      if (existing.version !== expectedVersion) {\n        return Promise.reject(new VersionConflictError(name, id, expectedVersion));\n      }\n      records.set(id, { value: structuredClone(value), version: existing.version + 1 });\n      return Promise.resolve();\n    },\n\n    list(name) {\n      const entries: StoredEntry[] = [...collection(name)].map(([id, record]) => ({\n        id,\n        record: structuredClone(record),\n      }));\n      return Promise.resolve(entries);\n    },\n  };\n}\n"],"mappings":";;;AAWA,SAAgB,uBAAoC;CAClD,MAAM,8BAAc,IAAI,IAA+C;CAEvE,SAAS,WAAW,MAAiD;EACnE,IAAI,WAAW,YAAY,IAAI,IAAI;EACnC,IAAI,aAAa,KAAA,GAAW;GAC1B,2BAAW,IAAI,IAAI;GACnB,YAAY,IAAI,MAAM,QAAQ;EAChC;EACA,OAAO;CACT;CAEA,OAAO;EACL,MAAM;EAEN,IAAI,MAAM,IAAI;GACZ,MAAM,SAAS,WAAW,IAAI,CAAC,CAAC,IAAI,EAAE;GACtC,OAAO,QAAQ,QAAQ,WAAW,KAAA,IAAY,OAAO,gBAAgB,MAAM,CAAC;EAC9E;EAEA,OAAO,EAAE,YAAY,MAAM,IAAI,SAAS;GACtC,MAAM,UAAU,WAAW,IAAI;GAC/B,IAAI,QAAQ,IAAI,EAAE,GAChB,OAAO,QAAQ,OAAO,IAAI,kBAAkB,MAAM,EAAE,CAAC;GAEvD,QAAQ,IAAI,IAAI;IAAE,OAAO,gBAAgB,KAAK;IAAG,SAAS;GAAE,CAAC;GAC7D,OAAO,QAAQ,QAAQ;EACzB;EAEA,OAAO,EAAE,YAAY,MAAM,IAAI,OAAO,mBAAmB;GACvD,MAAM,UAAU,WAAW,IAAI;GAC/B,MAAM,WAAW,QAAQ,IAAI,EAAE;GAC/B,IAAI,aAAa,KAAA,GACf,OAAO,QAAQ,OAAO,IAAI,oBAAoB,MAAM,EAAE,CAAC;GAEzD,IAAI,SAAS,YAAY,iBACvB,OAAO,QAAQ,OAAO,IAAI,qBAAqB,MAAM,IAAI,eAAe,CAAC;GAE3E,QAAQ,IAAI,IAAI;IAAE,OAAO,gBAAgB,KAAK;IAAG,SAAS,SAAS,UAAU;GAAE,CAAC;GAChF,OAAO,QAAQ,QAAQ;EACzB;EAEA,KAAK,MAAM;GACT,MAAM,UAAyB,CAAC,GAAG,WAAW,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,aAAa;IAC1E;IACA,QAAQ,gBAAgB,MAAM;GAChC,EAAE;GACF,OAAO,QAAQ,QAAQ,OAAO;EAChC;CACF;AACF"}
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../src/store/memory.ts"],"sourcesContent":["import {\n  RecordExistsError,\n  RecordNotFoundError,\n  VersionConflictError,\n  type CollectionName,\n  type StoredEntry,\n  type StoredRecord,\n  type StoreDriver,\n} from \"./driver\";\n\n/**\n * Creates an isolated process-local StoreDriver for development, examples, and tests.\n *\n * @remarks\n * Every call creates a new empty store. Records survive only for the lifetime of the returned\n * object and are cloned at the driver boundary, so mutating caller-owned values cannot mutate\n * stored state. Use a persistent adapter from `@vercel/factory/storage/blob` or\n * `@vercel/factory/storage/postgres` in deployed runtimes.\n *\n * @returns A new empty driver whose `name` is `memory`.\n *\n * @example\n * ```ts\n * import { createInMemoryDriver, createStores } from \"@vercel/factory/storage\";\n *\n * const stores = createStores({ driver: createInMemoryDriver() });\n * ```\n */\nexport function createInMemoryDriver(): StoreDriver {\n  const collections = new Map<CollectionName, Map<string, StoredRecord>>();\n\n  function collection(name: CollectionName): Map<string, StoredRecord> {\n    let existing = collections.get(name);\n    if (existing === undefined) {\n      existing = new Map();\n      collections.set(name, existing);\n    }\n    return existing;\n  }\n\n  return {\n    name: \"memory\",\n\n    get(name, id) {\n      const record = collection(name).get(id);\n      return Promise.resolve(record === undefined ? null : structuredClone(record));\n    },\n\n    insert({ collection: name, id, value }) {\n      const records = collection(name);\n      if (records.has(id)) {\n        return Promise.reject(new RecordExistsError(name, id));\n      }\n      records.set(id, { value: structuredClone(value), version: 1 });\n      return Promise.resolve();\n    },\n\n    update({ collection: name, id, value, expectedVersion }) {\n      const records = collection(name);\n      const existing = records.get(id);\n      if (existing === undefined) {\n        return Promise.reject(new RecordNotFoundError(name, id));\n      }\n      if (existing.version !== expectedVersion) {\n        return Promise.reject(new VersionConflictError(name, id, expectedVersion));\n      }\n      records.set(id, { value: structuredClone(value), version: existing.version + 1 });\n      return Promise.resolve();\n    },\n\n    list(name) {\n      const entries: StoredEntry[] = [...collection(name)].map(([id, record]) => ({\n        id,\n        record: structuredClone(record),\n      }));\n      return Promise.resolve(entries);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,uBAAoC;CAClD,MAAM,8BAAc,IAAI,IAA+C;CAEvE,SAAS,WAAW,MAAiD;EACnE,IAAI,WAAW,YAAY,IAAI,IAAI;EACnC,IAAI,aAAa,KAAA,GAAW;GAC1B,2BAAW,IAAI,IAAI;GACnB,YAAY,IAAI,MAAM,QAAQ;EAChC;EACA,OAAO;CACT;CAEA,OAAO;EACL,MAAM;EAEN,IAAI,MAAM,IAAI;GACZ,MAAM,SAAS,WAAW,IAAI,CAAC,CAAC,IAAI,EAAE;GACtC,OAAO,QAAQ,QAAQ,WAAW,KAAA,IAAY,OAAO,gBAAgB,MAAM,CAAC;EAC9E;EAEA,OAAO,EAAE,YAAY,MAAM,IAAI,SAAS;GACtC,MAAM,UAAU,WAAW,IAAI;GAC/B,IAAI,QAAQ,IAAI,EAAE,GAChB,OAAO,QAAQ,OAAO,IAAI,kBAAkB,MAAM,EAAE,CAAC;GAEvD,QAAQ,IAAI,IAAI;IAAE,OAAO,gBAAgB,KAAK;IAAG,SAAS;GAAE,CAAC;GAC7D,OAAO,QAAQ,QAAQ;EACzB;EAEA,OAAO,EAAE,YAAY,MAAM,IAAI,OAAO,mBAAmB;GACvD,MAAM,UAAU,WAAW,IAAI;GAC/B,MAAM,WAAW,QAAQ,IAAI,EAAE;GAC/B,IAAI,aAAa,KAAA,GACf,OAAO,QAAQ,OAAO,IAAI,oBAAoB,MAAM,EAAE,CAAC;GAEzD,IAAI,SAAS,YAAY,iBACvB,OAAO,QAAQ,OAAO,IAAI,qBAAqB,MAAM,IAAI,eAAe,CAAC;GAE3E,QAAQ,IAAI,IAAI;IAAE,OAAO,gBAAgB,KAAK;IAAG,SAAS,SAAS,UAAU;GAAE,CAAC;GAChF,OAAO,QAAQ,QAAQ;EACzB;EAEA,KAAK,MAAM;GACT,MAAM,UAAyB,CAAC,GAAG,WAAW,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,aAAa;IAC1E;IACA,QAAQ,gBAAgB,MAAM;GAChC,EAAE;GACF,OAAO,QAAQ,QAAQ,OAAO;EAChC;CACF;AACF"}

package/dist/store/slack-pr-notifications.d.mts

@@ -0,0 +1,44 @@
+import { RepositorySlug } from "../schema/repository.mjs";
+import { StoreDriver } from "./driver.mjs";
+import { SlackPrNotifications } from "../schema/slack-pr-notifications.mjs";
+import { z } from "zod";
+//#region src/store/slack-pr-notifications.d.ts
+declare const commandSchema: z.ZodObject<{
+  operationId: z.ZodString;
+  actor: z.ZodString;
+  preference: z.ZodUnion<readonly [z.ZodReadonly<z.ZodObject<{
+    channelId: z.ZodString;
+    mentionUserIds: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>>, z.ZodNull, z.ZodLiteral<"config">]>;
+}, z.core.$strict>;
+/** Effective PR notification settings and the source of the current choice. */
+interface SlackPrNotificationSnapshot {
+  readonly revision: number;
+  readonly source: "config" | "slack";
+  readonly settings: SlackPrNotifications | null;
+  readonly updatedBy?: string;
+  readonly updatedAt?: string;
+}
+/** A trusted Slack command: an object enables notifications, null disables them, and config resets. */
+type UpdateSlackPrNotificationsInput = z.infer<typeof commandSchema>;
+/** Durable PR notification preferences scoped to a connector, workspace, and optional repository. */
+interface SlackPrNotificationStore {
+  get(): Promise<SlackPrNotificationSnapshot>;
+  /** The caller authenticates the operator; operationId must identify the original Slack message. */
+  update(input: UpdateSlackPrNotificationsInput): Promise<SlackPrNotificationSnapshot>;
+}
+/** Persistence scope and Git-configured fallback for PR notification preferences. */
+interface SlackPrNotificationStoreOptions {
+  readonly driver: StoreDriver;
+  readonly connector: string;
+  readonly workspaceId: string;
+  /** Omit for the factory-wide default; supply a slug to isolate one repository's preferences. */
+  readonly repository?: RepositorySlug;
+  readonly defaults?: SlackPrNotifications | null;
+  readonly now?: () => string;
+}
+/** Creates directly addressed settings with immutable command intents and compare-and-swap updates. */
+declare function createSlackPrNotificationStore({ driver, connector, workspaceId, repository, defaults, now }: SlackPrNotificationStoreOptions): SlackPrNotificationStore;
+//#endregion
+export { SlackPrNotificationSnapshot, SlackPrNotificationStore, SlackPrNotificationStoreOptions, UpdateSlackPrNotificationsInput, createSlackPrNotificationStore };
+//# sourceMappingURL=slack-pr-notifications.d.mts.map

package/dist/store/slack-pr-notifications.mjs

@@ -0,0 +1,121 @@
+import { repositorySlugSchema } from "../schema/repository.mjs";
+import { slackPrNotificationsSchema } from "../schema/slack-pr-notifications.mjs";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+//#region src/store/slack-pr-notifications.ts
+const preferenceSchema = z.union([
+	slackPrNotificationsSchema,
+	z.null(),
+	z.literal("config")
+]);
+const commandSchema = z.strictObject({
+	operationId: z.string().min(1).max(512).describe("Stable identity of the authenticated Slack message."),
+	actor: z.string().regex(/^slack:T[A-Z0-9]+:[UW][A-Z0-9]+$/u).describe("Authenticated Slack operator making this choice."),
+	preference: preferenceSchema.describe("Destination override, null to disable, or config to restore the file default.")
+});
+const recordSchema = commandSchema.extend({
+	schemaVersion: z.literal(1).describe("Persisted settings format version."),
+	expectedRevision: z.number().int().nonnegative().describe("Settings revision observed when this command was first recorded."),
+	updatedAt: z.iso.datetime().describe("Time the command was first recorded.")
+});
+function isConflict(error, ...names) {
+	return error instanceof Error && names.includes(error.name);
+}
+/** Creates directly addressed settings with immutable command intents and compare-and-swap updates. */
+function createSlackPrNotificationStore({ driver, connector, workspaceId, repository, defaults, now = () => (/* @__PURE__ */ new Date()).toISOString() }) {
+	z.string().regex(/^slack\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u).parse(connector);
+	z.string().regex(/^T[A-Z0-9]+$/u).parse(workspaceId);
+	if (repository !== void 0) repositorySlugSchema.parse(repository);
+	const fallback = defaults == null ? null : slackPrNotificationsSchema.parse(defaults);
+	const hash = (value) => createHash("sha256").update(value).digest("hex");
+	const id = `slack-pr-${hash(JSON.stringify(repository === void 0 ? [connector, workspaceId] : [
+		connector,
+		workspaceId,
+		repository
+	]))}`;
+	const collection = "communicationSettings";
+	async function read() {
+		const record = await driver.get(collection, id);
+		return record === null ? null : {
+			version: record.version,
+			value: recordSchema.parse(record.value)
+		};
+	}
+	function snapshot(record) {
+		const preference = record === null ? "config" : record.value.preference;
+		return {
+			revision: record?.version ?? 0,
+			source: preference === "config" ? "config" : "slack",
+			settings: preference === "config" ? fallback : preference,
+			...record && {
+				updatedBy: record.value.actor,
+				updatedAt: record.value.updatedAt
+			}
+		};
+	}
+	async function update(value) {
+		const input = commandSchema.parse(value);
+		if (!input.actor.startsWith(`slack:${workspaceId}:`)) throw new Error("PR notification operator belongs to another Slack workspace.");
+		const commandId = `${id}-command-${hash(input.operationId)}`;
+		let command = await driver.get(collection, commandId);
+		if (command === null) {
+			const current = await read();
+			const intent = recordSchema.parse({
+				...input,
+				schemaVersion: 1,
+				expectedRevision: current?.version ?? 0,
+				updatedAt: now()
+			});
+			try {
+				await driver.insert({
+					collection,
+					id: commandId,
+					value: intent
+				});
+			} catch (error) {
+				if (!isConflict(error, "RecordExistsError")) throw error;
+			}
+			command = await driver.get(collection, commandId);
+		}
+		if (command === null) throw new Error("PR notification command was not saved.");
+		const intent = recordSchema.parse(command.value);
+		if (JSON.stringify({
+			operationId: intent.operationId,
+			actor: intent.actor,
+			preference: intent.preference
+		}) !== JSON.stringify(input)) throw new Error("This Slack message already requested different PR notification settings.");
+		const current = await read();
+		if (current?.value.operationId === input.operationId) return snapshot(current);
+		if ((current?.version ?? 0) !== intent.expectedRevision) throw new Error("PR notification settings changed after this command. Send a new Slack message to change them again.");
+		try {
+			if (current === null) await driver.insert({
+				collection,
+				id,
+				value: intent
+			});
+			else await driver.update({
+				collection,
+				id,
+				value: intent,
+				expectedVersion: current.version
+			});
+		} catch (error) {
+			if (!isConflict(error, "RecordExistsError", "VersionConflictError")) throw error;
+			const winner = await read();
+			if (winner?.value.operationId === input.operationId) return snapshot(winner);
+			throw new Error("Another command changed PR notification settings. Send a new Slack message to change them again.", { cause: error });
+		}
+		return snapshot({
+			value: intent,
+			version: intent.expectedRevision + 1
+		});
+	}
+	return {
+		get: async () => snapshot(await read()),
+		update
+	};
+}
+//#endregion
+export { createSlackPrNotificationStore };
+
+//# sourceMappingURL=slack-pr-notifications.mjs.map

package/dist/store/slack-pr-notifications.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"slack-pr-notifications.mjs","names":[],"sources":["../../src/store/slack-pr-notifications.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { z } from \"zod\";\nimport {\n  slackPrNotificationsSchema,\n  type SlackPrNotifications,\n} from \"../schema/slack-pr-notifications\";\nimport type { StoreDriver } from \"./driver\";\nimport { repositorySlugSchema, type RepositorySlug } from \"../schema/repository\";\n\nconst preferenceSchema = z.union([slackPrNotificationsSchema, z.null(), z.literal(\"config\")]);\nconst commandSchema = z.strictObject({\n  operationId: z\n    .string()\n    .min(1)\n    .max(512)\n    .describe(\"Stable identity of the authenticated Slack message.\"),\n  actor: z\n    .string()\n    .regex(/^slack:T[A-Z0-9]+:[UW][A-Z0-9]+$/u)\n    .describe(\"Authenticated Slack operator making this choice.\"),\n  preference: preferenceSchema.describe(\n    \"Destination override, null to disable, or config to restore the file default.\",\n  ),\n});\nconst recordSchema = commandSchema.extend({\n  schemaVersion: z.literal(1).describe(\"Persisted settings format version.\"),\n  expectedRevision: z\n    .number()\n    .int()\n    .nonnegative()\n    .describe(\"Settings revision observed when this command was first recorded.\"),\n  updatedAt: z.iso.datetime().describe(\"Time the command was first recorded.\"),\n});\n\n// Drivers loaded through separate package entry points have distinct error constructors.\nfunction isConflict(error: unknown, ...names: string[]): boolean {\n  return error instanceof Error && names.includes(error.name);\n}\n\n/** Effective PR notification settings and the source of the current choice. */\nexport interface SlackPrNotificationSnapshot {\n  readonly revision: number;\n  readonly source: \"config\" | \"slack\";\n  readonly settings: SlackPrNotifications | null;\n  readonly updatedBy?: string;\n  readonly updatedAt?: string;\n}\n\n/** A trusted Slack command: an object enables notifications, null disables them, and config resets. */\nexport type UpdateSlackPrNotificationsInput = z.infer<typeof commandSchema>;\n\n/** Durable PR notification preferences scoped to a connector, workspace, and optional repository. */\nexport interface SlackPrNotificationStore {\n  get(): Promise<SlackPrNotificationSnapshot>;\n  /** The caller authenticates the operator; operationId must identify the original Slack message. */\n  update(input: UpdateSlackPrNotificationsInput): Promise<SlackPrNotificationSnapshot>;\n}\n\n/** Persistence scope and Git-configured fallback for PR notification preferences. */\nexport interface SlackPrNotificationStoreOptions {\n  readonly driver: StoreDriver;\n  readonly connector: string;\n  readonly workspaceId: string;\n  /** Omit for the factory-wide default; supply a slug to isolate one repository's preferences. */\n  readonly repository?: RepositorySlug;\n  readonly defaults?: SlackPrNotifications | null;\n  readonly now?: () => string;\n}\n\n/** Creates directly addressed settings with immutable command intents and compare-and-swap updates. */\nexport function createSlackPrNotificationStore({\n  driver,\n  connector,\n  workspaceId,\n  repository,\n  defaults,\n  now = () => new Date().toISOString(),\n}: SlackPrNotificationStoreOptions): SlackPrNotificationStore {\n  z.string()\n    .regex(/^slack\\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u)\n    .parse(connector);\n  z.string()\n    .regex(/^T[A-Z0-9]+$/u)\n    .parse(workspaceId);\n  if (repository !== undefined) repositorySlugSchema.parse(repository);\n  const fallback = defaults == null ? null : slackPrNotificationsSchema.parse(defaults);\n  const hash = (value: string) => createHash(\"sha256\").update(value).digest(\"hex\");\n  const scope =\n    repository === undefined ? [connector, workspaceId] : [connector, workspaceId, repository];\n  const id = `slack-pr-${hash(JSON.stringify(scope))}`;\n  const collection = \"communicationSettings\";\n\n  async function read() {\n    const record = await driver.get(collection, id);\n    return record === null\n      ? null\n      : { version: record.version, value: recordSchema.parse(record.value) };\n  }\n\n  function snapshot(record: Awaited<ReturnType<typeof read>>): SlackPrNotificationSnapshot {\n    const preference = record === null ? \"config\" : record.value.preference;\n    return {\n      revision: record?.version ?? 0,\n      source: preference === \"config\" ? \"config\" : \"slack\",\n      settings: preference === \"config\" ? fallback : preference,\n      ...(record && { updatedBy: record.value.actor, updatedAt: record.value.updatedAt }),\n    };\n  }\n\n  async function update(value: UpdateSlackPrNotificationsInput) {\n    const input = commandSchema.parse(value);\n    if (!input.actor.startsWith(`slack:${workspaceId}:`))\n      throw new Error(\"PR notification operator belongs to another Slack workspace.\");\n    const commandId = `${id}-command-${hash(input.operationId)}`;\n    let command = await driver.get(collection, commandId);\n    if (command === null) {\n      const current = await read();\n      const intent = recordSchema.parse({\n        ...input,\n        schemaVersion: 1,\n        expectedRevision: current?.version ?? 0,\n        updatedAt: now(),\n      });\n      try {\n        await driver.insert({ collection, id: commandId, value: intent });\n      } catch (error) {\n        if (!isConflict(error, \"RecordExistsError\")) throw error;\n      }\n      command = await driver.get(collection, commandId);\n    }\n    if (command === null) throw new Error(\"PR notification command was not saved.\");\n    const intent = recordSchema.parse(command.value);\n    if (\n      JSON.stringify({\n        operationId: intent.operationId,\n        actor: intent.actor,\n        preference: intent.preference,\n      }) !== JSON.stringify(input)\n    )\n      throw new Error(\"This Slack message already requested different PR notification settings.\");\n\n    const current = await read();\n    if (current?.value.operationId === input.operationId) return snapshot(current);\n    if ((current?.version ?? 0) !== intent.expectedRevision)\n      throw new Error(\n        \"PR notification settings changed after this command. Send a new Slack message to change them again.\",\n      );\n    try {\n      if (current === null) await driver.insert({ collection, id, value: intent });\n      else await driver.update({ collection, id, value: intent, expectedVersion: current.version });\n    } catch (error) {\n      if (!isConflict(error, \"RecordExistsError\", \"VersionConflictError\")) throw error;\n      const winner = await read();\n      if (winner?.value.operationId === input.operationId) return snapshot(winner);\n      throw new Error(\n        \"Another command changed PR notification settings. Send a new Slack message to change them again.\",\n        { cause: error },\n      );\n    }\n    return snapshot({ value: intent, version: intent.expectedRevision + 1 });\n  }\n\n  return { get: async () => snapshot(await read()), update };\n}\n"],"mappings":"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"}

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

@@ -1,6 +1,6 @@
 import { TaskId } from "../schema/id.mjs";
 import { JsonValue, WorkflowBinding } from "../schema/work.mjs";
-import { Task } from "../schema/task.mjs";
+import { ExecutionReference, Task, TaskState } from "../schema/task.mjs";
 import { WorkflowRegistry } from "../workflows.mjs";
 import { IsoDateTimeClock } from "../schema/common.mjs";
 import { TaskAttemptRef } from "../schema/execution.mjs";
@@ -9,57 +9,172 @@ import { FactoryStores } from "./engine.mjs";
 //#region src/store/task-work.d.ts
 /** Workflow-facing Task operations for completion, message waiting, recovery, and usage aggregation. */
 interface TaskWorkStore {
-  /** Complete through the dynamic registry boundary, which validates unknown output at runtime. */
+  /**
+   * Completes through the dynamic registry boundary, which validates unknown output at runtime.
+   *
+   * @remarks
+   * The exact Task attempt is mandatory. The engine validates output against the Task's stored
+   * workflow, persists it with the `succeeded` transition, and returns only after that write. A
+   * replay with the same validated output returns the existing succeeded Task; different output
+   * is refused. This method does not authenticate a provider callback—use a fence and establish
+   * caller authority before invoking it.
+   *
+   * @param input - Exact Task attempt, unknown candidate output, and optional execution fence.
+   * @returns The durably succeeded Task containing its validated `workResult`.
+   * @throws When the attempt, lifecycle state, execution fence, or runtime output validation fails.
+   */
   complete(input: CompleteTaskWorkInput): Promise<Task>;
-  /** Complete work while statically checking output against its exact workflow binding. */
+  /**
+   * Completes work while statically checking output against its exact workflow binding.
+   *
+   * @remarks
+   * In addition to `complete` semantics, the supplied binding must equal the Task's persisted
+   * workflow ID and version. Retain historical workflow definitions in the registry while stored
+   * Tasks may still use them. For Eve tools, authenticate first with `requireTaskExecution` and
+   * pass its attempt and execution as the completion fence.
+   *
+   * @param input - Exact Task attempt, typed workflow binding and output, and optional fence.
+   * @returns The durably succeeded Task containing its validated `workResult`.
+   * @throws When the workflow, attempt, lifecycle state, execution fence, or output is invalid.
+   */
   completeWorkflow<Output extends JsonValue>(input: CompleteWorkflowTaskWorkInput<Output>): Promise<Task>;
+  /**
+   * Marks a running exact Task attempt as intentionally inactive while awaiting messages.
+   *
+   * @remarks
+   * This keeps the Task in `running`; it does not stall, cancel, or create a new attempt. The
+   * waiting marker and optional workflow phase are durable when the promise resolves. Repeating
+   * the same target state is a no-op. A stale attempt or non-running Task is refused, so callers
+   * should reread the Task before deciding whether a later attempt still needs the message.
+   *
+   * @param input - Exact running attempt and optional workflow phase.
+   * @returns The updated running Task with `waitingForMessages` set.
+   * @throws When the Task is absent, no longer running, or on a different attempt.
+   */
   waitForMessages(input: WaitForTaskMessagesInput): Promise<Task>;
+  /**
+   * Resumes an exact message-waiting Task attempt and records fresh progress.
+   *
+   * @remarks
+   * The Task remains `running`, its waiting marker is cleared, and `lastProgressAt` advances. The
+   * write is durable when the promise resolves and repeating it for an already-resumed attempt is
+   * a no-op. Resuming does not claim or acknowledge messages; the workflow owns that ordering.
+   *
+   * @param input - Exact running attempt to resume.
+   * @returns The updated running Task with message waiting cleared.
+   * @throws When the Task is absent, no longer running, or on a different attempt.
+   */
   resume(input: ResumeTaskWorkInput): Promise<Task>;
-  /** Repair admitted creation snapshots by direct graph IDs, never by scanning the bucket. */
+  /**
+   * Repairs admitted creation snapshots by direct graph IDs, never by scanning the bucket.
+   *
+   * @remarks
+   * The canonical graph contains immutable admission snapshots. Recovery validates every
+   * admission against the exact registered workflow, restores only missing Task records, and
+   * returns existing records with their current mutable progress. It is safe to repeat after an
+   * interrupted Task creation.
+   *
+   * This operation repairs Factory persistence only. It does not start or reattach a provider
+   * execution, rerun workflow code, retry a Task, or migrate old Task JSON. After recovery, the
+   * caller must inspect each Task's lifecycle and recorded execution and apply workflow-owned
+   * reconciliation policy.
+   *
+   * @param rootTaskId - Root of the canonical Task graph to repair and read.
+   * @returns Every validated Task admitted to that graph.
+   * @throws When the graph is absent, a stored workflow version is not registered, persisted data
+   * is invalid, or a current Task no longer matches its immutable admission identity.
+   */
   recover(rootTaskId: TaskId): Promise<readonly Task[]>;
-  /** Each Task contributes local measured usage once; no parent roll-up is charged again. */
+  /**
+   * Aggregates Task-local measured usage once without charging parent roll-ups again.
+   *
+   * @remarks
+   * This first performs the same persistence repair and validation as {@link recover}. For each
+   * Task, recorded step usage is authoritative; otherwise a settled amount is used, then zero.
+   * The result is a current snapshot, not a reservation or billing transaction, and calling it
+   * does not write settlement receipts.
+   *
+   * @param rootTaskId - Root of the canonical Task graph to aggregate.
+   * @returns Cost, token, and Task counts for the recovered graph.
+   * @throws The same persistence and validation errors as {@link recover}.
+   */
   usage(rootTaskId: TaskId): Promise<TaskWorkUsage>;
 }
 /** Exact Task attempt and candidate workflow output used to complete work. */
 interface CompleteTaskWorkInput {
+  /** Task ID and current positive attempt; stale attempts are refused. */
   task: TaskAttemptRef;
+  /** Candidate value validated against the Task's exact registered output schema. */
   output: unknown;
+  /**
+   * Optional source-state and execution fence for provider callbacks. Omit only when trusted
+   * workflow code already owns lifecycle authority.
+   */
+  fence?: TaskWorkCompletionFence;
 }
 /** Exact Task attempt, workflow contract, and statically checked output used to complete work. */
 interface CompleteWorkflowTaskWorkInput<Output extends JsonValue = JsonValue> {
+  /** Task ID and current positive attempt; stale attempts are refused. */
   task: TaskAttemptRef;
+  /** Exact binding required to match the Task's persisted workflow. */
   workflow: WorkflowBinding<JsonValue, Output>;
+  /** Candidate output statically carried by the binding and validated again at runtime. */
   output: NoInfer<Output>;
+  /**
+   * Optional source-state and execution fence for provider callbacks. Omit only when trusted
+   * workflow code already owns lifecycle authority.
+   */
+  fence?: TaskWorkCompletionFence;
+}
+/** Atomic source-state and provider-execution conditions for a workflow completion write. */
+interface TaskWorkCompletionFence {
+  /** Lifecycle state required atomically with completion, normally `running`. */
+  readonly from: TaskState;
+  /** Provider execution reference required to remain current at the completion write. */
+  readonly execution: ExecutionReference;
 }
 /** Aggregated measured usage across one canonical Task graph. */
 interface TaskWorkUsage {
+  /** Sum of measured Task usage, falling back to settlement only when no usage is recorded. */
   costUsd: number;
+  /** Sum of recorded provider input tokens across Tasks. */
   inputTokens: number;
+  /** Sum of recorded provider output tokens across Tasks. */
   outputTokens: number;
+  /** Number of Tasks admitted to the recovered canonical graph. */
   taskCount: number;
 }
 /** Exact running Task attempt and optional workflow phase used to await messages. */
 interface WaitForTaskMessagesInput {
+  /** Task ID and current positive attempt; stale attempts are refused. */
   task: TaskAttemptRef;
+  /** Optional durable workflow-owned phase label retained across waiting and resumption. */
   phase?: string;
 }
 /** Exact running Task attempt to resume after message delivery. */
 interface ResumeTaskWorkInput {
+  /** Task ID and current positive attempt; stale attempts are refused. */
   task: TaskAttemptRef;
 }
 /** Canonical Task graph, receipt, and Task capabilities used by workflow-facing operations. */
 type TaskWorkStores = Pick<FactoryStores, "graphs" | "receipts" | "tasks">;
 /** Engine-owned dependencies used to construct workflow-facing Task operations. */
 interface CreateTaskWorkStoreOptions {
+  /** Policy-free persistence driver used for direct canonical Task reads. */
   driver: StoreDriver;
+  /** ISO timestamp source shared with the surrounding store engine. */
   now: IsoDateTimeClock;
+  /** Lazily resolves graph, receipt, and Task operations after engine construction. */
   stores: () => TaskWorkStores;
+  /** Exact workflow versions used to validate stored input and completion output. */
   workflows: WorkflowRegistry;
+  /** Persists a validated Task with compare-and-swap semantics. */
   update(task: Task, version: number): Promise<void>;
+  /** Recreates a missing canonical Task snapshot from its immutable graph admission. */
   restore(task: Task): Promise<Task>;
 }
 /** Creates workflow-facing Task operations backed by canonical graph and Task stores. */
 declare function createTaskWorkStore(options: CreateTaskWorkStoreOptions): TaskWorkStore;
 //#endregion
-export { CompleteTaskWorkInput, CompleteWorkflowTaskWorkInput, CreateTaskWorkStoreOptions, ResumeTaskWorkInput, TaskWorkStore, TaskWorkStores, TaskWorkUsage, WaitForTaskMessagesInput, createTaskWorkStore };
+export { CompleteTaskWorkInput, CompleteWorkflowTaskWorkInput, CreateTaskWorkStoreOptions, ResumeTaskWorkInput, TaskWorkCompletionFence, TaskWorkStore, TaskWorkStores, TaskWorkUsage, WaitForTaskMessagesInput, createTaskWorkStore };
 //# sourceMappingURL=task-work.d.mts.map

package/dist/store/task-work.mjs

@@ -76,10 +76,11 @@ function createTaskWorkStore(options) {
 		}
 	}
 	async function complete(input, expectedWorkflow) {
-		const { task: { taskId: id, attempt: expectAttempt }, output: value } = input;
+		const { task: { taskId: id, attempt: expectAttempt }, output: value, fence } = input;
 		for (;;) {
 			const { task, work } = await read(id);
 			assertAttempt(task, expectAttempt);
+			if (fence !== void 0 && !isDeepStrictEqual(task.execution, fence.execution)) throw new Error(`Task ${id} execution has been replaced`);
 			if (expectedWorkflow !== void 0 && !isDeepStrictEqual(work.workflow, expectedWorkflow)) throw new Error(`Task ${id} uses workflow ${work.workflow.id}@${work.workflow.version}, not ${expectedWorkflow.id}@${expectedWorkflow.version}`);
 			if (task.state === "succeeded") {
 				const output = workflows.validateOutput(work.workflow, value);
@@ -90,7 +91,8 @@ function createTaskWorkStore(options) {
 				return await stores().tasks.transition(id, "succeeded", {
 					output: value,
 					expectAttempt,
-					expectFrom: task.state,
+					expectFrom: fence?.from ?? task.state,
+					...fence === void 0 ? {} : { expectExecution: fence.execution },
 					phase: "workflow"
 				});
 			} catch (error) {
@@ -102,9 +104,10 @@ function createTaskWorkStore(options) {
 	}
 	return {
 		complete,
-		completeWorkflow: ({ task, workflow, output }) => complete({
+		completeWorkflow: ({ task, workflow, output, fence }) => complete({
 			task,
-			output
+			output,
+			fence
 		}, workflow),
 		waitForMessages: ({ task: { taskId, attempt }, phase }) => setWaiting(taskId, attempt, true, phase),
 		resume: ({ task: { taskId, attempt } }) => setWaiting(taskId, attempt, false),

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

@@ -1 +1 @@
-{"version":3,"file":"task-work.mjs","names":[],"sources":["../../src/store/task-work.ts"],"sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { z } from \"zod\";\nimport type { IsoDateTimeClock } from \"../schema/common\";\nimport type { TaskAttemptRef } from \"../schema/execution\";\nimport type { TaskId } from \"../schema/id\";\nimport { taskSchema, type Task } from \"../schema/task\";\nimport { InvalidTransitionError } from \"../schema/transitions\";\nimport type { JsonValue, WorkflowBinding } from \"../schema/work\";\nimport type { WorkflowRegistry } from \"../workflows\";\nimport { RecordNotFoundError, VersionConflictError, type StoreDriver } from \"./driver\";\nimport type { FactoryStores } from \"./engine\";\nimport { assertTaskAdmission } from \"./task-graphs\";\n\n/** Workflow-facing Task operations for completion, message waiting, recovery, and usage aggregation. */\nexport interface TaskWorkStore {\n  /** Complete through the dynamic registry boundary, which validates unknown output at runtime. */\n  complete(input: CompleteTaskWorkInput): Promise<Task>;\n  /** Complete work while statically checking output against its exact workflow binding. */\n  completeWorkflow<Output extends JsonValue>(\n    input: CompleteWorkflowTaskWorkInput<Output>,\n  ): Promise<Task>;\n  waitForMessages(input: WaitForTaskMessagesInput): Promise<Task>;\n  resume(input: ResumeTaskWorkInput): Promise<Task>;\n  /** Repair admitted creation snapshots by direct graph IDs, never by scanning the bucket. */\n  recover(rootTaskId: TaskId): Promise<readonly Task[]>;\n  /** Each Task contributes local measured usage once; no parent roll-up is charged again. */\n  usage(rootTaskId: TaskId): Promise<TaskWorkUsage>;\n}\n\n/** Exact Task attempt and candidate workflow output used to complete work. */\nexport interface CompleteTaskWorkInput {\n  task: TaskAttemptRef;\n  output: unknown;\n}\n\n/** Exact Task attempt, workflow contract, and statically checked output used to complete work. */\nexport interface CompleteWorkflowTaskWorkInput<Output extends JsonValue = JsonValue> {\n  task: TaskAttemptRef;\n  workflow: WorkflowBinding<JsonValue, Output>;\n  output: NoInfer<Output>;\n}\n\n/** Aggregated measured usage across one canonical Task graph. */\nexport interface TaskWorkUsage {\n  costUsd: number;\n  inputTokens: number;\n  outputTokens: number;\n  taskCount: number;\n}\n\n/** Exact running Task attempt and optional workflow phase used to await messages. */\nexport interface WaitForTaskMessagesInput {\n  task: TaskAttemptRef;\n  phase?: string;\n}\n\n/** Exact running Task attempt to resume after message delivery. */\nexport interface ResumeTaskWorkInput {\n  task: TaskAttemptRef;\n}\n\n/** Canonical Task graph, receipt, and Task capabilities used by workflow-facing operations. */\nexport type TaskWorkStores = Pick<FactoryStores, \"graphs\" | \"receipts\" | \"tasks\">;\n\n/** Engine-owned dependencies used to construct workflow-facing Task operations. */\nexport interface CreateTaskWorkStoreOptions {\n  driver: StoreDriver;\n  now: IsoDateTimeClock;\n  stores: () => TaskWorkStores;\n  workflows: WorkflowRegistry;\n  update(task: Task, version: number): Promise<void>;\n  restore(task: Task): Promise<Task>;\n}\n\n/** Creates workflow-facing Task operations backed by canonical graph and Task stores. */\nexport function createTaskWorkStore(options: CreateTaskWorkStoreOptions): TaskWorkStore {\n  const { driver, now, stores, workflows, update, restore } = options;\n  function parseTask(value: unknown): Task {\n    const task = taskSchema.parse(value);\n    workflows.validateStoredInput(task.work.workflow, task.work.input);\n    if (task.workResult) workflows.validateStoredOutput(task.work.workflow, task.workResult.output);\n    return task;\n  }\n  async function read(id: TaskId) {\n    const record = await driver.get(\"tasks\", id);\n    if (!record) throw new RecordNotFoundError(\"tasks\", id);\n    const task = parseTask(record.value);\n    if (task.id !== id) throw new Error(`Task ${id} does not match its storage key`);\n    return { task, version: record.version, work: task.work };\n  }\n  async function recover(rootTaskId: TaskId): Promise<readonly Task[]> {\n    const graph = await stores().graphs.get(rootTaskId);\n    if (!graph) throw new RecordNotFoundError(\"taskGraphs\", rootTaskId);\n    const tasks: Task[] = [];\n    for (const node of graph.nodes) {\n      const admission = parseTask(node.admission);\n      const existing = await stores().tasks.get(node.taskId);\n      const task = parseTask(existing ?? (await restore(admission)));\n      assertTaskAdmission({ task, admission });\n      tasks.push(task);\n    }\n    return tasks;\n  }\n  function assertAttempt(task: Task, expectAttempt: number) {\n    z.number().int().positive().parse(expectAttempt);\n    if (task.attempt !== expectAttempt)\n      throw new Error(`Task ${task.id} is on attempt ${task.attempt}, not ${expectAttempt}`);\n  }\n  async function setWaiting(\n    id: TaskId,\n    expectAttempt: number,\n    waiting: boolean,\n    phase?: string,\n  ): Promise<Task> {\n    for (;;) {\n      const { task, version } = await read(id);\n      assertAttempt(task, expectAttempt);\n      if (task.state !== \"running\")\n        throw new Error(`Task ${id} must be running to ${waiting ? \"wait\" : \"resume\"}`);\n      const next = taskSchema.parse({\n        ...task,\n        waitingForMessages: waiting,\n        workflowPhase: phase ?? task.workflowPhase,\n        lastProgressAt: waiting ? task.lastProgressAt : now(),\n        updatedAt: now(),\n      });\n      if (task.waitingForMessages === waiting && next.workflowPhase === task.workflowPhase)\n        return task;\n      await stores().receipts.append({\n        taskId: id,\n        repositoryIds: task.repositoryIds,\n        kind: task.kind,\n        state: waiting ? \"waiting\" : \"resumed\",\n        phase: \"workflow\",\n        attempt: task.attempt,\n        reason: waiting\n          ? \"Workflow is waiting for Task messages\"\n          : \"Workflow resumed message processing\",\n        dedupeKey: `work:${id}:${version}:${waiting ? \"wait\" : \"resume\"}`,\n      });\n      try {\n        await update(next, version);\n        return next;\n      } catch (error) {\n        if (!(error instanceof VersionConflictError)) throw error;\n      }\n    }\n  }\n  async function complete(\n    input: CompleteTaskWorkInput,\n    expectedWorkflow?: WorkflowBinding,\n  ): Promise<Task> {\n    const {\n      task: { taskId: id, attempt: expectAttempt },\n      output: value,\n    } = input;\n    for (;;) {\n      const { task, work } = await read(id);\n      assertAttempt(task, expectAttempt);\n      if (expectedWorkflow !== undefined && !isDeepStrictEqual(work.workflow, expectedWorkflow)) {\n        throw new Error(\n          `Task ${id} uses workflow ${work.workflow.id}@${work.workflow.version}, not ${expectedWorkflow.id}@${expectedWorkflow.version}`,\n        );\n      }\n      if (task.state === \"succeeded\") {\n        const output = workflows.validateOutput(work.workflow, value);\n        if (!isDeepStrictEqual(task.workResult?.output, output)) {\n          throw new Error(`Task ${id} already recorded a different workflow output`);\n        }\n        return task;\n      }\n      try {\n        return await stores().tasks.transition(id, \"succeeded\", {\n          output: value,\n          expectAttempt,\n          expectFrom: task.state,\n          phase: \"workflow\",\n        });\n      } catch (error) {\n        if (error instanceof VersionConflictError) continue;\n        if (error instanceof InvalidTransitionError && (await read(id)).task.state === \"succeeded\")\n          continue;\n        throw error;\n      }\n    }\n  }\n  return {\n    complete,\n    completeWorkflow: ({ task, workflow, output }) => complete({ task, output }, workflow),\n    waitForMessages: ({ task: { taskId, attempt }, phase }) =>\n      setWaiting(taskId, attempt, true, phase),\n    resume: ({ task: { taskId, attempt } }) => setWaiting(taskId, attempt, false),\n    recover,\n    async usage(rootTaskId) {\n      const tasks = await recover(rootTaskId);\n      let micros = 0;\n      let inputTokens = 0;\n      let outputTokens = 0;\n      for (const task of tasks) {\n        micros += Math.round((task.usage?.costUsd ?? task.settledUsd ?? 0) * 1_000_000);\n        inputTokens += task.usage?.inputTokens ?? 0;\n        outputTokens += task.usage?.outputTokens ?? 0;\n      }\n      return { costUsd: micros / 1_000_000, inputTokens, outputTokens, taskCount: tasks.length };\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"task-work.mjs","names":[],"sources":["../../src/store/task-work.ts"],"sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { z } from \"zod\";\nimport type { IsoDateTimeClock } from \"../schema/common\";\nimport type { TaskAttemptRef } from \"../schema/execution\";\nimport type { TaskId } from \"../schema/id\";\nimport { taskSchema, type ExecutionReference, type Task, type TaskState } from \"../schema/task\";\nimport { InvalidTransitionError } from \"../schema/transitions\";\nimport type { JsonValue, WorkflowBinding } from \"../schema/work\";\nimport type { WorkflowRegistry } from \"../workflows\";\nimport { RecordNotFoundError, VersionConflictError, type StoreDriver } from \"./driver\";\nimport type { FactoryStores } from \"./engine\";\nimport { assertTaskAdmission } from \"./task-graphs\";\n\n/** Workflow-facing Task operations for completion, message waiting, recovery, and usage aggregation. */\nexport interface TaskWorkStore {\n  /**\n   * Completes through the dynamic registry boundary, which validates unknown output at runtime.\n   *\n   * @remarks\n   * The exact Task attempt is mandatory. The engine validates output against the Task's stored\n   * workflow, persists it with the `succeeded` transition, and returns only after that write. A\n   * replay with the same validated output returns the existing succeeded Task; different output\n   * is refused. This method does not authenticate a provider callback—use a fence and establish\n   * caller authority before invoking it.\n   *\n   * @param input - Exact Task attempt, unknown candidate output, and optional execution fence.\n   * @returns The durably succeeded Task containing its validated `workResult`.\n   * @throws When the attempt, lifecycle state, execution fence, or runtime output validation fails.\n   */\n  complete(input: CompleteTaskWorkInput): Promise<Task>;\n  /**\n   * Completes work while statically checking output against its exact workflow binding.\n   *\n   * @remarks\n   * In addition to `complete` semantics, the supplied binding must equal the Task's persisted\n   * workflow ID and version. Retain historical workflow definitions in the registry while stored\n   * Tasks may still use them. For Eve tools, authenticate first with `requireTaskExecution` and\n   * pass its attempt and execution as the completion fence.\n   *\n   * @param input - Exact Task attempt, typed workflow binding and output, and optional fence.\n   * @returns The durably succeeded Task containing its validated `workResult`.\n   * @throws When the workflow, attempt, lifecycle state, execution fence, or output is invalid.\n   */\n  completeWorkflow<Output extends JsonValue>(\n    input: CompleteWorkflowTaskWorkInput<Output>,\n  ): Promise<Task>;\n  /**\n   * Marks a running exact Task attempt as intentionally inactive while awaiting messages.\n   *\n   * @remarks\n   * This keeps the Task in `running`; it does not stall, cancel, or create a new attempt. The\n   * waiting marker and optional workflow phase are durable when the promise resolves. Repeating\n   * the same target state is a no-op. A stale attempt or non-running Task is refused, so callers\n   * should reread the Task before deciding whether a later attempt still needs the message.\n   *\n   * @param input - Exact running attempt and optional workflow phase.\n   * @returns The updated running Task with `waitingForMessages` set.\n   * @throws When the Task is absent, no longer running, or on a different attempt.\n   */\n  waitForMessages(input: WaitForTaskMessagesInput): Promise<Task>;\n  /**\n   * Resumes an exact message-waiting Task attempt and records fresh progress.\n   *\n   * @remarks\n   * The Task remains `running`, its waiting marker is cleared, and `lastProgressAt` advances. The\n   * write is durable when the promise resolves and repeating it for an already-resumed attempt is\n   * a no-op. Resuming does not claim or acknowledge messages; the workflow owns that ordering.\n   *\n   * @param input - Exact running attempt to resume.\n   * @returns The updated running Task with message waiting cleared.\n   * @throws When the Task is absent, no longer running, or on a different attempt.\n   */\n  resume(input: ResumeTaskWorkInput): Promise<Task>;\n  /**\n   * Repairs admitted creation snapshots by direct graph IDs, never by scanning the bucket.\n   *\n   * @remarks\n   * The canonical graph contains immutable admission snapshots. Recovery validates every\n   * admission against the exact registered workflow, restores only missing Task records, and\n   * returns existing records with their current mutable progress. It is safe to repeat after an\n   * interrupted Task creation.\n   *\n   * This operation repairs Factory persistence only. It does not start or reattach a provider\n   * execution, rerun workflow code, retry a Task, or migrate old Task JSON. After recovery, the\n   * caller must inspect each Task's lifecycle and recorded execution and apply workflow-owned\n   * reconciliation policy.\n   *\n   * @param rootTaskId - Root of the canonical Task graph to repair and read.\n   * @returns Every validated Task admitted to that graph.\n   * @throws When the graph is absent, a stored workflow version is not registered, persisted data\n   * is invalid, or a current Task no longer matches its immutable admission identity.\n   */\n  recover(rootTaskId: TaskId): Promise<readonly Task[]>;\n  /**\n   * Aggregates Task-local measured usage once without charging parent roll-ups again.\n   *\n   * @remarks\n   * This first performs the same persistence repair and validation as {@link recover}. For each\n   * Task, recorded step usage is authoritative; otherwise a settled amount is used, then zero.\n   * The result is a current snapshot, not a reservation or billing transaction, and calling it\n   * does not write settlement receipts.\n   *\n   * @param rootTaskId - Root of the canonical Task graph to aggregate.\n   * @returns Cost, token, and Task counts for the recovered graph.\n   * @throws The same persistence and validation errors as {@link recover}.\n   */\n  usage(rootTaskId: TaskId): Promise<TaskWorkUsage>;\n}\n\n/** Exact Task attempt and candidate workflow output used to complete work. */\nexport interface CompleteTaskWorkInput {\n  /** Task ID and current positive attempt; stale attempts are refused. */\n  task: TaskAttemptRef;\n  /** Candidate value validated against the Task's exact registered output schema. */\n  output: unknown;\n  /**\n   * Optional source-state and execution fence for provider callbacks. Omit only when trusted\n   * workflow code already owns lifecycle authority.\n   */\n  fence?: TaskWorkCompletionFence;\n}\n\n/** Exact Task attempt, workflow contract, and statically checked output used to complete work. */\nexport interface CompleteWorkflowTaskWorkInput<Output extends JsonValue = JsonValue> {\n  /** Task ID and current positive attempt; stale attempts are refused. */\n  task: TaskAttemptRef;\n  /** Exact binding required to match the Task's persisted workflow. */\n  workflow: WorkflowBinding<JsonValue, Output>;\n  /** Candidate output statically carried by the binding and validated again at runtime. */\n  output: NoInfer<Output>;\n  /**\n   * Optional source-state and execution fence for provider callbacks. Omit only when trusted\n   * workflow code already owns lifecycle authority.\n   */\n  fence?: TaskWorkCompletionFence;\n}\n\n/** Atomic source-state and provider-execution conditions for a workflow completion write. */\nexport interface TaskWorkCompletionFence {\n  /** Lifecycle state required atomically with completion, normally `running`. */\n  readonly from: TaskState;\n  /** Provider execution reference required to remain current at the completion write. */\n  readonly execution: ExecutionReference;\n}\n\n/** Aggregated measured usage across one canonical Task graph. */\nexport interface TaskWorkUsage {\n  /** Sum of measured Task usage, falling back to settlement only when no usage is recorded. */\n  costUsd: number;\n  /** Sum of recorded provider input tokens across Tasks. */\n  inputTokens: number;\n  /** Sum of recorded provider output tokens across Tasks. */\n  outputTokens: number;\n  /** Number of Tasks admitted to the recovered canonical graph. */\n  taskCount: number;\n}\n\n/** Exact running Task attempt and optional workflow phase used to await messages. */\nexport interface WaitForTaskMessagesInput {\n  /** Task ID and current positive attempt; stale attempts are refused. */\n  task: TaskAttemptRef;\n  /** Optional durable workflow-owned phase label retained across waiting and resumption. */\n  phase?: string;\n}\n\n/** Exact running Task attempt to resume after message delivery. */\nexport interface ResumeTaskWorkInput {\n  /** Task ID and current positive attempt; stale attempts are refused. */\n  task: TaskAttemptRef;\n}\n\n/** Canonical Task graph, receipt, and Task capabilities used by workflow-facing operations. */\nexport type TaskWorkStores = Pick<FactoryStores, \"graphs\" | \"receipts\" | \"tasks\">;\n\n/** Engine-owned dependencies used to construct workflow-facing Task operations. */\nexport interface CreateTaskWorkStoreOptions {\n  /** Policy-free persistence driver used for direct canonical Task reads. */\n  driver: StoreDriver;\n  /** ISO timestamp source shared with the surrounding store engine. */\n  now: IsoDateTimeClock;\n  /** Lazily resolves graph, receipt, and Task operations after engine construction. */\n  stores: () => TaskWorkStores;\n  /** Exact workflow versions used to validate stored input and completion output. */\n  workflows: WorkflowRegistry;\n  /** Persists a validated Task with compare-and-swap semantics. */\n  update(task: Task, version: number): Promise<void>;\n  /** Recreates a missing canonical Task snapshot from its immutable graph admission. */\n  restore(task: Task): Promise<Task>;\n}\n\n/** Creates workflow-facing Task operations backed by canonical graph and Task stores. */\nexport function createTaskWorkStore(options: CreateTaskWorkStoreOptions): TaskWorkStore {\n  const { driver, now, stores, workflows, update, restore } = options;\n  function parseTask(value: unknown): Task {\n    const task = taskSchema.parse(value);\n    workflows.validateStoredInput(task.work.workflow, task.work.input);\n    if (task.workResult) workflows.validateStoredOutput(task.work.workflow, task.workResult.output);\n    return task;\n  }\n  async function read(id: TaskId) {\n    const record = await driver.get(\"tasks\", id);\n    if (!record) throw new RecordNotFoundError(\"tasks\", id);\n    const task = parseTask(record.value);\n    if (task.id !== id) throw new Error(`Task ${id} does not match its storage key`);\n    return { task, version: record.version, work: task.work };\n  }\n  async function recover(rootTaskId: TaskId): Promise<readonly Task[]> {\n    const graph = await stores().graphs.get(rootTaskId);\n    if (!graph) throw new RecordNotFoundError(\"taskGraphs\", rootTaskId);\n    const tasks: Task[] = [];\n    for (const node of graph.nodes) {\n      const admission = parseTask(node.admission);\n      const existing = await stores().tasks.get(node.taskId);\n      const task = parseTask(existing ?? (await restore(admission)));\n      assertTaskAdmission({ task, admission });\n      tasks.push(task);\n    }\n    return tasks;\n  }\n  function assertAttempt(task: Task, expectAttempt: number) {\n    z.number().int().positive().parse(expectAttempt);\n    if (task.attempt !== expectAttempt)\n      throw new Error(`Task ${task.id} is on attempt ${task.attempt}, not ${expectAttempt}`);\n  }\n  async function setWaiting(\n    id: TaskId,\n    expectAttempt: number,\n    waiting: boolean,\n    phase?: string,\n  ): Promise<Task> {\n    for (;;) {\n      const { task, version } = await read(id);\n      assertAttempt(task, expectAttempt);\n      if (task.state !== \"running\")\n        throw new Error(`Task ${id} must be running to ${waiting ? \"wait\" : \"resume\"}`);\n      const next = taskSchema.parse({\n        ...task,\n        waitingForMessages: waiting,\n        workflowPhase: phase ?? task.workflowPhase,\n        lastProgressAt: waiting ? task.lastProgressAt : now(),\n        updatedAt: now(),\n      });\n      if (task.waitingForMessages === waiting && next.workflowPhase === task.workflowPhase)\n        return task;\n      await stores().receipts.append({\n        taskId: id,\n        repositoryIds: task.repositoryIds,\n        kind: task.kind,\n        state: waiting ? \"waiting\" : \"resumed\",\n        phase: \"workflow\",\n        attempt: task.attempt,\n        reason: waiting\n          ? \"Workflow is waiting for Task messages\"\n          : \"Workflow resumed message processing\",\n        dedupeKey: `work:${id}:${version}:${waiting ? \"wait\" : \"resume\"}`,\n      });\n      try {\n        await update(next, version);\n        return next;\n      } catch (error) {\n        if (!(error instanceof VersionConflictError)) throw error;\n      }\n    }\n  }\n  async function complete(\n    input: CompleteTaskWorkInput,\n    expectedWorkflow?: WorkflowBinding,\n  ): Promise<Task> {\n    const {\n      task: { taskId: id, attempt: expectAttempt },\n      output: value,\n      fence,\n    } = input;\n    for (;;) {\n      const { task, work } = await read(id);\n      assertAttempt(task, expectAttempt);\n      if (fence !== undefined && !isDeepStrictEqual(task.execution, fence.execution)) {\n        throw new Error(`Task ${id} execution has been replaced`);\n      }\n      if (expectedWorkflow !== undefined && !isDeepStrictEqual(work.workflow, expectedWorkflow)) {\n        throw new Error(\n          `Task ${id} uses workflow ${work.workflow.id}@${work.workflow.version}, not ${expectedWorkflow.id}@${expectedWorkflow.version}`,\n        );\n      }\n      if (task.state === \"succeeded\") {\n        const output = workflows.validateOutput(work.workflow, value);\n        if (!isDeepStrictEqual(task.workResult?.output, output)) {\n          throw new Error(`Task ${id} already recorded a different workflow output`);\n        }\n        return task;\n      }\n      try {\n        return await stores().tasks.transition(id, \"succeeded\", {\n          output: value,\n          expectAttempt,\n          expectFrom: fence?.from ?? task.state,\n          ...(fence === undefined ? {} : { expectExecution: fence.execution }),\n          phase: \"workflow\",\n        });\n      } catch (error) {\n        if (error instanceof VersionConflictError) continue;\n        if (error instanceof InvalidTransitionError && (await read(id)).task.state === \"succeeded\")\n          continue;\n        throw error;\n      }\n    }\n  }\n  return {\n    complete,\n    completeWorkflow: ({ task, workflow, output, fence }) =>\n      complete({ task, output, fence }, workflow),\n    waitForMessages: ({ task: { taskId, attempt }, phase }) =>\n      setWaiting(taskId, attempt, true, phase),\n    resume: ({ task: { taskId, attempt } }) => setWaiting(taskId, attempt, false),\n    recover,\n    async usage(rootTaskId) {\n      const tasks = await recover(rootTaskId);\n      let micros = 0;\n      let inputTokens = 0;\n      let outputTokens = 0;\n      for (const task of tasks) {\n        micros += Math.round((task.usage?.costUsd ?? task.settledUsd ?? 0) * 1_000_000);\n        inputTokens += task.usage?.inputTokens ?? 0;\n        outputTokens += task.usage?.outputTokens ?? 0;\n      }\n      return { costUsd: micros / 1_000_000, inputTokens, outputTokens, taskCount: tasks.length };\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/sweep.d.mts

@@ -10,6 +10,10 @@ type SweepQueuedStores = Pick<FactoryStores, "graphs" | "receipts" | "repositori
 /**
  * Single-repository adapter for an exact agent route. Supplied by the app, which knows its
  * agents' addresses. Returns the provider's execution reference when it has one.
+ *
+ * @param task - Running Task already admitted by the dispatch gate.
+ * @param repository - Exact enabled repository selected from the Task scope.
+ * @returns Provider execution reference that dispatch can persist for recovery.
  */
 type TaskLauncher = (task: Task, repository: Repository) => Promise<ExecutionReference>;
 /** Exact-route launchers, budget gate, and pass bounds for queued Task dispatch. */
@@ -25,6 +29,7 @@ interface SweepQueuedOptions {
 }
 /** Tasks dispatched, deferred by a gate, or failed by one queued-work pass. */
 interface SweepQueuedResult {
+  /** Task IDs whose provider execution reference was durably recorded. */
   readonly dispatched: readonly TaskId[];
   /** Tasks left in the queue because a declared gate may become eligible later. */
   readonly skipped: readonly {
@@ -44,12 +49,29 @@ type SweepSkipReasonCode = DispatchRefusalCode | "workflow_owned" | "awaiting_ap
 /** Stable reason a queued Task could not be routed or launched. */
 type SweepFailureReasonCode = "invalid_repository_scope" | "repository_not_found" | "launcher_not_registered" | "launch_failed";
 /**
- * One pass of the factory's dispatcher, meant to run on a schedule inside the
- * deployment: every queued task that is allowed to run is started, in
- * creation order. Nothing outside the factory ever starts an agent; the CLI
- * only writes tasks and approvals, and this picks them up.
- * Idempotent by construction: dispatchTask's single-winner transition means
- * two overlapping sweeps cannot start the same task twice.
+ * Runs one bounded pass over queued Tasks and dispatches each eligible exact route.
+ *
+ * @remarks
+ * Candidates are ordered by newest attempt first and then creation time. Route-less work remains
+ * queued for its workflow owner; unmet dependencies, approvals, and pass limits appear in
+ * `skipped`. Invalid repository scope, missing repositories or launchers, and launch failures
+ * appear in `failed`, with unrouteable Tasks transitioned to `failed` when this sweep wins the
+ * race. A result entry describes this pass rather than guaranteeing the Task's lifecycle state:
+ * an ambiguously accepted launch is reported as `launch_failed` while its Task intentionally stays
+ * running for recovery. Callers should surface every failure, reread those Tasks before deciding
+ * remediation, and schedule another pass for skipped work.
+ *
+ * Overlapping passes are safe: {@link dispatchTask} atomically admits one winner before invoking a
+ * launcher. A supplied `tasks` snapshot bounds reads and candidate selection for this pass; it can
+ * become stale, and corresponding races are returned as `task_changed` rather than hidden.
+ * `maxDispatches` counts provider launches started during the pass, including launches that later
+ * fail, so `dispatched.length` may be smaller than the limit.
+ *
+ * @param stores - Graph, receipt, repository, and Task stores used during the pass.
+ * @param options - Exact-route launchers plus optional budget, Task snapshot, and dispatch limit.
+ * @returns IDs dispatched and structured skipped/failed outcomes for every considered candidate.
+ * @throws When `maxDispatches` is not a positive integer or an unexpected persistence error occurs.
+ * @see The shipped `docs/recipes/retry-recovery.md` recipe for scheduled recovery.
  */
 declare function sweepQueued(stores: SweepQueuedStores, options: SweepQueuedOptions): Promise<SweepQueuedResult>;
 //#endregion