@sanity/workflow-engine 0.6.0 → 0.7.0

package/dist/index.js

@@ -79,6 +79,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);
 }
@@ -223,6 +238,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);
@@ -460,10 +477,14 @@ function abortReason(instance) {
   )?.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 +509,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 +547,51 @@ 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)
+  }));
 }
 function buildSnapshot(args) {
   const docs = [], knownIds = /* @__PURE__ */ new Set();
@@ -557,6 +638,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 +664,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 +693,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 +711,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 +812,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 +839,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 = [];
@@ -776,7 +866,7 @@ 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 +890,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();
@@ -977,7 +1083,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 +1213,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 {
@@ -1233,7 +1342,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,
@@ -1340,7 +1449,7 @@ 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 = [];
@@ -1493,9 +1602,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 +1626,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];
-}
-function firstDocRefGdrUri(entries) {
-  if (entries) {
-    for (const s of entries)
-      if (s._type === "doc.ref" && s.value !== null) return s.value.id;
-  }
+  return Array.isArray(value) ? { rows: value, discoveryResource } : value == null ? { rows: [], discoveryResource } : { rows: [value], discoveryResource };
 }
-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 +1652,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 +1674,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 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, workflowResource) {
-  const toUri = (id) => isGdrUri(id) ? id : gdrFromResource(workflowResource, id);
+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;
@@ -2059,21 +2183,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;
 }
@@ -2223,8 +2350,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 +2384,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 +2646,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 +2705,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 +2719,8 @@ async function evaluateTask(args) {
         snapshot,
         taskScope,
         stageHasExits,
-        guardDenial
+        guardDenial,
+        requirementsReason
       })
     );
   return {
@@ -2593,12 +2731,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 +3023,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);
@@ -3130,7 +3279,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 +3519,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 +3689,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 +4142,7 @@ export {
   ActionParamsInvalidError,
   CascadeLimitError,
   ConcurrentFireActionError,
+  DEFAULT_CONTENT_PERSPECTIVE,
   DISPLAY,
   EFFECTS_CONTEXT_DISPLAY,
   GUARD_DOC_TYPE,
@@ -4007,7 +4157,6 @@ export {
   WorkflowStateDivergedError,
   abortReason,
   actionVerdict,
-  assigneesOf,
   availableActions,
   buildSnapshot,
   compileGuard,
@@ -4039,13 +4188,13 @@ export {
   isGdr,
   isTerminalStage,
   lakeGuardId,
-  openStage,
   parseGdr,
   readsRaw,
   refCanvas,
   refDashboard,
   refDataset,
   refMediaLibrary,
+  remediationsFor,
   resolveAccess,
   resourceFromParsed,
   retractStageGuards,