@vercel/factory 0.0.14 → 0.0.16

package/dist/sandbox/task-environment.mjs

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { Sandbox } from "@vercel/sandbox";
+//#region src/sandbox/task-environment.ts
+const livenessByStatus = {
+	pending: "transitioning",
+	running: "live",
+	stopping: "terminal",
+	stopped: "terminal",
+	failed: "terminal",
+	aborted: "terminal",
+	snapshotting: "terminal"
+};
+function observe(sandbox) {
+	const liveness = livenessByStatus[sandbox.status];
+	if (liveness === void 0) throw new Error("Unsupported sandbox liveness state");
+	return {
+		sandbox,
+		liveness
+	};
+}
+const discoveryTagKey = "factoryTask";
+const defaultSeededMarker = "/workspace/.factory-seeded";
+const defaultBridgePorts = [4e3];
+/** Derive a deterministic provider sandbox name from a scoped Task-attempt identity. */
+function taskSandboxName(key, scope) {
+	return `factory-task-${createHash("sha256").update(`${scope}:${key.taskId}:${key.attempt}`).digest("hex").slice(0, 16)}`;
+}
+/** Build the complete tag set used to discover and re-verify a Task sandbox. */
+function taskSandboxTags(key, scope) {
+	return {
+		[discoveryTagKey]: taskSandboxName(key, scope),
+		factoryScope: createHash("sha256").update(scope).digest("hex").slice(0, 16),
+		factoryTaskId: key.taskId,
+		factoryTaskAttempt: String(key.attempt)
+	};
+}
+function verifyTags(key, scope, name, tags) {
+	const expected = taskSandboxTags(key, scope);
+	if (name !== taskSandboxName(key, scope) || tags?.[discoveryTagKey] !== expected[discoveryTagKey] || tags?.factoryScope !== expected.factoryScope || tags?.factoryTaskId !== expected.factoryTaskId || tags?.factoryTaskAttempt !== expected.factoryTaskAttempt) throw new Error(`Sandbox ${name} does not carry the identity of Task ${key.taskId} attempt ${key.attempt}`);
+}
+async function isSeeded(sandbox, marker) {
+	return (await sandbox.runCommand({
+		cmd: "test",
+		args: ["-f", marker],
+		timeoutMs: 1e4
+	})).exitCode === 0;
+}
+async function markSeeded(sandbox, marker) {
+	await sandbox.writeFiles([{
+		path: marker,
+		content: "seeded"
+	}]);
+}
+/** Create or recover the exact sandbox for a Task attempt and ensure seeding completed. */
+async function ensureTaskSandbox(key, options) {
+	const api = options.api ?? Sandbox;
+	const name = taskSandboxName(key, options.scope);
+	const seededMarker = options.seededMarker ?? defaultSeededMarker;
+	const sandbox = await api.getOrCreate({
+		name,
+		runtime: options.runtime ?? "node24",
+		ports: [...options.ports ?? defaultBridgePorts],
+		timeout: options.timeoutMs,
+		tags: taskSandboxTags(key, options.scope),
+		async onCreate(created) {
+			await options.seed(created);
+			await markSeeded(created, seededMarker);
+		}
+	});
+	verifyTags(key, options.scope, sandbox.name, sandbox.tags);
+	if (!await isSeeded(sandbox, seededMarker)) {
+		await options.seed(sandbox);
+		await markSeeded(sandbox, seededMarker);
+	}
+	return sandbox;
+}
+/** Discover an existing Task sandbox without resuming or replacing it. */
+async function findTaskSandbox(key, options) {
+	const api = options.api ?? Sandbox;
+	const name = taskSandboxName(key, options.scope);
+	const matches = await api.list({
+		tags: { [discoveryTagKey]: name },
+		limit: 2
+	});
+	if (matches.sandboxes.length === 0) return null;
+	if (matches.sandboxes.length > 1 || matches.pagination.next) throw new Error(`More than one sandbox matches Task ${key.taskId} attempt ${key.attempt}; refusing to select one`);
+	const candidate = matches.sandboxes[0];
+	verifyTags(key, options.scope, candidate.name, candidate.tags);
+	let sandbox;
+	try {
+		sandbox = await api.get({
+			name: candidate.name,
+			resume: false
+		});
+	} catch (error) {
+		if (isMissing(error)) return null;
+		throw error;
+	}
+	verifyTags(key, options.scope, sandbox.name, sandbox.tags);
+	return sandbox;
+}
+/** Stop a live Task sandbox idempotently while treating provider disappearance as success. */
+async function stopTaskSandbox(sandbox) {
+	if (observe(sandbox).liveness === "terminal") return;
+	try {
+		await sandbox.stop();
+	} catch (error) {
+		if (!isMissing(error)) throw error;
+	}
+}
+function isMissing(error) {
+	return typeof error === "object" && error !== null && ("status" in error && error.status === 404 || "response" in error && error.response instanceof Response && error.response.status === 404);
+}
+/** Adapt scoped Vercel Sandbox creation and discovery to the execution-environment contract. */
+function createTaskSandboxEnvironment(options) {
+	return {
+		name: (key) => taskSandboxName(key, options.scope),
+		ensure: (key, { timeoutMs, request }) => ensureTaskSandbox(key, {
+			scope: options.scope,
+			timeoutMs,
+			seed: (sandbox) => options.seed(request, sandbox),
+			...options.runtime ? { runtime: options.runtime } : {},
+			...options.ports ? { ports: options.ports } : {},
+			...options.seededMarker ? { seededMarker: options.seededMarker } : {},
+			api: options.api
+		}).then(observe),
+		find: async (key) => {
+			const sandbox = await findTaskSandbox(key, {
+				scope: options.scope,
+				api: options.api
+			});
+			return sandbox ? observe(sandbox) : null;
+		},
+		stop: stopTaskSandbox
+	};
+}
+//#endregion
+export { createTaskSandboxEnvironment, ensureTaskSandbox, findTaskSandbox, stopTaskSandbox, taskSandboxName, taskSandboxTags };
+
+//# sourceMappingURL=task-environment.mjs.map

package/dist/sandbox/task-environment.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-environment.mjs","names":[],"sources":["../../src/sandbox/task-environment.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport { Sandbox } from \"@vercel/sandbox\";\nimport type { CodingExecutionRequest, TaskAttemptRef } from \"../schema/execution\";\nimport type { ExecutionEnvironment, EnvironmentLiveness } from \"./execution-environment\";\n\nconst livenessByStatus: Record<Sandbox[\"status\"], EnvironmentLiveness> = {\n  pending: \"transitioning\",\n  running: \"live\",\n  stopping: \"terminal\",\n  stopped: \"terminal\",\n  failed: \"terminal\",\n  aborted: \"terminal\",\n  snapshotting: \"terminal\",\n};\n\nfunction observe(sandbox: Sandbox) {\n  const liveness = livenessByStatus[sandbox.status];\n  if (liveness === undefined) throw new Error(\"Unsupported sandbox liveness state\");\n  return { sandbox, liveness };\n}\n\n/** Isolates stores that reuse Task IDs within the project's shared sandbox namespace. */\nexport interface TaskSandboxScope {\n  scope: string;\n}\n\n/** Injectable subset of the Vercel Sandbox API used for creation and exact identity discovery. */\nexport type SandboxApi = Pick<typeof Sandbox, \"getOrCreate\" | \"get\" | \"list\">;\n\nconst discoveryTagKey = \"factoryTask\";\nconst defaultSeededMarker = \"/workspace/.factory-seeded\";\n// The harness bridge listens on port 4000.\nconst defaultBridgePorts = [4000];\n\n/** Derive a deterministic provider sandbox name from a scoped Task-attempt identity. */\nexport function taskSandboxName(key: TaskAttemptRef, scope: string): string {\n  const digest = createHash(\"sha256\")\n    .update(`${scope}:${key.taskId}:${key.attempt}`)\n    .digest(\"hex\")\n    .slice(0, 16);\n  return `factory-task-${digest}`;\n}\n\n/** Build the complete tag set used to discover and re-verify a Task sandbox. */\nexport function taskSandboxTags(key: TaskAttemptRef, scope: string): Record<string, string> {\n  return {\n    [discoveryTagKey]: taskSandboxName(key, scope),\n    factoryScope: createHash(\"sha256\").update(scope).digest(\"hex\").slice(0, 16),\n    factoryTaskId: key.taskId,\n    factoryTaskAttempt: String(key.attempt),\n  };\n}\n\nfunction verifyTags(\n  key: TaskAttemptRef,\n  scope: string,\n  name: string,\n  tags: Record<string, string> | undefined,\n) {\n  const expected = taskSandboxTags(key, scope);\n  if (\n    name !== taskSandboxName(key, scope) ||\n    tags?.[discoveryTagKey] !== expected[discoveryTagKey] ||\n    tags?.factoryScope !== expected.factoryScope ||\n    tags?.factoryTaskId !== expected.factoryTaskId ||\n    tags?.factoryTaskAttempt !== expected.factoryTaskAttempt\n  ) {\n    throw new Error(\n      `Sandbox ${name} does not carry the identity of Task ${key.taskId} attempt ${key.attempt}`,\n    );\n  }\n}\n\nasync function isSeeded(sandbox: Sandbox, marker: string): Promise<boolean> {\n  const command = await sandbox.runCommand({\n    cmd: \"test\",\n    args: [\"-f\", marker],\n    timeoutMs: 10_000,\n  });\n  return command.exitCode === 0;\n}\n\nasync function markSeeded(sandbox: Sandbox, marker: string): Promise<void> {\n  await sandbox.writeFiles([{ path: marker, content: \"seeded\" }]);\n}\n\n/** Configures idempotent creation and workspace seeding for a Task sandbox. */\nexport interface EnsureTaskSandboxOptions extends TaskSandboxScope {\n  /** Sandbox lifetime; callers add margin over the execution timeout. */\n  timeoutMs: number;\n  /** Seeds the workspace; must be idempotent because a crashed seed reruns. */\n  seed(sandbox: Sandbox): Promise<void>;\n  runtime?: string;\n  ports?: readonly number[];\n  seededMarker?: string;\n  api?: SandboxApi;\n}\n\n/** Create or recover the exact sandbox for a Task attempt and ensure seeding completed. */\nexport async function ensureTaskSandbox(\n  key: TaskAttemptRef,\n  options: EnsureTaskSandboxOptions,\n): Promise<Sandbox> {\n  const api = options.api ?? Sandbox;\n  const name = taskSandboxName(key, options.scope);\n  const seededMarker = options.seededMarker ?? defaultSeededMarker;\n  const sandbox = await api.getOrCreate({\n    name,\n    runtime: options.runtime ?? \"node24\",\n    ports: [...(options.ports ?? defaultBridgePorts)],\n    timeout: options.timeoutMs,\n    tags: taskSandboxTags(key, options.scope),\n    async onCreate(created) {\n      await options.seed(created);\n      await markSeeded(created, seededMarker);\n    },\n  });\n  verifyTags(key, options.scope, sandbox.name, sandbox.tags);\n  // onCreate can crash between creation and the marker; finish seeding here.\n  if (!(await isSeeded(sandbox, seededMarker))) {\n    await options.seed(sandbox);\n    await markSeeded(sandbox, seededMarker);\n  }\n  return sandbox;\n}\n\n/** Scope and provider API used to discover an existing Task sandbox. */\nexport interface FindTaskSandboxOptions extends TaskSandboxScope {\n  api?: SandboxApi;\n}\n\n/** Discover an existing Task sandbox without resuming or replacing it. */\nexport async function findTaskSandbox(\n  key: TaskAttemptRef,\n  options: FindTaskSandboxOptions,\n): Promise<Sandbox | null> {\n  const api = options.api ?? Sandbox;\n  const name = taskSandboxName(key, options.scope);\n  // The Sandbox API accepts only one tag filter; all tags are re-verified below.\n  const matches = await api.list({ tags: { [discoveryTagKey]: name }, limit: 2 });\n  if (matches.sandboxes.length === 0) return null;\n  if (matches.sandboxes.length > 1 || matches.pagination.next) {\n    throw new Error(\n      `More than one sandbox matches Task ${key.taskId} attempt ${key.attempt}; refusing to select one`,\n    );\n  }\n  const candidate = matches.sandboxes[0]!;\n  verifyTags(key, options.scope, candidate.name, candidate.tags);\n  let sandbox: Sandbox;\n  try {\n    sandbox = await api.get({ name: candidate.name, resume: false });\n  } catch (error) {\n    if (isMissing(error)) return null;\n    throw error;\n  }\n  verifyTags(key, options.scope, sandbox.name, sandbox.tags);\n  return sandbox;\n}\n\n/** Stop a live Task sandbox idempotently while treating provider disappearance as success. */\nexport async function stopTaskSandbox(sandbox: Sandbox): Promise<void> {\n  if (observe(sandbox).liveness === \"terminal\") return;\n  try {\n    await sandbox.stop();\n  } catch (error) {\n    if (!isMissing(error)) throw error;\n  }\n}\n\nfunction isMissing(error: unknown): boolean {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    ((\"status\" in error && error.status === 404) ||\n      (\"response\" in error && error.response instanceof Response && error.response.status === 404))\n  );\n}\n\n/** Scoped creation, seeding, and provider dependencies for a Task sandbox environment. */\nexport interface TaskSandboxEnvironmentOptions {\n  /** Deployment- or run-unique namespace; see {@link TaskSandboxScope}. */\n  scope: string;\n  seed(request: CodingExecutionRequest, sandbox: Sandbox): Promise<void>;\n  runtime?: EnsureTaskSandboxOptions[\"runtime\"];\n  ports?: readonly number[];\n  seededMarker?: string;\n  api?: SandboxApi;\n}\n\n/** Adapt scoped Vercel Sandbox creation and discovery to the execution-environment contract. */\nexport function createTaskSandboxEnvironment(\n  options: TaskSandboxEnvironmentOptions,\n): ExecutionEnvironment<Sandbox> {\n  return {\n    name: (key) => taskSandboxName(key, options.scope),\n    ensure: (key, { timeoutMs, request }) =>\n      ensureTaskSandbox(key, {\n        scope: options.scope,\n        timeoutMs,\n        seed: (sandbox) => options.seed(request, sandbox),\n        ...(options.runtime ? { runtime: options.runtime } : {}),\n        ...(options.ports ? { ports: options.ports } : {}),\n        ...(options.seededMarker ? { seededMarker: options.seededMarker } : {}),\n        api: options.api,\n      }).then(observe),\n    find: async (key) => {\n      const sandbox = await findTaskSandbox(key, { scope: options.scope, api: options.api });\n      return sandbox ? observe(sandbox) : null;\n    },\n    stop: stopTaskSandbox,\n  };\n}\n"],"mappings":"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"}

package/dist/sandbox/workspace.d.mts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+//#region src/sandbox/workspace.d.ts
+declare const outputPathSchema: z.core.$ZodBranded<z.ZodString, "SandboxOutputPath", "out">;
+/** An absolute, normalized artifact path confined to the configured sandbox output directory. */
+type SandboxOutputPath = z.infer<typeof outputPathSchema>;
+/** Current working directory reported by a sandbox session. */
+interface SandboxSession {
+  cwd: string;
+}
+/** Minimal sandbox session boundary needed to derive workspace paths. */
+interface SandboxWorkspaceHandle {
+  currentSession(): SandboxSession;
+}
+/** Standard repository, output, and artifact paths inside a harness workspace. */
+interface HarnessWorkspace {
+  root: string;
+  repo: string;
+  out: string;
+  artifacts: string;
+}
+/** File existence, symlinks, and read limits are checked by the sandbox reader. */
+declare function parseSandboxOutputPath(value: unknown, outputDirectory: string): SandboxOutputPath;
+/** Default harness SDK working directory beneath the sandbox session root. */
+declare const defaultHarnessWorkDir = "workspace";
+/** Resolve the standard repository, output, and artifact paths for a harness workspace. */
+declare function harnessWorkspace(sandbox: SandboxWorkspaceHandle): HarnessWorkspace;
+//#endregion
+export { HarnessWorkspace, SandboxOutputPath, SandboxSession, SandboxWorkspaceHandle, defaultHarnessWorkDir, harnessWorkspace, parseSandboxOutputPath };
+//# sourceMappingURL=workspace.d.mts.map

package/dist/sandbox/workspace.mjs

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { posix } from "node:path";
+//#region src/sandbox/workspace.ts
+const outputPathSchema = z.string().refine((value) => posix.isAbsolute(value) && posix.normalize(value) === value && !value.includes("\0"), "Artifact paths must stay inside the captured workspace output").brand();
+/** File existence, symlinks, and read limits are checked by the sandbox reader. */
+function parseSandboxOutputPath(value, outputDirectory) {
+	const path = outputPathSchema.parse(value);
+	if (!path.startsWith(`${outputDirectory}/`)) throw new Error("Artifact paths must stay inside the captured workspace output");
+	return path;
+}
+/** Default harness SDK working directory beneath the sandbox session root. */
+const defaultHarnessWorkDir = "workspace";
+/** Resolve the standard repository, output, and artifact paths for a harness workspace. */
+function harnessWorkspace(sandbox) {
+	const cwd = sandbox.currentSession().cwd;
+	if (!posix.isAbsolute(cwd)) throw new Error("The sandbox working directory must be absolute");
+	const root = posix.join(cwd, defaultHarnessWorkDir);
+	return {
+		root,
+		repo: posix.join(root, "repo"),
+		out: posix.join(root, "out"),
+		artifacts: posix.join(root, "artifacts")
+	};
+}
+//#endregion
+export { defaultHarnessWorkDir, harnessWorkspace, parseSandboxOutputPath };
+
+//# sourceMappingURL=workspace.mjs.map

package/dist/sandbox/workspace.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.mjs","names":[],"sources":["../../src/sandbox/workspace.ts"],"sourcesContent":["import { posix } from \"node:path\";\nimport { z } from \"zod\";\n\nconst outputPathSchema = z\n  .string()\n  .refine(\n    (value) => posix.isAbsolute(value) && posix.normalize(value) === value && !value.includes(\"\\0\"),\n    \"Artifact paths must stay inside the captured workspace output\",\n  )\n  .brand<\"SandboxOutputPath\">();\n\n/** An absolute, normalized artifact path confined to the configured sandbox output directory. */\nexport type SandboxOutputPath = z.infer<typeof outputPathSchema>;\n\n/** Current working directory reported by a sandbox session. */\nexport interface SandboxSession {\n  cwd: string;\n}\n\n/** Minimal sandbox session boundary needed to derive workspace paths. */\nexport interface SandboxWorkspaceHandle {\n  currentSession(): SandboxSession;\n}\n\n/** Standard repository, output, and artifact paths inside a harness workspace. */\nexport interface HarnessWorkspace {\n  root: string;\n  repo: string;\n  out: string;\n  artifacts: string;\n}\n\n/** File existence, symlinks, and read limits are checked by the sandbox reader. */\nexport function parseSandboxOutputPath(value: unknown, outputDirectory: string): SandboxOutputPath {\n  const path = outputPathSchema.parse(value);\n  if (!path.startsWith(`${outputDirectory}/`))\n    throw new Error(\"Artifact paths must stay inside the captured workspace output\");\n  return path;\n}\n\n/** Default harness SDK working directory beneath the sandbox session root. */\nexport const defaultHarnessWorkDir = \"workspace\";\n\n/** Resolve the standard repository, output, and artifact paths for a harness workspace. */\nexport function harnessWorkspace(sandbox: SandboxWorkspaceHandle): HarnessWorkspace {\n  const cwd = sandbox.currentSession().cwd;\n  if (!posix.isAbsolute(cwd)) throw new Error(\"The sandbox working directory must be absolute\");\n  const root = posix.join(cwd, defaultHarnessWorkDir);\n  return {\n    root,\n    repo: posix.join(root, \"repo\"),\n    out: posix.join(root, \"out\"),\n    artifacts: posix.join(root, \"artifacts\"),\n  };\n}\n"],"mappings":";;;AAGA,MAAM,mBAAmB,EACtB,OAAO,CAAC,CACR,QACE,UAAU,MAAM,WAAW,KAAK,KAAK,MAAM,UAAU,KAAK,MAAM,SAAS,CAAC,MAAM,SAAS,IAAI,GAC9F,+DACF,CAAC,CACA,MAA2B;;AAwB9B,SAAgB,uBAAuB,OAAgB,iBAA4C;CACjG,MAAM,OAAO,iBAAiB,MAAM,KAAK;CACzC,IAAI,CAAC,KAAK,WAAW,GAAG,gBAAgB,EAAE,GACxC,MAAM,IAAI,MAAM,+DAA+D;CACjF,OAAO;AACT;;AAGA,MAAa,wBAAwB;;AAGrC,SAAgB,iBAAiB,SAAmD;CAClF,MAAM,MAAM,QAAQ,eAAe,CAAC,CAAC;CACrC,IAAI,CAAC,MAAM,WAAW,GAAG,GAAG,MAAM,IAAI,MAAM,gDAAgD;CAC5F,MAAM,OAAO,MAAM,KAAK,KAAK,qBAAqB;CAClD,OAAO;EACL;EACA,MAAM,MAAM,KAAK,MAAM,MAAM;EAC7B,KAAK,MAAM,KAAK,MAAM,KAAK;EAC3B,WAAW,MAAM,KAAK,MAAM,WAAW;CACzC;AACF"}

package/dist/schema/agent-route.d.mts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+//#region src/schema/agent-route.d.ts
+/** Validates an exact agent-route identity used for lookup and persisted recovery. */
+declare const agentRouteBindingSchema: z.core.$ZodBranded<z.ZodObject<{
+  id: z.ZodString;
+  version: z.ZodNumber;
+}, z.core.$strict>, "AgentRouteBinding", "out">;
+/** Exact identifier and version selecting one registered agent route. */
+type AgentRouteBinding<Id extends string = string, Version extends number = number> = z.infer<typeof agentRouteBindingSchema> & {
+  readonly id: Id;
+  readonly version: Version;
+};
+/** Plain identifier and version accepted when constructing an agent-route binding. */
+interface AgentRouteBindingInput<Id extends string = string, Version extends number = number> {
+  readonly id: Id;
+  readonly version: Version;
+}
+/**
+ * Validates and brands an exact agent-route binding while preserving literal identity.
+ *
+ * @remarks
+ * This creates an identity value only; it does not prove that the route is registered. Resolve it
+ * through `defineAgentRoutes(...).get(binding)` or let dispatch compare it with the Task's stored
+ * route. Both ID and version are required, so recovery never selects an implicit latest version.
+ *
+ * @param input - Plain route ID and positive exact version.
+ * @returns A validated binding retaining the input's literal ID and version types.
+ * @throws A Zod validation error when either field is invalid.
+ *
+ * @example
+ * ```ts
+ * import { parseAgentRouteBinding } from "@vercel/factory/workflows";
+ *
+ * const route = parseAgentRouteBinding({ id: "incident-worker", version: 1 });
+ * ```
+ */
+declare function parseAgentRouteBinding<const Input extends AgentRouteBindingInput>(input: Input): AgentRouteBinding<Input["id"], Input["version"]>;
+//#endregion
+export { AgentRouteBinding, AgentRouteBindingInput, agentRouteBindingSchema, parseAgentRouteBinding };
+//# sourceMappingURL=agent-route.d.mts.map

package/dist/schema/agent-route.mjs

@@ -0,0 +1,33 @@
+import { z } from "zod";
+//#region src/schema/agent-route.ts
+/** Validates an exact agent-route identity used for lookup and persisted recovery. */
+const agentRouteBindingSchema = z.strictObject({
+	id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/u).describe("Stable route identifier selected by a workflow."),
+	version: z.number().int().positive().describe("Exact positive version of the selected route.")
+}).describe("Exact agent-route identity; lookup never defaults or selects a latest version.").brand();
+/**
+* Validates and brands an exact agent-route binding while preserving literal identity.
+*
+* @remarks
+* This creates an identity value only; it does not prove that the route is registered. Resolve it
+* through `defineAgentRoutes(...).get(binding)` or let dispatch compare it with the Task's stored
+* route. Both ID and version are required, so recovery never selects an implicit latest version.
+*
+* @param input - Plain route ID and positive exact version.
+* @returns A validated binding retaining the input's literal ID and version types.
+* @throws A Zod validation error when either field is invalid.
+*
+* @example
+* ```ts
+* import { parseAgentRouteBinding } from "@vercel/factory/workflows";
+*
+* const route = parseAgentRouteBinding({ id: "incident-worker", version: 1 });
+* ```
+*/
+function parseAgentRouteBinding(input) {
+	return agentRouteBindingSchema.parse(input);
+}
+//#endregion
+export { agentRouteBindingSchema, parseAgentRouteBinding };
+
+//# sourceMappingURL=agent-route.mjs.map

package/dist/schema/agent-route.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-route.mjs","names":[],"sources":["../../src/schema/agent-route.ts"],"sourcesContent":["import { z } from \"zod\";\n\n/** Validates an exact agent-route identity used for lookup and persisted recovery. */\nexport const agentRouteBindingSchema = z\n  .strictObject({\n    id: z\n      .string()\n      .regex(/^[a-z][a-z0-9-]{0,63}$/u)\n      .describe(\"Stable route identifier selected by a workflow.\"),\n    version: z.number().int().positive().describe(\"Exact positive version of the selected route.\"),\n  })\n  .describe(\"Exact agent-route identity; lookup never defaults or selects a latest version.\")\n  .brand<\"AgentRouteBinding\">();\n\n/** Exact identifier and version selecting one registered agent route. */\nexport type AgentRouteBinding<\n  Id extends string = string,\n  Version extends number = number,\n> = z.infer<typeof agentRouteBindingSchema> & {\n  readonly id: Id;\n  readonly version: Version;\n};\n\n/** Plain identifier and version accepted when constructing an agent-route binding. */\nexport interface AgentRouteBindingInput<\n  Id extends string = string,\n  Version extends number = number,\n> {\n  readonly id: Id;\n  readonly version: Version;\n}\n\n/**\n * Validates and brands an exact agent-route binding while preserving literal identity.\n *\n * @remarks\n * This creates an identity value only; it does not prove that the route is registered. Resolve it\n * through `defineAgentRoutes(...).get(binding)` or let dispatch compare it with the Task's stored\n * route. Both ID and version are required, so recovery never selects an implicit latest version.\n *\n * @param input - Plain route ID and positive exact version.\n * @returns A validated binding retaining the input's literal ID and version types.\n * @throws A Zod validation error when either field is invalid.\n *\n * @example\n * ```ts\n * import { parseAgentRouteBinding } from \"@vercel/factory/workflows\";\n *\n * const route = parseAgentRouteBinding({ id: \"incident-worker\", version: 1 });\n * ```\n */\nexport function parseAgentRouteBinding<const Input extends AgentRouteBindingInput>(\n  input: Input,\n): AgentRouteBinding<Input[\"id\"], Input[\"version\"]> {\n  return agentRouteBindingSchema.parse(input) as AgentRouteBinding<Input[\"id\"], Input[\"version\"]>;\n}\n"],"mappings":";;;AAGA,MAAa,0BAA0B,EACpC,aAAa;CACZ,IAAI,EACD,OAAO,CAAC,CACR,MAAM,yBAAyB,CAAC,CAChC,SAAS,iDAAiD;CAC7D,SAAS,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,+CAA+C;AAC/F,CAAC,CAAC,CACD,SAAS,gFAAgF,CAAC,CAC1F,MAA2B;;;;;;;;;;;;;;;;;;;;AAuC9B,SAAgB,uBACd,OACkD;CAClD,OAAO,wBAAwB,MAAM,KAAK;AAC5C"}

package/dist/schema/answer.d.mts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+//#region src/schema/answer.d.ts
+/** Validates an immutable authenticated answer to a workflow QuestionTask. */
+declare const answerEventSchema: z.ZodObject<{
+  schemaVersion: z.ZodLiteral<1>;
+  id: z.ZodType<`ans_${string}`, string, z.core.$ZodTypeInternals<`ans_${string}`, string>>;
+  questionTaskId: z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>;
+  parentTaskId: z.ZodOptional<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>;
+  repositoryIds: z.ZodReadonly<z.ZodTuple<[z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>], z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>>>;
+  replyTo: z.ZodObject<{
+    channel: z.ZodString;
+    address: z.ZodString;
+  }, z.core.$strict>;
+  question: z.ZodString;
+  answer: z.ZodString;
+  answeredBy: z.ZodString;
+  recordedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+/** Immutable authenticated answer projected onto a question and its parent Task. */
+type AnswerEvent = z.infer<typeof answerEventSchema>;
+//#endregion
+export { AnswerEvent, answerEventSchema };
+//# sourceMappingURL=answer.d.mts.map

package/dist/schema/answer.mjs

@@ -0,0 +1,21 @@
+import { answerIdSchema, repositoryIdsSchema, taskIdSchema } from "./id.mjs";
+import { isoDateTimeSchema, replyToSchema, schemaVersionSchema } from "./common.mjs";
+import { z } from "zod";
+//#region src/schema/answer.ts
+/** Validates an immutable authenticated answer to a workflow QuestionTask. */
+const answerEventSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: answerIdSchema,
+	questionTaskId: taskIdSchema,
+	parentTaskId: taskIdSchema.optional(),
+	repositoryIds: repositoryIdsSchema,
+	replyTo: replyToSchema,
+	question: z.string().min(1),
+	answer: z.string().min(1).max(4e3),
+	answeredBy: z.string().min(1),
+	recordedAt: isoDateTimeSchema
+});
+//#endregion
+export { answerEventSchema };
+
+//# sourceMappingURL=answer.mjs.map

package/dist/schema/answer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"answer.mjs","names":[],"sources":["../../src/schema/answer.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { isoDateTimeSchema, replyToSchema, schemaVersionSchema } from \"./common\";\nimport { answerIdSchema, repositoryIdsSchema, taskIdSchema } from \"./id\";\n\n/** Validates an immutable authenticated answer to a workflow QuestionTask. */\nexport const answerEventSchema = z.strictObject({\n  schemaVersion: schemaVersionSchema,\n  id: answerIdSchema,\n  questionTaskId: taskIdSchema,\n  parentTaskId: taskIdSchema.optional(),\n  repositoryIds: repositoryIdsSchema,\n  replyTo: replyToSchema,\n  question: z.string().min(1),\n  answer: z.string().min(1).max(4000),\n  answeredBy: z.string().min(1),\n  recordedAt: isoDateTimeSchema,\n});\n\n/** Immutable authenticated answer projected onto a question and its parent Task. */\nexport type AnswerEvent = z.infer<typeof answerEventSchema>;\n"],"mappings":";;;;;AAKA,MAAa,oBAAoB,EAAE,aAAa;CAC9C,eAAe;CACf,IAAI;CACJ,gBAAgB;CAChB,cAAc,aAAa,SAAS;CACpC,eAAe;CACf,SAAS;CACT,UAAU,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CAC1B,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAI;CAClC,YAAY,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CAC5B,YAAY;AACd,CAAC"}

package/dist/schema/budget.d.mts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+//#region src/schema/budget.d.ts
+/** UTC calendar month key in `YYYY-MM` form. */
+type BudgetMonth = `${number}-${"01" | "02" | "03" | "04" | "05" | "06" | "07" | "08" | "09" | "10" | "11" | "12"}`;
+/** Validates the UTC calendar month key used for a Factory budget. */
+declare const budgetMonthSchema: z.ZodType<BudgetMonth, string>;
+/** Validates Factory-wide, investigative, per-Task, and optional repository spending limits. */
+declare const budgetLimitsSchema: z.ZodReadonly<z.ZodObject<{
+  totalUsd: z.ZodNumber;
+  investigationUsd: z.ZodNumber;
+  perTaskReservationUsd: z.ZodNumber;
+  warningPercent: z.ZodNumber;
+  perRepositoryUsd: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodType<`${string}/${string}`, string, z.core.$ZodTypeInternals<`${string}/${string}`, string>>, z.ZodNumber>>>;
+}, z.core.$strict>>;
+/** Validates one persisted monthly Factory budget and its emitted-notice state. */
+declare const budgetSchema: z.ZodReadonly<z.ZodObject<{
+  schemaVersion: z.ZodLiteral<1>;
+  factoryId: z.ZodType<`fac_${string}`, string, z.core.$ZodTypeInternals<`fac_${string}`, string>>;
+  month: z.ZodType<`${number}-01` | `${number}-02` | `${number}-03` | `${number}-04` | `${number}-05` | `${number}-06` | `${number}-07` | `${number}-08` | `${number}-09` | `${number}-10` | `${number}-11` | `${number}-12`, string, z.core.$ZodTypeInternals<`${number}-01` | `${number}-02` | `${number}-03` | `${number}-04` | `${number}-05` | `${number}-06` | `${number}-07` | `${number}-08` | `${number}-09` | `${number}-10` | `${number}-11` | `${number}-12`, string>>;
+  limits: z.ZodReadonly<z.ZodObject<{
+    totalUsd: z.ZodNumber;
+    investigationUsd: z.ZodNumber;
+    perTaskReservationUsd: z.ZodNumber;
+    warningPercent: z.ZodNumber;
+    perRepositoryUsd: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodType<`${string}/${string}`, string, z.core.$ZodTypeInternals<`${string}/${string}`, string>>, z.ZodNumber>>>;
+  }, z.core.$strict>>;
+  notices: z.ZodReadonly<z.ZodObject<{
+    warningAt: z.ZodOptional<z.ZodISODateTime>;
+    exhaustedAt: z.ZodOptional<z.ZodISODateTime>;
+  }, z.core.$strict>>;
+}, z.core.$strict>>;
+/** Spending limits and warning threshold enforced for a monthly Factory budget. */
+type BudgetLimits = z.infer<typeof budgetLimitsSchema>;
+/** Persisted monthly Factory budget configuration and notice state. */
+type Budget = z.infer<typeof budgetSchema>;
+//#endregion
+export { Budget, BudgetLimits, BudgetMonth, budgetLimitsSchema, budgetMonthSchema, budgetSchema };
+//# sourceMappingURL=budget.d.mts.map

package/dist/schema/budget.mjs

@@ -0,0 +1,30 @@
+import { factoryIdSchema } from "./id.mjs";
+import { isoDateTimeSchema, schemaVersionSchema, usdSchema } from "./common.mjs";
+import { repositorySlugSchema } from "./repository.mjs";
+import { z } from "zod";
+//#region src/schema/budget.ts
+/** Validates the UTC calendar month key used for a Factory budget. */
+const budgetMonthSchema = z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/u, "Expected a UTC calendar month in YYYY-MM form");
+/** Validates Factory-wide, investigative, per-Task, and optional repository spending limits. */
+const budgetLimitsSchema = z.strictObject({
+	totalUsd: usdSchema,
+	investigationUsd: usdSchema,
+	perTaskReservationUsd: usdSchema,
+	warningPercent: z.number().int().min(1).max(100),
+	perRepositoryUsd: z.record(repositorySlugSchema, usdSchema).readonly().optional()
+}).readonly();
+/** Validates one persisted monthly Factory budget and its emitted-notice state. */
+const budgetSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	factoryId: factoryIdSchema,
+	month: budgetMonthSchema,
+	limits: budgetLimitsSchema,
+	notices: z.strictObject({
+		warningAt: isoDateTimeSchema.optional(),
+		exhaustedAt: isoDateTimeSchema.optional()
+	}).readonly()
+}).readonly();
+//#endregion
+export { budgetLimitsSchema, budgetMonthSchema, budgetSchema };
+
+//# sourceMappingURL=budget.mjs.map

package/dist/schema/budget.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.mjs","names":[],"sources":["../../src/schema/budget.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { isoDateTimeSchema, schemaVersionSchema, usdSchema } from \"./common\";\nimport { factoryIdSchema } from \"./id\";\nimport { repositorySlugSchema } from \"./repository\";\n\n/** UTC calendar month key in `YYYY-MM` form. */\nexport type BudgetMonth = `${number}-${\n  | \"01\"\n  | \"02\"\n  | \"03\"\n  | \"04\"\n  | \"05\"\n  | \"06\"\n  | \"07\"\n  | \"08\"\n  | \"09\"\n  | \"10\"\n  | \"11\"\n  | \"12\"}`;\n\n/** Validates the UTC calendar month key used for a Factory budget. */\nexport const budgetMonthSchema = z\n  .string()\n  .regex(/^\\d{4}-(0[1-9]|1[0-2])$/u, \"Expected a UTC calendar month in YYYY-MM form\") as z.ZodType<\n  BudgetMonth,\n  string\n>;\n\n/** Validates Factory-wide, investigative, per-Task, and optional repository spending limits. */\nexport const budgetLimitsSchema = z\n  .strictObject({\n    totalUsd: usdSchema,\n    investigationUsd: usdSchema,\n    perTaskReservationUsd: usdSchema,\n    warningPercent: z.number().int().min(1).max(100),\n    perRepositoryUsd: z.record(repositorySlugSchema, usdSchema).readonly().optional(),\n  })\n  .readonly();\n\n/** Validates one persisted monthly Factory budget and its emitted-notice state. */\nexport const budgetSchema = z\n  .strictObject({\n    schemaVersion: schemaVersionSchema,\n    factoryId: factoryIdSchema,\n    month: budgetMonthSchema,\n    limits: budgetLimitsSchema,\n    notices: z\n      .strictObject({\n        warningAt: isoDateTimeSchema.optional(),\n        exhaustedAt: isoDateTimeSchema.optional(),\n      })\n      .readonly(),\n  })\n  .readonly();\n\n/** Spending limits and warning threshold enforced for a monthly Factory budget. */\nexport type BudgetLimits = z.infer<typeof budgetLimitsSchema>;\n/** Persisted monthly Factory budget configuration and notice state. */\nexport type Budget = z.infer<typeof budgetSchema>;\n"],"mappings":";;;;;;AAqBA,MAAa,oBAAoB,EAC9B,OAAO,CAAC,CACR,MAAM,4BAA4B,+CAA+C;;AAMpF,MAAa,qBAAqB,EAC/B,aAAa;CACZ,UAAU;CACV,kBAAkB;CAClB,uBAAuB;CACvB,gBAAgB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG;CAC/C,kBAAkB,EAAE,OAAO,sBAAsB,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS;AAClF,CAAC,CAAC,CACD,SAAS;;AAGZ,MAAa,eAAe,EACzB,aAAa;CACZ,eAAe;CACf,WAAW;CACX,OAAO;CACP,QAAQ;CACR,SAAS,EACN,aAAa;EACZ,WAAW,kBAAkB,SAAS;EACtC,aAAa,kBAAkB,SAAS;CAC1C,CAAC,CAAC,CACD,SAAS;AACd,CAAC,CAAC,CACD,SAAS"}

package/dist/schema/catalog.mjs

@@ -0,0 +1,72 @@
+import { isoDateTimeSchema, replyToSchema, schemaVersionSchema } from "./common.mjs";
+import { externalSessionSchema, storedSessionSchema } from "./stored-session.mjs";
+import { changeSchema } from "./change.mjs";
+import { storedTaskSchema } from "./stored-task.mjs";
+import { z } from "zod";
+//#region src/schema/catalog.ts
+const shardSchema = z.string().regex(/^[0-9a-f]$/u);
+const sourceVersionSchema = z.number().int().positive();
+const repairSchema = z.strictObject({
+	id: z.string().min(1),
+	sourceVersion: sourceVersionSchema
+});
+/** Validates one fixed shard of the recoverable Task discovery index. */
+const taskCatalogSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: z.templateLiteral(["tasks-", shardSchema]),
+	entries: z.array(z.strictObject({
+		sourceVersion: sourceVersionSchema,
+		value: storedTaskSchema
+	})),
+	repairs: z.array(repairSchema).default([]),
+	updatedAt: isoDateTimeSchema
+});
+/** Validates one fixed shard of the recoverable Change discovery index. */
+const changeCatalogSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: z.templateLiteral(["changes-", shardSchema]),
+	entries: z.array(z.strictObject({
+		sourceVersion: sourceVersionSchema,
+		value: changeSchema
+	})),
+	repairs: z.array(repairSchema).default([]),
+	updatedAt: isoDateTimeSchema
+});
+/** Validates one fixed shard of the recoverable operator-session discovery index. */
+const sessionCatalogSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: z.templateLiteral(["sessions-", shardSchema]),
+	entries: z.array(z.strictObject({
+		sourceVersion: sourceVersionSchema,
+		value: storedSessionSchema
+	})),
+	repairs: z.array(repairSchema).default([]),
+	updatedAt: isoDateTimeSchema
+});
+/** Validates one fixed shard of the external-conversation discovery index. */
+const externalSessionCatalogSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: z.templateLiteral(["external-sessions-", shardSchema]),
+	entries: z.array(z.strictObject({
+		sourceVersion: sourceVersionSchema,
+		value: externalSessionSchema
+	})),
+	repairs: z.array(repairSchema).default([]),
+	updatedAt: isoDateTimeSchema
+});
+/** Validates the directly addressed Task index for one reply destination. */
+const taskRouteSchema = z.strictObject({
+	schemaVersion: schemaVersionSchema,
+	id: z.string().regex(/^task-route_[a-z0-9]{6,64}$/u),
+	replyTo: replyToSchema,
+	entries: z.array(z.strictObject({
+		sourceVersion: sourceVersionSchema,
+		value: storedTaskSchema
+	})),
+	repairs: z.array(repairSchema).default([]),
+	updatedAt: isoDateTimeSchema
+});
+//#endregion
+export { changeCatalogSchema, externalSessionCatalogSchema, sessionCatalogSchema, taskCatalogSchema, taskRouteSchema };
+
+//# sourceMappingURL=catalog.mjs.map

package/dist/schema/catalog.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.mjs","names":[],"sources":["../../src/schema/catalog.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { isoDateTimeSchema, replyToSchema, schemaVersionSchema } from \"./common\";\nimport { changeSchema } from \"./change\";\nimport { externalSessionSchema, storedSessionSchema } from \"./stored-session\";\nimport { storedTaskSchema } from \"./stored-task\";\n\nconst shardSchema = z.string().regex(/^[0-9a-f]$/u);\nconst sourceVersionSchema = z.number().int().positive();\nconst repairSchema = z.strictObject({\n  id: z.string().min(1),\n  sourceVersion: sourceVersionSchema,\n});\n\n/** Validates one fixed shard of the recoverable Task discovery index. */\nexport const taskCatalogSchema = z.strictObject({\n  schemaVersion: schemaVersionSchema,\n  id: z.templateLiteral([\"tasks-\", shardSchema]),\n  entries: z.array(z.strictObject({ sourceVersion: sourceVersionSchema, value: storedTaskSchema })),\n  repairs: z.array(repairSchema).default([]),\n  updatedAt: isoDateTimeSchema,\n});\n\n/** Validates one fixed shard of the recoverable Change discovery index. */\nexport const changeCatalogSchema = z.strictObject({\n  schemaVersion: schemaVersionSchema,\n  id: z.templateLiteral([\"changes-\", shardSchema]),\n  entries: z.array(z.strictObject({ sourceVersion: sourceVersionSchema, value: changeSchema })),\n  repairs: z.array(repairSchema).default([]),\n  updatedAt: isoDateTimeSchema,\n});\n\n/** Validates one fixed shard of the recoverable operator-session discovery index. */\nexport const sessionCatalogSchema = z.strictObject({\n  schemaVersion: schemaVersionSchema,\n  id: z.templateLiteral([\"sessions-\", shardSchema]),\n  entries: z.array(\n    z.strictObject({ sourceVersion: sourceVersionSchema, value: storedSessionSchema }),\n  ),\n  repairs: z.array(repairSchema).default([]),\n  updatedAt: isoDateTimeSchema,\n});\n\n/** Validates one fixed shard of the external-conversation discovery index. */\nexport const externalSessionCatalogSchema = z.strictObject({\n  schemaVersion: schemaVersionSchema,\n  id: z.templateLiteral([\"external-sessions-\", shardSchema]),\n  entries: z.array(\n    z.strictObject({ sourceVersion: sourceVersionSchema, value: externalSessionSchema }),\n  ),\n  repairs: z.array(repairSchema).default([]),\n  updatedAt: isoDateTimeSchema,\n});\n\n/** Validates the directly addressed Task index for one reply destination. */\nexport const taskRouteSchema = z.strictObject({\n  schemaVersion: schemaVersionSchema,\n  id: z.string().regex(/^task-route_[a-z0-9]{6,64}$/u),\n  replyTo: replyToSchema,\n  entries: z.array(z.strictObject({ sourceVersion: sourceVersionSchema, value: storedTaskSchema })),\n  repairs: z.array(repairSchema).default([]),\n  updatedAt: isoDateTimeSchema,\n});\n"],"mappings":";;;;;;AAMA,MAAM,cAAc,EAAE,OAAO,CAAC,CAAC,MAAM,aAAa;AAClD,MAAM,sBAAsB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS;AACtD,MAAM,eAAe,EAAE,aAAa;CAClC,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;CACpB,eAAe;AACjB,CAAC;;AAGD,MAAa,oBAAoB,EAAE,aAAa;CAC9C,eAAe;CACf,IAAI,EAAE,gBAAgB,CAAC,UAAU,WAAW,CAAC;CAC7C,SAAS,EAAE,MAAM,EAAE,aAAa;EAAE,eAAe;EAAqB,OAAO;CAAiB,CAAC,CAAC;CAChG,SAAS,EAAE,MAAM,YAAY,CAAC,CAAC,QAAQ,CAAC,CAAC;CACzC,WAAW;AACb,CAAC;;AAGD,MAAa,sBAAsB,EAAE,aAAa;CAChD,eAAe;CACf,IAAI,EAAE,gBAAgB,CAAC,YAAY,WAAW,CAAC;CAC/C,SAAS,EAAE,MAAM,EAAE,aAAa;EAAE,eAAe;EAAqB,OAAO;CAAa,CAAC,CAAC;CAC5F,SAAS,EAAE,MAAM,YAAY,CAAC,CAAC,QAAQ,CAAC,CAAC;CACzC,WAAW;AACb,CAAC;;AAGD,MAAa,uBAAuB,EAAE,aAAa;CACjD,eAAe;CACf,IAAI,EAAE,gBAAgB,CAAC,aAAa,WAAW,CAAC;CAChD,SAAS,EAAE,MACT,EAAE,aAAa;EAAE,eAAe;EAAqB,OAAO;CAAoB,CAAC,CACnF;CACA,SAAS,EAAE,MAAM,YAAY,CAAC,CAAC,QAAQ,CAAC,CAAC;CACzC,WAAW;AACb,CAAC;;AAGD,MAAa,+BAA+B,EAAE,aAAa;CACzD,eAAe;CACf,IAAI,EAAE,gBAAgB,CAAC,sBAAsB,WAAW,CAAC;CACzD,SAAS,EAAE,MACT,EAAE,aAAa;EAAE,eAAe;EAAqB,OAAO;CAAsB,CAAC,CACrF;CACA,SAAS,EAAE,MAAM,YAAY,CAAC,CAAC,QAAQ,CAAC,CAAC;CACzC,WAAW;AACb,CAAC;;AAGD,MAAa,kBAAkB,EAAE,aAAa;CAC5C,eAAe;CACf,IAAI,EAAE,OAAO,CAAC,CAAC,MAAM,8BAA8B;CACnD,SAAS;CACT,SAAS,EAAE,MAAM,EAAE,aAAa;EAAE,eAAe;EAAqB,OAAO;CAAiB,CAAC,CAAC;CAChG,SAAS,EAAE,MAAM,YAAY,CAAC,CAAC,QAAQ,CAAC,CAAC;CACzC,WAAW;AACb,CAAC"}

package/dist/schema/change.d.mts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+//#region src/schema/change.d.ts
+/** Validates the shared ordinal scale used for risk and confidence. */
+declare const changeLevelSchema: z.ZodEnum<{
+  low: "low";
+  medium: "medium";
+  high: "high";
+}>;
+/** Validates the durable lifecycle state of a pull-request Change. */
+declare const changeStateSchema: z.ZodEnum<{
+  verifying: "verifying";
+  ready: "ready";
+  merged: "merged";
+  deployed: "deployed";
+  rolled_out: "rolled_out";
+  rolled_back: "rolled_back";
+  closed: "closed";
+}>;
+/** Validates the verification evidence used to assess a Change. */
+declare const changeEvidenceSchema: z.ZodObject<{
+  reproVerified: z.ZodBoolean;
+  testsAdded: z.ZodNumber;
+  checksGreen: z.ZodBoolean;
+  attackPassed: z.ZodBoolean;
+  scopeMatches: z.ZodBoolean;
+  previewUrl: z.ZodOptional<z.ZodURL>;
+}, z.core.$strict>;
+/** Validates a persisted human-visible pull-request Change and its trust evidence. */
+declare const changeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  state: z.ZodEnum<{
+    verifying: "verifying";
+    ready: "ready";
+    closed: "closed";
+  }>;
+  decidedBy: z.ZodOptional<z.ZodString>;
+  schemaVersion: z.ZodLiteral<1>;
+  id: z.ZodType<`chg_${string}`, string, z.core.$ZodTypeInternals<`chg_${string}`, string>>;
+  repositoryId: z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>;
+  taskId: z.ZodOptional<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>;
+  groupId: z.ZodOptional<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>;
+  prNumber: z.ZodNumber;
+  prUrl: z.ZodURL;
+  author: z.ZodString;
+  risk: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+  }>;
+  confidence: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+  }>;
+  evidence: z.ZodObject<{
+    reproVerified: z.ZodBoolean;
+    testsAdded: z.ZodNumber;
+    checksGreen: z.ZodBoolean;
+    attackPassed: z.ZodBoolean;
+    scopeMatches: z.ZodBoolean;
+    previewUrl: z.ZodOptional<z.ZodURL>;
+  }, z.core.$strict>;
+  mergeSha: z.ZodOptional<z.ZodString>;
+  createdAt: z.ZodISODateTime;
+  updatedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+  state: z.ZodEnum<{
+    merged: "merged";
+    deployed: "deployed";
+    rolled_out: "rolled_out";
+    rolled_back: "rolled_back";
+  }>;
+  decidedBy: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  id: z.ZodType<`chg_${string}`, string, z.core.$ZodTypeInternals<`chg_${string}`, string>>;
+  repositoryId: z.ZodType<`repo_${string}`, string, z.core.$ZodTypeInternals<`repo_${string}`, string>>;
+  taskId: z.ZodOptional<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>;
+  groupId: z.ZodOptional<z.ZodType<`task_${string}`, string, z.core.$ZodTypeInternals<`task_${string}`, string>>>;
+  prNumber: z.ZodNumber;
+  prUrl: z.ZodURL;
+  author: z.ZodString;
+  risk: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+  }>;
+  confidence: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+  }>;
+  evidence: z.ZodObject<{
+    reproVerified: z.ZodBoolean;
+    testsAdded: z.ZodNumber;
+    checksGreen: z.ZodBoolean;
+    attackPassed: z.ZodBoolean;
+    scopeMatches: z.ZodBoolean;
+    previewUrl: z.ZodOptional<z.ZodURL>;
+  }, z.core.$strict>;
+  mergeSha: z.ZodOptional<z.ZodString>;
+  createdAt: z.ZodISODateTime;
+  updatedAt: z.ZodISODateTime;
+}, z.core.$strict>], "state">;
+/** Shared low-to-high ordinal value used for risk and confidence. */
+type ChangeLevel = z.infer<typeof changeLevelSchema>;
+/** Durable lifecycle state of a human-visible pull-request Change. */
+type ChangeState = z.infer<typeof changeStateSchema>;
+/** Verification facts supporting the risk and confidence assigned to a Change. */
+type ChangeEvidence = z.infer<typeof changeEvidenceSchema>;
+/** Persisted pull-request Change tracked independently from the Tasks that produced it. */
+type Change = z.infer<typeof changeSchema>;
+/** Change read model narrowed to one exact lifecycle state. */
+type ChangeInState<State extends ChangeState> = Change & {
+  readonly state: State;
+};
+//#endregion
+export { Change, ChangeEvidence, ChangeInState, ChangeLevel, ChangeState, changeEvidenceSchema, changeLevelSchema, changeSchema, changeStateSchema };
+//# sourceMappingURL=change.d.mts.map