@vercel/factory 0.0.15 → 0.0.16

package/dist/session-review.d.mts

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

package/dist/session-review.mjs

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

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":"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"}

package/dist/signal-triage.mjs

@@ -1,7 +1,7 @@
 import { signalIdSchema } from "./schema/id.mjs";
 import { repositoryIdsForSession } from "./eve/task-session.mjs";
-import { defineHook } from "eve/hooks";
 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";

package/dist/signals.d.mts

@@ -1,3 +1,4 @@
+/// <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";

package/dist/stall.d.mts

@@ -10,6 +10,8 @@ interface StallSweepOptions {
   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>;
 }
@@ -30,7 +32,8 @@ declare function stallWindowMinutes(policy: ExecutionPolicy, kind: Task["kind"])
  * 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.
+ * 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

package/dist/stall.mjs

@@ -9,7 +9,8 @@ function stallWindowMinutes(policy, kind) {
 * 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.
+* 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();
@@ -27,9 +28,12 @@ async function sweepTaskStalls(stores, options) {
 		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"
+				expectFrom: "running",
+				expectAttempt: task.attempt,
+				expectExecution: task.execution
 			});
 			result.stalled.push(task.id);
 			newlyStalled.push(stalled);

package/dist/stall.mjs.map

@@ -1 +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"}
+{"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/store/driver.d.mts

@@ -1,6 +1,6 @@
 //#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";
+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;

package/dist/store/driver.mjs.map

@@ -1 +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  | \"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":";;AAwDA,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"}
+{"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"}