@vercel/factory 0.0.14 → 0.0.16

package/dist/schema/work.d.mts

@@ -0,0 +1,150 @@
+import { AgentRouteBinding } from "./agent-route.mjs";
+import { z } from "zod";
+//#region src/schema/work.d.ts
+/** Finite JSON data accepted at persisted workflow boundaries. */
+type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+  readonly [key: string]: JsonValue;
+};
+declare const workflowInputType: unique symbol;
+declare const workflowOutputType: unique symbol;
+/** Exact workflow identity carrying its input and output types for safe construction. */
+type WorkflowBinding<Input extends JsonValue = JsonValue, Output extends JsonValue = JsonValue, Id extends string = string, Version extends number = number> = z.infer<typeof workflowBindingSchema> & {
+  readonly id: Id;
+  readonly version: Version;
+  readonly [workflowInputType]?: Input;
+  readonly [workflowOutputType]?: Output;
+};
+/** Definition-like value exposing an exact typed workflow binding. */
+interface WorkflowReference<InputSchema extends z.ZodType = z.ZodType, Binding extends WorkflowBinding = WorkflowBinding> {
+  readonly binding: Binding;
+  readonly input: InputSchema;
+}
+/** Input type carried by a definition-like workflow reference. */
+type WorkflowReferenceInput<Reference extends WorkflowReference> = z.input<Reference["input"]> & JsonValue;
+/** Maximum serialized UTF-8 size of workflow input, output, or message JSON. */
+declare const MAX_WORK_JSON_BYTES: number;
+/** Maximum nesting depth below the root of persisted workflow JSON. */
+declare const MAX_WORK_JSON_DEPTH = 32;
+/** Validates bounded canonical JSON without cycles, accessors, or sparse arrays. */
+declare const jsonValueSchema: z.ZodCustom<JsonValue, JsonValue>;
+/** Validates an exact workflow identifier and positive integer version. */
+declare const workflowBindingSchema: z.core.$ZodBranded<z.ZodObject<{
+  id: z.ZodString;
+  version: z.ZodNumber;
+}, z.core.$strict>, "WorkflowBinding", "out">;
+/** Plain identifier and version accepted when constructing a workflow binding. */
+interface WorkflowBindingInput<Id extends string = string, Version extends number = number> {
+  readonly id: Id;
+  readonly version: Version;
+}
+/** Validates and brands an exact workflow binding while preserving literal identity. */
+declare function parseWorkflowBinding<const Input extends WorkflowBindingInput>(input: Input): WorkflowBinding<JsonValue, JsonValue, Input["id"], Input["version"]>;
+/** Validates the required versioned input and completion contract for a Task. */
+declare const taskWorkSchema: z.ZodObject<{
+  title: z.ZodString;
+  input: z.ZodCustom<JsonValue, JsonValue>;
+  completionCriteria: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+  workflow: z.core.$ZodBranded<z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+  }, z.core.$strict>, "WorkflowBinding", "out">;
+  route: z.ZodOptional<z.core.$ZodBranded<z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodNumber;
+  }, z.core.$strict>, "AgentRouteBinding", "out">>;
+}, z.core.$strict>;
+/** Validates canonical output recorded when workflow work completes. */
+declare const taskWorkResultSchema: z.ZodObject<{
+  output: z.ZodCustom<JsonValue, JsonValue>;
+  completedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+/** Required title, typed input, criteria, workflow, and optional route contract of a Task. */
+interface TaskWork<Input extends JsonValue = JsonValue, Workflow extends WorkflowBinding = WorkflowBinding> {
+  /** Short operator-facing description of the requested work. */
+  readonly title: string;
+  /** Canonical bounded JSON validated by the exact registered workflow before persistence. */
+  readonly input: Input;
+  /** Explicit acceptance statements interpreted by workflow or agent policy. */
+  readonly completionCriteria: readonly string[];
+  /** Exact workflow ID and version that validate this Task's input and output. */
+  readonly workflow: Workflow;
+  /** Exact agent route to dispatch, or absent when workflow code owns execution. */
+  readonly route?: AgentRouteBinding;
+}
+/** Validated canonical output and completion timestamp of succeeded workflow work. */
+type TaskWorkResult = z.infer<typeof taskWorkResultSchema>;
+/** Named fields for constructing generic `task@1` work. */
+interface TaskWorkOptions<Input extends JsonValue = JsonValue> {
+  /** Short operator-facing description, trimmed and limited to 256 characters. */
+  readonly title: string;
+  /** Bounded JSON input. Defaults to an empty object. */
+  readonly input?: Input;
+  /** Generic work always selects `task@1`; use `WorkflowTaskWorkOptions` for custom workflows. */
+  readonly workflow?: never;
+  /** Add an exact agent route after construction or use `routeTaskWork`. */
+  readonly route?: never;
+  /** Generic work starts with no explicit criteria. */
+  readonly completionCriteria?: never;
+}
+/** Named fields for constructing work owned by an exact workflow contract. */
+interface WorkflowTaskWorkOptions<Input extends JsonValue = JsonValue, Workflow extends WorkflowBinding | WorkflowReference = WorkflowBinding | WorkflowReference> {
+  /** Short operator-facing description, trimmed and limited to 256 characters. */
+  readonly title: string;
+  /** Input statically checked against the referenced workflow and validated again by the engine. */
+  readonly input: Input;
+  /** Exact typed workflow definition or binding; no implicit latest version is selected. */
+  readonly workflow: Workflow;
+  /** Add an exact agent route after construction or use `routeTaskWork`. */
+  readonly route?: never;
+  /** Workflow policy owns acceptance criteria; this helper starts with an empty list. */
+  readonly completionCriteria?: never;
+}
+/**
+ * Constructs generic `task@1` work with an empty completion-criteria list.
+ *
+ * @remarks
+ * This helper constructs the persisted work envelope; it does not create or dispatch a Task.
+ * Supplying a workflow definition or typed binding preserves its input/output relationship for
+ * later `stores.work.completeWorkflow` calls. The store engine performs authoritative runtime
+ * validation against its registered exact workflow version.
+ *
+ * @param options - Named title and optional bounded JSON input for generic `task@1` work.
+ * @returns A new work envelope selecting the generic `task@1` workflow.
+ * @throws A Zod validation error when the title, input, or workflow binding is invalid.
+ *
+ * @example
+ * ```ts
+ * import { taskWork } from "@vercel/factory/workflows";
+ *
+ * const work = taskWork({
+ *   title: "Summarize the incident",
+ *   input: { incidentId: "inc_123" },
+ * });
+ * ```
+ */
+declare function taskWork<const Input extends JsonValue = JsonValue>(options: TaskWorkOptions<Input>): TaskWork<Input>;
+/**
+ * Constructs work from a workflow definition while preserving its exact typed binding.
+ *
+ * @param options - Named title, workflow definition, and input accepted by that definition.
+ * @returns A new work envelope carrying the definition's exact workflow binding.
+ * @throws A Zod validation error when the title, input envelope, or workflow binding is invalid.
+ */
+declare function taskWork<InputSchema extends z.ZodType, Binding extends WorkflowBinding>(options: WorkflowTaskWorkOptions<NoInfer<z.input<InputSchema>> & JsonValue, {
+  readonly input: InputSchema;
+  readonly binding: Binding;
+}>): TaskWork<z.input<InputSchema> & JsonValue, Binding>;
+/**
+ * Constructs work from an exact typed workflow binding.
+ *
+ * @param options - Named title, exact binding, and input carried by that binding.
+ * @returns A new work envelope carrying the supplied exact workflow binding.
+ * @throws A Zod validation error when the title, input envelope, or workflow binding is invalid.
+ */
+declare function taskWork<Input extends JsonValue, Output extends JsonValue, const Id extends string, const Version extends number>(options: WorkflowTaskWorkOptions<NoInfer<Input>, WorkflowBinding<Input, Output, Id, Version> & {
+  readonly binding?: never;
+  readonly input?: never;
+}>): TaskWork<Input, WorkflowBinding<Input, Output, Id, Version>>;
+//#endregion
+export { JsonValue, MAX_WORK_JSON_BYTES, MAX_WORK_JSON_DEPTH, TaskWork, TaskWorkOptions, TaskWorkResult, WorkflowBinding, WorkflowBindingInput, WorkflowReference, WorkflowReferenceInput, WorkflowTaskWorkOptions, jsonValueSchema, parseWorkflowBinding, taskWork, taskWorkResultSchema, taskWorkSchema, workflowBindingSchema };
+//# sourceMappingURL=work.d.mts.map

package/dist/schema/work.mjs

@@ -0,0 +1,102 @@
+import { isoDateTimeSchema } from "./common.mjs";
+import { agentRouteBindingSchema } from "./agent-route.mjs";
+import { z } from "zod";
+//#region src/schema/work.ts
+/** Maximum serialized UTF-8 size of workflow input, output, or message JSON. */
+const MAX_WORK_JSON_BYTES = 65536;
+/** Maximum nesting depth below the root of persisted workflow JSON. */
+const MAX_WORK_JSON_DEPTH = 32;
+const encoder = new TextEncoder();
+function isBoundedJson(value) {
+	let bytes = 0;
+	const ancestors = /* @__PURE__ */ new Set();
+	const addBytes = (count) => {
+		bytes += count;
+		return bytes <= MAX_WORK_JSON_BYTES;
+	};
+	const stringFits = (text) => text.length <= 65536 && addBytes(encoder.encode(JSON.stringify(text)).byteLength);
+	const visit = (entry, depth) => {
+		if (depth > 32) return false;
+		if (entry === null) return addBytes(4);
+		if (typeof entry === "boolean") return addBytes(entry ? 4 : 5);
+		if (typeof entry === "string") return stringFits(entry);
+		if (typeof entry === "number") return Number.isFinite(entry) && addBytes(JSON.stringify(entry).length);
+		if (typeof entry !== "object" || ancestors.has(entry)) return false;
+		const array = Array.isArray(entry);
+		const prototype = Object.getPrototypeOf(entry);
+		if (array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null) return false;
+		if (!addBytes(2)) return false;
+		ancestors.add(entry);
+		const keys = Reflect.ownKeys(entry);
+		if (array) {
+			if (entry.length > 65536 || keys.length !== entry.length + 1) return false;
+			for (let index = 0; index < entry.length; index++) {
+				const descriptor = Object.getOwnPropertyDescriptor(entry, String(index));
+				if (!descriptor || !descriptor.enumerable || !("value" in descriptor)) return false;
+				if (index > 0 && !addBytes(1)) return false;
+				if (!visit(descriptor.value, depth + 1)) return false;
+			}
+		} else for (const [index, key] of keys.entries()) {
+			if (typeof key !== "string") return false;
+			const descriptor = Object.getOwnPropertyDescriptor(entry, key);
+			if (!descriptor || !descriptor.enumerable || !("value" in descriptor)) return false;
+			if (index > 0 && !addBytes(1)) return false;
+			if (!stringFits(key) || !addBytes(1) || !visit(descriptor.value, depth + 1)) return false;
+		}
+		ancestors.delete(entry);
+		return true;
+	};
+	try {
+		return visit(value, 0);
+	} catch {
+		return false;
+	}
+}
+/** Validates bounded canonical JSON without cycles, accessors, or sparse arrays. */
+const jsonValueSchema = z.custom(isBoundedJson, { message: `Expected finite JSON with at most ${MAX_WORK_JSON_BYTES} UTF-8 bytes and depth 32; cycles, accessors, sparse arrays, and non-JSON properties are not allowed` }).describe("Finite JSON value, at most 64 KiB serialized UTF-8 and 32 levels below the root.");
+/** Validates an exact workflow identifier and positive integer version. */
+const workflowBindingSchema = z.strictObject({
+	id: z.string().max(64).regex(/^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/, "Expected a lowercase hyphenated or snake_case workflow name").describe("Registered workflow name, starting with a lowercase letter; at most 64 characters."),
+	version: z.number().int().positive().describe("Exact positive integer version of the registered workflow.")
+}).describe("Explicit workflow identity and version; never resolved to an implicit latest version.").brand();
+/** Validates and brands an exact workflow binding while preserving literal identity. */
+function parseWorkflowBinding(input) {
+	return workflowBindingSchema.parse(input);
+}
+/** Validates the required versioned input and completion contract for a Task. */
+const taskWorkSchema = z.strictObject({
+	title: z.string().trim().min(1).max(256).describe("Short work title, from 1 to 256 characters."),
+	input: jsonValueSchema.describe("Bounded JSON input to validate against the registered workflow input schema."),
+	completionCriteria: z.array(z.string().trim().min(1).max(2048).describe("One completion criterion, from 1 to 2048 characters.")).max(32).readonly().describe("Up to 32 explicit completion criteria; workflow code determines completion."),
+	workflow: workflowBindingSchema.describe("Exact registered workflow contract that owns this work."),
+	route: agentRouteBindingSchema.optional().describe("Exact agent execution route selected by the workflow; absent for work not dispatched to an agent.")
+}).describe("Required versioned work contract; registered workflow validation is owned by the engine.");
+/** Validates canonical output recorded when workflow work completes. */
+const taskWorkResultSchema = z.strictObject({
+	output: jsonValueSchema.describe("Canonical bounded JSON output, validated by the engine against the stored workflow output schema."),
+	completedAt: isoDateTimeSchema.describe("Engine timestamp when the workflow result was completed.")
+}).describe("Completed result of workflow work; registered output validation is owned by the engine.");
+function taskWork(options) {
+	const { title, input = {} } = options;
+	const workflow = options.workflow ?? parseWorkflowBinding({
+		id: "task",
+		version: 1
+	});
+	const binding = "binding" in workflow ? workflow.binding : workflow;
+	const parsed = taskWorkSchema.parse({
+		title,
+		input,
+		workflow: binding,
+		completionCriteria: []
+	});
+	return structuredClone({
+		title: parsed.title,
+		input,
+		workflow: binding,
+		completionCriteria: []
+	});
+}
+//#endregion
+export { MAX_WORK_JSON_BYTES, MAX_WORK_JSON_DEPTH, jsonValueSchema, parseWorkflowBinding, taskWork, taskWorkResultSchema, taskWorkSchema, workflowBindingSchema };
+
+//# sourceMappingURL=work.mjs.map

package/dist/schema/work.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"work.mjs","names":[],"sources":["../../src/schema/work.ts"],"sourcesContent":["import { z } from \"zod\";\nimport { agentRouteBindingSchema, type AgentRouteBinding } from \"./agent-route\";\nimport { isoDateTimeSchema } from \"./common\";\n\n/** Finite JSON data accepted at persisted workflow boundaries. */\nexport type JsonValue =\n  | null\n  | boolean\n  | number\n  | string\n  | readonly JsonValue[]\n  | { readonly [key: string]: JsonValue };\n\ndeclare const workflowInputType: unique symbol;\ndeclare const workflowOutputType: unique symbol;\n\n/** Exact workflow identity carrying its input and output types for safe construction. */\nexport type WorkflowBinding<\n  Input extends JsonValue = JsonValue,\n  Output extends JsonValue = JsonValue,\n  Id extends string = string,\n  Version extends number = number,\n> = z.infer<typeof workflowBindingSchema> & {\n  readonly id: Id;\n  readonly version: Version;\n  readonly [workflowInputType]?: Input;\n  readonly [workflowOutputType]?: Output;\n};\n\n/** Definition-like value exposing an exact typed workflow binding. */\nexport interface WorkflowReference<\n  InputSchema extends z.ZodType = z.ZodType,\n  Binding extends WorkflowBinding = WorkflowBinding,\n> {\n  readonly binding: Binding;\n  readonly input: InputSchema;\n}\n\n/** Input type carried by a definition-like workflow reference. */\nexport type WorkflowReferenceInput<Reference extends WorkflowReference> = z.input<\n  Reference[\"input\"]\n> &\n  JsonValue;\n\n/** Maximum serialized UTF-8 size of workflow input, output, or message JSON. */\nexport const MAX_WORK_JSON_BYTES = 64 * 1024;\n/** Maximum nesting depth below the root of persisted workflow JSON. */\nexport const MAX_WORK_JSON_DEPTH = 32;\n\nconst encoder = new TextEncoder();\n\nfunction isBoundedJson(value: unknown): boolean {\n  let bytes = 0;\n  const ancestors = new Set<object>();\n  const addBytes = (count: number): boolean => {\n    bytes += count;\n    return bytes <= MAX_WORK_JSON_BYTES;\n  };\n  const stringFits = (text: string): boolean =>\n    text.length <= MAX_WORK_JSON_BYTES && addBytes(encoder.encode(JSON.stringify(text)).byteLength);\n\n  const visit = (entry: unknown, depth: number): boolean => {\n    if (depth > MAX_WORK_JSON_DEPTH) return false;\n    if (entry === null) return addBytes(4);\n    if (typeof entry === \"boolean\") return addBytes(entry ? 4 : 5);\n    if (typeof entry === \"string\") return stringFits(entry);\n    if (typeof entry === \"number\") {\n      return Number.isFinite(entry) && addBytes(JSON.stringify(entry).length);\n    }\n    if (typeof entry !== \"object\" || ancestors.has(entry)) return false;\n\n    const array = Array.isArray(entry);\n    const prototype: unknown = Object.getPrototypeOf(entry);\n    if (\n      array ? prototype !== Array.prototype : prototype !== Object.prototype && prototype !== null\n    ) {\n      return false;\n    }\n    if (!addBytes(2)) return false;\n    ancestors.add(entry);\n    const keys = Reflect.ownKeys(entry);\n    if (array) {\n      if (entry.length > MAX_WORK_JSON_BYTES || keys.length !== entry.length + 1) return false;\n      for (let index = 0; index < entry.length; index++) {\n        const descriptor = Object.getOwnPropertyDescriptor(entry, String(index));\n        if (!descriptor || !descriptor.enumerable || !(\"value\" in descriptor)) return false;\n        if (index > 0 && !addBytes(1)) return false;\n        if (!visit(descriptor.value, depth + 1)) return false;\n      }\n    } else {\n      for (const [index, key] of keys.entries()) {\n        if (typeof key !== \"string\") return false;\n        const descriptor = Object.getOwnPropertyDescriptor(entry, key);\n        if (!descriptor || !descriptor.enumerable || !(\"value\" in descriptor)) return false;\n        if (index > 0 && !addBytes(1)) return false;\n        if (!stringFits(key) || !addBytes(1) || !visit(descriptor.value, depth + 1)) return false;\n      }\n    }\n    ancestors.delete(entry);\n    return true;\n  };\n\n  try {\n    return visit(value, 0);\n  } catch {\n    return false;\n  }\n}\n\n/** Validates bounded canonical JSON without cycles, accessors, or sparse arrays. */\nexport const jsonValueSchema = z\n  .custom<JsonValue>(isBoundedJson, {\n    message: `Expected finite JSON with at most ${MAX_WORK_JSON_BYTES} UTF-8 bytes and depth ${MAX_WORK_JSON_DEPTH}; cycles, accessors, sparse arrays, and non-JSON properties are not allowed`,\n  })\n  .describe(\"Finite JSON value, at most 64 KiB serialized UTF-8 and 32 levels below the root.\");\n\n/** Validates an exact workflow identifier and positive integer version. */\nexport const workflowBindingSchema = z\n  .strictObject({\n    id: z\n      .string()\n      .max(64)\n      .regex(\n        /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/,\n        \"Expected a lowercase hyphenated or snake_case workflow name\",\n      )\n      .describe(\n        \"Registered workflow name, starting with a lowercase letter; at most 64 characters.\",\n      ),\n    version: z\n      .number()\n      .int()\n      .positive()\n      .describe(\"Exact positive integer version of the registered workflow.\"),\n  })\n  .describe(\"Explicit workflow identity and version; never resolved to an implicit latest version.\")\n  .brand<\"WorkflowBinding\">();\n\n/** Plain identifier and version accepted when constructing a workflow binding. */\nexport interface WorkflowBindingInput<Id extends string = string, Version extends number = number> {\n  readonly id: Id;\n  readonly version: Version;\n}\n\n/** Validates and brands an exact workflow binding while preserving literal identity. */\nexport function parseWorkflowBinding<const Input extends WorkflowBindingInput>(\n  input: Input,\n): WorkflowBinding<JsonValue, JsonValue, Input[\"id\"], Input[\"version\"]> {\n  return workflowBindingSchema.parse(input) as WorkflowBinding<\n    JsonValue,\n    JsonValue,\n    Input[\"id\"],\n    Input[\"version\"]\n  >;\n}\n\n/** Validates the required versioned input and completion contract for a Task. */\nexport const taskWorkSchema = z\n  .strictObject({\n    title: z\n      .string()\n      .trim()\n      .min(1)\n      .max(256)\n      .describe(\"Short work title, from 1 to 256 characters.\"),\n    input: jsonValueSchema.describe(\n      \"Bounded JSON input to validate against the registered workflow input schema.\",\n    ),\n    completionCriteria: z\n      .array(\n        z\n          .string()\n          .trim()\n          .min(1)\n          .max(2048)\n          .describe(\"One completion criterion, from 1 to 2048 characters.\"),\n      )\n      .max(32)\n      .readonly()\n      .describe(\"Up to 32 explicit completion criteria; workflow code determines completion.\"),\n    workflow: workflowBindingSchema.describe(\n      \"Exact registered workflow contract that owns this work.\",\n    ),\n    route: agentRouteBindingSchema\n      .optional()\n      .describe(\n        \"Exact agent execution route selected by the workflow; absent for work not dispatched to an agent.\",\n      ),\n  })\n  .describe(\n    \"Required versioned work contract; registered workflow validation is owned by the engine.\",\n  );\n\n/** Validates canonical output recorded when workflow work completes. */\nexport const taskWorkResultSchema = z\n  .strictObject({\n    output: jsonValueSchema.describe(\n      \"Canonical bounded JSON output, validated by the engine against the stored workflow output schema.\",\n    ),\n    completedAt: isoDateTimeSchema.describe(\n      \"Engine timestamp when the workflow result was completed.\",\n    ),\n  })\n  .describe(\n    \"Completed result of workflow work; registered output validation is owned by the engine.\",\n  );\n\n/** Required title, typed input, criteria, workflow, and optional route contract of a Task. */\nexport interface TaskWork<\n  Input extends JsonValue = JsonValue,\n  Workflow extends WorkflowBinding = WorkflowBinding,\n> {\n  /** Short operator-facing description of the requested work. */\n  readonly title: string;\n  /** Canonical bounded JSON validated by the exact registered workflow before persistence. */\n  readonly input: Input;\n  /** Explicit acceptance statements interpreted by workflow or agent policy. */\n  readonly completionCriteria: readonly string[];\n  /** Exact workflow ID and version that validate this Task's input and output. */\n  readonly workflow: Workflow;\n  /** Exact agent route to dispatch, or absent when workflow code owns execution. */\n  readonly route?: AgentRouteBinding;\n}\n/** Validated canonical output and completion timestamp of succeeded workflow work. */\nexport type TaskWorkResult = z.infer<typeof taskWorkResultSchema>;\n\n/** Named fields for constructing generic `task@1` work. */\nexport interface TaskWorkOptions<Input extends JsonValue = JsonValue> {\n  /** Short operator-facing description, trimmed and limited to 256 characters. */\n  readonly title: string;\n  /** Bounded JSON input. Defaults to an empty object. */\n  readonly input?: Input;\n  /** Generic work always selects `task@1`; use `WorkflowTaskWorkOptions` for custom workflows. */\n  readonly workflow?: never;\n  /** Add an exact agent route after construction or use `routeTaskWork`. */\n  readonly route?: never;\n  /** Generic work starts with no explicit criteria. */\n  readonly completionCriteria?: never;\n}\n\n/** Named fields for constructing work owned by an exact workflow contract. */\nexport interface WorkflowTaskWorkOptions<\n  Input extends JsonValue = JsonValue,\n  Workflow extends WorkflowBinding | WorkflowReference = WorkflowBinding | WorkflowReference,\n> {\n  /** Short operator-facing description, trimmed and limited to 256 characters. */\n  readonly title: string;\n  /** Input statically checked against the referenced workflow and validated again by the engine. */\n  readonly input: Input;\n  /** Exact typed workflow definition or binding; no implicit latest version is selected. */\n  readonly workflow: Workflow;\n  /** Add an exact agent route after construction or use `routeTaskWork`. */\n  readonly route?: never;\n  /** Workflow policy owns acceptance criteria; this helper starts with an empty list. */\n  readonly completionCriteria?: never;\n}\n\n/**\n * Constructs generic `task@1` work with an empty completion-criteria list.\n *\n * @remarks\n * This helper constructs the persisted work envelope; it does not create or dispatch a Task.\n * Supplying a workflow definition or typed binding preserves its input/output relationship for\n * later `stores.work.completeWorkflow` calls. The store engine performs authoritative runtime\n * validation against its registered exact workflow version.\n *\n * @param options - Named title and optional bounded JSON input for generic `task@1` work.\n * @returns A new work envelope selecting the generic `task@1` workflow.\n * @throws A Zod validation error when the title, input, or workflow binding is invalid.\n *\n * @example\n * ```ts\n * import { taskWork } from \"@vercel/factory/workflows\";\n *\n * const work = taskWork({\n *   title: \"Summarize the incident\",\n *   input: { incidentId: \"inc_123\" },\n * });\n * ```\n */\nexport function taskWork<const Input extends JsonValue = JsonValue>(\n  options: TaskWorkOptions<Input>,\n): TaskWork<Input>;\n/**\n * Constructs work from a workflow definition while preserving its exact typed binding.\n *\n * @param options - Named title, workflow definition, and input accepted by that definition.\n * @returns A new work envelope carrying the definition's exact workflow binding.\n * @throws A Zod validation error when the title, input envelope, or workflow binding is invalid.\n */\nexport function taskWork<InputSchema extends z.ZodType, Binding extends WorkflowBinding>(\n  options: WorkflowTaskWorkOptions<\n    NoInfer<z.input<InputSchema>> & JsonValue,\n    { readonly input: InputSchema; readonly binding: Binding }\n  >,\n): TaskWork<z.input<InputSchema> & JsonValue, Binding>;\n/**\n * Constructs work from an exact typed workflow binding.\n *\n * @param options - Named title, exact binding, and input carried by that binding.\n * @returns A new work envelope carrying the supplied exact workflow binding.\n * @throws A Zod validation error when the title, input envelope, or workflow binding is invalid.\n */\nexport function taskWork<\n  Input extends JsonValue,\n  Output extends JsonValue,\n  const Id extends string,\n  const Version extends number,\n>(\n  options: WorkflowTaskWorkOptions<\n    NoInfer<Input>,\n    WorkflowBinding<Input, Output, Id, Version> & {\n      readonly binding?: never;\n      readonly input?: never;\n    }\n  >,\n): TaskWork<Input, WorkflowBinding<Input, Output, Id, Version>>;\nexport function taskWork(options: TaskWorkOptions | WorkflowTaskWorkOptions): TaskWork {\n  const { title, input = {} } = options;\n  const workflow =\n    options.workflow ??\n    parseWorkflowBinding({\n      id: \"task\",\n      version: 1,\n    });\n  const binding = \"binding\" in workflow ? workflow.binding : workflow;\n  const parsed = taskWorkSchema.parse({ title, input, workflow: binding, completionCriteria: [] });\n  return structuredClone({\n    title: parsed.title,\n    input,\n    workflow: binding,\n    completionCriteria: [],\n  });\n}\n"],"mappings":"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"}

package/dist/session-previews.d.mts

@@ -0,0 +1,76 @@
+import { z } from "zod";
+//#region src/session-previews.d.ts
+/** Validates an application-supplied preview page with explicit availability and expiry. */
+declare const sessionPreviewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  status: z.ZodEnum<{
+    unknown: "unknown";
+    ready: "ready";
+  }>;
+  url: z.ZodString;
+  id: z.ZodString;
+  title: z.ZodString;
+  instructions: z.ZodOptional<z.ZodString>;
+  source: z.ZodString;
+  revision: z.ZodNullable<z.ZodString>;
+  expiresAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>, z.ZodObject<{
+  status: z.ZodEnum<{
+    unavailable: "unavailable";
+    starting: "starting";
+    expired: "expired";
+  }>;
+  reason: z.ZodString;
+  id: z.ZodString;
+  title: z.ZodString;
+  instructions: z.ZodOptional<z.ZodString>;
+  source: z.ZodString;
+  revision: z.ZodNullable<z.ZodString>;
+  expiresAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>], "status">;
+/** Validates the optional live-preview projection, including instructions for non-web work. */
+declare const sessionPreviewsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  state: z.ZodLiteral<"ready">;
+  previews: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodEnum<{
+      unknown: "unknown";
+      ready: "ready";
+    }>;
+    url: z.ZodString;
+    id: z.ZodString;
+    title: z.ZodString;
+    instructions: z.ZodOptional<z.ZodString>;
+    source: z.ZodString;
+    revision: z.ZodNullable<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+  }, z.core.$strict>, z.ZodObject<{
+    status: z.ZodEnum<{
+      unavailable: "unavailable";
+      starting: "starting";
+      expired: "expired";
+    }>;
+    reason: z.ZodString;
+    id: z.ZodString;
+    title: z.ZodString;
+    instructions: z.ZodOptional<z.ZodString>;
+    source: z.ZodString;
+    revision: z.ZodNullable<z.ZodString>;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+  }, z.core.$strict>], "status">>>;
+  instructions: z.ZodNullable<z.ZodString>;
+  limitations: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+  truncated: z.ZodBoolean;
+  executionId: z.ZodNullable<z.ZodString>;
+  capturedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+  state: z.ZodLiteral<"unavailable">;
+  reason: z.ZodString;
+  executionId: z.ZodNullable<z.ZodString>;
+  capturedAt: z.ZodISODateTime;
+}, z.core.$strict>], "state">;
+/** One application-owned preview page and its recorded availability. */
+type SessionPreview = z.infer<typeof sessionPreviewSchema>;
+/** Provider-neutral preview pages and practical testing instructions for a session. */
+type SessionPreviews = z.infer<typeof sessionPreviewsSchema>;
+//#endregion
+export { SessionPreview, SessionPreviews, sessionPreviewSchema, sessionPreviewsSchema };
+//# sourceMappingURL=session-previews.d.mts.map

package/dist/session-previews.mjs

@@ -0,0 +1,55 @@
+import { z } from "zod";
+//#region src/session-previews.ts
+const text = z.string().trim().min(1);
+const previewUrl = z.string().refine((value) => {
+	if (!/^https?:\/\//iu.test(value) || /[\s\\]/u.test(value) || [...value].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)) return false;
+	try {
+		const url = new URL(value);
+		return ["https:", "http:"].includes(url.protocol) && !url.username && !url.password;
+	} catch {
+		return false;
+	}
+}, "Use an absolute HTTP(S) preview URL without credentials");
+const page = {
+	id: text.describe("Stable preview identity within this session."),
+	title: text.describe("Page or application to try."),
+	instructions: text.optional().describe("Actions to try and expected results, as Markdown."),
+	source: text.describe("Application-owned origin of the preview."),
+	revision: text.nullable().describe("Exact opaque code revision, or null when not recorded."),
+	expiresAt: z.iso.datetime().optional().describe("Known expiry; absent means not recorded.")
+};
+/** Validates an application-supplied preview page with explicit availability and expiry. */
+const sessionPreviewSchema = z.discriminatedUnion("status", [z.strictObject({
+	...page,
+	status: z.enum(["ready", "unknown"]).describe("Ready as reported by the reader, or unchecked."),
+	url: previewUrl.describe("Browser destination; the application owns access and lifetime.")
+}), z.strictObject({
+	...page,
+	status: z.enum([
+		"starting",
+		"unavailable",
+		"expired"
+	]).describe("Why this preview cannot be opened."),
+	reason: text.describe("Explanation and next steps for the operator.")
+})]);
+const common = {
+	executionId: text.nullable().describe("Observed session execution, or null before execution."),
+	capturedAt: z.iso.datetime().describe("When the preview projection was read.")
+};
+/** Validates the optional live-preview projection, including instructions for non-web work. */
+const sessionPreviewsSchema = z.discriminatedUnion("state", [z.strictObject({
+	...common,
+	state: z.literal("ready").describe("The reader completed; individual pages have their own status."),
+	previews: z.array(sessionPreviewSchema).readonly().describe("Recorded preview pages or applications."),
+	instructions: text.nullable().describe("How to test the work, including local steps when no live site exists."),
+	limitations: z.array(text).readonly().describe("Missing evidence or review limitations."),
+	truncated: z.boolean().describe("Whether the reader omitted entries due to its configured limits.")
+}), z.strictObject({
+	...common,
+	state: z.literal("unavailable").describe("Preview information could not be read."),
+	reason: text.describe("Why preview information is unavailable.")
+})]);
+//#endregion
+export { sessionPreviewSchema, sessionPreviewsSchema };
+
+//# sourceMappingURL=session-previews.mjs.map

package/dist/session-previews.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-previews.mjs","names":[],"sources":["../src/session-previews.ts"],"sourcesContent":["import { z } from \"zod\";\n\nconst text = z.string().trim().min(1);\nconst previewUrl = z.string().refine((value) => {\n  if (\n    !/^https?:\\/\\//iu.test(value) ||\n    /[\\s\\\\]/u.test(value) ||\n    [...value].some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)\n  )\n    return false;\n  try {\n    const url = new URL(value);\n    return [\"https:\", \"http:\"].includes(url.protocol) && !url.username && !url.password;\n  } catch {\n    return false;\n  }\n}, \"Use an absolute HTTP(S) preview URL without credentials\");\nconst page = {\n  id: text.describe(\"Stable preview identity within this session.\"),\n  title: text.describe(\"Page or application to try.\"),\n  instructions: text.optional().describe(\"Actions to try and expected results, as Markdown.\"),\n  source: text.describe(\"Application-owned origin of the preview.\"),\n  revision: text.nullable().describe(\"Exact opaque code revision, or null when not recorded.\"),\n  expiresAt: z.iso.datetime().optional().describe(\"Known expiry; absent means not recorded.\"),\n};\n\n/** Validates an application-supplied preview page with explicit availability and expiry. */\nexport const sessionPreviewSchema = z.discriminatedUnion(\"status\", [\n  z.strictObject({\n    ...page,\n    status: z.enum([\"ready\", \"unknown\"]).describe(\"Ready as reported by the reader, or unchecked.\"),\n    url: previewUrl.describe(\"Browser destination; the application owns access and lifetime.\"),\n  }),\n  z.strictObject({\n    ...page,\n    status: z\n      .enum([\"starting\", \"unavailable\", \"expired\"])\n      .describe(\"Why this preview cannot be opened.\"),\n    reason: text.describe(\"Explanation and next steps for the operator.\"),\n  }),\n]);\n\nconst common = {\n  executionId: text.nullable().describe(\"Observed session execution, or null before execution.\"),\n  capturedAt: z.iso.datetime().describe(\"When the preview projection was read.\"),\n};\n\n/** Validates the optional live-preview projection, including instructions for non-web work. */\nexport const sessionPreviewsSchema = z.discriminatedUnion(\"state\", [\n  z.strictObject({\n    ...common,\n    state: z\n      .literal(\"ready\")\n      .describe(\"The reader completed; individual pages have their own status.\"),\n    previews: z\n      .array(sessionPreviewSchema)\n      .readonly()\n      .describe(\"Recorded preview pages or applications.\"),\n    instructions: text\n      .nullable()\n      .describe(\"How to test the work, including local steps when no live site exists.\"),\n    limitations: z.array(text).readonly().describe(\"Missing evidence or review limitations.\"),\n    truncated: z\n      .boolean()\n      .describe(\"Whether the reader omitted entries due to its configured limits.\"),\n  }),\n  z.strictObject({\n    ...common,\n    state: z.literal(\"unavailable\").describe(\"Preview information could not be read.\"),\n    reason: text.describe(\"Why preview information is unavailable.\"),\n  }),\n]);\n\n/** One application-owned preview page and its recorded availability. */\nexport type SessionPreview = z.infer<typeof sessionPreviewSchema>;\n/** Provider-neutral preview pages and practical testing instructions for a session. */\nexport type SessionPreviews = z.infer<typeof sessionPreviewsSchema>;\n"],"mappings":";;AAEA,MAAM,OAAO,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;AACpC,MAAM,aAAa,EAAE,OAAO,CAAC,CAAC,QAAQ,UAAU;CAC9C,IACE,CAAC,iBAAiB,KAAK,KAAK,KAC5B,UAAU,KAAK,KAAK,KACpB,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,cAAc,UAAU,WAAW,CAAC,IAAI,MAAM,UAAU,WAAW,CAAC,MAAM,GAAG,GAE9F,OAAO;CACT,IAAI;EACF,MAAM,MAAM,IAAI,IAAI,KAAK;EACzB,OAAO,CAAC,UAAU,OAAO,CAAC,CAAC,SAAS,IAAI,QAAQ,KAAK,CAAC,IAAI,YAAY,CAAC,IAAI;CAC7E,QAAQ;EACN,OAAO;CACT;AACF,GAAG,yDAAyD;AAC5D,MAAM,OAAO;CACX,IAAI,KAAK,SAAS,8CAA8C;CAChE,OAAO,KAAK,SAAS,6BAA6B;CAClD,cAAc,KAAK,SAAS,CAAC,CAAC,SAAS,mDAAmD;CAC1F,QAAQ,KAAK,SAAS,0CAA0C;CAChE,UAAU,KAAK,SAAS,CAAC,CAAC,SAAS,wDAAwD;CAC3F,WAAW,EAAE,IAAI,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,0CAA0C;AAC5F;;AAGA,MAAa,uBAAuB,EAAE,mBAAmB,UAAU,CACjE,EAAE,aAAa;CACb,GAAG;CACH,QAAQ,EAAE,KAAK,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,SAAS,gDAAgD;CAC9F,KAAK,WAAW,SAAS,gEAAgE;AAC3F,CAAC,GACD,EAAE,aAAa;CACb,GAAG;CACH,QAAQ,EACL,KAAK;EAAC;EAAY;EAAe;CAAS,CAAC,CAAC,CAC5C,SAAS,oCAAoC;CAChD,QAAQ,KAAK,SAAS,8CAA8C;AACtE,CAAC,CACH,CAAC;AAED,MAAM,SAAS;CACb,aAAa,KAAK,SAAS,CAAC,CAAC,SAAS,uDAAuD;CAC7F,YAAY,EAAE,IAAI,SAAS,CAAC,CAAC,SAAS,uCAAuC;AAC/E;;AAGA,MAAa,wBAAwB,EAAE,mBAAmB,SAAS,CACjE,EAAE,aAAa;CACb,GAAG;CACH,OAAO,EACJ,QAAQ,OAAO,CAAC,CAChB,SAAS,+DAA+D;CAC3E,UAAU,EACP,MAAM,oBAAoB,CAAC,CAC3B,SAAS,CAAC,CACV,SAAS,yCAAyC;CACrD,cAAc,KACX,SAAS,CAAC,CACV,SAAS,uEAAuE;CACnF,aAAa,EAAE,MAAM,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,yCAAyC;CACxF,WAAW,EACR,QAAQ,CAAC,CACT,SAAS,kEAAkE;AAChF,CAAC,GACD,EAAE,aAAa;CACb,GAAG;CACH,OAAO,EAAE,QAAQ,aAAa,CAAC,CAAC,SAAS,wCAAwC;CACjF,QAAQ,KAAK,SAAS,yCAAyC;AACjE,CAAC,CACH,CAAC"}

package/dist/session-review.d.mts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+//#region src/session-review.d.ts
+/** Validates one recorded check without inferring success from a completed Task. */
+declare const sessionReviewCheckSchema: z.ZodObject<{
+  source: z.ZodString;
+  revision: z.ZodNullable<z.ZodString>;
+  id: z.ZodString;
+  title: z.ZodString;
+  status: z.ZodEnum<{
+    unknown: "unknown";
+    running: "running";
+    failed: "failed";
+    passed: "passed";
+    skipped: "skipped";
+  }>;
+  command: z.ZodOptional<z.ZodString>;
+  details: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Validates a screenshot supplied by the application's authorized review reader. */
+declare const sessionReviewScreenshotSchema: z.ZodObject<{
+  source: z.ZodString;
+  revision: z.ZodNullable<z.ZodString>;
+  id: z.ZodString;
+  url: z.ZodString;
+  caption: z.ZodString;
+  state: z.ZodOptional<z.ZodEnum<{
+    before: "before";
+    after: "after";
+  }>>;
+  comparisonId: z.ZodOptional<z.ZodString>;
+  width: z.ZodOptional<z.ZodNumber>;
+  height: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Validates a reported issue and the evidence or uncertainty behind it. */
+declare const sessionReviewIssueSchema: z.ZodObject<{
+  source: z.ZodString;
+  revision: z.ZodNullable<z.ZodString>;
+  id: z.ZodString;
+  title: z.ZodString;
+  body: z.ZodString;
+  status: z.ZodEnum<{
+    open: "open";
+    resolved: "resolved";
+  }>;
+  path: z.ZodOptional<z.ZodString>;
+  line: z.ZodOptional<z.ZodNumber>;
+  priority: z.ZodOptional<z.ZodString>;
+  evidence: z.ZodOptional<z.ZodString>;
+  limitations: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Validates a review projection with explicit distinctions between missing and empty evidence. */
+declare const sessionReviewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  state: z.ZodLiteral<"ready">;
+  summary: z.ZodOptional<z.ZodString>;
+  checks: z.ZodNullable<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    source: z.ZodString;
+    revision: z.ZodNullable<z.ZodString>;
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+      unknown: "unknown";
+      running: "running";
+      failed: "failed";
+      passed: "passed";
+      skipped: "skipped";
+    }>;
+    command: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>>>;
+  screenshots: z.ZodNullable<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    source: z.ZodString;
+    revision: z.ZodNullable<z.ZodString>;
+    id: z.ZodString;
+    url: z.ZodString;
+    caption: z.ZodString;
+    state: z.ZodOptional<z.ZodEnum<{
+      before: "before";
+      after: "after";
+    }>>;
+    comparisonId: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>>>;
+  issues: z.ZodNullable<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    source: z.ZodString;
+    revision: z.ZodNullable<z.ZodString>;
+    id: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodString;
+    status: z.ZodEnum<{
+      open: "open";
+      resolved: "resolved";
+    }>;
+    path: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodNumber>;
+    priority: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodOptional<z.ZodString>;
+    limitations: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>>>;
+  limitations: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+  truncated: z.ZodBoolean;
+  executionId: z.ZodNullable<z.ZodString>;
+  capturedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+  state: z.ZodLiteral<"unavailable">;
+  reason: z.ZodString;
+  executionId: z.ZodNullable<z.ZodString>;
+  capturedAt: z.ZodISODateTime;
+}, z.core.$strict>], "state">;
+/** Recorded check displayed in the operator review screen. */
+type SessionReviewCheck = z.infer<typeof sessionReviewCheckSchema>;
+/** Screenshot and optional before/after grouping supplied by an application. */
+type SessionReviewScreenshot = z.infer<typeof sessionReviewScreenshotSchema>;
+/** Reported issue with its recorded resolution state and supporting evidence. */
+type SessionReviewIssue = z.infer<typeof sessionReviewIssueSchema>;
+/** Provider-neutral evidence for reviewing an operator session. */
+type SessionReview = z.infer<typeof sessionReviewSchema>;
+//#endregion
+export { SessionReview, SessionReviewCheck, SessionReviewIssue, SessionReviewScreenshot, sessionReviewCheckSchema, sessionReviewIssueSchema, sessionReviewSchema, sessionReviewScreenshotSchema };
+//# sourceMappingURL=session-review.d.mts.map

package/dist/session-review.mjs

@@ -0,0 +1,79 @@
+import { z } from "zod";
+//#region src/session-review.ts
+const text = z.string().min(1);
+const source = {
+	source: text.describe("Human-readable origin of the evidence, including attempt when known."),
+	revision: text.nullable().describe("Exact provider-owned revision, or null when not recorded.")
+};
+/** Validates one recorded check without inferring success from a completed Task. */
+const sessionReviewCheckSchema = z.strictObject({
+	id: text.describe("Stable check identity within this review."),
+	title: text.describe("Check name."),
+	status: z.enum([
+		"passed",
+		"failed",
+		"skipped",
+		"running",
+		"unknown"
+	]).describe("Recorded outcome."),
+	command: text.optional().describe("Exact command, when recorded."),
+	details: text.optional().describe("Recorded output or explanation, rendered as Markdown."),
+	...source
+});
+const imageUrl = z.string().refine((value) => {
+	if (/[\s\\]/u.test(value)) return false;
+	if (value.startsWith("/") && !value.startsWith("//")) return true;
+	try {
+		const url = new URL(value);
+		return ["https:", "http:"].includes(url.protocol) && !url.username && !url.password;
+	} catch {
+		return false;
+	}
+}, "Use an HTTP(S) image URL or an absolute same-origin path");
+/** Validates a screenshot supplied by the application's authorized review reader. */
+const sessionReviewScreenshotSchema = z.strictObject({
+	id: text.describe("Stable image identity within this review."),
+	url: imageUrl.describe("Browser-readable image URL; the application owns access and expiry."),
+	caption: text.describe("Description of what the screenshot demonstrates."),
+	state: z.enum(["before", "after"]).optional().describe("Side of a before/after comparison."),
+	comparisonId: text.optional().describe("Groups before and after images of the same scenario."),
+	width: z.number().int().positive().optional().describe("Captured pixel width."),
+	height: z.number().int().positive().optional().describe("Captured pixel height."),
+	...source
+});
+/** Validates a reported issue and the evidence or uncertainty behind it. */
+const sessionReviewIssueSchema = z.strictObject({
+	id: text.describe("Stable issue identity within this review."),
+	title: text.describe("Short problem description."),
+	body: text.describe("Impact and explanation, rendered as Markdown."),
+	status: z.enum(["open", "resolved"]).describe("Recorded resolution state, not inferred from Task success."),
+	path: text.optional().describe("Repository-relative affected file."),
+	line: z.number().int().positive().optional().describe("Affected line in the recorded revision."),
+	priority: text.optional().describe("Application-defined urgency label."),
+	evidence: text.optional().describe("What was checked and what it showed."),
+	limitations: text.optional().describe("What remains uncertain or unchecked."),
+	...source
+});
+const common = {
+	executionId: text.nullable().describe("Observed session execution, or null before execution."),
+	capturedAt: z.iso.datetime().describe("When this evidence projection was read.")
+};
+/** Validates a review projection with explicit distinctions between missing and empty evidence. */
+const sessionReviewSchema = z.discriminatedUnion("state", [z.strictObject({
+	...common,
+	state: z.literal("ready").describe("The configured review reader completed."),
+	summary: text.optional().describe("Application-provided summary of the work."),
+	checks: z.array(sessionReviewCheckSchema).readonly().nullable().describe("Recorded checks; null means not recorded, not passing."),
+	screenshots: z.array(sessionReviewScreenshotSchema).readonly().nullable().describe("Recorded screenshots; null means no capture report is available."),
+	issues: z.array(sessionReviewIssueSchema).readonly().nullable().describe("Reported issues; null means no issue report is available."),
+	limitations: z.array(text).readonly().describe("Missing evidence, unsupported sources, or other review limitations."),
+	truncated: z.boolean().describe("The reader omitted evidence because of its configured limits.")
+}), z.strictObject({
+	...common,
+	state: z.literal("unavailable").describe("Review evidence could not be read."),
+	reason: text.describe("Why review evidence is unavailable.")
+})]);
+//#endregion
+export { sessionReviewCheckSchema, sessionReviewIssueSchema, sessionReviewSchema, sessionReviewScreenshotSchema };
+
+//# sourceMappingURL=session-review.mjs.map