@vercel/factory 0.0.14 → 0.0.16

package/dist/session-review.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-review.mjs","names":[],"sources":["../src/session-review.ts"],"sourcesContent":["import { z } from \"zod\";\n\nconst text = z.string().min(1);\nconst source = {\n  source: text.describe(\"Human-readable origin of the evidence, including attempt when known.\"),\n  revision: text.nullable().describe(\"Exact provider-owned revision, or null when not recorded.\"),\n};\n\n/** Validates one recorded check without inferring success from a completed Task. */\nexport const sessionReviewCheckSchema = z.strictObject({\n  id: text.describe(\"Stable check identity within this review.\"),\n  title: text.describe(\"Check name.\"),\n  status: z\n    .enum([\"passed\", \"failed\", \"skipped\", \"running\", \"unknown\"])\n    .describe(\"Recorded outcome.\"),\n  command: text.optional().describe(\"Exact command, when recorded.\"),\n  details: text.optional().describe(\"Recorded output or explanation, rendered as Markdown.\"),\n  ...source,\n});\n\nconst imageUrl = z.string().refine((value) => {\n  if (/[\\s\\\\]/u.test(value)) return false;\n  if (value.startsWith(\"/\") && !value.startsWith(\"//\")) return true;\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 HTTP(S) image URL or an absolute same-origin path\");\n\n/** Validates a screenshot supplied by the application's authorized review reader. */\nexport const sessionReviewScreenshotSchema = z.strictObject({\n  id: text.describe(\"Stable image identity within this review.\"),\n  url: imageUrl.describe(\"Browser-readable image URL; the application owns access and expiry.\"),\n  caption: text.describe(\"Description of what the screenshot demonstrates.\"),\n  state: z.enum([\"before\", \"after\"]).optional().describe(\"Side of a before/after comparison.\"),\n  comparisonId: text.optional().describe(\"Groups before and after images of the same scenario.\"),\n  width: z.number().int().positive().optional().describe(\"Captured pixel width.\"),\n  height: z.number().int().positive().optional().describe(\"Captured pixel height.\"),\n  ...source,\n});\n\n/** Validates a reported issue and the evidence or uncertainty behind it. */\nexport const sessionReviewIssueSchema = z.strictObject({\n  id: text.describe(\"Stable issue identity within this review.\"),\n  title: text.describe(\"Short problem description.\"),\n  body: text.describe(\"Impact and explanation, rendered as Markdown.\"),\n  status: z\n    .enum([\"open\", \"resolved\"])\n    .describe(\"Recorded resolution state, not inferred from Task success.\"),\n  path: text.optional().describe(\"Repository-relative affected file.\"),\n  line: z.number().int().positive().optional().describe(\"Affected line in the recorded revision.\"),\n  priority: text.optional().describe(\"Application-defined urgency label.\"),\n  evidence: text.optional().describe(\"What was checked and what it showed.\"),\n  limitations: text.optional().describe(\"What remains uncertain or unchecked.\"),\n  ...source,\n});\n\nconst common = {\n  executionId: text.nullable().describe(\"Observed session execution, or null before execution.\"),\n  capturedAt: z.iso.datetime().describe(\"When this evidence projection was read.\"),\n};\n\n/** Validates a review projection with explicit distinctions between missing and empty evidence. */\nexport const sessionReviewSchema = z.discriminatedUnion(\"state\", [\n  z.strictObject({\n    ...common,\n    state: z.literal(\"ready\").describe(\"The configured review reader completed.\"),\n    summary: text.optional().describe(\"Application-provided summary of the work.\"),\n    checks: z\n      .array(sessionReviewCheckSchema)\n      .readonly()\n      .nullable()\n      .describe(\"Recorded checks; null means not recorded, not passing.\"),\n    screenshots: z\n      .array(sessionReviewScreenshotSchema)\n      .readonly()\n      .nullable()\n      .describe(\"Recorded screenshots; null means no capture report is available.\"),\n    issues: z\n      .array(sessionReviewIssueSchema)\n      .readonly()\n      .nullable()\n      .describe(\"Reported issues; null means no issue report is available.\"),\n    limitations: z\n      .array(text)\n      .readonly()\n      .describe(\"Missing evidence, unsupported sources, or other review limitations.\"),\n    truncated: z\n      .boolean()\n      .describe(\"The reader omitted evidence because of its configured limits.\"),\n  }),\n  z.strictObject({\n    ...common,\n    state: z.literal(\"unavailable\").describe(\"Review evidence could not be read.\"),\n    reason: text.describe(\"Why review evidence is unavailable.\"),\n  }),\n]);\n\n/** Recorded check displayed in the operator review screen. */\nexport type SessionReviewCheck = z.infer<typeof sessionReviewCheckSchema>;\n/** Screenshot and optional before/after grouping supplied by an application. */\nexport type SessionReviewScreenshot = z.infer<typeof sessionReviewScreenshotSchema>;\n/** Reported issue with its recorded resolution state and supporting evidence. */\nexport type SessionReviewIssue = z.infer<typeof sessionReviewIssueSchema>;\n/** Provider-neutral evidence for reviewing an operator session. */\nexport type SessionReview = z.infer<typeof sessionReviewSchema>;\n"],"mappings":";;AAEA,MAAM,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;AAC7B,MAAM,SAAS;CACb,QAAQ,KAAK,SAAS,sEAAsE;CAC5F,UAAU,KAAK,SAAS,CAAC,CAAC,SAAS,2DAA2D;AAChG;;AAGA,MAAa,2BAA2B,EAAE,aAAa;CACrD,IAAI,KAAK,SAAS,2CAA2C;CAC7D,OAAO,KAAK,SAAS,aAAa;CAClC,QAAQ,EACL,KAAK;EAAC;EAAU;EAAU;EAAW;EAAW;CAAS,CAAC,CAAC,CAC3D,SAAS,mBAAmB;CAC/B,SAAS,KAAK,SAAS,CAAC,CAAC,SAAS,+BAA+B;CACjE,SAAS,KAAK,SAAS,CAAC,CAAC,SAAS,uDAAuD;CACzF,GAAG;AACL,CAAC;AAED,MAAM,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,UAAU;CAC5C,IAAI,UAAU,KAAK,KAAK,GAAG,OAAO;CAClC,IAAI,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,WAAW,IAAI,GAAG,OAAO;CAC7D,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,0DAA0D;;AAG7D,MAAa,gCAAgC,EAAE,aAAa;CAC1D,IAAI,KAAK,SAAS,2CAA2C;CAC7D,KAAK,SAAS,SAAS,qEAAqE;CAC5F,SAAS,KAAK,SAAS,kDAAkD;CACzE,OAAO,EAAE,KAAK,CAAC,UAAU,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,oCAAoC;CAC3F,cAAc,KAAK,SAAS,CAAC,CAAC,SAAS,sDAAsD;CAC7F,OAAO,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,uBAAuB;CAC9E,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,wBAAwB;CAChF,GAAG;AACL,CAAC;;AAGD,MAAa,2BAA2B,EAAE,aAAa;CACrD,IAAI,KAAK,SAAS,2CAA2C;CAC7D,OAAO,KAAK,SAAS,4BAA4B;CACjD,MAAM,KAAK,SAAS,+CAA+C;CACnE,QAAQ,EACL,KAAK,CAAC,QAAQ,UAAU,CAAC,CAAC,CAC1B,SAAS,4DAA4D;CACxE,MAAM,KAAK,SAAS,CAAC,CAAC,SAAS,oCAAoC;CACnE,MAAM,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,yCAAyC;CAC/F,UAAU,KAAK,SAAS,CAAC,CAAC,SAAS,oCAAoC;CACvE,UAAU,KAAK,SAAS,CAAC,CAAC,SAAS,sCAAsC;CACzE,aAAa,KAAK,SAAS,CAAC,CAAC,SAAS,sCAAsC;CAC5E,GAAG;AACL,CAAC;AAED,MAAM,SAAS;CACb,aAAa,KAAK,SAAS,CAAC,CAAC,SAAS,uDAAuD;CAC7F,YAAY,EAAE,IAAI,SAAS,CAAC,CAAC,SAAS,yCAAyC;AACjF;;AAGA,MAAa,sBAAsB,EAAE,mBAAmB,SAAS,CAC/D,EAAE,aAAa;CACb,GAAG;CACH,OAAO,EAAE,QAAQ,OAAO,CAAC,CAAC,SAAS,yCAAyC;CAC5E,SAAS,KAAK,SAAS,CAAC,CAAC,SAAS,2CAA2C;CAC7E,QAAQ,EACL,MAAM,wBAAwB,CAAC,CAC/B,SAAS,CAAC,CACV,SAAS,CAAC,CACV,SAAS,wDAAwD;CACpE,aAAa,EACV,MAAM,6BAA6B,CAAC,CACpC,SAAS,CAAC,CACV,SAAS,CAAC,CACV,SAAS,kEAAkE;CAC9E,QAAQ,EACL,MAAM,wBAAwB,CAAC,CAC/B,SAAS,CAAC,CACV,SAAS,CAAC,CACV,SAAS,2DAA2D;CACvE,aAAa,EACV,MAAM,IAAI,CAAC,CACX,SAAS,CAAC,CACV,SAAS,qEAAqE;CACjF,WAAW,EACR,QAAQ,CAAC,CACT,SAAS,+DAA+D;AAC7E,CAAC,GACD,EAAE,aAAa;CACb,GAAG;CACH,OAAO,EAAE,QAAQ,aAAa,CAAC,CAAC,SAAS,oCAAoC;CAC7E,QAAQ,KAAK,SAAS,qCAAqC;AAC7D,CAAC,CACH,CAAC"}

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 { ForbiddenError } from "eve/channels/auth";
+import { defineHook } from "eve/hooks";
+//#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,20 @@
+/// <reference types="node" />
+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,41 @@
+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[];
+  /** Recover a saved result before marking work stalled; a throw defers stall recovery. */
+  recoverResult?: (task: Task) => Promise<boolean>;
+  /** 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. Configured result recovery
+ * runs before marking a Task stalled; an error defers that attempt to a later pass.
+ */
+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,83 @@
+//#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. Configured result recovery
+* runs before marking a Task stalled; an error defers that attempt to a later pass.
+*/
+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 {
+			if (await options.recoverResult?.(task)) continue;
+			const stalled = await stores.tasks.transition(task.id, "stalled", {
+				reason: `no progress for ${Math.floor(sinceProgress / 6e4)} minutes (window ${minutes})`,
+				expectFrom: "running",
+				expectAttempt: task.attempt,
+				expectExecution: task.execution
+			});
+			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  /** Recover a saved result before marking work stalled; a throw defers stall recovery. */\n  recoverResult?: (task: Task) => Promise<boolean>;\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. Configured result recovery\n * runs before marking a Task stalled; an error defers that attempt to a later pass.\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      if (await options.recoverResult?.(task)) continue;\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        expectAttempt: task.attempt,\n        expectExecution: task.execution,\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":";;AA8BA,SAAgB,mBAAmB,QAAyB,MAA4B;CACtF,OAAO,OAAO,mBAAmB,SAAS,OAAO;AACnD;;;;;;;;;;AAWA,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,IAAI,MAAM,QAAQ,gBAAgB,IAAI,GAAG;GACzC,MAAM,UAAU,MAAM,OAAO,MAAM,WAAW,KAAK,IAAI,WAAW;IAChE,QAAQ,mBAAmB,KAAK,MAAM,gBAAgB,GAAM,EAAE,mBAAmB,QAAQ;IACzF,YAAY;IACZ,eAAe,KAAK;IACpB,iBAAiB,KAAK;GACxB,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" | "communicationSettings" | "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

package/dist/store/driver.mjs

@@ -0,0 +1,42 @@
+//#region src/store/driver.ts
+/** Error raised when an insert targets an already occupied storage key. */
+var RecordExistsError = class extends Error {
+	constructor(collection, id) {
+		super(`record "${id}" already exists in "${collection}"`);
+		this.name = "RecordExistsError";
+	}
+};
+/** Error raised when an operation requires a storage record that does not exist. */
+var RecordNotFoundError = class extends Error {
+	constructor(collection, id) {
+		super(`record "${id}" not found in "${collection}"`);
+		this.name = "RecordNotFoundError";
+	}
+};
+/** Error raised when atomic update loses its expected-version comparison. */
+var VersionConflictError = class extends Error {
+	constructor(collection, id, expectedVersion) {
+		super(`record "${id}" in "${collection}" changed since version ${expectedVersion} was read`);
+		this.name = "VersionConflictError";
+	}
+};
+/**
+* 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.
+*/
+var TransientStoreError = class extends Error {
+	constructor(collection, id, cause) {
+		const reason = cause instanceof Error ? cause.message : String(cause);
+		super(`record "${id}" in "${collection}" failed after transient retries were exhausted: ${reason}`, { cause: cause instanceof Error ? cause : void 0 });
+		this.name = "TransientStoreError";
+	}
+};
+//#endregion
+export { RecordExistsError, RecordNotFoundError, TransientStoreError, VersionConflictError };
+
+//# sourceMappingURL=driver.mjs.map

package/dist/store/driver.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.mjs","names":[],"sources":["../../src/store/driver.ts"],"sourcesContent":["/** Closed set of persistence collections understood by Factory store drivers. */\nexport type CollectionName =\n  | \"repositories\"\n  | \"signals\"\n  | \"tasks\"\n  | \"changes\"\n  | \"receipts\"\n  | \"budgets\"\n  | \"answers\"\n  | \"sessions\"\n  | \"externalSessions\"\n  | \"transcripts\"\n  | \"images\"\n  | \"questionRoutes\"\n  | \"taskCatalogs\"\n  | \"changeCatalogs\"\n  | \"sessionCatalogs\"\n  | \"externalSessionCatalogs\"\n  | \"taskRoutes\"\n  | \"outboxQueues\"\n  | \"outboxDeliveries\"\n  | \"communicationSettings\"\n  | \"taskGraphs\"\n  | \"taskMessages\"\n  | \"taskEffects\"\n  | \"taskInboxes\"\n  | \"taskMessageProcessing\"\n  | \"taskMessageDecisions\"\n  | \"taskMessageDiscards\"\n  | \"plannerActivations\"\n  | \"plannerCancellations\";\n\n/** Opaque persisted value paired with its compare-and-swap version. */\nexport interface StoredRecord {\n  readonly value: unknown;\n  readonly version: number;\n}\n\n/** Collection-listing entry containing its storage key and versioned record. */\nexport interface StoredEntry {\n  readonly id: string;\n  readonly record: StoredRecord;\n}\n\n/** Collection, storage key, and opaque value for one insert-only write. */\nexport interface InsertStoreRecordInput {\n  readonly collection: CollectionName;\n  readonly id: string;\n  readonly value: unknown;\n}\n\n/** Collection, storage key, opaque value, and compare-and-swap version for one update. */\nexport interface UpdateStoreRecordInput extends InsertStoreRecordInput {\n  readonly expectedVersion: number;\n}\n\n/** Error raised when an insert targets an already occupied storage key. */\nexport class RecordExistsError extends Error {\n  constructor(collection: CollectionName, id: string) {\n    super(`record \"${id}\" already exists in \"${collection}\"`);\n    this.name = \"RecordExistsError\";\n  }\n}\n\n/** Error raised when an operation requires a storage record that does not exist. */\nexport class RecordNotFoundError extends Error {\n  constructor(collection: CollectionName, id: string) {\n    super(`record \"${id}\" not found in \"${collection}\"`);\n    this.name = \"RecordNotFoundError\";\n  }\n}\n\n/** Error raised when atomic update loses its expected-version comparison. */\nexport class VersionConflictError extends Error {\n  constructor(collection: CollectionName, id: string, expectedVersion: number) {\n    super(`record \"${id}\" in \"${collection}\" changed since version ${expectedVersion} was read`);\n    this.name = \"VersionConflictError\";\n  }\n}\n\n/**\n * A transient infrastructure failure (network error, 5xx/429 response) that\n * a driver's own bounded, backed-off low-level retries could not resolve.\n * Distinct from VersionConflictError (a concurrent writer legitimately won)\n * and from validation or \"already exists\" errors (the request itself is\n * rejected): the same operation may still succeed if retried again later,\n * but every caller retrying on this error must keep its own bound so a real\n * outage surfaces as a failure instead of hanging a dispatch cycle.\n */\nexport class TransientStoreError extends Error {\n  constructor(collection: CollectionName, id: string, cause: unknown) {\n    const reason = cause instanceof Error ? cause.message : String(cause);\n    super(\n      `record \"${id}\" in \"${collection}\" failed after transient retries were exhausted: ${reason}`,\n      { cause: cause instanceof Error ? cause : undefined },\n    );\n    this.name = \"TransientStoreError\";\n  }\n}\n\n/**\n * Raw persistence contract. Drivers store opaque values and enforce nothing\n * about their content; every invariant lives in the engine above. `update`\n * must be an atomic compare-and-swap on `expectedVersion`. A driver may\n * throw TransientStoreError for a read or write that failed only because of\n * infrastructure trouble (network errors, 5xx/429 responses); it must not\n * use TransientStoreError for version conflicts or malformed input.\n */\nexport interface StoreDriver {\n  readonly name: string;\n  get(collection: CollectionName, id: string): Promise<StoredRecord | null>;\n  insert(input: InsertStoreRecordInput): Promise<void>;\n  update(input: UpdateStoreRecordInput): Promise<void>;\n  list(collection: CollectionName): Promise<readonly StoredEntry[]>;\n}\n"],"mappings":";;AAyDA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,YAAY,YAA4B,IAAY;EAClD,MAAM,WAAW,GAAG,uBAAuB,WAAW,EAAE;EACxD,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,sBAAb,cAAyC,MAAM;CAC7C,YAAY,YAA4B,IAAY;EAClD,MAAM,WAAW,GAAG,kBAAkB,WAAW,EAAE;EACnD,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,uBAAb,cAA0C,MAAM;CAC9C,YAAY,YAA4B,IAAY,iBAAyB;EAC3E,MAAM,WAAW,GAAG,QAAQ,WAAW,0BAA0B,gBAAgB,UAAU;EAC3F,KAAK,OAAO;CACd;AACF;;;;;;;;;;AAWA,IAAa,sBAAb,cAAyC,MAAM;CAC7C,YAAY,YAA4B,IAAY,OAAgB;EAClE,MAAM,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EACpE,MACE,WAAW,GAAG,QAAQ,WAAW,mDAAmD,UACpF,EAAE,OAAO,iBAAiB,QAAQ,QAAQ,KAAA,EAAU,CACtD;EACA,KAAK,OAAO;CACd;AACF"}