@sanity/workflow-engine 0.4.0 → 0.5.0

package/dist/index.js

@@ -246,6 +246,20 @@ function effectBindings(effects) {
     (e) => Object.entries(e.bindings ?? {}).map(([k, groq]) => [`${e.name}.${k}`, groq])
   );
 }
+function actionVerdict(task, action) {
+  return {
+    task: task.task.name,
+    taskStatus: task.status,
+    action: action.action.name,
+    title: action.action.title,
+    allowed: action.allowed,
+    disabledReason: action.disabledReason,
+    params: action.action.params ?? []
+  };
+}
+function availableActions(tasks) {
+  return tasks.flatMap((t) => t.actions.map((a) => actionVerdict(t, a)));
+}
 const wallClock = () => (/* @__PURE__ */ new Date()).toISOString(), GUARD_DOC_TYPE = "temp.system.guard";
 class MutationGuardDeniedError extends Error {
   denied;
@@ -440,79 +454,63 @@ function stripStateForLake(value) {
 function bareId(id) {
   return isGdrUri(id) ? extractDocumentId(id) : id;
 }
-const GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
-function resolveGuard(guard, instance, stageName, now) {
-  const ctx = { instance, now }, targets = resolveIdRefTargets(guard.match.idRefs, ctx);
-  if (targets === null) return null;
-  const resource = assertSingleResource(targets), types = resolveMatchTypes(targets, guard.match.types);
-  return { doc: compileGuard({
-    id: lakeGuardId({ instanceDocId: instance._id, guardName: guard.name }),
-    resourceType: resource.type,
-    resourceId: resource.id,
-    owner: GUARD_OWNER,
-    sourceInstanceId: instance._id,
-    sourceDefinition: instance.definition,
-    sourceStage: stageName,
-    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 };
+function abortReason(instance) {
+  return instance.history.find(
+    (h) => h._type === "aborted"
+  )?.reason;
 }
-async function upsertGuard(client, doc) {
-  if (!await client.getDocument(doc._id)) {
-    await client.create(doc);
-    return;
-  }
-  const { _id, _type, _rev, _createdAt, _updatedAt, ...body } = doc;
-  await client.patch(doc._id).set(body).commit();
+function diagnoseInputFromEvaluation(evaluation) {
+  return {
+    instance: evaluation.instance,
+    tasks: evaluation.currentStage.tasks,
+    transitions: evaluation.currentStage.transitions
+  };
 }
-function resolvedStageGuards(args) {
-  const stage = args.definition.stages.find((s) => s.name === args.stageName), out = [];
-  for (const guard of stage?.guards ?? []) {
-    const resolved = resolveGuard(guard, args.instance, args.stageName, args.now);
-    resolved !== null && out.push({ client: args.clientForGdr(resolved.routeGdr), doc: resolved.doc });
-  }
-  return out;
+function openStage(instance) {
+  return findOpenStageEntry(instance);
 }
-async function committedInstance(args) {
-  return await args.client.getDocument(args.instance._id) ?? void 0;
+function assigneesOf(stage, taskName) {
+  return (stage?.tasks.find((t) => t.name === taskName)?.state ?? []).filter((s) => s._type === "assignees").flatMap((s) => s.value);
 }
-async function deployStageGuards(args) {
-  const live = await committedInstance(args);
-  if (!(live === void 0 || live.currentStage !== args.stageName) && live.abortedAt === void 0)
-    for (const { client, doc } of resolvedStageGuards(args))
-      await upsertGuard(client, doc);
+function isResolved(status) {
+  return status === "done" || status === "skipped";
 }
-async function retractStageGuards(args) {
-  const live = await committedInstance(args);
-  if (live !== void 0 && !(live.currentStage === args.stageName && live.abortedAt === void 0))
-    for (const { client, doc } of resolvedStageGuards(args))
-      await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit();
+function failedEffectCause(input) {
+  const stalled = new Set(input.tasks.filter((t) => !isResolved(t.status)).map((t) => t.task.name)), effect = [...input.instance.effectHistory].reverse().find((e) => e.status === "failed" && e.origin.kind === "task" && stalled.has(e.origin.name));
+  return effect ? { kind: "failed-effect", effect } : void 0;
 }
-function randomKey(length = 12) {
-  const bytes = new Uint8Array(length);
-  return globalThis.crypto.getRandomValues(bytes), [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, length);
+function hungEffectCause(input) {
+  const effect = input.instance.pendingEffects.find((e) => e.claim !== void 0);
+  return effect ? { kind: "hung-effect", effect } : void 0;
 }
-async function evaluateCondition(args) {
-  const { condition, snapshot, params } = args;
-  return condition === void 0 ? !0 : !!await runGroq(condition, params, snapshot);
+function failedTaskCause(input) {
+  const failed = input.tasks.find((t) => t.status === "failed");
+  return failed ? { kind: "failed-task", task: failed.task.name } : void 0;
 }
-async function evaluatePredicates(args) {
-  const out = {};
-  for (const [name, groq] of Object.entries(args.predicates ?? {}))
-    out[name] = !!await runGroq(groq, args.params, args.snapshot);
-  return out;
+function waitingState(input) {
+  const active = input.tasks.find((t) => t.status === "active" && (t.task.actions ?? []).length > 0);
+  if (active !== void 0)
+    return {
+      state: "waiting",
+      task: active.task.name,
+      assignees: assigneesOf(openStage(input.instance), active.task.name),
+      actions: (active.task.actions ?? []).map((a) => a.name)
+    };
 }
-async function runGroq(groq, params, snapshot) {
-  const tree = parse(groq, { params });
-  return (await evaluate(tree, { dataset: snapshot.docs, params })).get();
+function noTransitionFiresCause(input) {
+  if (input.transitions.length !== 0 && !input.transitions.some((t) => t.filterSatisfied) && input.tasks.every((t) => isResolved(t.status)))
+    return { kind: "no-transition-fires" };
+}
+function diagnoseInstance(input) {
+  const { instance } = input;
+  if (instance.abortedAt !== void 0) {
+    const reason = abortReason(instance);
+    return { state: "aborted", at: instance.abortedAt, ...reason !== void 0 ? { reason } : {} };
+  }
+  if (instance.completedAt !== void 0)
+    return { state: "completed", at: instance.completedAt };
+  const cause = failedEffectCause(input) ?? failedTaskCause(input) ?? hungEffectCause(input) ?? noTransitionFiresCause(input);
+  return cause !== void 0 ? { state: "stuck", cause } : waitingState(input) ?? { state: "progressing" };
 }
 function buildSnapshot(args) {
   const docs = [], knownIds = /* @__PURE__ */ new Set();
@@ -631,156 +629,357 @@ function resourceFromParsed(parsed) {
 function collectEntryDocUris(resolvedStateEntries) {
   return entryDocRefs(resolvedStateEntries).map((ref) => ref.id);
 }
-class StateValueShapeError extends Error {
-  entryType;
-  entryName;
-  issues;
-  constructor(args) {
-    const issueText = args.issues.join("; ");
-    super(
-      `State entry ${args.mode} shape invalid for "${args.entryName}" (${args.entryType}): ${issueText}`
-    ), this.name = "StateValueShapeError", this.entryType = args.entryType, this.entryName = args.entryName, this.issues = args.issues;
-  }
-}
-const GdrShape = v.looseObject({
-  id: v.pipe(
-    v.string(),
-    v.check((s) => isGdrUri(s), "must be a GDR URI")
-  ),
-  type: v.pipe(v.string(), v.minLength(1))
-}), ReleaseRefShape = v.looseObject({
-  id: v.pipe(
-    v.string(),
-    v.check((s) => isGdrUri(s), "must be a GDR URI")
-  ),
-  type: v.literal("system.release"),
-  releaseName: v.pipe(v.string(), v.minLength(1))
-}), ActorShape = v.looseObject({
-  kind: v.picklist(["user", "ai", "system"]),
-  id: v.pipe(v.string(), v.minLength(1)),
-  roles: v.optional(v.array(v.string())),
-  onBehalfOf: v.optional(v.string())
-}), AssigneeShape = v.union([
-  v.looseObject({ type: v.literal("user"), id: v.pipe(v.string(), v.minLength(1)) }),
-  v.looseObject({ type: v.literal("role"), role: v.pipe(v.string(), v.minLength(1)) })
-]), ChecklistItemShape = v.looseObject({
-  label: v.pipe(v.string(), v.minLength(1)),
-  done: v.boolean(),
-  doneBy: v.optional(v.string()),
-  doneAt: v.optional(v.string()),
-  _key: v.optional(v.pipe(v.string(), v.minLength(1)))
-}), NoteItemShape = v.pipe(
-  v.looseObject({
-    _key: v.optional(v.pipe(v.string(), v.minLength(1)))
-  }),
-  v.check(
-    (val) => typeof val == "object" && val !== null && !Array.isArray(val),
-    "must be an object"
-  )
-), NullableString = v.union([v.null(), v.string()]), NullableNumber = v.union([v.null(), v.number()]), NullableBoolean = v.union([v.null(), v.boolean()]), NullableDateTime = v.union([
-  v.null(),
-  v.pipe(
-    v.string(),
-    v.check((s) => !Number.isNaN(Date.parse(s)), "must be an ISO-8601 datetime string")
-  )
-]), NullableUrl = NullableString, valueSchemas = {
-  "doc.ref": v.union([v.null(), GdrShape]),
-  "doc.refs": v.array(GdrShape),
-  "release.ref": v.union([v.null(), ReleaseRefShape]),
-  query: v.any(),
-  "value.string": NullableString,
-  "value.url": NullableUrl,
-  "value.number": NullableNumber,
-  "value.boolean": NullableBoolean,
-  "value.dateTime": NullableDateTime,
-  "value.actor": v.union([v.null(), ActorShape]),
-  checklist: v.array(ChecklistItemShape),
-  notes: v.array(NoteItemShape),
-  assignees: v.array(AssigneeShape)
-}, itemSchemas = {
-  "doc.refs": GdrShape,
-  checklist: ChecklistItemShape,
-  notes: NoteItemShape,
-  assignees: AssigneeShape
-};
-function isAppendable(entryType) {
-  return entryType in itemSchemas;
+const resourceKey = (r) => `${r.type}.${r.id}`;
+function guardsForResource(client) {
+  return client.fetch("*[_type == $t] | order(_id asc)", { t: GUARD_DOC_TYPE });
 }
-function validateStateValue(args) {
-  const schema = valueSchemas[args.entryType];
-  if (schema === void 0)
-    throw new StateValueShapeError({
-      entryType: args.entryType,
-      entryName: args.entryName,
-      issues: [`unknown state entry type ${args.entryType}`],
-      mode: "value"
-    });
-  const result = v.safeParse(schema, args.value);
-  if (!result.success)
-    throw new StateValueShapeError({
-      entryType: args.entryType,
-      entryName: args.entryName,
-      issues: formatIssues(result.issues),
-      mode: "value"
-    });
+function instanceGuardQuery(instanceId) {
+  return {
+    query: "*[_type == $guardType && sourceInstanceId == $instanceId]",
+    params: { guardType: GUARD_DOC_TYPE, instanceId }
+  };
 }
-function validateStateAppendItem(args) {
-  if (!isAppendable(args.entryType))
-    throw new StateValueShapeError({
-      entryType: args.entryType,
-      entryName: args.entryName,
-      issues: [`state entry type ${args.entryType} does not support append`],
-      mode: "item"
-    });
-  const schema = itemSchemas[args.entryType], result = v.safeParse(schema, args.item);
-  if (!result.success)
-    throw new StateValueShapeError({
-      entryType: args.entryType,
-      entryName: args.entryName,
-      issues: formatIssues(result.issues),
-      mode: "item"
-    });
+function verdictGuardsForInstance(client, instanceId) {
+  const { query, params } = instanceGuardQuery(instanceId);
+  return client.fetch(query, params);
 }
-function formatIssues(issues) {
-  return issues.map((i) => {
-    const keys = i.path?.map((p) => p.key) ?? [];
-    return `${keys.length > 0 ? `at ${keys.join(".")}: ` : ""}${i.message}`;
-  });
+async function guardsForInstance(args) {
+  const { client, clientForGdr, instance } = args, stateUris = [
+    ...collectEntryDocUris(instance.state),
+    ...instance.stages.flatMap((stage) => collectEntryDocUris(stage.state))
+  ], clients = resourceClientMap(
+    instance.workflowResource,
+    client,
+    clientForGdr,
+    stateUris.map((uri) => tryParseGdr(uri))
+  ), { query, params } = instanceGuardQuery(instance._id);
+  return queryGuardsAcross(clients.values(), query, params);
 }
-function derivePerspectiveFromState(entries) {
-  if (entries !== void 0) {
-    for (const entry of entries)
-      if (entry._type === "release.ref" && entry.value !== null) {
-        const releaseName = entry.value.releaseName;
-        if (typeof releaseName == "string" && releaseName.length > 0)
-          return [releaseName];
-      }
-  }
+async function guardsForDefinition(args) {
+  const perClient = await guardsForDefinitionByClient(args);
+  return dedupById(perClient.flatMap((entry) => entry.guards));
 }
-async function resolveDeclaredState(args) {
-  const { entryDefs, initialState, ctx, randomKey: randomKey2 } = args;
-  if (entryDefs === void 0 || entryDefs.length === 0) return [];
-  const out = [];
-  for (const entry of entryDefs) {
-    const scopedCtx = { ...ctx, resolvedState: out };
-    out.push(await resolveOneEntry(entry, initialState, scopedCtx, randomKey2));
-  }
-  return out;
+async function guardsForDefinitionByClient(args) {
+  const { client, clientForGdr, workflowResource, definition, definitions } = args, gdrs = definitions.flatMap(
+    (def) => guardIdRefs(def).map(({ idRef, stage }) => staticIdRefGdr(idRef, stage, def))
+  ), clients = resourceClientMap(workflowResource, client, clientForGdr, gdrs), query = "*[_type == $t && sourceDefinition == $definition]", params = { t: GUARD_DOC_TYPE, definition };
+  return Promise.all(
+    [...clients.values()].map(async (resourceClient) => ({
+      client: resourceClient,
+      guards: await resourceClient.fetch(query, params)
+    }))
+  );
 }
-const ARRAY_SLOT_TYPES = /* @__PURE__ */ new Set([
-  "doc.refs",
-  "checklist",
-  "notes",
-  "assignees"
-]);
-function defaultEntryValue(entryType) {
-  return ARRAY_SLOT_TYPES.has(entryType) ? [] : null;
+function guardIdRefs(definition) {
+  return definition.stages.flatMap(
+    (stage) => (stage.guards ?? []).flatMap(
+      (guard) => (guard.match.idRefs ?? []).map((idRef) => ({ idRef, stage }))
+    )
+  );
 }
-function resolveInitValue(entry, initialState, defaultValue) {
-  const initMatch = initialState.find((s) => s.name === entry.name && s.type === entry.type);
-  return initMatch === void 0 ? defaultValue : (assertInitValueShape(entry, initMatch.value), initMatch.value);
+function staticIdRefGdr(idRef, stage, definition) {
+  const read = /^\$state\.([\w-]+)/.exec(idRef);
+  if (read === null) return;
+  const source = entriesInScope(stage, definition).find((e) => e.name === read[1])?.source;
+  return source?.type === "literal" ? gdrFromValue(source.value) : void 0;
 }
-function resolveStateReadValue(source, ctx, defaultValue) {
+function entriesInScope(stage, definition) {
+  return [
+    ...definition.state ?? [],
+    ...stage.state ?? [],
+    ...(stage.tasks ?? []).flatMap((task) => task.state ?? [])
+  ];
+}
+function gdrFromValue(value) {
+  if (typeof value == "string") return tryParseGdr(value);
+  if (typeof value == "object" && value !== null && "id" in value) {
+    const id = value.id;
+    return typeof id == "string" ? tryParseGdr(id) : void 0;
+  }
+}
+function tryParseGdr(uri) {
+  try {
+    return parseGdr(uri);
+  } catch {
+    return;
+  }
+}
+function resourceClientMap(base, baseClient, clientForGdr, gdrs) {
+  const map = /* @__PURE__ */ new Map([[resourceKey(base), baseClient]]);
+  for (const parsed of gdrs) {
+    if (parsed === void 0) continue;
+    const key = resourceKey(resourceFromParsed(parsed));
+    map.has(key) || map.set(key, clientForGdr(parsed));
+  }
+  return map;
+}
+async function queryGuardsAcross(clients, query, params) {
+  const perResource = await Promise.all(
+    [...clients].map((c) => c.fetch(query, params))
+  );
+  return dedupById(perResource.flat());
+}
+function dedupById(guards) {
+  return [...new Map(guards.map((g) => [g._id, g])).values()].sort((a, b) => a._id.localeCompare(b._id));
+}
+const TAG_RE = /^[a-z0-9][a-z0-9-]*$/;
+function validateTags(tags) {
+  if (tags.length === 0)
+    throw new Error("tags: must be a non-empty array");
+  for (const tag of tags)
+    if (!TAG_RE.test(tag))
+      throw new Error(
+        `tags: invalid tag "${tag}" \u2014 must match ${TAG_RE.source} (ASCII lowercase + digits + dashes, no leading dash, no dots)`
+      );
+}
+function canonicalTag(tags) {
+  return tags[0];
+}
+function tagScopeFilter(param = "engineTags") {
+  return `count(tags[@ in $${param}]) > 0`;
+}
+const GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
+function resolveGuard(guard, instance, stageName, now) {
+  const ctx = { instance, now }, targets = resolveIdRefTargets(guard.match.idRefs, ctx);
+  if (targets === null) return null;
+  const resource = assertSingleResource(targets), types = resolveMatchTypes(targets, guard.match.types);
+  return { doc: compileGuard({
+    id: lakeGuardId({ instanceDocId: instance._id, guardName: guard.name }),
+    resourceType: resource.type,
+    resourceId: resource.id,
+    owner: GUARD_OWNER,
+    sourceInstanceId: instance._id,
+    sourceDefinition: instance.definition,
+    sourceStage: stageName,
+    name: guard.name,
+    ...guard.description !== void 0 ? { description: guard.description } : {},
+    match: {
+      ...types !== void 0 ? { types } : {},
+      idRefs: bareIdRefs(targets),
+      ...guard.match.idPatterns !== void 0 ? { idPatterns: guard.match.idPatterns } : {},
+      actions: guard.match.actions
+    },
+    predicate: guard.predicate ?? "",
+    metadata: resolveMetadata(guard.metadata, ctx)
+  }), routeGdr: targets[0].parsed };
+}
+async function upsertGuard(client, doc) {
+  if (!await client.getDocument(doc._id)) {
+    await client.create(doc);
+    return;
+  }
+  const { _id, _type, _rev, _createdAt, _updatedAt, ...body } = doc;
+  await client.patch(doc._id).set(body).commit();
+}
+function resolvedStageGuards(args) {
+  const stage = args.definition.stages.find((s) => s.name === args.stageName), out = [];
+  for (const guard of stage?.guards ?? []) {
+    const resolved = resolveGuard(guard, args.instance, args.stageName, args.now);
+    resolved !== null && out.push({ client: args.clientForGdr(resolved.routeGdr), doc: resolved.doc });
+  }
+  return out;
+}
+async function committedInstance(args) {
+  return await args.client.getDocument(args.instance._id) ?? void 0;
+}
+async function deployStageGuards(args) {
+  const live = await committedInstance(args);
+  if (!(live === void 0 || live.currentStage !== args.stageName) && live.abortedAt === void 0)
+    for (const { client, doc } of resolvedStageGuards(args))
+      await upsertGuard(client, doc);
+}
+async function retractStageGuards(args) {
+  const live = await committedInstance(args);
+  if (live !== void 0 && !(live.currentStage === args.stageName && live.abortedAt === void 0))
+    for (const { client, doc } of resolvedStageGuards(args))
+      await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit();
+}
+async function deleteOrphanedDefinitionGuards(args) {
+  const { client, clientForGdr, workflowResource, definition, definitions, tags } = args, perClient = await guardsForDefinitionByClient({
+    client,
+    clientForGdr,
+    workflowResource,
+    definition,
+    definitions
+  }), ownPartitionPrefix = `${canonicalTag(tags)}.`;
+  let count = 0;
+  for (const { client: resourceClient, guards } of perClient) {
+    const own = guards.filter((guard) => guard.sourceInstanceId.startsWith(ownPartitionPrefix));
+    if (own.length === 0) continue;
+    const tx = resourceClient.transaction();
+    for (const guard of own) tx.delete(guard._id);
+    await tx.commit(), count += own.length;
+  }
+  return count;
+}
+function randomKey(length = 12) {
+  const bytes = new Uint8Array(length);
+  return globalThis.crypto.getRandomValues(bytes), [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, length);
+}
+async function evaluateCondition(args) {
+  const { condition, snapshot, params } = args;
+  return condition === void 0 ? !0 : !!await runGroq(condition, params, snapshot);
+}
+async function evaluatePredicates(args) {
+  const out = {};
+  for (const [name, groq] of Object.entries(args.predicates ?? {}))
+    out[name] = !!await runGroq(groq, args.params, args.snapshot);
+  return out;
+}
+async function runGroq(groq, params, snapshot) {
+  const tree = parse(groq, { params });
+  return (await evaluate(tree, { dataset: snapshot.docs, params })).get();
+}
+class StateValueShapeError extends Error {
+  entryType;
+  entryName;
+  issues;
+  constructor(args) {
+    const issueText = args.issues.join("; ");
+    super(
+      `State entry ${args.mode} shape invalid for "${args.entryName}" (${args.entryType}): ${issueText}`
+    ), this.name = "StateValueShapeError", this.entryType = args.entryType, this.entryName = args.entryName, this.issues = args.issues;
+  }
+}
+const GdrShape = v.looseObject({
+  id: v.pipe(
+    v.string(),
+    v.check((s) => isGdrUri(s), "must be a GDR URI")
+  ),
+  type: v.pipe(v.string(), v.minLength(1))
+}), ReleaseRefShape = v.looseObject({
+  id: v.pipe(
+    v.string(),
+    v.check((s) => isGdrUri(s), "must be a GDR URI")
+  ),
+  type: v.literal("system.release"),
+  releaseName: v.pipe(v.string(), v.minLength(1))
+}), ActorShape = v.looseObject({
+  kind: v.picklist(["user", "ai", "system"]),
+  id: v.pipe(v.string(), v.minLength(1)),
+  roles: v.optional(v.array(v.string())),
+  onBehalfOf: v.optional(v.string())
+}), AssigneeShape = v.union([
+  v.looseObject({ type: v.literal("user"), id: v.pipe(v.string(), v.minLength(1)) }),
+  v.looseObject({ type: v.literal("role"), role: v.pipe(v.string(), v.minLength(1)) })
+]), ChecklistItemShape = v.looseObject({
+  label: v.pipe(v.string(), v.minLength(1)),
+  done: v.boolean(),
+  doneBy: v.optional(v.string()),
+  doneAt: v.optional(v.string()),
+  _key: v.optional(v.pipe(v.string(), v.minLength(1)))
+}), NoteItemShape = v.pipe(
+  v.looseObject({
+    _key: v.optional(v.pipe(v.string(), v.minLength(1)))
+  }),
+  v.check(
+    (val) => typeof val == "object" && val !== null && !Array.isArray(val),
+    "must be an object"
+  )
+), NullableString = v.union([v.null(), v.string()]), NullableNumber = v.union([v.null(), v.number()]), NullableBoolean = v.union([v.null(), v.boolean()]), NullableDateTime = v.union([
+  v.null(),
+  v.pipe(
+    v.string(),
+    v.check((s) => !Number.isNaN(Date.parse(s)), "must be an ISO-8601 datetime string")
+  )
+]), NullableUrl = NullableString, valueSchemas = {
+  "doc.ref": v.union([v.null(), GdrShape]),
+  "doc.refs": v.array(GdrShape),
+  "release.ref": v.union([v.null(), ReleaseRefShape]),
+  query: v.any(),
+  "value.string": NullableString,
+  "value.url": NullableUrl,
+  "value.number": NullableNumber,
+  "value.boolean": NullableBoolean,
+  "value.dateTime": NullableDateTime,
+  "value.actor": v.union([v.null(), ActorShape]),
+  checklist: v.array(ChecklistItemShape),
+  notes: v.array(NoteItemShape),
+  assignees: v.array(AssigneeShape)
+}, itemSchemas = {
+  "doc.refs": GdrShape,
+  checklist: ChecklistItemShape,
+  notes: NoteItemShape,
+  assignees: AssigneeShape
+};
+function isAppendable(entryType) {
+  return entryType in itemSchemas;
+}
+function validateStateValue(args) {
+  const schema = valueSchemas[args.entryType];
+  if (schema === void 0)
+    throw new StateValueShapeError({
+      entryType: args.entryType,
+      entryName: args.entryName,
+      issues: [`unknown state entry type ${args.entryType}`],
+      mode: "value"
+    });
+  const result = v.safeParse(schema, args.value);
+  if (!result.success)
+    throw new StateValueShapeError({
+      entryType: args.entryType,
+      entryName: args.entryName,
+      issues: formatIssues(result.issues),
+      mode: "value"
+    });
+}
+function validateStateAppendItem(args) {
+  if (!isAppendable(args.entryType))
+    throw new StateValueShapeError({
+      entryType: args.entryType,
+      entryName: args.entryName,
+      issues: [`state entry type ${args.entryType} does not support append`],
+      mode: "item"
+    });
+  const schema = itemSchemas[args.entryType], result = v.safeParse(schema, args.item);
+  if (!result.success)
+    throw new StateValueShapeError({
+      entryType: args.entryType,
+      entryName: args.entryName,
+      issues: formatIssues(result.issues),
+      mode: "item"
+    });
+}
+function formatIssues(issues) {
+  return issues.map((i) => {
+    const keys = i.path?.map((p) => p.key) ?? [];
+    return `${keys.length > 0 ? `at ${keys.join(".")}: ` : ""}${i.message}`;
+  });
+}
+function derivePerspectiveFromState(entries) {
+  if (entries !== void 0) {
+    for (const entry of entries)
+      if (entry._type === "release.ref" && entry.value !== null) {
+        const releaseName = entry.value.releaseName;
+        if (typeof releaseName == "string" && releaseName.length > 0)
+          return [releaseName];
+      }
+  }
+}
+async function resolveDeclaredState(args) {
+  const { entryDefs, initialState, ctx, randomKey: randomKey2 } = args;
+  if (entryDefs === void 0 || entryDefs.length === 0) return [];
+  const out = [];
+  for (const entry of entryDefs) {
+    const scopedCtx = { ...ctx, resolvedState: out };
+    out.push(await resolveOneEntry(entry, initialState, scopedCtx, randomKey2));
+  }
+  return out;
+}
+const ARRAY_SLOT_TYPES = /* @__PURE__ */ new Set([
+  "doc.refs",
+  "checklist",
+  "notes",
+  "assignees"
+]);
+function defaultEntryValue(entryType) {
+  return ARRAY_SLOT_TYPES.has(entryType) ? [] : null;
+}
+function resolveInitValue(entry, initialState, defaultValue) {
+  const initMatch = initialState.find((s) => s.name === entry.name && s.type === entry.type);
+  return initMatch === void 0 ? defaultValue : (assertInitValueShape(entry, initMatch.value), initMatch.value);
+}
+function resolveStateReadValue(source, ctx, defaultValue) {
   const target = (source.scope === "workflow" ? ctx.workflowState ?? [] : ctx.resolvedState ?? []).find((s) => s.name === source.state), targetValue = target === void 0 ? void 0 : target.value;
   return (source.path !== void 0 ? getPath(targetValue, source.path) : targetValue) ?? defaultValue;
 }
@@ -963,77 +1162,30 @@ async function resolveStageStateEntries(args) {
       workflowResource: instance.workflowResource,
       // Allow stage-scope entries' `source: { type: "stateRead", scope:
       // "workflow", ... }` to see the already-resolved workflow-scope state.
-      workflowState: instance.state ?? [],
-      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
-    },
-    randomKey
-  });
-}
-async function resolveTaskStateEntries(args) {
-  const { client, instance, stage, task, now } = args;
-  return resolveDeclaredState({
-    entryDefs: task.state,
-    initialState: [],
-    ctx: {
-      client,
-      now,
-      selfId: instance._id,
-      tags: instance.tags ?? [],
-      stageName: stage.name,
-      workflowResource: instance.workflowResource,
-      taskName: task.name,
-      workflowState: instance.state ?? [],
-      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
-    },
-    randomKey
-  });
-}
-async function resolveBindings(args) {
-  const resolved = {};
-  for (const [key, groq] of Object.entries(args.bindings ?? {}))
-    resolved[key] = await runGroq(groq, args.params, args.snapshot);
-  return { ...resolved, ...args.staticInput };
-}
-function effectsContextEntry(name, value) {
-  const _key = randomKey();
-  return typeof value == "string" ? { _key, _type: "effectsContext.string", name, value } : typeof value == "number" ? { _key, _type: "effectsContext.number", name, value } : typeof value == "boolean" ? { _key, _type: "effectsContext.boolean", name, value } : { _key, _type: "effectsContext.ref", name, value };
-}
-function effectsContextJsonEntry(name, value) {
-  return { _key: randomKey(), _type: "effectsContext.json", name, value: JSON.stringify(value) };
-}
-function buildInstanceBase(args) {
-  const { id, now, actor, perspective } = args;
-  return {
-    _id: id,
-    _type: WORKFLOW_INSTANCE_TYPE,
-    _rev: "",
-    _createdAt: now,
-    _updatedAt: now,
-    tags: args.tags,
-    workflowResource: args.workflowResource,
-    definition: args.definitionName,
-    pinnedVersion: args.pinnedVersion,
-    definitionSnapshot: JSON.stringify(args.definition),
-    state: args.state,
-    effectsContext: args.effectsContext,
-    ancestors: args.ancestors,
-    ...perspective !== void 0 ? { perspective } : {},
-    currentStage: args.initialStage,
-    stages: [],
-    pendingEffects: [],
-    effectHistory: [],
-    history: [
-      {
-        _key: randomKey(),
-        _type: "stageEntered",
-        at: now,
-        stage: args.initialStage,
-        ...actor !== void 0 ? { actor } : {}
-      }
-    ],
-    startedAt: now,
-    lastChangedAt: now
-  };
+      workflowState: instance.state ?? [],
+      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
+    },
+    randomKey
+  });
+}
+async function resolveTaskStateEntries(args) {
+  const { client, instance, stage, task, now } = args;
+  return resolveDeclaredState({
+    entryDefs: task.state,
+    initialState: [],
+    ctx: {
+      client,
+      now,
+      selfId: instance._id,
+      tags: instance.tags ?? [],
+      stageName: stage.name,
+      workflowResource: instance.workflowResource,
+      taskName: task.name,
+      workflowState: instance.state ?? [],
+      ...instance.perspective !== void 0 ? { perspective: instance.perspective } : {}
+    },
+    randomKey
+  });
 }
 class ActionParamsInvalidError extends Error {
   action;
@@ -1154,21 +1306,98 @@ function stageTransitionHistory(args) {
     }
   ];
 }
-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 startMutation(instance) {
+  return {
+    currentStage: instance.currentStage,
+    // Deep-ish copy. Per-scope state entry 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((entry) => ({ ...entry })),
+      tasks: s.tasks.map((t) => ({
+        ...t,
+        ...t.state !== void 0 ? { state: t.state.map((entry) => ({ ...entry })) } : {}
+      }))
+    })),
+    pendingEffects: [...instance.pendingEffects],
+    effectHistory: [...instance.effectHistory],
+    effectsContext: [...instance.effectsContext],
+    history: [...instance.history],
+    lastChangedAt: instance.lastChangedAt,
+    ...instance.completedAt !== void 0 ? { completedAt: instance.completedAt } : {},
+    ...instance.abortedAt !== void 0 ? { abortedAt: instance.abortedAt } : {},
+    pendingCreates: []
+  };
 }
-function canonicalTag(tags) {
-  return tags[0];
+function instanceStateFields(src) {
+  const fields = {
+    currentStage: src.currentStage,
+    state: src.state,
+    stages: src.stages,
+    pendingEffects: src.pendingEffects,
+    effectHistory: src.effectHistory,
+    effectsContext: src.effectsContext,
+    history: src.history
+  };
+  return src.completedAt !== void 0 && (fields.completedAt = src.completedAt), src.abortedAt !== void 0 && (fields.abortedAt = src.abortedAt), fields;
 }
-function tagScopeFilter(param = "engineTags") {
-  return `count(tags[@ in $${param}]) > 0`;
+function materializeInstance(base, mutation) {
+  return {
+    ...base,
+    currentStage: mutation.currentStage,
+    state: mutation.state,
+    stages: mutation.stages
+  };
+}
+async function persist(ctx, mutation) {
+  const set = {
+    ...instanceStateFields(mutation),
+    lastChangedAt: ctx.now
+  }, pendingCreates = mutation.pendingCreates;
+  if (pendingCreates.length === 0)
+    return ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev).commit();
+  const tx = ctx.client.transaction();
+  for (const body of pendingCreates) tx.create(body);
+  tx.patch(ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev)), await tx.commit(), mutation.pendingCreates = [];
+  const actorForPriming = void 0;
+  for (const body of pendingCreates)
+    await primeInitialStage(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await cascadeAutoTransitions(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await propagateToAncestors(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock);
+  const reloaded = await ctx.client.getDocument(ctx.instance._id);
+  if (!reloaded)
+    throw new Error(`Instance ${ctx.instance._id} disappeared after transaction commit`);
+  return reloaded;
+}
+function currentStageEntry(mutation) {
+  const entry = findOpenStageEntry(mutation);
+  if (entry === void 0)
+    throw new Error(
+      `Mutation invariant broken: no current (un-exited) StageEntry for currentStage "${mutation.currentStage}"`
+    );
+  return entry;
+}
+function currentTasks(mutation) {
+  return currentStageEntry(mutation).tasks;
+}
+function findTaskInCurrentStage(ctx, taskName) {
+  const stage = findStage(ctx.definition, ctx.instance.currentStage), task = (stage.tasks ?? []).find((t) => t.name === taskName);
+  if (task === void 0)
+    throw new Error(
+      `Task "${taskName}" not found in current stage "${stage.name}" of ${ctx.definition.name}`
+    );
+  return { stage, task };
+}
+function requireMutationTaskEntry(mutation, task) {
+  const mutEntry = currentTasks(mutation).find((t) => t.name === task);
+  if (mutEntry === void 0)
+    throw new Error(`Task "${task}" disappeared from mutation copy \u2014 invariant broken`);
+  return mutEntry;
+}
+function findCurrentStageEntry(instance) {
+  return findOpenStageEntry(instance);
+}
+function findCurrentTasks(instance) {
+  return findCurrentStageEntry(instance)?.tasks ?? [];
 }
 function definitionLookupGroq(explicit) {
   const scoped = `_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $definition && ${tagScopeFilter()}`;
@@ -1186,6 +1415,47 @@ function clientForDiscovery(defaultClient, clientForGdr, subjectGdrUri) {
     return defaultClient;
   }
 }
+function effectsContextEntry(name, value) {
+  const _key = randomKey();
+  return typeof value == "string" ? { _key, _type: "effectsContext.string", name, value } : typeof value == "number" ? { _key, _type: "effectsContext.number", name, value } : typeof value == "boolean" ? { _key, _type: "effectsContext.boolean", name, value } : { _key, _type: "effectsContext.ref", name, value };
+}
+function effectsContextJsonEntry(name, value) {
+  return { _key: randomKey(), _type: "effectsContext.json", name, value: JSON.stringify(value) };
+}
+function buildInstanceBase(args) {
+  const { id, now, actor, perspective } = args;
+  return {
+    _id: id,
+    _type: WORKFLOW_INSTANCE_TYPE,
+    _rev: "",
+    _createdAt: now,
+    _updatedAt: now,
+    tags: args.tags,
+    workflowResource: args.workflowResource,
+    definition: args.definitionName,
+    pinnedVersion: args.pinnedVersion,
+    definitionSnapshot: JSON.stringify(args.definition),
+    state: args.state,
+    effectsContext: args.effectsContext,
+    ancestors: args.ancestors,
+    ...perspective !== void 0 ? { perspective } : {},
+    currentStage: args.initialStage,
+    stages: [],
+    pendingEffects: [],
+    effectHistory: [],
+    history: [
+      {
+        _key: randomKey(),
+        _type: "stageEntered",
+        at: now,
+        stage: args.initialStage,
+        ...actor !== void 0 ? { actor } : {}
+      }
+    ],
+    startedAt: now,
+    lastChangedAt: now
+  };
+}
 const MAX_SPAWN_DEPTH = 6, SUBWORKFLOWS_ALL_DONE = "count($subworkflows[status != 'done']) == 0", FAIL_WHEN_SYSTEM_ID = "engine.failWhen", COMPLETE_WHEN_SYSTEM_ID = "engine.completeWhen";
 function gateActor(outcome) {
   return {
@@ -1364,6 +1634,111 @@ async function subworkflowRows(ctx, refs) {
     status: c.completedAt !== void 0 && c.completedAt !== null ? "done" : "active"
   }));
 }
+async function resolveBindings(args) {
+  const resolved = {};
+  for (const [key, groq] of Object.entries(args.bindings ?? {}))
+    resolved[key] = await runGroq(groq, args.params, args.snapshot);
+  return { ...resolved, ...args.staticInput };
+}
+async function completeEffect(args) {
+  const { client, instanceId, effectKey, status, outputs, detail, error, durationMs, options } = args, ctx = await loadContext(client, instanceId, {
+    ...options?.clock ? { clock: options.clock } : {},
+    ...options?.clientForGdr ? { clientForGdr: options.clientForGdr } : {}
+  });
+  return commitCompleteEffect(
+    ctx,
+    effectKey,
+    status,
+    outputs,
+    detail,
+    error,
+    durationMs,
+    options?.actor
+  );
+}
+function buildEffectHistoryEntry(pending, outcome) {
+  const { status, ranAt, actor, detail, error, durationMs, outputs } = outcome, resolvedActor = actor ?? pending.actor;
+  return {
+    _key: pending._key,
+    name: pending.name,
+    ...pending.title !== void 0 ? { title: pending.title } : {},
+    ...pending.description !== void 0 ? { description: pending.description } : {},
+    params: pending.params,
+    origin: pending.origin,
+    ...resolvedActor !== void 0 ? { actor: resolvedActor } : {},
+    ranAt,
+    ...durationMs !== void 0 ? { durationMs } : {},
+    status,
+    ...detail !== void 0 ? { detail } : {},
+    ...error !== void 0 ? { error } : {},
+    ...outputs !== void 0 ? { outputs } : {}
+  };
+}
+function upsertEffectsContext(mutation, effectName, outputs) {
+  const existingIndex = mutation.effectsContext.findIndex((e) => e.name === effectName), entry = effectsContextJsonEntry(effectName, outputs);
+  existingIndex >= 0 ? mutation.effectsContext[existingIndex] = entry : mutation.effectsContext.push(entry);
+}
+async function commitCompleteEffect(ctx, effectKey, status, outputs, detail, error, durationMs, actor) {
+  const pending = ctx.instance.pendingEffects.find((e) => e._key === effectKey);
+  if (pending === void 0)
+    throw new Error(`Pending effect "${effectKey}" not found on instance ${ctx.instance._id}`);
+  const mutation = startMutation(ctx.instance);
+  mutation.pendingEffects = mutation.pendingEffects.filter((e) => e._key !== effectKey);
+  const ranAt = ctx.now;
+  return mutation.effectHistory.push(
+    buildEffectHistoryEntry(pending, { status, ranAt, actor, detail, error, durationMs, outputs })
+  ), status === "done" && outputs !== void 0 && upsertEffectsContext(mutation, pending.name, outputs), mutation.history.push({
+    _key: randomKey(),
+    _type: "effectCompleted",
+    at: ranAt,
+    effectKey,
+    effect: pending.name,
+    status,
+    ...outputs !== void 0 ? { outputs } : {},
+    ...detail !== void 0 ? { detail } : {},
+    ...actor !== void 0 ? { actor } : {}
+  }), await persist(ctx, mutation), { effectKey, status };
+}
+function buildQueuedEffect(effect, origin, params, actor, now) {
+  const key = randomKey(), pending = {
+    _key: key,
+    _type: "pendingEffect",
+    name: effect.name,
+    ...effect.title !== void 0 ? { title: effect.title } : {},
+    ...effect.description !== void 0 ? { description: effect.description } : {},
+    ...effect.bindings !== void 0 ? { bindings: effect.bindings } : {},
+    params,
+    origin,
+    ...actor !== void 0 ? { actor } : {},
+    queuedAt: now
+  }, history = {
+    _key: randomKey(),
+    _type: "effectQueued",
+    at: now,
+    effectKey: key,
+    effect: effect.name,
+    origin
+  };
+  return { pending, history };
+}
+async function queueEffects(ctx, mutation, effects, origin, actor, opts) {
+  if (!effects || effects.length === 0) return;
+  const now = ctx.now, liveCtx = { ...ctx, instance: materializeInstance(ctx.instance, mutation) }, params = await ctxConditionParams(liveCtx, {
+    ...opts?.taskName !== void 0 ? { taskName: opts.taskName } : {},
+    ...actor !== void 0 ? { actor } : {},
+    // Caller-supplied action params, readable in bindings as `$params.<name>`.
+    vars: { params: opts?.callerParams ?? {} }
+  });
+  for (const effect of effects) {
+    const resolved = await resolveBindings({
+      bindings: effect.bindings,
+      staticInput: effect.input,
+      snapshot: ctx.snapshot,
+      params
+    }), { pending, history } = buildQueuedEffect(effect, origin, resolved, actor, now);
+    mutation.pendingEffects.push(pending), mutation.history.push(history);
+  }
+}
 function resolveStaticSource(src, ctx) {
   switch (src.type) {
     case "literal":
@@ -1593,7 +1968,8 @@ function evalOpPredicate(p, row, ctx) {
 }
 async function invokeTask(args) {
   const { client, instanceId, task: taskName, options } = args, ctx = await loadContext(client, instanceId, {
-    ...options?.clock ? { clock: options.clock } : {}
+    ...options?.clock ? { clock: options.clock } : {},
+    ...options?.clientForGdr ? { clientForGdr: options.clientForGdr } : {}
   });
   return commitInvoke(ctx, taskName, options?.actor);
 }
@@ -1701,7 +2077,8 @@ function isTerminalStage(stage) {
 }
 async function setStage(args) {
   const { client, instanceId, targetStage, reason, options } = args, ctx = await loadContext(client, instanceId, {
-    ...options?.clock ? { clock: options.clock } : {}
+    ...options?.clock ? { clock: options.clock } : {},
+    ...options?.clientForGdr ? { clientForGdr: options.clientForGdr } : {}
   });
   return commitSetStage(ctx, targetStage, reason, options?.actor);
 }
@@ -1952,287 +2329,58 @@ async function cascadeAutoTransitions(client, instanceId, actor, clientForGdr, c
   let count = 0;
   for (; ; ) {
     if (await resolveCompleteWhen(client, instanceId, clientForGdr, clock, overlay), !(await evaluateAutoTransitions({
-      client,
-      instanceId,
-      ...actor !== void 0 ? { options: { actor } } : {},
-      ...clientForGdr ? { clientForGdr } : {},
-      ...clock ? { clock } : {},
-      ...overlay ? { overlay } : {}
-    })).fired) return count;
-    if (count++, count >= CASCADE_LIMIT)
-      throw new CascadeLimitError({ instanceId, limit: CASCADE_LIMIT });
-  }
-}
-async function findResolvedParentSpawn(client, child, clientForGdr, clock) {
-  const parentRef = child.ancestors.at(-1);
-  if (parentRef === void 0) return;
-  const parent = await client.getDocument(gdrToBareId(parentRef.id));
-  if (!parent || parent._type !== WORKFLOW_INSTANCE_TYPE || typeof parent.definitionSnapshot != "string") return;
-  const definition = parseDefinitionSnapshot(parent), stage = definition.stages.find((s) => s.name === parent.currentStage);
-  if (stage === void 0) return;
-  const parentCurrentTasks = findCurrentTasks(parent), task = (stage.tasks ?? []).find((t) => t.subworkflows === void 0 ? !1 : parentCurrentTasks.find((e) => e.name === t.name)?.spawnedInstances?.some((r) => gdrToBareId(r.id) === child._id) ?? !1);
-  if (task?.subworkflows === void 0) return;
-  const entry = parentCurrentTasks.find((e) => e.name === task.name);
-  if (entry === void 0 || entry.status !== "active") return;
-  const ctx = await buildEngineContext({
-    client,
-    clientForGdr,
-    instance: parent,
-    definition,
-    ...clock ? { clock } : {}
-  }), outcome = await evaluateResolutionGate(ctx, task, await taskConditionVars(ctx, entry));
-  if (outcome !== void 0)
-    return { parent, definition, stage, task, outcome };
-}
-async function propagateToAncestors(client, instanceId, actor, clientForGdr, clock) {
-  const instance = await client.getDocument(instanceId);
-  if (!instance) return;
-  const resolvedClientForGdr = clientForGdr ?? (() => client), found = await findResolvedParentSpawn(client, instance, resolvedClientForGdr, clock);
-  if (found === void 0) return;
-  const { parent, definition, stage, task, outcome } = found, ctx = await buildEngineContext({
-    client,
-    clientForGdr: resolvedClientForGdr,
-    instance: parent,
-    definition,
-    ...clock ? { clock } : {}
-  }), mutation = startMutation(parent), mutEntry = currentTasks(mutation).find((e) => e.name === task.name);
-  mutEntry !== void 0 && (applyTaskStatusChange({
-    entry: mutEntry,
-    history: mutation.history,
-    stage: stage.name,
-    to: outcome,
-    at: ctx.now,
-    actor: gateActor(outcome)
-  }), await persist(ctx, mutation), await cascadeAutoTransitions(client, parent._id, actor, clientForGdr, clock), await propagateToAncestors(client, parent._id, actor, clientForGdr, clock));
-}
-function startMutation(instance) {
-  return {
-    currentStage: instance.currentStage,
-    // Deep-ish copy. Per-scope state entry 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((entry) => ({ ...entry })),
-      tasks: s.tasks.map((t) => ({
-        ...t,
-        ...t.state !== void 0 ? { state: t.state.map((entry) => ({ ...entry })) } : {}
-      }))
-    })),
-    pendingEffects: [...instance.pendingEffects],
-    effectHistory: [...instance.effectHistory],
-    effectsContext: [...instance.effectsContext],
-    history: [...instance.history],
-    lastChangedAt: instance.lastChangedAt,
-    ...instance.completedAt !== void 0 ? { completedAt: instance.completedAt } : {},
-    ...instance.abortedAt !== void 0 ? { abortedAt: instance.abortedAt } : {},
-    pendingCreates: []
-  };
-}
-function instanceStateFields(src) {
-  const fields = {
-    currentStage: src.currentStage,
-    state: src.state,
-    stages: src.stages,
-    pendingEffects: src.pendingEffects,
-    effectHistory: src.effectHistory,
-    effectsContext: src.effectsContext,
-    history: src.history
-  };
-  return src.completedAt !== void 0 && (fields.completedAt = src.completedAt), src.abortedAt !== void 0 && (fields.abortedAt = src.abortedAt), fields;
-}
-function materializeInstance(base, mutation) {
-  return {
-    ...base,
-    currentStage: mutation.currentStage,
-    state: mutation.state,
-    stages: mutation.stages
-  };
-}
-async function persist(ctx, mutation) {
-  const set = {
-    ...instanceStateFields(mutation),
-    lastChangedAt: ctx.now
-  }, pendingCreates = mutation.pendingCreates;
-  if (pendingCreates.length === 0)
-    return ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev).commit();
-  const tx = ctx.client.transaction();
-  for (const body of pendingCreates) tx.create(body);
-  tx.patch(ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev)), await tx.commit(), mutation.pendingCreates = [];
-  const actorForPriming = void 0;
-  for (const body of pendingCreates)
-    await primeInitialStage(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await cascadeAutoTransitions(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock), await propagateToAncestors(ctx.client, body._id, actorForPriming, ctx.clientForGdr, ctx.clock);
-  const reloaded = await ctx.client.getDocument(ctx.instance._id);
-  if (!reloaded)
-    throw new Error(`Instance ${ctx.instance._id} disappeared after transaction commit`);
-  return reloaded;
-}
-function currentStageEntry(mutation) {
-  const entry = findOpenStageEntry(mutation);
-  if (entry === void 0)
-    throw new Error(
-      `Mutation invariant broken: no current (un-exited) StageEntry for currentStage "${mutation.currentStage}"`
-    );
-  return entry;
-}
-function currentTasks(mutation) {
-  return currentStageEntry(mutation).tasks;
-}
-function findTaskInCurrentStage(ctx, taskName) {
-  const stage = findStage(ctx.definition, ctx.instance.currentStage), task = (stage.tasks ?? []).find((t) => t.name === taskName);
-  if (task === void 0)
-    throw new Error(
-      `Task "${taskName}" not found in current stage "${stage.name}" of ${ctx.definition.name}`
-    );
-  return { stage, task };
-}
-function requireMutationTaskEntry(mutation, task) {
-  const mutEntry = currentTasks(mutation).find((t) => t.name === task);
-  if (mutEntry === void 0)
-    throw new Error(`Task "${task}" 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, {
-    ...options?.clock ? { clock: options.clock } : {}
-  });
-  return commitCompleteEffect(
-    ctx,
-    effectKey,
-    status,
-    outputs,
-    detail,
-    error,
-    durationMs,
-    options?.actor
-  );
-}
-function buildEffectHistoryEntry(pending, outcome) {
-  const { status, ranAt, actor, detail, error, durationMs, outputs } = outcome, resolvedActor = actor ?? pending.actor;
-  return {
-    _key: pending._key,
-    name: pending.name,
-    ...pending.title !== void 0 ? { title: pending.title } : {},
-    ...pending.description !== void 0 ? { description: pending.description } : {},
-    params: pending.params,
-    origin: pending.origin,
-    ...resolvedActor !== void 0 ? { actor: resolvedActor } : {},
-    ranAt,
-    ...durationMs !== void 0 ? { durationMs } : {},
-    status,
-    ...detail !== void 0 ? { detail } : {},
-    ...error !== void 0 ? { error } : {},
-    ...outputs !== void 0 ? { outputs } : {}
-  };
-}
-function upsertEffectsContext(mutation, effectName, outputs) {
-  const existingIndex = mutation.effectsContext.findIndex((e) => e.name === effectName), entry = effectsContextJsonEntry(effectName, outputs);
-  existingIndex >= 0 ? mutation.effectsContext[existingIndex] = entry : mutation.effectsContext.push(entry);
-}
-async function commitCompleteEffect(ctx, effectKey, status, outputs, detail, error, durationMs, actor) {
-  const pending = ctx.instance.pendingEffects.find((e) => e._key === effectKey);
-  if (pending === void 0)
-    throw new Error(`Pending effect "${effectKey}" not found on instance ${ctx.instance._id}`);
-  const mutation = startMutation(ctx.instance);
-  mutation.pendingEffects = mutation.pendingEffects.filter((e) => e._key !== effectKey);
-  const ranAt = ctx.now;
-  return mutation.effectHistory.push(
-    buildEffectHistoryEntry(pending, { status, ranAt, actor, detail, error, durationMs, outputs })
-  ), status === "done" && outputs !== void 0 && upsertEffectsContext(mutation, pending.name, outputs), mutation.history.push({
-    _key: randomKey(),
-    _type: "effectCompleted",
-    at: ranAt,
-    effectKey,
-    effect: pending.name,
-    status,
-    ...outputs !== void 0 ? { outputs } : {},
-    ...detail !== void 0 ? { detail } : {},
-    ...actor !== void 0 ? { actor } : {}
-  }), await persist(ctx, mutation), { effectKey, status };
-}
-function buildQueuedEffect(effect, origin, params, actor, now) {
-  const key = randomKey(), pending = {
-    _key: key,
-    _type: "pendingEffect",
-    name: effect.name,
-    ...effect.title !== void 0 ? { title: effect.title } : {},
-    ...effect.description !== void 0 ? { description: effect.description } : {},
-    ...effect.bindings !== void 0 ? { bindings: effect.bindings } : {},
-    params,
-    origin,
-    ...actor !== void 0 ? { actor } : {},
-    queuedAt: now
-  }, history = {
-    _key: randomKey(),
-    _type: "effectQueued",
-    at: now,
-    effectKey: key,
-    effect: effect.name,
-    origin
-  };
-  return { pending, history };
-}
-async function queueEffects(ctx, mutation, effects, origin, actor, opts) {
-  if (!effects || effects.length === 0) return;
-  const now = ctx.now, liveCtx = { ...ctx, instance: materializeInstance(ctx.instance, mutation) }, params = await ctxConditionParams(liveCtx, {
-    ...opts?.taskName !== void 0 ? { taskName: opts.taskName } : {},
-    ...actor !== void 0 ? { actor } : {},
-    // Caller-supplied action params, readable in bindings as `$params.<name>`.
-    vars: { params: opts?.callerParams ?? {} }
-  });
-  for (const effect of effects) {
-    const resolved = await resolveBindings({
-      bindings: effect.bindings,
-      staticInput: effect.input,
-      snapshot: ctx.snapshot,
-      params
-    }), { pending, history } = buildQueuedEffect(effect, origin, resolved, actor, now);
-    mutation.pendingEffects.push(pending), mutation.history.push(history);
+      client,
+      instanceId,
+      ...actor !== void 0 ? { options: { actor } } : {},
+      ...clientForGdr ? { clientForGdr } : {},
+      ...clock ? { clock } : {},
+      ...overlay ? { overlay } : {}
+    })).fired) return count;
+    if (count++, count >= CASCADE_LIMIT)
+      throw new CascadeLimitError({ instanceId, limit: CASCADE_LIMIT });
   }
 }
-async function abortInstance(args) {
-  const { client, instanceId, reason, options } = args, ctx = await loadContext(client, instanceId, {
-    ...options?.clock ? { clock: options.clock } : {}
-  });
-  return commitAbort(ctx, reason, options?.actor);
+async function findResolvedParentSpawn(client, child, clientForGdr, clock) {
+  const parentRef = child.ancestors.at(-1);
+  if (parentRef === void 0) return;
+  const parent = await client.getDocument(gdrToBareId(parentRef.id));
+  if (!parent || parent._type !== WORKFLOW_INSTANCE_TYPE || typeof parent.definitionSnapshot != "string") return;
+  const definition = parseDefinitionSnapshot(parent), stage = definition.stages.find((s) => s.name === parent.currentStage);
+  if (stage === void 0) return;
+  const parentCurrentTasks = findCurrentTasks(parent), task = (stage.tasks ?? []).find((t) => t.subworkflows === void 0 ? !1 : parentCurrentTasks.find((e) => e.name === t.name)?.spawnedInstances?.some((r) => gdrToBareId(r.id) === child._id) ?? !1);
+  if (task?.subworkflows === void 0) return;
+  const entry = parentCurrentTasks.find((e) => e.name === task.name);
+  if (entry === void 0 || entry.status !== "active") return;
+  const ctx = await buildEngineContext({
+    client,
+    clientForGdr,
+    instance: parent,
+    definition,
+    ...clock ? { clock } : {}
+  }), outcome = await evaluateResolutionGate(ctx, task, await taskConditionVars(ctx, entry));
+  if (outcome !== void 0)
+    return { parent, definition, stage, task, outcome };
 }
-async function commitAbort(ctx, reason, actor) {
-  if (ctx.instance.completedAt !== void 0)
-    return { fired: !1 };
-  const stage = findStage(ctx.definition, ctx.instance.currentStage), mutation = startMutation(ctx.instance), at = ctx.now, openEntry = findOpenStageEntry(mutation);
-  return openEntry !== void 0 && (openEntry.exitedAt = at), mutation.effectHistory.push(
-    ...mutation.pendingEffects.map(
-      (pending) => buildEffectHistoryEntry(pending, {
-        status: "failed",
-        ranAt: at,
-        actor,
-        detail: "instance aborted before dispatch",
-        error: void 0,
-        durationMs: void 0,
-        outputs: void 0
-      })
-    )
-  ), mutation.pendingEffects = [], mutation.history.push({
-    _key: randomKey(),
-    _type: "aborted",
-    at,
+async function propagateToAncestors(client, instanceId, actor, clientForGdr, clock) {
+  const instance = await client.getDocument(instanceId);
+  if (!instance) return;
+  const resolvedClientForGdr = clientForGdr ?? (() => client), found = await findResolvedParentSpawn(client, instance, resolvedClientForGdr, clock);
+  if (found === void 0) return;
+  const { parent, definition, stage, task, outcome } = found, ctx = await buildEngineContext({
+    client,
+    clientForGdr: resolvedClientForGdr,
+    instance: parent,
+    definition,
+    ...clock ? { clock } : {}
+  }), mutation = startMutation(parent), mutEntry = currentTasks(mutation).find((e) => e.name === task.name);
+  mutEntry !== void 0 && (applyTaskStatusChange({
+    entry: mutEntry,
+    history: mutation.history,
     stage: stage.name,
-    ...reason !== void 0 ? { reason } : {},
-    ...actor !== void 0 ? { actor } : {}
-  }), mutation.completedAt = at, mutation.abortedAt = at, await persist(ctx, mutation), await retractStageGuards({
-    client: ctx.client,
-    clientForGdr: ctx.clientForGdr,
-    instance: ctx.instance,
-    definition: ctx.definition,
-    stageName: stage.name,
-    now: ctx.now
-  }), { fired: !0, stage: stage.name };
+    to: outcome,
+    at: ctx.now,
+    actor: gateActor(outcome)
+  }), await persist(ctx, mutation), await cascadeAutoTransitions(client, parent._id, actor, clientForGdr, clock), await propagateToAncestors(client, parent._id, actor, clientForGdr, clock));
 }
 const parsedFilters = /* @__PURE__ */ new Map();
 async function matchesFilter(args) {
@@ -2328,93 +2476,6 @@ async function fetchGrantsCached(requestFn, resourcePath) {
     return;
   }
 }
-const resourceKey = (r) => `${r.type}.${r.id}`;
-function guardsForResource(client) {
-  return client.fetch("*[_type == $t] | order(_id asc)", { t: GUARD_DOC_TYPE });
-}
-function instanceGuardQuery(instanceId) {
-  return {
-    query: "*[_type == $guardType && sourceInstanceId == $instanceId]",
-    params: { guardType: GUARD_DOC_TYPE, instanceId }
-  };
-}
-function verdictGuardsForInstance(client, instanceId) {
-  const { query, params } = instanceGuardQuery(instanceId);
-  return client.fetch(query, params);
-}
-async function guardsForInstance(args) {
-  const { client, clientForGdr, instance } = args, stateUris = [
-    ...collectEntryDocUris(instance.state),
-    ...instance.stages.flatMap((stage) => collectEntryDocUris(stage.state))
-  ], clients = resourceClientMap(
-    instance.workflowResource,
-    client,
-    clientForGdr,
-    stateUris.map((uri) => tryParseGdr(uri))
-  ), { query, params } = instanceGuardQuery(instance._id);
-  return queryGuardsAcross(clients.values(), query, params);
-}
-async function guardsForDefinition(args) {
-  const { client, clientForGdr, workflowResource, definition, definitions } = args, gdrs = definitions.flatMap(
-    (def) => guardIdRefs(def).map(({ idRef, stage }) => staticIdRefGdr(idRef, stage, def))
-  ), clients = resourceClientMap(workflowResource, client, clientForGdr, gdrs);
-  return queryGuardsAcross(clients.values(), "*[_type == $t && sourceDefinition == $definition]", {
-    t: GUARD_DOC_TYPE,
-    definition
-  });
-}
-function guardIdRefs(definition) {
-  return definition.stages.flatMap(
-    (stage) => (stage.guards ?? []).flatMap(
-      (guard) => (guard.match.idRefs ?? []).map((idRef) => ({ idRef, stage }))
-    )
-  );
-}
-function staticIdRefGdr(idRef, stage, definition) {
-  const read = /^\$state\.([\w-]+)/.exec(idRef);
-  if (read === null) return;
-  const source = entriesInScope(stage, definition).find((e) => e.name === read[1])?.source;
-  return source?.type === "literal" ? gdrFromValue(source.value) : void 0;
-}
-function entriesInScope(stage, definition) {
-  return [
-    ...definition.state ?? [],
-    ...stage.state ?? [],
-    ...(stage.tasks ?? []).flatMap((task) => task.state ?? [])
-  ];
-}
-function gdrFromValue(value) {
-  if (typeof value == "string") return tryParseGdr(value);
-  if (typeof value == "object" && value !== null && "id" in value) {
-    const id = value.id;
-    return typeof id == "string" ? tryParseGdr(id) : void 0;
-  }
-}
-function tryParseGdr(uri) {
-  try {
-    return parseGdr(uri);
-  } catch {
-    return;
-  }
-}
-function resourceClientMap(base, baseClient, clientForGdr, gdrs) {
-  const map = /* @__PURE__ */ new Map([[resourceKey(base), baseClient]]);
-  for (const parsed of gdrs) {
-    if (parsed === void 0) continue;
-    const key = resourceKey(resourceFromParsed(parsed));
-    map.has(key) || map.set(key, clientForGdr(parsed));
-  }
-  return map;
-}
-async function queryGuardsAcross(clients, query, params) {
-  const perResource = await Promise.all(
-    [...clients].map((c) => c.fetch(query, params))
-  );
-  return dedupById(perResource.flat());
-}
-function dedupById(guards) {
-  return [...new Map(guards.map((g) => [g._id, g])).values()].sort((a, b) => a._id.localeCompare(b._id));
-}
 async function evaluateInstance(args) {
   const { client, tags, instanceId, resourceClients } = args, now = (args.clock ?? wallClock)();
   validateTags(tags);
@@ -2685,11 +2746,51 @@ async function loadDefinitionVersions(client, definition, tags) {
     { definition, engineTags: tags }
   );
 }
+async function abortInstance(args) {
+  const { client, instanceId, reason, options } = args, ctx = await loadContext(client, instanceId, {
+    ...options?.clock ? { clock: options.clock } : {},
+    ...options?.clientForGdr ? { clientForGdr: options.clientForGdr } : {}
+  });
+  return commitAbort(ctx, reason, options?.actor);
+}
+async function commitAbort(ctx, reason, actor) {
+  if (ctx.instance.completedAt !== void 0)
+    return { fired: !1 };
+  const stage = findStage(ctx.definition, ctx.instance.currentStage), mutation = startMutation(ctx.instance), at = ctx.now, openEntry = findOpenStageEntry(mutation);
+  return openEntry !== void 0 && (openEntry.exitedAt = at), mutation.effectHistory.push(
+    ...mutation.pendingEffects.map(
+      (pending) => buildEffectHistoryEntry(pending, {
+        status: "failed",
+        ranAt: at,
+        actor,
+        detail: "instance aborted before dispatch",
+        error: void 0,
+        durationMs: void 0,
+        outputs: void 0
+      })
+    )
+  ), mutation.pendingEffects = [], mutation.history.push({
+    _key: randomKey(),
+    _type: "aborted",
+    at,
+    stage: stage.name,
+    ...reason !== void 0 ? { reason } : {},
+    ...actor !== void 0 ? { actor } : {}
+  }), mutation.completedAt = at, mutation.abortedAt = at, await persist(ctx, mutation), await retractStageGuards({
+    client: ctx.client,
+    clientForGdr: ctx.clientForGdr,
+    instance: ctx.instance,
+    definition: ctx.definition,
+    stageName: stage.name,
+    now: ctx.now
+  }), { fired: !0, stage: stage.name };
+}
 async function fireAction(args) {
   const { client, instanceId, task, action, params, options } = args;
   for (let attempt = 1; attempt <= CONCURRENT_FIRE_ACTION_MAX_ATTEMPTS; attempt++) {
     const ctx = await loadContext(client, instanceId, {
-      ...options?.clock ? { clock: options.clock } : {}
+      ...options?.clock ? { clock: options.clock } : {},
+      ...options?.clientForGdr ? { clientForGdr: options.clientForGdr } : {}
     });
     try {
       return await commitAction(ctx, task, action, params, options);
@@ -2815,6 +2916,15 @@ async function cascade(client, instanceId, actor, clientForGdr, clock, overlay)
   );
   return await propagateToAncestors(client, instanceId, actor, clientForGdr, clock), count;
 }
+async function abortAndPropagate(args) {
+  const { client, instanceId, reason, actor, clientForGdr, clock } = args, result = await abortInstance({
+    client,
+    instanceId,
+    ...reason !== void 0 ? { reason } : {},
+    options: { ...actor !== void 0 ? { actor } : {}, clock, clientForGdr }
+  });
+  return result.fired && await propagateToAncestors(client, instanceId, actor, clientForGdr, clock), result.fired;
+}
 function buildClientForGdr(defaultClient, resolver) {
   return resolver === void 0 ? () => defaultClient : (parsed) => resolver(parsed) ?? defaultClient;
 }
@@ -2837,10 +2947,11 @@ function assertActionAllowed(evaluation, task, action) {
     throw new ActionDisabledError({ task, action, reason: actionEval.disabledReason });
 }
 async function applyAction(args) {
-  const { client, instance, task, action, params, actor, grants, clock } = args, options = {
+  const { client, instance, task, action, params, actor, grants, clock, clientForGdr } = args, options = {
     actor,
     ...grants !== void 0 ? { grants } : {},
-    ...clock !== void 0 ? { clock } : {}
+    ...clock !== void 0 ? { clock } : {},
+    ...clientForGdr !== void 0 ? { clientForGdr } : {}
   };
   return findOpenStageEntry(instance)?.tasks.find((t) => t.name === task)?.status === "pending" && await invokeTask({ client, instanceId: instance._id, task, options }), (await fireAction({
     client,
@@ -2851,6 +2962,78 @@ async function applyAction(args) {
     options
   })).ranOps;
 }
+async function deleteDefinition(args) {
+  const { client, tags, definition, version, cascade: cascade2, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, versions = await loadDefinitionVersions(client, definition, tags);
+  if (versions.length === 0)
+    throw new Error(`No deployed definition for workflow ${definition}`);
+  const targets = version === void 0 ? versions : versions.filter((d) => d.version === version);
+  if (targets.length === 0)
+    throw new Error(`Workflow definition ${definition} v${version} not deployed`);
+  const lastVersionGoes = targets.length === versions.length;
+  await assertNoSpawnReferrers(client, tags, definition, targets, lastVersionGoes);
+  const instanceIds = await nonTerminalInstanceIds(client, tags, definition, version);
+  if (instanceIds.length > 0 && cascade2 !== !0)
+    throw new Error(
+      `Cannot delete ${definition}: ${instanceIds.length} non-terminal instance(s) exist (${previewIds(instanceIds)}). Pass cascade to abort them first \u2014 instances are aborted in place, never deleted.`
+    );
+  const abortedInstanceIds = await abortInstances({
+    client,
+    instanceIds,
+    reason,
+    actor,
+    clientForGdr,
+    clock
+  }), tx = client.transaction();
+  for (const target of targets) tx.delete(target._id);
+  await tx.commit();
+  const deletedGuardCount = lastVersionGoes ? await deleteOrphanedDefinitionGuards({
+    client,
+    clientForGdr,
+    workflowResource: args.workflowResource,
+    definition,
+    definitions: versions,
+    tags
+  }) : 0;
+  return {
+    name: definition,
+    deletedVersions: targets.map((d) => d.version),
+    abortedInstanceIds,
+    deletedGuardCount
+  };
+}
+async function assertNoSpawnReferrers(client, tags, definition, targets, lastVersionGoes) {
+  const deployed = await client.fetch(
+    `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && ${tagScopeFilter()}]`,
+    { engineTags: tags }
+  ), targetIds = new Set(targets.map((d) => d._id)), targetVersions = new Set(targets.map((d) => d.version)), referrers = deployed.filter((d) => !targetIds.has(d._id)).filter(
+    (d) => refsOf(d).some(
+      (ref) => ref.name === definition && (typeof ref.version == "number" ? targetVersions.has(ref.version) : lastVersionGoes)
+    )
+  );
+  if (referrers.length > 0) {
+    const names = referrers.map((d) => `${d.name} v${d.version}`).join(", ");
+    throw new Error(
+      `Cannot delete ${definition}: still spawn-referenced by deployed definition(s) ${names}. Delete or redeploy the referrer(s) first.`
+    );
+  }
+}
+async function nonTerminalInstanceIds(client, tags, definition, version) {
+  const versionFilter = version === void 0 ? "" : " && pinnedVersion == $version";
+  return (await client.fetch(
+    `*[_type == "${WORKFLOW_INSTANCE_TYPE}" && definition == $definition && ${tagScopeFilter()} && !defined(completedAt)${versionFilter}] | order(_id asc){_id}`,
+    { definition, engineTags: tags, ...version !== void 0 ? { version } : {} }
+  )).map((doc) => doc._id);
+}
+async function abortInstances(args) {
+  const { client, instanceIds, reason, actor, clientForGdr, clock } = args, aborted = [];
+  for (const instanceId of instanceIds)
+    await abortAndPropagate({ client, instanceId, reason, actor, clientForGdr, clock }) && aborted.push(instanceId);
+  return aborted;
+}
+function previewIds(ids) {
+  const head = ids.slice(0, 3).join(", ");
+  return ids.length > 3 ? `${head}, \u2026` : head;
+}
 const workflow = {
   /**
    * Deploy a set of workflow definitions as one call. Each lands as a
@@ -2901,6 +3084,14 @@ const workflow = {
     }
     return hasWrites && await tx.commit(), { results };
   },
+  /**
+   * Remove a deployed workflow definition (all versions, or one via
+   * `version`). Refuses while non-terminal instances exist unless
+   * `cascade` aborts them first — instances are never deleted, only
+   * aborted in place; see {@link deleteDefinitionInternal} for the
+   * full contract (spawn-referrer check, guard-doc housekeeping).
+   */
+  deleteDefinition: async (args) => deleteDefinition(args),
   /**
    * Spawn a new workflow instance from a deployed definition.
    *
@@ -2995,6 +3186,7 @@ const workflow = {
       actor,
       ...access.grants !== void 0 ? { grants: access.grants } : {},
       clock,
+      clientForGdr,
       ...params !== void 0 ? { params } : {}
     }), cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
@@ -3022,7 +3214,7 @@ const workflow = {
       ...detail !== void 0 ? { detail } : {},
       ...error !== void 0 ? { error } : {},
       ...durationMs !== void 0 ? { durationMs } : {},
-      options: { ...actor !== void 0 ? { actor } : {}, clock }
+      options: { ...actor !== void 0 ? { actor } : {}, clock, clientForGdr }
     });
     const cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
@@ -3063,7 +3255,7 @@ const workflow = {
       instanceId,
       targetStage,
       ...reason !== void 0 ? { reason } : {},
-      options: { ...actor !== void 0 ? { actor } : {}, clock }
+      options: { ...actor !== void 0 ? { actor } : {}, clock, clientForGdr }
     }), cascaded = result.fired ? await cascade(client, instanceId, actor, clientForGdr, clock) : 0;
     return {
       instance: await reload(client, instanceId, tags),
@@ -3073,24 +3265,18 @@ const workflow = {
   },
   /**
    * Admin override — hard-stop an in-flight instance where it stands.
-   * No stage move, no transition effects, pending effects cancelled; see
-   * the engine-level {@link engineAbortInstance} for the full contract.
-   * Ancestors are propagated (not cascaded — the instance is terminal)
-   * so a parent gate waiting on this child re-evaluates.
+   * No stage move, no transition effects, pending effects cancelled;
+   * see {@link abortAndPropagate} for the abort + ancestor-propagation
+   * contract (propagated, not cascaded — the instance is terminal).
    */
   abortInstance: async (args) => {
     const { client, tags, instanceId, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
     await reload(client, instanceId, tags);
-    const result = await abortInstance({
-      client,
-      instanceId,
-      ...reason !== void 0 ? { reason } : {},
-      options: { ...actor !== void 0 ? { actor } : {}, clock }
-    });
-    return result.fired && await propagateToAncestors(client, instanceId, actor, clientForGdr, clock), {
+    const fired = await abortAndPropagate({ client, instanceId, reason, actor, clientForGdr, clock });
+    return {
       instance: await reload(client, instanceId, tags),
       cascaded: 0,
-      fired: result.fired
+      fired
     };
   },
   /**
@@ -3189,6 +3375,30 @@ const workflow = {
    * `fireAction` to gate writes via the same logic.
    */
   evaluate: async (args) => evaluateInstance(args),
+  /**
+   * Diagnose why an instance is or isn't progressing. Projects the
+   * instance (the same read as `evaluate`) and classifies it — terminal,
+   * `progressing`, `waiting` (an action is available — healthy), or `stuck`
+   * with a structured cause — returning that verdict as a
+   * {@link DiagnoseResult} alongside the evaluation it came from, so a
+   * consumer can render the supporting evidence without a second projection.
+   * Pure read.
+   */
+  diagnose: async (args) => {
+    const evaluation = await evaluateInstance(args);
+    return { evaluation, diagnosis: diagnoseInstance(diagnoseInputFromEvaluation(evaluation)) };
+  },
+  /**
+   * List the actions an actor could fire on an instance's current stage,
+   * each flagged `allowed` (with a structured `disabledReason` when not).
+   * Projects the instance from the actor's perspective and flattens its
+   * tasks' actions. Returns the evaluation alongside the actions so a
+   * consumer can read the instance/stage context. Pure read.
+   */
+  availableActions: async (args) => {
+    const evaluation = await evaluateInstance(args);
+    return { evaluation, actions: availableActions(evaluation.currentStage.tasks) };
+  },
   /**
    * Materialised spawned children of a parent instance.
    *
@@ -3449,6 +3659,7 @@ function createInstanceSession(args) {
           task,
           action,
           actor,
+          clientForGdr,
           ...grants !== void 0 ? { grants } : {},
           ...clock !== void 0 ? { clock } : {},
           ...params !== void 0 ? { params } : {}
@@ -3504,8 +3715,11 @@ function createEngine(args) {
     completeEffect: (rest) => workflow.completeEffect(bind(rest)),
     tick: (rest) => workflow.tick(bind(rest)),
     evaluateInstance: (rest) => evaluateInstance(bind(rest)),
+    diagnose: (rest) => workflow.diagnose(bind(rest)),
+    availableActions: (rest) => workflow.availableActions(bind(rest)),
     setStage: (rest) => workflow.setStage(bind(rest)),
     abortInstance: (rest) => workflow.abortInstance(bind(rest)),
+    deleteDefinition: (rest) => workflow.deleteDefinition(bind(rest)),
     getInstance: ({ instanceId }) => workflow.getInstance({ client, tags, workflowResource, instanceId }),
     subscriptionDocumentsForInstance: ({ instanceId }) => workflow.getInstance({ client, tags, workflowResource, instanceId }).then(subscriptionDocumentsForInstance),
     instance: (instanceDoc, opts) => createInstanceSession({
@@ -3583,6 +3797,36 @@ function createEngine(args) {
     })
   };
 }
+function docIdFor(def, target) {
+  return definitionDocId(target.workflowResource, canonicalTag(target.tags), def.name, def.version);
+}
+function diffStatus(existing, expected) {
+  return existing === void 0 ? "create" : isDefinitionUnchanged(existing, expected) ? "unchanged" : "update";
+}
+function diffEntry(def, existingRaw, target) {
+  const docId = docIdFor(def, target), expected = {
+    ...def,
+    _id: docId,
+    _type: WORKFLOW_DEFINITION_TYPE,
+    tags: target.tags
+  }, status = diffStatus(existingRaw, expected), existing = existingRaw ? stripSystemFields(existingRaw) : void 0;
+  return {
+    name: def.name,
+    version: def.version,
+    status,
+    docId,
+    expected,
+    ...existing !== void 0 ? { existing } : {}
+  };
+}
+async function computeDiffEntries(client, defs, target) {
+  const entries = [];
+  for (const def of defs) {
+    const existingRaw = await client.getDocument(docIdFor(def, target)) ?? void 0;
+    entries.push(diffEntry(def, existingRaw, target));
+  }
+  return entries;
+}
 const HISTORY_DISPLAY = {
   stageEntered: {
     title: "Stage entered",
@@ -3776,15 +4020,23 @@ export {
   WORKFLOW_DEFINITION_TYPE,
   WORKFLOW_INSTANCE_TYPE,
   WorkflowStateDivergedError,
+  abortReason,
+  actionVerdict,
+  assigneesOf,
+  availableActions,
   buildSnapshot,
   canonicalTag,
   compileGuard,
+  computeDiffEntries,
   contentReleaseName,
   createEngine,
   datasetResourceParts,
   defaultLoggerFactory,
   denyingGuards,
   deployStageGuards,
+  diagnoseInputFromEvaluation,
+  diagnoseInstance,
+  diffEntry,
   displayDescription,
   displayTitle,
   effectsContextMap,
@@ -3803,6 +4055,7 @@ export {
   isGdr,
   isTerminalStage,
   lakeGuardId,
+  openStage,
   parseGdr,
   readsRaw,
   refCanvas,