@sanity/workflow-engine 0.8.0 → 0.9.0

package/dist/index.js

@@ -1,5 +1,5 @@
 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 findOpenStageEntry(host) {
@@ -140,11 +140,11 @@ function scopedStateOverlay(instance, snapshot, taskName) {
   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) {
+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 : (actor.roles ?? []).includes(a.role)
+    (a) => a.type === "user" ? a.id === actor.id : actorFulfillsRole(actor.roles, a.role, roleAliases)
   );
 }
 function effectsContextMap(instance) {
@@ -663,6 +663,17 @@ function isRevisionConflict(error) {
   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;
@@ -1282,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)
@@ -1302,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({
@@ -2033,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":
@@ -2682,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);
@@ -2715,6 +2816,7 @@ async function evaluateFromSnapshot(args) {
         actor,
         snapshot,
         scope,
+        roleAliases: definition.roleAliases,
         stageHasExits: !isTerminalStage(stage),
         guardDenial
       })
@@ -2736,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 }),
@@ -2771,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
@@ -3006,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) {
@@ -3104,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 {
@@ -3150,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,
@@ -3377,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`,
@@ -3822,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);
@@ -3872,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);
       });
     }
   };
@@ -3921,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)),
@@ -4216,10 +4590,12 @@ export {
   ActionDisabledError,
   ActionParamsInvalidError,
   CascadeLimitError,
+  ConcurrentEditStateError,
   ConcurrentFireActionError,
   DEFAULT_CONTENT_PERSPECTIVE,
   DISPLAY,
   EFFECTS_CONTEXT_DISPLAY,
+  EditStateDeniedError,
   GUARD_DOC_TYPE,
   GUARD_LIFTED_PREDICATE,
   GUARD_OWNER,