@sanity/workflow-engine 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,17 +1,17 @@
 import { parse, evaluate } from "groq-js";
-import { z } from "zod";
+import * as v from "valibot";
 function validateDefinition(definition) {
-  const v = createDefinitionValidator();
+  const v2 = createDefinitionValidator();
   for (const slot of definition.state ?? [])
-    v.checkSlot(slot, "workflow.state", `workflow.state "${slot.id}"`);
+    v2.checkSlot(slot, `workflow.state "${slot.id}"`);
   for (const p of definition.predicates ?? [])
-    p.groq && v.checkFilter(p.groq, `predicate "${p.id}"`);
+    p.groq && v2.checkFilter(p.groq, `predicate "${p.id}"`);
   for (const stage of definition.stages)
-    validateStage(v, stage);
-  if (v.errors.length > 0)
+    validateStage(v2, stage);
+  if (v2.errors.length > 0)
     throw new Error(
-      `defineWorkflow("${definition.workflowId}", v${definition.version}): ${v.errors.length} validation error${v.errors.length === 1 ? "" : "s"}:
-` + v.errors.join(`
+      `defineWorkflow("${definition.workflowId}", v${definition.version}): ${v2.errors.length} validation error${v2.errors.length === 1 ? "" : "s"}:
+` + v2.errors.join(`
 `)
     );
 }
@@ -30,31 +30,29 @@ function createDefinitionValidator() {
   };
   return { errors, tryParse, checkFilter: (groq, where) => {
     tryParse(groq, where), rejectTypeScan(groq, where);
-  }, checkSlot: (slot, scopeLabel, slotLabel) => {
-    slot.source.kind === "computed" && errors.push(
-      `  \xB7 ${scopeLabel} slot "${slot.id}": source.kind="computed" is reserved (not implemented in v0.1)`
-    ), slot.source.kind === "query" && tryParse(slot.source.query, `${slotLabel}.query`);
+  }, checkSlot: (slot, slotLabel) => {
+    slot.source.kind === "query" && tryParse(slot.source.query, `${slotLabel}.query`);
   } };
 }
-function validateStage(v, stage) {
+function validateStage(v2, stage) {
   for (const slot of stage.state ?? [])
-    v.checkSlot(slot, `stage "${stage.id}".state`, `stage "${stage.id}".state "${slot.id}"`);
-  typeof stage.completion == "string" && v.tryParse(stage.completion, `stage "${stage.id}".completion`);
+    v2.checkSlot(slot, `stage "${stage.id}".state "${slot.id}"`);
+  typeof stage.completion == "string" && v2.tryParse(stage.completion, `stage "${stage.id}".completion`);
   for (const t of stage.transitions ?? [])
-    typeof t.filter == "string" && v.checkFilter(t.filter, `transition ${stage.id} \u2192 ${t.to} filter`);
+    typeof t.filter == "string" && v2.checkFilter(t.filter, `transition ${stage.id} \u2192 ${t.to} filter`);
   for (const task of stage.tasks ?? [])
-    validateTask(v, stage.id, task);
+    validateTask(v2, stage.id, task);
 }
-function validateTask(v, stageId, task) {
+function validateTask(v2, stageId, task) {
   const where = `stage "${stageId}" task "${task.id}"`;
   for (const slot of task.state ?? [])
-    v.checkSlot(slot, `${where}.state`, `${where}.state "${slot.id}"`);
-  typeof task.filter == "string" && v.checkFilter(task.filter, `${where}.filter`), typeof task.completeWhen == "string" && v.checkFilter(task.completeWhen, `${where}.completeWhen`);
+    v2.checkSlot(slot, `${where}.state "${slot.id}"`);
+  typeof task.filter == "string" && v2.checkFilter(task.filter, `${where}.filter`), typeof task.completeWhen == "string" && v2.checkFilter(task.completeWhen, `${where}.completeWhen`);
   for (const a of task.actions ?? [])
-    typeof a.filter == "string" && v.checkFilter(a.filter, `task "${task.id}" action "${a.id}".filter`);
-  task.spawns?.forEach?.groq && v.tryParse(task.spawns.forEach.groq, `task "${task.id}".spawns.forEach.groq`);
+    typeof a.filter == "string" && v2.checkFilter(a.filter, `task "${task.id}" action "${a.id}".filter`);
+  task.spawns?.forEach?.groq && v2.tryParse(task.spawns.forEach.groq, `task "${task.id}".spawns.forEach.groq`);
 }
-const KNOWN_SCHEMES = /* @__PURE__ */ new Set(["dataset", "canvas", "media-library", "dashboard"]);
+const wallClock = () => (/* @__PURE__ */ new Date()).toISOString(), KNOWN_SCHEMES = /* @__PURE__ */ new Set(["dataset", "canvas", "media-library", "dashboard"]);
 function parseGdr(uri) {
   const colon = uri.indexOf(":");
   if (colon < 0)
@@ -121,6 +119,9 @@ function gdrFromResource(res, documentId) {
   }
   return gdrUri({ scheme: res.type, resourceId: res.id, documentId });
 }
+function selfGdr(doc) {
+  return gdrFromResource(doc.workflowResource, doc._id);
+}
 function isGdrUri(value) {
   if (typeof value != "string") return !1;
   try {
@@ -135,15 +136,15 @@ function gdrRef(res, documentId, type) {
 function isGdr(value) {
   return typeof value == "object" && value !== null && typeof value.id == "string" && typeof value.type == "string";
 }
-function buildParams(instance, extra) {
+function buildParams(instance, now, extra) {
   return {
-    self: gdrFromResource(instance.workflowResource, instance._id),
+    self: selfGdr(instance),
     state: stateMap(instance.state ?? []),
     parent: instance.ancestors.at(-1)?.id ?? null,
     ancestors: instance.ancestors.map((a) => a.id),
     /** Current stage id — bind for filters that scope to the current stage. */
     stage: instance.currentStageId,
-    now: (/* @__PURE__ */ new Date()).toISOString(),
+    now,
     ...extra
   };
 }
@@ -167,8 +168,8 @@ function stripStateForLake(value) {
   if (Array.isArray(value)) return value.map(stripStateForLake);
   if (typeof value == "object") {
     const out = {};
-    for (const [k, v] of Object.entries(value))
-      out[k] = stripStateForLake(v);
+    for (const [k, v2] of Object.entries(value))
+      out[k] = stripStateForLake(v2);
     return out;
   }
   return value;
@@ -226,7 +227,7 @@ function matchesParamType(type, value) {
     case "boolean":
       return typeof value == "boolean";
     case "string[]":
-      return Array.isArray(value) && value.every((v) => typeof v == "string");
+      return Array.isArray(value) && value.every((v2) => typeof v2 == "string");
     case "reference":
       return isGdr(value);
   }
@@ -247,11 +248,11 @@ function restampForSnapshot(doc, gdrUri2, resource) {
 }
 function rewriteRefsRecursive(value, resource) {
   if (Array.isArray(value))
-    return value.map((v) => rewriteRefsRecursive(v, resource));
+    return value.map((v2) => rewriteRefsRecursive(v2, resource));
   if (value === null || typeof value != "object") return value;
   const obj = value, out = {};
-  for (const [k, v] of Object.entries(obj))
-    k === "_ref" && typeof v == "string" ? out[k] = v.includes(":") ? v : gdrFromResource(resource, v) : out[k] = rewriteRefsRecursive(v, resource);
+  for (const [k, v2] of Object.entries(obj))
+    k === "_ref" && typeof v2 == "string" ? out[k] = v2.includes(":") ? v2 : gdrFromResource(resource, v2) : out[k] = rewriteRefsRecursive(v2, resource);
   return out;
 }
 async function hydrateSnapshot(args) {
@@ -260,7 +261,7 @@ async function hydrateSnapshot(args) {
     const fetched = await loadByGdr(client, clientForGdr, instance.workflowResource, uri);
     fetched && (loaded.push(fetched), visited.add(uri));
   };
-  loaded.push({ doc: instance, resource: instance.workflowResource }), visited.add(gdrFromResource(instance.workflowResource, instance._id));
+  loaded.push({ doc: instance, resource: instance.workflowResource }), visited.add(selfGdr(instance));
   for (const ancestor of instance.ancestors)
     await loadInto(ancestor.id);
   for (const uri of collectSlotDocUris(instance.state))
@@ -295,12 +296,12 @@ function slotDocUris(slot) {
   if (!slot || typeof slot != "object") return [];
   const s = slot;
   if (s._type === "workflow.state.doc.ref") {
-    const v = s.value, id = refId(v);
+    const v2 = s.value, id = refId(v2);
     return id !== void 0 ? [id] : [];
   }
   if (s._type === "workflow.state.doc.refs") {
-    const v = s.value;
-    return Array.isArray(v) ? v.map(refId).filter((id) => id !== void 0) : [];
+    const v2 = s.value;
+    return Array.isArray(v2) ? v2.map(refId).filter((id) => id !== void 0) : [];
   }
   return [];
 }
@@ -324,50 +325,61 @@ class SlotValueShapeError extends Error {
     super(`Slot ${args.mode} shape invalid for "${args.slotId}" (${args.slotType}): ${issueText}`), this.name = "SlotValueShapeError", this.slotType = args.slotType, this.slotId = args.slotId, this.issues = args.issues;
   }
 }
-const GdrShape = z.object({
-  id: z.string().refine((s) => isGdrUri(s), { message: "must be a GDR URI" }),
-  type: z.string().min(1)
-}).passthrough(), ReleaseRefShape = z.object({
-  id: z.string().refine((s) => isGdrUri(s), { message: "must be a GDR URI" }),
-  type: z.literal("system.release"),
-  releaseName: z.string().min(1)
-}).passthrough(), ActorShape = z.object({
-  kind: z.enum(["user", "ai", "system"]),
-  id: z.string().min(1),
-  roles: z.array(z.string()).optional(),
-  onBehalfOf: z.string().optional()
-}).passthrough(), AssigneeShape = z.union([
-  z.object({ kind: z.literal("user"), id: z.string().min(1) }).passthrough(),
-  z.object({ kind: z.literal("role"), role: z.string().min(1) }).passthrough()
-]), ChecklistItemShape = z.object({
-  label: z.string().min(1),
-  done: z.boolean(),
-  doneBy: z.string().optional(),
-  doneAt: z.string().optional(),
-  _key: z.string().min(1).optional()
-}).passthrough(), NoteItemShape = z.object({
-  _key: z.string().min(1).optional()
-}).passthrough().refine((v) => typeof v == "object" && v !== null && !Array.isArray(v), {
-  message: "must be an object"
-}), NullableString = z.union([z.null(), z.string()]), NullableNumber = z.union([z.null(), z.number()]), NullableBoolean = z.union([z.null(), z.boolean()]), NullableDateTime = z.union([
-  z.null(),
-  z.string().refine((s) => !Number.isNaN(Date.parse(s)), {
-    message: "must be an ISO-8601 datetime string"
-  })
+const GdrShape = v.looseObject({
+  id: v.pipe(
+    v.string(),
+    v.check((s) => isGdrUri(s), "must be a GDR URI")
+  ),
+  type: v.pipe(v.string(), v.minLength(1))
+}), ReleaseRefShape = v.looseObject({
+  id: v.pipe(
+    v.string(),
+    v.check((s) => isGdrUri(s), "must be a GDR URI")
+  ),
+  type: v.literal("system.release"),
+  releaseName: v.pipe(v.string(), v.minLength(1))
+}), ActorShape = v.looseObject({
+  kind: v.picklist(["user", "ai", "system"]),
+  id: v.pipe(v.string(), v.minLength(1)),
+  roles: v.optional(v.array(v.string())),
+  onBehalfOf: v.optional(v.string())
+}), AssigneeShape = v.union([
+  v.looseObject({ kind: v.literal("user"), id: v.pipe(v.string(), v.minLength(1)) }),
+  v.looseObject({ kind: v.literal("role"), role: v.pipe(v.string(), v.minLength(1)) })
+]), ChecklistItemShape = v.looseObject({
+  label: v.pipe(v.string(), v.minLength(1)),
+  done: v.boolean(),
+  doneBy: v.optional(v.string()),
+  doneAt: v.optional(v.string()),
+  _key: v.optional(v.pipe(v.string(), v.minLength(1)))
+}), NoteItemShape = v.pipe(
+  v.looseObject({
+    _key: v.optional(v.pipe(v.string(), v.minLength(1)))
+  }),
+  v.check(
+    (val) => typeof val == "object" && val !== null && !Array.isArray(val),
+    "must be an object"
+  )
+), NullableString = v.union([v.null(), v.string()]), NullableNumber = v.union([v.null(), v.number()]), NullableBoolean = v.union([v.null(), v.boolean()]), NullableDateTime = v.union([
+  v.null(),
+  v.pipe(
+    v.string(),
+    v.check((s) => !Number.isNaN(Date.parse(s)), "must be an ISO-8601 datetime string")
+  )
 ]), NullableUrl = NullableString, valueSchemas = {
-  "workflow.state.doc.ref": z.union([z.null(), GdrShape]),
-  "workflow.state.doc.refs": z.array(GdrShape),
-  "workflow.state.release.ref": z.union([z.null(), ReleaseRefShape]),
-  "workflow.state.query": z.any(),
+  "workflow.state.doc.ref": v.union([v.null(), GdrShape]),
+  "workflow.state.doc.refs": v.array(GdrShape),
+  "workflow.state.release.ref": v.union([v.null(), ReleaseRefShape]),
+  "workflow.state.query": v.any(),
   "workflow.state.value.string": NullableString,
   "workflow.state.value.url": NullableUrl,
   "workflow.state.value.number": NullableNumber,
   "workflow.state.value.boolean": NullableBoolean,
   "workflow.state.value.dateTime": NullableDateTime,
-  "workflow.state.value.actor": z.union([z.null(), ActorShape]),
-  "workflow.state.checklist": z.array(ChecklistItemShape),
-  "workflow.state.notes": z.array(NoteItemShape),
-  "workflow.state.assignees": z.array(AssigneeShape)
+  "workflow.state.value.actor": v.union([v.null(), ActorShape]),
+  "workflow.state.checklist": v.array(ChecklistItemShape),
+  "workflow.state.notes": v.array(NoteItemShape),
+  "workflow.state.assignees": v.array(AssigneeShape)
 }, itemSchemas = {
   "workflow.state.doc.refs": GdrShape,
   "workflow.state.checklist": ChecklistItemShape,
@@ -386,12 +398,12 @@ function validateSlotValue(args) {
       issues: [`unknown slot type ${args.slotType}`],
       mode: "value"
     });
-  const result = schema.safeParse(args.value);
+  const result = v.safeParse(schema, args.value);
   if (!result.success)
     throw new SlotValueShapeError({
       slotType: args.slotType,
       slotId: args.slotId,
-      issues: formatIssues(result.error.issues),
+      issues: formatIssues(result.issues),
       mode: "value"
     });
 }
@@ -403,17 +415,20 @@ function validateSlotAppendItem(args) {
       issues: [`slot type ${args.slotType} does not support append`],
       mode: "item"
     });
-  const result = itemSchemas[args.slotType].safeParse(args.item);
+  const schema = itemSchemas[args.slotType], result = v.safeParse(schema, args.item);
   if (!result.success)
     throw new SlotValueShapeError({
       slotType: args.slotType,
       slotId: args.slotId,
-      issues: formatIssues(result.error.issues),
+      issues: formatIssues(result.issues),
       mode: "item"
     });
 }
 function formatIssues(issues) {
-  return issues.map((i) => `${i.path.length > 0 ? `at ${i.path.join(".")}: ` : ""}${i.message}`);
+  return issues.map((i) => {
+    const keys = i.path?.map((p) => p.key) ?? [];
+    return `${keys.length > 0 ? `at ${keys.join(".")}: ` : ""}${i.message}`;
+  });
 }
 function derivePerspectiveFromState(slots) {
   if (slots !== void 0) {
@@ -458,7 +473,7 @@ async function resolveQueryValue(slot, source, ctx, client, defaultValue) {
     state: stateMapFromResolved(ctx.resolvedState ?? []),
     stage: ctx.stageId ?? null,
     task: ctx.taskId ?? null,
-    now: (/* @__PURE__ */ new Date()).toISOString(),
+    now: ctx.now,
     engineTags: ctx.tags ?? []
   });
   try {
@@ -475,7 +490,7 @@ async function resolveSlotValue(slot, initialState, ctx, defaultValue) {
   const source = slot.source;
   return source.kind === "init" ? resolveInitValue(slot, initialState, defaultValue) : source.kind === "literal" ? source.value ?? defaultValue : source.kind === "stateRead" ? resolveStateReadValue(source, ctx, defaultValue) : source.kind === "query" && ctx.client !== void 0 ? resolveQueryValue(slot, source, ctx, ctx.client, defaultValue) : defaultValue;
 }
-function buildResolvedSlot(slot, value, _key) {
+function buildResolvedSlot(slot, value, _key, now) {
   const titleProp = slot.title !== void 0 ? { title: slot.title } : {}, descriptionProp = slot.description !== void 0 ? { description: slot.description } : {};
   return slot.type === "workflow.state.query" ? {
     _key,
@@ -484,7 +499,7 @@ function buildResolvedSlot(slot, value, _key) {
     ...titleProp,
     ...descriptionProp,
     value,
-    resolvedAt: (/* @__PURE__ */ new Date()).toISOString()
+    resolvedAt: now
   } : {
     _key,
     _type: slot.type,
@@ -496,7 +511,7 @@ function buildResolvedSlot(slot, value, _key) {
 }
 async function resolveOneSlot(slot, initialState, ctx, randomKey2) {
   const defaultValue = defaultSlotValue(slot.type), value = await resolveSlotValue(slot, initialState, ctx, defaultValue);
-  return validateSlotValue({ slotType: slot.type, slotId: slot.id, value }), buildResolvedSlot(slot, value, randomKey2());
+  return validateSlotValue({ slotType: slot.type, slotId: slot.id, value }), buildResolvedSlot(slot, value, randomKey2(), ctx.now);
 }
 function stateMapFromResolved(slots) {
   const out = {};
@@ -510,10 +525,10 @@ function assertInitValueShape(slot, value) {
   }
   if (slot.type === "workflow.state.release.ref") {
     assertGdrShape(value, `state slot "${slot.id}" (workflow.state.release.ref)`);
-    const v = value;
-    if (typeof v.releaseName != "string" || v.releaseName.length === 0)
+    const v2 = value;
+    if (typeof v2.releaseName != "string" || v2.releaseName.length === 0)
       throw new Error(
-        `Invalid init value for state slot "${slot.id}" (workflow.state.release.ref): \`releaseName\` must be a non-empty string. Got ${JSON.stringify(v.releaseName)}.`
+        `Invalid init value for state slot "${slot.id}" (workflow.state.release.ref): \`releaseName\` must be a non-empty string. Got ${JSON.stringify(v2.releaseName)}.`
       );
     return;
   }
@@ -531,18 +546,18 @@ function assertGdrShape(value, context) {
     throw new Error(
       `Invalid GDR for ${context}: expected { id: "<scheme>:...", type: "<schema>" }, got ${typeof value}.`
     );
-  const v = value;
-  if (typeof v.id != "string" || !isGdrUri(v.id))
+  const v2 = value;
+  if (typeof v2.id != "string" || !isGdrUri(v2.id))
     throw new Error(
-      `Invalid GDR for ${context}: \`id\` must be a GDR URI ("<scheme>:<...id-parts>" with scheme dataset|canvas|media-library|dashboard). Got ${JSON.stringify(v.id)}. Construct via \`gdrFromResource\` / \`refDataset\` / \`refCanvas\` etc. \u2014 bare document ids are not accepted.`
+      `Invalid GDR for ${context}: \`id\` must be a GDR URI ("<scheme>:<...id-parts>" with scheme dataset|canvas|media-library|dashboard). Got ${JSON.stringify(v2.id)}. Construct via \`gdrFromResource\` / \`refDataset\` / \`refCanvas\` etc. \u2014 bare document ids are not accepted.`
     );
-  if (typeof v.type != "string" || v.type.length === 0)
+  if (typeof v2.type != "string" || v2.type.length === 0)
     throw new Error(
-      `Invalid GDR for ${context}: \`type\` (schema name) must be a non-empty string. Got ${JSON.stringify(v.type)}.`
+      `Invalid GDR for ${context}: \`type\` (schema name) must be a non-empty string. Got ${JSON.stringify(v2.type)}.`
     );
 }
 function normalizeQueryResult(slotType, raw, workflowResource) {
-  return raw == null ? raw : slotType === "workflow.state.doc.ref" ? coerceToGdr(raw, workflowResource) : slotType === "workflow.state.doc.refs" ? Array.isArray(raw) ? raw.map((item) => coerceToGdr(item, workflowResource)).filter((v) => v !== null) : [] : raw;
+  return raw == null ? raw : slotType === "workflow.state.doc.ref" ? coerceToGdr(raw, workflowResource) : slotType === "workflow.state.doc.refs" ? Array.isArray(raw) ? raw.map((item) => coerceToGdr(item, workflowResource)).filter((v2) => v2 !== null) : [] : raw;
 }
 function toGdrUri(docId, workflowResource) {
   return isGdrUri(docId) ? docId : gdrFromResource(workflowResource, docId);
@@ -567,22 +582,24 @@ async function loadContext(client, instanceId, options) {
   const instance = await client.getDocument(instanceId);
   if (!instance)
     throw new Error(`Workflow instance ${instanceId} not found`);
-  const definition = JSON.parse(instance.definitionSnapshot), clientForGdr = options?.clientForGdr ?? (() => client), snapshot = await hydrateSnapshot({ client, clientForGdr, instance, definition });
-  return { client, clientForGdr, instance, definition, snapshot };
+  const definition = JSON.parse(instance.definitionSnapshot), clientForGdr = options?.clientForGdr ?? (() => client), clock = options?.clock ?? wallClock, snapshot = await hydrateSnapshot({ client, clientForGdr, instance, definition });
+  return { client, clientForGdr, clock, now: clock(), instance, definition, snapshot };
 }
 function ctxEvaluateFilter(ctx, filter) {
   return evaluateFilter({
     filter,
     definition: ctx.definition,
     snapshot: ctx.snapshot,
-    params: buildParams(ctx.instance)
+    params: buildParams(ctx.instance, ctx.now)
   });
 }
 async function buildEngineContext(args) {
-  const { client, clientForGdr, instance, definition } = args;
+  const { client, clientForGdr, instance, definition } = args, clock = args.clock ?? wallClock;
   return {
     client,
     clientForGdr,
+    clock,
+    now: clock(),
     instance,
     definition,
     snapshot: await hydrateSnapshot({ client, clientForGdr, instance, definition })
@@ -595,12 +612,13 @@ function findStage(definition, stageId) {
   return stage;
 }
 async function resolveStageStateSlots(args) {
-  const { client, instance, stage, initialState } = args;
+  const { client, instance, stage, now, initialState } = args;
   return resolveDeclaredState({
     slotDefs: stage.state,
     initialState: initialState ?? [],
     ctx: {
       client,
+      now,
       selfId: instance._id,
       tags: instance.tags ?? [],
       stageId: stage.id,
@@ -615,12 +633,13 @@ async function resolveStageStateSlots(args) {
   });
 }
 async function resolveTaskStateSlots(args) {
-  const { client, instance, stage, task } = args;
+  const { client, instance, stage, task, now } = args;
   return resolveDeclaredState({
     slotDefs: task.state,
     initialState: [],
     ctx: {
       client,
+      now,
       selfId: instance._id,
       tags: instance.tags ?? [],
       stageId: stage.id,
@@ -648,16 +667,24 @@ function slotValue$1(slot) {
   if (slot != null && typeof slot == "object")
     return slot.value;
 }
-function resolveSource(src, ctx) {
+function resolveStaticSource(src, ctx) {
   switch (src.source) {
     case "literal":
-      return src.value;
+      return { handled: !0, value: src.value };
     case "param":
-      return ctx.params?.[src.paramId];
+      return { handled: !0, value: ctx.params?.[src.paramId] };
     case "actor":
-      return ctx.actor;
+      return { handled: !0, value: ctx.actor };
     case "now":
-      return (/* @__PURE__ */ new Date()).toISOString();
+      return { handled: !0, value: ctx.now };
+    default:
+      return { handled: !1 };
+  }
+}
+function resolveSource(src, ctx) {
+  const staticValue = resolveStaticSource(src, ctx);
+  if (staticValue.handled) return staticValue.value;
+  switch (src.source) {
     case "self":
       return ctx.instance._id;
     case "stageId":
@@ -668,6 +695,11 @@ function resolveSource(src, ctx) {
       return resolveEffectOutput(src, ctx);
     case "object":
       return resolveObject(src, ctx);
+    case "row":
+    case "parentState":
+      return;
+    default:
+      return;
   }
 }
 function resolveStateRead(src, ctx) {
@@ -687,10 +719,11 @@ function resolveObject(src, ctx) {
   return out;
 }
 async function resolveBindings(args) {
-  const { bindings, staticInput, instance, params, actor } = args, resolved = {};
+  const { bindings, staticInput, instance, now, params, actor } = args, resolved = {};
   if (bindings) {
     const ctx = {
       instance,
+      now,
       ...params !== void 0 ? { params } : {},
       ...actor !== void 0 ? { actor } : {}
     };
@@ -737,16 +770,29 @@ function buildInstanceBase(args) {
     lastChangedAt: now
   };
 }
+const GUARD_DOC_TYPE = "temp.system.guard";
+class MutationGuardDeniedError extends Error {
+  denied;
+  documentId;
+  action;
+  constructor(args) {
+    const ids = args.denied.map((d) => d.guardId).join(", ");
+    super(`Mutation on "${args.documentId}" (${args.action}) denied by guard(s) [${ids}]`), this.name = "MutationGuardDeniedError", this.denied = args.denied, this.documentId = args.documentId, this.action = args.action;
+  }
+}
 function lakeGuardId(args) {
-  return `temp.system.guard.${args.instanceDocId}.${args.stageId}.${args.index}`;
+  return `${GUARD_DOC_TYPE}.${args.instanceDocId}.${args.stageId}.${args.index}`;
 }
 function compileGuard(args) {
   return {
     _id: args.id,
-    _type: "temp.system.guard",
+    _type: GUARD_DOC_TYPE,
     resourceType: args.resourceType,
     resourceId: args.resourceId,
     owner: args.owner,
+    sourceInstanceId: args.sourceInstanceId,
+    sourceDefinitionId: args.sourceDefinitionId,
+    sourceStageId: args.sourceStageId,
     ...args.name !== void 0 ? { name: args.name } : {},
     ...args.description !== void 0 ? { description: args.description } : {},
     match: args.match,
@@ -802,9 +848,9 @@ function resolveIdRefTarget(src, ctx) {
   if (typeof value == "string" && isGdrUri(value))
     return { parsed: parseGdr(value) };
   if (value && typeof value == "object") {
-    const v = value;
-    if (typeof v.id == "string" && isGdrUri(v.id))
-      return typeof v.type == "string" ? { parsed: parseGdr(v.id), type: v.type } : { parsed: parseGdr(v.id) };
+    const v2 = value;
+    if (typeof v2.id == "string" && isGdrUri(v2.id))
+      return typeof v2.type == "string" ? { parsed: parseGdr(v2.id), type: v2.type } : { parsed: parseGdr(v2.id) };
   }
   return null;
 }
@@ -843,8 +889,8 @@ function resolveMetadata(metadata, ctx) {
   return out;
 }
 const GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
-function resolveGuard(guard, index, instance, stageId) {
-  const ctx = { instance, stageId }, targets = resolveIdRefTargets(guard.match.idRefs, ctx);
+function resolveGuard(guard, index, instance, stageId, now) {
+  const ctx = { instance, stageId, now }, targets = resolveIdRefTargets(guard.match.idRefs, ctx);
   if (targets === null) return null;
   const resource = assertSingleResource(targets), types = resolveMatchTypes(targets, guard.match.types);
   return { doc: compileGuard({
@@ -852,6 +898,9 @@ function resolveGuard(guard, index, instance, stageId) {
     resourceType: resource.type,
     resourceId: resource.id,
     owner: GUARD_OWNER,
+    sourceInstanceId: instance._id,
+    sourceDefinitionId: instance.workflowId,
+    sourceStageId: stageId,
     ...guard.name !== void 0 ? { name: guard.name } : {},
     ...guard.description !== void 0 ? { description: guard.description } : {},
     match: {
@@ -865,47 +914,108 @@ function resolveGuard(guard, index, instance, stageId) {
   }), routeGdr: targets[0].parsed };
 }
 async function upsertGuard(client, doc) {
-  const existing = await client.getDocument(doc._id), set = {
-    resourceType: doc.resourceType,
-    resourceId: doc.resourceId,
-    owner: doc.owner,
-    match: doc.match,
-    predicate: doc.predicate,
-    metadata: doc.metadata
-  };
-  doc.name !== void 0 && (set.name = doc.name), doc.description !== void 0 && (set.description = doc.description), existing ? await client.patch(doc._id).set(set).commit() : await client.create(doc);
+  if (!await client.getDocument(doc._id)) {
+    await client.create(doc);
+    return;
+  }
+  const { _id, _type, _rev, _createdAt, _updatedAt, ...body } = doc;
+  await client.patch(doc._id).set(body).commit();
 }
 function resolvedStageGuards(args) {
   const stage = args.definition.stages.find((s) => s.id === args.stageId), out = [];
   for (const [index, guard] of (stage?.guards ?? []).entries()) {
-    const resolved = resolveGuard(guard, index, args.instance, args.stageId);
+    const resolved = resolveGuard(guard, index, args.instance, args.stageId, args.now);
     resolved !== null && out.push({ client: args.clientForGdr(resolved.routeGdr), doc: resolved.doc });
   }
   return out;
 }
+async function committedStageId(args) {
+  return (await args.client.getDocument(args.instance._id))?.currentStageId;
+}
 async function deployStageGuards(args) {
-  for (const { client, doc } of resolvedStageGuards(args))
-    await upsertGuard(client, doc);
+  if (await committedStageId(args) === args.stageId)
+    for (const { client, doc } of resolvedStageGuards(args))
+      await upsertGuard(client, doc);
 }
 async function retractStageGuards(args) {
-  for (const { client, doc } of resolvedStageGuards(args))
-    await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit();
+  const live = await committedStageId(args);
+  if (!(live === void 0 || live === args.stageId))
+    for (const { client, doc } of resolvedStageGuards(args))
+      await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit();
 }
-async function reconcileStageGuards(args) {
-  const { client, clientForGdr, instance, definition, exitedStageId, enteredStageId } = args;
-  exitedStageId !== void 0 && await retractStageGuards({
-    client,
-    clientForGdr,
-    instance,
-    definition,
-    stageId: exitedStageId
-  }), enteredStageId !== void 0 && await deployStageGuards({
-    client,
-    clientForGdr,
-    instance,
-    definition,
-    stageId: enteredStageId
-  });
+class ActionParamsInvalidError extends Error {
+  action;
+  taskId;
+  issues;
+  constructor(args) {
+    const lines = args.issues.map((i) => `  - ${i.paramId}: ${i.reason}`).join(`
+`);
+    super(`Action "${args.action}" on task "${args.taskId}" rejected: invalid params
+${lines}`), this.name = "ActionParamsInvalidError", this.action = args.action, this.taskId = args.taskId, this.issues = args.issues;
+  }
+}
+class WorkflowStateDivergedError extends Error {
+  instanceId;
+  /** The guard-deploy failure that triggered the (attempted) rollback. */
+  guardError;
+  /** The rollback failure, when rollback was attempted and itself failed. */
+  rollbackError;
+  constructor(args) {
+    super(
+      `Workflow "${args.instanceId}" state committed but its guards could not be reconciled: ${args.reason}.`,
+      { cause: args.guardError }
+    ), this.name = "WorkflowStateDivergedError", this.instanceId = args.instanceId, this.guardError = args.guardError, args.rollbackError !== void 0 && (this.rollbackError = args.rollbackError);
+  }
+}
+const CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS = 3;
+class ConcurrentFireActionError extends Error {
+  instanceId;
+  taskId;
+  action;
+  attempts;
+  constructor(args) {
+    super(
+      `Action "${args.action}" on task "${args.taskId}" (instance ${args.instanceId}) lost the optimistic-locking race ${args.attempts} attempts running \u2014 a concurrent writer kept committing first. Re-read and retry, or investigate a write storm on this instance.`
+    ), this.name = "ConcurrentFireActionError", this.instanceId = args.instanceId, this.taskId = args.taskId, this.action = args.action, this.attempts = args.attempts;
+  }
+}
+function isRevisionConflict(error) {
+  if (typeof error != "object" || error === null) return !1;
+  const { statusCode, message } = error;
+  return statusCode === 409 ? !0 : typeof message == "string" && message.includes("ifRevisionId check failed");
+}
+class CascadeLimitError extends Error {
+  instanceId;
+  limit;
+  constructor(args) {
+    super(
+      `Cascade did not stabilise after ${args.limit} auto-transitions on ${args.instanceId} \u2014 likely a runaway loop (transition guards that stay mutually satisfied). Check that each transition's filter eventually goes false.`
+    ), this.name = "CascadeLimitError", this.instanceId = args.instanceId, this.limit = args.limit;
+  }
+}
+async function deployOrRollback(args) {
+  try {
+    await args.deploy();
+  } catch (guardError) {
+    if (!args.reversible)
+      throw new WorkflowStateDivergedError({
+        instanceId: args.instanceId,
+        guardError,
+        reason: "the move created child instances a parent-only rollback cannot undo"
+      });
+    try {
+      let patch = args.client.patch(args.instanceId).set(args.restore);
+      args.unset && args.unset.length > 0 && (patch = patch.unset(args.unset)), args.committedRev !== void 0 && (patch = patch.ifRevisionId(args.committedRev)), await patch.commit();
+    } catch (rollbackError) {
+      throw new WorkflowStateDivergedError({
+        instanceId: args.instanceId,
+        guardError,
+        rollbackError,
+        reason: "rollback of the committed move failed"
+      });
+    }
+    throw guardError;
+  }
 }
 async function discoverItems(args) {
   const { client, groq, params, perspective } = args, fetchOptions = perspective !== void 0 ? { perspective } : void 0;
@@ -922,31 +1032,29 @@ function clientForDiscovery(defaultClient, clientForGdr, subjectGdrUri) {
 const MAX_SPAWN_DEPTH = 6;
 async function spawnChildren(ctx, mutation, task, spawn, actor) {
   if (ctx.instance.ancestors.length + 1 > MAX_SPAWN_DEPTH) {
-    const chain = [
-      ...ctx.instance.ancestors.map((a) => a.id),
-      gdrFromResource(ctx.instance.workflowResource, ctx.instance._id)
-    ].join(" \u2192 ");
+    const chain = [...ctx.instance.ancestors.map((a) => a.id), selfGdr(ctx.instance)].join(" \u2192 ");
     throw new Error(
       `Spawn depth limit (${MAX_SPAWN_DEPTH}) exceeded on task "${task.id}" of ${ctx.instance._id}. Ancestor chain: ${chain}`
     );
   }
-  const rows = await resolveSpawnRows(ctx, spawn), refs = [];
+  const now = ctx.now, rows = await resolveSpawnRows(ctx, spawn), refs = [];
   for (const row of rows) {
-    const projected = projectSpawnRow(ctx.instance, spawn, row), { ref, body } = await prepareChildInstance({
+    const projected = projectSpawnRow(ctx.instance, spawn, row, now), { ref, body } = await prepareChildInstance({
       client: ctx.client,
       parent: ctx.instance,
       task,
       spawn,
       initialState: projected.initialState,
       effectsContext: projected.effectsContext,
-      actor
+      actor,
+      now
     });
     refs.push(ref), mutation.pendingCreates.push(body);
   }
   return refs;
 }
 async function resolveSpawnRows(ctx, spawn) {
-  const params = buildParams(ctx.instance), groq = spawn.forEach.groq;
+  const params = buildParams(ctx.instance, ctx.now), groq = spawn.forEach.groq;
   let value;
   if (groq.includes("*")) {
     const routingUri = firstDocRefGdrUri(ctx.instance.state), client = clientForDiscovery(ctx.client, ctx.clientForGdr, routingUri);
@@ -968,7 +1076,7 @@ function firstDocRefGdrUri(slots) {
       if (s._type === "workflow.state.doc.ref" && s.value !== null) return s.value.id;
   }
 }
-function resolveSpawnSource(source, parent, row) {
+function resolveSpawnSource(source, parent, row, now) {
   switch (source.source) {
     case "literal":
       return source.value;
@@ -979,15 +1087,15 @@ function resolveSpawnSource(source, parent, row) {
       return slot === void 0 ? null : source.path !== void 0 ? getPath(slot, source.path) : slot;
     }
     case "self":
-      return gdrFromResource(parent.workflowResource, parent._id);
+      return selfGdr(parent);
     case "stageId":
       return parent.currentStageId;
     case "now":
-      return (/* @__PURE__ */ new Date()).toISOString();
+      return now;
     case "object": {
       const out = {};
-      for (const [k, v] of Object.entries(source.fields))
-        out[k] = resolveSpawnSource(v, parent, row);
+      for (const [k, v2] of Object.entries(source.fields))
+        out[k] = resolveSpawnSource(v2, parent, row, now);
       return out;
     }
     case "actor":
@@ -997,10 +1105,10 @@ function resolveSpawnSource(source, parent, row) {
       return null;
   }
 }
-function projectSpawnRow(parent, spawn, row) {
+function projectSpawnRow(parent, spawn, row, now) {
   const initialState = [];
   for (const entry of spawn.forEach.as.initialState ?? []) {
-    const raw = resolveSpawnSource(entry.value, parent, row), value = canonicaliseSpawnValue(entry.type, raw, parent.workflowResource);
+    const raw = resolveSpawnSource(entry.value, parent, row, now), value = canonicaliseSpawnValue(entry.type, raw, parent.workflowResource);
     initialState.push({
       type: entry.type,
       id: entry.id,
@@ -1009,13 +1117,13 @@ function projectSpawnRow(parent, spawn, row) {
   }
   const effectsContext = {};
   for (const [k, src] of Object.entries(spawn.forEach.as.effectsContext ?? {})) {
-    const v = resolveSpawnSource(src, parent, row);
-    v != null && (typeof v == "string" || typeof v == "number" || typeof v == "boolean" || typeof v == "object" && "id" in v && "type" in v) && (effectsContext[k] = v);
+    const v2 = resolveSpawnSource(src, parent, row, now);
+    v2 != null && (typeof v2 == "string" || typeof v2 == "number" || typeof v2 == "boolean" || typeof v2 == "object" && "id" in v2 && "type" in v2) && (effectsContext[k] = v2);
   }
   return { initialState, effectsContext };
 }
 function canonicaliseSpawnValue(slotType, value, workflowResource) {
-  return slotType === "workflow.state.doc.ref" ? coerceSpawnGdr(value, workflowResource) : slotType === "workflow.state.doc.refs" && Array.isArray(value) ? value.map((v) => coerceSpawnGdr(v, workflowResource)).filter((v) => v !== null) : value;
+  return slotType === "workflow.state.doc.ref" ? coerceSpawnGdr(value, workflowResource) : slotType === "workflow.state.doc.refs" && Array.isArray(value) ? value.map((v2) => coerceSpawnGdr(v2, workflowResource)).filter((v2) => v2 !== null) : value;
 }
 function coerceSpawnGdr(raw, workflowResource) {
   const toUri = (id) => isGdrUri(id) ? id : gdrFromResource(workflowResource, id);
@@ -1038,7 +1146,7 @@ async function resolveLogicalDefinition(client, ref, tags) {
   return await client.fetch(groq, params) ?? null;
 }
 async function prepareChildInstance(args) {
-  const { client, parent, task, spawn, initialState, effectsContext, actor } = args, definition = await resolveLogicalDefinition(client, spawn.definitionRef, parent.tags ?? []);
+  const { client, parent, task, spawn, initialState, effectsContext, actor, now } = args, definition = await resolveLogicalDefinition(client, spawn.definitionRef, parent.tags ?? []);
   if (definition === null) {
     const versionLabel = spawn.definitionRef.version === void 0 || spawn.definitionRef.version === "latest" ? "latest" : `v${spawn.definitionRef.version}`;
     throw new Error(
@@ -1048,7 +1156,7 @@ async function prepareChildInstance(args) {
   const childTags = parent.tags ?? [], childPrefix = childTags[0] ?? "wf", workflowResource = parent.workflowResource, childDocId = `${childPrefix}.wf-instance.${randomKey()}`, childRef = { id: gdrFromResource(workflowResource, childDocId), type: "workflow.instance" }, ancestors = [
     ...parent.ancestors,
     {
-      id: gdrFromResource(parent.workflowResource, parent._id),
+      id: selfGdr(parent),
       type: "workflow.instance"
     }
   ], inheritedPerspective = parent.perspective, childState = await resolveDeclaredState({
@@ -1056,6 +1164,7 @@ async function prepareChildInstance(args) {
     initialState,
     ctx: {
       client,
+      now,
       selfId: childDocId,
       tags: childTags,
       workflowResource,
@@ -1075,7 +1184,7 @@ async function prepareChildInstance(args) {
     }
   ), base = buildInstanceBase({
     id: childDocId,
-    now: (/* @__PURE__ */ new Date()).toISOString(),
+    now,
     tags: childTags,
     workflowResource,
     workflowId: definition.workflowId,
@@ -1111,7 +1220,9 @@ async function checkSpawnCompletion(client, entry, spawn) {
   }
 }
 async function invokeTask(args) {
-  const { client, instanceId, taskId, options } = args, ctx = await loadContext(client, instanceId);
+  const { client, instanceId, taskId, options } = args, ctx = await loadContext(client, instanceId, {
+    ...options?.clock ? { clock: options.clock } : {}
+  });
   return commitInvoke(ctx, taskId, options?.actor);
 }
 async function commitInvoke(ctx, taskId, actor) {
@@ -1123,41 +1234,41 @@ async function commitInvoke(ctx, taskId, actor) {
   const mutation = startMutation(ctx.instance), mutEntry = requireMutationTaskEntry(mutation, taskId);
   return await activateTask(ctx, mutation, task, mutEntry, actor), await persist(ctx, mutation), { invoked: !0, taskId };
 }
-async function autoResolveOnActivate(ctx, mutation, task, entry) {
+async function autoResolveOnActivate(ctx, mutation, task, entry, now) {
   const checks = [
     { filter: task.failWhen, outcome: "failed", systemId: "engine.failWhen" },
     { filter: task.completeWhen, outcome: "done", systemId: "engine.completeWhen" }
   ];
-  for (const { filter, outcome, systemId } of checks) {
-    if (filter === void 0 || !await ctxEvaluateFilter(ctx, filter)) continue;
-    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
-    return entry.status = outcome, entry.completedAt = completedAt, entry.completedBy = systemId, mutation.history.push(
-      taskStatusChangedEntry({
-        stageId: mutation.currentStageId,
-        taskId: task.id,
-        from: "active",
-        to: outcome,
-        actor: { kind: "system", id: systemId },
-        at: completedAt
-      })
-    ), !0;
-  }
+  for (const { filter, outcome, systemId } of checks)
+    if (filter !== void 0 && await ctxEvaluateFilter(ctx, filter))
+      return entry.status = outcome, entry.completedAt = now, entry.completedBy = systemId, mutation.history.push(
+        taskStatusChangedEntry({
+          stageId: mutation.currentStageId,
+          taskId: task.id,
+          from: "active",
+          to: outcome,
+          at: now,
+          actor: { kind: "system", id: systemId }
+        })
+      ), !0;
   return !1;
 }
 async function activateTask(ctx, mutation, task, entry, actor) {
-  if (entry.status = "active", entry.startedAt = (/* @__PURE__ */ new Date()).toISOString(), task.state !== void 0 && task.state.length > 0) {
+  const now = ctx.now;
+  if (entry.status = "active", entry.startedAt = now, task.state !== void 0 && task.state.length > 0) {
     const stage = findStage(ctx.definition, mutation.currentStageId);
     entry.state = await resolveTaskStateSlots({
       client: ctx.client,
       instance: ctx.instance,
       stage,
-      task
+      task,
+      now
     });
   }
-  if (!await autoResolveOnActivate(ctx, mutation, task, entry) && (mutation.history.push({
+  if (!await autoResolveOnActivate(ctx, mutation, task, entry, now) && (mutation.history.push({
     _key: randomKey(),
     _type: "workflow.history.taskActivated",
-    at: (/* @__PURE__ */ new Date()).toISOString(),
+    at: now,
     stageId: mutation.currentStageId,
     taskId: task.id,
     ...actor !== void 0 ? { actor } : {}
@@ -1177,18 +1288,19 @@ async function activateTask(ctx, mutation, task, entry, actor) {
       mutation.history.push({
         _key: randomKey(),
         _type: "workflow.history.spawned",
-        at: (/* @__PURE__ */ new Date()).toISOString(),
+        at: now,
         taskId: task.id,
         instanceRef: ref
       });
     if (await checkSpawnCompletion(ctx.client, entry, task.spawns)) {
       const previousStatus = entry.status;
-      entry.status = "done", entry.completedAt = (/* @__PURE__ */ new Date()).toISOString(), mutation.history.push(
+      entry.status = "done", entry.completedAt = now, mutation.history.push(
         taskStatusChangedEntry({
           stageId: mutation.currentStageId,
           taskId: task.id,
           from: previousStatus,
           to: "done",
+          at: now,
           ...actor !== void 0 ? { actor } : {}
         })
       );
@@ -1205,7 +1317,7 @@ async function buildStageTasks(ctx, stage) {
       status: inScope ? "pending" : "skipped",
       ...task.filter !== void 0 ? {
         filterEvaluation: {
-          at: (/* @__PURE__ */ new Date()).toISOString(),
+          at: ctx.now,
           truthy: inScope
         }
       } : {}
@@ -1217,7 +1329,9 @@ function activatesOnStageEnter(task) {
   return task.invokeOn === "stageEnter" || task.spawns !== void 0 || task.completeWhen !== void 0 || task.failWhen !== void 0;
 }
 async function setStage(args) {
-  const { client, instanceId, targetStageId, reason, options } = args, ctx = await loadContext(client, instanceId);
+  const { client, instanceId, targetStageId, reason, options } = args, ctx = await loadContext(client, instanceId, {
+    ...options?.clock ? { clock: options.clock } : {}
+  });
   return commitSetStage(ctx, targetStageId, reason, options?.actor);
 }
 async function enterStage(ctx, mutation, nextStage, actor, at) {
@@ -1229,7 +1343,8 @@ async function enterStage(ctx, mutation, nextStage, actor, at) {
     state: await resolveStageStateSlots({
       client: ctx.client,
       instance: ctx.instance,
-      stage: nextStage
+      stage: nextStage,
+      now: at
     }),
     tasks: await buildStageTasks(ctx, nextStage)
   };
@@ -1248,7 +1363,7 @@ async function enterStage(ctx, mutation, nextStage, actor, at) {
   nextStage.kind === "terminal" && (mutation.completedAt = at);
 }
 async function beginStageMove(ctx, currentStage, actor) {
-  const mutation = startMutation(ctx.instance), at = (/* @__PURE__ */ new Date()).toISOString();
+  const mutation = startMutation(ctx.instance), at = ctx.now;
   return await queueEffects(
     ctx,
     mutation,
@@ -1282,13 +1397,46 @@ async function commitSetStage(ctx, targetStageId, reason, actor) {
   };
 }
 async function persistStageMove(ctx, mutation, exitedStageId, enteredStageId) {
-  await persist(ctx, mutation), await reconcileStageGuards({
+  await persistThenDeploy(
+    ctx,
+    mutation,
+    () => deployStageGuards({
+      client: ctx.client,
+      clientForGdr: ctx.clientForGdr,
+      instance: materializeInstance(ctx.instance, mutation),
+      definition: ctx.definition,
+      stageId: enteredStageId,
+      now: ctx.now
+    })
+  ), await retractStageGuards({
     client: ctx.client,
     clientForGdr: ctx.clientForGdr,
     instance: ctx.instance,
     definition: ctx.definition,
-    exitedStageId,
-    enteredStageId
+    stageId: exitedStageId,
+    now: ctx.now
+  });
+}
+async function persistThenDeploy(ctx, mutation, deploy) {
+  const spawned = mutation.pendingCreates.length > 0, committed = await persist(ctx, mutation);
+  await deployOrRollback({
+    client: ctx.client,
+    instanceId: ctx.instance._id,
+    committedRev: committed._rev,
+    restore: instanceStateFields(ctx.instance),
+    unset: ctx.instance.completedAt === void 0 ? ["completedAt"] : [],
+    reversible: !spawned,
+    deploy
+  });
+}
+async function refreshStageGuards(ctx, mutation, stageId) {
+  await deployStageGuards({
+    client: ctx.client,
+    clientForGdr: ctx.clientForGdr,
+    instance: materializeInstance(ctx.instance, mutation),
+    definition: ctx.definition,
+    stageId,
+    now: ctx.now
   });
 }
 async function commitTransition(ctx, action, actor) {
@@ -1330,15 +1478,18 @@ async function pickTransition(ctx, stage, action) {
     if (await ctxEvaluateFilter(ctx, candidate.filter)) return candidate;
 }
 async function evaluateAutoTransitions(args) {
-  const { client, instanceId, options, clientForGdr } = args, ctx = await loadContext(client, instanceId, clientForGdr ? { clientForGdr } : void 0);
+  const { client, instanceId, options, clientForGdr, clock } = args, ctx = await loadContext(client, instanceId, {
+    ...clientForGdr ? { clientForGdr } : {},
+    ...clock ? { clock } : {}
+  });
   return commitTransition(ctx, void 0, options?.actor);
 }
-async function primeInitialStage(client, instanceId, actor, clientForGdr) {
+async function primeInitialStage(client, instanceId, actor, clientForGdr, clock) {
   const instance = await client.getDocument(instanceId);
   if (!instance || instance.stages.length > 0 || instance.pendingEffects.length > 0) return;
   const definition = JSON.parse(instance.definitionSnapshot), stage = definition.stages.find((s) => s.id === instance.currentStageId);
   if (stage === void 0) return;
-  const snapshot = await hydrateSnapshot({
+  const now = (clock ?? wallClock)(), snapshot = await hydrateSnapshot({
     client,
     clientForGdr: clientForGdr ?? (() => client),
     instance,
@@ -1349,7 +1500,7 @@ async function primeInitialStage(client, instanceId, actor, clientForGdr) {
       filter: task.filter,
       definition,
       snapshot,
-      params: buildParams(instance)
+      params: buildParams(instance, now)
     });
     tasks.push({
       _key: randomKey(),
@@ -1360,8 +1511,8 @@ async function primeInitialStage(client, instanceId, actor, clientForGdr) {
   const initialStageEntry = {
     _key: randomKey(),
     id: stage.id,
-    enteredAt: (/* @__PURE__ */ new Date()).toISOString(),
-    state: await resolveStageStateSlots({ client, instance, stage }),
+    enteredAt: now,
+    state: await resolveStageStateSlots({ client, instance, stage, now }),
     tasks
   }, pendingEffects = [], newHistory = [...instance.history];
   for (const effect of stage.onEnter ?? []) {
@@ -1369,29 +1520,44 @@ async function primeInitialStage(client, instanceId, actor, clientForGdr) {
       bindings: effect.bindings,
       staticInput: effect.input,
       instance,
+      now,
       ...actor !== void 0 ? { actor } : {}
     }), { pending, history } = buildQueuedEffect(
       effect,
       { kind: "stageEnter", id: stage.id },
       params,
-      actor
+      actor,
+      now
     );
     pendingEffects.push(pending), newHistory.push(history);
   }
-  await client.patch(instance._id).set({
+  const committed = await client.patch(instance._id).set({
     stages: [initialStageEntry],
     pendingEffects,
     history: newHistory,
-    lastChangedAt: (/* @__PURE__ */ new Date()).toISOString()
-  }).ifRevisionId(instance._rev).commit(), await deployStageGuards({
+    lastChangedAt: now
+  }).ifRevisionId(instance._rev).commit();
+  await deployOrRollback({
     client,
-    clientForGdr: clientForGdr ?? (() => client),
-    instance,
-    definition,
-    stageId: stage.id
-  }), await autoActivatePrimedTasks(client, instanceId, definition, stage, actor, clientForGdr);
+    instanceId: instance._id,
+    committedRev: committed._rev,
+    restore: {
+      stages: instance.stages,
+      pendingEffects: instance.pendingEffects,
+      history: instance.history
+    },
+    reversible: !0,
+    deploy: () => deployStageGuards({
+      client,
+      clientForGdr: clientForGdr ?? (() => client),
+      instance,
+      definition,
+      stageId: stage.id,
+      now
+    })
+  }), await autoActivatePrimedTasks(client, instanceId, definition, stage, actor, clientForGdr, clock);
 }
-async function autoActivatePrimedTasks(client, instanceId, definition, stage, actor, clientForGdr) {
+async function autoActivatePrimedTasks(client, instanceId, definition, stage, actor, clientForGdr, clock) {
   const resolvedClientForGdr = clientForGdr ?? (() => client);
   for (const task of stage.tasks ?? []) {
     if (!activatesOnStageEnter(task)) continue;
@@ -1401,7 +1567,8 @@ async function autoActivatePrimedTasks(client, instanceId, definition, stage, ac
       client,
       clientForGdr: resolvedClientForGdr,
       instance: updated,
-      definition
+      definition,
+      ...clock ? { clock } : {}
     }), mutation = startMutation(updated), mutEntry = currentTasks(mutation).find((t) => t.id === task.id);
     mutEntry && mutEntry.status === "pending" && (await activateTask(updatedCtx, mutation, task, mutEntry, actor), await persist(updatedCtx, mutation));
   }
@@ -1419,8 +1586,11 @@ async function gatherAutoResolveCandidates(ctx, tasks) {
     }
   return candidates;
 }
-async function resolveCompleteWhen(client, instanceId, clientForGdr) {
-  const ctx = await loadContext(client, instanceId, clientForGdr ? { clientForGdr } : void 0), stage = findStage(ctx.definition, ctx.instance.currentStageId), tasksWithAutoPredicate = (stage.tasks ?? []).filter(
+async function resolveCompleteWhen(client, instanceId, clientForGdr, clock) {
+  const ctx = await loadContext(client, instanceId, {
+    ...clientForGdr ? { clientForGdr } : {},
+    ...clock ? { clock } : {}
+  }), stage = findStage(ctx.definition, ctx.instance.currentStageId), tasksWithAutoPredicate = (stage.tasks ?? []).filter(
     (t) => t.completeWhen !== void 0 || t.failWhen !== void 0
   );
   if (tasksWithAutoPredicate.length === 0) return 0;
@@ -1434,65 +1604,71 @@ async function resolveCompleteWhen(client, instanceId, clientForGdr) {
     const previousStatus = mutEntry.status, actor = {
       kind: "system",
       id: outcome === "failed" ? "engine.failWhen" : "engine.completeWhen"
-    };
-    mutEntry.status = outcome, mutEntry.completedAt = (/* @__PURE__ */ new Date()).toISOString(), mutEntry.completedBy = actor.id, mutation.history.push(
+    }, now = ctx.now;
+    mutEntry.status = outcome, mutEntry.completedAt = now, mutEntry.completedBy = actor.id, mutation.history.push(
       taskStatusChangedEntry({
         stageId: stage.id,
         taskId: task.id,
         from: previousStatus,
         to: outcome,
+        at: now,
         actor
       })
     ), count++;
   }
   return count > 0 && await persist(ctx, mutation), count;
 }
-async function cascadeAutoTransitions(client, instanceId, actor, clientForGdr) {
+async function cascadeAutoTransitions(client, instanceId, actor, clientForGdr, clock) {
   let count = 0;
   for (; ; ) {
-    if (await resolveCompleteWhen(client, instanceId, clientForGdr), !(await evaluateAutoTransitions({
+    if (await resolveCompleteWhen(client, instanceId, clientForGdr, clock), !(await evaluateAutoTransitions({
       client,
       instanceId,
       ...actor !== void 0 ? { options: { actor } } : {},
-      ...clientForGdr ? { clientForGdr } : {}
+      ...clientForGdr ? { clientForGdr } : {},
+      ...clock ? { clock } : {}
     })).fired) return count;
-    if (count++, count > CASCADE_LIMIT)
-      throw new Error(
-        `Cascade did not stabilise after ${CASCADE_LIMIT} auto-transitions on ${instanceId} \u2014 possible infinite loop`
-      );
+    if (count++, count >= CASCADE_LIMIT)
+      throw new CascadeLimitError({ instanceId, limit: CASCADE_LIMIT });
   }
 }
-async function propagateToAncestors(client, instanceId, actor, clientForGdr) {
-  const instance = await client.getDocument(instanceId);
-  if (!instance || instance.ancestors.length === 0) return;
-  const parentRef = instance.ancestors[instance.ancestors.length - 1];
+async function findSatisfiedParentSpawn(client, child) {
+  const parentRef = child.ancestors.at(-1);
   if (parentRef === void 0) return;
-  const parentId = gdrToBareId(parentRef.id), parent = await client.getDocument(parentId);
-  if (!parent || parent._type !== "workflow.instance" || typeof parent.definitionSnapshot != "string")
-    return;
-  const parentDefinition = JSON.parse(parent.definitionSnapshot), parentStage = parentDefinition.stages.find((s) => s.id === parent.currentStageId);
-  if (parentStage === void 0) return;
-  const parentCurrentTasks = findCurrentTasks(parent), parentTask = (parentStage.tasks ?? []).find((t) => t.spawns === void 0 ? !1 : parentCurrentTasks.find((e) => e.id === t.id)?.spawnedInstances?.some((r) => gdrToBareId(r.id) === instance._id) ?? !1);
-  if (parentTask === void 0) return;
-  const parentEntry = parentCurrentTasks.find((e) => e.id === parentTask.id);
-  if (parentEntry === void 0 || parentEntry.status === "done" || !await checkSpawnCompletion(client, parentEntry, parentTask.spawns)) return;
-  const ctx = await buildEngineContext({
+  const parent = await client.getDocument(gdrToBareId(parentRef.id));
+  if (!parent || parent._type !== "workflow.instance" || typeof parent.definitionSnapshot != "string") return;
+  const definition = JSON.parse(parent.definitionSnapshot), stage = definition.stages.find((s) => s.id === parent.currentStageId);
+  if (stage === void 0) return;
+  const parentCurrentTasks = findCurrentTasks(parent), task = (stage.tasks ?? []).find((t) => t.spawns === void 0 ? !1 : parentCurrentTasks.find((e) => e.id === t.id)?.spawnedInstances?.some((r) => gdrToBareId(r.id) === child._id) ?? !1);
+  if (task?.spawns === void 0) return;
+  const entry = parentCurrentTasks.find((e) => e.id === task.id);
+  if (!(entry === void 0 || entry.status === "done") && await checkSpawnCompletion(client, entry, task.spawns))
+    return { parent, definition, stage, task };
+}
+async function propagateToAncestors(client, instanceId, actor, clientForGdr, clock) {
+  const instance = await client.getDocument(instanceId);
+  if (!instance) return;
+  const found = await findSatisfiedParentSpawn(client, instance);
+  if (found === void 0) return;
+  const { parent, definition, stage, task } = found, ctx = await buildEngineContext({
     client,
     clientForGdr: clientForGdr ?? (() => client),
     instance: parent,
-    definition: parentDefinition
-  }), mutation = startMutation(parent), mutEntry = currentTasks(mutation).find((e) => e.id === parentTask.id);
+    definition,
+    ...clock ? { clock } : {}
+  }), mutation = startMutation(parent), mutEntry = currentTasks(mutation).find((e) => e.id === task.id);
   if (mutEntry === void 0) return;
-  const previousStatus = mutEntry.status;
-  mutEntry.status = "done", mutEntry.completedAt = (/* @__PURE__ */ new Date()).toISOString(), mutation.history.push(
+  const previousStatus = mutEntry.status, now = ctx.now;
+  mutEntry.status = "done", mutEntry.completedAt = now, mutation.history.push(
     taskStatusChangedEntry({
-      stageId: parentStage.id,
-      taskId: parentTask.id,
+      stageId: stage.id,
+      taskId: task.id,
       from: previousStatus,
       to: "done",
+      at: now,
       ...actor !== void 0 ? { actor } : {}
     })
-  ), await persist(ctx, mutation), await cascadeAutoTransitions(client, parentId, actor, clientForGdr), await propagateToAncestors(client, parentId, actor, clientForGdr);
+  ), await persist(ctx, mutation), await cascadeAutoTransitions(client, parent._id, actor, clientForGdr, clock), await propagateToAncestors(client, parent._id, actor, clientForGdr, clock);
 }
 function startMutation(instance) {
   return {
@@ -1521,7 +1697,7 @@ function taskStatusChangedEntry(args) {
   return {
     _key: randomKey(),
     _type: "workflow.history.taskStatusChanged",
-    at: args.at ?? (/* @__PURE__ */ new Date()).toISOString(),
+    at: args.at,
     stageId: args.stageId,
     taskId: args.taskId,
     from: args.from,
@@ -1561,19 +1737,31 @@ function stageTransitionHistory(args) {
     }
   ];
 }
-async function persist(ctx, mutation) {
-  const set = {
+function instanceStateFields(src) {
+  const fields = {
+    currentStageId: src.currentStageId,
+    state: src.state,
+    stages: src.stages,
+    pendingEffects: src.pendingEffects,
+    effectHistory: src.effectHistory,
+    effectsContext: src.effectsContext,
+    history: src.history
+  };
+  return src.completedAt !== void 0 && (fields.completedAt = src.completedAt), fields;
+}
+function materializeInstance(base, mutation) {
+  return {
+    ...base,
     currentStageId: mutation.currentStageId,
     state: mutation.state,
-    stages: mutation.stages,
-    pendingEffects: mutation.pendingEffects,
-    effectHistory: mutation.effectHistory,
-    effectsContext: mutation.effectsContext,
-    history: mutation.history,
-    lastChangedAt: (/* @__PURE__ */ new Date()).toISOString()
+    stages: mutation.stages
   };
-  mutation.completedAt !== void 0 && (set.completedAt = mutation.completedAt);
-  const pendingCreates = mutation.pendingCreates;
+}
+async function persist(ctx, mutation) {
+  const set = {
+    ...instanceStateFields(mutation),
+    lastChangedAt: ctx.now
+  }, pendingCreates = mutation.pendingCreates;
   if (pendingCreates.length === 0)
     return ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev).commit();
   const tx = ctx.client.transaction();
@@ -1581,7 +1769,7 @@ async function persist(ctx, mutation) {
   tx.patch(ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev)), await tx.commit(), mutation.pendingCreates = [];
   const actorForPriming = void 0;
   for (const body of pendingCreates)
-    await primeInitialStage(ctx.client, body._id, actorForPriming, ctx.clientForGdr), await cascadeAutoTransitions(ctx.client, body._id, actorForPriming, ctx.clientForGdr), await propagateToAncestors(ctx.client, body._id, actorForPriming, ctx.clientForGdr);
+    await primeInitialStage(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await cascadeAutoTransitions(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await propagateToAncestors(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock);
   const reloaded = await ctx.client.getDocument(ctx.instance._id);
   if (!reloaded)
     throw new Error(`Instance ${ctx.instance._id} disappeared after transaction commit`);
@@ -1622,7 +1810,9 @@ function findCurrentTasks(instance) {
   return findCurrentStageEntry(instance)?.tasks ?? [];
 }
 async function completeEffect(args) {
-  const { client, instanceId, effectKey, status, outputs, detail, error, durationMs, options } = args, ctx = await loadContext(client, instanceId);
+  const { client, instanceId, effectKey, status, outputs, detail, error, durationMs, options } = args, ctx = await loadContext(client, instanceId, {
+    ...options?.clock ? { clock: options.clock } : {}
+  });
   return commitCompleteEffect(
     ctx,
     effectKey,
@@ -1664,7 +1854,7 @@ async function commitCompleteEffect(ctx, effectKey, status, outputs, detail, err
     throw new Error(`Pending effect "${effectKey}" not found on instance ${ctx.instance._id}`);
   const mutation = startMutation(ctx.instance);
   mutation.pendingEffects = mutation.pendingEffects.filter((e) => e._key !== effectKey);
-  const ranAt = (/* @__PURE__ */ new Date()).toISOString();
+  const ranAt = ctx.now;
   return mutation.effectHistory.push(
     buildEffectHistoryEntry(pending, { status, ranAt, actor, detail, error, durationMs, outputs })
   ), status === "done" && outputs !== void 0 && upsertEffectsContext(mutation, outputs), mutation.history.push({
@@ -1679,7 +1869,7 @@ async function commitCompleteEffect(ctx, effectKey, status, outputs, detail, err
     ...actor !== void 0 ? { actor } : {}
   }), await persist(ctx, mutation), { effectKey, status };
 }
-function buildQueuedEffect(effect, origin, params, actor) {
+function buildQueuedEffect(effect, origin, params, actor, now) {
   const key = randomKey(), pending = {
     _key: key,
     _type: "workflow.pendingEffect",
@@ -1690,11 +1880,11 @@ function buildQueuedEffect(effect, origin, params, actor) {
     params,
     origin,
     ...actor !== void 0 ? { actor } : {},
-    queuedAt: (/* @__PURE__ */ new Date()).toISOString()
+    queuedAt: now
   }, history = {
     _key: randomKey(),
     _type: "workflow.history.effectQueued",
-    at: (/* @__PURE__ */ new Date()).toISOString(),
+    at: now,
     effectKey: key,
     effectId: effect.id,
     origin
@@ -1703,7 +1893,7 @@ function buildQueuedEffect(effect, origin, params, actor) {
 }
 async function queueEffects(ctx, mutation, effects, origin, actor, callerParams) {
   if (!effects) return;
-  const liveInstance = {
+  const now = ctx.now, liveInstance = {
     ...ctx.instance,
     state: mutation.state,
     stages: mutation.stages,
@@ -1714,22 +1904,21 @@ async function queueEffects(ctx, mutation, effects, origin, actor, callerParams)
       bindings: effect.bindings,
       staticInput: effect.input,
       instance: liveInstance,
+      now,
       ...callerParams !== void 0 ? { params: callerParams } : {},
       ...actor !== void 0 ? { actor } : {}
-    }), { pending, history } = buildQueuedEffect(effect, origin, params, actor);
+    }), { pending, history } = buildQueuedEffect(effect, origin, params, actor, now);
     mutation.pendingEffects.push(pending), mutation.history.push(history);
   }
 }
-class ActionParamsInvalidError extends Error {
-  action;
-  taskId;
-  issues;
-  constructor(args) {
-    const lines = args.issues.map((i) => `  - ${i.paramId}: ${i.reason}`).join(`
-`);
-    super(`Action "${args.action}" on task "${args.taskId}" rejected: invalid params
-${lines}`), this.name = "ActionParamsInvalidError", this.action = args.action, this.taskId = args.taskId, this.issues = args.issues;
-  }
+const STATE_OP_TYPES = [
+  "workflow.op.state.set",
+  "workflow.op.state.append",
+  "workflow.op.state.updateWhere",
+  "workflow.op.state.removeWhere"
+];
+function isStateOp(summary) {
+  return STATE_OP_TYPES.includes(summary.opType);
 }
 function validateActionParams(action, taskId, callerParams) {
   const declared = action.params ?? [], params = callerParams ?? {}, issues = [];
@@ -1766,7 +1955,7 @@ function checkParamType(value, decl) {
     case "doc.ref":
       return hasStringField(value, "id");
     case "doc.refs":
-      return Array.isArray(value) && value.every((v) => checkParamType(v, { paramType: "doc.ref" }));
+      return Array.isArray(value) && value.every((v2) => checkParamType(v2, { paramType: "doc.ref" }));
     case "json":
       return !0;
     default:
@@ -1774,15 +1963,15 @@ function checkParamType(value, decl) {
   }
 }
 async function runActionOps(args) {
-  const { ops, mutation, stageId, taskId, actionName, params, actor } = args;
+  const { ops, mutation, stageId, taskId, actionName, params, actor, self, now } = args;
   if (ops === void 0 || ops.length === 0) return [];
   const summaries = [];
   for (const op of ops) {
-    const summary = applyOp(op, { mutation, stageId, taskId, params, actor });
+    const summary = applyOp(op, { mutation, stageId, taskId, params, actor, self, now });
     summaries.push(summary), mutation.history.push({
       _key: randomKey(),
       _type: "workflow.history.opApplied",
-      at: (/* @__PURE__ */ new Date()).toISOString(),
+      at: now,
       stageId,
       taskId,
       actionId: actionName,
@@ -1841,8 +2030,8 @@ function applyStateUpdateWhere(op, ctx) {
     /*createIfMissing*/
     !1
   ), resolvedMerge = {};
-  for (const [k, v] of Object.entries(op.merge))
-    resolvedMerge[k] = resolveOpSource(v, ctx);
+  for (const [k, v2] of Object.entries(op.merge))
+    resolvedMerge[k] = resolveOpSource(v2, ctx);
   return slot !== void 0 && Array.isArray(slot.value) && (slot.value = slot.value.map(
     (row) => evalOpPredicate(op.where, row, ctx) ? { ...row, ...resolvedMerge } : row
   )), { opType: op.type, target: op.target, resolved: { merge: resolvedMerge } };
@@ -1885,18 +2074,11 @@ function locateSlot(ctx, target, createIfMissing) {
   }, host.push(slot)), slot;
 }
 function resolveOpSource(src, ctx) {
+  const staticValue = resolveStaticSource(src, ctx);
+  if (staticValue.handled) return staticValue.value;
   switch (src.source) {
-    case "literal":
-      return src.value;
-    case "param":
-      return ctx.params[src.paramId];
-    case "actor":
-      return ctx.actor;
-    case "now":
-      return (/* @__PURE__ */ new Date()).toISOString();
     case "self":
-      return;
-    // Not applicable inside ops; reserved for higher-level binding.
+      return ctx.self;
     case "stageId":
       return ctx.stageId;
     case "stateRead": {
@@ -1906,8 +2088,8 @@ function resolveOpSource(src, ctx) {
     case "effectOutput": {
       const entry = ctx.mutation.effectsContext.find((e) => e.id === src.contextId);
       if (entry === void 0) return null;
-      const v = src.path !== void 0 ? getPath(entry.value, src.path) : entry.value;
-      return v === void 0 ? null : v;
+      const v2 = src.path !== void 0 ? getPath(entry.value, src.path) : entry.value;
+      return v2 === void 0 ? null : v2;
     }
     case "object": {
       const out = {};
@@ -1915,6 +2097,11 @@ function resolveOpSource(src, ctx) {
         out[field] = resolveOpSource(fieldSrc, ctx);
       return out;
     }
+    case "row":
+    case "parentState":
+      return;
+    default:
+      return;
   }
 }
 function slotValue(slots, slotId) {
@@ -1934,8 +2121,23 @@ function evalOpPredicate(p, row, ctx) {
   return row[p.field] === target;
 }
 async function fireAction(args) {
-  const { client, instanceId, taskId, action, params, options } = args, ctx = await loadContext(client, instanceId);
-  return commitAction(ctx, taskId, action, params, options?.actor);
+  const { client, instanceId, taskId, action, params, options } = args;
+  for (let attempt = 1; attempt <= CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS; attempt++) {
+    const ctx = await loadContext(client, instanceId, {
+      ...options?.clock ? { clock: options.clock } : {}
+    });
+    try {
+      return await commitAction(ctx, taskId, action, params, options?.actor);
+    } catch (error) {
+      if (!isRevisionConflict(error)) throw error;
+    }
+  }
+  throw new ConcurrentFireActionError({
+    instanceId,
+    taskId,
+    action,
+    attempts: CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS
+  });
 }
 async function resolveActionCommit(ctx, taskId, actionName, callerParams) {
   const { stage, task } = findTaskInCurrentStage(ctx, taskId), action = (task.actions ?? []).find((a) => a.id === actionName);
@@ -1951,15 +2153,16 @@ async function resolveActionCommit(ctx, taskId, actionName, callerParams) {
   const params = validateActionParams(action, taskId, callerParams);
   return { stage, task, action, params };
 }
-function applyActionSetStatus(action, mutation, mutEntry, stageId, taskId, actor) {
+function applyActionSetStatus(action, mutation, mutEntry, stageId, taskId, actor, now) {
   if (action.setStatus === void 0) return;
   const initialStatus = mutEntry.status, newStatus = action.setStatus;
-  return mutEntry.status = newStatus, mutEntry.completedAt = (/* @__PURE__ */ new Date()).toISOString(), actor && (mutEntry.completedBy = actor.id), mutation.history.push(
+  return mutEntry.status = newStatus, mutEntry.completedAt = now, actor && (mutEntry.completedBy = actor.id), mutation.history.push(
     taskStatusChangedEntry({
       stageId,
       taskId,
       from: initialStatus,
       to: newStatus,
+      at: now,
       ...actor !== void 0 ? { actor } : {}
     })
   ), newStatus;
@@ -1970,11 +2173,11 @@ async function commitAction(ctx, taskId, actionName, callerParams, actor) {
     taskId,
     actionName,
     callerParams
-  ), mutation = startMutation(ctx.instance), mutEntry = requireMutationTaskEntry(mutation, taskId);
+  ), mutation = startMutation(ctx.instance), mutEntry = requireMutationTaskEntry(mutation, taskId), now = ctx.now;
   mutation.history.push({
     _key: randomKey(),
     _type: "workflow.history.actionFired",
-    at: (/* @__PURE__ */ new Date()).toISOString(),
+    at: now,
     stageId: stage.id,
     taskId,
     actionId: actionName,
@@ -1987,8 +2190,10 @@ async function commitAction(ctx, taskId, actionName, callerParams, actor) {
     taskId,
     actionName,
     params,
-    actor
-  }), newStatus = applyActionSetStatus(action, mutation, mutEntry, stage.id, taskId, actor);
+    actor,
+    self: selfGdr(ctx.instance),
+    now
+  }), newStatus = applyActionSetStatus(action, mutation, mutEntry, stage.id, taskId, actor, now);
   return await queueEffects(
     ctx,
     mutation,
@@ -1999,7 +2204,11 @@ async function commitAction(ctx, taskId, actionName, callerParams, actor) {
     },
     actor,
     params
-  ), await persist(ctx, mutation), {
+  ), await persistThenDeploy(
+    ctx,
+    mutation,
+    () => ranOps.some(isStateOp) ? refreshStageGuards(ctx, mutation, stage.id) : Promise.resolve()
+  ), {
     fired: !0,
     taskId,
     action: actionName,
@@ -2038,7 +2247,7 @@ async function resolveAccess(client, args = {}) {
   const overrideActor = args.override?.actor, overrideGrants = args.override?.grants;
   if (overrideActor !== void 0 && overrideGrants !== void 0)
     return { actor: overrideActor, grants: overrideGrants };
-  const requestFn = client.request;
+  const requestFn = client.request === void 0 ? void 0 : (opts) => client.request(opts);
   if (requestFn === void 0) {
     if (overrideActor === void 0)
       throw new Error(
@@ -2113,7 +2322,7 @@ function canonicalTag(tags) {
 }
 const WILDCARD_ROLE = "*";
 async function evaluateInstance(args) {
-  const { client, tags, instanceId, resourceClients } = args;
+  const { client, tags, instanceId, resourceClients } = args, now = (args.clock ?? wallClock)();
   validateTags(tags);
   const { actor, grants } = await resolveAccess(client, {
     ...args.access !== void 0 ? { override: args.access } : {},
@@ -2145,7 +2354,8 @@ async function evaluateInstance(args) {
         definition,
         actor,
         grants,
-        snapshot
+        snapshot,
+        now
       })
     );
   const transitionEvaluations = [];
@@ -2156,7 +2366,7 @@ async function evaluateInstance(args) {
         filter: transition.filter,
         definition,
         snapshot,
-        params: buildParams(instance)
+        params: buildParams(instance, now)
       })
     });
   const currentStage = {
@@ -2174,7 +2384,7 @@ async function evaluateInstance(args) {
   };
 }
 async function evaluateTask(args) {
-  const { task, statusEntry, instance, definition, actor, grants, snapshot } = args, status = statusEntry?.status ?? "pending", actions = [];
+  const { task, statusEntry, instance, definition, actor, grants, snapshot, now } = args, status = statusEntry?.status ?? "pending", actions = [];
   for (const action of task.actions ?? [])
     actions.push(
       await evaluateAction({
@@ -2186,7 +2396,8 @@ async function evaluateTask(args) {
         definition,
         actor,
         ...grants !== void 0 ? { grants } : {},
-        snapshot
+        snapshot,
+        now
       })
     );
   return {
@@ -2200,9 +2411,9 @@ async function evaluateTask(args) {
   };
 }
 async function evaluateAction(args) {
-  const { action, task, status, instance, definition, actor, grants, snapshot } = args, syncReason = lifecycleReason(instance, definition, status) ?? actorReason(action, task, actor);
+  const { action, task, status, instance, definition, actor, grants, snapshot, now } = args, syncReason = lifecycleReason(instance, definition, status) ?? actorReason(action, task, actor);
   if (syncReason !== void 0) return disabled(action, syncReason);
-  const asyncReason = await permissionReason(action, instance, actor, grants) ?? await filterReason(action, instance, definition, snapshot);
+  const asyncReason = await permissionReason(action, instance, actor, grants) ?? await filterReason(action, instance, definition, snapshot, now);
   return asyncReason !== void 0 ? disabled(action, asyncReason) : { action, allowed: !0 };
 }
 function lifecycleReason(instance, definition, status) {
@@ -2231,12 +2442,12 @@ async function permissionReason(action, instance, actor, grants) {
   }))
     return { kind: "permission-denied", permission, matchingGrants: grants.length };
 }
-async function filterReason(action, instance, definition, snapshot) {
+async function filterReason(action, instance, definition, snapshot, now) {
   if (!(action.filter === void 0 || await evaluateFilter({
     filter: action.filter,
     definition,
     snapshot,
-    params: buildParams(instance)
+    params: buildParams(instance, now)
   })))
     return { kind: "filter-failed", filter: action.filter };
 }
@@ -2261,6 +2472,43 @@ function parseDefinitionSnapshot(instance) {
     );
   }
 }
+const resourceKey = (r) => `${r.type}.${r.id}`;
+function guardsForResource(client) {
+  return client.fetch("*[_type == $t] | order(_id asc)", { t: GUARD_DOC_TYPE });
+}
+async function guardsForInstance(args) {
+  const { client, clientForGdr, instance } = args, clientsByResource = /* @__PURE__ */ new Map([
+    [resourceKey(instance.workflowResource), client]
+  ]), stateUris = [
+    ...collectSlotDocUris(instance.state),
+    ...instance.stages.flatMap((stage) => collectSlotDocUris(stage.state))
+  ];
+  for (const uri of stateUris) {
+    const parsed = tryParseGdr(uri);
+    if (parsed === void 0) continue;
+    const key = resourceKey(resourceFromParsed(parsed));
+    clientsByResource.has(key) || clientsByResource.set(key, clientForGdr(parsed));
+  }
+  const perResource = await Promise.all(
+    [...clientsByResource.values()].map(
+      (c) => c.fetch("*[_type == $t && sourceInstanceId == $id]", {
+        t: GUARD_DOC_TYPE,
+        id: instance._id
+      })
+    )
+  );
+  return dedupById(perResource.flat());
+}
+function tryParseGdr(uri) {
+  try {
+    return parseGdr(uri);
+  } catch {
+    return;
+  }
+}
+function dedupById(guards) {
+  return [...new Map(guards.map((g) => [g._id, g])).values()].sort((a, b) => a._id.localeCompare(b._id));
+}
 class ActionDisabledError extends Error {
   reason;
   taskId;
@@ -2371,14 +2619,14 @@ function isDefinitionUnchanged(existing, expected) {
 }
 function stripSystemFields(doc) {
   const out = {};
-  for (const [k, v] of Object.entries(doc))
-    k === "_rev" || k === "_createdAt" || k === "_updatedAt" || (out[k] = v);
+  for (const [k, v2] of Object.entries(doc))
+    k === "_rev" || k === "_createdAt" || k === "_updatedAt" || (out[k] = v2);
   return out;
 }
 function stableStringify(value) {
   return value === null || typeof value != "object" ? JSON.stringify(value) : Array.isArray(value) ? `[${value.map(stableStringify).join(",")}]` : `{${Object.entries(value).toSorted(
     ([a], [b]) => a.localeCompare(b)
-  ).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+  ).map(([k, v2]) => `${JSON.stringify(k)}:${stableStringify(v2)}`).join(",")}}`;
 }
 async function loadDefinition(client, workflowId, version, tags) {
   if (version !== void 0) {
@@ -2418,9 +2666,9 @@ async function resolveOperationContext(args) {
     clientForGdr: buildClientForGdr(args.client, args.resourceClients)
   };
 }
-async function cascade(client, instanceId, actor, clientForGdr) {
-  const count = await cascadeAutoTransitions(client, instanceId, actor, clientForGdr);
-  return await propagateToAncestors(client, instanceId, actor, clientForGdr), count;
+async function cascade(client, instanceId, actor, clientForGdr, clock) {
+  const count = await cascadeAutoTransitions(client, instanceId, actor, clientForGdr, clock);
+  return await propagateToAncestors(client, instanceId, actor, clientForGdr, clock), count;
 }
 function buildClientForGdr(defaultClient, resolver) {
   return resolver === void 0 ? () => defaultClient : (parsed) => resolver(parsed) ?? defaultClient;
@@ -2512,16 +2760,17 @@ const workflow = {
       effectsContext,
       instanceId,
       perspective
-    } = args, { actor, clientForGdr } = await resolveOperationContext(args), definition = await loadDefinition(client, workflowId, version, tags), id = instanceId ?? `${canonicalTag(tags)}.wf-instance.${randomKey()}`;
+    } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, definition = await loadDefinition(client, workflowId, version, tags), id = instanceId ?? `${canonicalTag(tags)}.wf-instance.${randomKey()}`;
     if (definition.stages.find((s) => s.id === definition.initialStageId) === void 0)
       throw new Error(
         `Initial stage "${definition.initialStageId}" missing in ${workflowId} v${definition.version}`
       );
-    const now = (/* @__PURE__ */ new Date()).toISOString(), effectsContextEntries = effectsContext ? toEffectsContextEntries(effectsContext) : [], resolvedState = await resolveDeclaredState({
+    const now = clock(), effectsContextEntries = effectsContext ? toEffectsContextEntries(effectsContext) : [], resolvedState = await resolveDeclaredState({
       slotDefs: definition.state ?? [],
       initialState: initialState ?? [],
       ctx: {
         client,
+        now,
         selfId: id,
         tags,
         workflowResource,
@@ -2543,7 +2792,7 @@ const workflow = {
       initialStageId: definition.initialStageId,
       actor
     });
-    return await client.create(base), await primeInitialStage(client, id, actor, clientForGdr), await cascade(client, id, actor, clientForGdr), reload(client, id, tags);
+    return await client.create(base), await primeInitialStage(client, id, actor, clientForGdr, clock), await cascade(client, id, actor, clientForGdr, clock), reload(client, id, tags);
   },
   /**
    * Fire an action against a task. If the task is pending, it is
@@ -2565,7 +2814,7 @@ const workflow = {
       params,
       idempotent,
       resourceClients
-    } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), before = await reload(client, instanceId, tags), taskEntry = before.stages.find(
+    } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, before = await reload(client, instanceId, tags), taskEntry = before.stages.find(
       (s) => s.id === before.currentStageId && s.exitedAt === void 0
     )?.tasks.find((t) => t.id === taskId);
     if (taskEntry === void 0 && idempotent === !0)
@@ -2575,6 +2824,7 @@ const workflow = {
       tags,
       instanceId,
       access,
+      clock,
       ...resourceClients !== void 0 ? { resourceClients } : {}
     })).currentStage.tasks.find((t) => t.task.id === taskId)?.actions.find((a) => a.action.id === action);
     if (actionEval !== void 0 && !actionEval.allowed && actionEval.disabledReason)
@@ -2587,7 +2837,7 @@ const workflow = {
       client,
       instanceId,
       taskId,
-      options: { actor }
+      options: { actor, clock }
     });
     const actionResult = await fireAction({
       client,
@@ -2595,8 +2845,8 @@ const workflow = {
       taskId,
       action,
       ...params !== void 0 ? { params } : {},
-      options: { actor }
-    }), cascaded = await cascade(client, instanceId, actor, clientForGdr);
+      options: { actor, clock }
+    }), cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
       instance: await reload(client, instanceId, tags),
       cascaded,
@@ -2612,7 +2862,7 @@ const workflow = {
    * reference them. Cascades after.
    */
   completeEffect: async (args) => {
-    const { client, tags, instanceId, effectKey, status, outputs, detail, error, durationMs } = args, { actor, clientForGdr } = await resolveOperationContext(args);
+    const { client, tags, instanceId, effectKey, status, outputs, detail, error, durationMs } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
     await completeEffect({
       client,
       instanceId,
@@ -2622,9 +2872,9 @@ const workflow = {
       ...detail !== void 0 ? { detail } : {},
       ...error !== void 0 ? { error } : {},
       ...durationMs !== void 0 ? { durationMs } : {},
-      ...actor !== void 0 ? { options: { actor } } : {}
+      options: { ...actor !== void 0 ? { actor } : {}, clock }
     });
-    const cascaded = await cascade(client, instanceId, actor, clientForGdr);
+    const cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
       instance: await reload(client, instanceId, tags),
       cascaded,
@@ -2641,9 +2891,9 @@ const workflow = {
    * affected instances and the engine re-evaluates.
    */
   tick: async (args) => {
-    const { client, tags, instanceId } = args, { actor, clientForGdr } = await resolveOperationContext(args);
+    const { client, tags, instanceId } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
     await reload(client, instanceId, tags);
-    const cascaded = await cascade(client, instanceId, actor, clientForGdr);
+    const cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
       instance: await reload(client, instanceId, tags),
       cascaded,
@@ -2656,15 +2906,15 @@ const workflow = {
    * upstream; this verb performs the mechanical move.
    */
   setStage: async (args) => {
-    const { client, tags, instanceId, targetStageId, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args);
+    const { client, tags, instanceId, targetStageId, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
     await reload(client, instanceId, tags);
     const result = await setStage({
       client,
       instanceId,
       targetStageId,
       ...reason !== void 0 ? { reason } : {},
-      ...actor !== void 0 ? { options: { actor } } : {}
-    }), cascaded = result.fired ? await cascade(client, instanceId, actor, clientForGdr) : 0;
+      options: { ...actor !== void 0 ? { actor } : {}, clock }
+    }), cascaded = result.fired ? await cascade(client, instanceId, actor, clientForGdr, clock) : 0;
     return {
       instance: await reload(client, instanceId, tags),
       cascaded,
@@ -2680,6 +2930,16 @@ const workflow = {
     const { client, tags, instanceId } = args;
     return validateTags(tags), reload(client, instanceId, tags);
   },
+  guardsForInstance: async (args) => {
+    const { client, tags, instanceId, resourceClients } = args;
+    validateTags(tags);
+    const instance = await reload(client, instanceId, tags);
+    return guardsForInstance({
+      client,
+      clientForGdr: buildClientForGdr(client, resourceClients),
+      instance
+    });
+  },
   /**
    * Run a caller-supplied GROQ query with the engine's tags bound as
    * `$engineTags`. This does NOT rewrite the query — arbitrary GROQ
@@ -2714,9 +2974,9 @@ const workflow = {
    * without re-implementing hydration. Pure read — never writes.
    */
   queryInScope: async (args) => {
-    const { client, tags, instanceId, groq, params, resourceClients } = args;
+    const { client, tags, instanceId, groq, params, resourceClients } = args, clock = args.clock ?? wallClock;
     validateTags(tags);
-    const instance = await reload(client, instanceId, tags), definition = JSON.parse(instance.definitionSnapshot), clientForGdr = buildClientForGdr(client, resourceClients), snapshot = await hydrateSnapshot({ client, clientForGdr, instance, definition }), reserved = buildParams(instance), tree = parse(groq, { params: { ...reserved, ...params } });
+    const instance = await reload(client, instanceId, tags), definition = JSON.parse(instance.definitionSnapshot), clientForGdr = buildClientForGdr(client, resourceClients), snapshot = await hydrateSnapshot({ client, clientForGdr, instance, definition }), reserved = buildParams(instance, clock()), tree = parse(groq, { params: { ...reserved, ...params } });
     return await (await evaluate(tree, {
       dataset: snapshot.docs,
       params: { ...reserved, ...params }
@@ -2900,7 +3160,8 @@ async function claimPendingEffect(client, instance, effectKey, drainerActor) {
   };
   try {
     return await client.patch(instance._id).ifRevisionId(instance._rev).set({ [`pendingEffects[_key=="${effectKey}"].claim`]: claim }).commit(), !0;
-  } catch {
+  } catch (error) {
+    if (!isRevisionConflict(error)) throw error;
     return !1;
   }
 }
@@ -2945,13 +3206,14 @@ const defaultLoggerFactory = (name) => ({
   }
 };
 function createEngine(args) {
-  const { client, workflowResource, tags, resourceClients } = args;
+  const { client, workflowResource, tags, resourceClients, clock } = args;
   validateTags(tags);
   const effectHandlers = args.effectHandlers ?? {}, missingHandler = args.missingHandler ?? "fail", logger = args.loggerFactory ?? defaultLoggerFactory, bind = (rest) => ({
     client,
     tags,
     workflowResource,
     ...resourceClients !== void 0 ? { resourceClients } : {},
+    ...clock !== void 0 ? { clock } : {},
     ...rest
   });
   return {
@@ -2969,6 +3231,13 @@ function createEngine(args) {
     evaluateInstance: (rest) => evaluateInstance(bind(rest)),
     setStage: (rest) => workflow.setStage(bind(rest)),
     getInstance: ({ instanceId }) => workflow.getInstance({ client, tags, workflowResource, instanceId }),
+    guardsForInstance: ({ instanceId }) => workflow.guardsForInstance({
+      client,
+      tags,
+      workflowResource,
+      instanceId,
+      ...resourceClients !== void 0 ? { resourceClients } : {}
+    }),
     children: ({ instanceId, taskId }) => workflow.children({
       client,
       tags,
@@ -2989,7 +3258,8 @@ function createEngine(args) {
       workflowResource,
       instanceId,
       groq,
-      ...params !== void 0 ? { params } : {}
+      ...params !== void 0 ? { params } : {},
+      ...clock !== void 0 ? { clock } : {}
     }),
     listPendingEffects: ({ instanceId }) => workflow.listPendingEffects({ client, tags, workflowResource, instanceId }),
     findPendingEffects: ({ instanceId, claimed, names }) => workflow.findPendingEffects({
@@ -3020,15 +3290,6 @@ function createEngine(args) {
     })
   };
 }
-class MutationGuardDeniedError extends Error {
-  denied;
-  documentId;
-  action;
-  constructor(args) {
-    const ids = args.denied.map((d) => d.guardId).join(", ");
-    super(`Mutation on "${args.documentId}" (${args.action}) denied by guard(s) [${ids}]`), this.name = "MutationGuardDeniedError", this.denied = args.denied, this.documentId = args.documentId, this.action = args.action;
-  }
-}
 const HISTORY_DISPLAY = {
   "workflow.history.stageEntered": {
     title: "Stage entered",
@@ -3224,14 +3485,18 @@ export {
   AUTHORING_DISPLAY,
   ActionDisabledError,
   ActionParamsInvalidError,
+  CascadeLimitError,
+  ConcurrentFireActionError,
   DISPLAY,
   EFFECTS_CONTEXT_DISPLAY,
+  GUARD_DOC_TYPE,
   GUARD_LIFTED_PREDICATE,
   GUARD_OWNER,
   HISTORY_DISPLAY,
   MutationGuardDeniedError,
   OP_DISPLAY,
   STATE_SLOT_DISPLAY,
+  WorkflowStateDivergedError,
   canonicalTag,
   compileGuard,
   createEngine,
@@ -3246,10 +3511,12 @@ export {
   gdrRef,
   gdrUri,
   guardMatches,
+  guardsForInstance,
+  guardsForResource,
+  isDefinitionUnchanged,
   isGdr,
   lakeGuardId,
   parseGdr,
-  reconcileStageGuards,
   refCanvas,
   refDashboard,
   refDataset,
@@ -3257,8 +3524,10 @@ export {
   resolveAccess,
   retractStageGuards,
   silentLogger,
+  stripSystemFields,
   validateDefinition,
   validateTags,
+  wallClock,
   workflow
 };
 //# sourceMappingURL=index.js.map