@sanity/workflow-engine 0.5.0 → 0.7.0

package/dist/index.js

@@ -79,6 +79,21 @@ function gdrFromResource(res, documentId) {
   }
   return gdrUri({ scheme: res.type, resourceId: res.id, documentId });
 }
+function resourceFromGdrUri(uri) {
+  let parsed;
+  try {
+    parsed = parseGdr(uri);
+  } catch {
+    return;
+  }
+  if (parsed.scheme === "dataset")
+    return parsed.projectId === void 0 || parsed.dataset === void 0 ? void 0 : { type: "dataset", id: `${parsed.projectId}.${parsed.dataset}` };
+  if (parsed.resourceId !== void 0)
+    return { type: parsed.scheme, id: parsed.resourceId };
+}
+function sameResource(a, b) {
+  return a.type === b.type && a.id === b.id;
+}
 function selfGdr(doc) {
   return gdrFromResource(doc.workflowResource, doc._id);
 }
@@ -223,6 +238,8 @@ function validateTask(v2, stageName, task) {
   for (const entry of task.state ?? [])
     v2.checkEntry(entry, `${where}.state "${entry.name}"`);
   task.filter !== void 0 && v2.checkCondition(task.filter, `${where}.filter`), task.completeWhen !== void 0 && v2.checkCondition(task.completeWhen, `${where}.completeWhen`), task.failWhen !== void 0 && v2.checkCondition(task.failWhen, `${where}.failWhen`);
+  for (const [name, groq] of Object.entries(task.requirements ?? {}))
+    v2.checkCondition(groq, `${where}.requirements "${name}"`);
   for (const [key, groq] of effectBindings(task.effects))
     v2.tryParse(groq, `${where} effect binding "${key}"`);
   validateTaskActions(v2, task), task.subworkflows !== void 0 && validateSubworkflows(v2, where, task.subworkflows);
@@ -460,10 +477,14 @@ function abortReason(instance) {
   )?.reason;
 }
 function diagnoseInputFromEvaluation(evaluation) {
+  const stage = openStage(evaluation.instance);
   return {
     instance: evaluation.instance,
     tasks: evaluation.currentStage.tasks,
-    transitions: evaluation.currentStage.transitions
+    transitions: evaluation.currentStage.transitions,
+    assignees: Object.fromEntries(
+      evaluation.currentStage.tasks.map((t) => [t.task.name, assigneesOf(stage, t.task.name)])
+    )
   };
 }
 function openStage(instance) {
@@ -488,18 +509,34 @@ function failedTaskCause(input) {
   return failed ? { kind: "failed-task", task: failed.task.name } : void 0;
 }
 function waitingState(input) {
-  const active = input.tasks.find((t) => t.status === "active" && (t.task.actions ?? []).length > 0);
+  const active = input.tasks.find(
+    (t) => t.status === "active" && (t.task.actions ?? []).length > 0 && (t.unmetRequirements ?? []).length === 0
+  );
   if (active !== void 0)
     return {
       state: "waiting",
       task: active.task.name,
-      assignees: assigneesOf(openStage(input.instance), active.task.name),
+      assignees: input.assignees[active.task.name] ?? [],
       actions: (active.task.actions ?? []).map((a) => a.name)
     };
 }
+function blockedState(input) {
+  const blocked = input.tasks.find(
+    (t) => t.status === "active" && (t.task.actions ?? []).length > 0 && (t.unmetRequirements ?? []).length > 0
+  );
+  if (blocked !== void 0)
+    return {
+      state: "blocked",
+      task: blocked.task.name,
+      requirements: blocked.unmetRequirements ?? [],
+      assignees: input.assignees[blocked.task.name] ?? []
+    };
+}
 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" };
+  if (input.transitions.length === 0 || input.transitions.some((t) => t.filterSatisfied) || !input.tasks.every((t) => isResolved(t.status)))
+    return;
+  const undecidable = input.transitions.filter((t) => t.unevaluable);
+  return undecidable.length > 0 ? { kind: "transition-unevaluable", transitions: undecidable.map((t) => t.transition.name) } : { kind: "no-transition-fires" };
 }
 function diagnoseInstance(input) {
   const { instance } = input;
@@ -510,7 +547,51 @@ function diagnoseInstance(input) {
   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" };
+  return cause !== void 0 ? { state: "stuck", cause } : waitingState(input) ?? blockedState(input) ?? { state: "progressing" };
+}
+const RUNNABLE_VERBS = /* @__PURE__ */ new Set(["set-stage", "abort"]);
+function remediationsForCause(cause) {
+  switch (cause.kind) {
+    case "failed-effect":
+      return [
+        {
+          verb: "retry-effect",
+          rationale: "Re-run the failed effect once the upstream system is healthy."
+        },
+        { verb: "abort", rationale: "Abort the instance if it can no longer recover." }
+      ];
+    case "hung-effect":
+      return [
+        {
+          verb: "drain-effects",
+          rationale: "Re-run the effect drainer to re-pick the claimed effect."
+        },
+        { verb: "abort", rationale: "Abort the instance if the effect never drains." }
+      ];
+    case "failed-task":
+      return [
+        { verb: "reset-task", rationale: "Reset or skip the failed task." },
+        {
+          verb: "set-stage",
+          rationale: "Move the instance past the failed task to the intended next stage."
+        }
+      ];
+    case "no-transition-fires":
+      return [
+        {
+          verb: "set-stage",
+          rationale: "Move the instance to the intended next stage to force it forward."
+        }
+      ];
+    case "transition-unevaluable":
+      return [];
+  }
+}
+function remediationsFor(diagnosis) {
+  return diagnosis.state !== "stuck" ? [] : remediationsForCause(diagnosis.cause).map((seed) => ({
+    ...seed,
+    available: RUNNABLE_VERBS.has(seed.verb)
+  }));
 }
 function buildSnapshot(args) {
   const docs = [], knownIds = /* @__PURE__ */ new Set();
@@ -557,6 +638,7 @@ function collectWatchRefs(instance) {
 function readsRaw(ref) {
   return ref.type === WORKFLOW_INSTANCE_TYPE || ref.type === "system.release";
 }
+const DEFAULT_CONTENT_PERSPECTIVE = "drafts";
 function contentReleaseName(args) {
   const { ref, perspective } = args;
   if (!readsRaw(ref) && Array.isArray(perspective))
@@ -582,6 +664,11 @@ function entryReleaseRefs(state) {
     (entry) => entry._type === "release.ref" && isGdr(entry.value) ? [entry.value] : []
   );
 }
+function entrySubjectRefs(state) {
+  return stateEntries(state).flatMap(
+    (entry) => (entry._type === "doc.ref" || entry._type === "release.ref") && isGdr(entry.value) ? [entry.value] : []
+  );
+}
 function stateEntries(state) {
   return Array.isArray(state) ? state.filter(
     (entry) => !!entry && typeof entry == "object"
@@ -606,7 +693,10 @@ async function hydrateSnapshot(args) {
   };
   loaded.push({ doc: instance, resource: instance.workflowResource }), visited.add(selfGdr(instance));
   for (const ref of collectWatchRefs(instance))
-    await loadInto(ref.id, readsRaw(ref) ? void 0 : instance.perspective);
+    await loadInto(
+      ref.id,
+      readsRaw(ref) ? "raw" : instance.perspective ?? DEFAULT_CONTENT_PERSPECTIVE
+    );
   return buildSnapshot({ docs: loaded });
 }
 async function loadByGdr(defaultClient, clientForGdr, defaultResource, uri, perspective) {
@@ -621,7 +711,7 @@ async function loadByGdr(defaultClient, clientForGdr, defaultResource, uri, pers
   return doc ? { doc, resource: resourceFromParsed(parsed) } : null;
 }
 async function readDoc(client, id, perspective) {
-  return perspective === void 0 ? await client.getDocument(id) ?? null : await client.fetch("*[_id == $id][0]", { id }, { perspective }) ?? null;
+  return perspective === "raw" ? await client.getDocument(id) ?? null : await client.fetch("*[_id == $id][0]", { id }, { perspective }) ?? null;
 }
 function resourceFromParsed(parsed) {
   return parsed.scheme === "dataset" ? { type: "dataset", id: `${parsed.projectId}.${parsed.dataset}` } : { type: parsed.scheme, id: parsed.resourceId ?? "" };
@@ -722,23 +812,7 @@ async function queryGuardsAcross(clients, query, params) {
 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";
+const SYNC_COMMIT = { visibility: "sync" }, 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;
@@ -765,11 +839,11 @@ function resolveGuard(guard, instance, stageName, now) {
 }
 async function upsertGuard(client, doc) {
   if (!await client.getDocument(doc._id)) {
-    await client.create(doc);
+    await client.create(doc, SYNC_COMMIT);
     return;
   }
   const { _id, _type, _rev, _createdAt, _updatedAt, ...body } = doc;
-  await client.patch(doc._id).set(body).commit();
+  await client.patch(doc._id).set(body).commit(SYNC_COMMIT);
 }
 function resolvedStageGuards(args) {
   const stage = args.definition.stages.find((s) => s.name === args.stageName), out = [];
@@ -792,16 +866,16 @@ 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();
+      await client.getDocument(doc._id) && await client.patch(doc._id).set({ predicate: GUARD_LIFTED_PREDICATE }).commit(SYNC_COMMIT);
 }
 async function deleteOrphanedDefinitionGuards(args) {
-  const { client, clientForGdr, workflowResource, definition, definitions, tags } = args, perClient = await guardsForDefinitionByClient({
+  const { client, clientForGdr, workflowResource, definition, definitions, tag } = args, perClient = await guardsForDefinitionByClient({
     client,
     clientForGdr,
     workflowResource,
     definition,
     definitions
-  }), ownPartitionPrefix = `${canonicalTag(tags)}.`;
+  }), ownPartitionPrefix = `${tag}.`;
   let count = 0;
   for (const { client: resourceClient, guards } of perClient) {
     const own = guards.filter((guard) => guard.sourceInstanceId.startsWith(ownPartitionPrefix));
@@ -816,16 +890,32 @@ 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) {
+function isUnevaluable(result) {
+  return result == null;
+}
+async function evaluateConditionOutcome(args) {
   const { condition, snapshot, params } = args;
-  return condition === void 0 ? !0 : !!await runGroq(condition, params, snapshot);
+  if (condition === void 0) return "satisfied";
+  const result = await runGroq(condition, params, snapshot);
+  return isUnevaluable(result) ? "unevaluable" : result ? "satisfied" : "unsatisfied";
+}
+async function evaluateCondition(args) {
+  return await evaluateConditionOutcome(args) === "satisfied";
 }
 async function evaluatePredicates(args) {
   const out = {};
-  for (const [name, groq] of Object.entries(args.predicates ?? {}))
-    out[name] = !!await runGroq(groq, args.params, args.snapshot);
+  for (const [name, groq] of Object.entries(args.predicates ?? {})) {
+    const result = await runGroq(groq, args.params, args.snapshot);
+    out[name] = isUnevaluable(result) ? null : !!result;
+  }
   return out;
 }
+async function evaluateRequirements(args) {
+  const unmet = [];
+  for (const [name, condition] of Object.entries(args.requirements ?? {}))
+    await evaluateCondition({ condition, snapshot: args.snapshot, params: args.params }) || unmet.push(name);
+  return unmet;
+}
 async function runGroq(groq, params, snapshot) {
   const tree = parse(groq, { params });
   return (await evaluate(tree, { dataset: snapshot.docs, params })).get();
@@ -990,10 +1080,10 @@ async function resolveQueryValue(entry, source, ctx, client, defaultValue) {
     stage: ctx.stageName ?? null,
     task: ctx.taskName ?? null,
     now: ctx.now,
-    engineTags: ctx.tags ?? []
+    tag: ctx.tag
   });
   try {
-    const fetchOptions = ctx.perspective !== void 0 ? { perspective: ctx.perspective } : void 0, result = await client.fetch(source.query, params, fetchOptions);
+    const fetchOptions = { perspective: ctx.perspective ?? DEFAULT_CONTENT_PERSPECTIVE }, result = await client.fetch(source.query, params, fetchOptions);
     return normalizeQueryResult(entry.type, result, ctx.workflowResource) ?? defaultValue;
   } catch (err) {
     throw new Error(
@@ -1123,13 +1213,16 @@ async function ctxConditionParams(ctx, opts) {
     params
   }), ...params };
 }
-async function ctxEvaluateCondition(ctx, condition, opts) {
-  return condition === void 0 ? !0 : evaluateCondition({
+async function ctxEvaluateConditionOutcome(ctx, condition, opts) {
+  return condition === void 0 ? "satisfied" : evaluateConditionOutcome({
     condition,
     snapshot: ctx.snapshot,
     params: await ctxConditionParams(ctx, opts)
   });
 }
+async function ctxEvaluateCondition(ctx, condition, opts) {
+  return await ctxEvaluateConditionOutcome(ctx, condition, opts) === "satisfied";
+}
 async function buildEngineContext(args) {
   const { client, clientForGdr, instance, definition } = args, clock = args.clock ?? wallClock;
   return {
@@ -1157,7 +1250,7 @@ async function resolveStageStateEntries(args) {
       client,
       now,
       selfId: instance._id,
-      tags: instance.tags ?? [],
+      tag: instance.tag,
       stageName: stage.name,
       workflowResource: instance.workflowResource,
       // Allow stage-scope entries' `source: { type: "stateRead", scope:
@@ -1177,7 +1270,7 @@ async function resolveTaskStateEntries(args) {
       client,
       now,
       selfId: instance._id,
-      tags: instance.tags ?? [],
+      tag: instance.tag,
       stageName: stage.name,
       workflowResource: instance.workflowResource,
       taskName: task.name,
@@ -1249,7 +1342,7 @@ async function deployOrRollback(args) {
       });
     try {
       let patch = args.client.patch(args.instanceId).set(args.restore);
-      args.unset && args.unset.length > 0 && (patch = patch.unset(args.unset)), args.committedRev !== void 0 && (patch = patch.ifRevisionId(args.committedRev)), await patch.commit();
+      args.unset && args.unset.length > 0 && (patch = patch.unset(args.unset)), args.committedRev !== void 0 && (patch = patch.ifRevisionId(args.committedRev)), await patch.commit(SYNC_COMMIT);
     } catch (rollbackError) {
       throw new WorkflowStateDivergedError({
         instanceId: args.instanceId,
@@ -1356,7 +1449,7 @@ async function persist(ctx, 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();
+    return ctx.client.patch(ctx.instance._id).set(set).ifRevisionId(ctx.instance._rev).commit(SYNC_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 = [];
@@ -1399,6 +1492,16 @@ function findCurrentStageEntry(instance) {
 function findCurrentTasks(instance) {
   return findCurrentStageEntry(instance)?.tasks ?? [];
 }
+const TAG_RE = /^[a-z0-9][a-z0-9-]*$/;
+function validateTag(tag) {
+  if (!TAG_RE.test(tag))
+    throw new Error(
+      `tag: invalid tag "${tag}" \u2014 must match ${TAG_RE.source} (ASCII lowercase + digits + dashes, no leading dash, no dots)`
+    );
+}
+function tagScopeFilter() {
+  return "tag == $tag";
+}
 function definitionLookupGroq(explicit) {
   const scoped = `_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $definition && ${tagScopeFilter()}`;
   return explicit ? `*[${scoped} && version == $version][0]` : `*[${scoped}] | order(version desc)[0]`;
@@ -1415,6 +1518,14 @@ function clientForDiscovery(defaultClient, clientForGdr, subjectGdrUri) {
     return defaultClient;
   }
 }
+async function reload(client, instanceId, tag) {
+  const doc = await client.getDocument(instanceId);
+  if (!doc)
+    throw new Error(`Workflow instance ${instanceId} not found`);
+  if (doc.tag !== tag)
+    throw new Error(`Workflow instance ${instanceId} not visible to this engine (tag mismatch)`);
+  return doc;
+}
 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 };
@@ -1430,7 +1541,7 @@ function buildInstanceBase(args) {
     _rev: "",
     _createdAt: now,
     _updatedAt: now,
-    tags: args.tags,
+    tag: args.tag,
     workflowResource: args.workflowResource,
     definition: args.definitionName,
     pinnedVersion: args.pinnedVersion,
@@ -1481,7 +1592,7 @@ async function spawnSubworkflows(ctx, mutation, task, sub, actor) {
       `Subworkflow depth limit (${MAX_SPAWN_DEPTH}) exceeded on task "${task.name}" of ${ctx.instance._id}. Ancestor chain: ${chain}`
     );
   }
-  const now = ctx.now, definition = await resolveDefinitionRef(ctx.client, sub.definition, ctx.instance.tags ?? []);
+  const now = ctx.now, definition = await resolveDefinitionRef(ctx.client, sub.definition, ctx.instance.tag);
   if (definition === null) {
     const versionLabel = sub.definition.version === void 0 || sub.definition.version === "latest" ? "latest" : `v${sub.definition.version}`;
     throw new Error(
@@ -1491,9 +1602,16 @@ async function spawnSubworkflows(ctx, mutation, task, sub, actor) {
   const parentScope = await ctxConditionParams(ctx, {
     taskName: task.name,
     ...actor ? { actor } : {}
-  }), rows = await resolveSpawnRows(ctx, sub), effectsContext = await resolveContextHandoff(ctx, sub, parentScope), refs = [];
+  }), { rows, discoveryResource } = await resolveSpawnRows(ctx, sub), effectsContext = await resolveContextHandoff(ctx, sub, parentScope), refs = [];
   for (const row of rows) {
-    const initialState = await projectRowState(ctx, sub, definition, parentScope, row), { ref, body } = await prepareChildInstance({
+    const initialState = await projectRowState(
+      ctx,
+      sub,
+      definition,
+      parentScope,
+      row,
+      discoveryResource
+    ), { ref, body } = await prepareChildInstance({
       client: ctx.client,
       parent: ctx.instance,
       definition,
@@ -1508,28 +1626,25 @@ async function spawnSubworkflows(ctx, mutation, task, sub, actor) {
 }
 async function resolveSpawnRows(ctx, sub) {
   const params = buildParams({ instance: ctx.instance, now: ctx.now, snapshot: ctx.snapshot }), groq = sub.forEach;
-  let value;
+  let value, discoveryResource;
   if (groq.includes("*")) {
-    const routingUri = firstDocRefGdrUri(ctx.instance.state), client = clientForDiscovery(ctx.client, ctx.clientForGdr, routingUri);
-    value = await discoverItems({
+    const routingUri = entrySubjectRefs(ctx.instance.state)[0]?.id, client = clientForDiscovery(ctx.client, ctx.clientForGdr, routingUri);
+    client !== ctx.client && routingUri !== void 0 && (discoveryResource = resourceFromGdrUri(routingUri)), value = await discoverItems({
       client,
       groq,
       params,
-      ...ctx.instance.perspective !== void 0 ? { perspective: ctx.instance.perspective } : {}
+      // Draft-aware by default (drafts overlay published) when there's no
+      // release, so a `forEach` discovers in-flight items the same way the
+      // engine reads any other content.
+      perspective: ctx.instance.perspective ?? DEFAULT_CONTENT_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];
+  return Array.isArray(value) ? { rows: value, discoveryResource } : value == null ? { rows: [], discoveryResource } : { rows: [value], discoveryResource };
 }
-function firstDocRefGdrUri(entries) {
-  if (entries) {
-    for (const s of entries)
-      if (s._type === "doc.ref" && s.value !== null) return s.value.id;
-  }
-}
-async function projectRowState(ctx, sub, childDefinition, parentScope, row) {
+async function projectRowState(ctx, sub, childDefinition, parentScope, row, discoveryResource) {
   const out = [];
   for (const [name, groq] of Object.entries(sub.with ?? {})) {
     const declared = (childDefinition.state ?? []).find((e) => e.name === name);
@@ -1537,7 +1652,12 @@ async function projectRowState(ctx, sub, childDefinition, parentScope, row) {
       throw new Error(
         `subworkflows.with["${name}"]: subworkflow "${childDefinition.name}" declares no state entry "${name}"`
       );
-    const raw = await runGroq(groq, { ...parentScope, row }, ctx.snapshot), value = canonicaliseSpawnValue(declared.type, raw, ctx.instance.workflowResource);
+    const raw = await runGroq(groq, { ...parentScope, row }, ctx.snapshot), value = canonicaliseSpawnValue(declared.type, raw, {
+      parentResource: ctx.instance.workflowResource,
+      discoveryResource,
+      entryName: name,
+      childName: childDefinition.name
+    });
     value != null && out.push({
       type: declared.type,
       name,
@@ -1554,11 +1674,17 @@ async function resolveContextHandoff(ctx, sub, parentScope) {
   }
   return out;
 }
-function canonicaliseSpawnValue(kind, value, workflowResource) {
-  return kind === "doc.ref" ? coerceSpawnGdr(value, workflowResource) : kind === "doc.refs" && Array.isArray(value) ? value.map((v2) => coerceSpawnGdr(v2, workflowResource)).filter((v2) => v2 !== null) : value;
+function canonicaliseSpawnValue(kind, value, cx) {
+  return kind === "doc.ref" ? coerceSpawnGdr(value, cx) : kind === "doc.refs" && Array.isArray(value) ? value.map((v2) => coerceSpawnGdr(v2, cx)).filter((v2) => v2 !== null) : value;
+}
+function assertBareIdRootsCorrectly(id, cx) {
+  if (!(cx.discoveryResource === void 0 || sameResource(cx.discoveryResource, cx.parentResource)))
+    throw new Error(
+      `subworkflows.with["${cx.entryName}"]: subworkflow "${cx.childName}" projected the bare id "${id}", which roots at the parent resource "${cx.parentResource.id}", but spawn discovery ran against "${cx.discoveryResource.id}". The child would reference a document that doesn't exist in the parent resource. Project an explicit GDR URI in the with-GROQ (e.g. "dataset:<projectId>:<dataset>:" + _id) so the child's subject points at the resource the discovered rows came from.`
+    );
 }
-function coerceSpawnGdr(raw, workflowResource) {
-  const toUri = (id) => isGdrUri(id) ? id : gdrFromResource(workflowResource, id);
+function coerceSpawnGdr(raw, cx) {
+  const toUri = (id) => isGdrUri(id) ? id : (assertBareIdRootsCorrectly(id, cx), gdrFromResource(cx.parentResource, id));
   if (raw == null) return null;
   if (typeof raw == "object" && "id" in raw && "type" in raw) {
     const r = raw;
@@ -1571,15 +1697,15 @@ function coerceSpawnGdr(raw, workflowResource) {
   }
   return typeof raw == "string" && raw.length > 0 ? { id: toUri(raw), type: "document" } : null;
 }
-async function resolveDefinitionRef(client, ref, tags) {
-  const wantsExplicit = typeof ref.version == "number", params = { definition: ref.name, engineTags: tags };
+async function resolveDefinitionRef(client, ref, tag) {
+  const wantsExplicit = typeof ref.version == "number", params = { definition: ref.name, tag };
   return wantsExplicit && (params.version = ref.version), await client.fetch(
     definitionLookupGroq(wantsExplicit),
     params
   ) ?? null;
 }
 async function prepareChildInstance(args) {
-  const { client, parent, definition, initialState, effectsContext, actor, now } = args, childTags = parent.tags ?? [], childPrefix = childTags[0] ?? "wf", workflowResource = parent.workflowResource, childDocId = `${childPrefix}.wf-instance.${randomKey()}`, childRef = { id: gdrFromResource(workflowResource, childDocId), type: WORKFLOW_INSTANCE_TYPE }, ancestors = [
+  const { client, parent, definition, initialState, effectsContext, actor, now } = args, childTag = parent.tag, workflowResource = parent.workflowResource, childDocId = `${childTag}.wf-instance.${randomKey()}`, childRef = { id: gdrFromResource(workflowResource, childDocId), type: WORKFLOW_INSTANCE_TYPE }, ancestors = [
     ...parent.ancestors,
     {
       id: selfGdr(parent),
@@ -1592,7 +1718,7 @@ async function prepareChildInstance(args) {
       client,
       now,
       selfId: childDocId,
-      tags: childTags,
+      tag: childTag,
       workflowResource,
       ...inheritedPerspective !== void 0 ? { perspective: inheritedPerspective } : {}
     },
@@ -1611,7 +1737,7 @@ async function prepareChildInstance(args) {
   ), base = buildInstanceBase({
     id: childDocId,
     now,
-    tags: childTags,
+    tag: childTag,
     workflowResource,
     definitionName: definition.name,
     pinnedVersion: definition.version,
@@ -2057,21 +2183,24 @@ function resolveMachineStep(mutation, task, entry, now) {
 async function buildStageTasks(ctx, stage) {
   const entries = [];
   for (const task of stage.tasks ?? []) {
-    const inScope = await ctxEvaluateCondition(ctx, task.filter, { taskName: task.name });
+    const outcome = await ctxEvaluateConditionOutcome(ctx, task.filter, { taskName: task.name }), inScope = outcome !== "unsatisfied";
     entries.push({
       _key: randomKey(),
       name: task.name,
       status: inScope ? "pending" : "skipped",
-      ...task.filter !== void 0 ? {
-        filterEvaluation: {
-          at: ctx.now,
-          truthy: inScope
-        }
-      } : {}
+      ...task.filter !== void 0 ? { filterEvaluation: buildFilterEvaluation(ctx.now, task.filter, outcome) } : {}
     });
   }
   return entries;
 }
+function buildFilterEvaluation(at, filter, outcome) {
+  return outcome === "unevaluable" ? {
+    at,
+    truthy: !1,
+    unevaluable: !0,
+    detail: `Filter "${filter}" could not be evaluated (GROQ null \u2014 a referenced operand was missing or incomparable). Task kept in scope so the gate is not silently skipped.`
+  } : { at, truthy: outcome === "satisfied" };
+}
 function isTerminalStage(stage) {
   return (stage.transitions ?? []).length === 0;
 }
@@ -2221,8 +2350,11 @@ async function commitTransition(ctx, actor) {
   };
 }
 async function pickTransition(ctx, stage) {
-  for (const candidate of stage.transitions ?? [])
-    if (await ctxEvaluateCondition(ctx, candidate.filter)) return candidate;
+  for (const candidate of stage.transitions ?? []) {
+    const outcome = await ctxEvaluateConditionOutcome(ctx, candidate.filter);
+    if (outcome === "satisfied") return candidate;
+    if (outcome === "unevaluable") return;
+  }
 }
 async function evaluateAutoTransitions(args) {
   const { client, instanceId, options, clientForGdr, clock, overlay } = args, ctx = await loadContext(client, instanceId, {
@@ -2252,7 +2384,7 @@ async function primeInitialStage(client, instanceId, actor, clientForGdr, clock)
   }, committed = await client.patch(instance._id).set({
     stages: [initialStageEntry],
     lastChangedAt: now
-  }).ifRevisionId(instance._rev).commit();
+  }).ifRevisionId(instance._rev).commit(SYNC_COMMIT);
   await deployOrRollback({
     client,
     instanceId: instance._id,
@@ -2477,17 +2609,12 @@ async function fetchGrantsCached(requestFn, resourcePath) {
   }
 }
 async function evaluateInstance(args) {
-  const { client, tags, instanceId, resourceClients } = args, now = (args.clock ?? wallClock)();
-  validateTags(tags);
+  const { client, tag, instanceId, resourceClients } = args, now = (args.clock ?? wallClock)();
+  validateTag(tag);
   const { actor, grants } = await resolveAccess(client, {
     ...args.access !== void 0 ? { override: args.access } : {},
     ...args.grantsFromPath !== void 0 ? { grantsFromPath: args.grantsFromPath } : {}
-  }), instance = await client.getDocument(instanceId);
-  if (!instance)
-    throw new Error(`Workflow instance "${instanceId}" not found`);
-  if (!tags.some((t) => instance.tags?.includes(t)))
-    throw new Error(`Workflow instance "${instanceId}" not visible to this engine (tag mismatch)`);
-  const definition = parseDefinitionSnapshot(instance), snapshot = await hydrateSnapshot({ client, clientForGdr: resourceClients !== void 0 ? (parsed) => resourceClients(parsed) ?? client : () => client, instance }), guards = await verdictGuardsForInstance(client, instance._id);
+  }), instance = await reload(client, instanceId, tag), definition = parseDefinitionSnapshot(instance), snapshot = await hydrateSnapshot({ client, clientForGdr: resourceClients !== void 0 ? (parsed) => resourceClients(parsed) ?? client : () => client, instance }), guards = await verdictGuardsForInstance(client, instance._id);
   return evaluateFromSnapshot({
     instance,
     definition,
@@ -2519,15 +2646,18 @@ async function evaluateFromSnapshot(args) {
       })
     );
   const transitionEvaluations = [];
-  for (const transition of stage.transitions ?? [])
+  for (const transition of stage.transitions ?? []) {
+    const outcome = await evaluateConditionOutcome({
+      condition: transition.filter,
+      snapshot,
+      params: scope
+    });
     transitionEvaluations.push({
       transition,
-      filterSatisfied: await evaluateCondition({
-        condition: transition.filter,
-        snapshot,
-        params: scope
-      })
+      filterSatisfied: outcome === "satisfied",
+      unevaluable: outcome === "unevaluable"
     });
+  }
   const currentStage = {
     stage,
     tasks: taskEvaluations,
@@ -2575,7 +2705,11 @@ async function evaluateTask(args) {
       ...scopedStateOverlay(instance, snapshot, task.name)
     },
     assigned
-  }, actions = [];
+  }, unmetRequirements = await evaluateRequirements({
+    requirements: task.requirements,
+    snapshot,
+    params: taskScope
+  }), requirementsReason = unmetRequirements.length > 0 ? { kind: "requirements-unmet", unmetRequirements } : void 0, actions = [];
   for (const action of task.actions ?? [])
     actions.push(
       await evaluateAction({
@@ -2585,7 +2719,8 @@ async function evaluateTask(args) {
         snapshot,
         taskScope,
         stageHasExits,
-        guardDenial
+        guardDenial,
+        requirementsReason
       })
     );
   return {
@@ -2596,12 +2731,22 @@ async function evaluateTask(args) {
     // they're still inbox items. The inbox reads the assignees-kind state
     // entry BY KIND (who-data is state).
     pendingOnActor: (status === "active" || status === "pending") && assigned,
+    ...unmetRequirements.length > 0 ? { unmetRequirements } : {},
     actions
   };
 }
 async function evaluateAction(args) {
-  const { action, status, instance, snapshot, taskScope, stageHasExits, guardDenial } = args, lifecycle = lifecycleReason(instance, status, stageHasExits);
-  return lifecycle !== void 0 ? disabled(action, lifecycle) : guardDenial !== void 0 ? disabled(action, guardDenial) : action.filter !== void 0 && !await evaluateCondition({
+  const {
+    action,
+    status,
+    instance,
+    snapshot,
+    taskScope,
+    stageHasExits,
+    guardDenial,
+    requirementsReason
+  } = args, lifecycle = lifecycleReason(instance, status, stageHasExits);
+  return lifecycle !== void 0 ? disabled(action, lifecycle) : guardDenial !== void 0 ? disabled(action, guardDenial) : requirementsReason !== void 0 ? disabled(action, requirementsReason) : action.filter !== void 0 && !await evaluateCondition({
     condition: action.filter,
     snapshot,
     params: taskScope
@@ -2628,22 +2773,21 @@ function lifecycleReason(instance, status, stageHasExits) {
 function disabled(action, reason) {
   return { action, allowed: !1, disabledReason: reason };
 }
-function definitionDocId(_workflowResource, prefix, definition, version) {
-  return `${prefix}.${definition}.v${version}`;
+function definitionDocId(_workflowResource, tag, definition, version) {
+  return `${tag}.${definition}.v${version}`;
 }
-async function sortByDependencies(client, definitions, tags, workflowResource) {
-  const prefix = canonicalTag(tags), byName = /* @__PURE__ */ new Map();
+async function sortByDependencies(client, definitions, tag, workflowResource) {
+  const byName = /* @__PURE__ */ new Map();
   for (const def of definitions) {
     const list = byName.get(def.name) ?? [];
     list.push(def), byName.set(def.name, list);
   }
   const findInBatch = (ref) => findRefInBatch(byName, ref);
   return await assertCrossBatchRefsDeployed(client, definitions, {
-    tags,
+    tag,
     workflowResource,
-    prefix,
     findInBatch
-  }), topoSortDefinitions(definitions, { workflowResource, prefix, findInBatch });
+  }), topoSortDefinitions(definitions, { workflowResource, tag, findInBatch });
 }
 function findRefInBatch(byName, ref) {
   const candidates = byName.get(ref.name);
@@ -2656,10 +2800,10 @@ function findRefInBatch(byName, ref) {
 async function assertCrossBatchRefsDeployed(client, definitions, ctx) {
   const missing = [];
   for (const def of definitions) {
-    const fromId = definitionDocId(ctx.workflowResource, ctx.prefix, def.name, def.version);
+    const fromId = definitionDocId(ctx.workflowResource, ctx.tag, def.name, def.version);
     for (const ref of refsOf(def)) {
       if (ctx.findInBatch(ref) !== void 0) continue;
-      const label = await resolveDeployedRefLabel(client, ref, ctx.tags);
+      const label = await resolveDeployedRefLabel(client, ref, ctx.tag);
       label !== void 0 && missing.push({ from: fromId, ref: label });
     }
   }
@@ -2671,8 +2815,8 @@ async function assertCrossBatchRefsDeployed(client, definitions, ctx) {
 `)
   );
 }
-async function resolveDeployedRefLabel(client, ref, tags) {
-  const wantsExplicit = typeof ref.version == "number", params = { definition: ref.name, engineTags: tags };
+async function resolveDeployedRefLabel(client, ref, tag) {
+  const wantsExplicit = typeof ref.version == "number", params = { definition: ref.name, tag };
   if (wantsExplicit && (params.version = ref.version), !await client.fetch(
     definitionLookupGroq(wantsExplicit),
     params
@@ -2681,7 +2825,7 @@ async function resolveDeployedRefLabel(client, ref, tags) {
 }
 function topoSortDefinitions(definitions, ctx) {
   const visited = /* @__PURE__ */ new Set(), visiting = /* @__PURE__ */ new Set(), ordered = [], visit = (def) => {
-    const id = definitionDocId(ctx.workflowResource, ctx.prefix, def.name, def.version);
+    const id = definitionDocId(ctx.workflowResource, ctx.tag, def.name, def.version);
     if (!visited.has(id)) {
       if (visiting.has(id))
         throw new Error(`workflow.deployDefinitions: dependency cycle involving "${id}"`);
@@ -2722,11 +2866,11 @@ function stableStringify(value) {
     ([a], [b]) => a.localeCompare(b)
   ).map(([k, v2]) => `${JSON.stringify(k)}:${stableStringify(v2)}`).join(",")}}`;
 }
-async function loadDefinition(client, definition, version, tags) {
+async function loadDefinition(client, definition, version, tag) {
   if (version !== void 0) {
     const doc = await client.fetch(
       definitionLookupGroq(!0),
-      { definition, version, engineTags: tags }
+      { definition, version, tag }
     );
     if (!doc)
       throw new Error(`Workflow definition ${definition} v${version} not deployed`);
@@ -2734,16 +2878,16 @@ async function loadDefinition(client, definition, version, tags) {
   }
   const latest = await client.fetch(definitionLookupGroq(!1), {
     definition,
-    engineTags: tags
+    tag
   });
   if (!latest)
     throw new Error(`No deployed definition for workflow ${definition}`);
   return latest;
 }
-async function loadDefinitionVersions(client, definition, tags) {
+async function loadDefinitionVersions(client, definition, tag) {
   return client.fetch(
-    `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $definition && count(tags[@ in $engineTags]) > 0] | order(version desc)`,
-    { definition, engineTags: tags }
+    `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $definition && ${tagScopeFilter()}] | order(version desc)`,
+    { definition, tag }
   );
 }
 async function abortInstance(args) {
@@ -2879,7 +3023,8 @@ const disabledReasonDetail = {
   "task-not-active": (r) => `task status is "${r.status}"`,
   "stage-terminal": (r) => `stage "${r.stage}" 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})` : ""}`
+  "mutation-guard-denied": (r) => `blocked by mutation guard(s) [${r.guardIds.join(", ")}]${r.detail ? ` (${r.detail})` : ""}`,
+  "requirements-unmet": (r) => `unmet requirement(s): ${r.unmetRequirements.join(", ")}`
 };
 function formatDisabledReason(task, action, reason) {
   const detail = disabledReasonDetail[reason.kind](reason);
@@ -2894,7 +3039,7 @@ function bareIdFromSpawnRef(uri) {
   }
 }
 async function resolveOperationContext(args) {
-  validateTags(args.tags);
+  validateTag(args.tag);
   const access = await resolveAccess(args.client, {
     ...args.access !== void 0 ? { override: args.access } : {},
     ...args.grantsFromPath !== void 0 ? { grantsFromPath: args.grantsFromPath } : {}
@@ -2928,16 +3073,6 @@ async function abortAndPropagate(args) {
 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));
 }
@@ -2963,15 +3098,15 @@ async function applyAction(args) {
   })).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);
+  const { client, tag, definition, version, cascade: cascade2, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, versions = await loadDefinitionVersions(client, definition, tag);
   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);
+  await assertNoSpawnReferrers(client, tag, definition, targets, lastVersionGoes);
+  const instanceIds = await nonTerminalInstanceIds(client, tag, 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.`
@@ -2992,7 +3127,7 @@ async function deleteDefinition(args) {
     workflowResource: args.workflowResource,
     definition,
     definitions: versions,
-    tags
+    tag
   }) : 0;
   return {
     name: definition,
@@ -3001,10 +3136,10 @@ async function deleteDefinition(args) {
     deletedGuardCount
   };
 }
-async function assertNoSpawnReferrers(client, tags, definition, targets, lastVersionGoes) {
+async function assertNoSpawnReferrers(client, tag, definition, targets, lastVersionGoes) {
   const deployed = await client.fetch(
     `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && ${tagScopeFilter()}]`,
-    { engineTags: tags }
+    { tag }
   ), 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)
@@ -3017,11 +3152,11 @@ async function assertNoSpawnReferrers(client, tags, definition, targets, lastVer
     );
   }
 }
-async function nonTerminalInstanceIds(client, tags, definition, version) {
+async function nonTerminalInstanceIds(client, tag, 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 } : {} }
+    { definition, tag, ...version !== void 0 ? { version } : {} }
   )).map((doc) => doc._id);
 }
 async function abortInstances(args) {
@@ -3052,20 +3187,20 @@ const workflow = {
    * Cycles in the dependency graph error before any write happens.
    */
   deployDefinitions: async (args) => {
-    const { client, tags, workflowResource, definitions } = args;
-    validateTags(tags);
+    const { client, tag, workflowResource, definitions } = args;
+    validateTag(tag);
     for (const def of definitions)
       validateDefinition(def);
-    const ordered = await sortByDependencies(client, definitions, tags, workflowResource), results = [], prefix = canonicalTag(tags), tx = client.transaction();
+    const ordered = await sortByDependencies(client, definitions, tag, workflowResource), results = [], tx = client.transaction();
     let hasWrites = !1;
     for (const def of ordered) {
-      const id = definitionDocId(workflowResource, prefix, def.name, def.version), expected = {
+      const id = definitionDocId(workflowResource, tag, def.name, def.version), expected = {
         ...def,
         _id: id,
         _type: WORKFLOW_DEFINITION_TYPE,
-        tags
+        tag
       }, existing = await client.getDocument(id);
-      if (existing && intersectsTags(existing.tags, tags) && isDefinitionUnchanged(existing, expected)) {
+      if (existing && existing.tag === tag && isDefinitionUnchanged(existing, expected)) {
         results.push({ definition: def.name, version: def.version, status: "unchanged" });
         continue;
       }
@@ -3103,7 +3238,7 @@ const workflow = {
   startInstance: async (args) => {
     const {
       client,
-      tags,
+      tag,
       workflowResource,
       definition: definitionName,
       version,
@@ -3112,7 +3247,7 @@ const workflow = {
       effectsContext,
       instanceId,
       perspective
-    } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, definition = await loadDefinition(client, definitionName, version, tags), id = instanceId ?? `${canonicalTag(tags)}.wf-instance.${randomKey()}`;
+    } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, definition = await loadDefinition(client, definitionName, version, tag), id = instanceId ?? `${tag}.wf-instance.${randomKey()}`;
     if (definition.stages.find((s) => s.name === definition.initialStage) === void 0)
       throw new Error(
         `Initial stage "${definition.initialStage}" missing in ${definitionName} v${definition.version}`
@@ -3124,7 +3259,7 @@ const workflow = {
         client,
         now,
         selfId: id,
-        tags,
+        tag,
         workflowResource,
         ...perspective !== void 0 ? { perspective } : {}
       },
@@ -3132,7 +3267,7 @@ const workflow = {
     }), effectivePerspective = perspective ?? derivePerspectiveFromState(resolvedState), base = buildInstanceBase({
       id,
       now,
-      tags,
+      tag,
       workflowResource,
       definitionName: definition.name,
       pinnedVersion: definition.version,
@@ -3144,7 +3279,7 @@ const workflow = {
       initialStage: definition.initialStage,
       actor
     });
-    return await client.create(base), await primeInitialStage(client, id, actor, clientForGdr, clock), await cascade(client, id, actor, clientForGdr, clock), reload(client, id, tags);
+    return await client.create(base, SYNC_COMMIT), await primeInitialStage(client, id, actor, clientForGdr, clock), await cascade(client, id, actor, clientForGdr, clock), reload(client, id, tag);
   },
   /**
    * Fire an action against a task. If the task is pending, it is
@@ -3159,19 +3294,19 @@ const workflow = {
   fireAction: async (args) => {
     const {
       client,
-      tags,
+      tag,
       instanceId,
       task,
       action,
       params,
       idempotent,
       resourceClients
-    } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, before = await reload(client, instanceId, tags);
+    } = args, { access, actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, before = await reload(client, instanceId, tag);
     if (findOpenStageEntry(before)?.tasks.find((t) => t.name === task) === void 0 && idempotent === !0)
       return { instance: before, cascaded: 0, fired: !1 };
     const evaluation = await evaluateInstance({
       client,
-      tags,
+      tag,
       instanceId,
       access,
       clock,
@@ -3190,7 +3325,7 @@ const workflow = {
       ...params !== void 0 ? { params } : {}
     }), cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
-      instance: await reload(client, instanceId, tags),
+      instance: await reload(client, instanceId, tag),
       cascaded,
       fired: !0,
       ...ranOps !== void 0 ? { ranOps } : {}
@@ -3204,7 +3339,7 @@ const workflow = {
    * reference them. Cascades after.
    */
   completeEffect: async (args) => {
-    const { client, tags, instanceId, effectKey, status, outputs, detail, error, durationMs } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
+    const { client, tag, instanceId, effectKey, status, outputs, detail, error, durationMs } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
     await completeEffect({
       client,
       instanceId,
@@ -3218,7 +3353,7 @@ const workflow = {
     });
     const cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
-      instance: await reload(client, instanceId, tags),
+      instance: await reload(client, instanceId, tag),
       cascaded,
       fired: !0
     };
@@ -3233,11 +3368,11 @@ const workflow = {
    * affected instances and the engine re-evaluates.
    */
   tick: async (args) => {
-    const { client, tags, instanceId } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, current = await reload(client, instanceId, tags), guards = await verdictGuardsForInstance(client, current._id);
+    const { client, tag, instanceId } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock, current = await reload(client, instanceId, tag), guards = await verdictGuardsForInstance(client, current._id);
     await assertInstanceWriteAllowed({ instance: current, guards, identity: actor.id });
     const cascaded = await cascade(client, instanceId, actor, clientForGdr, clock);
     return {
-      instance: await reload(client, instanceId, tags),
+      instance: await reload(client, instanceId, tag),
       cascaded,
       fired: cascaded > 0
     };
@@ -3248,8 +3383,8 @@ const workflow = {
    * upstream; this verb performs the mechanical move.
    */
   setStage: async (args) => {
-    const { client, tags, instanceId, targetStage, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
-    await reload(client, instanceId, tags);
+    const { client, tag, instanceId, targetStage, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
+    await reload(client, instanceId, tag);
     const result = await setStage({
       client,
       instanceId,
@@ -3258,7 +3393,7 @@ const workflow = {
       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),
+      instance: await reload(client, instanceId, tag),
       cascaded,
       fired: result.fired
     };
@@ -3270,28 +3405,28 @@ const workflow = {
    * 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 { client, tag, instanceId, reason } = args, { actor, clientForGdr } = await resolveOperationContext(args), clock = args.clock ?? wallClock;
+    await reload(client, instanceId, tag);
     const fired = await abortAndPropagate({ client, instanceId, reason, actor, clientForGdr, clock });
     return {
-      instance: await reload(client, instanceId, tags),
+      instance: await reload(client, instanceId, tag),
       cascaded: 0,
       fired
     };
   },
   /**
-   * Fetch a workflow instance by id, scoped to the engine's tags.
+   * Fetch a workflow instance by id, scoped to the engine's tag.
    * 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);
+    const { client, tag, instanceId } = args;
+    return validateTag(tag), reload(client, instanceId, tag);
   },
   guardsForInstance: async (args) => {
-    const { client, tags, instanceId, resourceClients } = args;
-    validateTags(tags);
-    const instance = await reload(client, instanceId, tags);
+    const { client, tag, instanceId, resourceClients } = args;
+    validateTag(tag);
+    const instance = await reload(client, instanceId, tag);
     return guardsForInstance({
       client,
       clientForGdr: buildClientForGdr(client, resourceClients),
@@ -3299,9 +3434,9 @@ const workflow = {
     });
   },
   guardsForDefinition: async (args) => {
-    const { client, tags, workflowResource, definition, resourceClients } = args;
-    validateTags(tags);
-    const definitions = await loadDefinitionVersions(client, definition, tags);
+    const { client, tag, workflowResource, definition, resourceClients } = args;
+    validateTag(tag);
+    const definitions = await loadDefinitionVersions(client, definition, tag);
     if (definitions.length === 0)
       throw new Error(`No deployed definition for workflow ${definition}`);
     return guardsForDefinition({
@@ -3313,22 +3448,21 @@ const workflow = {
     });
   },
   /**
-   * Run a caller-supplied GROQ query with the engine's tags bound as
-   * `$engineTags`. This does NOT rewrite the query — arbitrary GROQ
+   * Run a caller-supplied GROQ query with the engine's tag bound as
+   * `$tag`. 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
+   * filter on `$tag` (e.g. `tag == $tag`). To guard against accidental
+   * cross-partition reads, a query that never references `$tag` 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"))
+    const { client, tag, groq, params } = args;
+    if (validateTag(tag), !/\$tag\b/.test(groq))
       throw new Error(
-        `workflow.query: query must filter on $engineTags to stay tag-scoped (e.g. "count(tags[@ in $engineTags]) > 0"); got: ${groq}`
+        `workflow.query: query must filter on $tag to stay tag-scoped (e.g. "tag == $tag"); got: ${groq}`
       );
-    return client.fetch(groq, { ...params, engineTags: tags });
+    return client.fetch(groq, { ...params, tag });
   },
   /**
    * Snapshot-aware GROQ — runs against the same in-memory view that
@@ -3347,9 +3481,9 @@ const workflow = {
    * without re-implementing hydration. Pure read — never writes.
    */
   queryInScope: async (args) => {
-    const { client, tags, instanceId, groq, params, resourceClients } = args, clock = args.clock ?? wallClock;
-    validateTags(tags);
-    const instance = await reload(client, instanceId, tags), clientForGdr = buildClientForGdr(client, resourceClients), snapshot = await hydrateSnapshot({ client, clientForGdr, instance }), reserved = buildParams({ instance, now: clock(), snapshot }), tree = parse(groq, { params: { ...reserved, ...params } });
+    const { client, tag, instanceId, groq, params, resourceClients } = args, clock = args.clock ?? wallClock;
+    validateTag(tag);
+    const instance = await reload(client, instanceId, tag), clientForGdr = buildClientForGdr(client, resourceClients), snapshot = await hydrateSnapshot({ client, clientForGdr, instance }), reserved = buildParams({ instance, now: clock(), snapshot }), tree = parse(groq, { params: { ...reserved, ...params } });
     return await (await evaluate(tree, {
       dataset: snapshot.docs,
       params: { ...reserved, ...params }
@@ -3359,13 +3493,13 @@ const workflow = {
    * 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,
+  listPendingEffects: async (args) => (await reload(args.client, args.instanceId, args.tag)).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.name))),
+  findPendingEffects: async (args) => (await reload(args.client, args.instanceId, args.tag)).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.name))),
   /**
    * Project the instance from a given actor's perspective. Returns a
    * `WorkflowEvaluation` with per-action verdicts (`allowed` + a
@@ -3385,8 +3519,8 @@ const workflow = {
    * Pure read.
    */
   diagnose: async (args) => {
-    const evaluation = await evaluateInstance(args);
-    return { evaluation, diagnosis: diagnoseInstance(diagnoseInputFromEvaluation(evaluation)) };
+    const evaluation = await evaluateInstance(args), diagnosis = diagnoseInstance(diagnoseInputFromEvaluation(evaluation));
+    return { evaluation, diagnosis, remediations: remediationsFor(diagnosis) };
   },
   /**
    * List the actions an actor could fire on an instance's current stage,
@@ -3406,18 +3540,18 @@ const workflow = {
    * 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
+   * instances, drops any that aren't visible to this engine's tag, and
    * returns them sorted by `startedAt` ascending.
    *
    * Pass `task` to restrict to a single spawning task on the parent.
    */
   children: async (args) => {
-    const { client, tags, instanceId, task } = args;
-    validateTags(tags);
-    const parent = await reload(client, instanceId, tags), isSpawned = (h) => h._type === "spawned", ids = parent.history.filter(isSpawned).filter((h) => task === void 0 || h.task === task).flatMap((h) => bareIdFromSpawnRef(h.instanceRef.id));
+    const { client, tag, instanceId, task } = args;
+    validateTag(tag);
+    const parent = await reload(client, instanceId, tag), isSpawned = (h) => h._type === "spawned", ids = parent.history.filter(isSpawned).filter((h) => task === void 0 || h.task === task).flatMap((h) => bareIdFromSpawnRef(h.instanceRef.id));
     return ids.length === 0 ? [] : client.fetch(
       `*[_id in $ids && ${tagScopeFilter()}] | order(startedAt asc)`,
-      { ids, engineTags: tags }
+      { ids, tag }
     );
   },
   /**
@@ -3432,11 +3566,11 @@ const workflow = {
   }
 };
 async function verifyDeployedDefinitionsInternal(args) {
-  const { client, tags, effectHandlers, missingHandler, logger } = args;
-  validateTags(tags);
+  const { client, tag, effectHandlers, missingHandler, logger } = args;
+  validateTag(tag);
   const log = logger("verifyDeployedDefinitions"), definitions = await client.fetch(
     `*[_type == "${WORKFLOW_DEFINITION_TYPE}" && ${tagScopeFilter()}] | order(name asc, version asc)`,
-    { engineTags: tags }
+    { tag }
   ), seen = [], missingByName = /* @__PURE__ */ new Map();
   for (const def of definitions)
     seen.push({ name: def.name, version: def.version, _id: def._id }), walkEffectNames(def, (name, location) => {
@@ -3485,7 +3619,7 @@ function walkEffectNames(def, visit) {
 async function drainEffectsInternal(args) {
   const {
     client,
-    tags,
+    tag,
     workflowResource,
     resourceClients,
     instanceId,
@@ -3496,10 +3630,10 @@ async function drainEffectsInternal(args) {
     actor: drainerActor,
     ...args.access?.grants !== void 0 ? { grants: args.access.grants } : {}
   };
-  validateTags(tags);
+  validateTag(tag);
   const log = logger("drainEffects"), drained = [], failed = [], skipped = [], skippedKeys = /* @__PURE__ */ new Set();
   for (; ; ) {
-    const before = await reload(client, instanceId, tags), candidate = before.pendingEffects.find(
+    const before = await reload(client, instanceId, tag), candidate = before.pendingEffects.find(
       (e) => e.claim === void 0 && !skippedKeys.has(e._key)
     );
     if (candidate === void 0) break;
@@ -3516,7 +3650,7 @@ async function drainEffectsInternal(args) {
     });
     await reportEffectOutcome({
       client,
-      tags,
+      tag,
       workflowResource,
       ...resourceClients !== void 0 ? { resourceClients } : {},
       instanceId,
@@ -3555,7 +3689,7 @@ async function claimPendingEffect(client, instance, effectKey, drainerActor) {
     claimedBy: drainerActor
   };
   try {
-    return await client.patch(instance._id).ifRevisionId(instance._rev).set({ [`pendingEffects[_key=="${effectKey}"].claim`]: claim }).commit(), !0;
+    return await client.patch(instance._id).ifRevisionId(instance._rev).set({ [`pendingEffects[_key=="${effectKey}"].claim`]: claim }).commit(SYNC_COMMIT), !0;
   } catch (error) {
     if (!isRevisionConflict(error)) throw error;
     return !1;
@@ -3586,7 +3720,7 @@ async function applyMissingHandler(policy, info, log) {
   }
 }
 function createInstanceSession(args) {
-  const { client, tags, clock } = args, clientForGdr = buildClientForGdr(client, args.resourceClients);
+  const { client, tag, clock } = args, clientForGdr = buildClientForGdr(client, args.resourceClients);
   let instance = asHeldInstance(args.instance), overlay = /* @__PURE__ */ new Map(), heldGuards = [], committing = !1, buffered;
   const selfUri = () => gdrFromResource(instance.workflowResource, instance._id), applyUpdate = (docs) => {
     const next = /* @__PURE__ */ new Map();
@@ -3647,7 +3781,7 @@ function createInstanceSession(args) {
       return commit(async (actor, held) => {
         await assertInstanceWriteAllowed({ instance, guards: heldGuards, identity: actor.id });
         const cascaded = await cascade(client, instance._id, actor, clientForGdr, clock, held);
-        return instance = await reload(client, instance._id, tags), { instance, cascaded, fired: cascaded > 0 };
+        return instance = await reload(client, instance._id, tag), { instance, cascaded, fired: cascaded > 0 };
       });
     },
     fireAction({ task, action, params }) {
@@ -3664,7 +3798,7 @@ function createInstanceSession(args) {
           ...clock !== void 0 ? { clock } : {},
           ...params !== void 0 ? { params } : {}
         }), cascaded = await cascade(client, instance._id, actor, clientForGdr, clock, held);
-        return instance = await reload(client, instance._id, tags), { instance, cascaded, fired: !0, ...ranOps !== void 0 ? { ranOps } : {} };
+        return instance = await reload(client, instance._id, tag), { instance, cascaded, fired: !0, ...ranOps !== void 0 ? { ranOps } : {} };
       });
     }
   };
@@ -3692,11 +3826,11 @@ const defaultLoggerFactory = (name) => ({
   }
 };
 function createEngine(args) {
-  const { client, workflowResource, tags, resourceClients, clock } = args;
-  validateTags(tags);
+  const { client, workflowResource, resourceClients, clock, tag } = args;
+  validateTag(tag);
   const effectHandlers = args.effectHandlers ?? {}, missingHandler = args.missingHandler ?? "fail", logger = args.loggerFactory ?? defaultLoggerFactory, bind = (rest) => ({
     client,
-    tags,
+    tag,
     workflowResource,
     ...resourceClients !== void 0 ? { resourceClients } : {},
     ...clock !== void 0 ? { clock } : {},
@@ -3704,7 +3838,7 @@ function createEngine(args) {
   });
   return {
     client,
-    tags,
+    tag,
     workflowResource,
     effectHandlers,
     missingHandler,
@@ -3720,11 +3854,11 @@ function createEngine(args) {
     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),
+    getInstance: ({ instanceId }) => workflow.getInstance({ client, tag, workflowResource, instanceId }),
+    subscriptionDocumentsForInstance: ({ instanceId }) => workflow.getInstance({ client, tag, workflowResource, instanceId }).then(subscriptionDocumentsForInstance),
     instance: (instanceDoc, opts) => createInstanceSession({
       client,
-      tags,
+      tag,
       instance: instanceDoc,
       ...resourceClients !== void 0 ? { resourceClients } : {},
       ...clock !== void 0 ? { clock } : {},
@@ -3733,45 +3867,45 @@ function createEngine(args) {
     }),
     guardsForInstance: ({ instanceId }) => workflow.guardsForInstance({
       client,
-      tags,
+      tag,
       workflowResource,
       instanceId,
       ...resourceClients !== void 0 ? { resourceClients } : {}
     }),
     guardsForDefinition: ({ definition }) => workflow.guardsForDefinition({
       client,
-      tags,
+      tag,
       workflowResource,
       definition,
       ...resourceClients !== void 0 ? { resourceClients } : {}
     }),
     children: ({ instanceId, task }) => workflow.children({
       client,
-      tags,
+      tag,
       workflowResource,
       instanceId,
       ...task !== void 0 ? { task } : {}
     }),
     query: ({ groq, params }) => workflow.query({
       client,
-      tags,
+      tag,
       workflowResource,
       groq,
       ...params !== void 0 ? { params } : {}
     }),
     queryInScope: ({ instanceId, groq, params }) => workflow.queryInScope({
       client,
-      tags,
+      tag,
       workflowResource,
       instanceId,
       groq,
       ...params !== void 0 ? { params } : {},
       ...clock !== void 0 ? { clock } : {}
     }),
-    listPendingEffects: ({ instanceId }) => workflow.listPendingEffects({ client, tags, workflowResource, instanceId }),
+    listPendingEffects: ({ instanceId }) => workflow.listPendingEffects({ client, tag, workflowResource, instanceId }),
     findPendingEffects: ({ instanceId, claimed, names }) => workflow.findPendingEffects({
       client,
-      tags,
+      tag,
       workflowResource,
       instanceId,
       ...claimed !== void 0 ? { claimed } : {},
@@ -3779,7 +3913,7 @@ function createEngine(args) {
     }),
     drainEffects: ({ instanceId, access }) => drainEffectsInternal({
       client,
-      tags,
+      tag,
       workflowResource,
       ...resourceClients !== void 0 ? { resourceClients } : {},
       instanceId,
@@ -3790,7 +3924,7 @@ function createEngine(args) {
     }),
     verifyDeployedDefinitions: () => verifyDeployedDefinitionsInternal({
       client,
-      tags,
+      tag,
       effectHandlers,
       missingHandler,
       logger
@@ -3798,7 +3932,7 @@ function createEngine(args) {
   };
 }
 function docIdFor(def, target) {
-  return definitionDocId(target.workflowResource, canonicalTag(target.tags), def.name, def.version);
+  return definitionDocId(target.workflowResource, target.tag, def.name, def.version);
 }
 function diffStatus(existing, expected) {
   return existing === void 0 ? "create" : isDefinitionUnchanged(existing, expected) ? "unchanged" : "update";
@@ -3808,7 +3942,7 @@ function diffEntry(def, existingRaw, target) {
     ...def,
     _id: docId,
     _type: WORKFLOW_DEFINITION_TYPE,
-    tags: target.tags
+    tag: target.tag
   }, status = diffStatus(existingRaw, expected), existing = existingRaw ? stripSystemFields(existingRaw) : void 0;
   return {
     name: def.name,
@@ -4008,6 +4142,7 @@ export {
   ActionParamsInvalidError,
   CascadeLimitError,
   ConcurrentFireActionError,
+  DEFAULT_CONTENT_PERSPECTIVE,
   DISPLAY,
   EFFECTS_CONTEXT_DISPLAY,
   GUARD_DOC_TYPE,
@@ -4022,10 +4157,8 @@ export {
   WorkflowStateDivergedError,
   abortReason,
   actionVerdict,
-  assigneesOf,
   availableActions,
   buildSnapshot,
-  canonicalTag,
   compileGuard,
   computeDiffEntries,
   contentReleaseName,
@@ -4055,13 +4188,13 @@ export {
   isGdr,
   isTerminalStage,
   lakeGuardId,
-  openStage,
   parseGdr,
   readsRaw,
   refCanvas,
   refDashboard,
   refDataset,
   refMediaLibrary,
+  remediationsFor,
   resolveAccess,
   resourceFromParsed,
   retractStageGuards,
@@ -4071,7 +4204,7 @@ export {
   subscriptionDocumentsForInstance,
   tagScopeFilter,
   validateDefinition,
-  validateTags,
+  validateTag,
   verdictGuardsForInstance,
   wallClock,
   workflow