@sanity/workflow-engine 0.7.0 → 0.9.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 { actorFulfillsRole, isTerminalTaskStatus, WORKFLOW_DEFINITION_TYPE, andConditions, 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) {
@@ -111,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, roleAliases) {
+  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 : actorFulfillsRole(actor.roles, a.role, roleAliases)
+  );
+}
+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);
@@ -126,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) {
@@ -209,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)`
     );
   } };
 }
@@ -388,89 +477,6 @@ 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"
@@ -593,6 +599,90 @@ function remediationsFor(diagnosis) {
     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 ConcurrentEditStateError extends Error {
+  instanceId;
+  target;
+  attempts;
+  constructor(args) {
+    const where = args.target.task !== void 0 ? `${args.target.task}.${args.target.state}` : args.target.state;
+    super(
+      `Edit of "${args.target.scope}:${where}" (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 = "ConcurrentEditStateError", this.instanceId = args.instanceId, this.target = args.target, this.attempts = args.attempts;
+  }
+}
+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();
   for (const { doc, resource } of args.docs) {
@@ -858,9 +948,16 @@ 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);
@@ -1049,6 +1146,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 };
@@ -1056,6 +1154,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",
@@ -1184,6 +1293,12 @@ function coerceToGdr(raw, workflowResource) {
 function gdrToBareId(uri) {
   return uri.includes(":") ? extractDocumentId(uri) : uri;
 }
+function loadCallContext(client, instanceId, options) {
+  return loadContext(client, instanceId, {
+    ...options?.clock ? { clock: options.clock } : {},
+    ...options?.clientForGdr ? { clientForGdr: options.clientForGdr } : {}
+  });
+}
 async function loadContext(client, instanceId, options) {
   const instance = await client.getDocument(instanceId);
   if (!instance)
@@ -1204,7 +1319,7 @@ async function ctxConditionParams(ctx, opts) {
     ...base,
     state,
     actor: opts?.actor,
-    assigned: opts?.taskName !== void 0 ? assignedFor(ctx.instance, opts.taskName, opts?.actor) : !1,
+    assigned: opts?.taskName !== void 0 ? assignedFor(ctx.instance, opts.taskName, opts?.actor, ctx.definition.roleAliases) : !1,
     ...opts?.vars
   };
   return { ...await evaluatePredicates({
@@ -1249,86 +1364,36 @@ async function resolveStageStateEntries(args) {
     ctx: {
       client,
       now,
-      selfId: instance._id,
-      tag: instance.tag,
-      stageName: stage.name,
-      workflowResource: instance.workflowResource,
-      // Allow stage-scope entries' `source: { type: "stateRead", scope:
-      // "workflow", ... }` to see the already-resolved workflow-scope state.
-      workflowState: instance.state ?? [],
-      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
-    },
-    randomKey
-  });
-}
-async function resolveTaskStateEntries(args) {
-  const { client, instance, stage, task, now } = args;
-  return resolveDeclaredState({
-    entryDefs: task.state,
-    initialState: [],
-    ctx: {
-      client,
-      now,
-      selfId: instance._id,
-      tag: instance.tag,
-      stageName: stage.name,
-      workflowResource: instance.workflowResource,
-      taskName: task.name,
-      workflowState: instance.state ?? [],
-      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
-    },
-    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");
+      selfId: instance._id,
+      tag: instance.tag,
+      stageName: stage.name,
+      workflowResource: instance.workflowResource,
+      // Allow stage-scope entries' `source: { type: "stateRead", scope:
+      // "workflow", ... }` to see the already-resolved workflow-scope state.
+      workflowState: instance.state ?? [],
+      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
+    },
+    randomKey
+  });
 }
-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 resolveTaskStateEntries(args) {
+  const { client, instance, stage, task, now } = args;
+  return resolveDeclaredState({
+    entryDefs: task.state,
+    initialState: [],
+    ctx: {
+      client,
+      now,
+      selfId: instance._id,
+      tag: instance.tag,
+      stageName: stage.name,
+      workflowResource: instance.workflowResource,
+      taskName: task.name,
+      workflowState: instance.state ?? [],
+      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
+    },
+    randomKey
+  });
 }
 async function deployOrRollback(args) {
   try {
@@ -1351,7 +1416,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) {
@@ -1440,7 +1509,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) {
@@ -1455,7 +1525,21 @@ 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, 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`);
@@ -1720,6 +1804,7 @@ async function prepareChildInstance(args) {
       selfId: childDocId,
       tag: childTag,
       workflowResource,
+      definitionName: definition.name,
       ...inheritedPerspective !== void 0 ? { perspective: inheritedPerspective } : {}
     },
     randomKey
@@ -1766,6 +1851,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 } : {},
@@ -1811,9 +1918,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,
@@ -1823,7 +1932,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 = {
@@ -1937,22 +2050,27 @@ function runOps(args) {
   const summaries = [];
   for (const op of ops) {
     const summary = applyOp(op, { mutation, stage, taskName: origin.task, params, actor, self, now });
-    summaries.push(summary), mutation.history.push({
-      _key: randomKey(),
-      _type: "opApplied",
-      at: now,
-      stage,
-      ...origin.task !== void 0 ? { task: origin.task } : {},
-      ...origin.action !== void 0 ? { action: origin.action } : {},
-      ...origin.transition !== void 0 ? { transition: origin.transition } : {},
-      opType: summary.opType,
-      ...summary.target !== void 0 ? { target: summary.target } : {},
-      ...summary.resolved !== void 0 ? { resolved: summary.resolved } : {},
-      ...actor !== void 0 ? { actor } : {}
-    });
+    summaries.push(summary), mutation.history.push(opAppliedEntry({ origin, summary, stage, actor, now }));
   }
   return summaries;
 }
+function opAppliedEntry(args) {
+  const { origin, summary, stage, actor, now } = args;
+  return {
+    _key: randomKey(),
+    _type: "opApplied",
+    at: now,
+    stage,
+    ...origin.task !== void 0 ? { task: origin.task } : {},
+    ...origin.action !== void 0 ? { action: origin.action } : {},
+    ...origin.transition !== void 0 ? { transition: origin.transition } : {},
+    ...origin.edit === !0 ? { edit: !0 } : {},
+    opType: summary.opType,
+    ...summary.target !== void 0 ? { target: summary.target } : {},
+    ...summary.resolved !== void 0 ? { resolved: summary.resolved } : {},
+    ...actor !== void 0 ? { actor } : {}
+  };
+}
 function applyOp(op, ctx) {
   switch (op.type) {
     case "state.set":
@@ -2283,28 +2401,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 };
@@ -2608,6 +2704,85 @@ async function fetchGrantsCached(requestFn, resourcePath) {
     return;
   }
 }
+function effectiveEditable(baseline, override) {
+  if (baseline === void 0) return;
+  if (override === void 0) return baseline;
+  if (baseline === !0 && override === !0) return !0;
+  const parts = [baseline, override].map((e) => e === !0 ? void 0 : e);
+  return andConditions(parts) ?? !0;
+}
+function slotSites(definition, stage) {
+  const sites = [];
+  for (const entry of definition.state ?? []) sites.push({ scope: "workflow", entry });
+  for (const entry of stage.state ?? []) sites.push({ scope: "stage", entry });
+  for (const task of stage.tasks ?? [])
+    for (const entry of task.state ?? []) sites.push({ scope: "task", task: task.name, entry });
+  return sites;
+}
+function toResolvedSlot(site, stage) {
+  return {
+    scope: site.scope,
+    ...site.task !== void 0 ? { task: site.task } : {},
+    name: site.entry.name,
+    type: site.entry.type,
+    ...site.entry.title !== void 0 ? { title: site.entry.title } : {},
+    ref: { scope: site.scope, state: site.entry.name },
+    effective: effectiveEditable(site.entry.editable, stage.editable?.[site.entry.name])
+  };
+}
+function editableSlotsInStage(definition, stage) {
+  return slotSites(definition, stage).filter((site) => site.entry.editable !== void 0).map((site) => toResolvedSlot(site, stage));
+}
+function editTargetMatches(slot, target) {
+  return slot.name !== target.state ? !1 : target.task !== void 0 ? slot.scope === "task" && slot.task === target.task : target.scope !== void 0 ? slot.scope === target.scope : !0;
+}
+const SCOPE_PRECEDENCE = { task: 0, stage: 1, workflow: 2 };
+function resolveEditTarget(args) {
+  const { definition, stage, target } = args, found = slotSites(definition, stage).filter(
+    (site) => editTargetMatches(
+      {
+        scope: site.scope,
+        name: site.entry.name,
+        ...site.task !== void 0 ? { task: site.task } : {}
+      },
+      target
+    )
+  ).sort((a, b) => SCOPE_PRECEDENCE[a.scope] - SCOPE_PRECEDENCE[b.scope])[0];
+  return found ? toResolvedSlot(found, stage) : void 0;
+}
+function slotWindowOpen(instance, slot) {
+  if (instance.completedAt !== void 0) return { open: !1, detail: "instance completed" };
+  if (instance.abortedAt !== void 0) return { open: !1, detail: "instance aborted" };
+  if (slot.scope !== "task") return { open: !0 };
+  const status = findOpenStageEntry(instance)?.tasks.find((t) => t.name === slot.task)?.status;
+  return status === "active" ? { open: !0 } : { open: !1, detail: `task "${slot.task}" is ${status ?? "not active"}` };
+}
+function readSlotValue(instance, slot) {
+  return slotStateHost(instance, slot)?.find((e) => e.name === slot.name)?.value;
+}
+function slotStateHost(instance, slot) {
+  if (slot.scope === "workflow") return instance.state;
+  const stageEntry = findOpenStageEntry(instance);
+  return slot.scope === "stage" ? stageEntry?.state : stageEntry?.tasks.find((t) => t.name === slot.task)?.state;
+}
+function slotProvenance(instance, ref) {
+  let latest;
+  for (const entry of instance.history)
+    entry._type === "opApplied" && (entry.target?.scope !== ref.scope || entry.target.state !== ref.state || (latest = { at: entry.at, ...entry.actor !== void 0 ? { actor: entry.actor } : {} }));
+  return latest === void 0 ? {} : {
+    ...latest.actor !== void 0 ? { setBy: latest.actor } : {},
+    setAt: latest.at
+  };
+}
+function editDisabledReason(args) {
+  const { effective, instance, window, guardDenial, predicateSatisfied } = args;
+  if (effective === void 0) return { kind: "not-editable" };
+  if (!window.open)
+    return instance.completedAt !== void 0 ? { kind: "instance-completed", completedAt: instance.completedAt } : { kind: "edit-window-closed", detail: window.detail ?? "closed" };
+  if (guardDenial !== void 0) return guardDenial;
+  if (!predicateSatisfied)
+    return { kind: "editor-not-permitted", predicate: effective === !0 ? "true" : effective };
+}
 async function evaluateInstance(args) {
   const { client, tag, instanceId, resourceClients } = args, now = (args.clock ?? wallClock)();
   validateTag(tag);
@@ -2641,6 +2816,7 @@ async function evaluateFromSnapshot(args) {
         actor,
         snapshot,
         scope,
+        roleAliases: definition.roleAliases,
         stageHasExits: !isTerminalStage(stage),
         guardDenial
       })
@@ -2662,16 +2838,65 @@ async function evaluateFromSnapshot(args) {
     stage,
     tasks: taskEvaluations,
     transitions: transitionEvaluations
-  }, pendingOnYou = taskEvaluations.filter((t) => t.pendingOnActor), canInteract = taskEvaluations.some((t) => t.actions.some((a) => a.allowed));
+  }, pendingOnYou = taskEvaluations.filter((t) => t.pendingOnActor), canInteract = taskEvaluations.some((t) => t.actions.some((a) => a.allowed)), editGuardDenial = guardDenial?.kind === "mutation-guard-denied" ? guardDenial : void 0, editableSlots = await evaluateEditableSlots({
+    instance,
+    definition,
+    stage,
+    actor,
+    snapshot,
+    scope,
+    guardDenial: editGuardDenial
+  });
   return {
     instance,
     definition,
     actor,
     currentStage,
     pendingOnYou,
-    canInteract
+    canInteract,
+    editableSlots
   };
 }
+async function evaluateEditableSlots(args) {
+  const { instance, definition, stage, actor, snapshot, scope, guardDenial } = args, slots = [];
+  for (const slot of editableSlotsInStage(definition, stage)) {
+    const window = slotWindowOpen(instance, slot), predicateSatisfied = await editPredicateSatisfied({
+      slot,
+      window,
+      guardDenial,
+      instance,
+      snapshot,
+      scope,
+      actor,
+      roleAliases: definition.roleAliases
+    }), reason = editDisabledReason({
+      effective: slot.effective,
+      instance,
+      window,
+      guardDenial,
+      predicateSatisfied
+    }), value = readSlotValue(instance, slot);
+    slots.push({
+      scope: slot.scope,
+      ...slot.task !== void 0 ? { task: slot.task } : {},
+      name: slot.name,
+      type: slot.type,
+      ...slot.title !== void 0 ? { title: slot.title } : {},
+      value,
+      editable: reason === void 0,
+      ...reason !== void 0 ? { disabledReason: reason } : {},
+      ...slotProvenance(instance, slot.ref)
+    });
+  }
+  return slots;
+}
+async function editPredicateSatisfied(args) {
+  const { slot, window, guardDenial, instance, snapshot, scope, actor, roleAliases } = args;
+  if (!window.open || guardDenial !== void 0) return !1;
+  if (slot.effective === !0) return !0;
+  const params = slot.scope === "task" && slot.task !== void 0 ? taskScopeFor({ scope, instance, snapshot, actor, taskName: slot.task, roleAliases }) : scope;
+  return evaluateCondition({ condition: slot.effective, snapshot, params });
+}
 async function renderScope(args) {
   const { instance, definition, actor, grants, snapshot, now } = args, params = {
     ...buildParams({ instance, now, snapshot }),
@@ -2697,15 +2922,36 @@ async function advisoryCan(instance, actor, grants) {
     });
   return can;
 }
-async function evaluateTask(args) {
-  const { task, statusEntry, instance, actor, snapshot, scope, stageHasExits, guardDenial } = args, status = statusEntry?.status ?? "pending", assigned = assignedFor(instance, task.name, actor), taskScope = {
+function taskScopeFor(args) {
+  const { scope, instance, snapshot, actor, taskName, roleAliases } = args;
+  return {
     ...scope,
     state: {
       ...scope.state,
-      ...scopedStateOverlay(instance, snapshot, task.name)
+      ...scopedStateOverlay(instance, snapshot, taskName)
     },
-    assigned
-  }, unmetRequirements = await evaluateRequirements({
+    assigned: assignedFor(instance, taskName, actor, roleAliases)
+  };
+}
+async function evaluateTask(args) {
+  const {
+    task,
+    statusEntry,
+    instance,
+    actor,
+    snapshot,
+    scope,
+    roleAliases,
+    stageHasExits,
+    guardDenial
+  } = args, status = statusEntry?.status ?? "pending", taskScope = taskScopeFor({
+    scope,
+    instance,
+    snapshot,
+    actor,
+    taskName: task.name,
+    roleAliases
+  }), assigned = taskScope.assigned === !0, unmetRequirements = await evaluateRequirements({
     requirements: task.requirements,
     snapshot,
     params: taskScope
@@ -2932,10 +3178,7 @@ async function commitAbort(ctx, reason, actor) {
 async function fireAction(args) {
   const { client, instanceId, task, 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 } : {},
-      ...options?.clientForGdr ? { clientForGdr: options.clientForGdr } : {}
-    });
+    const ctx = await loadCallContext(client, instanceId, options);
     try {
       return await commitAction(ctx, task, action, params, options);
     } catch (error) {
@@ -3030,6 +3273,114 @@ function formatDisabledReason(task, action, reason) {
   const detail = disabledReasonDetail[reason.kind](reason);
   return `Action "${task}:${action}" is not allowed: ${detail}`;
 }
+class EditStateDeniedError extends Error {
+  reason;
+  target;
+  constructor(args) {
+    super(formatEditDisabledReason(args.target, args.reason)), this.name = "EditStateDeniedError", this.reason = args.reason, this.target = args.target;
+  }
+}
+const editDisabledReasonDetail = {
+  "not-editable": () => "slot is not declared editable",
+  "instance-completed": (r) => `instance completed at ${r.completedAt}`,
+  "edit-window-closed": (r) => `edit window closed (${r.detail})`,
+  "editor-not-permitted": (r) => `editor not permitted (${r.predicate})`,
+  "mutation-guard-denied": (r) => `blocked by mutation guard(s) [${r.guardIds.join(", ")}]${r.detail ? ` (${r.detail})` : ""}`
+};
+function formatEditDisabledReason(target, reason) {
+  const detail = editDisabledReasonDetail[reason.kind](
+    reason
+  ), where = target.task !== void 0 ? `${target.task}.${target.state}` : target.state;
+  return `State "${target.scope}:${where}" is not editable: ${detail}`;
+}
+async function editState(args) {
+  const { client, instanceId, target, mode = "set", value, options } = args;
+  for (let attempt = 1; attempt <= CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS; attempt++) {
+    const ctx = await loadCallContext(client, instanceId, options);
+    try {
+      return await commitEdit(ctx, target, mode, value, options);
+    } catch (error) {
+      if (!isRevisionConflict(error)) throw error;
+    }
+  }
+  throw new ConcurrentEditStateError({
+    instanceId,
+    target: labelTarget(target),
+    attempts: CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS
+  });
+}
+async function commitEdit(ctx, target, mode, value, options) {
+  const actor = options?.actor, stage = findStage(ctx.definition, ctx.instance.currentStage), slot = resolveEditTarget({ definition: ctx.definition, stage, target });
+  if (slot === void 0)
+    throw new Error(
+      `No state slot "${describeTarget(target)}" resolves in current stage "${stage.name}" of ${ctx.definition.name}`
+    );
+  await assertSlotEditable(ctx, slot, options);
+  const op = buildEditOp(slot, mode, value), mutation = startMutation(ctx.instance), ranOps = runOps({
+    ops: [op],
+    mutation,
+    stage: stage.name,
+    origin: {
+      edit: !0,
+      ...slot.scope === "task" && slot.task !== void 0 ? { task: slot.task } : {}
+    },
+    params: {},
+    actor,
+    self: selfGdr(ctx.instance),
+    now: ctx.now
+  });
+  return await persistThenDeploy(
+    ctx,
+    mutation,
+    () => ranOps.some(isStateOp) ? refreshStageGuards(ctx, mutation, stage.name) : Promise.resolve()
+  ), {
+    edited: !0,
+    target: slotTarget(slot),
+    ...ranOps.length > 0 ? { ranOps } : {}
+  };
+}
+async function assertSlotEditable(ctx, slot, options) {
+  const actor = options?.actor, window = slotWindowOpen(ctx.instance, slot), can = options?.grants !== void 0 && actor !== void 0 ? await advisoryCan(ctx.instance, actor, options.grants) : void 0, predicateSatisfied = window.open && slot.effective !== !0 && slot.effective !== void 0 ? await ctxEvaluateCondition(ctx, slot.effective, {
+    ...slot.task !== void 0 ? { taskName: slot.task } : {},
+    ...actor !== void 0 ? { actor } : {},
+    ...can !== void 0 ? { vars: { can } } : {}
+  }) : slot.effective === !0, reason = editDisabledReason({
+    effective: slot.effective,
+    instance: ctx.instance,
+    window,
+    guardDenial: void 0,
+    predicateSatisfied
+  });
+  if (reason !== void 0) throw new EditStateDeniedError({ target: slotTarget(slot), reason });
+}
+function buildEditOp(slot, mode, value) {
+  if (mode === "unset") return { type: "state.unset", target: slot.ref };
+  if (value === void 0)
+    throw new Error(`editState mode "${mode}" requires a value for slot "${slot.name}"`);
+  return {
+    type: mode === "append" ? "state.append" : "state.set",
+    target: slot.ref,
+    value: { type: "literal", value }
+  };
+}
+function slotTarget(slot) {
+  return {
+    scope: slot.scope,
+    state: slot.name,
+    ...slot.task !== void 0 ? { task: slot.task } : {}
+  };
+}
+function labelTarget(target) {
+  return {
+    scope: target.scope ?? (target.task !== void 0 ? "task" : "workflow"),
+    state: target.state,
+    ...target.task !== void 0 ? { task: target.task } : {}
+  };
+}
+function describeTarget(target) {
+  const where = target.task !== void 0 ? `${target.task}.${target.state}` : target.state;
+  return target.scope !== void 0 ? `${target.scope}:${where}` : where;
+}
 function bareIdFromSpawnRef(uri) {
   if (!uri.includes(":")) return [uri];
   try {
@@ -3076,18 +3427,60 @@ function buildClientForGdr(defaultClient, resolver) {
 function toEffectsContextEntries(ctx) {
   return Object.entries(ctx).map(([id, value]) => effectsContextEntry(id, value));
 }
+async function dispatchGatedWrite(args) {
+  const { client, tag, instanceId, resourceClients, access, apply } = args, evaluation = await evaluateInstance({
+    client,
+    tag,
+    instanceId,
+    access,
+    clock: args.clock,
+    ...resourceClients !== void 0 ? { resourceClients } : {}
+  }), ranOps = await apply(args.before, evaluation), cascaded = await cascade(client, instanceId, args.actor, args.clientForGdr, args.clock);
+  return {
+    instance: await reload(client, instanceId, tag),
+    cascaded,
+    fired: !0,
+    ...ranOps !== void 0 ? { ranOps } : {}
+  };
+}
 function assertActionAllowed(evaluation, task, action) {
   const actionEval = evaluation.currentStage.tasks.find((t) => t.task.name === task)?.actions.find((a) => a.action.name === action);
   if (actionEval?.allowed === !1 && actionEval.disabledReason)
     throw new ActionDisabledError({ task, action, reason: actionEval.disabledReason });
 }
-async function applyAction(args) {
-  const { client, instance, task, action, params, actor, grants, clock, clientForGdr } = args, options = {
-    actor,
-    ...grants !== void 0 ? { grants } : {},
-    ...clock !== void 0 ? { clock } : {},
-    ...clientForGdr !== void 0 ? { clientForGdr } : {}
+function assertEditAllowed(evaluation, target) {
+  const slot = evaluation.editableSlots.filter((s) => editTargetMatches(s, target)).sort((a, b) => SCOPE_PRECEDENCE[a.scope] - SCOPE_PRECEDENCE[b.scope])[0];
+  if (slot !== void 0 && !slot.editable && slot.disabledReason !== void 0)
+    throw new EditStateDeniedError({
+      target: {
+        scope: slot.scope,
+        state: slot.name,
+        ...slot.task !== void 0 ? { task: slot.task } : {}
+      },
+      reason: slot.disabledReason
+    });
+}
+async function applyEdit(args) {
+  const { client, instance, target, mode, value, actor, grants, clock, clientForGdr } = args;
+  return (await editState({
+    client,
+    instanceId: instance._id,
+    target,
+    ...mode !== void 0 ? { mode } : {},
+    ...value !== void 0 ? { value } : {},
+    options: buildEngineCallOptions({ actor, grants, clock, clientForGdr })
+  })).ranOps;
+}
+function buildEngineCallOptions(args) {
+  return {
+    actor: args.actor,
+    ...args.grants !== void 0 ? { grants: args.grants } : {},
+    ...args.clock !== void 0 ? { clock: args.clock } : {},
+    ...args.clientForGdr !== void 0 ? { clientForGdr: args.clientForGdr } : {}
   };
+}
+async function applyAction(args) {
+  const { client, instance, task, action, params, actor, grants, clock, clientForGdr } = args, options = buildEngineCallOptions({ actor, grants, clock, clientForGdr });
   return findOpenStageEntry(instance)?.tasks.find((t) => t.name === task)?.status === "pending" && await invokeTask({ client, instanceId: instance._id, task, options }), (await fireAction({
     client,
     instanceId: instance._id,
@@ -3261,6 +3654,7 @@ const workflow = {
         selfId: id,
         tag,
         workflowResource,
+        definitionName: definition.name,
         ...perspective !== void 0 ? { perspective } : {}
       },
       randomKey
@@ -3302,34 +3696,68 @@ const workflow = {
       idempotent,
       resourceClients
     } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, before = await reload(client, instanceId, tag);
-    if (findOpenStageEntry(before)?.tasks.find((t) => t.name === task) === void 0 && idempotent === !0)
-      return { instance: before, cascaded: 0, fired: !1 };
-    const evaluation = await evaluateInstance({
+    return findOpenStageEntry(before)?.tasks.find((t) => t.name === task) === void 0 && idempotent === !0 ? { instance: before, cascaded: 0, fired: !1 } : dispatchGatedWrite({
       client,
       tag,
       instanceId,
       access,
+      actor,
+      clientForGdr,
       clock,
-      ...resourceClients !== void 0 ? { resourceClients } : {}
+      before,
+      ...resourceClients !== void 0 ? { resourceClients } : {},
+      apply: (instance, evaluation) => (assertActionAllowed(evaluation, task, action), applyAction({
+        client,
+        instance,
+        task,
+        action,
+        actor,
+        ...access.grants !== void 0 ? { grants: access.grants } : {},
+        clock,
+        clientForGdr,
+        ...params !== void 0 ? { params } : {}
+      }))
     });
-    assertActionAllowed(evaluation, task, action);
-    const ranOps = await applyAction({
+  },
+  /**
+   * Edit a declared-editable state slot directly — reassign, reschedule,
+   * claim-by-hand, append to a running log — through the generic edit seam,
+   * instead of a bespoke action per field. Soft-gates on the slot's declared
+   * editability (the same projection a UI renders), applies the edit as a
+   * `state.*` op (so provenance + history are stamped by the op path),
+   * refreshes the stage's guards, then cascades — an edit to a value a
+   * transition reads can and should move the instance. Advisory like every
+   * engine gate; the lake ACL + guards are the only hard locks.
+   *
+   * Each call is a discrete COMMIT (a history entry, a guard refresh, a
+   * cascade, an `ifRevisionId` write), not a draft patch — so an inline-field
+   * UI must bind it to a deliberate boundary (blur / Enter / Save / debounce),
+   * never an `onChange` per keystroke.
+   */
+  editState: async (args) => {
+    const { client, tag, instanceId, target, mode, value, resourceClients } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, before = await reload(client, instanceId, tag);
+    return dispatchGatedWrite({
       client,
-      instance: before,
-      task,
-      action,
+      tag,
+      instanceId,
+      access,
       actor,
-      ...access.grants !== void 0 ? { grants: access.grants } : {},
-      clock,
       clientForGdr,
-      ...params !== void 0 ? { params } : {}
-    }), cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
-    return {
-      instance: await reload(client, instanceId, tag),
-      cascaded,
-      fired: !0,
-      ...ranOps !== void 0 ? { ranOps } : {}
-    };
+      clock,
+      before,
+      ...resourceClients !== void 0 ? { resourceClients } : {},
+      apply: (instance, evaluation) => (assertEditAllowed(evaluation, target), applyEdit({
+        client,
+        instance,
+        target,
+        ...mode !== void 0 ? { mode } : {},
+        ...value !== void 0 ? { value } : {},
+        actor,
+        ...access.grants !== void 0 ? { grants: access.grants } : {},
+        clock,
+        clientForGdr
+      }))
+    });
   },
   /**
    * Report a queued effect's outcome. Drains it from `pendingEffects`,
@@ -3747,6 +4175,9 @@ function createInstanceSession(args) {
       ...clock !== void 0 ? { now: clock() } : {},
       ...grants !== void 0 ? { grants } : {}
     });
+  }, settleAfterApply = async (actor, held, ranOps) => {
+    const cascaded = await cascade(client, instance._id, actor, clientForGdr, clock, held);
+    return instance = await reload(client, instance._id, tag), { instance, cascaded, fired: !0, ...ranOps !== void 0 ? { ranOps } : {} };
   }, commit = async (run) => {
     committing = !0;
     const held = new Map(overlay);
@@ -3797,8 +4228,25 @@ function createInstanceSession(args) {
           ...grants !== void 0 ? { grants } : {},
           ...clock !== void 0 ? { clock } : {},
           ...params !== void 0 ? { params } : {}
-        }), cascaded = await cascade(client, instance._id, actor, clientForGdr, clock, held);
-        return instance = await reload(client, instance._id, tag), { instance, cascaded, fired: !0, ...ranOps !== void 0 ? { ranOps } : {} };
+        });
+        return settleAfterApply(actor, held, ranOps);
+      });
+    },
+    editState({ target, mode, value }) {
+      return commit(async (actor, held) => {
+        assertEditAllowed(await evaluateWith(held, heldGuards), target);
+        const { grants } = await access(), ranOps = await applyEdit({
+          client,
+          instance,
+          target,
+          ...mode !== void 0 ? { mode } : {},
+          ...value !== void 0 ? { value } : {},
+          actor,
+          clientForGdr,
+          ...grants !== void 0 ? { grants } : {},
+          ...clock !== void 0 ? { clock } : {}
+        });
+        return settleAfterApply(actor, held, ranOps);
       });
     }
   };
@@ -3846,6 +4294,7 @@ function createEngine(args) {
     deployDefinitions: (rest) => workflow.deployDefinitions(bind(rest)),
     startInstance: (rest) => workflow.startInstance(bind(rest)),
     fireAction: (rest) => workflow.fireAction(bind(rest)),
+    editState: (rest) => workflow.editState(bind(rest)),
     completeEffect: (rest) => workflow.completeEffect(bind(rest)),
     tick: (rest) => workflow.tick(bind(rest)),
     evaluateInstance: (rest) => evaluateInstance(bind(rest)),
@@ -4141,16 +4590,20 @@ export {
   ActionDisabledError,
   ActionParamsInvalidError,
   CascadeLimitError,
+  ConcurrentEditStateError,
   ConcurrentFireActionError,
   DEFAULT_CONTENT_PERSPECTIVE,
   DISPLAY,
   EFFECTS_CONTEXT_DISPLAY,
+  EditStateDeniedError,
   GUARD_DOC_TYPE,
   GUARD_LIFTED_PREDICATE,
   GUARD_OWNER,
   HISTORY_DISPLAY,
   MutationGuardDeniedError,
   OP_DISPLAY,
+  PartialGuardDeployError,
+  RequiredStateNotProvidedError,
   STATE_SLOT_DISPLAY,
   WORKFLOW_DEFINITION_TYPE,
   WORKFLOW_INSTANCE_TYPE,
@@ -4186,6 +4639,7 @@ export {
   instanceGuardQuery,
   isDefinitionUnchanged,
   isGdr,
+  isStartableDefinition,
   isTerminalStage,
   lakeGuardId,
   parseGdr,