@sanity/workflow-engine 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,4 +1,5 @@
 import { parse, evaluate } from "groq-js";
+import { WORKFLOW_DEFINITION_TYPE } from "./_chunks-es/schema.js";
 import * as v from "valibot";
 function validateDefinition(definition) {
   const v2 = createDefinitionValidator();
@@ -177,9 +178,94 @@ function stripStateForLake(value) {
 function bareId(id) {
   return isGdrUri(id) ? extractDocumentId(id) : id;
 }
-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);
+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 readStateSlot(instance, scope, slotId, stageId, taskId) {
+  if (scope === "workflow")
+    return slotValue$1(instance.state?.find((s) => s.id === slotId));
+  const stageEntry = instance.stages.find(
+    (s) => s.id === (stageId ?? instance.currentStageId) && s.exitedAt === void 0
+  );
+  if (stageEntry === void 0) return;
+  if (scope === "stage")
+    return slotValue$1(stageEntry.state?.find((s) => s.id === slotId));
+  const taskEntry = stageEntry.tasks.find((t) => t.id === taskId);
+  return slotValue$1(taskEntry?.state?.find((s) => s.id === slotId));
+}
+function slotValue$1(slot) {
+  if (slot != null && typeof slot == "object")
+    return slot.value;
+}
+function resolveStaticSource(src, ctx) {
+  switch (src.source) {
+    case "literal":
+      return { handled: !0, value: src.value };
+    case "param":
+      return { handled: !0, value: ctx.params?.[src.paramId] };
+    case "actor":
+      return { handled: !0, value: ctx.actor };
+    case "now":
+      return { handled: !0, value: ctx.now };
+    default:
+      return { handled: !1 };
+  }
+}
+function resolveSource(src, ctx) {
+  const staticValue = resolveStaticSource(src, ctx);
+  if (staticValue.handled) return staticValue.value;
+  switch (src.source) {
+    case "self":
+      return ctx.instance._id;
+    case "stageId":
+      return ctx.stageId ?? ctx.instance.currentStageId;
+    case "stateRead":
+      return resolveStateRead(src, ctx);
+    case "effectOutput":
+      return resolveEffectOutput(src, ctx);
+    case "object":
+      return resolveObject(src, ctx);
+    case "row":
+    case "parentState":
+      return;
+    default:
+      return;
+  }
+}
+function resolveStateRead(src, ctx) {
+  const value = readStateSlot(ctx.instance, src.scope, src.slotId, ctx.stageId, ctx.taskId);
+  return src.path !== void 0 ? getPath(value, src.path) : value;
+}
+function resolveEffectOutput(src, ctx) {
+  const entry = ctx.instance.effectsContext.find((e) => e.id === src.contextId);
+  if (entry === void 0) return null;
+  const value = src.path !== void 0 ? getPath(entry.value, src.path) : entry.value;
+  return value === void 0 ? null : value;
+}
+function resolveObject(src, ctx) {
+  const out = {};
+  for (const [field, fieldSrc] of Object.entries(src.fields))
+    out[field] = resolveSource(fieldSrc, ctx);
+  return out;
+}
+async function resolveBindings(args) {
+  const { bindings, staticInput, instance, now, params, actor } = args, resolved = {};
+  if (bindings) {
+    const ctx = {
+      instance,
+      now,
+      ...params !== void 0 ? { params } : {},
+      ...actor !== void 0 ? { actor } : {}
+    };
+    for (const [key, src] of Object.entries(bindings))
+      resolved[key] = resolveSource(src, ctx);
+  }
+  return { ...resolved, ...staticInput };
 }
 async function evaluateFilter(args) {
   const { filter, definition, snapshot, params } = args;
@@ -235,130 +321,333 @@ function matchesParamType(type, value) {
 function describeValue(value) {
   return Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
 }
-function buildSnapshot(args) {
-  const docs = [], knownIds = /* @__PURE__ */ new Set();
-  for (const { doc, resource } of args.docs) {
-    const uri = gdrFromResource(resource, doc._id), restamped = restampForSnapshot(doc, uri, resource);
-    docs.push(restamped), knownIds.add(uri);
+const GUARD_DOC_TYPE = "temp.system.guard";
+class MutationGuardDeniedError extends Error {
+  denied;
+  documentId;
+  action;
+  constructor(args) {
+    const ids = args.denied.map((d) => d.guardId).join(", ");
+    super(`Mutation on "${args.documentId}" (${args.action}) denied by guard(s) [${ids}]`), this.name = "MutationGuardDeniedError", this.denied = args.denied, this.documentId = args.documentId, this.action = args.action;
   }
-  return { docs, knownIds };
-}
-function restampForSnapshot(doc, gdrUri2, resource) {
-  return { ...rewriteRefsRecursive(doc, resource), _id: gdrUri2 };
 }
-function rewriteRefsRecursive(value, resource) {
-  if (Array.isArray(value))
-    return value.map((v2) => rewriteRefsRecursive(v2, resource));
-  if (value === null || typeof value != "object") return value;
-  const obj = value, out = {};
-  for (const [k, v2] of Object.entries(obj))
-    k === "_ref" && typeof v2 == "string" ? out[k] = v2.includes(":") ? v2 : gdrFromResource(resource, v2) : out[k] = rewriteRefsRecursive(v2, resource);
-  return out;
+function lakeGuardId(args) {
+  return `${GUARD_DOC_TYPE}.${args.instanceDocId}.${args.stageId}.${args.index}`;
 }
-async function hydrateSnapshot(args) {
-  const { client, clientForGdr, instance, definition } = args, loaded = [], visited = /* @__PURE__ */ new Set(), loadInto = async (uri) => {
-    if (visited.has(uri)) return;
-    const fetched = await loadByGdr(client, clientForGdr, instance.workflowResource, uri);
-    fetched && (loaded.push(fetched), visited.add(uri));
+function compileGuard(args) {
+  return {
+    _id: args.id,
+    _type: GUARD_DOC_TYPE,
+    resourceType: args.resourceType,
+    resourceId: args.resourceId,
+    owner: args.owner,
+    sourceInstanceId: args.sourceInstanceId,
+    sourceDefinitionId: args.sourceDefinitionId,
+    sourceStageId: args.sourceStageId,
+    ...args.name !== void 0 ? { name: args.name } : {},
+    ...args.description !== void 0 ? { description: args.description } : {},
+    match: args.match,
+    predicate: args.predicate,
+    metadata: args.metadata
   };
-  loaded.push({ doc: instance, resource: instance.workflowResource }), visited.add(selfGdr(instance));
-  for (const ancestor of instance.ancestors)
-    await loadInto(ancestor.id);
-  for (const uri of collectSlotDocUris(instance.state))
-    await loadInto(uri);
-  if (definition) {
-    const stageEntry = instance.stages.find(
-      (s) => s.id === instance.currentStageId && s.exitedAt === void 0
-    );
-    for (const uri of collectSlotDocUris(stageEntry?.state))
-      await loadInto(uri);
+}
+function toGroqJsPredicate(predicate) {
+  return predicate.replace(new RegExp("(?<!\\$)\\bguard\\.", "g"), "$guard.").replace(new RegExp("(?<!\\$)\\bmutation\\.", "g"), "$mutation.");
+}
+function globMatch(pattern, value) {
+  if (!pattern.includes("*")) return pattern === value;
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`).test(value);
+}
+function guardMatches(guard, doc, action) {
+  const m = guard.match;
+  if (!m.actions.includes(action) || m.types && m.types.length > 0 && !(doc.type !== void 0 && m.types.includes(doc.type)))
+    return !1;
+  if (m.idRefs && m.idRefs.length > 0 || m.idPatterns && m.idPatterns.length > 0) {
+    const byRef = m.idRefs?.includes(doc.id) ?? !1, byPattern = m.idPatterns?.some((p) => globMatch(p, doc.id)) ?? !1;
+    if (!byRef && !byPattern) return !1;
   }
-  return buildSnapshot({ docs: loaded });
+  return !0;
 }
-async function loadByGdr(defaultClient, clientForGdr, defaultResource, uri) {
-  let parsed;
+async function evaluateMutationGuard(args) {
+  const { guard, context } = args;
+  if (guard.predicate === "") return !1;
+  const params = { guard, mutation: { action: context.action } };
   try {
-    parsed = parseGdr(uri);
+    const tree = parse(toGroqJsPredicate(guard.predicate), { mode: "delta", params });
+    return await (await evaluate(tree, {
+      before: context.before,
+      after: context.after,
+      params,
+      ...context.identity !== void 0 ? { identity: context.identity } : {}
+    })).get() === !0;
   } catch {
-    const doc2 = await defaultClient.getDocument(uri);
-    return doc2 ? { doc: doc2, resource: defaultResource } : null;
+    return !1;
   }
-  const doc = await clientForGdr(parsed).getDocument(parsed.documentId);
-  return doc ? { doc, resource: resourceFromParsed(parsed) } : null;
 }
-function resourceFromParsed(parsed) {
-  return parsed.scheme === "dataset" ? { type: "dataset", id: `${parsed.projectId}.${parsed.dataset}` } : { type: parsed.scheme, id: parsed.resourceId ?? "" };
+async function denyingGuards(args) {
+  const { guards, doc, context } = args, denied = [];
+  for (const guard of guards)
+    guardMatches(guard, doc, context.action) && (await evaluateMutationGuard({ guard, context }) || denied.push(guard));
+  return denied;
 }
-function collectSlotDocUris(resolvedStateSlots) {
-  return Array.isArray(resolvedStateSlots) ? resolvedStateSlots.flatMap(slotDocUris) : [];
+function resourceOf(p) {
+  return p.scheme === "dataset" ? { type: "dataset", id: `${p.projectId}.${p.dataset}` } : { type: p.scheme, id: p.resourceId ?? "" };
 }
-function slotDocUris(slot) {
-  if (!slot || typeof slot != "object") return [];
-  const s = slot;
-  if (s._type === "workflow.state.doc.ref") {
-    const v2 = s.value, id = refId(v2);
-    return id !== void 0 ? [id] : [];
-  }
-  if (s._type === "workflow.state.doc.refs") {
-    const v2 = s.value;
-    return Array.isArray(v2) ? v2.map(refId).filter((id) => id !== void 0) : [];
+function resolveIdRefTarget(src, ctx) {
+  const value = resolveSource(src, ctx);
+  if (typeof value == "string" && isGdrUri(value))
+    return { parsed: parseGdr(value) };
+  if (value && typeof value == "object") {
+    const v2 = value;
+    if (typeof v2.id == "string" && isGdrUri(v2.id))
+      return typeof v2.type == "string" ? { parsed: parseGdr(v2.id), type: v2.type } : { parsed: parseGdr(v2.id) };
   }
-  return [];
-}
-function refId(ref) {
-  return ref && typeof ref.id == "string" ? ref.id : void 0;
+  return null;
 }
-function getPath(value, path) {
-  let current = value;
-  for (const part of path.split(".")) {
-    if (current == null || typeof current != "object") return;
-    current = current[part];
+function resolveIdRefTargets(idRefs, ctx) {
+  const targets = [];
+  for (const src of idRefs ?? []) {
+    const target = resolveIdRefTarget(src, ctx);
+    if (target === null) return null;
+    targets.push(target);
   }
-  return current;
+  return targets.length === 0 ? null : targets;
 }
-class SlotValueShapeError extends Error {
-  slotType;
-  slotId;
-  issues;
-  constructor(args) {
-    const issueText = args.issues.join("; ");
-    super(`Slot ${args.mode} shape invalid for "${args.slotId}" (${args.slotType}): ${issueText}`), this.name = "SlotValueShapeError", this.slotType = args.slotType, this.slotId = args.slotId, this.issues = args.issues;
+function assertSingleResource(targets) {
+  const resource = resourceOf(targets[0].parsed);
+  for (const g of targets) {
+    const r = resourceOf(g.parsed);
+    if (r.type !== resource.type || r.id !== resource.id)
+      throw new Error(
+        `Guard targets span multiple resources (${resource.type}:${resource.id} vs ${r.type}:${r.id}); a guard is single-resource.`
+      );
   }
+  return resource;
 }
-const GdrShape = v.looseObject({
-  id: v.pipe(
-    v.string(),
-    v.check((s) => isGdrUri(s), "must be a GDR URI")
-  ),
-  type: v.pipe(v.string(), v.minLength(1))
-}), ReleaseRefShape = v.looseObject({
-  id: v.pipe(
-    v.string(),
-    v.check((s) => isGdrUri(s), "must be a GDR URI")
-  ),
-  type: v.literal("system.release"),
-  releaseName: v.pipe(v.string(), v.minLength(1))
-}), ActorShape = v.looseObject({
-  kind: v.picklist(["user", "ai", "system"]),
-  id: v.pipe(v.string(), v.minLength(1)),
-  roles: v.optional(v.array(v.string())),
-  onBehalfOf: v.optional(v.string())
-}), AssigneeShape = v.union([
-  v.looseObject({ kind: v.literal("user"), id: v.pipe(v.string(), v.minLength(1)) }),
-  v.looseObject({ kind: v.literal("role"), role: v.pipe(v.string(), v.minLength(1)) })
-]), ChecklistItemShape = v.looseObject({
-  label: v.pipe(v.string(), v.minLength(1)),
-  done: v.boolean(),
-  doneBy: v.optional(v.string()),
-  doneAt: v.optional(v.string()),
-  _key: v.optional(v.pipe(v.string(), v.minLength(1)))
-}), NoteItemShape = v.pipe(
-  v.looseObject({
-    _key: v.optional(v.pipe(v.string(), v.minLength(1)))
-  }),
-  v.check(
-    (val) => typeof val == "object" && val !== null && !Array.isArray(val),
-    "must be an object"
+function bareIdRefs(targets) {
+  return targets.flatMap((g) => [g.parsed.documentId, `drafts.${g.parsed.documentId}`]);
+}
+function resolveMatchTypes(targets, authorTypes) {
+  if (authorTypes !== void 0) return authorTypes;
+  const inferred = [...new Set(targets.map((g) => g.type).filter((t) => !!t))];
+  return inferred.length > 0 ? inferred : void 0;
+}
+function resolveMetadata(metadata, ctx) {
+  const out = {};
+  for (const [k, src] of Object.entries(metadata ?? {}))
+    out[k] = resolveSource(src, ctx);
+  return out;
+}
+const GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
+function resolveGuard(guard, index, instance, stageId, now) {
+  const ctx = { instance, stageId, now }, targets = resolveIdRefTargets(guard.match.idRefs, ctx);
+  if (targets === null) return null;
+  const resource = assertSingleResource(targets), types = resolveMatchTypes(targets, guard.match.types);
+  return { doc: compileGuard({
+    id: lakeGuardId({ instanceDocId: instance._id, stageId, index }),
+    resourceType: resource.type,
+    resourceId: resource.id,
+    owner: GUARD_OWNER,
+    sourceInstanceId: instance._id,
+    sourceDefinitionId: instance.workflowId,
+    sourceStageId: stageId,
+    ...guard.name !== void 0 ? { name: guard.name } : {},
+    ...guard.description !== void 0 ? { description: guard.description } : {},
+    match: {
+      ...types !== void 0 ? { types } : {},
+      idRefs: bareIdRefs(targets),
+      ...guard.match.idPatterns !== void 0 ? { idPatterns: guard.match.idPatterns } : {},
+      actions: guard.match.actions
+    },
+    predicate: guard.predicate ?? "",
+    metadata: resolveMetadata(guard.metadata, ctx)
+  }), routeGdr: targets[0].parsed };
+}
+async function upsertGuard(client, doc) {
+  if (!await client.getDocument(doc._id)) {
+    await client.create(doc);
+    return;
+  }
+  const { _id, _type, _rev, _createdAt, _updatedAt, ...body } = doc;
+  await client.patch(doc._id).set(body).commit();
+}
+function resolvedStageGuards(args) {
+  const stage = args.definition.stages.find((s) => s.id === args.stageId), out = [];
+  for (const [index, guard] of (stage?.guards ?? []).entries()) {
+    const resolved = resolveGuard(guard, index, args.instance, args.stageId, args.now);
+    resolved !== null && out.push({ client: args.clientForGdr(resolved.routeGdr), doc: resolved.doc });
+  }
+  return out;
+}
+async function committedStageId(args) {
+  return (await args.client.getDocument(args.instance._id))?.currentStageId;
+}
+async function deployStageGuards(args) {
+  if (await committedStageId(args) === args.stageId)
+    for (const { client, doc } of resolvedStageGuards(args))
+      await upsertGuard(client, doc);
+}
+async function retractStageGuards(args) {
+  const live = await committedStageId(args);
+  if (!(live === void 0 || live === args.stageId))
+    for (const { client, doc } of resolvedStageGuards(args))
+      await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit();
+}
+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);
+}
+function buildSnapshot(args) {
+  const docs = [], knownIds = /* @__PURE__ */ new Set();
+  for (const { doc, resource } of args.docs) {
+    const uri = gdrFromResource(resource, doc._id), restamped = restampForSnapshot(doc, uri, resource);
+    docs.push(restamped), knownIds.add(uri);
+  }
+  return { docs, knownIds };
+}
+function restampForSnapshot(doc, gdrUri2, resource) {
+  return { ...rewriteRefsRecursive(doc, resource), _id: gdrUri2 };
+}
+function rewriteRefsRecursive(value, resource) {
+  if (Array.isArray(value))
+    return value.map((v2) => rewriteRefsRecursive(v2, resource));
+  if (value === null || typeof value != "object") return value;
+  const obj = value, out = {};
+  for (const [k, v2] of Object.entries(obj))
+    k === "_ref" && typeof v2 == "string" ? out[k] = v2.includes(":") ? v2 : gdrFromResource(resource, v2) : out[k] = rewriteRefsRecursive(v2, resource);
+  return out;
+}
+function findOpenStageEntry(host) {
+  return host.stages.find((s) => s.id === host.currentStageId && s.exitedAt === void 0);
+}
+function collectWatchRefs(instance) {
+  const stage = findOpenStageEntry(instance);
+  return [
+    gdrRef(instance.workflowResource, instance._id, instance._type),
+    ...instance.ancestors,
+    ...slotDocRefs(instance.state),
+    ...slotDocRefs(stage?.state),
+    ...slotReleaseRefs(instance.state),
+    ...slotReleaseRefs(stage?.state)
+  ];
+}
+function readsRaw(ref) {
+  return ref.type === "workflow.instance" || ref.type === "system.release";
+}
+function contentReleaseName(args) {
+  const { ref, perspective } = args;
+  if (!readsRaw(ref) && Array.isArray(perspective))
+    return perspective.find((entry) => entry !== "drafts" && entry !== "published" && entry !== "raw");
+}
+function subscriptionDocumentsForInstance(instance) {
+  const seen = /* @__PURE__ */ new Set(), documents = [];
+  for (const ref of collectWatchRefs(instance))
+    !isGdrUri(ref.id) || seen.has(ref.id) || (seen.add(ref.id), documents.push({ ...parseGdr(ref.id), globalDocumentId: ref.id, type: ref.type }));
+  return {
+    documents,
+    ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
+  };
+}
+function slotDocRefs(slots) {
+  return slotEntries(slots).flatMap((slot) => slot._type === "workflow.state.doc.ref" ? isGdr(slot.value) ? [slot.value] : [] : slot._type === "workflow.state.doc.refs" ? Array.isArray(slot.value) ? slot.value.filter(isGdr) : [] : []);
+}
+function slotReleaseRefs(slots) {
+  return slotEntries(slots).flatMap(
+    (slot) => slot._type === "workflow.state.release.ref" && isGdr(slot.value) ? [slot.value] : []
+  );
+}
+function slotEntries(slots) {
+  return Array.isArray(slots) ? slots.filter(
+    (slot) => !!slot && typeof slot == "object"
+  ) : [];
+}
+async function hydrateSnapshot(args) {
+  const { client, clientForGdr, instance, overlay } = args, loaded = [], visited = /* @__PURE__ */ new Set(), loadInto = async (uri, perspective) => {
+    if (visited.has(uri)) return;
+    const held = overlay?.get(uri);
+    if (held !== void 0) {
+      loaded.push(held), visited.add(uri);
+      return;
+    }
+    const fetched = await loadByGdr(
+      client,
+      clientForGdr,
+      instance.workflowResource,
+      uri,
+      perspective
+    );
+    fetched && (loaded.push(fetched), visited.add(uri));
+  };
+  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);
+  return buildSnapshot({ docs: loaded });
+}
+async function loadByGdr(defaultClient, clientForGdr, defaultResource, uri, perspective) {
+  let parsed;
+  try {
+    parsed = parseGdr(uri);
+  } catch {
+    const doc2 = await readDoc(defaultClient, uri, perspective);
+    return doc2 ? { doc: doc2, resource: defaultResource } : null;
+  }
+  const routed = clientForGdr(parsed), doc = await readDoc(routed, parsed.documentId, perspective);
+  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;
+}
+function resourceFromParsed(parsed) {
+  return parsed.scheme === "dataset" ? { type: "dataset", id: `${parsed.projectId}.${parsed.dataset}` } : { type: parsed.scheme, id: parsed.resourceId ?? "" };
+}
+function collectSlotDocUris(resolvedStateSlots) {
+  return slotDocRefs(resolvedStateSlots).map((ref) => ref.id);
+}
+const WORKFLOW_INSTANCE_TYPE = "workflow.instance";
+class SlotValueShapeError extends Error {
+  slotType;
+  slotId;
+  issues;
+  constructor(args) {
+    const issueText = args.issues.join("; ");
+    super(`Slot ${args.mode} shape invalid for "${args.slotId}" (${args.slotType}): ${issueText}`), this.name = "SlotValueShapeError", this.slotType = args.slotType, this.slotId = args.slotId, this.issues = args.issues;
+  }
+}
+const GdrShape = v.looseObject({
+  id: v.pipe(
+    v.string(),
+    v.check((s) => isGdrUri(s), "must be a GDR URI")
+  ),
+  type: v.pipe(v.string(), v.minLength(1))
+}), ReleaseRefShape = v.looseObject({
+  id: v.pipe(
+    v.string(),
+    v.check((s) => isGdrUri(s), "must be a GDR URI")
+  ),
+  type: v.literal("system.release"),
+  releaseName: v.pipe(v.string(), v.minLength(1))
+}), ActorShape = v.looseObject({
+  kind: v.picklist(["user", "ai", "system"]),
+  id: v.pipe(v.string(), v.minLength(1)),
+  roles: v.optional(v.array(v.string())),
+  onBehalfOf: v.optional(v.string())
+}), AssigneeShape = v.union([
+  v.looseObject({ kind: v.literal("user"), id: v.pipe(v.string(), v.minLength(1)) }),
+  v.looseObject({ kind: v.literal("role"), role: v.pipe(v.string(), v.minLength(1)) })
+]), ChecklistItemShape = v.looseObject({
+  label: v.pipe(v.string(), v.minLength(1)),
+  done: v.boolean(),
+  doneBy: v.optional(v.string()),
+  doneAt: v.optional(v.string()),
+  _key: v.optional(v.pipe(v.string(), v.minLength(1)))
+}), NoteItemShape = v.pipe(
+  v.looseObject({
+    _key: v.optional(v.pipe(v.string(), v.minLength(1)))
+  }),
+  v.check(
+    (val) => typeof val == "object" && val !== null && !Array.isArray(val),
+    "must be an object"
   )
 ), NullableString = v.union([v.null(), v.string()]), NullableNumber = v.union([v.null(), v.number()]), NullableBoolean = v.union([v.null(), v.boolean()]), NullableDateTime = v.union([
   v.null(),
@@ -582,7 +871,12 @@ async function loadContext(client, instanceId, options) {
   const instance = await client.getDocument(instanceId);
   if (!instance)
     throw new Error(`Workflow instance ${instanceId} not found`);
-  const definition = JSON.parse(instance.definitionSnapshot), clientForGdr = options?.clientForGdr ?? (() => client), clock = options?.clock ?? wallClock, snapshot = await hydrateSnapshot({ client, clientForGdr, instance, definition });
+  const definition = JSON.parse(instance.definitionSnapshot), clientForGdr = options?.clientForGdr ?? (() => client), clock = options?.clock ?? wallClock, snapshot = await hydrateSnapshot({
+    client,
+    clientForGdr,
+    instance,
+    ...options?.overlay !== void 0 ? { overlay: options.overlay } : {}
+  });
   return { client, clientForGdr, clock, now: clock(), instance, definition, snapshot };
 }
 function ctxEvaluateFilter(ctx, filter) {
@@ -602,7 +896,7 @@ async function buildEngineContext(args) {
     now: clock(),
     instance,
     definition,
-    snapshot: await hydrateSnapshot({ client, clientForGdr, instance, definition })
+    snapshot: await hydrateSnapshot({ client, clientForGdr, instance })
   };
 }
 function findStage(definition, stageId) {
@@ -651,297 +945,281 @@ async function resolveTaskStateSlots(args) {
     randomKey
   });
 }
-function readStateSlot(instance, scope, slotId, stageId, taskId) {
-  if (scope === "workflow")
-    return slotValue$1(instance.state?.find((s) => s.id === slotId));
-  const stageEntry = instance.stages.find(
-    (s) => s.id === (stageId ?? instance.currentStageId) && s.exitedAt === void 0
-  );
-  if (stageEntry === void 0) return;
-  if (scope === "stage")
-    return slotValue$1(stageEntry.state?.find((s) => s.id === slotId));
-  const taskEntry = stageEntry.tasks.find((t) => t.id === taskId);
-  return slotValue$1(taskEntry?.state?.find((s) => s.id === slotId));
-}
-function slotValue$1(slot) {
-  if (slot != null && typeof slot == "object")
-    return slot.value;
+function effectsContextEntry(id, value) {
+  const _key = randomKey();
+  return typeof value == "string" ? { _key, _type: "effectsContext.string", id, value } : typeof value == "number" ? { _key, _type: "effectsContext.number", id, value } : typeof value == "boolean" ? { _key, _type: "effectsContext.boolean", id, value } : { _key, _type: "effectsContext.ref", id, value };
 }
-function resolveStaticSource(src, ctx) {
-  switch (src.source) {
-    case "literal":
-      return { handled: !0, value: src.value };
-    case "param":
-      return { handled: !0, value: ctx.params?.[src.paramId] };
-    case "actor":
-      return { handled: !0, value: ctx.actor };
-    case "now":
-      return { handled: !0, value: ctx.now };
-    default:
-      return { handled: !1 };
-  }
+function buildInstanceBase(args) {
+  const { id, now, actor, perspective } = args;
+  return {
+    _id: id,
+    _type: WORKFLOW_INSTANCE_TYPE,
+    _rev: "",
+    _createdAt: now,
+    _updatedAt: now,
+    tags: args.tags,
+    workflowResource: args.workflowResource,
+    workflowId: args.workflowId,
+    pinnedVersion: args.pinnedVersion,
+    definitionSnapshot: JSON.stringify(args.definition),
+    state: args.state,
+    effectsContext: args.effectsContext,
+    ancestors: args.ancestors,
+    ...perspective !== void 0 ? { perspective } : {},
+    currentStageId: args.initialStageId,
+    stages: [],
+    pendingEffects: [],
+    effectHistory: [],
+    history: [
+      {
+        _key: randomKey(),
+        _type: "workflow.history.stageEntered",
+        at: now,
+        stageId: args.initialStageId,
+        ...actor !== void 0 ? { actor } : {}
+      }
+    ],
+    startedAt: now,
+    lastChangedAt: now
+  };
 }
-function resolveSource(src, ctx) {
-  const staticValue = resolveStaticSource(src, ctx);
-  if (staticValue.handled) return staticValue.value;
-  switch (src.source) {
-    case "self":
-      return ctx.instance._id;
-    case "stageId":
-      return ctx.stageId ?? ctx.instance.currentStageId;
-    case "stateRead":
-      return resolveStateRead(src, ctx);
-    case "effectOutput":
-      return resolveEffectOutput(src, ctx);
-    case "object":
-      return resolveObject(src, ctx);
-    case "row":
-    case "parentState":
-      return;
-    default:
-      return;
-  }
-}
-function resolveStateRead(src, ctx) {
-  const value = readStateSlot(ctx.instance, src.scope, src.slotId, ctx.stageId, ctx.taskId);
-  return src.path !== void 0 ? getPath(value, src.path) : value;
-}
-function resolveEffectOutput(src, ctx) {
-  const entry = ctx.instance.effectsContext.find((e) => e.id === src.contextId);
-  if (entry === void 0) return null;
-  const value = src.path !== void 0 ? getPath(entry.value, src.path) : entry.value;
-  return value === void 0 ? null : value;
-}
-function resolveObject(src, ctx) {
-  const out = {};
-  for (const [field, fieldSrc] of Object.entries(src.fields))
-    out[field] = resolveSource(fieldSrc, ctx);
-  return out;
-}
-async function resolveBindings(args) {
-  const { bindings, staticInput, instance, now, params, actor } = args, resolved = {};
-  if (bindings) {
-    const ctx = {
-      instance,
-      now,
-      ...params !== void 0 ? { params } : {},
-      ...actor !== void 0 ? { actor } : {}
-    };
-    for (const [key, src] of Object.entries(bindings))
-      resolved[key] = resolveSource(src, ctx);
-  }
-  return { ...resolved, ...staticInput };
-}
-function effectsContextEntry(id, value) {
-  const _key = randomKey();
-  return typeof value == "string" ? { _key, _type: "effectsContext.string", id, value } : typeof value == "number" ? { _key, _type: "effectsContext.number", id, value } : typeof value == "boolean" ? { _key, _type: "effectsContext.boolean", id, value } : { _key, _type: "effectsContext.ref", id, value };
+function startMutation(instance) {
+  return {
+    currentStageId: instance.currentStageId,
+    // Deep-ish copy. Per-scope state slot arrays need their own copies
+    // so ops can mutate without leaking into the source.
+    state: (instance.state ?? []).map((s) => ({ ...s })),
+    stages: instance.stages.map((s) => ({
+      ...s,
+      state: (s.state ?? []).map((slot) => ({ ...slot })),
+      tasks: s.tasks.map((t) => ({
+        ...t,
+        ...t.state !== void 0 ? { state: t.state.map((slot) => ({ ...slot })) } : {}
+      }))
+    })),
+    pendingEffects: [...instance.pendingEffects],
+    effectHistory: [...instance.effectHistory],
+    effectsContext: [...instance.effectsContext],
+    history: [...instance.history],
+    lastChangedAt: instance.lastChangedAt,
+    ...instance.completedAt !== void 0 ? { completedAt: instance.completedAt } : {},
+    pendingCreates: []
+  };
 }
-function buildInstanceBase(args) {
-  const { id, now, actor, perspective } = args;
+function taskStatusChangedEntry(args) {
   return {
-    _id: id,
-    _type: "workflow.instance",
-    _rev: "",
-    _createdAt: now,
-    _updatedAt: now,
-    tags: args.tags,
-    workflowResource: args.workflowResource,
-    workflowId: args.workflowId,
-    pinnedVersion: args.pinnedVersion,
-    definitionSnapshot: JSON.stringify(args.definition),
-    state: args.state,
-    effectsContext: args.effectsContext,
-    ancestors: args.ancestors,
-    ...perspective !== void 0 ? { perspective } : {},
-    currentStageId: args.initialStageId,
-    stages: [],
-    pendingEffects: [],
-    effectHistory: [],
-    history: [
-      {
-        _key: randomKey(),
-        _type: "workflow.history.stageEntered",
-        at: now,
-        stageId: args.initialStageId,
-        ...actor !== void 0 ? { actor } : {}
-      }
-    ],
-    startedAt: now,
-    lastChangedAt: now
+    _key: randomKey(),
+    _type: "workflow.history.taskStatusChanged",
+    at: args.at,
+    stageId: args.stageId,
+    taskId: args.taskId,
+    from: args.from,
+    to: args.to,
+    ...args.actor !== void 0 ? { actor: args.actor } : {}
   };
 }
-const GUARD_DOC_TYPE = "temp.system.guard";
-class MutationGuardDeniedError extends Error {
-  denied;
-  documentId;
-  action;
-  constructor(args) {
-    const ids = args.denied.map((d) => d.guardId).join(", ");
-    super(`Mutation on "${args.documentId}" (${args.action}) denied by guard(s) [${ids}]`), this.name = "MutationGuardDeniedError", this.denied = args.denied, this.documentId = args.documentId, this.action = args.action;
-  }
+function stageTransitionHistory(args) {
+  const { fromStageId, toStageId, at, transitionId, actor, via, reason } = args, shared = {
+    at,
+    ...transitionId !== void 0 ? { transitionId } : {},
+    ...actor !== void 0 ? { actor } : {},
+    ...via !== void 0 ? { via } : {},
+    ...reason !== void 0 ? { reason } : {}
+  };
+  return [
+    {
+      _key: randomKey(),
+      _type: "workflow.history.stageExited",
+      stageId: fromStageId,
+      toStageId,
+      ...shared
+    },
+    {
+      _key: randomKey(),
+      _type: "workflow.history.transitionFired",
+      fromStageId,
+      toStageId,
+      ...shared
+    },
+    {
+      _key: randomKey(),
+      _type: "workflow.history.stageEntered",
+      stageId: toStageId,
+      fromStageId,
+      ...shared
+    }
+  ];
 }
-function lakeGuardId(args) {
-  return `${GUARD_DOC_TYPE}.${args.instanceDocId}.${args.stageId}.${args.index}`;
+function instanceStateFields(src) {
+  const fields = {
+    currentStageId: src.currentStageId,
+    state: src.state,
+    stages: src.stages,
+    pendingEffects: src.pendingEffects,
+    effectHistory: src.effectHistory,
+    effectsContext: src.effectsContext,
+    history: src.history
+  };
+  return src.completedAt !== void 0 && (fields.completedAt = src.completedAt), fields;
 }
-function compileGuard(args) {
+function materializeInstance(base, mutation) {
   return {
-    _id: args.id,
-    _type: GUARD_DOC_TYPE,
-    resourceType: args.resourceType,
-    resourceId: args.resourceId,
-    owner: args.owner,
-    sourceInstanceId: args.sourceInstanceId,
-    sourceDefinitionId: args.sourceDefinitionId,
-    sourceStageId: args.sourceStageId,
-    ...args.name !== void 0 ? { name: args.name } : {},
-    ...args.description !== void 0 ? { description: args.description } : {},
-    match: args.match,
-    predicate: args.predicate,
-    metadata: args.metadata
+    ...base,
+    currentStageId: mutation.currentStageId,
+    state: mutation.state,
+    stages: mutation.stages
   };
 }
-function toGroqJsPredicate(predicate) {
-  return predicate.replace(new RegExp("(?<!\\$)\\bguard\\.", "g"), "$guard.").replace(new RegExp("(?<!\\$)\\bmutation\\.", "g"), "$mutation.");
+async function persist(ctx, mutation) {
+  const set = {
+    ...instanceStateFields(mutation),
+    lastChangedAt: ctx.now
+  }, pendingCreates = mutation.pendingCreates;
+  if (pendingCreates.length === 0)
+    return ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev).commit();
+  const tx = ctx.client.transaction();
+  for (const body of pendingCreates) tx.create(body);
+  tx.patch(ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev)), await tx.commit(), mutation.pendingCreates = [];
+  const actorForPriming = void 0;
+  for (const body of pendingCreates)
+    await primeInitialStage(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await cascadeAutoTransitions(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await propagateToAncestors(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock);
+  const reloaded = await ctx.client.getDocument(ctx.instance._id);
+  if (!reloaded)
+    throw new Error(`Instance ${ctx.instance._id} disappeared after transaction commit`);
+  return reloaded;
 }
-function globMatch(pattern, value) {
-  if (!pattern.includes("*")) return pattern === value;
-  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
-  return new RegExp(`^${escaped}$`).test(value);
+function currentStageEntry(mutation) {
+  const entry = findOpenStageEntry(mutation);
+  if (entry === void 0)
+    throw new Error(
+      `Mutation invariant broken: no current (un-exited) StageEntry for currentStageId "${mutation.currentStageId}"`
+    );
+  return entry;
 }
-function guardMatches(guard, doc, action) {
-  const m = guard.match;
-  if (!m.actions.includes(action) || m.types && m.types.length > 0 && !(doc.type !== void 0 && m.types.includes(doc.type)))
-    return !1;
-  if (m.idRefs && m.idRefs.length > 0 || m.idPatterns && m.idPatterns.length > 0) {
-    const byRef = m.idRefs?.includes(doc.id) ?? !1, byPattern = m.idPatterns?.some((p) => globMatch(p, doc.id)) ?? !1;
-    if (!byRef && !byPattern) return !1;
-  }
-  return !0;
+function currentTasks(mutation) {
+  return currentStageEntry(mutation).tasks;
 }
-async function evaluateMutationGuard(args) {
-  const { guard, context } = args;
-  if (guard.predicate === "") return !1;
-  const params = { guard, mutation: { action: context.action } };
-  try {
-    const tree = parse(toGroqJsPredicate(guard.predicate), { mode: "delta", params });
-    return await (await evaluate(tree, {
-      before: context.before,
-      after: context.after,
-      params,
-      ...context.identity !== void 0 ? { identity: context.identity } : {}
-    })).get() === !0;
-  } catch {
-    return !1;
-  }
+function findTaskInCurrentStage(ctx, taskId) {
+  const stage = findStage(ctx.definition, ctx.instance.currentStageId), task = (stage.tasks ?? []).find((t) => t.id === taskId);
+  if (task === void 0)
+    throw new Error(
+      `Task "${taskId}" not found in current stage "${stage.id}" of ${ctx.definition.workflowId}`
+    );
+  return { stage, task };
 }
-async function denyingGuards(args) {
-  const { guards, doc, context } = args, denied = [];
-  for (const guard of guards)
-    guardMatches(guard, doc, context.action) && (await evaluateMutationGuard({ guard, context }) || denied.push(guard));
-  return denied;
+function requireMutationTaskEntry(mutation, taskId) {
+  const mutEntry = currentTasks(mutation).find((t) => t.id === taskId);
+  if (mutEntry === void 0)
+    throw new Error(`Task "${taskId}" disappeared from mutation copy \u2014 invariant broken`);
+  return mutEntry;
 }
-function resourceOf(p) {
-  return p.scheme === "dataset" ? { type: "dataset", id: `${p.projectId}.${p.dataset}` } : { type: p.scheme, id: p.resourceId ?? "" };
+function findCurrentStageEntry(instance) {
+  return findOpenStageEntry(instance);
 }
-function resolveIdRefTarget(src, ctx) {
-  const value = resolveSource(src, ctx);
-  if (typeof value == "string" && isGdrUri(value))
-    return { parsed: parseGdr(value) };
-  if (value && typeof value == "object") {
-    const v2 = value;
-    if (typeof v2.id == "string" && isGdrUri(v2.id))
-      return typeof v2.type == "string" ? { parsed: parseGdr(v2.id), type: v2.type } : { parsed: parseGdr(v2.id) };
-  }
-  return null;
-}
-function resolveIdRefTargets(idRefs, ctx) {
-  const targets = [];
-  for (const src of idRefs ?? []) {
-    const target = resolveIdRefTarget(src, ctx);
-    if (target === null) return null;
-    targets.push(target);
-  }
-  return targets.length === 0 ? null : targets;
-}
-function assertSingleResource(targets) {
-  const resource = resourceOf(targets[0].parsed);
-  for (const g of targets) {
-    const r = resourceOf(g.parsed);
-    if (r.type !== resource.type || r.id !== resource.id)
-      throw new Error(
-        `Guard targets span multiple resources (${resource.type}:${resource.id} vs ${r.type}:${r.id}); a guard is single-resource.`
-      );
-  }
-  return resource;
-}
-function bareIdRefs(targets) {
-  return targets.flatMap((g) => [g.parsed.documentId, `drafts.${g.parsed.documentId}`]);
-}
-function resolveMatchTypes(targets, authorTypes) {
-  if (authorTypes !== void 0) return authorTypes;
-  const inferred = [...new Set(targets.map((g) => g.type).filter((t) => !!t))];
-  return inferred.length > 0 ? inferred : void 0;
-}
-function resolveMetadata(metadata, ctx) {
-  const out = {};
-  for (const [k, src] of Object.entries(metadata ?? {}))
-    out[k] = resolveSource(src, ctx);
-  return out;
+function findCurrentTasks(instance) {
+  return findCurrentStageEntry(instance)?.tasks ?? [];
 }
-const GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
-function resolveGuard(guard, index, instance, stageId, now) {
-  const ctx = { instance, stageId, now }, targets = resolveIdRefTargets(guard.match.idRefs, ctx);
-  if (targets === null) return null;
-  const resource = assertSingleResource(targets), types = resolveMatchTypes(targets, guard.match.types);
-  return { doc: compileGuard({
-    id: lakeGuardId({ instanceDocId: instance._id, stageId, index }),
-    resourceType: resource.type,
-    resourceId: resource.id,
-    owner: GUARD_OWNER,
-    sourceInstanceId: instance._id,
-    sourceDefinitionId: instance.workflowId,
-    sourceStageId: stageId,
-    ...guard.name !== void 0 ? { name: guard.name } : {},
-    ...guard.description !== void 0 ? { description: guard.description } : {},
-    match: {
-      ...types !== void 0 ? { types } : {},
-      idRefs: bareIdRefs(targets),
-      ...guard.match.idPatterns !== void 0 ? { idPatterns: guard.match.idPatterns } : {},
-      actions: guard.match.actions
-    },
-    predicate: guard.predicate ?? "",
-    metadata: resolveMetadata(guard.metadata, ctx)
-  }), routeGdr: targets[0].parsed };
+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 } : {}
+  });
+  return commitCompleteEffect(
+    ctx,
+    effectKey,
+    status,
+    outputs,
+    detail,
+    error,
+    durationMs,
+    options?.actor
+  );
 }
-async function upsertGuard(client, doc) {
-  if (!await client.getDocument(doc._id)) {
-    await client.create(doc);
-    return;
-  }
-  const { _id, _type, _rev, _createdAt, _updatedAt, ...body } = doc;
-  await client.patch(doc._id).set(body).commit();
+function buildEffectHistoryEntry(pending, outcome) {
+  const { status, ranAt, actor, detail, error, durationMs, outputs } = outcome, resolvedActor = actor ?? pending.actor;
+  return {
+    _key: pending._key,
+    effectId: pending.effectId,
+    ...pending.title !== void 0 ? { title: pending.title } : {},
+    ...pending.description !== void 0 ? { description: pending.description } : {},
+    params: pending.params,
+    origin: pending.origin,
+    ...resolvedActor !== void 0 ? { actor: resolvedActor } : {},
+    ranAt,
+    ...durationMs !== void 0 ? { durationMs } : {},
+    status,
+    ...detail !== void 0 ? { detail } : {},
+    ...error !== void 0 ? { error } : {},
+    ...outputs !== void 0 ? { outputs } : {}
+  };
 }
-function resolvedStageGuards(args) {
-  const stage = args.definition.stages.find((s) => s.id === args.stageId), out = [];
-  for (const [index, guard] of (stage?.guards ?? []).entries()) {
-    const resolved = resolveGuard(guard, index, args.instance, args.stageId, args.now);
-    resolved !== null && out.push({ client: args.clientForGdr(resolved.routeGdr), doc: resolved.doc });
+function upsertEffectsContext(mutation, outputs) {
+  for (const [id, value] of Object.entries(outputs)) {
+    const existingIndex = mutation.effectsContext.findIndex((e) => e.id === id), entry = effectsContextEntry(id, value);
+    existingIndex >= 0 ? mutation.effectsContext[existingIndex] = entry : mutation.effectsContext.push(entry);
   }
-  return out;
 }
-async function committedStageId(args) {
-  return (await args.client.getDocument(args.instance._id))?.currentStageId;
+async function commitCompleteEffect(ctx, effectKey, status, outputs, detail, error, durationMs, actor) {
+  const pending = ctx.instance.pendingEffects.find((e) => e._key === effectKey);
+  if (pending === void 0)
+    throw new Error(`Pending effect "${effectKey}" not found on instance ${ctx.instance._id}`);
+  const mutation = startMutation(ctx.instance);
+  mutation.pendingEffects = mutation.pendingEffects.filter((e) => e._key !== effectKey);
+  const ranAt = ctx.now;
+  return mutation.effectHistory.push(
+    buildEffectHistoryEntry(pending, { status, ranAt, actor, detail, error, durationMs, outputs })
+  ), status === "done" && outputs !== void 0 && upsertEffectsContext(mutation, outputs), mutation.history.push({
+    _key: randomKey(),
+    _type: "workflow.history.effectCompleted",
+    at: ranAt,
+    effectKey,
+    effectId: pending.effectId,
+    status,
+    ...outputs !== void 0 ? { outputs } : {},
+    ...detail !== void 0 ? { detail } : {},
+    ...actor !== void 0 ? { actor } : {}
+  }), await persist(ctx, mutation), { effectKey, status };
 }
-async function deployStageGuards(args) {
-  if (await committedStageId(args) === args.stageId)
-    for (const { client, doc } of resolvedStageGuards(args))
-      await upsertGuard(client, doc);
+function buildQueuedEffect(effect, origin, params, actor, now) {
+  const key = randomKey(), pending = {
+    _key: key,
+    _type: "workflow.pendingEffect",
+    effectId: effect.id,
+    ...effect.title !== void 0 ? { title: effect.title } : {},
+    ...effect.description !== void 0 ? { description: effect.description } : {},
+    ...effect.bindings !== void 0 ? { bindings: effect.bindings } : {},
+    params,
+    origin,
+    ...actor !== void 0 ? { actor } : {},
+    queuedAt: now
+  }, history = {
+    _key: randomKey(),
+    _type: "workflow.history.effectQueued",
+    at: now,
+    effectKey: key,
+    effectId: effect.id,
+    origin
+  };
+  return { pending, history };
 }
-async function retractStageGuards(args) {
-  const live = await committedStageId(args);
-  if (!(live === void 0 || live === args.stageId))
-    for (const { client, doc } of resolvedStageGuards(args))
-      await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit();
+async function queueEffects(ctx, mutation, effects, origin, actor, callerParams) {
+  if (!effects) return;
+  const now = ctx.now, liveInstance = {
+    ...ctx.instance,
+    state: mutation.state,
+    stages: mutation.stages,
+    effectsContext: mutation.effectsContext
+  };
+  for (const effect of effects) {
+    const params = await resolveBindings({
+      bindings: effect.bindings,
+      staticInput: effect.input,
+      instance: liveInstance,
+      now,
+      ...callerParams !== void 0 ? { params: callerParams } : {},
+      ...actor !== void 0 ? { actor } : {}
+    }), { pending, history } = buildQueuedEffect(effect, origin, params, actor, now);
+    mutation.pendingEffects.push(pending), mutation.history.push(history);
+  }
 }
 class ActionParamsInvalidError extends Error {
   action;
@@ -1017,6 +1295,26 @@ async function deployOrRollback(args) {
     throw guardError;
   }
 }
+const TAG_RE = /^[a-z0-9][a-z0-9-]*$/;
+function validateTags(tags) {
+  if (tags.length === 0)
+    throw new Error("tags: must be a non-empty array");
+  for (const tag of tags)
+    if (!TAG_RE.test(tag))
+      throw new Error(
+        `tags: invalid tag "${tag}" \u2014 must match ${TAG_RE.source} (ASCII lowercase + digits + dashes, no leading dash, no dots)`
+      );
+}
+function canonicalTag(tags) {
+  return tags[0];
+}
+function tagScopeFilter(param = "engineTags") {
+  return `count(tags[@ in $${param}]) > 0`;
+}
+function definitionLookupGroq(explicit) {
+  const scoped = `_type == "${WORKFLOW_DEFINITION_TYPE}" && workflowId == $workflowId && ${tagScopeFilter()}`;
+  return explicit ? `*[${scoped} && version == $version][0]` : `*[${scoped}] | order(version desc)[0]`;
+}
 async function discoverItems(args) {
   const { client, groq, params, perspective } = args, fetchOptions = perspective !== void 0 ? { perspective } : void 0;
   return client.fetch(groq, paramsForLake(params), fetchOptions);
@@ -1140,10 +1438,11 @@ function coerceSpawnGdr(raw, workflowResource) {
   return typeof raw == "string" && raw.length > 0 ? { id: toUri(raw), type: "document" } : null;
 }
 async function resolveLogicalDefinition(client, ref, tags) {
-  const wantsExplicit = typeof ref.version == "number", params = { workflowId: ref.workflowId, tags };
-  wantsExplicit && (params.version = ref.version);
-  const groq = wantsExplicit ? '*[_type == "workflow.definition" && workflowId == $workflowId && version == $version && count(tags[@ in $tags]) > 0][0]' : '*[_type == "workflow.definition" && workflowId == $workflowId && count(tags[@ in $tags]) > 0] | order(version desc)[0]';
-  return await client.fetch(groq, params) ?? null;
+  const wantsExplicit = typeof ref.version == "number", params = { workflowId: ref.workflowId, engineTags: tags };
+  return wantsExplicit && (params.version = ref.version), await client.fetch(
+    definitionLookupGroq(wantsExplicit),
+    params
+  ) ?? null;
 }
 async function prepareChildInstance(args) {
   const { client, parent, task, spawn, initialState, effectsContext, actor, now } = args, definition = await resolveLogicalDefinition(client, spawn.definitionRef, parent.tags ?? []);
@@ -1153,11 +1452,11 @@ async function prepareChildInstance(args) {
       `Spawn target workflowId="${spawn.definitionRef.workflowId}" ${versionLabel} not deployed (parent ${parent._id}, task ${task.id})`
     );
   }
-  const childTags = parent.tags ?? [], childPrefix = childTags[0] ?? "wf", workflowResource = parent.workflowResource, childDocId = `${childPrefix}.wf-instance.${randomKey()}`, childRef = { id: gdrFromResource(workflowResource, childDocId), type: "workflow.instance" }, ancestors = [
+  const childTags = parent.tags ?? [], childPrefix = childTags[0] ?? "wf", workflowResource = parent.workflowResource, childDocId = `${childPrefix}.wf-instance.${randomKey()}`, childRef = { id: gdrFromResource(workflowResource, childDocId), type: WORKFLOW_INSTANCE_TYPE }, ancestors = [
     ...parent.ancestors,
     {
       id: selfGdr(parent),
-      type: "workflow.instance"
+      type: WORKFLOW_INSTANCE_TYPE
     }
   ], inheritedPerspective = parent.perspective, childState = await resolveDeclaredState({
     slotDefs: definition.state,
@@ -1478,9 +1777,10 @@ async function pickTransition(ctx, stage, action) {
     if (await ctxEvaluateFilter(ctx, candidate.filter)) return candidate;
 }
 async function evaluateAutoTransitions(args) {
-  const { client, instanceId, options, clientForGdr, clock } = args, ctx = await loadContext(client, instanceId, {
+  const { client, instanceId, options, clientForGdr, clock, overlay } = args, ctx = await loadContext(client, instanceId, {
     ...clientForGdr ? { clientForGdr } : {},
-    ...clock ? { clock } : {}
+    ...clock ? { clock } : {},
+    ...overlay ? { overlay } : {}
   });
   return commitTransition(ctx, void 0, options?.actor);
 }
@@ -1492,8 +1792,7 @@ async function primeInitialStage(client, instanceId, actor, clientForGdr, clock)
   const now = (clock ?? wallClock)(), snapshot = await hydrateSnapshot({
     client,
     clientForGdr: clientForGdr ?? (() => client),
-    instance,
-    definition
+    instance
   }), tasks = [];
   for (const task of stage.tasks ?? []) {
     const inScope = await evaluateFilter({
@@ -1586,10 +1885,11 @@ async function gatherAutoResolveCandidates(ctx, tasks) {
     }
   return candidates;
 }
-async function resolveCompleteWhen(client, instanceId, clientForGdr, clock) {
+async function resolveCompleteWhen(client, instanceId, clientForGdr, clock, overlay) {
   const ctx = await loadContext(client, instanceId, {
     ...clientForGdr ? { clientForGdr } : {},
-    ...clock ? { clock } : {}
+    ...clock ? { clock } : {},
+    ...overlay ? { overlay } : {}
   }), stage = findStage(ctx.definition, ctx.instance.currentStageId), tasksWithAutoPredicate = (stage.tasks ?? []).filter(
     (t) => t.completeWhen !== void 0 || t.failWhen !== void 0
   );
@@ -1618,15 +1918,16 @@ async function resolveCompleteWhen(client, instanceId, clientForGdr, clock) {
   }
   return count > 0 && await persist(ctx, mutation), count;
 }
-async function cascadeAutoTransitions(client, instanceId, actor, clientForGdr, clock) {
+async function cascadeAutoTransitions(client, instanceId, actor, clientForGdr, clock, overlay) {
   let count = 0;
   for (; ; ) {
-    if (await resolveCompleteWhen(client, instanceId, clientForGdr, clock), !(await evaluateAutoTransitions({
+    if (await resolveCompleteWhen(client, instanceId, clientForGdr, clock, overlay), !(await evaluateAutoTransitions({
       client,
       instanceId,
       ...actor !== void 0 ? { options: { actor } } : {},
       ...clientForGdr ? { clientForGdr } : {},
-      ...clock ? { clock } : {}
+      ...clock ? { clock } : {},
+      ...overlay ? { overlay } : {}
     })).fired) return count;
     if (count++, count >= CASCADE_LIMIT)
       throw new CascadeLimitError({ instanceId, limit: CASCADE_LIMIT });
@@ -1636,7 +1937,7 @@ async function findSatisfiedParentSpawn(client, child) {
   const parentRef = child.ancestors.at(-1);
   if (parentRef === void 0) return;
   const parent = await client.getDocument(gdrToBareId(parentRef.id));
-  if (!parent || parent._type !== "workflow.instance" || typeof parent.definitionSnapshot != "string") return;
+  if (!parent || parent._type !== WORKFLOW_INSTANCE_TYPE || typeof parent.definitionSnapshot != "string") return;
   const definition = JSON.parse(parent.definitionSnapshot), stage = definition.stages.find((s) => s.id === parent.currentStageId);
   if (stage === void 0) return;
   const parentCurrentTasks = findCurrentTasks(parent), task = (stage.tasks ?? []).find((t) => t.spawns === void 0 ? !1 : parentCurrentTasks.find((e) => e.id === t.id)?.spawnedInstances?.some((r) => gdrToBareId(r.id) === child._id) ?? !1);
@@ -1670,361 +1971,519 @@ async function propagateToAncestors(client, instanceId, actor, clientForGdr, clo
     })
   ), await persist(ctx, mutation), await cascadeAutoTransitions(client, parent._id, actor, clientForGdr, clock), await propagateToAncestors(client, parent._id, actor, clientForGdr, clock);
 }
-function startMutation(instance) {
-  return {
-    currentStageId: instance.currentStageId,
-    // Deep-ish copy. Per-scope state slot arrays need their own copies
-    // so ops can mutate without leaking into the source.
-    state: (instance.state ?? []).map((s) => ({ ...s })),
-    stages: instance.stages.map((s) => ({
-      ...s,
-      state: (s.state ?? []).map((slot) => ({ ...slot })),
-      tasks: s.tasks.map((t) => ({
-        ...t,
-        ...t.state !== void 0 ? { state: t.state.map((slot) => ({ ...slot })) } : {}
-      }))
-    })),
-    pendingEffects: [...instance.pendingEffects],
-    effectHistory: [...instance.effectHistory],
-    effectsContext: [...instance.effectsContext],
-    history: [...instance.history],
-    lastChangedAt: instance.lastChangedAt,
-    ...instance.completedAt !== void 0 ? { completedAt: instance.completedAt } : {},
-    pendingCreates: []
-  };
-}
-function taskStatusChangedEntry(args) {
-  return {
-    _key: randomKey(),
-    _type: "workflow.history.taskStatusChanged",
-    at: args.at,
-    stageId: args.stageId,
-    taskId: args.taskId,
-    from: args.from,
-    to: args.to,
-    ...args.actor !== void 0 ? { actor: args.actor } : {}
-  };
+const parsedFilters = /* @__PURE__ */ new Map();
+async function matchesFilter(args) {
+  const { document, filter, userId } = args;
+  parsedFilters.has(filter) || parsedFilters.set(filter, parse(`*[${filter}]`));
+  const ast = parsedFilters.get(filter), data = await (await evaluate(ast, {
+    dataset: [document],
+    ...userId !== void 0 ? { identity: userId } : {}
+  })).get();
+  return Array.isArray(data) && data.length === 1;
 }
-function stageTransitionHistory(args) {
-  const { fromStageId, toStageId, at, transitionId, actor, via, reason } = args, shared = {
-    at,
-    ...transitionId !== void 0 ? { transitionId } : {},
-    ...actor !== void 0 ? { actor } : {},
-    ...via !== void 0 ? { via } : {},
-    ...reason !== void 0 ? { reason } : {}
-  };
-  return [
-    {
-      _key: randomKey(),
-      _type: "workflow.history.stageExited",
-      stageId: fromStageId,
-      toStageId,
-      ...shared
-    },
-    {
-      _key: randomKey(),
-      _type: "workflow.history.transitionFired",
-      fromStageId,
-      toStageId,
-      ...shared
-    },
-    {
-      _key: randomKey(),
-      _type: "workflow.history.stageEntered",
-      stageId: toStageId,
-      fromStageId,
-      ...shared
-    }
-  ];
-}
-function instanceStateFields(src) {
-  const fields = {
-    currentStageId: src.currentStageId,
-    state: src.state,
-    stages: src.stages,
-    pendingEffects: src.pendingEffects,
-    effectHistory: src.effectHistory,
-    effectsContext: src.effectsContext,
-    history: src.history
-  };
-  return src.completedAt !== void 0 && (fields.completedAt = src.completedAt), fields;
-}
-function materializeInstance(base, mutation) {
-  return {
-    ...base,
-    currentStageId: mutation.currentStageId,
-    state: mutation.state,
-    stages: mutation.stages
-  };
-}
-async function persist(ctx, mutation) {
-  const set = {
-    ...instanceStateFields(mutation),
-    lastChangedAt: ctx.now
-  }, pendingCreates = mutation.pendingCreates;
-  if (pendingCreates.length === 0)
-    return ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev).commit();
-  const tx = ctx.client.transaction();
-  for (const body of pendingCreates) tx.create(body);
-  tx.patch(ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev)), await tx.commit(), mutation.pendingCreates = [];
-  const actorForPriming = void 0;
-  for (const body of pendingCreates)
-    await primeInitialStage(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await cascadeAutoTransitions(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await propagateToAncestors(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock);
-  const reloaded = await ctx.client.getDocument(ctx.instance._id);
-  if (!reloaded)
-    throw new Error(`Instance ${ctx.instance._id} disappeared after transaction commit`);
-  return reloaded;
+async function grantsPermissionOn(args) {
+  const { document, grants, permission, userId } = args;
+  if (!document || grants.length === 0) return !1;
+  for (const grant of grants)
+    if (grant.permissions.includes(permission) && await matchesFilter({
+      document,
+      filter: grant.filter,
+      ...userId !== void 0 ? { userId } : {}
+    }))
+      return !0;
+  return !1;
 }
-function findOpenStageEntry(host) {
-  return host.stages.find((s) => s.id === host.currentStageId && s.exitedAt === void 0);
+async function fetchGrants(args) {
+  const { client, resourcePath, signal } = args;
+  return client.request({ url: resourcePath, ...signal ? { signal } : {} });
 }
-function currentStageEntry(mutation) {
-  const entry = findOpenStageEntry(mutation);
-  if (entry === void 0)
+const actorCache = /* @__PURE__ */ new WeakMap(), grantsCache = /* @__PURE__ */ new WeakMap();
+async function resolveAccess(client, args = {}) {
+  const overrideActor = args.override?.actor, overrideGrants = args.override?.grants;
+  if (overrideActor !== void 0 && overrideGrants !== void 0)
+    return { actor: overrideActor, grants: overrideGrants };
+  const requestFn = client.request === void 0 ? void 0 : (opts) => client.request(opts);
+  if (requestFn === void 0) {
+    if (overrideActor === void 0)
+      throw new Error(
+        "workflow: no actor available. The engine resolves the actor from the client's token via `client.request({ url: '/users/me' })`. Supply a real `@sanity/client` configured with a token, or pass an explicit `access.actor` override (the test bench provides one by default)."
+      );
+    return { actor: overrideActor };
+  }
+  const actorPromise = overrideActor !== void 0 ? Promise.resolve(overrideActor) : cachedActor(client, requestFn), grantsPromise = resolveGrants(overrideGrants, args.grantsFromPath, client, requestFn), [actor, grants] = await Promise.all([actorPromise, grantsPromise]);
+  if (actor === void 0)
     throw new Error(
-      `Mutation invariant broken: no current (un-exited) StageEntry for currentStageId "${mutation.currentStageId}"`
+      "workflow: failed to resolve actor from `/users/me`. The client is configured but the endpoint returned no usable identity \u2014 check the token, or pass `access.actor` explicitly."
     );
-  return entry;
+  return { actor, ...grants !== void 0 ? { grants } : {} };
 }
-function currentTasks(mutation) {
-  return currentStageEntry(mutation).tasks;
+function cachedActor(client, requestFn) {
+  const cached = actorCache.get(client);
+  if (cached !== void 0) return cached;
+  const pending = fetchActor(requestFn).catch((err) => {
+    throw actorCache.get(client) === pending && actorCache.delete(client), err;
+  });
+  return actorCache.set(client, pending), pending;
 }
-function findTaskInCurrentStage(ctx, taskId) {
-  const stage = findStage(ctx.definition, ctx.instance.currentStageId), task = (stage.tasks ?? []).find((t) => t.id === taskId);
-  if (task === void 0)
-    throw new Error(
-      `Task "${taskId}" not found in current stage "${stage.id}" of ${ctx.definition.workflowId}`
-    );
-  return { stage, task };
+function resolveGrants(overrideGrants, grantsFromPath, client, requestFn) {
+  return overrideGrants !== void 0 ? Promise.resolve(overrideGrants) : grantsFromPath !== void 0 ? cachedGrants(client, requestFn, grantsFromPath) : Promise.resolve(void 0);
 }
-function requireMutationTaskEntry(mutation, taskId) {
-  const mutEntry = currentTasks(mutation).find((t) => t.id === taskId);
-  if (mutEntry === void 0)
-    throw new Error(`Task "${taskId}" disappeared from mutation copy \u2014 invariant broken`);
-  return mutEntry;
+function cachedGrants(client, requestFn, resourcePath) {
+  let byPath = grantsCache.get(client);
+  byPath === void 0 && (byPath = /* @__PURE__ */ new Map(), grantsCache.set(client, byPath));
+  let cached = byPath.get(resourcePath);
+  return cached === void 0 && (cached = fetchGrantsCached(requestFn, resourcePath), byPath.set(resourcePath, cached)), cached;
 }
-function findCurrentStageEntry(instance) {
-  return findOpenStageEntry(instance);
+async function fetchActor(requestFn) {
+  let user;
+  try {
+    user = await requestFn({
+      uri: "/users/me",
+      tag: "workflow.access.resolve-actor"
+    });
+  } catch (err) {
+    throw new Error(
+      'workflow: /users/me request failed. The engine resolves the actor from the client\'s token via `client.request({ uri: "/users/me" })`. Check the token/connectivity, or pass an explicit `access.actor` override.',
+      { cause: err }
+    );
+  }
+  if (!user || typeof user.id != "string" || user.id.length === 0) return;
+  const roleNames = user.roles?.map((r) => r.name).filter((n) => !!n) ?? [];
+  return {
+    kind: "user",
+    id: user.id,
+    ...roleNames.length > 0 ? { roles: roleNames } : {}
+  };
 }
-function findCurrentTasks(instance) {
-  return findCurrentStageEntry(instance)?.tasks ?? [];
+async function fetchGrantsCached(requestFn, resourcePath) {
+  try {
+    return await fetchGrants({ client: { request: requestFn }, resourcePath });
+  } catch (err) {
+    console.warn(
+      `workflow: failed to fetch grants from "${resourcePath}"; skipping permission gate. Original error: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return;
+  }
 }
-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 } : {}
+const WILDCARD_ROLE = "*";
+async function evaluateInstance(args) {
+  const { client, tags, instanceId, resourceClients } = args, now = (args.clock ?? wallClock)();
+  validateTags(tags);
+  const { actor, grants } = await resolveAccess(client, {
+    ...args.access !== void 0 ? { override: args.access } : {},
+    ...args.grantsFromPath !== void 0 ? { grantsFromPath: args.grantsFromPath } : {}
+  }), instance = await client.getDocument(instanceId);
+  if (!instance)
+    throw new Error(`Workflow instance "${instanceId}" not found`);
+  if (!tags.some((t) => instance.tags?.includes(t)))
+    throw new Error(`Workflow instance "${instanceId}" not visible to this engine (tag mismatch)`);
+  const definition = parseDefinitionSnapshot(instance), snapshot = await hydrateSnapshot({ client, clientForGdr: resourceClients !== void 0 ? (parsed) => resourceClients(parsed) ?? client : () => client, instance });
+  return evaluateFromSnapshot({
+    instance,
+    definition,
+    actor,
+    snapshot,
+    now,
+    ...grants !== void 0 ? { grants } : {}
   });
-  return commitCompleteEffect(
-    ctx,
-    effectKey,
-    status,
-    outputs,
-    detail,
-    error,
-    durationMs,
-    options?.actor
-  );
 }
-function buildEffectHistoryEntry(pending, outcome) {
-  const { status, ranAt, actor, detail, error, durationMs, outputs } = outcome;
+async function evaluateFromSnapshot(args) {
+  const { instance, definition, actor, grants, snapshot } = args, now = args.now ?? wallClock(), stage = definition.stages.find((s) => s.id === instance.currentStageId);
+  if (stage === void 0)
+    throw new Error(
+      `Instance "${instance._id}" currentStageId "${instance.currentStageId}" not in definition`
+    );
+  const currentTaskEntries = findOpenStageEntry(instance)?.tasks ?? [], taskEvaluations = [];
+  for (const task of stage.tasks ?? [])
+    taskEvaluations.push(
+      await evaluateTask({
+        task,
+        statusEntry: currentTaskEntries.find((t) => t.id === task.id),
+        instance,
+        definition,
+        actor,
+        grants,
+        snapshot,
+        now
+      })
+    );
+  const transitionEvaluations = [];
+  for (const transition of stage.transitions ?? [])
+    transitionEvaluations.push({
+      transition,
+      filterSatisfied: await evaluateFilter({
+        filter: transition.filter,
+        definition,
+        snapshot,
+        params: buildParams(instance, now)
+      })
+    });
+  const currentStage = {
+    stage,
+    tasks: taskEvaluations,
+    transitions: transitionEvaluations
+  }, pendingOnYou = taskEvaluations.filter((t) => t.pendingOnActor), canInteract = taskEvaluations.some((t) => t.actions.some((a) => a.allowed));
   return {
-    _key: pending._key,
-    effectId: pending.effectId,
-    ...pending.title !== void 0 ? { title: pending.title } : {},
-    ...pending.description !== void 0 ? { description: pending.description } : {},
-    params: pending.params,
-    origin: pending.origin,
-    ...actor !== void 0 ? { actor } : pending.actor !== void 0 ? { actor: pending.actor } : {},
-    ranAt,
-    ...durationMs !== void 0 ? { durationMs } : {},
-    status,
-    ...detail !== void 0 ? { detail } : {},
-    ...error !== void 0 ? { error } : {},
-    ...outputs !== void 0 ? { outputs } : {}
+    instance,
+    definition,
+    actor,
+    currentStage,
+    pendingOnYou,
+    canInteract
   };
 }
-function upsertEffectsContext(mutation, outputs) {
-  for (const [id, value] of Object.entries(outputs)) {
-    const existingIndex = mutation.effectsContext.findIndex((e) => e.id === id), entry = effectsContextEntry(id, value);
-    existingIndex >= 0 ? mutation.effectsContext[existingIndex] = entry : mutation.effectsContext.push(entry);
-  }
-}
-async function commitCompleteEffect(ctx, effectKey, status, outputs, detail, error, durationMs, actor) {
-  const pending = ctx.instance.pendingEffects.find((e) => e._key === effectKey);
-  if (pending === void 0)
-    throw new Error(`Pending effect "${effectKey}" not found on instance ${ctx.instance._id}`);
-  const mutation = startMutation(ctx.instance);
-  mutation.pendingEffects = mutation.pendingEffects.filter((e) => e._key !== effectKey);
-  const ranAt = ctx.now;
-  return mutation.effectHistory.push(
-    buildEffectHistoryEntry(pending, { status, ranAt, actor, detail, error, durationMs, outputs })
-  ), status === "done" && outputs !== void 0 && upsertEffectsContext(mutation, outputs), mutation.history.push({
-    _key: randomKey(),
-    _type: "workflow.history.effectCompleted",
-    at: ranAt,
-    effectKey,
-    effectId: pending.effectId,
+async function evaluateTask(args) {
+  const { task, statusEntry, instance, definition, actor, grants, snapshot, now } = args, status = statusEntry?.status ?? "pending", actions = [];
+  for (const action of task.actions ?? [])
+    actions.push(
+      await evaluateAction({
+        action,
+        task,
+        ...statusEntry !== void 0 ? { statusEntry } : {},
+        status,
+        instance,
+        definition,
+        actor,
+        ...grants !== void 0 ? { grants } : {},
+        snapshot,
+        now
+      })
+    );
+  return {
+    task,
     status,
-    ...outputs !== void 0 ? { outputs } : {},
-    ...detail !== void 0 ? { detail } : {},
-    ...actor !== void 0 ? { actor } : {}
-  }), await persist(ctx, mutation), { effectKey, status };
-}
-function buildQueuedEffect(effect, origin, params, actor, now) {
-  const key = randomKey(), pending = {
-    _key: key,
-    _type: "workflow.pendingEffect",
-    effectId: effect.id,
-    ...effect.title !== void 0 ? { title: effect.title } : {},
-    ...effect.description !== void 0 ? { description: effect.description } : {},
-    ...effect.bindings !== void 0 ? { bindings: effect.bindings } : {},
-    params,
-    origin,
-    ...actor !== void 0 ? { actor } : {},
-    queuedAt: now
-  }, history = {
-    _key: randomKey(),
-    _type: "workflow.history.effectQueued",
-    at: now,
-    effectKey: key,
-    effectId: effect.id,
-    origin
+    // "pending on actor" treats both `pending` and `active` as waiting on
+    // the assignee — pending tasks just haven't been auto-invoked yet, but
+    // they're still inbox items.
+    pendingOnActor: (status === "active" || status === "pending") && actorIsAssignee(actor, task.assignees ?? []),
+    actions
   };
-  return { pending, history };
 }
-async function queueEffects(ctx, mutation, effects, origin, actor, callerParams) {
-  if (!effects) return;
-  const now = ctx.now, liveInstance = {
-    ...ctx.instance,
-    state: mutation.state,
-    stages: mutation.stages,
-    effectsContext: mutation.effectsContext
-  };
-  for (const effect of effects) {
-    const params = await resolveBindings({
-      bindings: effect.bindings,
-      staticInput: effect.input,
-      instance: liveInstance,
-      now,
-      ...callerParams !== void 0 ? { params: callerParams } : {},
-      ...actor !== void 0 ? { actor } : {}
-    }), { pending, history } = buildQueuedEffect(effect, origin, params, actor, now);
-    mutation.pendingEffects.push(pending), mutation.history.push(history);
-  }
+async function evaluateAction(args) {
+  const { action, task, status, instance, definition, actor, grants, snapshot, now } = args, syncReason = lifecycleReason(instance, definition, status) ?? actorReason(action, task, actor);
+  if (syncReason !== void 0) return disabled(action, syncReason);
+  const asyncReason = await permissionReason(action, instance, actor, grants) ?? await filterReason(action, instance, definition, snapshot, now);
+  return asyncReason !== void 0 ? disabled(action, asyncReason) : { action, allowed: !0 };
 }
-const STATE_OP_TYPES = [
-  "workflow.op.state.set",
-  "workflow.op.state.append",
-  "workflow.op.state.updateWhere",
-  "workflow.op.state.removeWhere"
-];
-function isStateOp(summary) {
-  return STATE_OP_TYPES.includes(summary.opType);
+function lifecycleReason(instance, definition, status) {
+  if (instance.completedAt !== void 0)
+    return { kind: "instance-completed", completedAt: instance.completedAt };
+  if (definition.stages.find((s) => s.id === instance.currentStageId)?.kind === "terminal")
+    return { kind: "stage-terminal", stageId: instance.currentStageId };
+  if (status === "done" || status === "skipped" || status === "failed")
+    return { kind: "task-not-active", status };
 }
-function validateActionParams(action, taskId, callerParams) {
-  const declared = action.params ?? [], params = callerParams ?? {}, issues = [];
-  for (const decl of declared) {
-    const value = params[decl.id], present = decl.id in params && value !== void 0 && value !== null;
-    if (decl.required === !0 && !present) {
-      issues.push({ paramId: decl.id, reason: "required but missing" });
-      continue;
-    }
-    present && (checkParamType(value, decl) || issues.push({
-      paramId: decl.id,
-      reason: `expected paramType=${decl.paramType}, got ${typeof value}`
-    }));
-  }
-  if (issues.length > 0)
-    throw new ActionParamsInvalidError({ action: action.id, taskId, issues });
-  return params;
+function actorReason(action, task, actor) {
+  const actorRoles = actor.roles ?? [];
+  if (action.roles !== void 0 && action.roles.length > 0 && !(actorRoles.includes(WILDCARD_ROLE) || action.roles.some((r) => actorRoles.includes(r))))
+    return { kind: "role-required", required: [...action.roles], actorRoles: [...actorRoles] };
+  if (action.requireAssignment === !0 && !actorIsAssignee(actor, task.assignees ?? []))
+    return { kind: "not-assigned", assignees: [...task.assignees ?? []], actorId: actor.id };
 }
-function hasStringField(value, field) {
-  return typeof value == "object" && value !== null && field in value && typeof value[field] == "string";
+async function permissionReason(action, instance, actor, grants) {
+  if (grants === void 0) return;
+  const permission = action.requiredPermission ?? "update";
+  if (!await grantsPermissionOn({
+    document: instance,
+    grants,
+    permission,
+    userId: actor.id
+  }))
+    return { kind: "permission-denied", permission, matchingGrants: grants.length };
 }
-function checkParamType(value, decl) {
-  switch (decl.paramType) {
-    case "string":
-    case "url":
-    case "dateTime":
-      return typeof value == "string";
-    case "number":
-      return typeof value == "number" && Number.isFinite(value);
-    case "boolean":
-      return typeof value == "boolean";
-    case "actor":
-      return hasStringField(value, "kind");
-    case "doc.ref":
-      return hasStringField(value, "id");
-    case "doc.refs":
-      return Array.isArray(value) && value.every((v2) => checkParamType(v2, { paramType: "doc.ref" }));
-    case "json":
+async function filterReason(action, instance, definition, snapshot, now) {
+  if (!(action.filter === void 0 || await evaluateFilter({
+    filter: action.filter,
+    definition,
+    snapshot,
+    params: buildParams(instance, now)
+  })))
+    return { kind: "filter-failed", filter: action.filter };
+}
+function disabled(action, reason) {
+  return { action, allowed: !1, disabledReason: reason };
+}
+function actorIsAssignee(actor, assignees) {
+  if (assignees.length === 0) return !1;
+  const actorRoles = actor.roles ?? [], wildcard = actorRoles.includes(WILDCARD_ROLE);
+  for (const assignee of assignees)
+    if (assignee.kind === "user" && assignee.id === actor.id || assignee.kind === "role" && (wildcard || actorRoles.includes(assignee.role)))
       return !0;
-    default:
-      return !1;
-  }
+  return !1;
 }
-async function runActionOps(args) {
-  const { ops, mutation, stageId, taskId, actionName, params, actor, self, now } = args;
-  if (ops === void 0 || ops.length === 0) return [];
-  const summaries = [];
-  for (const op of ops) {
-    const summary = applyOp(op, { mutation, stageId, taskId, params, actor, self, now });
-    summaries.push(summary), mutation.history.push({
-      _key: randomKey(),
-      _type: "workflow.history.opApplied",
-      at: now,
-      stageId,
-      taskId,
-      actionId: actionName,
-      opType: summary.opType,
-      ...summary.target !== void 0 ? { target: summary.target } : {},
-      ...summary.resolved !== void 0 ? { resolved: summary.resolved } : {},
-      ...actor !== void 0 ? { actor } : {}
-    });
+function parseDefinitionSnapshot(instance) {
+  try {
+    return JSON.parse(instance.definitionSnapshot);
+  } catch (err) {
+    throw new Error(
+      `Failed to parse definitionSnapshot on instance "${instance._id}": ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
+    );
   }
-  return summaries;
 }
-function applyOp(op, ctx) {
-  switch (op.type) {
-    case "workflow.op.state.set":
-      return applyStateSet(op, ctx);
-    case "workflow.op.state.append":
-      return applyStateAppend(op, ctx);
-    case "workflow.op.state.updateWhere":
-      return applyStateUpdateWhere(op, ctx);
-    case "workflow.op.state.removeWhere":
-      return applyStateRemoveWhere(op, ctx);
-    case "workflow.op.status.set":
-      return applyStatusSet(op, ctx);
-  }
+const resourceKey = (r) => `${r.type}.${r.id}`;
+function guardsForResource(client) {
+  return client.fetch("*[_type == $t] | order(_id asc)", { t: GUARD_DOC_TYPE });
 }
-function applyStateSet(op, ctx) {
-  const value = resolveOpSource(op.value, ctx), slot = locateSlot(
-    ctx,
-    op.target,
-    /*createIfMissing*/
-    !0
+async function guardsForInstance(args) {
+  const { client, clientForGdr, instance } = args, clientsByResource = /* @__PURE__ */ new Map([
+    [resourceKey(instance.workflowResource), client]
+  ]), stateUris = [
+    ...collectSlotDocUris(instance.state),
+    ...instance.stages.flatMap((stage) => collectSlotDocUris(stage.state))
+  ];
+  for (const uri of stateUris) {
+    const parsed = tryParseGdr(uri);
+    if (parsed === void 0) continue;
+    const key = resourceKey(resourceFromParsed(parsed));
+    clientsByResource.has(key) || clientsByResource.set(key, clientForGdr(parsed));
+  }
+  const perResource = await Promise.all(
+    [...clientsByResource.values()].map(
+      (c) => c.fetch("*[_type == $t && sourceInstanceId == $id]", {
+        t: GUARD_DOC_TYPE,
+        id: instance._id
+      })
+    )
   );
-  return slot !== void 0 && (validateSlotValue({ slotType: slot._type, slotId: slot.id, value }), slot.value = value), { opType: op.type, target: op.target, resolved: { value } };
+  return dedupById(perResource.flat());
 }
-function applyStateAppend(op, ctx) {
-  const item = resolveOpSource(op.item, ctx), slot = locateSlot(
-    ctx,
-    op.target,
-    /*createIfMissing*/
-    !0
-  );
-  if (slot !== void 0) {
-    validateSlotAppendItem({ slotType: slot._type, slotId: slot.id, item });
-    const current = Array.isArray(slot.value) ? slot.value : [];
-    slot.value = [...current, withRowKey(item)];
+function tryParseGdr(uri) {
+  try {
+    return parseGdr(uri);
+  } catch {
+    return;
   }
-  return { opType: op.type, target: op.target, resolved: { item } };
 }
-function withRowKey(item) {
-  return typeof item == "object" && item !== null && !Array.isArray(item) && !("_key" in item) ? { _key: randomKey(), ...item } : item;
+function dedupById(guards) {
+  return [...new Map(guards.map((g) => [g._id, g])).values()].sort((a, b) => a._id.localeCompare(b._id));
 }
-function applyStateUpdateWhere(op, ctx) {
-  const slot = locateSlot(
+function definitionDocId(_workflowResource, prefix, workflowId, version) {
+  return `${prefix}.${workflowId}.v${version}`;
+}
+async function sortByDependencies(client, definitions, tags, workflowResource) {
+  const prefix = canonicalTag(tags), byWorkflowId = /* @__PURE__ */ new Map();
+  for (const def of definitions) {
+    const list = byWorkflowId.get(def.workflowId) ?? [];
+    list.push(def), byWorkflowId.set(def.workflowId, list);
+  }
+  const findInBatch = (ref) => findRefInBatch(byWorkflowId, ref);
+  return await assertCrossBatchRefsDeployed(client, definitions, {
+    tags,
+    workflowResource,
+    prefix,
+    findInBatch
+  }), topoSortDefinitions(definitions, { workflowResource, prefix, findInBatch });
+}
+function findRefInBatch(byWorkflowId, ref) {
+  const candidates = byWorkflowId.get(ref.workflowId);
+  if (!(candidates === void 0 || candidates.length === 0))
+    return typeof ref.version == "number" ? candidates.find((c) => c.version === ref.version) : candidates.reduce(
+      (best, c) => best === void 0 || c.version > best.version ? c : best,
+      void 0
+    );
+}
+async function assertCrossBatchRefsDeployed(client, definitions, ctx) {
+  const missing = [];
+  for (const def of definitions) {
+    const fromId = definitionDocId(ctx.workflowResource, ctx.prefix, def.workflowId, def.version);
+    for (const ref of refsOf(def)) {
+      if (ctx.findInBatch(ref) !== void 0) continue;
+      const label = await resolveDeployedRefLabel(client, ref, ctx.tags);
+      label !== void 0 && missing.push({ from: fromId, ref: label });
+    }
+  }
+  if (missing.length === 0) return;
+  const lines = missing.map((m) => `  - ${m.from} \u2192 ${m.ref} (neither in batch nor deployed)`);
+  throw new Error(
+    `workflow.deployDefinitions: ${missing.length} unresolved reference${missing.length === 1 ? "" : "s"}:
+` + lines.join(`
+`)
+  );
+}
+async function resolveDeployedRefLabel(client, ref, tags) {
+  const wantsExplicit = typeof ref.version == "number", params = { workflowId: ref.workflowId, engineTags: tags };
+  if (wantsExplicit && (params.version = ref.version), !await client.fetch(
+    definitionLookupGroq(wantsExplicit),
+    params
+  ))
+    return wantsExplicit ? `${ref.workflowId} v${ref.version}` : ref.workflowId;
+}
+function topoSortDefinitions(definitions, ctx) {
+  const visited = /* @__PURE__ */ new Set(), visiting = /* @__PURE__ */ new Set(), ordered = [], visit = (def) => {
+    const id = definitionDocId(ctx.workflowResource, ctx.prefix, def.workflowId, def.version);
+    if (!visited.has(id)) {
+      if (visiting.has(id))
+        throw new Error(`workflow.deployDefinitions: dependency cycle involving "${id}"`);
+      visiting.add(id);
+      for (const ref of refsOf(def)) {
+        const child = ctx.findInBatch(ref);
+        child !== void 0 && visit(child);
+      }
+      visiting.delete(id), visited.add(id), ordered.push(def);
+    }
+  };
+  for (const def of definitions) visit(def);
+  return ordered;
+}
+function refsOf(def) {
+  const out = [];
+  for (const stage of def.stages)
+    for (const task of stage.tasks ?? []) {
+      const ref = task.spawns?.definitionRef;
+      ref !== void 0 && out.push({
+        workflowId: ref.workflowId,
+        ...ref.version !== void 0 ? { version: ref.version } : {}
+      });
+    }
+  return out;
+}
+function isDefinitionUnchanged(existing, expected) {
+  return stableStringify(stripSystemFields(existing)) === stableStringify(stripSystemFields(expected));
+}
+function stripSystemFields(doc) {
+  const out = {};
+  for (const [k, v2] of Object.entries(doc))
+    k === "_rev" || k === "_createdAt" || k === "_updatedAt" || (out[k] = v2);
+  return out;
+}
+function stableStringify(value) {
+  return value === null || typeof value != "object" ? JSON.stringify(value) : Array.isArray(value) ? `[${value.map(stableStringify).join(",")}]` : `{${Object.entries(value).toSorted(
+    ([a], [b]) => a.localeCompare(b)
+  ).map(([k, v2]) => `${JSON.stringify(k)}:${stableStringify(v2)}`).join(",")}}`;
+}
+async function loadDefinition(client, workflowId, version, tags) {
+  if (version !== void 0) {
+    const doc = await client.fetch(
+      definitionLookupGroq(!0),
+      { workflowId, version, engineTags: tags }
+    );
+    if (!doc)
+      throw new Error(`Workflow definition ${workflowId} v${version} not deployed`);
+    return doc;
+  }
+  const latest = await client.fetch(definitionLookupGroq(!1), {
+    workflowId,
+    engineTags: tags
+  });
+  if (!latest)
+    throw new Error(`No deployed definition for workflow ${workflowId}`);
+  return latest;
+}
+const STATE_OP_TYPES = [
+  "workflow.op.state.set",
+  "workflow.op.state.append",
+  "workflow.op.state.updateWhere",
+  "workflow.op.state.removeWhere"
+];
+function isStateOp(summary) {
+  return STATE_OP_TYPES.includes(summary.opType);
+}
+function validateActionParams(action, taskId, callerParams) {
+  const declared = action.params ?? [], params = callerParams ?? {}, issues = [];
+  for (const decl of declared) {
+    const value = params[decl.id], present = decl.id in params && value !== void 0 && value !== null;
+    if (decl.required === !0 && !present) {
+      issues.push({ paramId: decl.id, reason: "required but missing" });
+      continue;
+    }
+    present && (checkParamType(value, decl) || issues.push({
+      paramId: decl.id,
+      reason: `expected paramType=${decl.paramType}, got ${typeof value}`
+    }));
+  }
+  if (issues.length > 0)
+    throw new ActionParamsInvalidError({ action: action.id, taskId, issues });
+  return params;
+}
+function hasStringField(value, field) {
+  return typeof value == "object" && value !== null && field in value && typeof value[field] == "string";
+}
+function checkParamType(value, decl) {
+  switch (decl.paramType) {
+    case "string":
+    case "url":
+    case "dateTime":
+      return typeof value == "string";
+    case "number":
+      return typeof value == "number" && Number.isFinite(value);
+    case "boolean":
+      return typeof value == "boolean";
+    case "actor":
+      return hasStringField(value, "kind");
+    case "doc.ref":
+      return hasStringField(value, "id");
+    case "doc.refs":
+      return Array.isArray(value) && value.every((v2) => checkParamType(v2, { paramType: "doc.ref" }));
+    case "json":
+      return !0;
+    default:
+      return !1;
+  }
+}
+async function runActionOps(args) {
+  const { ops, mutation, stageId, taskId, actionName, params, actor, self, now } = args;
+  if (ops === void 0 || ops.length === 0) return [];
+  const summaries = [];
+  for (const op of ops) {
+    const summary = applyOp(op, { mutation, stageId, taskId, params, actor, self, now });
+    summaries.push(summary), mutation.history.push({
+      _key: randomKey(),
+      _type: "workflow.history.opApplied",
+      at: now,
+      stageId,
+      taskId,
+      actionId: actionName,
+      opType: summary.opType,
+      ...summary.target !== void 0 ? { target: summary.target } : {},
+      ...summary.resolved !== void 0 ? { resolved: summary.resolved } : {},
+      ...actor !== void 0 ? { actor } : {}
+    });
+  }
+  return summaries;
+}
+function applyOp(op, ctx) {
+  switch (op.type) {
+    case "workflow.op.state.set":
+      return applyStateSet(op, ctx);
+    case "workflow.op.state.append":
+      return applyStateAppend(op, ctx);
+    case "workflow.op.state.updateWhere":
+      return applyStateUpdateWhere(op, ctx);
+    case "workflow.op.state.removeWhere":
+      return applyStateRemoveWhere(op, ctx);
+    case "workflow.op.status.set":
+      return applyStatusSet(op, ctx);
+  }
+}
+function applyStateSet(op, ctx) {
+  const value = resolveOpSource(op.value, ctx), slot = locateSlot(
+    ctx,
+    op.target,
+    /*createIfMissing*/
+    !0
+  );
+  return slot !== void 0 && (validateSlotValue({ slotType: slot._type, slotId: slot.id, value }), slot.value = value), { opType: op.type, target: op.target, resolved: { value } };
+}
+function applyStateAppend(op, ctx) {
+  const item = resolveOpSource(op.item, ctx), slot = locateSlot(
+    ctx,
+    op.target,
+    /*createIfMissing*/
+    !0
+  );
+  if (slot !== void 0) {
+    validateSlotAppendItem({ slotType: slot._type, slotId: slot.id, item });
+    const current = Array.isArray(slot.value) ? slot.value : [];
+    slot.value = [...current, withRowKey(item)];
+  }
+  return { opType: op.type, target: op.target, resolved: { item } };
+}
+function withRowKey(item) {
+  return typeof item == "object" && item !== null && !Array.isArray(item) && !("_key" in item) ? { _key: randomKey(), ...item } : item;
+}
+function applyStateUpdateWhere(op, ctx) {
+  const slot = locateSlot(
     ctx,
     op.target,
     /*createIfMissing*/
@@ -2132,382 +2591,89 @@ async function fireAction(args) {
       if (!isRevisionConflict(error)) throw error;
     }
   }
-  throw new ConcurrentFireActionError({
-    instanceId,
-    taskId,
-    action,
-    attempts: CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS
-  });
-}
-async function resolveActionCommit(ctx, taskId, actionName, callerParams) {
-  const { stage, task } = findTaskInCurrentStage(ctx, taskId), action = (task.actions ?? []).find((a) => a.id === actionName);
-  if (action === void 0)
-    throw new Error(`Action "${actionName}" not declared on task "${taskId}"`);
-  if (!await ctxEvaluateFilter(ctx, action.filter))
-    throw new Error(`Action "${actionName}" filter rejected on task "${taskId}"`);
-  const entry = findCurrentTasks(ctx.instance).find((t) => t.id === taskId);
-  if (entry === void 0 || entry.status !== "active")
-    throw new Error(
-      `Task "${taskId}" must be active to fire action "${actionName}"; status is ${entry?.status ?? "missing"}`
-    );
-  const params = validateActionParams(action, taskId, callerParams);
-  return { stage, task, action, params };
-}
-function applyActionSetStatus(action, mutation, mutEntry, stageId, taskId, actor, now) {
-  if (action.setStatus === void 0) return;
-  const initialStatus = mutEntry.status, newStatus = action.setStatus;
-  return mutEntry.status = newStatus, mutEntry.completedAt = now, actor && (mutEntry.completedBy = actor.id), mutation.history.push(
-    taskStatusChangedEntry({
-      stageId,
-      taskId,
-      from: initialStatus,
-      to: newStatus,
-      at: now,
-      ...actor !== void 0 ? { actor } : {}
-    })
-  ), newStatus;
-}
-async function commitAction(ctx, taskId, actionName, callerParams, actor) {
-  const { stage, task, action, params } = await resolveActionCommit(
-    ctx,
-    taskId,
-    actionName,
-    callerParams
-  ), mutation = startMutation(ctx.instance), mutEntry = requireMutationTaskEntry(mutation, taskId), now = ctx.now;
-  mutation.history.push({
-    _key: randomKey(),
-    _type: "workflow.history.actionFired",
-    at: now,
-    stageId: stage.id,
-    taskId,
-    actionId: actionName,
-    ...actor !== void 0 ? { actor } : {}
-  });
-  const ranOps = await runActionOps({
-    ops: action.ops,
-    mutation,
-    stageId: stage.id,
-    taskId,
-    actionName,
-    params,
-    actor,
-    self: selfGdr(ctx.instance),
-    now
-  }), newStatus = applyActionSetStatus(action, mutation, mutEntry, stage.id, taskId, actor, now);
-  return await queueEffects(
-    ctx,
-    mutation,
-    action.effects,
-    {
-      kind: "action",
-      id: `${task.id}:${actionName}`
-    },
-    actor,
-    params
-  ), await persistThenDeploy(
-    ctx,
-    mutation,
-    () => ranOps.some(isStateOp) ? refreshStageGuards(ctx, mutation, stage.id) : Promise.resolve()
-  ), {
-    fired: !0,
-    taskId,
-    action: actionName,
-    ...newStatus !== void 0 ? { newStatus } : {},
-    ...ranOps.length > 0 ? { ranOps } : {}
-  };
-}
-const parsedFilters = /* @__PURE__ */ new Map();
-async function matchesFilter(args) {
-  const { document, filter, userId } = args;
-  parsedFilters.has(filter) || parsedFilters.set(filter, parse(`*[${filter}]`));
-  const ast = parsedFilters.get(filter), data = await (await evaluate(ast, {
-    dataset: [document],
-    ...userId !== void 0 ? { identity: userId } : {}
-  })).get();
-  return Array.isArray(data) && data.length === 1;
-}
-async function grantsPermissionOn(args) {
-  const { document, grants, permission, userId } = args;
-  if (!document || grants.length === 0) return !1;
-  for (const grant of grants)
-    if (grant.permissions.includes(permission) && await matchesFilter({
-      document,
-      filter: grant.filter,
-      ...userId !== void 0 ? { userId } : {}
-    }))
-      return !0;
-  return !1;
-}
-async function fetchGrants(args) {
-  const { client, resourcePath, signal } = args;
-  return client.request({ url: resourcePath, ...signal ? { signal } : {} });
-}
-const actorCache = /* @__PURE__ */ new WeakMap(), grantsCache = /* @__PURE__ */ new WeakMap();
-async function resolveAccess(client, args = {}) {
-  const overrideActor = args.override?.actor, overrideGrants = args.override?.grants;
-  if (overrideActor !== void 0 && overrideGrants !== void 0)
-    return { actor: overrideActor, grants: overrideGrants };
-  const requestFn = client.request === void 0 ? void 0 : (opts) => client.request(opts);
-  if (requestFn === void 0) {
-    if (overrideActor === void 0)
-      throw new Error(
-        "workflow: no actor available. The engine resolves the actor from the client's token via `client.request({ url: '/users/me' })`. Supply a real `@sanity/client` configured with a token, or pass an explicit `access.actor` override (the test bench provides one by default)."
-      );
-    return { actor: overrideActor };
-  }
-  const actorPromise = overrideActor !== void 0 ? Promise.resolve(overrideActor) : cachedActor(client, requestFn), grantsPromise = overrideGrants !== void 0 ? Promise.resolve(overrideGrants) : args.grantsFromPath !== void 0 ? cachedGrants(client, requestFn, args.grantsFromPath) : Promise.resolve(void 0), [actor, grants] = await Promise.all([actorPromise, grantsPromise]);
-  if (actor === void 0)
-    throw new Error(
-      "workflow: failed to resolve actor from `/users/me`. The client is configured but the endpoint returned no usable identity \u2014 check the token, or pass `access.actor` explicitly."
-    );
-  return { actor, ...grants !== void 0 ? { grants } : {} };
-}
-function cachedActor(client, requestFn) {
-  const cached = actorCache.get(client);
-  if (cached !== void 0) return cached;
-  const pending = fetchActor(requestFn).catch((err) => {
-    throw actorCache.get(client) === pending && actorCache.delete(client), err;
-  });
-  return actorCache.set(client, pending), pending;
-}
-function cachedGrants(client, requestFn, resourcePath) {
-  let byPath = grantsCache.get(client);
-  byPath === void 0 && (byPath = /* @__PURE__ */ new Map(), grantsCache.set(client, byPath));
-  let cached = byPath.get(resourcePath);
-  return cached === void 0 && (cached = fetchGrantsCached(requestFn, resourcePath), byPath.set(resourcePath, cached)), cached;
-}
-async function fetchActor(requestFn) {
-  let user;
-  try {
-    user = await requestFn({
-      uri: "/users/me",
-      tag: "workflow.access.resolve-actor"
-    });
-  } catch (err) {
-    throw new Error(
-      'workflow: /users/me request failed. The engine resolves the actor from the client\'s token via `client.request({ uri: "/users/me" })`. Check the token/connectivity, or pass an explicit `access.actor` override.',
-      { cause: err }
-    );
-  }
-  if (!user || typeof user.id != "string" || user.id.length === 0) return;
-  const roleNames = user.roles?.map((r) => r.name).filter((n) => !!n) ?? [];
-  return {
-    kind: "user",
-    id: user.id,
-    ...roleNames.length > 0 ? { roles: roleNames } : {}
-  };
-}
-async function fetchGrantsCached(requestFn, resourcePath) {
-  try {
-    return await fetchGrants({ client: { request: requestFn }, resourcePath });
-  } catch (err) {
-    console.warn(
-      `workflow: failed to fetch grants from "${resourcePath}"; skipping permission gate. Original error: ${err instanceof Error ? err.message : String(err)}`
-    );
-    return;
-  }
-}
-const TAG_RE = /^[a-z0-9][a-z0-9-]*$/;
-function validateTags(tags) {
-  if (tags.length === 0)
-    throw new Error("tags: must be a non-empty array");
-  for (const tag of tags)
-    if (!TAG_RE.test(tag))
-      throw new Error(
-        `tags: invalid tag "${tag}" \u2014 must match ${TAG_RE.source} (ASCII lowercase + digits + dashes, no leading dash, no dots)`
-      );
-}
-function canonicalTag(tags) {
-  return tags[0];
-}
-const WILDCARD_ROLE = "*";
-async function evaluateInstance(args) {
-  const { client, tags, instanceId, resourceClients } = args, now = (args.clock ?? wallClock)();
-  validateTags(tags);
-  const { actor, grants } = await resolveAccess(client, {
-    ...args.access !== void 0 ? { override: args.access } : {},
-    ...args.grantsFromPath !== void 0 ? { grantsFromPath: args.grantsFromPath } : {}
-  }), instance = await client.getDocument(instanceId);
-  if (!instance)
-    throw new Error(`Workflow instance "${instanceId}" not found`);
-  if (!tags.some((t) => instance.tags?.includes(t)))
-    throw new Error(`Workflow instance "${instanceId}" not visible to this engine (tag mismatch)`);
-  const definition = parseDefinitionSnapshot(instance), stage = definition.stages.find((s) => s.id === instance.currentStageId);
-  if (stage === void 0)
-    throw new Error(
-      `Instance "${instanceId}" currentStageId "${instance.currentStageId}" not in definition`
-    );
-  const snapshot = await hydrateSnapshot({
-    client,
-    clientForGdr: resourceClients !== void 0 ? (parsed) => resourceClients(parsed) ?? client : () => client,
-    instance,
-    definition
-  }), currentTaskEntries = instance.stages.find(
-    (s) => s.id === instance.currentStageId && s.exitedAt === void 0
-  )?.tasks ?? [], taskEvaluations = [];
-  for (const task of stage.tasks ?? [])
-    taskEvaluations.push(
-      await evaluateTask({
-        task,
-        statusEntry: currentTaskEntries.find((t) => t.id === task.id),
-        instance,
-        definition,
-        actor,
-        grants,
-        snapshot,
-        now
-      })
-    );
-  const transitionEvaluations = [];
-  for (const transition of stage.transitions ?? [])
-    transitionEvaluations.push({
-      transition,
-      filterSatisfied: await evaluateFilter({
-        filter: transition.filter,
-        definition,
-        snapshot,
-        params: buildParams(instance, now)
-      })
-    });
-  const currentStage = {
-    stage,
-    tasks: taskEvaluations,
-    transitions: transitionEvaluations
-  }, pendingOnYou = taskEvaluations.filter((t) => t.pendingOnActor), canInteract = taskEvaluations.some((t) => t.actions.some((a) => a.allowed));
-  return {
-    instance,
-    definition,
-    actor,
-    currentStage,
-    pendingOnYou,
-    canInteract
-  };
-}
-async function evaluateTask(args) {
-  const { task, statusEntry, instance, definition, actor, grants, snapshot, now } = args, status = statusEntry?.status ?? "pending", actions = [];
-  for (const action of task.actions ?? [])
-    actions.push(
-      await evaluateAction({
-        action,
-        task,
-        ...statusEntry !== void 0 ? { statusEntry } : {},
-        status,
-        instance,
-        definition,
-        actor,
-        ...grants !== void 0 ? { grants } : {},
-        snapshot,
-        now
-      })
-    );
-  return {
-    task,
-    status,
-    // "pending on actor" treats both `pending` and `active` as waiting on
-    // the assignee — pending tasks just haven't been auto-invoked yet, but
-    // they're still inbox items.
-    pendingOnActor: (status === "active" || status === "pending") && actorIsAssignee(actor, task.assignees ?? []),
-    actions
-  };
-}
-async function evaluateAction(args) {
-  const { action, task, status, instance, definition, actor, grants, snapshot, now } = args, syncReason = lifecycleReason(instance, definition, status) ?? actorReason(action, task, actor);
-  if (syncReason !== void 0) return disabled(action, syncReason);
-  const asyncReason = await permissionReason(action, instance, actor, grants) ?? await filterReason(action, instance, definition, snapshot, now);
-  return asyncReason !== void 0 ? disabled(action, asyncReason) : { action, allowed: !0 };
-}
-function lifecycleReason(instance, definition, status) {
-  if (instance.completedAt !== void 0)
-    return { kind: "instance-completed", completedAt: instance.completedAt };
-  if (definition.stages.find((s) => s.id === instance.currentStageId)?.kind === "terminal")
-    return { kind: "stage-terminal", stageId: instance.currentStageId };
-  if (status === "done" || status === "skipped" || status === "failed")
-    return { kind: "task-not-active", status };
-}
-function actorReason(action, task, actor) {
-  const actorRoles = actor.roles ?? [];
-  if (action.roles !== void 0 && action.roles.length > 0 && !(actorRoles.includes(WILDCARD_ROLE) || action.roles.some((r) => actorRoles.includes(r))))
-    return { kind: "role-required", required: [...action.roles], actorRoles: [...actorRoles] };
-  if (action.requireAssignment === !0 && !actorIsAssignee(actor, task.assignees ?? []))
-    return { kind: "not-assigned", assignees: [...task.assignees ?? []], actorId: actor.id };
-}
-async function permissionReason(action, instance, actor, grants) {
-  if (grants === void 0) return;
-  const permission = action.requiredPermission ?? "update";
-  if (!await grantsPermissionOn({
-    document: instance,
-    grants,
-    permission,
-    userId: actor.id
-  }))
-    return { kind: "permission-denied", permission, matchingGrants: grants.length };
-}
-async function filterReason(action, instance, definition, snapshot, now) {
-  if (!(action.filter === void 0 || await evaluateFilter({
-    filter: action.filter,
-    definition,
-    snapshot,
-    params: buildParams(instance, now)
-  })))
-    return { kind: "filter-failed", filter: action.filter };
-}
-function disabled(action, reason) {
-  return { action, allowed: !1, disabledReason: reason };
-}
-function actorIsAssignee(actor, assignees) {
-  if (assignees.length === 0) return !1;
-  const actorRoles = actor.roles ?? [], wildcard = actorRoles.includes(WILDCARD_ROLE);
-  for (const assignee of assignees)
-    if (assignee.kind === "user" && assignee.id === actor.id || assignee.kind === "role" && (wildcard || actorRoles.includes(assignee.role)))
-      return !0;
-  return !1;
-}
-function parseDefinitionSnapshot(instance) {
-  try {
-    return JSON.parse(instance.definitionSnapshot);
-  } catch (err) {
-    throw new Error(
-      `Failed to parse definitionSnapshot on instance "${instance._id}": ${err instanceof Error ? err.message : String(err)}`,
-      { cause: err }
-    );
-  }
-}
-const resourceKey = (r) => `${r.type}.${r.id}`;
-function guardsForResource(client) {
-  return client.fetch("*[_type == $t] | order(_id asc)", { t: GUARD_DOC_TYPE });
-}
-async function guardsForInstance(args) {
-  const { client, clientForGdr, instance } = args, clientsByResource = /* @__PURE__ */ new Map([
-    [resourceKey(instance.workflowResource), client]
-  ]), stateUris = [
-    ...collectSlotDocUris(instance.state),
-    ...instance.stages.flatMap((stage) => collectSlotDocUris(stage.state))
-  ];
-  for (const uri of stateUris) {
-    const parsed = tryParseGdr(uri);
-    if (parsed === void 0) continue;
-    const key = resourceKey(resourceFromParsed(parsed));
-    clientsByResource.has(key) || clientsByResource.set(key, clientForGdr(parsed));
-  }
-  const perResource = await Promise.all(
-    [...clientsByResource.values()].map(
-      (c) => c.fetch("*[_type == $t && sourceInstanceId == $id]", {
-        t: GUARD_DOC_TYPE,
-        id: instance._id
-      })
-    )
-  );
-  return dedupById(perResource.flat());
+  throw new ConcurrentFireActionError({
+    instanceId,
+    taskId,
+    action,
+    attempts: CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS
+  });
 }
-function tryParseGdr(uri) {
-  try {
-    return parseGdr(uri);
-  } catch {
-    return;
-  }
+async function resolveActionCommit(ctx, taskId, actionName, callerParams) {
+  const { stage, task } = findTaskInCurrentStage(ctx, taskId), action = (task.actions ?? []).find((a) => a.id === actionName);
+  if (action === void 0)
+    throw new Error(`Action "${actionName}" not declared on task "${taskId}"`);
+  if (!await ctxEvaluateFilter(ctx, action.filter))
+    throw new Error(`Action "${actionName}" filter rejected on task "${taskId}"`);
+  const entry = findCurrentTasks(ctx.instance).find((t) => t.id === taskId);
+  if (entry === void 0 || entry.status !== "active")
+    throw new Error(
+      `Task "${taskId}" must be active to fire action "${actionName}"; status is ${entry?.status ?? "missing"}`
+    );
+  const params = validateActionParams(action, taskId, callerParams);
+  return { stage, task, action, params };
 }
-function dedupById(guards) {
-  return [...new Map(guards.map((g) => [g._id, g])).values()].sort((a, b) => a._id.localeCompare(b._id));
+function applyActionSetStatus(action, mutation, mutEntry, stageId, taskId, actor, now) {
+  if (action.setStatus === void 0) return;
+  const initialStatus = mutEntry.status, newStatus = action.setStatus;
+  return mutEntry.status = newStatus, mutEntry.completedAt = now, actor && (mutEntry.completedBy = actor.id), mutation.history.push(
+    taskStatusChangedEntry({
+      stageId,
+      taskId,
+      from: initialStatus,
+      to: newStatus,
+      at: now,
+      ...actor !== void 0 ? { actor } : {}
+    })
+  ), newStatus;
+}
+async function commitAction(ctx, taskId, actionName, callerParams, actor) {
+  const { stage, task, action, params } = await resolveActionCommit(
+    ctx,
+    taskId,
+    actionName,
+    callerParams
+  ), mutation = startMutation(ctx.instance), mutEntry = requireMutationTaskEntry(mutation, taskId), now = ctx.now;
+  mutation.history.push({
+    _key: randomKey(),
+    _type: "workflow.history.actionFired",
+    at: now,
+    stageId: stage.id,
+    taskId,
+    actionId: actionName,
+    ...actor !== void 0 ? { actor } : {}
+  });
+  const ranOps = await runActionOps({
+    ops: action.ops,
+    mutation,
+    stageId: stage.id,
+    taskId,
+    actionName,
+    params,
+    actor,
+    self: selfGdr(ctx.instance),
+    now
+  }), newStatus = applyActionSetStatus(action, mutation, mutEntry, stage.id, taskId, actor, now);
+  return await queueEffects(
+    ctx,
+    mutation,
+    action.effects,
+    {
+      kind: "action",
+      id: `${task.id}:${actionName}`
+    },
+    actor,
+    params
+  ), await persistThenDeploy(
+    ctx,
+    mutation,
+    () => ranOps.some(isStateOp) ? refreshStageGuards(ctx, mutation, stage.id) : Promise.resolve()
+  ), {
+    fired: !0,
+    taskId,
+    action: actionName,
+    ...newStatus !== void 0 ? { newStatus } : {},
+    ...ranOps.length > 0 ? { ranOps } : {}
+  };
 }
 class ActionDisabledError extends Error {
   reason;
@@ -2531,121 +2697,6 @@ function formatDisabledReason(taskId, action, reason) {
   const detail = disabledReasonDetail[reason.kind](reason);
   return `Action "${taskId}:${action}" is not allowed: ${detail}`;
 }
-function definitionDocId(_workflowResource, prefix, workflowId, version) {
-  return `${prefix}.${workflowId}.v${version}`;
-}
-async function sortByDependencies(client, definitions, tags, workflowResource) {
-  const prefix = canonicalTag(tags), byWorkflowId = /* @__PURE__ */ new Map();
-  for (const def of definitions) {
-    const list = byWorkflowId.get(def.workflowId) ?? [];
-    list.push(def), byWorkflowId.set(def.workflowId, list);
-  }
-  const findInBatch = (ref) => findRefInBatch(byWorkflowId, ref);
-  return await assertCrossBatchRefsDeployed(client, definitions, {
-    tags,
-    workflowResource,
-    prefix,
-    findInBatch
-  }), topoSortDefinitions(definitions, { workflowResource, prefix, findInBatch });
-}
-function findRefInBatch(byWorkflowId, ref) {
-  const candidates = byWorkflowId.get(ref.workflowId);
-  if (!(candidates === void 0 || candidates.length === 0))
-    return typeof ref.version == "number" ? candidates.find((c) => c.version === ref.version) : candidates.reduce(
-      (best, c) => best === void 0 || c.version > best.version ? c : best,
-      void 0
-    );
-}
-async function assertCrossBatchRefsDeployed(client, definitions, ctx) {
-  const missing = [];
-  for (const def of definitions) {
-    const fromId = definitionDocId(ctx.workflowResource, ctx.prefix, def.workflowId, def.version);
-    for (const ref of refsOf(def)) {
-      if (ctx.findInBatch(ref) !== void 0) continue;
-      const label = await resolveDeployedRefLabel(client, ref, ctx.tags);
-      label !== void 0 && missing.push({ from: fromId, ref: label });
-    }
-  }
-  if (missing.length === 0) return;
-  const lines = missing.map((m) => `  - ${m.from} \u2192 ${m.ref} (neither in batch nor deployed)`);
-  throw new Error(
-    `workflow.deployDefinitions: ${missing.length} unresolved reference${missing.length === 1 ? "" : "s"}:
-` + lines.join(`
-`)
-  );
-}
-async function resolveDeployedRefLabel(client, ref, tags) {
-  const wantsExplicit = typeof ref.version == "number", params = { workflowId: ref.workflowId, tags };
-  if (wantsExplicit && (params.version = ref.version), !await client.fetch(
-    definitionLookupGroq(wantsExplicit),
-    params
-  ))
-    return wantsExplicit ? `${ref.workflowId} v${ref.version}` : ref.workflowId;
-}
-function topoSortDefinitions(definitions, ctx) {
-  const visited = /* @__PURE__ */ new Set(), visiting = /* @__PURE__ */ new Set(), ordered = [], visit = (def) => {
-    const id = definitionDocId(ctx.workflowResource, ctx.prefix, def.workflowId, def.version);
-    if (!visited.has(id)) {
-      if (visiting.has(id))
-        throw new Error(`workflow.deployDefinitions: dependency cycle involving "${id}"`);
-      visiting.add(id);
-      for (const ref of refsOf(def)) {
-        const child = ctx.findInBatch(ref);
-        child !== void 0 && visit(child);
-      }
-      visiting.delete(id), visited.add(id), ordered.push(def);
-    }
-  };
-  for (const def of definitions) visit(def);
-  return ordered;
-}
-function definitionLookupGroq(wantsExplicit) {
-  return wantsExplicit ? '*[_type == "workflow.definition" && workflowId == $workflowId && version == $version && count(tags[@ in $tags]) > 0][0]' : '*[_type == "workflow.definition" && workflowId == $workflowId && count(tags[@ in $tags]) > 0] | order(version desc)[0]';
-}
-function refsOf(def) {
-  const out = [];
-  for (const stage of def.stages)
-    for (const task of stage.tasks ?? []) {
-      const ref = task.spawns?.definitionRef;
-      ref !== void 0 && out.push({
-        workflowId: ref.workflowId,
-        ...ref.version !== void 0 ? { version: ref.version } : {}
-      });
-    }
-  return out;
-}
-function isDefinitionUnchanged(existing, expected) {
-  return stableStringify(stripSystemFields(existing)) === stableStringify(stripSystemFields(expected));
-}
-function stripSystemFields(doc) {
-  const out = {};
-  for (const [k, v2] of Object.entries(doc))
-    k === "_rev" || k === "_createdAt" || k === "_updatedAt" || (out[k] = v2);
-  return out;
-}
-function stableStringify(value) {
-  return value === null || typeof value != "object" ? JSON.stringify(value) : Array.isArray(value) ? `[${value.map(stableStringify).join(",")}]` : `{${Object.entries(value).toSorted(
-    ([a], [b]) => a.localeCompare(b)
-  ).map(([k, v2]) => `${JSON.stringify(k)}:${stableStringify(v2)}`).join(",")}}`;
-}
-async function loadDefinition(client, workflowId, version, tags) {
-  if (version !== void 0) {
-    const doc = await client.fetch(
-      "*[_type == 'workflow.definition' && workflowId == $id && version == $v && count(tags[@ in $engineTags]) > 0][0]",
-      { id: workflowId, v: version, engineTags: tags }
-    );
-    if (!doc)
-      throw new Error(`Workflow definition ${workflowId} v${version} not deployed`);
-    return doc;
-  }
-  const latest = await client.fetch(
-    "*[_type == 'workflow.definition' && workflowId == $id && count(tags[@ in $engineTags]) > 0] | order(version desc)[0]",
-    { id: workflowId, engineTags: tags }
-  );
-  if (!latest)
-    throw new Error(`No deployed definition for workflow ${workflowId}`);
-  return latest;
-}
 function bareIdFromSpawnRef(uri) {
   if (!uri.includes(":")) return [uri];
   try {
@@ -2666,8 +2717,15 @@ async function resolveOperationContext(args) {
     clientForGdr: buildClientForGdr(args.client, args.resourceClients)
   };
 }
-async function cascade(client, instanceId, actor, clientForGdr, clock) {
-  const count = await cascadeAutoTransitions(client, instanceId, actor, clientForGdr, clock);
+async function cascade(client, instanceId, actor, clientForGdr, clock, overlay) {
+  const count = await cascadeAutoTransitions(
+    client,
+    instanceId,
+    actor,
+    clientForGdr,
+    clock,
+    overlay
+  );
   return await propagateToAncestors(client, instanceId, actor, clientForGdr, clock), count;
 }
 function buildClientForGdr(defaultClient, resolver) {
@@ -2686,6 +2744,22 @@ function intersectsTags(docTags, engineTags) {
 function toEffectsContextEntries(ctx) {
   return Object.entries(ctx).map(([id, value]) => effectsContextEntry(id, value));
 }
+function assertActionAllowed(evaluation, taskId, action) {
+  const actionEval = evaluation.currentStage.tasks.find((t) => t.task.id === taskId)?.actions.find((a) => a.action.id === action);
+  if (actionEval?.allowed === !1 && actionEval.disabledReason)
+    throw new ActionDisabledError({ taskId, action, reason: actionEval.disabledReason });
+}
+async function applyAction(args) {
+  const { client, instance, taskId, action, params, actor, clock } = args, options = { actor, ...clock !== void 0 ? { clock } : {} };
+  return findOpenStageEntry(instance)?.tasks.find((t) => t.id === taskId)?.status === "pending" && await invokeTask({ client, instanceId: instance._id, taskId, options }), (await fireAction({
+    client,
+    instanceId: instance._id,
+    taskId,
+    action,
+    ...params !== void 0 ? { params } : {},
+    options
+  })).ranOps;
+}
 const workflow = {
   /**
    * Persist a workflow definition to the lake. Stored as a
@@ -2718,7 +2792,7 @@ const workflow = {
       const id = definitionDocId(workflowResource, prefix, def.workflowId, def.version), expected = {
         ...def,
         _id: id,
-        _type: "workflow.definition",
+        _type: WORKFLOW_DEFINITION_TYPE,
         tags
       }, existing = await client.getDocument(id);
       if (existing && intersectsTags(existing.tags, tags) && isDefinitionUnchanged(existing, expected)) {
@@ -2814,44 +2888,32 @@ const workflow = {
       params,
       idempotent,
       resourceClients
-    } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, before = await reload(client, instanceId, tags), taskEntry = before.stages.find(
-      (s) => s.id === before.currentStageId && s.exitedAt === void 0
-    )?.tasks.find((t) => t.id === taskId);
-    if (taskEntry === void 0 && idempotent === !0)
+    } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, before = await reload(client, instanceId, tags);
+    if (findOpenStageEntry(before)?.tasks.find((t) => t.id === taskId) === void 0 && idempotent === !0)
       return { instance: before, cascaded: 0, fired: !1 };
-    const actionEval = (await evaluateInstance({
+    const evaluation = await evaluateInstance({
       client,
       tags,
       instanceId,
       access,
       clock,
       ...resourceClients !== void 0 ? { resourceClients } : {}
-    })).currentStage.tasks.find((t) => t.task.id === taskId)?.actions.find((a) => a.action.id === action);
-    if (actionEval !== void 0 && !actionEval.allowed && actionEval.disabledReason)
-      throw new ActionDisabledError({
-        taskId,
-        action,
-        reason: actionEval.disabledReason
-      });
-    taskEntry?.status === "pending" && await invokeTask({
-      client,
-      instanceId,
-      taskId,
-      options: { actor, clock }
     });
-    const actionResult = await fireAction({
+    assertActionAllowed(evaluation, taskId, action);
+    const ranOps = await applyAction({
       client,
-      instanceId,
+      instance: before,
       taskId,
       action,
-      ...params !== void 0 ? { params } : {},
-      options: { actor, clock }
+      actor,
+      clock,
+      ...params !== void 0 ? { params } : {}
     }), cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
       instance: await reload(client, instanceId, tags),
       cascaded,
       fired: !0,
-      ...actionResult.ranOps !== void 0 ? { ranOps: actionResult.ranOps } : {}
+      ...ranOps !== void 0 ? { ranOps } : {}
     };
   },
   /**
@@ -2976,7 +3038,7 @@ const workflow = {
   queryInScope: async (args) => {
     const { client, tags, instanceId, groq, params, resourceClients } = args, clock = args.clock ?? wallClock;
     validateTags(tags);
-    const instance = await reload(client, instanceId, tags), definition = JSON.parse(instance.definitionSnapshot), clientForGdr = buildClientForGdr(client, resourceClients), snapshot = await hydrateSnapshot({ client, clientForGdr, instance, definition }), reserved = buildParams(instance, clock()), tree = parse(groq, { params: { ...reserved, ...params } });
+    const instance = await reload(client, instanceId, tags), clientForGdr = buildClientForGdr(client, resourceClients), snapshot = await hydrateSnapshot({ client, clientForGdr, instance }), reserved = buildParams(instance, clock()), tree = parse(groq, { params: { ...reserved, ...params } });
     return await (await evaluate(tree, {
       dataset: snapshot.docs,
       params: { ...reserved, ...params }
@@ -3019,7 +3081,7 @@ const workflow = {
     validateTags(tags);
     const parent = await reload(client, instanceId, tags), isSpawned = (h) => h._type === "workflow.history.spawned", ids = parent.history.filter(isSpawned).filter((h) => taskId === void 0 || h.taskId === taskId).flatMap((h) => bareIdFromSpawnRef(h.instanceRef.id));
     return ids.length === 0 ? [] : client.fetch(
-      "*[_id in $ids && count(tags[@ in $engineTags]) > 0] | order(startedAt asc)",
+      `*[_id in $ids && ${tagScopeFilter()}] | order(startedAt asc)`,
       { ids, engineTags: tags }
     );
   },
@@ -3038,7 +3100,7 @@ async function verifyDeployedDefinitionsInternal(args) {
   const { client, tags, effectHandlers, missingHandler, logger } = args;
   validateTags(tags);
   const log = logger("verifyDeployedDefinitions"), definitions = await client.fetch(
-    '*[_type == "workflow.definition" && count(tags[@ in $engineTags]) > 0] | order(workflowId asc, version asc)',
+    `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && ${tagScopeFilter()}] | order(workflowId asc, version asc)`,
     { engineTags: tags }
   ), seen = [], missingByName = /* @__PURE__ */ new Map();
   for (const def of definitions)
@@ -3189,6 +3251,89 @@ async function applyMissingHandler(policy, info, log) {
     return "fail";
   }
 }
+function createInstanceSession(args) {
+  const { client, tags, clock } = args, clientForGdr = buildClientForGdr(client, args.resourceClients);
+  let instance = asHeldInstance(args.instance), overlay = /* @__PURE__ */ new Map(), committing = !1, buffered;
+  const selfUri = () => gdrFromResource(instance.workflowResource, instance._id), applyUpdate = (docs) => {
+    const next = /* @__PURE__ */ new Map();
+    for (const ld of docs) {
+      const owned = { doc: structuredClone(ld.doc), resource: ld.resource }, uri = gdrFromResource(owned.resource, owned.doc._id);
+      if (uri === selfUri()) {
+        instance = asHeldInstance(owned.doc);
+        continue;
+      }
+      next.set(uri, owned);
+    }
+    overlay = next;
+  }, access = () => resolveAccess(client, {
+    ...args.access !== void 0 ? { override: args.access } : {},
+    ...args.grantsFromPath !== void 0 ? { grantsFromPath: args.grantsFromPath } : {}
+  }), snapshotFrom = (held) => buildSnapshot({ docs: [{ doc: instance, resource: instance.workflowResource }, ...held.values()] }), evaluateWith = async (held) => {
+    const { actor, grants } = await access();
+    return evaluateFromSnapshot({
+      instance,
+      definition: parseDefinitionSnapshot(instance),
+      actor,
+      snapshot: snapshotFrom(held),
+      ...clock !== void 0 ? { now: clock() } : {},
+      ...grants !== void 0 ? { grants } : {}
+    });
+  }, commit = async (run) => {
+    committing = !0;
+    const held = new Map(overlay);
+    try {
+      const { actor } = await access();
+      return await run(actor, held);
+    } finally {
+      if (committing = !1, buffered !== void 0) {
+        const next = buffered;
+        buffered = void 0, applyUpdate(next);
+      }
+    }
+  };
+  return {
+    get subscriptionDocuments() {
+      return subscriptionDocumentsForInstance(instance);
+    },
+    update(docs) {
+      if (committing) {
+        buffered = docs;
+        return;
+      }
+      applyUpdate(docs);
+    },
+    evaluate() {
+      return evaluateWith(overlay);
+    },
+    tick() {
+      return commit(async (actor, held) => {
+        const cascaded = await cascade(client, instance._id, actor, clientForGdr, clock, held);
+        return instance = await reload(client, instance._id, tags), { instance, cascaded, fired: cascaded > 0 };
+      });
+    },
+    fireAction({ taskId, action, params }) {
+      return commit(async (actor, held) => {
+        assertActionAllowed(await evaluateWith(held), taskId, action);
+        const ranOps = await applyAction({
+          client,
+          instance,
+          taskId,
+          action,
+          actor,
+          ...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, tags), { instance, cascaded, fired: !0, ...ranOps !== void 0 ? { ranOps } : {} };
+      });
+    }
+  };
+}
+function asHeldInstance(doc) {
+  const candidate = doc;
+  if (candidate._type !== "workflow.instance" || typeof candidate.currentStageId != "string" || !Array.isArray(candidate.stages))
+    throw new Error(`update: self-doc ${doc._id} is not a valid workflow.instance`);
+  return doc;
+}
 const defaultLoggerFactory = (name) => ({
   // info/warn/error all go to stderr — these are diagnostic, not
   // program output. Keeps stdout reserved for the caller's own data
@@ -3231,6 +3376,16 @@ function createEngine(args) {
     evaluateInstance: (rest) => evaluateInstance(bind(rest)),
     setStage: (rest) => workflow.setStage(bind(rest)),
     getInstance: ({ instanceId }) => workflow.getInstance({ client, tags, workflowResource, instanceId }),
+    subscriptionDocumentsForInstance: ({ instanceId }) => workflow.getInstance({ client, tags, workflowResource, instanceId }).then(subscriptionDocumentsForInstance),
+    instance: (instanceDoc, opts) => createInstanceSession({
+      client,
+      tags,
+      instance: instanceDoc,
+      ...resourceClients !== void 0 ? { resourceClients } : {},
+      ...clock !== void 0 ? { clock } : {},
+      ...opts?.access !== void 0 ? { access: opts.access } : {},
+      ...opts?.grantsFromPath !== void 0 ? { grantsFromPath: opts.grantsFromPath } : {}
+    }),
     guardsForInstance: ({ instanceId }) => workflow.guardsForInstance({
       client,
       tags,
@@ -3496,15 +3651,20 @@ export {
   MutationGuardDeniedError,
   OP_DISPLAY,
   STATE_SLOT_DISPLAY,
+  WORKFLOW_DEFINITION_TYPE,
+  WORKFLOW_INSTANCE_TYPE,
   WorkflowStateDivergedError,
+  buildSnapshot,
   canonicalTag,
   compileGuard,
+  contentReleaseName,
   createEngine,
   defaultLoggerFactory,
   denyingGuards,
   deployStageGuards,
   displayDescription,
   displayTitle,
+  evaluateFromSnapshot,
   evaluateMutationGuard,
   extractDocumentId,
   gdrFromResource,
@@ -3517,14 +3677,18 @@ export {
   isGdr,
   lakeGuardId,
   parseGdr,
+  readsRaw,
   refCanvas,
   refDashboard,
   refDataset,
   refMediaLibrary,
   resolveAccess,
+  resourceFromParsed,
   retractStageGuards,
   silentLogger,
   stripSystemFields,
+  subscriptionDocumentsForInstance,
+  tagScopeFilter,
   validateDefinition,
   validateTags,
   wallClock,