@vercel/factory 0.0.13 → 0.0.15

package/dist/schema/work.d.mts

@@ -0,0 +1,101 @@
+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> {
+  readonly title: string;
+  readonly input: Input;
+  readonly completionCriteria: readonly string[];
+  readonly workflow: Workflow;
+  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> {
+  readonly title: string;
+  readonly input?: Input;
+  readonly workflow?: never;
+  readonly route?: never;
+  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> {
+  readonly title: string;
+  readonly input: Input;
+  readonly workflow: Workflow;
+  readonly route?: never;
+  readonly completionCriteria?: never;
+}
+/** Constructs generic `task@1` work with an empty completion-criteria list. */
+declare function taskWork<const Input extends JsonValue = JsonValue>(options: TaskWorkOptions<Input>): TaskWork<Input>;
+/** Constructs work from a definition-like reference with a typed exact workflow binding. */
+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. */
+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  readonly title: string;\n  readonly input: Input;\n  readonly completionCriteria: readonly string[];\n  readonly workflow: Workflow;\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  readonly title: string;\n  readonly input?: Input;\n  readonly workflow?: never;\n  readonly route?: never;\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  readonly title: string;\n  readonly input: Input;\n  readonly workflow: Workflow;\n  readonly route?: never;\n  readonly completionCriteria?: never;\n}\n\n/** Constructs generic `task@1` work with an empty completion-criteria list. */\nexport function taskWork<const Input extends JsonValue = JsonValue>(\n  options: TaskWorkOptions<Input>,\n): TaskWork<Input>;\n/** Constructs work from a definition-like reference with a typed exact workflow binding. */\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/** Constructs work from an exact typed workflow binding. */\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/signal-triage.d.mts

@@ -0,0 +1,20 @@
+import { Signal } from "./schema/signal.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+import { AuthFn } from "eve/channels/auth";
+//#region src/signal-triage.d.ts
+/** Bind optional signal attempt headers only after the underlying caller authenticates. */
+declare function withSignalTriage(authenticate: AuthFn<Request>): AuthFn<Request>;
+/** Encode the admitted Signal attempt for a trusted Foreman launch. */
+declare function signalTriageHeaders(signal: Signal): Record<string, string>;
+/** Persist admission before launching; an ambiguous launch stays visible and cannot be retried blindly. */
+declare function runSignalTriage(stores: Pick<FactoryStores, "signals">, signal: Signal, options: {
+  expectedAttempt: number;
+  by: string;
+}, launch: (admitted: Signal, operationId: string) => Promise<{
+  sessionId: string;
+} | void>): Promise<Signal>;
+/** Record taskless Foreman failures from authenticated, repository-scoped Eve lifecycle events. */
+declare function createSignalTriageHook(stores: Pick<FactoryStores, "signals">): import("eve/hooks").HookDefinition<"session.failed" | "turn.cancelled" | "turn.completed" | "turn.failed">;
+//#endregion
+export { createSignalTriageHook, runSignalTriage, signalTriageHeaders, withSignalTriage };
+//# sourceMappingURL=signal-triage.d.mts.map

package/dist/signal-triage.mjs

@@ -0,0 +1,85 @@
+import { signalIdSchema } from "./schema/id.mjs";
+import { repositoryIdsForSession } from "./eve/task-session.mjs";
+import { defineHook } from "eve/hooks";
+import { ForbiddenError } from "eve/channels/auth";
+//#region src/signal-triage.ts
+const signalHeader = "x-factory-signal-id";
+const attemptHeader = "x-factory-signal-attempt";
+/** Bind optional signal attempt headers only after the underlying caller authenticates. */
+function withSignalTriage(authenticate) {
+	return async (request) => {
+		const auth = await authenticate(request);
+		if (auth == null) return auth;
+		const id = request.headers.get(signalHeader);
+		const attempt = request.headers.get(attemptHeader);
+		if (id === null && attempt === null) return auth;
+		if (!signalIdSchema.safeParse(id).success || !attempt || !/^[1-9]\d*$/u.test(attempt) || !Number.isSafeInteger(Number(attempt))) throw new ForbiddenError();
+		return {
+			...auth,
+			attributes: {
+				...auth.attributes,
+				factorySignalId: id,
+				factorySignalAttempt: attempt
+			}
+		};
+	};
+}
+/** Encode the admitted Signal attempt for a trusted Foreman launch. */
+function signalTriageHeaders(signal) {
+	if (!signal.triage) throw new Error("Signal has no admitted triage attempt");
+	return {
+		[signalHeader]: signal.id,
+		[attemptHeader]: String(signal.triage.attempt)
+	};
+}
+/** Persist admission before launching; an ambiguous launch stays visible and cannot be retried blindly. */
+async function runSignalTriage(stores, signal, options, launch) {
+	const admitted = await stores.signals.beginTriage(signal.id, options);
+	const attempt = admitted.triage.attempt;
+	let execution;
+	try {
+		execution = await launch(admitted, attempt === 1 ? `factory-signal:${signal.id}` : `factory-signal:${signal.id}:${attempt}`);
+	} catch {
+		return stores.signals.updateTriage(signal.id, attempt, {
+			state: "uncertain",
+			failure: "launch_unconfirmed"
+		});
+	}
+	if (!execution) return stores.signals.updateTriage(signal.id, attempt, {
+		state: "uncertain",
+		failure: "launch_unconfirmed"
+	});
+	return stores.signals.updateTriage(signal.id, attempt, {
+		state: "running",
+		sessionId: execution.sessionId
+	});
+}
+/** Record taskless Foreman failures from authenticated, repository-scoped Eve lifecycle events. */
+function createSignalTriageHook(stores) {
+	async function stopped(ctx, failure) {
+		const auth = ctx.session.auth.initiator;
+		const id = signalIdSchema.safeParse(auth?.attributes.factorySignalId);
+		const attempt = Number(auth?.attributes.factorySignalAttempt);
+		if (!id.success || !Number.isSafeInteger(attempt) || attempt < 1) return;
+		const signal = await stores.signals.get(id.data);
+		if (!signal || !repositoryIdsForSession(auth)?.includes(signal.repositoryId)) return;
+		await stores.signals.updateTriage(id.data, attempt, {
+			state: "blocked",
+			failure,
+			sessionId: ctx.session.id
+		});
+	}
+	function category(code, message) {
+		return `${code} ${message}`.includes("customer_verification_required") ? "billing_verification_required" : "provider_failed";
+	}
+	return defineHook({ events: {
+		"turn.failed": (event, ctx) => stopped(ctx, category(event.data.code, event.data.message)),
+		"session.failed": (event, ctx) => stopped(ctx, category(event.data.code, event.data.message)),
+		"turn.cancelled": (_event, ctx) => stopped(ctx, "cancelled"),
+		"turn.completed": (_event, ctx) => stopped(ctx, "no_decision")
+	} });
+}
+//#endregion
+export { createSignalTriageHook, runSignalTriage, signalTriageHeaders, withSignalTriage };
+
+//# sourceMappingURL=signal-triage.mjs.map

package/dist/signal-triage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-triage.mjs","names":[],"sources":["../src/signal-triage.ts"],"sourcesContent":["import { ForbiddenError, type AuthFn } from \"eve/channels/auth\";\nimport type { SessionContext } from \"eve/context\";\nimport { defineHook } from \"eve/hooks\";\nimport { signalIdSchema } from \"./schema/id\";\nimport type { Signal, SignalTriage } from \"./schema/signal\";\nimport type { FactoryStores } from \"./store/engine\";\nimport { repositoryIdsForSession } from \"./eve/task-session\";\n\nconst signalHeader = \"x-factory-signal-id\";\nconst attemptHeader = \"x-factory-signal-attempt\";\n\n/** Bind optional signal attempt headers only after the underlying caller authenticates. */\nexport function withSignalTriage(authenticate: AuthFn<Request>): AuthFn<Request> {\n  return async (request) => {\n    const auth = await authenticate(request);\n    if (auth == null) return auth;\n    const id = request.headers.get(signalHeader);\n    const attempt = request.headers.get(attemptHeader);\n    if (id === null && attempt === null) return auth;\n    if (\n      !signalIdSchema.safeParse(id).success ||\n      !attempt ||\n      !/^[1-9]\\d*$/u.test(attempt) ||\n      !Number.isSafeInteger(Number(attempt))\n    )\n      throw new ForbiddenError();\n    return {\n      ...auth,\n      attributes: { ...auth.attributes, factorySignalId: id!, factorySignalAttempt: attempt },\n    };\n  };\n}\n\n/** Encode the admitted Signal attempt for a trusted Foreman launch. */\nexport function signalTriageHeaders(signal: Signal): Record<string, string> {\n  if (!signal.triage) throw new Error(\"Signal has no admitted triage attempt\");\n  return { [signalHeader]: signal.id, [attemptHeader]: String(signal.triage.attempt) };\n}\n\n/** Persist admission before launching; an ambiguous launch stays visible and cannot be retried blindly. */\nexport async function runSignalTriage(\n  stores: Pick<FactoryStores, \"signals\">,\n  signal: Signal,\n  options: { expectedAttempt: number; by: string },\n  launch: (admitted: Signal, operationId: string) => Promise<{ sessionId: string } | void>,\n): Promise<Signal> {\n  const admitted = await stores.signals.beginTriage(signal.id, options);\n  const attempt = admitted.triage!.attempt;\n  let execution: { sessionId: string } | void;\n  try {\n    execution = await launch(\n      admitted,\n      attempt === 1 ? `factory-signal:${signal.id}` : `factory-signal:${signal.id}:${attempt}`,\n    );\n  } catch {\n    return stores.signals.updateTriage(signal.id, attempt, {\n      state: \"uncertain\",\n      failure: \"launch_unconfirmed\",\n    });\n  }\n  if (!execution)\n    return stores.signals.updateTriage(signal.id, attempt, {\n      state: \"uncertain\",\n      failure: \"launch_unconfirmed\",\n    });\n  return stores.signals.updateTriage(signal.id, attempt, {\n    state: \"running\",\n    sessionId: execution.sessionId,\n  });\n}\n\n/** Record taskless Foreman failures from authenticated, repository-scoped Eve lifecycle events. */\nexport function createSignalTriageHook(stores: Pick<FactoryStores, \"signals\">) {\n  async function stopped(ctx: Pick<SessionContext, \"session\">, failure: SignalTriage[\"failure\"]) {\n    const auth = ctx.session.auth.initiator;\n    const id = signalIdSchema.safeParse(auth?.attributes.factorySignalId);\n    const attempt = Number(auth?.attributes.factorySignalAttempt);\n    if (!id.success || !Number.isSafeInteger(attempt) || attempt < 1) return;\n    const signal = await stores.signals.get(id.data);\n    if (!signal || !repositoryIdsForSession(auth)?.includes(signal.repositoryId)) return;\n    await stores.signals.updateTriage(id.data, attempt, {\n      state: \"blocked\",\n      failure,\n      sessionId: ctx.session.id,\n    });\n  }\n  function category(code: string, message: string): SignalTriage[\"failure\"] {\n    return `${code} ${message}`.includes(\"customer_verification_required\")\n      ? \"billing_verification_required\"\n      : \"provider_failed\";\n  }\n  return defineHook({\n    events: {\n      \"turn.failed\": (event, ctx) => stopped(ctx, category(event.data.code, event.data.message)),\n      \"session.failed\": (event, ctx) => stopped(ctx, category(event.data.code, event.data.message)),\n      \"turn.cancelled\": (_event, ctx) => stopped(ctx, \"cancelled\"),\n      \"turn.completed\": (_event, ctx) => stopped(ctx, \"no_decision\"),\n    },\n  });\n}\n"],"mappings":";;;;;AAQA,MAAM,eAAe;AACrB,MAAM,gBAAgB;;AAGtB,SAAgB,iBAAiB,cAAgD;CAC/E,OAAO,OAAO,YAAY;EACxB,MAAM,OAAO,MAAM,aAAa,OAAO;EACvC,IAAI,QAAQ,MAAM,OAAO;EACzB,MAAM,KAAK,QAAQ,QAAQ,IAAI,YAAY;EAC3C,MAAM,UAAU,QAAQ,QAAQ,IAAI,aAAa;EACjD,IAAI,OAAO,QAAQ,YAAY,MAAM,OAAO;EAC5C,IACE,CAAC,eAAe,UAAU,EAAE,CAAC,CAAC,WAC9B,CAAC,WACD,CAAC,cAAc,KAAK,OAAO,KAC3B,CAAC,OAAO,cAAc,OAAO,OAAO,CAAC,GAErC,MAAM,IAAI,eAAe;EAC3B,OAAO;GACL,GAAG;GACH,YAAY;IAAE,GAAG,KAAK;IAAY,iBAAiB;IAAK,sBAAsB;GAAQ;EACxF;CACF;AACF;;AAGA,SAAgB,oBAAoB,QAAwC;CAC1E,IAAI,CAAC,OAAO,QAAQ,MAAM,IAAI,MAAM,uCAAuC;CAC3E,OAAO;GAAG,eAAe,OAAO;GAAK,gBAAgB,OAAO,OAAO,OAAO,OAAO;CAAE;AACrF;;AAGA,eAAsB,gBACpB,QACA,QACA,SACA,QACiB;CACjB,MAAM,WAAW,MAAM,OAAO,QAAQ,YAAY,OAAO,IAAI,OAAO;CACpE,MAAM,UAAU,SAAS,OAAQ;CACjC,IAAI;CACJ,IAAI;EACF,YAAY,MAAM,OAChB,UACA,YAAY,IAAI,kBAAkB,OAAO,OAAO,kBAAkB,OAAO,GAAG,GAAG,SACjF;CACF,QAAQ;EACN,OAAO,OAAO,QAAQ,aAAa,OAAO,IAAI,SAAS;GACrD,OAAO;GACP,SAAS;EACX,CAAC;CACH;CACA,IAAI,CAAC,WACH,OAAO,OAAO,QAAQ,aAAa,OAAO,IAAI,SAAS;EACrD,OAAO;EACP,SAAS;CACX,CAAC;CACH,OAAO,OAAO,QAAQ,aAAa,OAAO,IAAI,SAAS;EACrD,OAAO;EACP,WAAW,UAAU;CACvB,CAAC;AACH;;AAGA,SAAgB,uBAAuB,QAAwC;CAC7E,eAAe,QAAQ,KAAsC,SAAkC;EAC7F,MAAM,OAAO,IAAI,QAAQ,KAAK;EAC9B,MAAM,KAAK,eAAe,UAAU,MAAM,WAAW,eAAe;EACpE,MAAM,UAAU,OAAO,MAAM,WAAW,oBAAoB;EAC5D,IAAI,CAAC,GAAG,WAAW,CAAC,OAAO,cAAc,OAAO,KAAK,UAAU,GAAG;EAClE,MAAM,SAAS,MAAM,OAAO,QAAQ,IAAI,GAAG,IAAI;EAC/C,IAAI,CAAC,UAAU,CAAC,wBAAwB,IAAI,CAAC,EAAE,SAAS,OAAO,YAAY,GAAG;EAC9E,MAAM,OAAO,QAAQ,aAAa,GAAG,MAAM,SAAS;GAClD,OAAO;GACP;GACA,WAAW,IAAI,QAAQ;EACzB,CAAC;CACH;CACA,SAAS,SAAS,MAAc,SAA0C;EACxE,OAAO,GAAG,KAAK,GAAG,UAAU,SAAS,gCAAgC,IACjE,kCACA;CACN;CACA,OAAO,WAAW,EAChB,QAAQ;EACN,gBAAgB,OAAO,QAAQ,QAAQ,KAAK,SAAS,MAAM,KAAK,MAAM,MAAM,KAAK,OAAO,CAAC;EACzF,mBAAmB,OAAO,QAAQ,QAAQ,KAAK,SAAS,MAAM,KAAK,MAAM,MAAM,KAAK,OAAO,CAAC;EAC5F,mBAAmB,QAAQ,QAAQ,QAAQ,KAAK,WAAW;EAC3D,mBAAmB,QAAQ,QAAQ,QAAQ,KAAK,aAAa;CAC/D,EACF,CAAC;AACH"}

package/dist/signals.d.mts

@@ -0,0 +1,19 @@
+import { DecidedSignal, PendingSignal, Signal, SignalOutcome, SignalSource, SignalTriage, signalOutcomeSchema, signalSchema, signalSourceSchema, signalTriageSchema, standardSignalSources } from "./schema/signal.mjs";
+import { SignalId, signalIdSchema } from "./schema/id.mjs";
+import { CreateSignalInput, DecideSignalInput, FactoryStores } from "./store/engine.mjs";
+import { signalInitialOutcome, signalOutcomeTransitions, signalTriageTransitions } from "./schema/transitions.mjs";
+import { createSignalTriageHook, runSignalTriage, signalTriageHeaders, withSignalTriage } from "./signal-triage.mjs";
+//#region src/signals.d.ts
+/** Narrow intake boundary that persists normalized Signals without starting workflow work. */
+interface SignalCreator {
+  create(input: CreateSignalInput): Promise<Signal>;
+}
+/**
+ * Bind normalized intake to signal creation alone. Connectors and API routes
+ * own authentication and normalization; configured workflows own what happens
+ * next.
+ */
+declare function createSignalCreator(stores: Pick<FactoryStores, "signals">): SignalCreator;
+//#endregion
+export { type CreateSignalInput, type DecideSignalInput, type DecidedSignal, type PendingSignal, type Signal, SignalCreator, type SignalId, type SignalOutcome, type SignalSource, type SignalTriage, createSignalCreator, createSignalTriageHook, runSignalTriage, signalIdSchema, signalInitialOutcome, signalOutcomeSchema, signalOutcomeTransitions, signalSchema, signalSourceSchema, signalTriageHeaders, signalTriageSchema, signalTriageTransitions, standardSignalSources, withSignalTriage };
+//# sourceMappingURL=signals.d.mts.map

package/dist/signals.mjs

@@ -0,0 +1,19 @@
+import { signalIdSchema } from "./schema/id.mjs";
+import { signalInitialOutcome, signalOutcomeTransitions, signalTriageTransitions } from "./schema/transitions.mjs";
+import { signalOutcomeSchema, signalSchema, signalSourceSchema, signalTriageSchema, standardSignalSources } from "./schema/signal.mjs";
+import { createSignalTriageHook, runSignalTriage, signalTriageHeaders, withSignalTriage } from "./signal-triage.mjs";
+//#region src/signals.ts
+/**
+* Bind normalized intake to signal creation alone. Connectors and API routes
+* own authentication and normalization; configured workflows own what happens
+* next.
+*/
+function createSignalCreator(stores) {
+	return { create(input) {
+		return stores.signals.create(input);
+	} };
+}
+//#endregion
+export { createSignalCreator, createSignalTriageHook, runSignalTriage, signalIdSchema, signalInitialOutcome, signalOutcomeSchema, signalOutcomeTransitions, signalSchema, signalSourceSchema, signalTriageHeaders, signalTriageSchema, signalTriageTransitions, standardSignalSources, withSignalTriage };
+
+//# sourceMappingURL=signals.mjs.map

package/dist/signals.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.mjs","names":[],"sources":["../src/signals.ts"],"sourcesContent":["import type { Signal } from \"./schema/signal\";\nimport type { CreateSignalInput, FactoryStores } from \"./store/engine\";\n\nexport { signalIdSchema, type SignalId } from \"./schema/id\";\nexport {\n  signalOutcomeSchema,\n  signalTriageSchema,\n  type SignalTriage,\n  signalSchema,\n  signalSourceSchema,\n  standardSignalSources,\n  type DecidedSignal,\n  type PendingSignal,\n  type Signal,\n  type SignalOutcome,\n  type SignalSource,\n} from \"./schema/signal\";\nexport {\n  signalInitialOutcome,\n  signalOutcomeTransitions,\n  signalTriageTransitions,\n} from \"./schema/transitions\";\nexport { type CreateSignalInput, type DecideSignalInput } from \"./store/engine\";\n\n/** Narrow intake boundary that persists normalized Signals without starting workflow work. */\nexport interface SignalCreator {\n  create(input: CreateSignalInput): Promise<Signal>;\n}\n\n/**\n * Bind normalized intake to signal creation alone. Connectors and API routes\n * own authentication and normalization; configured workflows own what happens\n * next.\n */\nexport function createSignalCreator(stores: Pick<FactoryStores, \"signals\">): SignalCreator {\n  return {\n    create(input) {\n      return stores.signals.create(input);\n    },\n  };\n}\n\nexport {\n  createSignalTriageHook,\n  withSignalTriage,\n  signalTriageHeaders,\n  runSignalTriage,\n} from \"./signal-triage\";\n"],"mappings":";;;;;;;;;;AAkCA,SAAgB,oBAAoB,QAAuD;CACzF,OAAO,EACL,OAAO,OAAO;EACZ,OAAO,OAAO,QAAQ,OAAO,KAAK;CACpC,EACF;AACF"}

package/dist/stall.d.mts

@@ -0,0 +1,38 @@
+import { TaskId } from "./schema/id.mjs";
+import { Task } from "./schema/task.mjs";
+import { DateClock, MaybePromise } from "./schema/common.mjs";
+import { FactoryStores } from "./store/engine.mjs";
+import { ExecutionPolicy } from "./schema/factory-config.mjs";
+//#region src/stall.d.ts
+/** Execution policy, clock, snapshot, and optional workflow cancellation hook for stall recovery. */
+interface StallSweepOptions {
+  policy: ExecutionPolicy;
+  now?: DateClock;
+  /** A dispatcher-wide snapshot avoids another complete task read. */
+  tasks?: readonly Task[];
+  /** Optional workflow policy that cancels a stalled task instead of retrying it. */
+  cancelStalled?: (task: Task, tasks: readonly Task[]) => MaybePromise<string | null>;
+}
+/** Task IDs transitioned at each stage of one stall-recovery pass. */
+interface TaskStallSweepResult {
+  readonly stalled: readonly TaskId[];
+  readonly requeued: readonly TaskId[];
+  readonly failed: readonly TaskId[];
+  readonly cancelled: readonly TaskId[];
+}
+/** Task capability required to detect and recover stalled work. */
+type TaskStallSweepStores = Pick<FactoryStores, "tasks">;
+/** Resolve the progress timeout for a Task kind from the configured execution policy. */
+declare function stallWindowMinutes(policy: ExecutionPolicy, kind: Task["kind"]): number;
+/**
+ * The reconciler's stall pass. A running task whose execution has not
+ * progressed within its stall window is marked stalled; a stalled task is
+ * re-queued for a replacement attempt while attempts remain, and failed once
+ * they are exhausted. Only `running` tasks can stall: a task whose result has
+ * already been recorded (verifying, or terminal) is never retried by this
+ * pass. Workflows explicitly waiting for messages are skipped.
+ */
+declare function sweepTaskStalls(stores: TaskStallSweepStores, options: StallSweepOptions): Promise<TaskStallSweepResult>;
+//#endregion
+export { StallSweepOptions, TaskStallSweepResult, TaskStallSweepStores, stallWindowMinutes, sweepTaskStalls };
+//# sourceMappingURL=stall.d.mts.map

package/dist/stall.mjs

@@ -0,0 +1,79 @@
+//#region src/stall.ts
+/** Resolve the progress timeout for a Task kind from the configured execution policy. */
+function stallWindowMinutes(policy, kind) {
+	return policy.stallMinutesByKind[kind] ?? policy.stallMinutes;
+}
+/**
+* The reconciler's stall pass. A running task whose execution has not
+* progressed within its stall window is marked stalled; a stalled task is
+* re-queued for a replacement attempt while attempts remain, and failed once
+* they are exhausted. Only `running` tasks can stall: a task whose result has
+* already been recorded (verifying, or terminal) is never retried by this
+* pass. Workflows explicitly waiting for messages are skipped.
+*/
+async function sweepTaskStalls(stores, options) {
+	const nowMs = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	const result = {
+		stalled: [],
+		requeued: [],
+		failed: [],
+		cancelled: []
+	};
+	const tasks = options.tasks ?? await stores.tasks.list();
+	const newlyStalled = [];
+	for (const task of tasks) {
+		if (task.waitingForMessages || task.state !== "running") continue;
+		const minutes = stallWindowMinutes(options.policy, task.kind);
+		const sinceProgress = nowMs - Date.parse(task.lastProgressAt ?? task.updatedAt);
+		if (sinceProgress < minutes * 6e4) continue;
+		try {
+			const stalled = await stores.tasks.transition(task.id, "stalled", {
+				reason: `no progress for ${Math.floor(sinceProgress / 6e4)} minutes (window ${minutes})`,
+				expectFrom: "running"
+			});
+			result.stalled.push(task.id);
+			newlyStalled.push(stalled);
+		} catch {
+			if (options.tasks !== void 0) {
+				const current = await stores.tasks.get(task.id).catch(() => null);
+				if (current?.state === "stalled") newlyStalled.push(current);
+			}
+			continue;
+		}
+	}
+	const stalledCandidates = options.tasks === void 0 ? await stores.tasks.list() : [...tasks.filter((task) => task.state === "stalled"), ...newlyStalled];
+	for (const task of stalledCandidates) {
+		if (task.waitingForMessages || task.state !== "stalled") continue;
+		const cancellationReason = await options.cancelStalled?.(task, tasks) ?? null;
+		try {
+			if (cancellationReason !== null) {
+				await stores.tasks.transition(task.id, "cancelled", {
+					reason: cancellationReason,
+					expectFrom: "stalled"
+				});
+				result.cancelled.push(task.id);
+			} else if (task.attempt < options.policy.maxAttempts) {
+				await stores.tasks.transition(task.id, "queued", {
+					reason: `stalled on attempt ${task.attempt} of ${options.policy.maxAttempts}; replacing`,
+					phase: "retry",
+					expectFrom: "stalled"
+				});
+				result.requeued.push(task.id);
+			} else {
+				await stores.tasks.transition(task.id, "failed", {
+					reason: `stalled on attempt ${task.attempt} of ${options.policy.maxAttempts}; attempts exhausted`,
+					phase: "retry",
+					expectFrom: "stalled"
+				});
+				result.failed.push(task.id);
+			}
+		} catch {
+			continue;
+		}
+	}
+	return result;
+}
+//#endregion
+export { stallWindowMinutes, sweepTaskStalls };
+
+//# sourceMappingURL=stall.mjs.map

package/dist/stall.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stall.mjs","names":[],"sources":["../src/stall.ts"],"sourcesContent":["import type { ExecutionPolicy } from \"./schema/factory-config\";\nimport type { DateClock, MaybePromise } from \"./schema/common\";\nimport type { TaskId } from \"./schema/id\";\nimport type { Task } from \"./schema/task\";\nimport type { FactoryStores } from \"./store/engine\";\n\n/** Execution policy, clock, snapshot, and optional workflow cancellation hook for stall recovery. */\nexport interface StallSweepOptions {\n  policy: ExecutionPolicy;\n  now?: DateClock;\n  /** A dispatcher-wide snapshot avoids another complete task read. */\n  tasks?: readonly Task[];\n  /** Optional workflow policy that cancels a stalled task instead of retrying it. */\n  cancelStalled?: (task: Task, tasks: readonly Task[]) => MaybePromise<string | null>;\n}\n\n/** Task IDs transitioned at each stage of one stall-recovery pass. */\nexport interface TaskStallSweepResult {\n  readonly stalled: readonly TaskId[];\n  readonly requeued: readonly TaskId[];\n  readonly failed: readonly TaskId[];\n  readonly cancelled: readonly TaskId[];\n}\n\n/** Task capability required to detect and recover stalled work. */\nexport type TaskStallSweepStores = Pick<FactoryStores, \"tasks\">;\n\n/** Resolve the progress timeout for a Task kind from the configured execution policy. */\nexport function stallWindowMinutes(policy: ExecutionPolicy, kind: Task[\"kind\"]): number {\n  return policy.stallMinutesByKind[kind] ?? policy.stallMinutes;\n}\n\n/**\n * The reconciler's stall pass. A running task whose execution has not\n * progressed within its stall window is marked stalled; a stalled task is\n * re-queued for a replacement attempt while attempts remain, and failed once\n * they are exhausted. Only `running` tasks can stall: a task whose result has\n * already been recorded (verifying, or terminal) is never retried by this\n * pass. Workflows explicitly waiting for messages are skipped.\n */\nexport async function sweepTaskStalls(\n  stores: TaskStallSweepStores,\n  options: StallSweepOptions,\n): Promise<TaskStallSweepResult> {\n  const nowMs = (options.now ?? (() => new Date()))().getTime();\n  const result: {\n    stalled: TaskId[];\n    requeued: TaskId[];\n    failed: TaskId[];\n    cancelled: TaskId[];\n  } = {\n    stalled: [],\n    requeued: [],\n    failed: [],\n    cancelled: [],\n  };\n  const tasks = options.tasks ?? (await stores.tasks.list());\n  const newlyStalled: Task[] = [];\n\n  for (const task of tasks) {\n    if (task.waitingForMessages || task.state !== \"running\") {\n      continue;\n    }\n    const minutes = stallWindowMinutes(options.policy, task.kind);\n    const sinceProgress = nowMs - Date.parse(task.lastProgressAt ?? task.updatedAt);\n    if (sinceProgress < minutes * 60_000) {\n      continue;\n    }\n    // A concurrent writer may have moved the task; skip rather than abort.\n    try {\n      const stalled = await stores.tasks.transition(task.id, \"stalled\", {\n        reason: `no progress for ${Math.floor(sinceProgress / 60_000)} minutes (window ${minutes})`,\n        expectFrom: \"running\",\n      });\n      result.stalled.push(task.id);\n      newlyStalled.push(stalled);\n    } catch {\n      if (options.tasks !== undefined) {\n        const current = await stores.tasks.get(task.id).catch(() => null);\n        if (current?.state === \"stalled\") newlyStalled.push(current);\n      }\n      continue;\n    }\n  }\n\n  // Resolve every stalled task, including ones stalled by an earlier pass that\n  // crashed before reaching this step.\n  const stalledCandidates =\n    options.tasks === undefined\n      ? await stores.tasks.list()\n      : [...tasks.filter((task) => task.state === \"stalled\"), ...newlyStalled];\n  for (const task of stalledCandidates) {\n    if (task.waitingForMessages || task.state !== \"stalled\") {\n      continue;\n    }\n    const cancellationReason = (await options.cancelStalled?.(task, tasks)) ?? null;\n    try {\n      if (cancellationReason !== null) {\n        await stores.tasks.transition(task.id, \"cancelled\", {\n          reason: cancellationReason,\n          expectFrom: \"stalled\",\n        });\n        result.cancelled.push(task.id);\n      } else if (task.attempt < options.policy.maxAttempts) {\n        await stores.tasks.transition(task.id, \"queued\", {\n          reason: `stalled on attempt ${task.attempt} of ${options.policy.maxAttempts}; replacing`,\n          phase: \"retry\",\n          expectFrom: \"stalled\",\n        });\n        result.requeued.push(task.id);\n      } else {\n        await stores.tasks.transition(task.id, \"failed\", {\n          reason: `stalled on attempt ${task.attempt} of ${options.policy.maxAttempts}; attempts exhausted`,\n          phase: \"retry\",\n          expectFrom: \"stalled\",\n        });\n        result.failed.push(task.id);\n      }\n    } catch {\n      continue;\n    }\n  }\n  return result;\n}\n"],"mappings":";;AA4BA,SAAgB,mBAAmB,QAAyB,MAA4B;CACtF,OAAO,OAAO,mBAAmB,SAAS,OAAO;AACnD;;;;;;;;;AAUA,eAAsB,gBACpB,QACA,SAC+B;CAC/B,MAAM,SAAS,QAAQ,8BAAc,IAAI,KAAK,GAAA,CAAI,CAAC,CAAC,QAAQ;CAC5D,MAAM,SAKF;EACF,SAAS,CAAC;EACV,UAAU,CAAC;EACX,QAAQ,CAAC;EACT,WAAW,CAAC;CACd;CACA,MAAM,QAAQ,QAAQ,SAAU,MAAM,OAAO,MAAM,KAAK;CACxD,MAAM,eAAuB,CAAC;CAE9B,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,KAAK,sBAAsB,KAAK,UAAU,WAC5C;EAEF,MAAM,UAAU,mBAAmB,QAAQ,QAAQ,KAAK,IAAI;EAC5D,MAAM,gBAAgB,QAAQ,KAAK,MAAM,KAAK,kBAAkB,KAAK,SAAS;EAC9E,IAAI,gBAAgB,UAAU,KAC5B;EAGF,IAAI;GACF,MAAM,UAAU,MAAM,OAAO,MAAM,WAAW,KAAK,IAAI,WAAW;IAChE,QAAQ,mBAAmB,KAAK,MAAM,gBAAgB,GAAM,EAAE,mBAAmB,QAAQ;IACzF,YAAY;GACd,CAAC;GACD,OAAO,QAAQ,KAAK,KAAK,EAAE;GAC3B,aAAa,KAAK,OAAO;EAC3B,QAAQ;GACN,IAAI,QAAQ,UAAU,KAAA,GAAW;IAC/B,MAAM,UAAU,MAAM,OAAO,MAAM,IAAI,KAAK,EAAE,CAAC,CAAC,YAAY,IAAI;IAChE,IAAI,SAAS,UAAU,WAAW,aAAa,KAAK,OAAO;GAC7D;GACA;EACF;CACF;CAIA,MAAM,oBACJ,QAAQ,UAAU,KAAA,IACd,MAAM,OAAO,MAAM,KAAK,IACxB,CAAC,GAAG,MAAM,QAAQ,SAAS,KAAK,UAAU,SAAS,GAAG,GAAG,YAAY;CAC3E,KAAK,MAAM,QAAQ,mBAAmB;EACpC,IAAI,KAAK,sBAAsB,KAAK,UAAU,WAC5C;EAEF,MAAM,qBAAsB,MAAM,QAAQ,gBAAgB,MAAM,KAAK,KAAM;EAC3E,IAAI;GACF,IAAI,uBAAuB,MAAM;IAC/B,MAAM,OAAO,MAAM,WAAW,KAAK,IAAI,aAAa;KAClD,QAAQ;KACR,YAAY;IACd,CAAC;IACD,OAAO,UAAU,KAAK,KAAK,EAAE;GAC/B,OAAO,IAAI,KAAK,UAAU,QAAQ,OAAO,aAAa;IACpD,MAAM,OAAO,MAAM,WAAW,KAAK,IAAI,UAAU;KAC/C,QAAQ,sBAAsB,KAAK,QAAQ,MAAM,QAAQ,OAAO,YAAY;KAC5E,OAAO;KACP,YAAY;IACd,CAAC;IACD,OAAO,SAAS,KAAK,KAAK,EAAE;GAC9B,OAAO;IACL,MAAM,OAAO,MAAM,WAAW,KAAK,IAAI,UAAU;KAC/C,QAAQ,sBAAsB,KAAK,QAAQ,MAAM,QAAQ,OAAO,YAAY;KAC5E,OAAO;KACP,YAAY;IACd,CAAC;IACD,OAAO,OAAO,KAAK,KAAK,EAAE;GAC5B;EACF,QAAQ;GACN;EACF;CACF;CACA,OAAO;AACT"}

package/dist/storage.d.mts

@@ -0,0 +1,4 @@
+import { CollectionName, InsertStoreRecordInput, RecordExistsError, RecordNotFoundError, StoreDriver, StoredEntry, StoredRecord, TransientStoreError, UpdateStoreRecordInput, VersionConflictError } from "./store/driver.mjs";
+import { CacheContinuationContextInput, CreateStoresOptions, FactoryStores, createStores } from "./store/engine.mjs";
+import { createInMemoryDriver } from "./store/memory.mjs";
+export { type CacheContinuationContextInput, type CollectionName, type CreateStoresOptions, type FactoryStores, type InsertStoreRecordInput, RecordExistsError, RecordNotFoundError, type StoreDriver, type StoredEntry, type StoredRecord, TransientStoreError, type UpdateStoreRecordInput, VersionConflictError, createInMemoryDriver, createStores };

package/dist/storage.mjs

@@ -0,0 +1,4 @@
+import { RecordExistsError, RecordNotFoundError, TransientStoreError, VersionConflictError } from "./store/driver.mjs";
+import { createStores } from "./store/engine.mjs";
+import { createInMemoryDriver } from "./store/memory.mjs";
+export { RecordExistsError, RecordNotFoundError, TransientStoreError, VersionConflictError, createInMemoryDriver, createStores };

package/dist/store/driver.d.mts

@@ -0,0 +1,65 @@
+//#region src/store/driver.d.ts
+/** Closed set of persistence collections understood by Factory store drivers. */
+type CollectionName = "repositories" | "signals" | "tasks" | "changes" | "receipts" | "budgets" | "answers" | "sessions" | "externalSessions" | "transcripts" | "images" | "questionRoutes" | "taskCatalogs" | "changeCatalogs" | "sessionCatalogs" | "externalSessionCatalogs" | "taskRoutes" | "outboxQueues" | "outboxDeliveries" | "taskGraphs" | "taskMessages" | "taskEffects" | "taskInboxes" | "taskMessageProcessing" | "taskMessageDecisions" | "taskMessageDiscards" | "plannerActivations" | "plannerCancellations";
+/** Opaque persisted value paired with its compare-and-swap version. */
+interface StoredRecord {
+  readonly value: unknown;
+  readonly version: number;
+}
+/** Collection-listing entry containing its storage key and versioned record. */
+interface StoredEntry {
+  readonly id: string;
+  readonly record: StoredRecord;
+}
+/** Collection, storage key, and opaque value for one insert-only write. */
+interface InsertStoreRecordInput {
+  readonly collection: CollectionName;
+  readonly id: string;
+  readonly value: unknown;
+}
+/** Collection, storage key, opaque value, and compare-and-swap version for one update. */
+interface UpdateStoreRecordInput extends InsertStoreRecordInput {
+  readonly expectedVersion: number;
+}
+/** Error raised when an insert targets an already occupied storage key. */
+declare class RecordExistsError extends Error {
+  constructor(collection: CollectionName, id: string);
+}
+/** Error raised when an operation requires a storage record that does not exist. */
+declare class RecordNotFoundError extends Error {
+  constructor(collection: CollectionName, id: string);
+}
+/** Error raised when atomic update loses its expected-version comparison. */
+declare class VersionConflictError extends Error {
+  constructor(collection: CollectionName, id: string, expectedVersion: number);
+}
+/**
+ * A transient infrastructure failure (network error, 5xx/429 response) that
+ * a driver's own bounded, backed-off low-level retries could not resolve.
+ * Distinct from VersionConflictError (a concurrent writer legitimately won)
+ * and from validation or "already exists" errors (the request itself is
+ * rejected): the same operation may still succeed if retried again later,
+ * but every caller retrying on this error must keep its own bound so a real
+ * outage surfaces as a failure instead of hanging a dispatch cycle.
+ */
+declare class TransientStoreError extends Error {
+  constructor(collection: CollectionName, id: string, cause: unknown);
+}
+/**
+ * Raw persistence contract. Drivers store opaque values and enforce nothing
+ * about their content; every invariant lives in the engine above. `update`
+ * must be an atomic compare-and-swap on `expectedVersion`. A driver may
+ * throw TransientStoreError for a read or write that failed only because of
+ * infrastructure trouble (network errors, 5xx/429 responses); it must not
+ * use TransientStoreError for version conflicts or malformed input.
+ */
+interface StoreDriver {
+  readonly name: string;
+  get(collection: CollectionName, id: string): Promise<StoredRecord | null>;
+  insert(input: InsertStoreRecordInput): Promise<void>;
+  update(input: UpdateStoreRecordInput): Promise<void>;
+  list(collection: CollectionName): Promise<readonly StoredEntry[]>;
+}
+//#endregion
+export { CollectionName, InsertStoreRecordInput, RecordExistsError, RecordNotFoundError, StoreDriver, StoredEntry, StoredRecord, TransientStoreError, UpdateStoreRecordInput, VersionConflictError };
+//# sourceMappingURL=driver.d.mts.map