@sanity/workflow-engine 0.0.0

package/dist/index.js

@@ -0,0 +1,3264 @@
+import { parse, evaluate } from "groq-js";
+import { z } from "zod";
+function validateDefinition(definition) {
+  const v = createDefinitionValidator();
+  for (const slot of definition.state ?? [])
+    v.checkSlot(slot, "workflow.state", `workflow.state "${slot.id}"`);
+  for (const p of definition.predicates ?? [])
+    p.groq && v.checkFilter(p.groq, `predicate "${p.id}"`);
+  for (const stage of definition.stages)
+    validateStage(v, stage);
+  if (v.errors.length > 0)
+    throw new Error(
+      `defineWorkflow("${definition.workflowId}", v${definition.version}): ${v.errors.length} validation error${v.errors.length === 1 ? "" : "s"}:
+` + v.errors.join(`
+`)
+    );
+}
+function createDefinitionValidator() {
+  const errors = [], tryParse = (groq, where) => {
+    try {
+      parse(groq);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      errors.push(`  \xB7 ${where}: ${message}`);
+    }
+  }, rejectTypeScan = (groq, where) => {
+    /\*\s*\[\s*_type\b/.test(groq) && errors.push(
+      `  \xB7 ${where}: filter scans by \`_type\` \u2014 that's a discovery query, not a predicate. Filters evaluate against the in-memory snapshot (instance + ancestors + state-declared docs). To bring extra docs in scope, declare a \`workflow.state.doc.ref\` (or \`doc.refs\`) slot on the workflow or this stage. For lake scans like "all articles in this release", use spawn \`forEach.groq\` instead.`
+    );
+  };
+  return { errors, tryParse, checkFilter: (groq, where) => {
+    tryParse(groq, where), rejectTypeScan(groq, where);
+  }, checkSlot: (slot, scopeLabel, slotLabel) => {
+    slot.source.kind === "computed" && errors.push(
+      `  \xB7 ${scopeLabel} slot "${slot.id}": source.kind="computed" is reserved (not implemented in v0.1)`
+    ), slot.source.kind === "query" && tryParse(slot.source.query, `${slotLabel}.query`);
+  } };
+}
+function validateStage(v, stage) {
+  for (const slot of stage.state ?? [])
+    v.checkSlot(slot, `stage "${stage.id}".state`, `stage "${stage.id}".state "${slot.id}"`);
+  typeof stage.completion == "string" && v.tryParse(stage.completion, `stage "${stage.id}".completion`);
+  for (const t of stage.transitions ?? [])
+    typeof t.filter == "string" && v.checkFilter(t.filter, `transition ${stage.id} \u2192 ${t.to} filter`);
+  for (const task of stage.tasks ?? [])
+    validateTask(v, stage.id, task);
+}
+function validateTask(v, stageId, task) {
+  const where = `stage "${stageId}" task "${task.id}"`;
+  for (const slot of task.state ?? [])
+    v.checkSlot(slot, `${where}.state`, `${where}.state "${slot.id}"`);
+  typeof task.filter == "string" && v.checkFilter(task.filter, `${where}.filter`), typeof task.completeWhen == "string" && v.checkFilter(task.completeWhen, `${where}.completeWhen`);
+  for (const a of task.actions ?? [])
+    typeof a.filter == "string" && v.checkFilter(a.filter, `task "${task.id}" action "${a.id}".filter`);
+  task.spawns?.forEach?.groq && v.tryParse(task.spawns.forEach.groq, `task "${task.id}".spawns.forEach.groq`);
+}
+const KNOWN_SCHEMES = /* @__PURE__ */ new Set(["dataset", "canvas", "media-library", "dashboard"]);
+function parseGdr(uri) {
+  const colon = uri.indexOf(":");
+  if (colon < 0)
+    throw new Error(
+      `Invalid GDR "${uri}": must be a URI of form "<scheme>:<...id-parts>". Known schemes: dataset, canvas, media-library, dashboard.`
+    );
+  const scheme = uri.slice(0, colon), rest = uri.slice(colon + 1);
+  if (!KNOWN_SCHEMES.has(scheme))
+    throw new Error(
+      `Invalid GDR "${uri}": unknown scheme "${scheme}". Known: dataset, canvas, media-library, dashboard.`
+    );
+  const parts = rest.split(":");
+  if (parts.some((part) => part.length === 0))
+    throw new Error(
+      `Invalid GDR "${uri}": id parts must be non-empty (no leading, trailing, or doubled ":").`
+    );
+  if (scheme === "dataset") {
+    if (parts.length !== 3)
+      throw new Error(
+        `Invalid GDR "${uri}": dataset scheme requires <projectId>:<dataset>:<documentId> (3 parts after scheme); got ${parts.length}.`
+      );
+    return {
+      scheme: "dataset",
+      projectId: parts[0],
+      dataset: parts[1],
+      documentId: parts[2]
+    };
+  }
+  if (parts.length !== 2)
+    throw new Error(
+      `Invalid GDR "${uri}": ${scheme} scheme requires <resourceId>:<documentId> (2 parts after scheme); got ${parts.length}.`
+    );
+  return {
+    scheme,
+    resourceId: parts[0],
+    documentId: parts[1]
+  };
+}
+function gdrUri(parts) {
+  return parts.scheme === "dataset" ? `dataset:${parts.projectId}:${parts.dataset}:${parts.documentId}` : `${parts.scheme}:${parts.resourceId}:${parts.documentId}`;
+}
+function extractDocumentId(gdrUriString) {
+  return parseGdr(gdrUriString).documentId;
+}
+function refDataset(projectId, dataset, documentId, type) {
+  return { id: gdrUri({ scheme: "dataset", projectId, dataset, documentId }), type };
+}
+function refCanvas(resourceId, documentId, type) {
+  return { id: gdrUri({ scheme: "canvas", resourceId, documentId }), type };
+}
+function refMediaLibrary(resourceId, documentId, type) {
+  return { id: gdrUri({ scheme: "media-library", resourceId, documentId }), type };
+}
+function refDashboard(resourceId, documentId, type) {
+  return { id: gdrUri({ scheme: "dashboard", resourceId, documentId }), type };
+}
+function gdrFromResource(res, documentId) {
+  if (res.type === "dataset") {
+    const dot = res.id.indexOf(".");
+    if (dot < 0)
+      throw new Error(`Invalid dataset resource id "${res.id}": expected "<projectId>.<dataset>".`);
+    const projectId = res.id.slice(0, dot), dataset = res.id.slice(dot + 1);
+    return gdrUri({ scheme: "dataset", projectId, dataset, documentId });
+  }
+  return gdrUri({ scheme: res.type, resourceId: res.id, documentId });
+}
+function isGdrUri(value) {
+  if (typeof value != "string") return !1;
+  try {
+    return parseGdr(value), !0;
+  } catch {
+    return !1;
+  }
+}
+function gdrRef(res, documentId, type) {
+  return { id: gdrFromResource(res, documentId), type };
+}
+function isGdr(value) {
+  return typeof value == "object" && value !== null && typeof value.id == "string" && typeof value.type == "string";
+}
+function buildParams(instance, extra) {
+  return {
+    self: gdrFromResource(instance.workflowResource, instance._id),
+    state: stateMap(instance.state ?? []),
+    parent: instance.ancestors.at(-1)?.id ?? null,
+    ancestors: instance.ancestors.map((a) => a.id),
+    /** Current stage id — bind for filters that scope to the current stage. */
+    stage: instance.currentStageId,
+    now: (/* @__PURE__ */ new Date()).toISOString(),
+    ...extra
+  };
+}
+function stateMap(slots) {
+  const out = {};
+  for (const s of slots) out[s.id] = s;
+  return out;
+}
+function paramsForLake(params) {
+  return {
+    ...params,
+    self: typeof params.self == "string" ? bareId(params.self) : params.self,
+    parent: typeof params.parent == "string" ? bareId(params.parent) : params.parent,
+    ancestors: Array.isArray(params.ancestors) ? params.ancestors.map((a) => typeof a == "string" ? bareId(a) : a) : params.ancestors,
+    state: stripStateForLake(params.state)
+  };
+}
+function stripStateForLake(value) {
+  if (value == null) return value;
+  if (typeof value == "string") return bareId(value);
+  if (Array.isArray(value)) return value.map(stripStateForLake);
+  if (typeof value == "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value))
+      out[k] = stripStateForLake(v);
+    return out;
+  }
+  return 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);
+}
+async function evaluateFilter(args) {
+  const { filter, definition, snapshot, params } = args;
+  if (filter === void 0) return !0;
+  if (typeof filter == "string")
+    return runGroqAgainstSnapshot(filter, params, snapshot);
+  const predicate = (definition.predicates ?? []).find((p) => p.id === filter.ref);
+  if (predicate === void 0)
+    throw new Error(`Unknown predicate ref: ${filter.ref}`);
+  validatePredicateArgs(predicate, filter.args ?? {});
+  const merged = { ...params, ...filter.args };
+  return runGroqAgainstSnapshot(predicate.groq, merged, snapshot);
+}
+async function runGroqAgainstSnapshot(groq, params, snapshot) {
+  if (!groq.includes("*")) {
+    const tree2 = parse(groq, { params });
+    return !!await (await evaluate(tree2, { params })).get();
+  }
+  const tree = parse(groq, { params });
+  return !!await (await evaluate(tree, { dataset: snapshot.docs, params })).get();
+}
+function validatePredicateArgs(predicate, args) {
+  for (const param of predicate.params ?? [])
+    validatePredicateParam(predicate.id, param, args);
+}
+function validatePredicateParam(predicateId, param, args) {
+  if (!(param.id in args))
+    throw new Error(`Predicate "${predicateId}" requires param "${param.id}"`);
+  const value = args[param.id];
+  if (!matchesParamType(param.type, value))
+    throw new Error(
+      `Predicate "${predicateId}" param "${param.id}" must be of type ${param.type}; got ${describeValue(value)}`
+    );
+  if (param.enum && !param.enum.includes(value))
+    throw new Error(
+      `Predicate "${predicateId}" param "${param.id}" must be one of ${param.enum.join(", ")}; got "${String(value)}"`
+    );
+}
+function matchesParamType(type, value) {
+  switch (type) {
+    case "string":
+      return typeof value == "string";
+    case "number":
+      return typeof value == "number";
+    case "boolean":
+      return typeof value == "boolean";
+    case "string[]":
+      return Array.isArray(value) && value.every((v) => typeof v == "string");
+    case "reference":
+      return isGdr(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);
+  }
+  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((v) => rewriteRefsRecursive(v, resource));
+  if (value === null || typeof value != "object") return value;
+  const obj = value, out = {};
+  for (const [k, v] of Object.entries(obj))
+    k === "_ref" && typeof v == "string" ? out[k] = v.includes(":") ? v : gdrFromResource(resource, v) : out[k] = rewriteRefsRecursive(v, resource);
+  return out;
+}
+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));
+  };
+  loaded.push({ doc: instance, resource: instance.workflowResource }), visited.add(gdrFromResource(instance.workflowResource, instance._id));
+  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);
+  }
+  return buildSnapshot({ docs: loaded });
+}
+async function loadByGdr(defaultClient, clientForGdr, defaultResource, uri) {
+  let parsed;
+  try {
+    parsed = parseGdr(uri);
+  } catch {
+    const doc2 = await defaultClient.getDocument(uri);
+    return doc2 ? { doc: doc2, resource: defaultResource } : null;
+  }
+  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 ?? "" };
+}
+function collectSlotDocUris(resolvedStateSlots) {
+  return Array.isArray(resolvedStateSlots) ? resolvedStateSlots.flatMap(slotDocUris) : [];
+}
+function slotDocUris(slot) {
+  if (!slot || typeof slot != "object") return [];
+  const s = slot;
+  if (s._type === "workflow.state.doc.ref") {
+    const v = s.value, id = refId(v);
+    return id !== void 0 ? [id] : [];
+  }
+  if (s._type === "workflow.state.doc.refs") {
+    const v = s.value;
+    return Array.isArray(v) ? v.map(refId).filter((id) => id !== void 0) : [];
+  }
+  return [];
+}
+function refId(ref) {
+  return ref && typeof ref.id == "string" ? ref.id : void 0;
+}
+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;
+}
+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 = z.object({
+  id: z.string().refine((s) => isGdrUri(s), { message: "must be a GDR URI" }),
+  type: z.string().min(1)
+}).passthrough(), ReleaseRefShape = z.object({
+  id: z.string().refine((s) => isGdrUri(s), { message: "must be a GDR URI" }),
+  type: z.literal("system.release"),
+  releaseName: z.string().min(1)
+}).passthrough(), ActorShape = z.object({
+  kind: z.enum(["user", "ai", "system"]),
+  id: z.string().min(1),
+  roles: z.array(z.string()).optional(),
+  onBehalfOf: z.string().optional()
+}).passthrough(), AssigneeShape = z.union([
+  z.object({ kind: z.literal("user"), id: z.string().min(1) }).passthrough(),
+  z.object({ kind: z.literal("role"), role: z.string().min(1) }).passthrough()
+]), ChecklistItemShape = z.object({
+  label: z.string().min(1),
+  done: z.boolean(),
+  doneBy: z.string().optional(),
+  doneAt: z.string().optional(),
+  _key: z.string().min(1).optional()
+}).passthrough(), NoteItemShape = z.object({
+  _key: z.string().min(1).optional()
+}).passthrough().refine((v) => typeof v == "object" && v !== null && !Array.isArray(v), {
+  message: "must be an object"
+}), NullableString = z.union([z.null(), z.string()]), NullableNumber = z.union([z.null(), z.number()]), NullableBoolean = z.union([z.null(), z.boolean()]), NullableDateTime = z.union([
+  z.null(),
+  z.string().refine((s) => !Number.isNaN(Date.parse(s)), {
+    message: "must be an ISO-8601 datetime string"
+  })
+]), NullableUrl = NullableString, valueSchemas = {
+  "workflow.state.doc.ref": z.union([z.null(), GdrShape]),
+  "workflow.state.doc.refs": z.array(GdrShape),
+  "workflow.state.release.ref": z.union([z.null(), ReleaseRefShape]),
+  "workflow.state.query": z.any(),
+  "workflow.state.value.string": NullableString,
+  "workflow.state.value.url": NullableUrl,
+  "workflow.state.value.number": NullableNumber,
+  "workflow.state.value.boolean": NullableBoolean,
+  "workflow.state.value.dateTime": NullableDateTime,
+  "workflow.state.value.actor": z.union([z.null(), ActorShape]),
+  "workflow.state.checklist": z.array(ChecklistItemShape),
+  "workflow.state.notes": z.array(NoteItemShape),
+  "workflow.state.assignees": z.array(AssigneeShape)
+}, itemSchemas = {
+  "workflow.state.doc.refs": GdrShape,
+  "workflow.state.checklist": ChecklistItemShape,
+  "workflow.state.notes": NoteItemShape,
+  "workflow.state.assignees": AssigneeShape
+};
+function isAppendable(slotType) {
+  return slotType in itemSchemas;
+}
+function validateSlotValue(args) {
+  const schema = valueSchemas[args.slotType];
+  if (schema === void 0)
+    throw new SlotValueShapeError({
+      slotType: args.slotType,
+      slotId: args.slotId,
+      issues: [`unknown slot type ${args.slotType}`],
+      mode: "value"
+    });
+  const result = schema.safeParse(args.value);
+  if (!result.success)
+    throw new SlotValueShapeError({
+      slotType: args.slotType,
+      slotId: args.slotId,
+      issues: formatIssues(result.error.issues),
+      mode: "value"
+    });
+}
+function validateSlotAppendItem(args) {
+  if (!isAppendable(args.slotType))
+    throw new SlotValueShapeError({
+      slotType: args.slotType,
+      slotId: args.slotId,
+      issues: [`slot type ${args.slotType} does not support append`],
+      mode: "item"
+    });
+  const result = itemSchemas[args.slotType].safeParse(args.item);
+  if (!result.success)
+    throw new SlotValueShapeError({
+      slotType: args.slotType,
+      slotId: args.slotId,
+      issues: formatIssues(result.error.issues),
+      mode: "item"
+    });
+}
+function formatIssues(issues) {
+  return issues.map((i) => `${i.path.length > 0 ? `at ${i.path.join(".")}: ` : ""}${i.message}`);
+}
+function derivePerspectiveFromState(slots) {
+  if (slots !== void 0) {
+    for (const slot of slots)
+      if (slot._type === "workflow.state.release.ref" && slot.value !== null) {
+        const releaseName = slot.value.releaseName;
+        if (typeof releaseName == "string" && releaseName.length > 0)
+          return [releaseName];
+      }
+  }
+}
+async function resolveDeclaredState(args) {
+  const { slotDefs, initialState, ctx, randomKey: randomKey2 } = args;
+  if (slotDefs === void 0 || slotDefs.length === 0) return [];
+  const out = [];
+  for (const slot of slotDefs) {
+    const scopedCtx = { ...ctx, resolvedState: out };
+    out.push(await resolveOneSlot(slot, initialState, scopedCtx, randomKey2));
+  }
+  return out;
+}
+const ARRAY_SLOT_TYPES = /* @__PURE__ */ new Set([
+  "workflow.state.doc.refs",
+  "workflow.state.checklist",
+  "workflow.state.notes",
+  "workflow.state.assignees"
+]);
+function defaultSlotValue(slotType) {
+  return ARRAY_SLOT_TYPES.has(slotType) ? [] : null;
+}
+function resolveInitValue(slot, initialState, defaultValue) {
+  const initMatch = initialState.find((s) => s.id === slot.id && s.type === slot.type);
+  return initMatch === void 0 ? defaultValue : (assertInitValueShape(slot, initMatch.value), initMatch.value);
+}
+function resolveStateReadValue(source, ctx, defaultValue) {
+  const target = (source.scope === "workflow" ? ctx.workflowState ?? [] : ctx.resolvedState ?? []).find((s) => s.id === source.slotId), targetValue = target === void 0 ? void 0 : target.value;
+  return (source.path !== void 0 ? getPath(targetValue, source.path) : targetValue) ?? defaultValue;
+}
+async function resolveQueryValue(slot, source, ctx, client, defaultValue) {
+  const params = paramsForLake({
+    self: ctx.selfId ?? null,
+    state: stateMapFromResolved(ctx.resolvedState ?? []),
+    stage: ctx.stageId ?? null,
+    task: ctx.taskId ?? null,
+    now: (/* @__PURE__ */ new Date()).toISOString(),
+    engineTags: ctx.tags ?? []
+  });
+  try {
+    const fetchOptions = ctx.perspective !== void 0 ? { perspective: ctx.perspective } : void 0, result = await client.fetch(source.query, params, fetchOptions);
+    return normalizeQueryResult(slot.type, result, ctx.workflowResource) ?? defaultValue;
+  } catch (err) {
+    throw new Error(
+      `Failed to resolve query slot "${slot.id}" (${slot.type}): ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
+    );
+  }
+}
+async function resolveSlotValue(slot, initialState, ctx, defaultValue) {
+  const source = slot.source;
+  return source.kind === "init" ? resolveInitValue(slot, initialState, defaultValue) : source.kind === "literal" ? source.value ?? defaultValue : source.kind === "stateRead" ? resolveStateReadValue(source, ctx, defaultValue) : source.kind === "query" && ctx.client !== void 0 ? resolveQueryValue(slot, source, ctx, ctx.client, defaultValue) : defaultValue;
+}
+function buildResolvedSlot(slot, value, _key) {
+  const titleProp = slot.title !== void 0 ? { title: slot.title } : {}, descriptionProp = slot.description !== void 0 ? { description: slot.description } : {};
+  return slot.type === "workflow.state.query" ? {
+    _key,
+    _type: "workflow.state.query",
+    id: slot.id,
+    ...titleProp,
+    ...descriptionProp,
+    value,
+    resolvedAt: (/* @__PURE__ */ new Date()).toISOString()
+  } : {
+    _key,
+    _type: slot.type,
+    id: slot.id,
+    ...titleProp,
+    ...descriptionProp,
+    value
+  };
+}
+async function resolveOneSlot(slot, initialState, ctx, randomKey2) {
+  const defaultValue = defaultSlotValue(slot.type), value = await resolveSlotValue(slot, initialState, ctx, defaultValue);
+  return validateSlotValue({ slotType: slot.type, slotId: slot.id, value }), buildResolvedSlot(slot, value, randomKey2());
+}
+function stateMapFromResolved(slots) {
+  const out = {};
+  for (const s of slots) out[s.id] = s;
+  return out;
+}
+function assertInitValueShape(slot, value) {
+  if (slot.type === "workflow.state.doc.ref") {
+    assertGdrShape(value, `state slot "${slot.id}" (workflow.state.doc.ref)`);
+    return;
+  }
+  if (slot.type === "workflow.state.release.ref") {
+    assertGdrShape(value, `state slot "${slot.id}" (workflow.state.release.ref)`);
+    const v = value;
+    if (typeof v.releaseName != "string" || v.releaseName.length === 0)
+      throw new Error(
+        `Invalid init value for state slot "${slot.id}" (workflow.state.release.ref): \`releaseName\` must be a non-empty string. Got ${JSON.stringify(v.releaseName)}.`
+      );
+    return;
+  }
+  if (slot.type === "workflow.state.doc.refs") {
+    if (!Array.isArray(value))
+      throw new Error(
+        `Invalid init value for state slot "${slot.id}" (workflow.state.doc.refs): expected an array of GDRs, got ${typeof value}.`
+      );
+    for (const [i, item] of value.entries())
+      assertGdrShape(item, `state slot "${slot.id}" (workflow.state.doc.refs) item [${i}]`);
+  }
+}
+function assertGdrShape(value, context) {
+  if (typeof value != "object" || value === null)
+    throw new Error(
+      `Invalid GDR for ${context}: expected { id: "<scheme>:...", type: "<schema>" }, got ${typeof value}.`
+    );
+  const v = value;
+  if (typeof v.id != "string" || !isGdrUri(v.id))
+    throw new Error(
+      `Invalid GDR for ${context}: \`id\` must be a GDR URI ("<scheme>:<...id-parts>" with scheme dataset|canvas|media-library|dashboard). Got ${JSON.stringify(v.id)}. Construct via \`gdrFromResource\` / \`refDataset\` / \`refCanvas\` etc. \u2014 bare document ids are not accepted.`
+    );
+  if (typeof v.type != "string" || v.type.length === 0)
+    throw new Error(
+      `Invalid GDR for ${context}: \`type\` (schema name) must be a non-empty string. Got ${JSON.stringify(v.type)}.`
+    );
+}
+function normalizeQueryResult(slotType, raw, workflowResource) {
+  return raw == null ? raw : slotType === "workflow.state.doc.ref" ? coerceToGdr(raw, workflowResource) : slotType === "workflow.state.doc.refs" ? Array.isArray(raw) ? raw.map((item) => coerceToGdr(item, workflowResource)).filter((v) => v !== null) : [] : raw;
+}
+function toGdrUri(docId, workflowResource) {
+  return isGdrUri(docId) ? docId : gdrFromResource(workflowResource, docId);
+}
+function coerceGdrShape(raw, workflowResource) {
+  if (!("id" in raw) || !("type" in raw)) return null;
+  const r = raw;
+  return typeof r.id != "string" || typeof r.type != "string" ? null : isGdrUri(r.id) ? { id: r.id, type: r.type } : workflowResource ? { id: gdrFromResource(workflowResource, r.id), type: r.type } : null;
+}
+function coerceRefEnvelope(raw, workflowResource) {
+  if (!("_ref" in raw)) return null;
+  const r = raw;
+  return typeof r._ref != "string" || !workflowResource ? null : { id: toGdrUri(r._ref, workflowResource), type: "document" };
+}
+function coerceToGdr(raw, workflowResource) {
+  return raw == null ? null : typeof raw == "object" ? coerceGdrShape(raw, workflowResource) ?? coerceRefEnvelope(raw, workflowResource) : typeof raw == "string" && workflowResource ? { id: toGdrUri(raw, workflowResource), type: "document" } : null;
+}
+function gdrToBareId(uri) {
+  return uri.includes(":") ? extractDocumentId(uri) : uri;
+}
+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), snapshot = await hydrateSnapshot({ client, clientForGdr, instance, definition });
+  return { client, clientForGdr, instance, definition, snapshot };
+}
+function ctxEvaluateFilter(ctx, filter) {
+  return evaluateFilter({
+    filter,
+    definition: ctx.definition,
+    snapshot: ctx.snapshot,
+    params: buildParams(ctx.instance)
+  });
+}
+async function buildEngineContext(args) {
+  const { client, clientForGdr, instance, definition } = args;
+  return {
+    client,
+    clientForGdr,
+    instance,
+    definition,
+    snapshot: await hydrateSnapshot({ client, clientForGdr, instance, definition })
+  };
+}
+function findStage(definition, stageId) {
+  const stage = definition.stages.find((s) => s.id === stageId);
+  if (stage === void 0)
+    throw new Error(`Stage "${stageId}" not found in definition ${definition.workflowId}`);
+  return stage;
+}
+async function resolveStageStateSlots(args) {
+  const { client, instance, stage, initialState } = args;
+  return resolveDeclaredState({
+    slotDefs: stage.state,
+    initialState: initialState ?? [],
+    ctx: {
+      client,
+      selfId: instance._id,
+      tags: instance.tags ?? [],
+      stageId: stage.id,
+      workflowResource: instance.workflowResource,
+      // Allow stage-scope slots' `source: { kind: "stateRead", scope:
+      // "workflow", ... }` to see the already-resolved workflow-scope
+      // state.
+      workflowState: instance.state ?? [],
+      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
+    },
+    randomKey
+  });
+}
+async function resolveTaskStateSlots(args) {
+  const { client, instance, stage, task } = args;
+  return resolveDeclaredState({
+    slotDefs: task.state,
+    initialState: [],
+    ctx: {
+      client,
+      selfId: instance._id,
+      tags: instance.tags ?? [],
+      stageId: stage.id,
+      workflowResource: instance.workflowResource,
+      taskId: task.id,
+      workflowState: instance.state ?? [],
+      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
+    },
+    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 resolveSource(src, ctx) {
+  switch (src.source) {
+    case "literal":
+      return src.value;
+    case "param":
+      return ctx.params?.[src.paramId];
+    case "actor":
+      return ctx.actor;
+    case "now":
+      return (/* @__PURE__ */ new Date()).toISOString();
+    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);
+  }
+}
+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, params, actor } = args, resolved = {};
+  if (bindings) {
+    const ctx = {
+      instance,
+      ...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 buildInstanceBase(args) {
+  const { id, now, actor, perspective } = 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
+  };
+}
+function lakeGuardId(args) {
+  return `temp.system.guard.${args.instanceDocId}.${args.stageId}.${args.index}`;
+}
+function compileGuard(args) {
+  return {
+    _id: args.id,
+    _type: "temp.system.guard",
+    resourceType: args.resourceType,
+    resourceId: args.resourceId,
+    owner: args.owner,
+    ...args.name !== void 0 ? { name: args.name } : {},
+    ...args.description !== void 0 ? { description: args.description } : {},
+    match: args.match,
+    predicate: args.predicate,
+    metadata: args.metadata
+  };
+}
+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 !0;
+}
+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;
+  }
+}
+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 resourceOf(p) {
+  return p.scheme === "dataset" ? { type: "dataset", id: `${p.projectId}.${p.dataset}` } : { type: p.scheme, id: p.resourceId ?? "" };
+}
+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 v = value;
+    if (typeof v.id == "string" && isGdrUri(v.id))
+      return typeof v.type == "string" ? { parsed: parseGdr(v.id), type: v.type } : { parsed: parseGdr(v.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;
+}
+const GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
+function resolveGuard(guard, index, instance, stageId) {
+  const ctx = { instance, stageId }, 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,
+    ...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) {
+  const existing = await client.getDocument(doc._id), set = {
+    resourceType: doc.resourceType,
+    resourceId: doc.resourceId,
+    owner: doc.owner,
+    match: doc.match,
+    predicate: doc.predicate,
+    metadata: doc.metadata
+  };
+  doc.name !== void 0 && (set.name = doc.name), doc.description !== void 0 && (set.description = doc.description), existing ? await client.patch(doc._id).set(set).commit() : await client.create(doc);
+}
+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);
+    resolved !== null && out.push({ client: args.clientForGdr(resolved.routeGdr), doc: resolved.doc });
+  }
+  return out;
+}
+async function deployStageGuards(args) {
+  for (const { client, doc } of resolvedStageGuards(args))
+    await upsertGuard(client, doc);
+}
+async function retractStageGuards(args) {
+  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 reconcileStageGuards(args) {
+  const { client, clientForGdr, instance, definition, exitedStageId, enteredStageId } = args;
+  exitedStageId !== void 0 && await retractStageGuards({
+    client,
+    clientForGdr,
+    instance,
+    definition,
+    stageId: exitedStageId
+  }), enteredStageId !== void 0 && await deployStageGuards({
+    client,
+    clientForGdr,
+    instance,
+    definition,
+    stageId: enteredStageId
+  });
+}
+async function discoverItems(args) {
+  const { client, groq, params, perspective } = args, fetchOptions = perspective !== void 0 ? { perspective } : void 0;
+  return client.fetch(groq, paramsForLake(params), fetchOptions);
+}
+function clientForDiscovery(defaultClient, clientForGdr, subjectGdrUri) {
+  if (!subjectGdrUri || !subjectGdrUri.includes(":")) return defaultClient;
+  try {
+    return clientForGdr(parseGdr(subjectGdrUri));
+  } catch {
+    return defaultClient;
+  }
+}
+const MAX_SPAWN_DEPTH = 6;
+async function spawnChildren(ctx, mutation, task, spawn, actor) {
+  if (ctx.instance.ancestors.length + 1 > MAX_SPAWN_DEPTH) {
+    const chain = [
+      ...ctx.instance.ancestors.map((a) => a.id),
+      gdrFromResource(ctx.instance.workflowResource, ctx.instance._id)
+    ].join(" \u2192 ");
+    throw new Error(
+      `Spawn depth limit (${MAX_SPAWN_DEPTH}) exceeded on task "${task.id}" of ${ctx.instance._id}. Ancestor chain: ${chain}`
+    );
+  }
+  const rows = await resolveSpawnRows(ctx, spawn), refs = [];
+  for (const row of rows) {
+    const projected = projectSpawnRow(ctx.instance, spawn, row), { ref, body } = await prepareChildInstance({
+      client: ctx.client,
+      parent: ctx.instance,
+      task,
+      spawn,
+      initialState: projected.initialState,
+      effectsContext: projected.effectsContext,
+      actor
+    });
+    refs.push(ref), mutation.pendingCreates.push(body);
+  }
+  return refs;
+}
+async function resolveSpawnRows(ctx, spawn) {
+  const params = buildParams(ctx.instance), groq = spawn.forEach.groq;
+  let value;
+  if (groq.includes("*")) {
+    const routingUri = firstDocRefGdrUri(ctx.instance.state), client = clientForDiscovery(ctx.client, ctx.clientForGdr, routingUri);
+    value = await discoverItems({
+      client,
+      groq,
+      params,
+      ...ctx.instance.perspective !== void 0 ? { perspective: ctx.instance.perspective } : {}
+    });
+  } else {
+    const tree = parse(groq, { params });
+    value = await (await evaluate(tree, { dataset: [ctx.instance], params, root: ctx.instance })).get();
+  }
+  return Array.isArray(value) ? value : value == null ? [] : [value];
+}
+function firstDocRefGdrUri(slots) {
+  if (slots) {
+    for (const s of slots)
+      if (s._type === "workflow.state.doc.ref" && s.value !== null) return s.value.id;
+  }
+}
+function resolveSpawnSource(source, parent, row) {
+  switch (source.source) {
+    case "literal":
+      return source.value;
+    case "row":
+      return source.path !== void 0 ? getPath(row, source.path) : row;
+    case "parentState": {
+      const slot = parent.state?.find((s) => s.id === source.slotId);
+      return slot === void 0 ? null : source.path !== void 0 ? getPath(slot, source.path) : slot;
+    }
+    case "self":
+      return gdrFromResource(parent.workflowResource, parent._id);
+    case "stageId":
+      return parent.currentStageId;
+    case "now":
+      return (/* @__PURE__ */ new Date()).toISOString();
+    case "object": {
+      const out = {};
+      for (const [k, v] of Object.entries(source.fields))
+        out[k] = resolveSpawnSource(v, parent, row);
+      return out;
+    }
+    case "actor":
+    case "param":
+    case "stateRead":
+    case "effectOutput":
+      return null;
+  }
+}
+function projectSpawnRow(parent, spawn, row) {
+  const initialState = [];
+  for (const entry of spawn.forEach.as.initialState ?? []) {
+    const raw = resolveSpawnSource(entry.value, parent, row), value = canonicaliseSpawnValue(entry.type, raw, parent.workflowResource);
+    initialState.push({
+      type: entry.type,
+      id: entry.id,
+      value
+    });
+  }
+  const effectsContext = {};
+  for (const [k, src] of Object.entries(spawn.forEach.as.effectsContext ?? {})) {
+    const v = resolveSpawnSource(src, parent, row);
+    v != null && (typeof v == "string" || typeof v == "number" || typeof v == "boolean" || typeof v == "object" && "id" in v && "type" in v) && (effectsContext[k] = v);
+  }
+  return { initialState, effectsContext };
+}
+function canonicaliseSpawnValue(slotType, value, workflowResource) {
+  return slotType === "workflow.state.doc.ref" ? coerceSpawnGdr(value, workflowResource) : slotType === "workflow.state.doc.refs" && Array.isArray(value) ? value.map((v) => coerceSpawnGdr(v, workflowResource)).filter((v) => v !== null) : value;
+}
+function coerceSpawnGdr(raw, workflowResource) {
+  const toUri = (id) => isGdrUri(id) ? id : gdrFromResource(workflowResource, id);
+  if (raw == null) return null;
+  if (typeof raw == "object" && "id" in raw && "type" in raw) {
+    const r = raw;
+    if (typeof r.id == "string" && typeof r.type == "string")
+      return { id: toUri(r.id), type: r.type };
+  }
+  if (typeof raw == "object" && "_ref" in raw) {
+    const r = raw;
+    if (typeof r._ref == "string") return { id: toUri(r._ref), type: "document" };
+  }
+  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;
+}
+async function prepareChildInstance(args) {
+  const { client, parent, task, spawn, initialState, effectsContext, actor } = args, definition = await resolveLogicalDefinition(client, spawn.definitionRef, parent.tags ?? []);
+  if (definition === null) {
+    const versionLabel = spawn.definitionRef.version === void 0 || spawn.definitionRef.version === "latest" ? "latest" : `v${spawn.definitionRef.version}`;
+    throw new Error(
+      `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 = [
+    ...parent.ancestors,
+    {
+      id: gdrFromResource(parent.workflowResource, parent._id),
+      type: "workflow.instance"
+    }
+  ], inheritedPerspective = parent.perspective, childState = await resolveDeclaredState({
+    slotDefs: definition.state,
+    initialState,
+    ctx: {
+      client,
+      selfId: childDocId,
+      tags: childTags,
+      workflowResource,
+      ...inheritedPerspective !== void 0 ? { perspective: inheritedPerspective } : {}
+    },
+    randomKey
+  }), childPerspective = derivePerspectiveFromState(childState) ?? inheritedPerspective, effectsContextEntries = Object.entries(effectsContext).map(
+    ([key, value]) => {
+      if (typeof value == "object" && value !== null && "id" in value && "type" in value) {
+        if (!isGdrUri(value.id))
+          throw new Error(
+            `spawn.forEach.as.effectsContext["${key}"]: GDR id must be a "<scheme>:..." URI, got ${JSON.stringify(value.id)}.`
+          );
+        return effectsContextEntry(key, { id: value.id, type: value.type });
+      }
+      return effectsContextEntry(key, value);
+    }
+  ), base = buildInstanceBase({
+    id: childDocId,
+    now: (/* @__PURE__ */ new Date()).toISOString(),
+    tags: childTags,
+    workflowResource,
+    workflowId: definition.workflowId,
+    pinnedVersion: definition.version,
+    definition,
+    state: childState,
+    effectsContext: effectsContextEntries,
+    ancestors,
+    perspective: childPerspective,
+    initialStageId: definition.initialStageId,
+    actor
+  });
+  return { ref: childRef, body: base };
+}
+async function checkSpawnCompletion(client, entry, spawn) {
+  const refs = entry.spawnedInstances ?? [];
+  if (refs.length === 0) {
+    const policy2 = spawn.completionPolicy ?? { kind: "all" };
+    return policy2.kind === "all" || policy2.kind === "count" && policy2.n === 0;
+  }
+  const ids = refs.map((r) => r.id.includes(":") ? gdrToBareId(r.id) : r.id), children = await client.fetch("*[_id in $ids]{_id, currentStageId, definitionSnapshot}", { ids });
+  let terminalCount = 0;
+  for (const child of children)
+    JSON.parse(child.definitionSnapshot).stages.find((s) => s.id === child.currentStageId)?.kind === "terminal" && terminalCount++;
+  const policy = spawn.completionPolicy ?? { kind: "all" };
+  switch (policy.kind) {
+    case "all":
+      return terminalCount === refs.length;
+    case "any":
+      return terminalCount >= 1;
+    case "count":
+      return terminalCount >= policy.n;
+  }
+}
+async function invokeTask(args) {
+  const { client, instanceId, taskId, options } = args, ctx = await loadContext(client, instanceId);
+  return commitInvoke(ctx, taskId, options?.actor);
+}
+async function commitInvoke(ctx, taskId, actor) {
+  const { task } = findTaskInCurrentStage(ctx, taskId), entry = findCurrentTasks(ctx.instance).find((t) => t.id === taskId);
+  if (entry === void 0)
+    throw new Error(`Task "${taskId}" has no status entry on instance ${ctx.instance._id}`);
+  if (entry.status !== "pending")
+    return { invoked: !1, taskId };
+  const mutation = startMutation(ctx.instance), mutEntry = requireMutationTaskEntry(mutation, taskId);
+  return await activateTask(ctx, mutation, task, mutEntry, actor), await persist(ctx, mutation), { invoked: !0, taskId };
+}
+async function autoResolveOnActivate(ctx, mutation, task, entry) {
+  const checks = [
+    { filter: task.failWhen, outcome: "failed", systemId: "engine.failWhen" },
+    { filter: task.completeWhen, outcome: "done", systemId: "engine.completeWhen" }
+  ];
+  for (const { filter, outcome, systemId } of checks) {
+    if (filter === void 0 || !await ctxEvaluateFilter(ctx, filter)) continue;
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return entry.status = outcome, entry.completedAt = completedAt, entry.completedBy = systemId, mutation.history.push(
+      taskStatusChangedEntry({
+        stageId: mutation.currentStageId,
+        taskId: task.id,
+        from: "active",
+        to: outcome,
+        actor: { kind: "system", id: systemId },
+        at: completedAt
+      })
+    ), !0;
+  }
+  return !1;
+}
+async function activateTask(ctx, mutation, task, entry, actor) {
+  if (entry.status = "active", entry.startedAt = (/* @__PURE__ */ new Date()).toISOString(), task.state !== void 0 && task.state.length > 0) {
+    const stage = findStage(ctx.definition, mutation.currentStageId);
+    entry.state = await resolveTaskStateSlots({
+      client: ctx.client,
+      instance: ctx.instance,
+      stage,
+      task
+    });
+  }
+  if (!await autoResolveOnActivate(ctx, mutation, task, entry) && (mutation.history.push({
+    _key: randomKey(),
+    _type: "workflow.history.taskActivated",
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    stageId: mutation.currentStageId,
+    taskId: task.id,
+    ...actor !== void 0 ? { actor } : {}
+  }), await queueEffects(
+    ctx,
+    mutation,
+    task.effects,
+    {
+      kind: "taskInvoke",
+      id: task.id
+    },
+    actor
+  ), task.spawns !== void 0)) {
+    const refs = await spawnChildren(ctx, mutation, task, task.spawns, actor);
+    entry.spawnedInstances = refs;
+    for (const ref of refs)
+      mutation.history.push({
+        _key: randomKey(),
+        _type: "workflow.history.spawned",
+        at: (/* @__PURE__ */ new Date()).toISOString(),
+        taskId: task.id,
+        instanceRef: ref
+      });
+    if (await checkSpawnCompletion(ctx.client, entry, task.spawns)) {
+      const previousStatus = entry.status;
+      entry.status = "done", entry.completedAt = (/* @__PURE__ */ new Date()).toISOString(), mutation.history.push(
+        taskStatusChangedEntry({
+          stageId: mutation.currentStageId,
+          taskId: task.id,
+          from: previousStatus,
+          to: "done",
+          ...actor !== void 0 ? { actor } : {}
+        })
+      );
+    }
+  }
+}
+async function buildStageTasks(ctx, stage) {
+  const entries = [];
+  for (const task of stage.tasks ?? []) {
+    const inScope = await ctxEvaluateFilter(ctx, task.filter);
+    entries.push({
+      _key: randomKey(),
+      id: task.id,
+      status: inScope ? "pending" : "skipped",
+      ...task.filter !== void 0 ? {
+        filterEvaluation: {
+          at: (/* @__PURE__ */ new Date()).toISOString(),
+          truthy: inScope
+        }
+      } : {}
+    });
+  }
+  return entries;
+}
+function activatesOnStageEnter(task) {
+  return task.invokeOn === "stageEnter" || task.spawns !== void 0 || task.completeWhen !== void 0 || task.failWhen !== void 0;
+}
+async function setStage(args) {
+  const { client, instanceId, targetStageId, reason, options } = args, ctx = await loadContext(client, instanceId);
+  return commitSetStage(ctx, targetStageId, reason, options?.actor);
+}
+async function enterStage(ctx, mutation, nextStage, actor, at) {
+  mutation.currentStageId = nextStage.id;
+  const nextStageEntry = {
+    _key: randomKey(),
+    id: nextStage.id,
+    enteredAt: at,
+    state: await resolveStageStateSlots({
+      client: ctx.client,
+      instance: ctx.instance,
+      stage: nextStage
+    }),
+    tasks: await buildStageTasks(ctx, nextStage)
+  };
+  mutation.stages.push(nextStageEntry), await queueEffects(
+    ctx,
+    mutation,
+    nextStage.onEnter,
+    { kind: "stageEnter", id: nextStage.id },
+    actor
+  );
+  for (const task of nextStage.tasks ?? []) {
+    if (!activatesOnStageEnter(task)) continue;
+    const entry = nextStageEntry.tasks.find((t) => t.id === task.id);
+    entry && entry.status === "pending" && await activateTask(ctx, mutation, task, entry, actor);
+  }
+  nextStage.kind === "terminal" && (mutation.completedAt = at);
+}
+async function beginStageMove(ctx, currentStage, actor) {
+  const mutation = startMutation(ctx.instance), at = (/* @__PURE__ */ new Date()).toISOString();
+  return await queueEffects(
+    ctx,
+    mutation,
+    currentStage.onExit,
+    { kind: "stageExit", id: currentStage.id },
+    actor
+  ), { mutation, at };
+}
+async function commitSetStage(ctx, targetStageId, reason, actor) {
+  const currentStage = findStage(ctx.definition, ctx.instance.currentStageId), nextStage = findStage(ctx.definition, targetStageId);
+  if (currentStage.id === nextStage.id)
+    return { fired: !1 };
+  const { mutation, at } = await beginStageMove(ctx, currentStage, actor), transitionId = `setStage:${currentStage.id}->${nextStage.id}`;
+  mutation.history.push(
+    ...stageTransitionHistory({
+      fromStageId: currentStage.id,
+      toStageId: nextStage.id,
+      at,
+      transitionId,
+      via: "setStage",
+      ...actor !== void 0 ? { actor } : {},
+      ...reason !== void 0 ? { reason } : {}
+    })
+  );
+  const priorEntry = findOpenStageEntry(mutation);
+  return priorEntry !== void 0 && (priorEntry.exitedAt = at), await enterStage(ctx, mutation, nextStage, actor, at), await persistStageMove(ctx, mutation, currentStage.id, nextStage.id), {
+    fired: !0,
+    fromStageId: currentStage.id,
+    toStageId: nextStage.id,
+    transitionId
+  };
+}
+async function persistStageMove(ctx, mutation, exitedStageId, enteredStageId) {
+  await persist(ctx, mutation), await reconcileStageGuards({
+    client: ctx.client,
+    clientForGdr: ctx.clientForGdr,
+    instance: ctx.instance,
+    definition: ctx.definition,
+    exitedStageId,
+    enteredStageId
+  });
+}
+async function commitTransition(ctx, action, actor) {
+  const currentStage = findStage(ctx.definition, ctx.instance.currentStageId), transition = await pickTransition(ctx, currentStage);
+  if (transition === void 0)
+    return { fired: !1 };
+  const { mutation, at } = await beginStageMove(ctx, currentStage, actor);
+  await queueEffects(
+    ctx,
+    mutation,
+    transition.effects,
+    {
+      kind: "transition",
+      id: transition.id ?? `${currentStage.id}->${transition.to}`
+    },
+    actor
+  ), mutation.history.push(
+    ...stageTransitionHistory({
+      fromStageId: currentStage.id,
+      toStageId: transition.to,
+      at,
+      ...transition.id !== void 0 ? { transitionId: transition.id } : {},
+      ...actor !== void 0 ? { actor } : {}
+    })
+  );
+  const priorEntry = findOpenStageEntry(mutation);
+  priorEntry !== void 0 && (priorEntry.exitedAt = at);
+  const nextStage = findStage(ctx.definition, transition.to);
+  return await enterStage(ctx, mutation, nextStage, actor, at), await persistStageMove(ctx, mutation, currentStage.id, nextStage.id), {
+    fired: !0,
+    fromStageId: currentStage.id,
+    toStageId: transition.to,
+    ...transition.id !== void 0 ? { transitionId: transition.id } : {}
+  };
+}
+async function pickTransition(ctx, stage, action) {
+  const candidates = (stage.transitions ?? []).filter((t) => t.on === void 0);
+  for (const candidate of candidates)
+    if (await ctxEvaluateFilter(ctx, candidate.filter)) return candidate;
+}
+async function evaluateAutoTransitions(args) {
+  const { client, instanceId, options, clientForGdr } = args, ctx = await loadContext(client, instanceId, clientForGdr ? { clientForGdr } : void 0);
+  return commitTransition(ctx, void 0, options?.actor);
+}
+async function primeInitialStage(client, instanceId, actor, clientForGdr) {
+  const instance = await client.getDocument(instanceId);
+  if (!instance || instance.stages.length > 0 || instance.pendingEffects.length > 0) return;
+  const definition = JSON.parse(instance.definitionSnapshot), stage = definition.stages.find((s) => s.id === instance.currentStageId);
+  if (stage === void 0) return;
+  const snapshot = await hydrateSnapshot({
+    client,
+    clientForGdr: clientForGdr ?? (() => client),
+    instance,
+    definition
+  }), tasks = [];
+  for (const task of stage.tasks ?? []) {
+    const inScope = await evaluateFilter({
+      filter: task.filter,
+      definition,
+      snapshot,
+      params: buildParams(instance)
+    });
+    tasks.push({
+      _key: randomKey(),
+      id: task.id,
+      status: inScope ? "pending" : "skipped"
+    });
+  }
+  const initialStageEntry = {
+    _key: randomKey(),
+    id: stage.id,
+    enteredAt: (/* @__PURE__ */ new Date()).toISOString(),
+    state: await resolveStageStateSlots({ client, instance, stage }),
+    tasks
+  }, pendingEffects = [], newHistory = [...instance.history];
+  for (const effect of stage.onEnter ?? []) {
+    const params = await resolveBindings({
+      bindings: effect.bindings,
+      staticInput: effect.input,
+      instance,
+      ...actor !== void 0 ? { actor } : {}
+    }), { pending, history } = buildQueuedEffect(
+      effect,
+      { kind: "stageEnter", id: stage.id },
+      params,
+      actor
+    );
+    pendingEffects.push(pending), newHistory.push(history);
+  }
+  await client.patch(instance._id).set({
+    stages: [initialStageEntry],
+    pendingEffects,
+    history: newHistory,
+    lastChangedAt: (/* @__PURE__ */ new Date()).toISOString()
+  }).ifRevisionId(instance._rev).commit(), await deployStageGuards({
+    client,
+    clientForGdr: clientForGdr ?? (() => client),
+    instance,
+    definition,
+    stageId: stage.id
+  }), await autoActivatePrimedTasks(client, instanceId, definition, stage, actor, clientForGdr);
+}
+async function autoActivatePrimedTasks(client, instanceId, definition, stage, actor, clientForGdr) {
+  const resolvedClientForGdr = clientForGdr ?? (() => client);
+  for (const task of stage.tasks ?? []) {
+    if (!activatesOnStageEnter(task)) continue;
+    const updated = await client.getDocument(instanceId);
+    if (!updated) continue;
+    const updatedCtx = await buildEngineContext({
+      client,
+      clientForGdr: resolvedClientForGdr,
+      instance: updated,
+      definition
+    }), mutation = startMutation(updated), mutEntry = currentTasks(mutation).find((t) => t.id === task.id);
+    mutEntry && mutEntry.status === "pending" && (await activateTask(updatedCtx, mutation, task, mutEntry, actor), await persist(updatedCtx, mutation));
+  }
+}
+const CASCADE_LIMIT = 100;
+async function gatherAutoResolveCandidates(ctx, tasks) {
+  const currentTasksList = findCurrentTasks(ctx.instance), candidates = [];
+  for (const task of tasks)
+    if (currentTasksList.find((e) => e.id === task.id)?.status === "active") {
+      if (task.failWhen !== void 0 && await ctxEvaluateFilter(ctx, task.failWhen)) {
+        candidates.push({ task, outcome: "failed" });
+        continue;
+      }
+      task.completeWhen !== void 0 && await ctxEvaluateFilter(ctx, task.completeWhen) && candidates.push({ task, outcome: "done" });
+    }
+  return candidates;
+}
+async function resolveCompleteWhen(client, instanceId, clientForGdr) {
+  const ctx = await loadContext(client, instanceId, clientForGdr ? { clientForGdr } : void 0), stage = findStage(ctx.definition, ctx.instance.currentStageId), tasksWithAutoPredicate = (stage.tasks ?? []).filter(
+    (t) => t.completeWhen !== void 0 || t.failWhen !== void 0
+  );
+  if (tasksWithAutoPredicate.length === 0) return 0;
+  const candidates = await gatherAutoResolveCandidates(ctx, tasksWithAutoPredicate);
+  if (candidates.length === 0) return 0;
+  const mutation = startMutation(ctx.instance);
+  let count = 0;
+  for (const { task, outcome } of candidates) {
+    const mutEntry = currentTasks(mutation).find((t) => t.id === task.id);
+    if (mutEntry === void 0 || mutEntry.status !== "active") continue;
+    const previousStatus = mutEntry.status, actor = {
+      kind: "system",
+      id: outcome === "failed" ? "engine.failWhen" : "engine.completeWhen"
+    };
+    mutEntry.status = outcome, mutEntry.completedAt = (/* @__PURE__ */ new Date()).toISOString(), mutEntry.completedBy = actor.id, mutation.history.push(
+      taskStatusChangedEntry({
+        stageId: stage.id,
+        taskId: task.id,
+        from: previousStatus,
+        to: outcome,
+        actor
+      })
+    ), count++;
+  }
+  return count > 0 && await persist(ctx, mutation), count;
+}
+async function cascadeAutoTransitions(client, instanceId, actor, clientForGdr) {
+  let count = 0;
+  for (; ; ) {
+    if (await resolveCompleteWhen(client, instanceId, clientForGdr), !(await evaluateAutoTransitions({
+      client,
+      instanceId,
+      ...actor !== void 0 ? { options: { actor } } : {},
+      ...clientForGdr ? { clientForGdr } : {}
+    })).fired) return count;
+    if (count++, count > CASCADE_LIMIT)
+      throw new Error(
+        `Cascade did not stabilise after ${CASCADE_LIMIT} auto-transitions on ${instanceId} \u2014 possible infinite loop`
+      );
+  }
+}
+async function propagateToAncestors(client, instanceId, actor, clientForGdr) {
+  const instance = await client.getDocument(instanceId);
+  if (!instance || instance.ancestors.length === 0) return;
+  const parentRef = instance.ancestors[instance.ancestors.length - 1];
+  if (parentRef === void 0) return;
+  const parentId = gdrToBareId(parentRef.id), parent = await client.getDocument(parentId);
+  if (!parent || parent._type !== "workflow.instance" || typeof parent.definitionSnapshot != "string")
+    return;
+  const parentDefinition = JSON.parse(parent.definitionSnapshot), parentStage = parentDefinition.stages.find((s) => s.id === parent.currentStageId);
+  if (parentStage === void 0) return;
+  const parentCurrentTasks = findCurrentTasks(parent), parentTask = (parentStage.tasks ?? []).find((t) => t.spawns === void 0 ? !1 : parentCurrentTasks.find((e) => e.id === t.id)?.spawnedInstances?.some((r) => gdrToBareId(r.id) === instance._id) ?? !1);
+  if (parentTask === void 0) return;
+  const parentEntry = parentCurrentTasks.find((e) => e.id === parentTask.id);
+  if (parentEntry === void 0 || parentEntry.status === "done" || !await checkSpawnCompletion(client, parentEntry, parentTask.spawns)) return;
+  const ctx = await buildEngineContext({
+    client,
+    clientForGdr: clientForGdr ?? (() => client),
+    instance: parent,
+    definition: parentDefinition
+  }), mutation = startMutation(parent), mutEntry = currentTasks(mutation).find((e) => e.id === parentTask.id);
+  if (mutEntry === void 0) return;
+  const previousStatus = mutEntry.status;
+  mutEntry.status = "done", mutEntry.completedAt = (/* @__PURE__ */ new Date()).toISOString(), mutation.history.push(
+    taskStatusChangedEntry({
+      stageId: parentStage.id,
+      taskId: parentTask.id,
+      from: previousStatus,
+      to: "done",
+      ...actor !== void 0 ? { actor } : {}
+    })
+  ), await persist(ctx, mutation), await cascadeAutoTransitions(client, parentId, actor, clientForGdr), await propagateToAncestors(client, parentId, actor, clientForGdr);
+}
+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 ?? (/* @__PURE__ */ new Date()).toISOString(),
+    stageId: args.stageId,
+    taskId: args.taskId,
+    from: args.from,
+    to: args.to,
+    ...args.actor !== void 0 ? { actor: args.actor } : {}
+  };
+}
+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
+    }
+  ];
+}
+async function persist(ctx, mutation) {
+  const set = {
+    currentStageId: mutation.currentStageId,
+    state: mutation.state,
+    stages: mutation.stages,
+    pendingEffects: mutation.pendingEffects,
+    effectHistory: mutation.effectHistory,
+    effectsContext: mutation.effectsContext,
+    history: mutation.history,
+    lastChangedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  mutation.completedAt !== void 0 && (set.completedAt = mutation.completedAt);
+  const 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), await cascadeAutoTransitions(ctx.client, body._id, actorForPriming, ctx.clientForGdr), await propagateToAncestors(ctx.client, body._id, actorForPriming, ctx.clientForGdr);
+  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 findOpenStageEntry(host) {
+  return host.stages.find((s) => s.id === host.currentStageId && s.exitedAt === void 0);
+}
+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 currentTasks(mutation) {
+  return currentStageEntry(mutation).tasks;
+}
+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 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 findCurrentStageEntry(instance) {
+  return findOpenStageEntry(instance);
+}
+function findCurrentTasks(instance) {
+  return findCurrentStageEntry(instance)?.tasks ?? [];
+}
+async function completeEffect(args) {
+  const { client, instanceId, effectKey, status, outputs, detail, error, durationMs, options } = args, ctx = await loadContext(client, instanceId);
+  return commitCompleteEffect(
+    ctx,
+    effectKey,
+    status,
+    outputs,
+    detail,
+    error,
+    durationMs,
+    options?.actor
+  );
+}
+function buildEffectHistoryEntry(pending, outcome) {
+  const { status, ranAt, actor, detail, error, durationMs, outputs } = outcome;
+  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 } : {}
+  };
+}
+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 = (/* @__PURE__ */ new Date()).toISOString();
+  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 };
+}
+function buildQueuedEffect(effect, origin, params, actor) {
+  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: (/* @__PURE__ */ new Date()).toISOString()
+  }, history = {
+    _key: randomKey(),
+    _type: "workflow.history.effectQueued",
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    effectKey: key,
+    effectId: effect.id,
+    origin
+  };
+  return { pending, history };
+}
+async function queueEffects(ctx, mutation, effects, origin, actor, callerParams) {
+  if (!effects) return;
+  const 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,
+      ...callerParams !== void 0 ? { params: callerParams } : {},
+      ...actor !== void 0 ? { actor } : {}
+    }), { pending, history } = buildQueuedEffect(effect, origin, params, actor);
+    mutation.pendingEffects.push(pending), mutation.history.push(history);
+  }
+}
+class ActionParamsInvalidError extends Error {
+  action;
+  taskId;
+  issues;
+  constructor(args) {
+    const lines = args.issues.map((i) => `  - ${i.paramId}: ${i.reason}`).join(`
+`);
+    super(`Action "${args.action}" on task "${args.taskId}" rejected: invalid params
+${lines}`), this.name = "ActionParamsInvalidError", this.action = args.action, this.taskId = args.taskId, this.issues = args.issues;
+  }
+}
+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((v) => checkParamType(v, { paramType: "doc.ref" }));
+    case "json":
+      return !0;
+    default:
+      return !1;
+  }
+}
+async function runActionOps(args) {
+  const { ops, mutation, stageId, taskId, actionName, params, actor } = 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 });
+    summaries.push(summary), mutation.history.push({
+      _key: randomKey(),
+      _type: "workflow.history.opApplied",
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      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*/
+    !1
+  ), resolvedMerge = {};
+  for (const [k, v] of Object.entries(op.merge))
+    resolvedMerge[k] = resolveOpSource(v, ctx);
+  return slot !== void 0 && Array.isArray(slot.value) && (slot.value = slot.value.map(
+    (row) => evalOpPredicate(op.where, row, ctx) ? { ...row, ...resolvedMerge } : row
+  )), { opType: op.type, target: op.target, resolved: { merge: resolvedMerge } };
+}
+function applyStateRemoveWhere(op, ctx) {
+  const slot = locateSlot(
+    ctx,
+    op.target,
+    /*createIfMissing*/
+    !1
+  );
+  return slot !== void 0 && Array.isArray(slot.value) && (slot.value = slot.value.filter(
+    (row) => !evalOpPredicate(op.where, row, ctx)
+  )), { opType: op.type, target: op.target };
+}
+function applyStatusSet(op, ctx) {
+  const entry = findOpenStageEntry(ctx.mutation)?.tasks.find((t) => t.id === op.taskId);
+  return entry !== void 0 && (entry.status = op.status), { opType: op.type, resolved: { taskId: op.taskId, status: op.status } };
+}
+function locateSlot(ctx, target, createIfMissing) {
+  let host;
+  if (target.scope === "workflow")
+    host = ctx.mutation.state;
+  else if (target.scope === "stage")
+    host = findOpenStageEntry(ctx.mutation)?.state;
+  else {
+    const task = findOpenStageEntry(ctx.mutation)?.tasks.find((t) => t.id === ctx.taskId);
+    host = task?.state, host === void 0 && task !== void 0 && createIfMissing && (task.state = [], host = task.state);
+  }
+  if (host === void 0)
+    throw new Error(
+      `Op target scope "${target.scope}" has no state container on this instance \u2014 declare the slot or check stage/task identity`
+    );
+  let slot = host.find((s) => s.id === target.slotId);
+  return slot === void 0 && createIfMissing && (slot = {
+    _key: randomKey(),
+    _type: "workflow.state.value.string",
+    id: target.slotId,
+    value: null
+  }, host.push(slot)), slot;
+}
+function resolveOpSource(src, ctx) {
+  switch (src.source) {
+    case "literal":
+      return src.value;
+    case "param":
+      return ctx.params[src.paramId];
+    case "actor":
+      return ctx.actor;
+    case "now":
+      return (/* @__PURE__ */ new Date()).toISOString();
+    case "self":
+      return;
+    // Not applicable inside ops; reserved for higher-level binding.
+    case "stageId":
+      return ctx.stageId;
+    case "stateRead": {
+      const value = readSlotFromMutation(ctx, src.scope, src.slotId);
+      return src.path !== void 0 ? getPath(value, src.path) : value;
+    }
+    case "effectOutput": {
+      const entry = ctx.mutation.effectsContext.find((e) => e.id === src.contextId);
+      if (entry === void 0) return null;
+      const v = src.path !== void 0 ? getPath(entry.value, src.path) : entry.value;
+      return v === void 0 ? null : v;
+    }
+    case "object": {
+      const out = {};
+      for (const [field, fieldSrc] of Object.entries(src.fields))
+        out[field] = resolveOpSource(fieldSrc, ctx);
+      return out;
+    }
+  }
+}
+function slotValue(slots, slotId) {
+  return slots?.find((s) => s.id === slotId)?.value;
+}
+function readSlotFromMutation(ctx, scope, slotId) {
+  if (scope === "workflow") return slotValue(ctx.mutation.state, slotId);
+  const stageEntry = findOpenStageEntry(ctx.mutation);
+  if (scope === "stage") return slotValue(stageEntry?.state, slotId);
+  const task = stageEntry?.tasks.find((t) => t.id === ctx.taskId);
+  return slotValue(task?.state, slotId);
+}
+function evalOpPredicate(p, row, ctx) {
+  if ("all" in p) return p.all.every((sub) => evalOpPredicate(sub, row, ctx));
+  if ("any" in p) return p.any.some((sub) => evalOpPredicate(sub, row, ctx));
+  const target = resolveOpSource(p.equals, ctx);
+  return row[p.field] === target;
+}
+async function fireAction(args) {
+  const { client, instanceId, taskId, action, params, options } = args, ctx = await loadContext(client, instanceId);
+  return commitAction(ctx, taskId, action, params, options?.actor);
+}
+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) {
+  if (action.setStatus === void 0) return;
+  const initialStatus = mutEntry.status, newStatus = action.setStatus;
+  return mutEntry.status = newStatus, mutEntry.completedAt = (/* @__PURE__ */ new Date()).toISOString(), actor && (mutEntry.completedBy = actor.id), mutation.history.push(
+    taskStatusChangedEntry({
+      stageId,
+      taskId,
+      from: initialStatus,
+      to: newStatus,
+      ...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);
+  mutation.history.push({
+    _key: randomKey(),
+    _type: "workflow.history.actionFired",
+    at: (/* @__PURE__ */ new Date()).toISOString(),
+    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
+  }), newStatus = applyActionSetStatus(action, mutation, mutEntry, stage.id, taskId, actor);
+  return await queueEffects(
+    ctx,
+    mutation,
+    action.effects,
+    {
+      kind: "action",
+      id: `${task.id}:${actionName}`
+    },
+    actor,
+    params
+  ), await persist(ctx, mutation), {
+    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;
+  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;
+  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
+      })
+    );
+  const transitionEvaluations = [];
+  for (const transition of stage.transitions ?? [])
+    transitionEvaluations.push({
+      transition,
+      filterSatisfied: await evaluateFilter({
+        filter: transition.filter,
+        definition,
+        snapshot,
+        params: buildParams(instance)
+      })
+    });
+  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 } = 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
+      })
+    );
+  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 } = 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);
+  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) {
+  if (!(action.filter === void 0 || await evaluateFilter({
+    filter: action.filter,
+    definition,
+    snapshot,
+    params: buildParams(instance)
+  })))
+    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 }
+    );
+  }
+}
+class ActionDisabledError extends Error {
+  reason;
+  taskId;
+  action;
+  constructor(args) {
+    super(formatDisabledReason(args.taskId, args.action, args.reason)), this.name = "ActionDisabledError", this.reason = args.reason, this.taskId = args.taskId, this.action = args.action;
+  }
+}
+const disabledReasonDetail = {
+  "role-required": (r) => `requires one of [${r.required.join(", ")}]; actor has [${r.actorRoles.join(", ") || "(none)"}]`,
+  "not-assigned": (r) => `actor "${r.actorId}" is not in the task assignees`,
+  "permission-denied": (r) => `actor lacks "${r.permission}" permission on the workflow instance`,
+  "filter-failed": (r) => `action filter returned false${r.detail ? ` (${r.detail})` : ""}`,
+  "task-not-active": (r) => `task status is "${r.status}"`,
+  "stage-terminal": (r) => `stage "${r.stageId}" is terminal`,
+  "instance-completed": (r) => `instance completed at ${r.completedAt}`,
+  "mutation-guard-denied": (r) => `blocked by mutation guard(s) [${r.guardIds.join(", ")}]${r.detail ? ` (${r.detail})` : ""}`
+};
+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, v] of Object.entries(doc))
+    k === "_rev" || k === "_createdAt" || k === "_updatedAt" || (out[k] = v);
+  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, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).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 {
+    return [extractDocumentId(uri)];
+  } catch {
+    return [];
+  }
+}
+async function resolveOperationContext(args) {
+  validateTags(args.tags);
+  const access = await resolveAccess(args.client, {
+    ...args.access !== void 0 ? { override: args.access } : {},
+    ...args.grantsFromPath !== void 0 ? { grantsFromPath: args.grantsFromPath } : {}
+  });
+  return {
+    access,
+    actor: access.actor,
+    clientForGdr: buildClientForGdr(args.client, args.resourceClients)
+  };
+}
+async function cascade(client, instanceId, actor, clientForGdr) {
+  const count = await cascadeAutoTransitions(client, instanceId, actor, clientForGdr);
+  return await propagateToAncestors(client, instanceId, actor, clientForGdr), count;
+}
+function buildClientForGdr(defaultClient, resolver) {
+  return resolver === void 0 ? () => defaultClient : (parsed) => resolver(parsed) ?? defaultClient;
+}
+async function reload(client, instanceId, tags) {
+  const doc = await client.getDocument(instanceId);
+  if (!doc) throw new Error(`Workflow instance ${instanceId} not found`);
+  if (!intersectsTags(doc.tags, tags))
+    throw new Error(`Workflow instance ${instanceId} not visible to this engine (tag mismatch)`);
+  return doc;
+}
+function intersectsTags(docTags, engineTags) {
+  return !docTags || docTags.length === 0 ? !1 : engineTags.some((t) => docTags.includes(t));
+}
+function toEffectsContextEntries(ctx) {
+  return Object.entries(ctx).map(([id, value]) => effectsContextEntry(id, value));
+}
+const workflow = {
+  /**
+   * Persist a workflow definition to the lake. Stored as a
+   * `workflow.definition` document with id
+   * `workflow.definition.<workflowId>.v<version>`. Subsequent versions
+   * are stored alongside earlier ones — `startInstance` picks the
+   * highest version by default.
+   */
+  /**
+   * Deploy a set of workflow definitions as one call. The SDK figures
+   * out the dependency order itself (children before parents that spawn
+   * them via `task.spawns.definitionRef`), idempotently writes any
+   * definition whose content has changed, and reports a per-definition
+   * outcome (`created` / `updated` / `unchanged`).
+   *
+   * Refs may point inside the batch OR at already-deployed definitions
+   * in the lake — both are valid. A ref pointing at neither errors with
+   * a clear message naming the missing target.
+   *
+   * Cycles in the dependency graph error before any write happens.
+   */
+  deployDefinitions: async (args) => {
+    const { client, tags, workflowResource, definitions } = args;
+    validateTags(tags);
+    for (const def of definitions)
+      validateDefinition(def);
+    const ordered = await sortByDependencies(client, definitions, tags, workflowResource), results = [], prefix = canonicalTag(tags), tx = client.transaction();
+    let hasWrites = !1;
+    for (const def of ordered) {
+      const id = definitionDocId(workflowResource, prefix, def.workflowId, def.version), expected = {
+        ...def,
+        _id: id,
+        _type: "workflow.definition",
+        tags
+      }, existing = await client.getDocument(id);
+      if (existing && intersectsTags(existing.tags, tags) && isDefinitionUnchanged(existing, expected)) {
+        results.push({ workflowId: def.workflowId, version: def.version, status: "unchanged" });
+        continue;
+      }
+      if (existing) {
+        const expectedKeys = new Set(Object.keys(expected)), toUnset = Object.keys(existing).filter(
+          (k) => !k.startsWith("_") && !expectedKeys.has(k)
+        ), patch = client.patch(id).set(expected).ifRevisionId(existing._rev);
+        toUnset.length > 0 && patch.unset(toUnset), tx.patch(patch);
+      } else
+        tx.create(expected);
+      hasWrites = !0, results.push({
+        workflowId: def.workflowId,
+        version: def.version,
+        status: existing ? "updated" : "created"
+      });
+    }
+    return hasWrites && await tx.commit(), { results };
+  },
+  /**
+   * Spawn a new workflow instance from a deployed definition.
+   *
+   * Pins the snapshot at start-time, seeds `effectsContext`, enters
+   * the initial stage (which builds taskStatus, queues onEnter
+   * effects, auto-activates tasks). Then cascades auto-transitions
+   * until stable. Returns the resulting instance.
+   */
+  startInstance: async (args) => {
+    const {
+      client,
+      tags,
+      workflowResource,
+      workflowId,
+      version,
+      initialState,
+      ancestors,
+      effectsContext,
+      instanceId,
+      perspective
+    } = args, { actor, clientForGdr } = await resolveOperationContext(args), definition = await loadDefinition(client, workflowId, version, tags), id = instanceId ?? `${canonicalTag(tags)}.wf-instance.${randomKey()}`;
+    if (definition.stages.find((s) => s.id === definition.initialStageId) === void 0)
+      throw new Error(
+        `Initial stage "${definition.initialStageId}" missing in ${workflowId} v${definition.version}`
+      );
+    const now = (/* @__PURE__ */ new Date()).toISOString(), effectsContextEntries = effectsContext ? toEffectsContextEntries(effectsContext) : [], resolvedState = await resolveDeclaredState({
+      slotDefs: definition.state ?? [],
+      initialState: initialState ?? [],
+      ctx: {
+        client,
+        selfId: id,
+        tags,
+        workflowResource,
+        ...perspective !== void 0 ? { perspective } : {}
+      },
+      randomKey
+    }), effectivePerspective = perspective ?? derivePerspectiveFromState(resolvedState), base = buildInstanceBase({
+      id,
+      now,
+      tags,
+      workflowResource,
+      workflowId: definition.workflowId,
+      pinnedVersion: definition.version,
+      definition,
+      state: resolvedState,
+      effectsContext: effectsContextEntries,
+      ancestors: ancestors ?? [],
+      perspective: effectivePerspective,
+      initialStageId: definition.initialStageId,
+      actor
+    });
+    return await client.create(base), await primeInitialStage(client, id, actor, clientForGdr), await cascade(client, id, actor, clientForGdr), reload(client, id, tags);
+  },
+  /**
+   * Fire an action against a task. If the task is pending, it is
+   * auto-invoked first (pending → active) so callers don't have to know
+   * the lifecycle. Cascades auto-transitions and propagates to ancestors
+   * after the action commits.
+   *
+   * This is the universal "something happened" call. Editors fire it.
+   * Runtimes fire it in response to webhooks, effect completions, and
+   * timer firings. External signals never bypass this.
+   */
+  fireAction: async (args) => {
+    const {
+      client,
+      tags,
+      instanceId,
+      taskId,
+      action,
+      params,
+      idempotent,
+      resourceClients
+    } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), 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)
+      return { instance: before, cascaded: 0, fired: !1 };
+    const actionEval = (await evaluateInstance({
+      client,
+      tags,
+      instanceId,
+      access,
+      ...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 }
+    });
+    const actionResult = await fireAction({
+      client,
+      instanceId,
+      taskId,
+      action,
+      ...params !== void 0 ? { params } : {},
+      options: { actor }
+    }), cascaded = await cascade(client, instanceId, actor, clientForGdr);
+    return {
+      instance: await reload(client, instanceId, tags),
+      cascaded,
+      fired: !0,
+      ...actionResult.ranOps !== void 0 ? { ranOps: actionResult.ranOps } : {}
+    };
+  },
+  /**
+   * Report a queued effect's outcome. Drains it from `pendingEffects`,
+   * appends an `effectHistory` entry, and (if `outputs` are supplied
+   * and the effect succeeded) upserts those values into
+   * `effectsContext` by key — so downstream effect bindings can
+   * reference them. Cascades after.
+   */
+  completeEffect: async (args) => {
+    const { client, tags, instanceId, effectKey, status, outputs, detail, error, durationMs } = args, { actor, clientForGdr } = await resolveOperationContext(args);
+    await completeEffect({
+      client,
+      instanceId,
+      effectKey,
+      status,
+      ...outputs !== void 0 ? { outputs } : {},
+      ...detail !== void 0 ? { detail } : {},
+      ...error !== void 0 ? { error } : {},
+      ...durationMs !== void 0 ? { durationMs } : {},
+      ...actor !== void 0 ? { options: { actor } } : {}
+    });
+    const cascaded = await cascade(client, instanceId, actor, clientForGdr);
+    return {
+      instance: await reload(client, instanceId, tags),
+      cascaded,
+      fired: !0
+    };
+  },
+  /**
+   * Re-evaluate auto-transitions and resolve due waits until stable.
+   *
+   * Used by the runtime after any event that might affect the workflow
+   * but isn't itself a task action: a subject doc was patched, a sibling
+   * workflow completed, the clock crossed a `completeWhen` deadline, etc.
+   * The runtime doesn't need to know what changed — it just nudges
+   * affected instances and the engine re-evaluates.
+   */
+  tick: async (args) => {
+    const { client, tags, instanceId } = args, { actor, clientForGdr } = await resolveOperationContext(args);
+    await reload(client, instanceId, tags);
+    const cascaded = await cascade(client, instanceId, actor, clientForGdr);
+    return {
+      instance: await reload(client, instanceId, tags),
+      cascaded,
+      fired: cascaded > 0
+    };
+  },
+  /**
+   * Admin override — force the instance into `targetStageId` regardless
+   * of filters or declared transitions. ACL gating should be enforced
+   * upstream; this verb performs the mechanical move.
+   */
+  setStage: async (args) => {
+    const { client, tags, instanceId, targetStageId, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args);
+    await reload(client, instanceId, tags);
+    const result = await setStage({
+      client,
+      instanceId,
+      targetStageId,
+      ...reason !== void 0 ? { reason } : {},
+      ...actor !== void 0 ? { options: { actor } } : {}
+    }), cascaded = result.fired ? await cascade(client, instanceId, actor, clientForGdr) : 0;
+    return {
+      instance: await reload(client, instanceId, tags),
+      cascaded,
+      fired: result.fired
+    };
+  },
+  /**
+   * Fetch a workflow instance by id, scoped to the engine's tags.
+   * Throws when the instance doesn't exist or isn't visible to this
+   * engine.
+   */
+  getInstance: async (args) => {
+    const { client, tags, instanceId } = args;
+    return validateTags(tags), reload(client, instanceId, tags);
+  },
+  /**
+   * Run a caller-supplied GROQ query with the engine's tags bound as
+   * `$engineTags`. This does NOT rewrite the query — arbitrary GROQ
+   * can't be safely tag-scoped after the fact — so the CALLER MUST
+   * filter on `$engineTags` (e.g.
+   * `count(tags[@ in $engineTags]) > 0`). To guard against accidental
+   * cross-tenant reads, a query that never references `$engineTags` is
+   * rejected before it reaches the lake. Caller is responsible for type
+   * narrowing the result.
+   */
+  query: async (args) => {
+    const { client, tags, groq, params } = args;
+    if (validateTags(tags), !groq.includes("$engineTags"))
+      throw new Error(
+        `workflow.query: query must filter on $engineTags to stay tag-scoped (e.g. "count(tags[@ in $engineTags]) > 0"); got: ${groq}`
+      );
+    return client.fetch(groq, { ...params, engineTags: tags });
+  },
+  /**
+   * Snapshot-aware GROQ — runs against the same in-memory view that
+   * filters see for a given instance.
+   *
+   * Hydrates the instance's snapshot (instance + subject + ancestors
+   * + every doc declared by a `doc.ref` / `doc.refs` slot in scope),
+   * then evaluates the supplied GROQ in groq-js against that dataset.
+   * Reserved params are auto-bound: `$self`, `$subject`, `$parent`,
+   * `$ancestors`, `$stage`, `$now` — all in GDR URI form to match the
+   * snapshot's keying.
+   *
+   * Use when an external consumer (a UI, a debug pane, a test) wants
+   * to ask "what does the engine see for this workflow right now?"
+   * without re-implementing hydration. Pure read — never writes.
+   */
+  queryInScope: async (args) => {
+    const { client, tags, instanceId, groq, params, resourceClients } = args;
+    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), tree = parse(groq, { params: { ...reserved, ...params } });
+    return await (await evaluate(tree, {
+      dataset: snapshot.docs,
+      params: { ...reserved, ...params }
+    })).get();
+  },
+  /**
+   * List every pending effect on the instance. Returns the same entries
+   * the runtime would see — claimed and unclaimed alike.
+   */
+  listPendingEffects: async (args) => (await reload(args.client, args.instanceId, args.tags)).pendingEffects,
+  /**
+   * Filter pending effects on the instance by criteria. `claimed`
+   * filters on claim presence; `names` restricts to specific effect
+   * names. Both filters compose (AND).
+   */
+  findPendingEffects: async (args) => (await reload(args.client, args.instanceId, args.tags)).pendingEffects.filter((e) => !(args.claimed === !0 && e.claim === void 0 || args.claimed === !1 && e.claim !== void 0 || args.names !== void 0 && !args.names.includes(e.effectId))),
+  /**
+   * Project the instance from a given actor's perspective. Returns a
+   * `WorkflowEvaluation` with per-action verdicts (`allowed` + a
+   * structured `disabledReason`). Pure read; never writes.
+   *
+   * Used by UIs to render disabled-with-reason buttons and by
+   * `fireAction` to gate writes via the same logic.
+   */
+  evaluate: async (args) => evaluateInstance(args),
+  /**
+   * Materialised spawned children of a parent instance.
+   *
+   * Walks `history` for `workflow.history.spawned` events — the durable
+   * record. (The per-task `spawnedInstances` field on the active stage
+   * only exists while that stage is current; history survives.) Strips
+   * the GDR URI on each `instanceRef` to a bare `_id`, fetches the
+   * instances, drops any that aren't visible to this engine's tags, and
+   * returns them sorted by `startedAt` ascending.
+   *
+   * Pass `taskId` to restrict to a single spawning task on the parent.
+   */
+  children: async (args) => {
+    const { client, tags, instanceId, taskId } = args;
+    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)",
+      { ids, engineTags: tags }
+    );
+  },
+  /**
+   * Permission helpers — Sanity ACL grants evaluated against documents
+   * via GROQ. Used by `workflow.evaluate` to soft-gate actions when the
+   * caller supplies grants.
+   */
+  permissions: {
+    matchesFilter,
+    grantsPermissionOn,
+    fetchGrants
+  }
+};
+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)',
+    { engineTags: tags }
+  ), seen = [], missingByName = /* @__PURE__ */ new Map();
+  for (const def of definitions)
+    seen.push({ workflowId: def.workflowId, version: def.version, _id: def._id }), walkEffectNames(def, (name, location) => {
+      if (effectHandlers[name] !== void 0) return;
+      const key = `${name}@@${def._id}`;
+      let bucket = missingByName.get(key);
+      bucket === void 0 && (bucket = { definitionId: def._id, locations: /* @__PURE__ */ new Set() }, missingByName.set(key, bucket)), bucket.locations.add(location);
+    });
+  const missing = [];
+  for (const [key, bucket] of missingByName.entries()) {
+    const name = key.split("@@")[0];
+    missing.push({
+      name,
+      definitionId: bucket.definitionId,
+      locations: [...bucket.locations].toSorted()
+    });
+  }
+  for (const m of missing) {
+    const info = {
+      phase: "deploy",
+      name: m.name,
+      locations: m.locations,
+      definitionId: m.definitionId
+    };
+    if (await applyMissingHandler(missingHandler, info, log) === "fail")
+      throw new Error(
+        `verifyDeployedDefinitions: missing handler for "${m.name}" referenced by ${m.definitionId} at ${m.locations.join(", ")}`
+      );
+  }
+  return { definitions: seen, missing };
+}
+function walkEffectNames(def, visit) {
+  const visitEffects = (effects, location) => {
+    for (const e of effects ?? []) visit(e.id, location);
+  };
+  for (const stage of def.stages ?? []) {
+    visitEffects(stage.onEnter, `stage[${stage.id}].onEnter`), visitEffects(stage.onExit, `stage[${stage.id}].onExit`);
+    for (const t of stage.tasks ?? []) {
+      visitEffects(t.effects, `stage[${stage.id}].task[${t.id}].effects`);
+      for (const a of t.actions ?? [])
+        visitEffects(a.effects, `stage[${stage.id}].task[${t.id}].action[${a.id}].effects`);
+    }
+    for (const tr of stage.transitions ?? [])
+      visitEffects(tr.effects, `stage[${stage.id}].transition[${tr.to}].effects`);
+  }
+}
+async function drainEffectsInternal(args) {
+  const {
+    client,
+    tags,
+    workflowResource,
+    resourceClients,
+    instanceId,
+    effectHandlers,
+    missingHandler,
+    logger
+  } = args, drainerActor = args.access?.actor ?? { kind: "system", id: "engine.drainEffects" }, completionAccess = {
+    actor: drainerActor,
+    ...args.access?.grants !== void 0 ? { grants: args.access.grants } : {}
+  };
+  validateTags(tags);
+  const log = logger("drainEffects"), drained = [], failed = [], skipped = [], skippedKeys = /* @__PURE__ */ new Set();
+  for (; ; ) {
+    const before = await reload(client, instanceId, tags), candidate = before.pendingEffects.find(
+      (e) => e.claim === void 0 && !skippedKeys.has(e._key)
+    );
+    if (candidate === void 0) break;
+    const handler = effectHandlers[candidate.effectId];
+    if (handler === void 0) {
+      await assertSkippableOrThrow(missingHandler, candidate, instanceId, log), skipped.push(candidate), skippedKeys.add(candidate._key);
+      continue;
+    }
+    if (!await claimPendingEffect(client, before, candidate._key, drainerActor)) continue;
+    const { outputs, dispatchError } = await dispatchEffect(handler, candidate, {
+      client,
+      instanceId,
+      logger
+    });
+    await reportEffectOutcome({
+      client,
+      tags,
+      workflowResource,
+      ...resourceClients !== void 0 ? { resourceClients } : {},
+      instanceId,
+      effectKey: candidate._key,
+      access: completionAccess,
+      outputs,
+      dispatchError
+    }), dispatchError === void 0 ? drained.push(candidate) : failed.push(candidate);
+  }
+  return { drained, failed, skipped };
+}
+async function reportEffectOutcome(args) {
+  const { outputs, dispatchError, resourceClients, ...rest } = args;
+  await workflow.completeEffect({
+    ...rest,
+    ...resourceClients !== void 0 ? { resourceClients } : {},
+    status: dispatchError === void 0 ? "done" : "failed",
+    ...outputs !== void 0 ? { outputs } : {},
+    ...dispatchError !== void 0 ? { error: dispatchError } : {}
+  });
+}
+async function assertSkippableOrThrow(missingHandler, candidate, instanceId, log) {
+  if (await applyMissingHandler(
+    missingHandler,
+    { phase: "drain", name: candidate.effectId, effectKey: candidate._key, instanceId },
+    log
+  ) === "fail")
+    throw new Error(
+      `drainEffects: no handler registered for "${candidate.effectId}" (effectKey=${candidate._key}, instanceId=${instanceId})`
+    );
+}
+async function claimPendingEffect(client, instance, effectKey, drainerActor) {
+  const claim = {
+    _type: "workflow.pendingEffect.claim",
+    claimedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    claimedBy: drainerActor
+  };
+  try {
+    return await client.patch(instance._id).ifRevisionId(instance._rev).set({ [`pendingEffects[_key=="${effectKey}"].claim`]: claim }).commit(), !0;
+  } catch {
+    return !1;
+  }
+}
+async function dispatchEffect(handler, candidate, ctx) {
+  try {
+    const result = await handler(candidate.params, {
+      client: ctx.client,
+      instanceId: ctx.instanceId,
+      effectKey: candidate._key,
+      log: (message, extra) => ctx.logger(`effect.${candidate.effectId}`).info(message, extra)
+    });
+    return result?.outputs !== void 0 ? { outputs: result.outputs } : {};
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err), stack = err instanceof Error && err.stack !== void 0 ? err.stack : void 0;
+    return { dispatchError: stack !== void 0 ? { message, stack } : { message } };
+  }
+}
+async function applyMissingHandler(policy, info, log) {
+  if (policy === "fail") return "fail";
+  if (policy === "skip")
+    return log.warn(`Missing effect handler "${info.name}" \u2014 skipping`, { info }), "skip";
+  try {
+    return await policy(info), "skip";
+  } catch {
+    return "fail";
+  }
+}
+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
+  // so progress markers (process.stdout.write) and logger lines
+  // don't interleave on the same line.
+  info: (message, extra) => console.error(`[${name}] ${message}`, extra !== void 0 ? extra : ""),
+  warn: (message, extra) => console.warn(`[${name}] ${message}`, extra !== void 0 ? extra : ""),
+  error: (message, extra) => console.error(`[${name}] ${message}`, extra !== void 0 ? extra : "")
+}), silentLogger = {
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+function createEngine(args) {
+  const { client, workflowResource, tags, resourceClients } = args;
+  validateTags(tags);
+  const effectHandlers = args.effectHandlers ?? {}, missingHandler = args.missingHandler ?? "fail", logger = args.loggerFactory ?? defaultLoggerFactory, bind = (rest) => ({
+    client,
+    tags,
+    workflowResource,
+    ...resourceClients !== void 0 ? { resourceClients } : {},
+    ...rest
+  });
+  return {
+    client,
+    tags,
+    workflowResource,
+    effectHandlers,
+    missingHandler,
+    logger,
+    deployDefinitions: (rest) => workflow.deployDefinitions(bind(rest)),
+    startInstance: (rest) => workflow.startInstance(bind(rest)),
+    fireAction: (rest) => workflow.fireAction(bind(rest)),
+    completeEffect: (rest) => workflow.completeEffect(bind(rest)),
+    tick: (rest) => workflow.tick(bind(rest)),
+    evaluateInstance: (rest) => evaluateInstance(bind(rest)),
+    setStage: (rest) => workflow.setStage(bind(rest)),
+    getInstance: ({ instanceId }) => workflow.getInstance({ client, tags, workflowResource, instanceId }),
+    children: ({ instanceId, taskId }) => workflow.children({
+      client,
+      tags,
+      workflowResource,
+      instanceId,
+      ...taskId !== void 0 ? { taskId } : {}
+    }),
+    query: ({ groq, params }) => workflow.query({
+      client,
+      tags,
+      workflowResource,
+      groq,
+      ...params !== void 0 ? { params } : {}
+    }),
+    queryInScope: ({ instanceId, groq, params }) => workflow.queryInScope({
+      client,
+      tags,
+      workflowResource,
+      instanceId,
+      groq,
+      ...params !== void 0 ? { params } : {}
+    }),
+    listPendingEffects: ({ instanceId }) => workflow.listPendingEffects({ client, tags, workflowResource, instanceId }),
+    findPendingEffects: ({ instanceId, claimed, names }) => workflow.findPendingEffects({
+      client,
+      tags,
+      workflowResource,
+      instanceId,
+      ...claimed !== void 0 ? { claimed } : {},
+      ...names !== void 0 ? { names } : {}
+    }),
+    drainEffects: ({ instanceId, access }) => drainEffectsInternal({
+      client,
+      tags,
+      workflowResource,
+      ...resourceClients !== void 0 ? { resourceClients } : {},
+      instanceId,
+      effectHandlers,
+      missingHandler,
+      logger,
+      ...access !== void 0 ? { access } : {}
+    }),
+    verifyDeployedDefinitions: () => verifyDeployedDefinitionsInternal({
+      client,
+      tags,
+      effectHandlers,
+      missingHandler,
+      logger
+    })
+  };
+}
+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;
+  }
+}
+const HISTORY_DISPLAY = {
+  "workflow.history.stageEntered": {
+    title: "Stage entered",
+    description: "The instance crossed into a new stage."
+  },
+  "workflow.history.stageExited": {
+    title: "Stage exited",
+    description: "The instance left a stage on the way to the next one."
+  },
+  "workflow.history.taskActivated": {
+    title: "Task activated",
+    description: "A task flipped from `pending` to `active` and its onEnter effects queued."
+  },
+  "workflow.history.taskStatusChanged": {
+    title: "Task status changed",
+    description: "An action or op flipped a task's status (active \u2192 done / skipped / failed)."
+  },
+  "workflow.history.actionFired": {
+    title: "Action fired",
+    description: "An action was invoked against a task \u2014 ops ran, status may have flipped, effects queued."
+  },
+  "workflow.history.transitionFired": {
+    title: "Transition fired",
+    description: "A transition committed and the instance moved to a new stage."
+  },
+  "workflow.history.effectQueued": {
+    title: "Effect queued",
+    description: "A pending effect was added to the queue, waiting for a drainer to dispatch it."
+  },
+  "workflow.history.effectCompleted": {
+    title: "Effect completed",
+    description: "A drainer ran an effect handler to completion (done or failed) and merged its outputs into effectsContext."
+  },
+  "workflow.history.spawned": {
+    title: "Spawned child",
+    description: "A `task.spawns` declaration spawned a child workflow instance."
+  },
+  "workflow.history.opApplied": {
+    title: "Op applied",
+    description: "An inline state-mutation op (state.set / state.append / status.set / etc.) ran during an action commit."
+  }
+}, STATE_SLOT_DISPLAY = {
+  "workflow.state.doc.ref": {
+    title: "Document reference",
+    description: "Single GDR pointer at a document in this or another resource."
+  },
+  "workflow.state.doc.refs": {
+    title: "Document references",
+    description: "Ordered list of GDR pointers \u2014 multi-doc selection."
+  },
+  "workflow.state.query": {
+    title: "Query result",
+    description: "Snapshot of a GROQ projection captured at slot-resolve time; resolvedAt is stamped on the value."
+  },
+  "workflow.state.value.string": {
+    title: "String value",
+    description: "Free-form string slot."
+  },
+  "workflow.state.value.url": {
+    title: "URL value",
+    description: "Validated URL slot."
+  },
+  "workflow.state.value.number": {
+    title: "Number value",
+    description: "Numeric slot."
+  },
+  "workflow.state.value.boolean": {
+    title: "Boolean value",
+    description: "True/false slot."
+  },
+  "workflow.state.value.dateTime": {
+    title: "Date / time value",
+    description: "ISO-timestamp slot."
+  },
+  "workflow.state.checklist": {
+    title: "Checklist",
+    description: "Append-only list of checkable items; ops add/update/remove entries."
+  },
+  "workflow.state.notes": {
+    title: "Notes log",
+    description: "Append-only structured-note log (signoffs, comments, audit rows)."
+  },
+  "workflow.state.assignees": {
+    title: "Assignees",
+    description: "Ordered list of typed (user|role) assignees."
+  }
+}, OP_DISPLAY = {
+  "workflow.op.state.set": {
+    title: "Set slot",
+    description: "Overwrite a state slot's value with a resolved Source."
+  },
+  "workflow.op.state.append": {
+    title: "Append to slot",
+    description: "Push a resolved item onto an array-typed slot (notes, checklist, assignees, refs)."
+  },
+  "workflow.op.state.updateWhere": {
+    title: "Update matching rows",
+    description: "Merge fields into rows of an array-typed slot that match the predicate."
+  },
+  "workflow.op.state.removeWhere": {
+    title: "Remove matching rows",
+    description: "Drop rows of an array-typed slot that match the predicate."
+  },
+  "workflow.op.status.set": {
+    title: "Set task status",
+    description: "Flip a task's status explicitly (action.setStatus is the more common path)."
+  }
+}, EFFECTS_CONTEXT_DISPLAY = {
+  "effectsContext.string": {
+    title: "String",
+    description: "Stable string parameter for effect handlers."
+  },
+  "effectsContext.number": {
+    title: "Number",
+    description: "Stable numeric parameter for effect handlers."
+  },
+  "effectsContext.boolean": {
+    title: "Boolean",
+    description: "Stable boolean parameter for effect handlers."
+  },
+  "effectsContext.ref": {
+    title: "GDR reference",
+    description: "Stable GDR pointer parameter for effect handlers."
+  },
+  "effectsContext.json": {
+    title: "JSON",
+    description: "Stable JSON payload for effect handlers."
+  }
+}, AUTHORING_DISPLAY = {
+  "workflow.stage": {
+    title: "Stage",
+    description: "A bucket of tasks the workflow is currently in."
+  },
+  "workflow.task": {
+    title: "Task",
+    description: "A unit of work inside a stage; carries actions and may spawn children."
+  },
+  "workflow.action": {
+    title: "Action",
+    description: "An invocable transition on a task \u2014 runs ops, queues effects, may flip status."
+  },
+  "workflow.action.param": {
+    title: "Action param",
+    description: "Caller-supplied parameter on an action; validated before any commit."
+  },
+  "workflow.transition": {
+    title: "Transition",
+    description: "An edge between stages, gated by a filter."
+  },
+  "workflow.predicate": {
+    title: "Predicate",
+    description: "Named GROQ filter, reusable across transitions / tasks / actions."
+  },
+  "workflow.effect": {
+    title: "Effect",
+    description: "Externally-dispatched side effect; queued on commit, drained by a runtime, completed asynchronously."
+  },
+  "workflow.spawn": {
+    title: "Spawn",
+    description: "Declares a task that fans out one or more child workflow instances."
+  },
+  "workflow.pendingEffect": {
+    title: "Pending effect",
+    description: "An effect that has been queued but not yet dispatched."
+  },
+  "workflow.pendingEffect.claim": {
+    title: "Claim",
+    description: "A drainer's lock on a pending effect while it dispatches."
+  },
+  "workflow.definition": {
+    title: "Workflow definition",
+    description: "An immutable workflow blueprint pinned by `workflowId` + `version`."
+  },
+  "workflow.instance": {
+    title: "Workflow instance",
+    description: "A running (or finished) workflow against a subject."
+  }
+}, DISPLAY = {
+  ...HISTORY_DISPLAY,
+  ...STATE_SLOT_DISPLAY,
+  ...OP_DISPLAY,
+  ...EFFECTS_CONTEXT_DISPLAY,
+  ...AUTHORING_DISPLAY
+};
+function displayTitle(typeKey) {
+  return typeKey ? DISPLAY[typeKey]?.title ?? typeKey : "";
+}
+function displayDescription(typeKey) {
+  if (typeKey)
+    return DISPLAY[typeKey]?.description;
+}
+export {
+  AUTHORING_DISPLAY,
+  ActionDisabledError,
+  ActionParamsInvalidError,
+  DISPLAY,
+  EFFECTS_CONTEXT_DISPLAY,
+  GUARD_LIFTED_PREDICATE,
+  GUARD_OWNER,
+  HISTORY_DISPLAY,
+  MutationGuardDeniedError,
+  OP_DISPLAY,
+  STATE_SLOT_DISPLAY,
+  canonicalTag,
+  compileGuard,
+  createEngine,
+  defaultLoggerFactory,
+  denyingGuards,
+  deployStageGuards,
+  displayDescription,
+  displayTitle,
+  evaluateMutationGuard,
+  extractDocumentId,
+  gdrFromResource,
+  gdrRef,
+  gdrUri,
+  guardMatches,
+  isGdr,
+  lakeGuardId,
+  parseGdr,
+  reconcileStageGuards,
+  refCanvas,
+  refDashboard,
+  refDataset,
+  refMediaLibrary,
+  resolveAccess,
+  retractStageGuards,
+  silentLogger,
+  validateDefinition,
+  validateTags,
+  workflow
+};
+//# sourceMappingURL=index.js.map