@sanity/workflow-engine 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,13 +1,9 @@
 import { parse, evaluate } from "groq-js";
 import { isTerminalTaskStatus, WORKFLOW_DEFINITION_TYPE, DOCUMENT_VALUE_PERMISSIONS } from "./_chunks-es/schema.js";
+import { isStartableDefinition } from "./_chunks-es/schema.js";
 import * as v from "valibot";
-function getPath(value, path) {
-  let current = value;
-  for (const part of path.split(".")) {
-    if (current == null || typeof current != "object") return;
-    current = current[part];
-  }
-  return current;
+function findOpenStageEntry(host) {
+  return host.stages.find((s) => s.name === host.currentStage && s.exitedAt === void 0);
 }
 const KNOWN_SCHEMES = /* @__PURE__ */ new Set(["dataset", "canvas", "media-library", "dashboard"]);
 function parseGdr(uri) {
@@ -79,6 +75,21 @@ function gdrFromResource(res, documentId) {
   }
   return gdrUri({ scheme: res.type, resourceId: res.id, documentId });
 }
+function resourceFromGdrUri(uri) {
+  let parsed;
+  try {
+    parsed = parseGdr(uri);
+  } catch {
+    return;
+  }
+  if (parsed.scheme === "dataset")
+    return parsed.projectId === void 0 || parsed.dataset === void 0 ? void 0 : { type: "dataset", id: `${parsed.projectId}.${parsed.dataset}` };
+  if (parsed.resourceId !== void 0)
+    return { type: parsed.scheme, id: parsed.resourceId };
+}
+function sameResource(a, b) {
+  return a.type === b.type && a.id === b.id;
+}
 function selfGdr(doc) {
   return gdrFromResource(doc.workflowResource, doc._id);
 }
@@ -96,12 +107,100 @@ function gdrRef(res, documentId, type) {
 function isGdr(value) {
   return typeof value == "object" && value !== null && typeof value.id == "string" && typeof value.type == "string";
 }
+function buildParams(args) {
+  const { instance, now, snapshot, extra } = args, currentTasks2 = findOpenStageEntry(instance)?.tasks ?? [];
+  return {
+    self: selfGdr(instance),
+    state: renderedState(instance.state ?? [], snapshot),
+    parent: instance.ancestors.at(-1)?.id ?? null,
+    ancestors: instance.ancestors.map((a) => a.id),
+    stage: instance.currentStage,
+    now,
+    /** `$effects` — parent context handoff by entry name, completed-effect
+     *  outputs namespaced under the effect's name (`$effects['x.y'].out`). */
+    effects: effectsContextMap(instance),
+    /** `$tasks` — the current stage's task rows, statuses included. */
+    tasks: currentTasks2,
+    allTasksDone: currentTasks2.every((t) => t.status === "done" || t.status === "skipped"),
+    anyTaskFailed: currentTasks2.some((t) => t.status === "failed"),
+    ...extra
+  };
+}
+function renderedState(entries, snapshot) {
+  const out = {};
+  for (const entry of entries) out[entry.name] = renderedValue(entry, snapshot);
+  return out;
+}
+function renderedValue(entry, snapshot) {
+  return entry._type !== "doc.ref" || entry.value === null || snapshot === void 0 ? entry.value : snapshot.docs.find((d) => d._id === entry.value.id) ?? entry.value;
+}
+function scopedStateOverlay(instance, snapshot, taskName) {
+  const stageEntry = findOpenStageEntry(instance);
+  if (stageEntry === void 0) return {};
+  const stageState = renderedState(stageEntry.state ?? [], snapshot), task = taskName ? stageEntry.tasks.find((t) => t.name === taskName) : void 0;
+  return { ...stageState, ...renderedState(task?.state ?? [], snapshot) };
+}
+function assignedFor(instance, taskName, actor) {
+  if (actor === void 0) return !1;
+  const entry = findOpenStageEntry(instance)?.tasks.find((t) => t.name === taskName)?.state?.find((s) => s._type === "assignees");
+  return entry === void 0 ? !1 : entry.value.some(
+    (a) => a.type === "user" ? a.id === actor.id : (actor.roles ?? []).includes(a.role)
+  );
+}
+function effectsContextMap(instance) {
+  const out = {};
+  for (const entry of instance.effectsContext)
+    out[entry.name] = entry._type === "effectsContext.json" ? parseJsonContextEntry(entry) : entry.value;
+  return out;
+}
+function parseJsonContextEntry(entry) {
+  try {
+    return JSON.parse(entry.value);
+  } catch (err) {
+    throw new Error(
+      `effectsContext entry "${entry.name}" holds unparseable JSON: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
+    );
+  }
+}
+function paramsForLake(params) {
+  return {
+    ...params,
+    self: typeof params.self == "string" ? bareId(params.self) : params.self,
+    parent: typeof params.parent == "string" ? bareId(params.parent) : params.parent,
+    ancestors: Array.isArray(params.ancestors) ? params.ancestors.map((a) => typeof a == "string" ? bareId(a) : a) : params.ancestors,
+    state: stripStateForLake(params.state)
+  };
+}
+function stripStateForLake(value) {
+  if (value == null) return value;
+  if (typeof value == "string") return bareId(value);
+  if (Array.isArray(value)) return value.map(stripStateForLake);
+  if (typeof value == "object") {
+    const out = {};
+    for (const [k, v2] of Object.entries(value))
+      out[k] = stripStateForLake(v2);
+    return out;
+  }
+  return value;
+}
+function bareId(id) {
+  return isGdrUri(id) ? extractDocumentId(id) : id;
+}
+function getPath(value, path) {
+  let current = value;
+  for (const part of path.split(".")) {
+    if (current == null || typeof current != "object") return;
+    current = current[part];
+  }
+  return current;
+}
 function resourceOf(p) {
   return p.scheme === "dataset" ? { type: "dataset", id: `${p.projectId}.${p.dataset}` } : { type: p.scheme, id: p.resourceId ?? "" };
 }
-const STATE_READ = /^\$state\.(\w+)(?:\.(.+))?$/;
+const STATE_READ = /^\$state\.(\w+)(?:\.(.+))?$/, EFFECTS_READ = /^\$effects\['([^']+)'\](?:\.(.+))?$/;
 function isGuardReadExpr(expr) {
-  return expr === "$self" || expr === "$now" || STATE_READ.test(expr);
+  return expr === "$self" || expr === "$now" || STATE_READ.test(expr) || EFFECTS_READ.test(expr);
 }
 function resolveGuardRead(expr, ctx) {
   if (expr === "$self") return selfGdr(ctx.instance);
@@ -111,8 +210,13 @@ function resolveGuardRead(expr, ctx) {
     const value = (ctx.instance.state ?? []).find((s) => s.name === stateRead[1])?.value;
     return stateRead[2] !== void 0 ? getPath(value, stateRead[2]) : value;
   }
+  const effectsRead = EFFECTS_READ.exec(expr);
+  if (effectsRead !== null) {
+    const outputs = effectsContextMap(ctx.instance)[effectsRead[1]];
+    return effectsRead[2] !== void 0 ? getPath(outputs, effectsRead[2]) : outputs;
+  }
   throw new Error(
-    `Guard read "${expr}" is not a supported deploy-time value \u2014 use "$self", "$now", or "$state.<name>[.path]" (guards store resolved values; the lake cannot see $state)`
+    `Guard read "${expr}" is not a supported deploy-time value \u2014 use "$self", "$now", "$state.<name>[.path]", or "$effects['<name>'][.path]" (guards store resolved values; the lake cannot see $state or $effects)`
   );
 }
 function resolveIdRefTarget(expr, ctx) {
@@ -194,7 +298,7 @@ function createDefinitionValidator() {
     entry.source.type === "query" && tryParse(entry.source.query, `${label}.query`);
   }, checkGuardRead: (expr, where) => {
     isGuardReadExpr(expr) || errors.push(
-      `  \xB7 ${where}: guard read "${expr}" is not a supported deploy-time value \u2014 use "$self", "$now", or "$state.<name>[.path]" (guards store resolved values; the lake cannot see $state)`
+      `  \xB7 ${where}: guard read "${expr}" is not a supported deploy-time value \u2014 use "$self", "$now", "$state.<name>[.path]", or "$effects['<name>'][.path]" (guards store resolved values; the lake cannot see $state or $effects)`
     );
   } };
 }
@@ -223,6 +327,8 @@ function validateTask(v2, stageName, task) {
   for (const entry of task.state ?? [])
     v2.checkEntry(entry, `${where}.state "${entry.name}"`);
   task.filter !== void 0 && v2.checkCondition(task.filter, `${where}.filter`), task.completeWhen !== void 0 && v2.checkCondition(task.completeWhen, `${where}.completeWhen`), task.failWhen !== void 0 && v2.checkCondition(task.failWhen, `${where}.failWhen`);
+  for (const [name, groq] of Object.entries(task.requirements ?? {}))
+    v2.checkCondition(groq, `${where}.requirements "${name}"`);
   for (const [key, groq] of effectBindings(task.effects))
     v2.tryParse(groq, `${where} effect binding "${key}"`);
   validateTaskActions(v2, task), task.subworkflows !== void 0 && validateSubworkflows(v2, where, task.subworkflows);
@@ -371,99 +477,20 @@ async function assertInstanceWriteAllowed(args) {
       guards: denied
     });
 }
-function findOpenStageEntry(host) {
-  return host.stages.find((s) => s.name === host.currentStage && s.exitedAt === void 0);
-}
-function buildParams(args) {
-  const { instance, now, snapshot, extra } = args, currentTasks2 = findOpenStageEntry(instance)?.tasks ?? [];
-  return {
-    self: selfGdr(instance),
-    state: renderedState(instance.state ?? [], snapshot),
-    parent: instance.ancestors.at(-1)?.id ?? null,
-    ancestors: instance.ancestors.map((a) => a.id),
-    stage: instance.currentStage,
-    now,
-    /** `$effects` — parent context handoff by entry name, completed-effect
-     *  outputs namespaced under the effect's name (`$effects['x.y'].out`). */
-    effects: effectsContextMap(instance),
-    /** `$tasks` — the current stage's task rows, statuses included. */
-    tasks: currentTasks2,
-    allTasksDone: currentTasks2.every((t) => t.status === "done" || t.status === "skipped"),
-    anyTaskFailed: currentTasks2.some((t) => t.status === "failed"),
-    ...extra
-  };
-}
-function renderedState(entries, snapshot) {
-  const out = {};
-  for (const entry of entries) out[entry.name] = renderedValue(entry, snapshot);
-  return out;
-}
-function renderedValue(entry, snapshot) {
-  return entry._type !== "doc.ref" || entry.value === null || snapshot === void 0 ? entry.value : snapshot.docs.find((d) => d._id === entry.value.id) ?? entry.value;
-}
-function scopedStateOverlay(instance, snapshot, taskName) {
-  const stageEntry = findOpenStageEntry(instance);
-  if (stageEntry === void 0) return {};
-  const stageState = renderedState(stageEntry.state ?? [], snapshot), task = taskName ? stageEntry.tasks.find((t) => t.name === taskName) : void 0;
-  return { ...stageState, ...renderedState(task?.state ?? [], snapshot) };
-}
-function assignedFor(instance, taskName, actor) {
-  if (actor === void 0) return !1;
-  const entry = findOpenStageEntry(instance)?.tasks.find((t) => t.name === taskName)?.state?.find((s) => s._type === "assignees");
-  return entry === void 0 ? !1 : entry.value.some(
-    (a) => a.type === "user" ? a.id === actor.id : (actor.roles ?? []).includes(a.role)
-  );
-}
-function effectsContextMap(instance) {
-  const out = {};
-  for (const entry of instance.effectsContext)
-    out[entry.name] = entry._type === "effectsContext.json" ? parseJsonContextEntry(entry) : entry.value;
-  return out;
-}
-function parseJsonContextEntry(entry) {
-  try {
-    return JSON.parse(entry.value);
-  } catch (err) {
-    throw new Error(
-      `effectsContext entry "${entry.name}" holds unparseable JSON: ${err instanceof Error ? err.message : String(err)}`,
-      { cause: err }
-    );
-  }
-}
-function paramsForLake(params) {
-  return {
-    ...params,
-    self: typeof params.self == "string" ? bareId(params.self) : params.self,
-    parent: typeof params.parent == "string" ? bareId(params.parent) : params.parent,
-    ancestors: Array.isArray(params.ancestors) ? params.ancestors.map((a) => typeof a == "string" ? bareId(a) : a) : params.ancestors,
-    state: stripStateForLake(params.state)
-  };
-}
-function stripStateForLake(value) {
-  if (value == null) return value;
-  if (typeof value == "string") return bareId(value);
-  if (Array.isArray(value)) return value.map(stripStateForLake);
-  if (typeof value == "object") {
-    const out = {};
-    for (const [k, v2] of Object.entries(value))
-      out[k] = stripStateForLake(v2);
-    return out;
-  }
-  return value;
-}
-function bareId(id) {
-  return isGdrUri(id) ? extractDocumentId(id) : id;
-}
 function abortReason(instance) {
   return instance.history.find(
     (h) => h._type === "aborted"
   )?.reason;
 }
 function diagnoseInputFromEvaluation(evaluation) {
+  const stage = openStage(evaluation.instance);
   return {
     instance: evaluation.instance,
     tasks: evaluation.currentStage.tasks,
-    transitions: evaluation.currentStage.transitions
+    transitions: evaluation.currentStage.transitions,
+    assignees: Object.fromEntries(
+      evaluation.currentStage.tasks.map((t) => [t.task.name, assigneesOf(stage, t.task.name)])
+    )
   };
 }
 function openStage(instance) {
@@ -488,18 +515,34 @@ function failedTaskCause(input) {
   return failed ? { kind: "failed-task", task: failed.task.name } : void 0;
 }
 function waitingState(input) {
-  const active = input.tasks.find((t) => t.status === "active" && (t.task.actions ?? []).length > 0);
+  const active = input.tasks.find(
+    (t) => t.status === "active" && (t.task.actions ?? []).length > 0 && (t.unmetRequirements ?? []).length === 0
+  );
   if (active !== void 0)
     return {
       state: "waiting",
       task: active.task.name,
-      assignees: assigneesOf(openStage(input.instance), active.task.name),
+      assignees: input.assignees[active.task.name] ?? [],
       actions: (active.task.actions ?? []).map((a) => a.name)
     };
 }
+function blockedState(input) {
+  const blocked = input.tasks.find(
+    (t) => t.status === "active" && (t.task.actions ?? []).length > 0 && (t.unmetRequirements ?? []).length > 0
+  );
+  if (blocked !== void 0)
+    return {
+      state: "blocked",
+      task: blocked.task.name,
+      requirements: blocked.unmetRequirements ?? [],
+      assignees: input.assignees[blocked.task.name] ?? []
+    };
+}
 function noTransitionFiresCause(input) {
-  if (input.transitions.length !== 0 && !input.transitions.some((t) => t.filterSatisfied) && input.tasks.every((t) => isResolved(t.status)))
-    return { kind: "no-transition-fires" };
+  if (input.transitions.length === 0 || input.transitions.some((t) => t.filterSatisfied) || !input.tasks.every((t) => isResolved(t.status)))
+    return;
+  const undecidable = input.transitions.filter((t) => t.unevaluable);
+  return undecidable.length > 0 ? { kind: "transition-unevaluable", transitions: undecidable.map((t) => t.transition.name) } : { kind: "no-transition-fires" };
 }
 function diagnoseInstance(input) {
   const { instance } = input;
@@ -510,7 +553,124 @@ function diagnoseInstance(input) {
   if (instance.completedAt !== void 0)
     return { state: "completed", at: instance.completedAt };
   const cause = failedEffectCause(input) ?? failedTaskCause(input) ?? hungEffectCause(input) ?? noTransitionFiresCause(input);
-  return cause !== void 0 ? { state: "stuck", cause } : waitingState(input) ?? { state: "progressing" };
+  return cause !== void 0 ? { state: "stuck", cause } : waitingState(input) ?? blockedState(input) ?? { state: "progressing" };
+}
+const RUNNABLE_VERBS = /* @__PURE__ */ new Set(["set-stage", "abort"]);
+function remediationsForCause(cause) {
+  switch (cause.kind) {
+    case "failed-effect":
+      return [
+        {
+          verb: "retry-effect",
+          rationale: "Re-run the failed effect once the upstream system is healthy."
+        },
+        { verb: "abort", rationale: "Abort the instance if it can no longer recover." }
+      ];
+    case "hung-effect":
+      return [
+        {
+          verb: "drain-effects",
+          rationale: "Re-run the effect drainer to re-pick the claimed effect."
+        },
+        { verb: "abort", rationale: "Abort the instance if the effect never drains." }
+      ];
+    case "failed-task":
+      return [
+        { verb: "reset-task", rationale: "Reset or skip the failed task." },
+        {
+          verb: "set-stage",
+          rationale: "Move the instance past the failed task to the intended next stage."
+        }
+      ];
+    case "no-transition-fires":
+      return [
+        {
+          verb: "set-stage",
+          rationale: "Move the instance to the intended next stage to force it forward."
+        }
+      ];
+    case "transition-unevaluable":
+      return [];
+  }
+}
+function remediationsFor(diagnosis) {
+  return diagnosis.state !== "stuck" ? [] : remediationsForCause(diagnosis.cause).map((seed) => ({
+    ...seed,
+    available: RUNNABLE_VERBS.has(seed.verb)
+  }));
+}
+class ActionParamsInvalidError extends Error {
+  action;
+  task;
+  issues;
+  constructor(args) {
+    const lines = args.issues.map((i) => `  - ${i.param}: ${i.reason}`).join(`
+`);
+    super(`Action "${args.action}" on task "${args.task}" rejected: invalid params
+${lines}`), this.name = "ActionParamsInvalidError", this.action = args.action, this.task = args.task, this.issues = args.issues;
+  }
+}
+class RequiredStateNotProvidedError extends Error {
+  definition;
+  missing;
+  constructor(args) {
+    const lines = args.missing.map((m) => `  - ${m.name} (${m.type})`).join(`
+`), where = args.definition !== void 0 ? ` for workflow "${args.definition}"` : "";
+    super(
+      `Required init state${where} was not provided:
+${lines}
+Provide each via \`initialState\` when starting standalone, or via the parent's \`subworkflows.with\` when spawned.`
+    ), this.name = "RequiredStateNotProvidedError", args.definition !== void 0 && (this.definition = args.definition), this.missing = args.missing;
+  }
+}
+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);
+  }
+}
+class PartialGuardDeployError extends Error {
+  stageName;
+  deployed;
+  constructor(args) {
+    super(
+      `Partial guard deploy on stage "${args.stageName}": ${args.deployed} guard(s) deployed before a later one failed.`,
+      { cause: args.cause }
+    ), this.name = "PartialGuardDeployError", this.stageName = args.stageName, this.deployed = args.deployed;
+  }
+}
+const CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS = 3;
+class ConcurrentFireActionError extends Error {
+  instanceId;
+  task;
+  action;
+  attempts;
+  constructor(args) {
+    super(
+      `Action "${args.action}" on task "${args.task}" (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.task = args.task, 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;
+  }
 }
 function buildSnapshot(args) {
   const docs = [], knownIds = /* @__PURE__ */ new Set();
@@ -557,6 +717,7 @@ function collectWatchRefs(instance) {
 function readsRaw(ref) {
   return ref.type === WORKFLOW_INSTANCE_TYPE || ref.type === "system.release";
 }
+const DEFAULT_CONTENT_PERSPECTIVE = "drafts";
 function contentReleaseName(args) {
   const { ref, perspective } = args;
   if (!readsRaw(ref) && Array.isArray(perspective))
@@ -582,6 +743,11 @@ function entryReleaseRefs(state) {
     (entry) => entry._type === "release.ref" && isGdr(entry.value) ? [entry.value] : []
   );
 }
+function entrySubjectRefs(state) {
+  return stateEntries(state).flatMap(
+    (entry) => (entry._type === "doc.ref" || entry._type === "release.ref") && isGdr(entry.value) ? [entry.value] : []
+  );
+}
 function stateEntries(state) {
   return Array.isArray(state) ? state.filter(
     (entry) => !!entry && typeof entry == "object"
@@ -606,7 +772,10 @@ async function hydrateSnapshot(args) {
   };
   loaded.push({ doc: instance, resource: instance.workflowResource }), visited.add(selfGdr(instance));
   for (const ref of collectWatchRefs(instance))
-    await loadInto(ref.id, readsRaw(ref) ? void 0 : instance.perspective);
+    await loadInto(
+      ref.id,
+      readsRaw(ref) ? "raw" : instance.perspective ?? DEFAULT_CONTENT_PERSPECTIVE
+    );
   return buildSnapshot({ docs: loaded });
 }
 async function loadByGdr(defaultClient, clientForGdr, defaultResource, uri, perspective) {
@@ -621,7 +790,7 @@ async function loadByGdr(defaultClient, clientForGdr, defaultResource, uri, pers
   return doc ? { doc, resource: resourceFromParsed(parsed) } : null;
 }
 async function readDoc(client, id, perspective) {
-  return perspective === void 0 ? await client.getDocument(id) ?? null : await client.fetch("*[_id == $id][0]", { id }, { perspective }) ?? null;
+  return perspective === "raw" ? await client.getDocument(id) ?? null : await client.fetch("*[_id == $id][0]", { id }, { perspective }) ?? null;
 }
 function resourceFromParsed(parsed) {
   return parsed.scheme === "dataset" ? { type: "dataset", id: `${parsed.projectId}.${parsed.dataset}` } : { type: parsed.scheme, id: parsed.resourceId ?? "" };
@@ -722,7 +891,7 @@ async function queryGuardsAcross(clients, query, params) {
 function dedupById(guards) {
   return [...new Map(guards.map((g) => [g._id, g])).values()].sort((a, b) => a._id.localeCompare(b._id));
 }
-const GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
+const SYNC_COMMIT = { visibility: "sync" }, GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
 function resolveGuard(guard, instance, stageName, now) {
   const ctx = { instance, now }, targets = resolveIdRefTargets(guard.match.idRefs, ctx);
   if (targets === null) return null;
@@ -749,11 +918,11 @@ function resolveGuard(guard, instance, stageName, now) {
 }
 async function upsertGuard(client, doc) {
   if (!await client.getDocument(doc._id)) {
-    await client.create(doc);
+    await client.create(doc, SYNC_COMMIT);
     return;
   }
   const { _id, _type, _rev, _createdAt, _updatedAt, ...body } = doc;
-  await client.patch(doc._id).set(body).commit();
+  await client.patch(doc._id).set(body).commit(SYNC_COMMIT);
 }
 function resolvedStageGuards(args) {
   const stage = args.definition.stages.find((s) => s.name === args.stageName), out = [];
@@ -768,15 +937,22 @@ async function committedInstance(args) {
 }
 async function deployStageGuards(args) {
   const live = await committedInstance(args);
-  if (!(live === void 0 || live.currentStage !== args.stageName) && live.abortedAt === void 0)
-    for (const { client, doc } of resolvedStageGuards(args))
+  if (live === void 0 || live.currentStage !== args.stageName || live.abortedAt !== void 0) return;
+  let deployed = 0;
+  for (const { client, doc } of resolvedStageGuards(args)) {
+    try {
       await upsertGuard(client, doc);
+    } catch (cause) {
+      throw deployed > 0 ? new PartialGuardDeployError({ stageName: args.stageName, deployed, cause }) : cause;
+    }
+    deployed += 1;
+  }
 }
 async function retractStageGuards(args) {
   const live = await committedInstance(args);
   if (live !== void 0 && !(live.currentStage === args.stageName && live.abortedAt === void 0))
     for (const { client, doc } of resolvedStageGuards(args))
-      await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit();
+      await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit(SYNC_COMMIT);
 }
 async function deleteOrphanedDefinitionGuards(args) {
   const { client, clientForGdr, workflowResource, definition, definitions, tag } = args, perClient = await guardsForDefinitionByClient({
@@ -800,16 +976,32 @@ function randomKey(length = 12) {
   const bytes = new Uint8Array(length);
   return globalThis.crypto.getRandomValues(bytes), [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, length);
 }
-async function evaluateCondition(args) {
+function isUnevaluable(result) {
+  return result == null;
+}
+async function evaluateConditionOutcome(args) {
   const { condition, snapshot, params } = args;
-  return condition === void 0 ? !0 : !!await runGroq(condition, params, snapshot);
+  if (condition === void 0) return "satisfied";
+  const result = await runGroq(condition, params, snapshot);
+  return isUnevaluable(result) ? "unevaluable" : result ? "satisfied" : "unsatisfied";
+}
+async function evaluateCondition(args) {
+  return await evaluateConditionOutcome(args) === "satisfied";
 }
 async function evaluatePredicates(args) {
   const out = {};
-  for (const [name, groq] of Object.entries(args.predicates ?? {}))
-    out[name] = !!await runGroq(groq, args.params, args.snapshot);
+  for (const [name, groq] of Object.entries(args.predicates ?? {})) {
+    const result = await runGroq(groq, args.params, args.snapshot);
+    out[name] = isUnevaluable(result) ? null : !!result;
+  }
   return out;
 }
+async function evaluateRequirements(args) {
+  const unmet = [];
+  for (const [name, condition] of Object.entries(args.requirements ?? {}))
+    await evaluateCondition({ condition, snapshot: args.snapshot, params: args.params }) || unmet.push(name);
+  return unmet;
+}
 async function runGroq(groq, params, snapshot) {
   const tree = parse(groq, { params });
   return (await evaluate(tree, { dataset: snapshot.docs, params })).get();
@@ -943,6 +1135,7 @@ function derivePerspectiveFromState(entries) {
 async function resolveDeclaredState(args) {
   const { entryDefs, initialState, ctx, randomKey: randomKey2 } = args;
   if (entryDefs === void 0 || entryDefs.length === 0) return [];
+  assertRequiredInitProvided(entryDefs, initialState, ctx.definitionName);
   const out = [];
   for (const entry of entryDefs) {
     const scopedCtx = { ...ctx, resolvedState: out };
@@ -950,6 +1143,17 @@ async function resolveDeclaredState(args) {
   }
   return out;
 }
+function assertRequiredInitProvided(entryDefs, initialState, definitionName) {
+  const missing = entryDefs.filter((entry) => entry.required === !0 && entry.source.type === "init").filter((entry) => {
+    const match = initialState.find((s) => s.name === entry.name && s.type === entry.type);
+    return match === void 0 || match.value === void 0 || match.value === null;
+  }).map((entry) => ({ name: entry.name, type: entry.type }));
+  if (missing.length !== 0)
+    throw new RequiredStateNotProvidedError({
+      ...definitionName !== void 0 ? { definition: definitionName } : {},
+      missing
+    });
+}
 const ARRAY_SLOT_TYPES = /* @__PURE__ */ new Set([
   "doc.refs",
   "checklist",
@@ -977,7 +1181,7 @@ async function resolveQueryValue(entry, source, ctx, client, defaultValue) {
     tag: ctx.tag
   });
   try {
-    const fetchOptions = ctx.perspective !== void 0 ? { perspective: ctx.perspective } : void 0, result = await client.fetch(source.query, params, fetchOptions);
+    const fetchOptions = { perspective: ctx.perspective ?? DEFAULT_CONTENT_PERSPECTIVE }, result = await client.fetch(source.query, params, fetchOptions);
     return normalizeQueryResult(entry.type, result, ctx.workflowResource) ?? defaultValue;
   } catch (err) {
     throw new Error(
@@ -1107,13 +1311,16 @@ async function ctxConditionParams(ctx, opts) {
     params
   }), ...params };
 }
-async function ctxEvaluateCondition(ctx, condition, opts) {
-  return condition === void 0 ? !0 : evaluateCondition({
+async function ctxEvaluateConditionOutcome(ctx, condition, opts) {
+  return condition === void 0 ? "satisfied" : evaluateConditionOutcome({
     condition,
     snapshot: ctx.snapshot,
     params: await ctxConditionParams(ctx, opts)
   });
 }
+async function ctxEvaluateCondition(ctx, condition, opts) {
+  return await ctxEvaluateConditionOutcome(ctx, condition, opts) === "satisfied";
+}
 async function buildEngineContext(args) {
   const { client, clientForGdr, instance, definition } = args, clock = args.clock ?? wallClock;
   return {
@@ -1171,56 +1378,6 @@ async function resolveTaskStateEntries(args) {
     randomKey
   });
 }
-class ActionParamsInvalidError extends Error {
-  action;
-  task;
-  issues;
-  constructor(args) {
-    const lines = args.issues.map((i) => `  - ${i.param}: ${i.reason}`).join(`
-`);
-    super(`Action "${args.action}" on task "${args.task}" rejected: invalid params
-${lines}`), this.name = "ActionParamsInvalidError", this.action = args.action, this.task = args.task, 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;
-  task;
-  action;
-  attempts;
-  constructor(args) {
-    super(
-      `Action "${args.action}" on task "${args.task}" (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.task = args.task, 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();
@@ -1233,7 +1390,7 @@ async function deployOrRollback(args) {
       });
     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();
+      args.unset && args.unset.length > 0 && (patch = patch.unset(args.unset)), args.committedRev !== void 0 && (patch = patch.ifRevisionId(args.committedRev)), await patch.commit(SYNC_COMMIT);
     } catch (rollbackError) {
       throw new WorkflowStateDivergedError({
         instanceId: args.instanceId,
@@ -1242,7 +1399,11 @@ async function deployOrRollback(args) {
         reason: "rollback of the committed move failed"
       });
     }
-    throw guardError;
+    throw guardError instanceof PartialGuardDeployError ? new WorkflowStateDivergedError({
+      instanceId: args.instanceId,
+      guardError,
+      reason: "a multi-guard deploy partially applied; the rolled-back move left orphaned guard locks"
+    }) : guardError;
   }
 }
 function applyTaskStatusChange(args) {
@@ -1331,7 +1492,8 @@ function materializeInstance(base, mutation) {
     ...base,
     currentStage: mutation.currentStage,
     state: mutation.state,
-    stages: mutation.stages
+    stages: mutation.stages,
+    effectsContext: mutation.effectsContext
   };
 }
 async function persist(ctx, mutation) {
@@ -1340,13 +1502,27 @@ async function persist(ctx, 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();
+    return ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev).commit(SYNC_COMMIT);
   const tx = ctx.client.transaction();
   for (const body of pendingCreates) tx.create(body);
   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, ctx.clock), await cascadeAutoTransitions(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await propagateToAncestors(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock);
+    try {
+      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);
+    } catch (cause) {
+      throw cause instanceof WorkflowStateDivergedError ? cause : new WorkflowStateDivergedError({
+        instanceId: ctx.instance._id,
+        guardError: cause,
+        reason: `spawned child "${body._id}" failed to settle after the spawn transaction committed`
+      });
+    }
   const reloaded = await ctx.client.getDocument(ctx.instance._id);
   if (!reloaded)
     throw new Error(`Instance ${ctx.instance._id} disappeared after transaction commit`);
@@ -1493,9 +1669,16 @@ async function spawnSubworkflows(ctx, mutation, task, sub, actor) {
   const parentScope = await ctxConditionParams(ctx, {
     taskName: task.name,
     ...actor ? { actor } : {}
-  }), rows = await resolveSpawnRows(ctx, sub), effectsContext = await resolveContextHandoff(ctx, sub, parentScope), refs = [];
+  }), { rows, discoveryResource } = await resolveSpawnRows(ctx, sub), effectsContext = await resolveContextHandoff(ctx, sub, parentScope), refs = [];
   for (const row of rows) {
-    const initialState = await projectRowState(ctx, sub, definition, parentScope, row), { ref, body } = await prepareChildInstance({
+    const initialState = await projectRowState(
+      ctx,
+      sub,
+      definition,
+      parentScope,
+      row,
+      discoveryResource
+    ), { ref, body } = await prepareChildInstance({
       client: ctx.client,
       parent: ctx.instance,
       definition,
@@ -1510,28 +1693,25 @@ async function spawnSubworkflows(ctx, mutation, task, sub, actor) {
 }
 async function resolveSpawnRows(ctx, sub) {
   const params = buildParams({ instance: ctx.instance, now: ctx.now, snapshot: ctx.snapshot }), groq = sub.forEach;
-  let value;
+  let value, discoveryResource;
   if (groq.includes("*")) {
-    const routingUri = firstDocRefGdrUri(ctx.instance.state), client = clientForDiscovery(ctx.client, ctx.clientForGdr, routingUri);
-    value = await discoverItems({
+    const routingUri = entrySubjectRefs(ctx.instance.state)[0]?.id, client = clientForDiscovery(ctx.client, ctx.clientForGdr, routingUri);
+    client !== ctx.client && routingUri !== void 0 && (discoveryResource = resourceFromGdrUri(routingUri)), value = await discoverItems({
       client,
       groq,
       params,
-      ...ctx.instance.perspective !== void 0 ? { perspective: ctx.instance.perspective } : {}
+      // Draft-aware by default (drafts overlay published) when there's no
+      // release, so a `forEach` discovers in-flight items the same way the
+      // engine reads any other content.
+      perspective: ctx.instance.perspective ?? DEFAULT_CONTENT_PERSPECTIVE
     });
   } else {
     const tree = parse(groq, { params });
     value = await (await evaluate(tree, { dataset: [ctx.instance], params, root: ctx.instance })).get();
   }
-  return Array.isArray(value) ? value : value == null ? [] : [value];
+  return Array.isArray(value) ? { rows: value, discoveryResource } : value == null ? { rows: [], discoveryResource } : { rows: [value], discoveryResource };
 }
-function firstDocRefGdrUri(entries) {
-  if (entries) {
-    for (const s of entries)
-      if (s._type === "doc.ref" && s.value !== null) return s.value.id;
-  }
-}
-async function projectRowState(ctx, sub, childDefinition, parentScope, row) {
+async function projectRowState(ctx, sub, childDefinition, parentScope, row, discoveryResource) {
   const out = [];
   for (const [name, groq] of Object.entries(sub.with ?? {})) {
     const declared = (childDefinition.state ?? []).find((e) => e.name === name);
@@ -1539,7 +1719,12 @@ async function projectRowState(ctx, sub, childDefinition, parentScope, row) {
       throw new Error(
         `subworkflows.with["${name}"]: subworkflow "${childDefinition.name}" declares no state entry "${name}"`
       );
-    const raw = await runGroq(groq, { ...parentScope, row }, ctx.snapshot), value = canonicaliseSpawnValue(declared.type, raw, ctx.instance.workflowResource);
+    const raw = await runGroq(groq, { ...parentScope, row }, ctx.snapshot), value = canonicaliseSpawnValue(declared.type, raw, {
+      parentResource: ctx.instance.workflowResource,
+      discoveryResource,
+      entryName: name,
+      childName: childDefinition.name
+    });
     value != null && out.push({
       type: declared.type,
       name,
@@ -1556,11 +1741,17 @@ async function resolveContextHandoff(ctx, sub, parentScope) {
   }
   return out;
 }
-function canonicaliseSpawnValue(kind, value, workflowResource) {
-  return kind === "doc.ref" ? coerceSpawnGdr(value, workflowResource) : kind === "doc.refs" && Array.isArray(value) ? value.map((v2) => coerceSpawnGdr(v2, workflowResource)).filter((v2) => v2 !== null) : value;
+function canonicaliseSpawnValue(kind, value, cx) {
+  return kind === "doc.ref" ? coerceSpawnGdr(value, cx) : kind === "doc.refs" && Array.isArray(value) ? value.map((v2) => coerceSpawnGdr(v2, cx)).filter((v2) => v2 !== null) : value;
 }
-function coerceSpawnGdr(raw, workflowResource) {
-  const toUri = (id) => isGdrUri(id) ? id : gdrFromResource(workflowResource, id);
+function assertBareIdRootsCorrectly(id, cx) {
+  if (!(cx.discoveryResource === void 0 || sameResource(cx.discoveryResource, cx.parentResource)))
+    throw new Error(
+      `subworkflows.with["${cx.entryName}"]: subworkflow "${cx.childName}" projected the bare id "${id}", which roots at the parent resource "${cx.parentResource.id}", but spawn discovery ran against "${cx.discoveryResource.id}". The child would reference a document that doesn't exist in the parent resource. Project an explicit GDR URI in the with-GROQ (e.g. "dataset:<projectId>:<dataset>:" + _id) so the child's subject points at the resource the discovered rows came from.`
+    );
+}
+function coerceSpawnGdr(raw, cx) {
+  const toUri = (id) => isGdrUri(id) ? id : (assertBareIdRootsCorrectly(id, cx), gdrFromResource(cx.parentResource, id));
   if (raw == null) return null;
   if (typeof raw == "object" && "id" in raw && "type" in raw) {
     const r = raw;
@@ -1596,6 +1787,7 @@ async function prepareChildInstance(args) {
       selfId: childDocId,
       tag: childTag,
       workflowResource,
+      definitionName: definition.name,
       ...inheritedPerspective !== void 0 ? { perspective: inheritedPerspective } : {}
     },
     randomKey
@@ -1642,6 +1834,28 @@ async function resolveBindings(args) {
     resolved[key] = await runGroq(groq, args.params, args.snapshot);
   return { ...resolved, ...args.staticInput };
 }
+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, stageName) {
+  await deployStageGuards({
+    client: ctx.client,
+    clientForGdr: ctx.clientForGdr,
+    instance: materializeInstance(ctx.instance, mutation),
+    definition: ctx.definition,
+    stageName,
+    now: ctx.now
+  });
+}
 async function completeEffect(args) {
   const { client, instanceId, effectKey, status, outputs, detail, error, durationMs, options } = args, ctx = await loadContext(client, instanceId, {
     ...options?.clock ? { clock: options.clock } : {},
@@ -1687,9 +1901,11 @@ async function commitCompleteEffect(ctx, effectKey, status, outputs, detail, err
   const mutation = startMutation(ctx.instance);
   mutation.pendingEffects = mutation.pendingEffects.filter((e) => e._key !== effectKey);
   const ranAt = ctx.now;
-  return mutation.effectHistory.push(
+  mutation.effectHistory.push(
     buildEffectHistoryEntry(pending, { status, ranAt, actor, detail, error, durationMs, outputs })
-  ), status === "done" && outputs !== void 0 && upsertEffectsContext(mutation, pending.name, outputs), mutation.history.push({
+  );
+  const wroteEffectsContext = status === "done" && outputs !== void 0;
+  return wroteEffectsContext && upsertEffectsContext(mutation, pending.name, outputs), mutation.history.push({
     _key: randomKey(),
     _type: "effectCompleted",
     at: ranAt,
@@ -1699,7 +1915,11 @@ async function commitCompleteEffect(ctx, effectKey, status, outputs, detail, err
     ...outputs !== void 0 ? { outputs } : {},
     ...detail !== void 0 ? { detail } : {},
     ...actor !== void 0 ? { actor } : {}
-  }), await persist(ctx, mutation), { effectKey, status };
+  }), await persistThenDeploy(
+    ctx,
+    mutation,
+    () => wroteEffectsContext ? refreshStageGuards(ctx, mutation, ctx.instance.currentStage) : Promise.resolve()
+  ), { effectKey, status };
 }
 function buildQueuedEffect(effect, origin, params, actor, now) {
   const key = randomKey(), pending = {
@@ -2059,21 +2279,24 @@ function resolveMachineStep(mutation, task, entry, now) {
 async function buildStageTasks(ctx, stage) {
   const entries = [];
   for (const task of stage.tasks ?? []) {
-    const inScope = await ctxEvaluateCondition(ctx, task.filter, { taskName: task.name });
+    const outcome = await ctxEvaluateConditionOutcome(ctx, task.filter, { taskName: task.name }), inScope = outcome !== "unsatisfied";
     entries.push({
       _key: randomKey(),
       name: task.name,
       status: inScope ? "pending" : "skipped",
-      ...task.filter !== void 0 ? {
-        filterEvaluation: {
-          at: ctx.now,
-          truthy: inScope
-        }
-      } : {}
+      ...task.filter !== void 0 ? { filterEvaluation: buildFilterEvaluation(ctx.now, task.filter, outcome) } : {}
     });
   }
   return entries;
 }
+function buildFilterEvaluation(at, filter, outcome) {
+  return outcome === "unevaluable" ? {
+    at,
+    truthy: !1,
+    unevaluable: !0,
+    detail: `Filter "${filter}" could not be evaluated (GROQ null \u2014 a referenced operand was missing or incomparable). Task kept in scope so the gate is not silently skipped.`
+  } : { at, truthy: outcome === "satisfied" };
+}
 function isTerminalStage(stage) {
   return (stage.transitions ?? []).length === 0;
 }
@@ -2156,28 +2379,6 @@ async function persistStageMove(ctx, mutation, exitedStage, enteredStage) {
     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, stageName) {
-  await deployStageGuards({
-    client: ctx.client,
-    clientForGdr: ctx.clientForGdr,
-    instance: materializeInstance(ctx.instance, mutation),
-    definition: ctx.definition,
-    stageName,
-    now: ctx.now
-  });
-}
 async function commitTransition(ctx, actor) {
   if (isTerminal(ctx))
     return { fired: !1 };
@@ -2223,8 +2424,11 @@ async function commitTransition(ctx, actor) {
   };
 }
 async function pickTransition(ctx, stage) {
-  for (const candidate of stage.transitions ?? [])
-    if (await ctxEvaluateCondition(ctx, candidate.filter)) return candidate;
+  for (const candidate of stage.transitions ?? []) {
+    const outcome = await ctxEvaluateConditionOutcome(ctx, candidate.filter);
+    if (outcome === "satisfied") return candidate;
+    if (outcome === "unevaluable") return;
+  }
 }
 async function evaluateAutoTransitions(args) {
   const { client, instanceId, options, clientForGdr, clock, overlay } = args, ctx = await loadContext(client, instanceId, {
@@ -2254,7 +2458,7 @@ async function primeInitialStage(client, instanceId, actor, clientForGdr, clock)
   }, committed = await client.patch(instance._id).set({
     stages: [initialStageEntry],
     lastChangedAt: now
-  }).ifRevisionId(instance._rev).commit();
+  }).ifRevisionId(instance._rev).commit(SYNC_COMMIT);
   await deployOrRollback({
     client,
     instanceId: instance._id,
@@ -2516,15 +2720,18 @@ async function evaluateFromSnapshot(args) {
       })
     );
   const transitionEvaluations = [];
-  for (const transition of stage.transitions ?? [])
+  for (const transition of stage.transitions ?? []) {
+    const outcome = await evaluateConditionOutcome({
+      condition: transition.filter,
+      snapshot,
+      params: scope
+    });
     transitionEvaluations.push({
       transition,
-      filterSatisfied: await evaluateCondition({
-        condition: transition.filter,
-        snapshot,
-        params: scope
-      })
+      filterSatisfied: outcome === "satisfied",
+      unevaluable: outcome === "unevaluable"
     });
+  }
   const currentStage = {
     stage,
     tasks: taskEvaluations,
@@ -2572,7 +2779,11 @@ async function evaluateTask(args) {
       ...scopedStateOverlay(instance, snapshot, task.name)
     },
     assigned
-  }, actions = [];
+  }, unmetRequirements = await evaluateRequirements({
+    requirements: task.requirements,
+    snapshot,
+    params: taskScope
+  }), requirementsReason = unmetRequirements.length > 0 ? { kind: "requirements-unmet", unmetRequirements } : void 0, actions = [];
   for (const action of task.actions ?? [])
     actions.push(
       await evaluateAction({
@@ -2582,7 +2793,8 @@ async function evaluateTask(args) {
         snapshot,
         taskScope,
         stageHasExits,
-        guardDenial
+        guardDenial,
+        requirementsReason
       })
     );
   return {
@@ -2593,12 +2805,22 @@ async function evaluateTask(args) {
     // they're still inbox items. The inbox reads the assignees-kind state
     // entry BY KIND (who-data is state).
     pendingOnActor: (status === "active" || status === "pending") && assigned,
+    ...unmetRequirements.length > 0 ? { unmetRequirements } : {},
     actions
   };
 }
 async function evaluateAction(args) {
-  const { action, status, instance, snapshot, taskScope, stageHasExits, guardDenial } = args, lifecycle = lifecycleReason(instance, status, stageHasExits);
-  return lifecycle !== void 0 ? disabled(action, lifecycle) : guardDenial !== void 0 ? disabled(action, guardDenial) : action.filter !== void 0 && !await evaluateCondition({
+  const {
+    action,
+    status,
+    instance,
+    snapshot,
+    taskScope,
+    stageHasExits,
+    guardDenial,
+    requirementsReason
+  } = args, lifecycle = lifecycleReason(instance, status, stageHasExits);
+  return lifecycle !== void 0 ? disabled(action, lifecycle) : guardDenial !== void 0 ? disabled(action, guardDenial) : requirementsReason !== void 0 ? disabled(action, requirementsReason) : action.filter !== void 0 && !await evaluateCondition({
     condition: action.filter,
     snapshot,
     params: taskScope
@@ -2875,7 +3097,8 @@ const disabledReasonDetail = {
   "task-not-active": (r) => `task status is "${r.status}"`,
   "stage-terminal": (r) => `stage "${r.stage}" is terminal`,
   "instance-completed": (r) => `instance completed at ${r.completedAt}`,
-  "mutation-guard-denied": (r) => `blocked by mutation guard(s) [${r.guardIds.join(", ")}]${r.detail ? ` (${r.detail})` : ""}`
+  "mutation-guard-denied": (r) => `blocked by mutation guard(s) [${r.guardIds.join(", ")}]${r.detail ? ` (${r.detail})` : ""}`,
+  "requirements-unmet": (r) => `unmet requirement(s): ${r.unmetRequirements.join(", ")}`
 };
 function formatDisabledReason(task, action, reason) {
   const detail = disabledReasonDetail[reason.kind](reason);
@@ -3112,6 +3335,7 @@ const workflow = {
         selfId: id,
         tag,
         workflowResource,
+        definitionName: definition.name,
         ...perspective !== void 0 ? { perspective } : {}
       },
       randomKey
@@ -3130,7 +3354,7 @@ const workflow = {
       initialStage: definition.initialStage,
       actor
     });
-    return await client.create(base), await primeInitialStage(client, id, actor, clientForGdr, clock), await cascade(client, id, actor, clientForGdr, clock), reload(client, id, tag);
+    return await client.create(base, SYNC_COMMIT), await primeInitialStage(client, id, actor, clientForGdr, clock), await cascade(client, id, actor, clientForGdr, clock), reload(client, id, tag);
   },
   /**
    * Fire an action against a task. If the task is pending, it is
@@ -3370,8 +3594,8 @@ const workflow = {
    * Pure read.
    */
   diagnose: async (args) => {
-    const evaluation = await evaluateInstance(args);
-    return { evaluation, diagnosis: diagnoseInstance(diagnoseInputFromEvaluation(evaluation)) };
+    const evaluation = await evaluateInstance(args), diagnosis = diagnoseInstance(diagnoseInputFromEvaluation(evaluation));
+    return { evaluation, diagnosis, remediations: remediationsFor(diagnosis) };
   },
   /**
    * List the actions an actor could fire on an instance's current stage,
@@ -3540,7 +3764,7 @@ async function claimPendingEffect(client, instance, effectKey, drainerActor) {
     claimedBy: drainerActor
   };
   try {
-    return await client.patch(instance._id).ifRevisionId(instance._rev).set({ [`pendingEffects[_key=="${effectKey}"].claim`]: claim }).commit(), !0;
+    return await client.patch(instance._id).ifRevisionId(instance._rev).set({ [`pendingEffects[_key=="${effectKey}"].claim`]: claim }).commit(SYNC_COMMIT), !0;
   } catch (error) {
     if (!isRevisionConflict(error)) throw error;
     return !1;
@@ -3993,6 +4217,7 @@ export {
   ActionParamsInvalidError,
   CascadeLimitError,
   ConcurrentFireActionError,
+  DEFAULT_CONTENT_PERSPECTIVE,
   DISPLAY,
   EFFECTS_CONTEXT_DISPLAY,
   GUARD_DOC_TYPE,
@@ -4001,13 +4226,14 @@ export {
   HISTORY_DISPLAY,
   MutationGuardDeniedError,
   OP_DISPLAY,
+  PartialGuardDeployError,
+  RequiredStateNotProvidedError,
   STATE_SLOT_DISPLAY,
   WORKFLOW_DEFINITION_TYPE,
   WORKFLOW_INSTANCE_TYPE,
   WorkflowStateDivergedError,
   abortReason,
   actionVerdict,
-  assigneesOf,
   availableActions,
   buildSnapshot,
   compileGuard,
@@ -4037,15 +4263,16 @@ export {
   instanceGuardQuery,
   isDefinitionUnchanged,
   isGdr,
+  isStartableDefinition,
   isTerminalStage,
   lakeGuardId,
-  openStage,
   parseGdr,
   readsRaw,
   refCanvas,
   refDashboard,
   refDataset,
   refMediaLibrary,
+  remediationsFor,
   resolveAccess,
   resourceFromParsed,
   retractStageGuards,