@sanity/workflow-engine 0.2.0 → 0.4.0

package/dist/define.js

@@ -1,506 +1,512 @@
 import * as v from "valibot";
+import { GROQ_IDENTIFIER, formatValidationError, issuesFromValibot, AuthoringWorkflowSchema, AuthoringStageSchema, AuthoringTaskSchema, AuthoringActionSchema, AuthoringTransitionSchema, AuthoringStateEntrySchema, AuthoringOpSchema, GuardSchema, EffectSchema } from "./_chunks-es/schema.js";
+function groq(strings, ...values) {
+  return strings.reduce((out, part, i) => i === 0 ? part : `${out}${serializeGroqValue(values[i - 1])}${part}`, "");
+}
+function serializeGroqValue(value) {
+  const serialized = JSON.stringify(value);
+  if (serialized === void 0)
+    throw new Error(
+      `groq tag cannot serialize ${typeof value} \u2014 interpolate JSON-representable values only`
+    );
+  return serialized;
+}
+function desugarWorkflow(authoring) {
+  const ctx = { issues: [], claimStates: /* @__PURE__ */ new Map(), claimedStates: /* @__PURE__ */ new Set() }, workflowState = desugarStateEntries(authoring.state, ["state"], ctx), workflowLayer = layerOf(workflowState), stages = authoring.stages.map((stage, i) => {
+    const path = ["stages", i], stageState = desugarStateEntries(stage.state, [...path, "state"], ctx), stageEnv = {
+      layers: [
+        { scope: "stage", entries: layerOf(stageState) },
+        { scope: "workflow", entries: workflowLayer }
+      ]
+    }, tasks = (stage.tasks ?? []).map(
+      (task, j) => desugarTask(task, [...path, "tasks", j], stageEnv, ctx)
+    ), transitions = (stage.transitions ?? []).map(
+      (transition, k) => desugarTransition(transition, [...path, "transitions", k], stageEnv, ctx)
+    );
+    return {
+      ...stripUndefined({
+        name: stage.name,
+        title: stage.title,
+        description: stage.description,
+        guards: stage.guards
+      }),
+      ...stageState ? { state: stageState } : {},
+      ...tasks.length > 0 ? { tasks } : {},
+      ...transitions.length > 0 ? { transitions } : {}
+    };
+  });
+  return checkUnclaimedClaimStates(ctx), { definition: {
+    ...stripUndefined({
+      name: authoring.name,
+      version: authoring.version,
+      title: authoring.title,
+      description: authoring.description,
+      initialStage: authoring.initialStage,
+      predicates: authoring.predicates
+    }),
+    ...workflowState ? { state: workflowState } : {},
+    stages
+  }, issues: ctx.issues };
+}
+function desugarStateEntries(entries, path, ctx) {
+  return !entries || entries.length === 0 ? entries === void 0 ? void 0 : [] : entries.map((entry, i) => {
+    if (entry.type !== "claim") return entry;
+    const desugared = {
+      ...stripUndefined({ name: entry.name, title: entry.title, description: entry.description }),
+      type: "value.actor",
+      source: { type: "write" }
+    };
+    return ctx.claimStates.set(desugared, { name: entry.name, path: [...path, i] }), desugared;
+  });
+}
+function layerOf(entries) {
+  return new Map((entries ?? []).map((entry) => [entry.name, entry]));
+}
+function desugarTask(task, path, stageEnv, ctx) {
+  const taskState = desugarStateEntries(task.state, [...path, "state"], ctx), env = {
+    layers: [{ scope: "task", entries: layerOf(taskState) }, ...stageEnv.layers]
+  }, ops = desugarOps(task.ops, [...path, "ops"], env, task.name, ctx), actions = (task.actions ?? []).map(
+    (action, a) => desugarAction(action, [...path, "actions", a], env, task.name, ctx)
+  );
+  return {
+    ...stripUndefined({
+      name: task.name,
+      title: task.title,
+      description: task.description,
+      filter: task.filter,
+      completeWhen: task.completeWhen,
+      failWhen: task.failWhen,
+      effects: task.effects,
+      subworkflows: task.subworkflows
+    }),
+    activation: task.activation ?? "manual",
+    ...taskState ? { state: taskState } : {},
+    ...ops ? { ops } : {},
+    ...actions.length > 0 ? { actions } : {}
+  };
+}
+function desugarAction(action, path, env, taskName, ctx) {
+  if ("type" in action)
+    return desugarClaimAction(action, path, env, ctx);
+  const filter = composeFilter([rolesCondition(action.roles), action.filter]), ops = desugarOps(action.ops, [...path, "ops"], env, taskName, ctx) ?? [];
+  return action.status !== void 0 && ops.push({ type: "status.set", task: taskName, status: action.status }), {
+    ...stripUndefined({
+      name: action.name,
+      title: action.title,
+      description: action.description,
+      params: action.params,
+      effects: action.effects
+    }),
+    ...filter ? { filter } : {},
+    ...ops.length > 0 ? { ops } : {}
+  };
+}
+function desugarClaimAction(action, path, env, ctx) {
+  const ref = typeof action.state == "string" ? { state: action.state } : action.state, resolved = resolveRef(ref, env, [...path, "state"], ctx);
+  if (resolved) {
+    const entry = entryAt(env, resolved);
+    entry && entry.type !== "value.actor" && ctx.issues.push({
+      path: [...path, "state"],
+      message: `claim action "${action.name}" references "${resolved.state}" of kind "${entry.type}" \u2014 a claim pair needs an actor-valued entry (a "claim" or "value.actor" state declaration)`
+    }), checkShadowedClaimTarget(action.name, ref.state, resolved, env, [...path, "state"], ctx), entry && ctx.claimedStates.add(entry);
+  }
+  const noSteal = `!defined($state.${ref.state})`, filter = composeFilter([noSteal, rolesCondition(action.roles), action.filter]), ops = resolved ? [{ type: "state.set", target: resolved, value: { type: "actor" } }] : [];
+  return {
+    ...stripUndefined({
+      name: action.name,
+      title: action.title,
+      description: action.description,
+      params: action.params,
+      effects: action.effects
+    }),
+    filter,
+    ...ops.length > 0 ? { ops } : {}
+  };
+}
+function checkShadowedClaimTarget(actionName, state, resolved, env, path, ctx) {
+  const nearest = env.layers.find((l) => l.entries.has(state));
+  nearest === void 0 || nearest.scope === resolved.scope || ctx.issues.push({
+    path,
+    message: `claim action "${actionName}" targets "${state}" at scope "${resolved.scope}", but a nearer ${nearest.scope}-scope entry of the same name shadows it in $state \u2014 the no-steal filter would read the shadowing entry while the claim writes the "${resolved.scope}" one. Rename one of the entries or claim the nearer one`
+  });
+}
+function checkUnclaimedClaimStates(ctx) {
+  for (const [entry, { name, path }] of ctx.claimStates)
+    ctx.claimedStates.has(entry) || ctx.issues.push({
+      path,
+      message: `claim state "${name}" is never referenced by a claim action \u2014 you announced the pattern and wrote half of it. Declare a defineAction({ type: "claim", state: "${name}" }) or use a raw value.actor entry`
+    });
+}
+function desugarTransition(transition, path, stageEnv, ctx) {
+  const ops = desugarOps(transition.ops, [...path, "ops"], stageEnv, void 0, ctx);
+  return {
+    ...stripUndefined({
+      name: transition.name,
+      title: transition.title,
+      description: transition.description,
+      to: transition.to,
+      effects: transition.effects
+    }),
+    filter: transition.filter ?? "$allTasksDone",
+    ...ops ? { ops } : {}
+  };
+}
+function desugarOps(ops, path, env, firingTask, ctx) {
+  if (ops)
+    return ops.map((op, i) => desugarOp(op, [...path, i], env, firingTask, ctx));
+}
+function desugarOp(op, path, env, firingTask, ctx) {
+  if (op.type === "status.set") {
+    const task = op.task ?? firingTask;
+    return task === void 0 && ctx.issues.push({
+      path: [...path, "task"],
+      message: "status.set outside an action must name its target task"
+    }), { type: "status.set", task: task ?? "", status: op.status };
+  }
+  if (op.type === "audit") return desugarAuditOp(op, path, env, ctx);
+  const target = resolveRef(op.target, env, [...path, "target"], ctx) ?? fallbackRef(op.target);
+  return { ...op, target };
+}
+const AUDIT_STAMPS = { actor: { type: "actor" }, at: { type: "now" } };
+function desugarAuditOp(op, path, env, ctx) {
+  const target = resolveRef(op.target, env, [...path, "target"], ctx) ?? fallbackRef(op.target);
+  if (op.value.type !== "object")
+    return ctx.issues.push({
+      path: [...path, "value"],
+      message: `audit value must be an object source carrying the domain fields (got "${op.value.type}")`
+    }), { type: "state.append", target, value: op.value };
+  const actorField = op.stampFields?.actor ?? "actor", atField = op.stampFields?.at ?? "at", fields = { ...op.value.fields };
+  for (const [stamp, source] of [
+    [actorField, AUDIT_STAMPS.actor],
+    [atField, AUDIT_STAMPS.at]
+  ]) {
+    if (stamp in fields) {
+      ctx.issues.push({
+        path: [...path, "value", "fields", stamp],
+        message: `audit stamp field "${stamp}" collides with an authored domain field \u2014 rename yours or remap the stamp via stampFields`
+      });
+      continue;
+    }
+    fields[stamp] = source;
+  }
+  return { type: "state.append", target, value: { type: "object", fields } };
+}
+function resolveRef(ref, env, path, ctx) {
+  const layers = ref.scope === void 0 ? env.layers : env.layers.filter((l) => l.scope === ref.scope);
+  for (const layer of layers)
+    if (layer.entries.has(ref.state)) return { scope: layer.scope, state: ref.state };
+  const reachable = env.layers.flatMap((l) => [...l.entries.keys()].map((n) => `${l.scope}:${n}`));
+  ctx.issues.push({
+    path,
+    message: `state reference "${ref.state}"${ref.scope ? ` (scope "${ref.scope}")` : ""} does not resolve to a declared entry. Reachable: ${reachable.join(", ") || "(none)"}`
+  });
+}
+function entryAt(env, ref) {
+  return env.layers.find((l) => l.scope === ref.scope)?.entries.get(ref.state);
+}
+function fallbackRef(ref) {
+  return { scope: ref.scope ?? "workflow", state: ref.state };
+}
+function rolesCondition(roles) {
+  if (!(!roles || roles.length === 0))
+    return groq`count($actor.roles[@ in ${roles}]) > 0`;
+}
+function composeFilter(parts) {
+  const present = parts.filter((p) => p !== void 0);
+  if (present.length !== 0)
+    return present.length === 1 ? present[0] : present.map((p) => `(${p})`).join(" && ");
+}
+function stripUndefined(obj) {
+  const out = {};
+  for (const [k, value] of Object.entries(obj))
+    value !== void 0 && (out[k] = value);
+  return out;
+}
+const RESERVED_CONDITION_VARS = [
+  "state",
+  "actor",
+  "assigned",
+  "can",
+  "row",
+  "now",
+  "effects",
+  "tasks",
+  "subworkflows",
+  "self",
+  "stage",
+  "parent",
+  "ancestors",
+  "allTasksDone",
+  "anyTaskFailed"
+], PREDICATE_CALLER_VARS = ["actor", "assigned", "can"];
 function knownList(ids) {
   return [...ids].map((s) => `"${s}"`).join(", ");
 }
-function checkStagesAndTasks(def, issues) {
-  const stageIds = /* @__PURE__ */ new Set();
-  for (const [i, stage] of def.stages.entries())
-    stageIds.has(stage.id) && issues.push({
-      path: ["stages", i, "id"],
-      message: `duplicate stage id "${stage.id}" (already declared earlier)`
-    }), stageIds.add(stage.id), stage.kind === "terminal" && stage.transitions && stage.transitions.length > 0 && issues.push({
-      path: ["stages", i, "transitions"],
-      message: `terminal stage "${stage.id}" must not declare transitions`
-    }), checkDuplicateTaskIds(stage, i, issues);
-  return stageIds;
-}
-function checkDuplicateTaskIds(stage, i, issues) {
-  const taskIds = /* @__PURE__ */ new Set();
-  for (const [j, task] of (stage.tasks ?? []).entries())
-    taskIds.has(task.id) && issues.push({
-      path: ["stages", i, "tasks", j, "id"],
-      message: `duplicate task id "${task.id}" in stage "${stage.id}"`
-    }), taskIds.add(task.id);
-}
-function checkInitialStage(def, stageIds, issues) {
-  stageIds.has(def.initialStageId) || issues.push({
-    path: ["initialStageId"],
-    message: `initialStageId "${def.initialStageId}" is not a declared stage. Known stages: ${knownList(stageIds)}`
+function checkDuplicates(names, what, issues) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const { name, path } of names)
+    seen.has(name) && issues.push({ path, message: `duplicate ${what} "${name}" (already declared earlier)` }), seen.add(name);
+  return seen;
+}
+function checkStages(def, issues) {
+  const stageNames = checkDuplicates(
+    def.stages.map((stage, i) => ({ name: stage.name, path: ["stages", i, "name"] })),
+    "stage name",
+    issues
+  );
+  for (const [i, stage] of def.stages.entries()) {
+    const taskNames = checkDuplicates(
+      (stage.tasks ?? []).map((task, j) => ({
+        name: task.name,
+        path: ["stages", i, "tasks", j, "name"]
+      })),
+      `task name in stage "${stage.name}"`,
+      issues
+    );
+    checkDuplicates(
+      (stage.transitions ?? []).map((t, k) => ({
+        name: t.name,
+        path: ["stages", i, "transitions", k, "name"]
+      })),
+      `transition name in stage "${stage.name}"`,
+      issues
+    ), checkTasks(def, i, taskNames, issues);
+  }
+  return stageNames;
+}
+function checkTasks(def, i, taskNames, issues) {
+  const stage = def.stages[i];
+  for (const [j, task] of (stage.tasks ?? []).entries()) {
+    const path = ["stages", i, "tasks", j];
+    checkDuplicates(
+      (task.actions ?? []).map((action, a) => ({
+        name: action.name,
+        path: [...path, "actions", a, "name"]
+      })),
+      `action name in task "${task.name}"`,
+      issues
+    ), checkStatusSetTargets(task, taskNames, path, issues);
+  }
+}
+function checkStatusSetTargets(task, taskNames, path, issues) {
+  checkStatusSetOps(task.ops, taskNames, [...path, "ops"], issues);
+  for (const [a, action] of (task.actions ?? []).entries())
+    checkStatusSetOps(action.ops, taskNames, [...path, "actions", a, "ops"], issues);
+}
+function checkStatusSetOps(ops, taskNames, path, issues) {
+  for (const [o, op] of (ops ?? []).entries())
+    op.type !== "status.set" || taskNames.has(op.task) || issues.push({
+      path: [...path, o, "task"],
+      message: `status.set targets task "${op.task}" which is not declared in this stage. Known tasks: ${knownList(taskNames)}`
+    });
+}
+function checkInitialStage(def, stageNames, issues) {
+  stageNames.has(def.initialStage) || issues.push({
+    path: ["initialStage"],
+    message: `initialStage "${def.initialStage}" is not a declared stage. Known stages: ${knownList(stageNames)}`
   });
 }
-function checkTransitionTargets(def, stageIds, issues) {
+function checkTransitionTargets(def, stageNames, issues) {
   for (const [i, stage] of def.stages.entries())
     for (const [k, t] of (stage.transitions ?? []).entries())
-      stageIds.has(t.to) || issues.push({
+      stageNames.has(t.to) || issues.push({
         path: ["stages", i, "transitions", k, "to"],
-        message: `transition target "${t.to}" is not a declared stage. Known stages: ${knownList(stageIds)}`
+        message: `transition target "${t.to}" is not a declared stage. Known stages: ${knownList(stageNames)}`
       });
 }
-function collectPredicateIds(def, issues) {
-  const predicateIds = /* @__PURE__ */ new Set();
-  for (const [i, p] of (def.predicates ?? []).entries())
-    predicateIds.has(p.id) && issues.push({
-      path: ["predicates", i, "id"],
-      message: `duplicate predicate id "${p.id}"`
-    }), predicateIds.add(p.id);
-  return predicateIds;
-}
-function checkFilterRefs(def, predicateIds, issues) {
-  const visit = (g, path) => {
-    g === void 0 || typeof g == "string" || predicateIds.has(g.ref) || issues.push({
-      path: [...path, "ref"],
-      message: `Filter references predicate "${g.ref}" which is not declared. Known predicates: ${knownList(predicateIds) || "(none)"}`
-    });
-  };
+function checkEffectNames(def, issues) {
+  const sites = [];
   for (const [i, stage] of def.stages.entries()) {
-    visit(stage.completion, ["stages", i, "completion"]);
     for (const [j, task] of (stage.tasks ?? []).entries()) {
-      visit(task.filter, ["stages", i, "tasks", j, "filter"]), visit(task.completeWhen, ["stages", i, "tasks", j, "completeWhen"]), visit(task.failWhen, ["stages", i, "tasks", j, "failWhen"]);
+      collectEffects(task.effects, ["stages", i, "tasks", j, "effects"], sites);
       for (const [a, action] of (task.actions ?? []).entries())
-        visit(action.filter, ["stages", i, "tasks", j, "actions", a, "filter"]);
+        collectEffects(action.effects, ["stages", i, "tasks", j, "actions", a, "effects"], sites);
     }
     for (const [k, t] of (stage.transitions ?? []).entries())
-      visit(t.filter, ["stages", i, "transitions", k, "filter"]);
+      collectEffects(t.effects, ["stages", i, "transitions", k, "effects"], sites);
   }
+  checkDuplicates(sites, "effect name (registry key \u2014 unique per definition)", issues);
 }
-function checkWorkflowInvariants(def) {
-  const issues = [], stageIds = checkStagesAndTasks(def, issues);
-  checkInitialStage(def, stageIds, issues), checkTransitionTargets(def, stageIds, issues);
-  const predicateIds = collectPredicateIds(def, issues);
-  return checkFilterRefs(def, predicateIds, issues), issues;
-}
-const TASK_STATUSES = ["pending", "active", "done", "skipped", "failed"], STATE_SCOPES = ["workflow", "stage", "task"], DOCUMENT_VALUE_PERMISSIONS = ["create", "read", "update"], MUTATION_GUARD_ACTIONS = [
-  "create",
-  "update",
-  "delete",
-  "publish",
-  "unpublish"
-], NonEmpty = v.pipe(v.string(), v.minLength(1, "must be a non-empty string")), PositiveInt = v.pipe(v.number(), v.integer(), v.minValue(1));
-function picklist(options) {
-  return v.picklist(
-    options,
-    `Invalid option: expected one of ${options.map((o) => `"${o}"`).join("|")}`
+function collectEffects(effects, path, sites) {
+  for (const [e, effect] of (effects ?? []).entries())
+    sites.push({ name: effect.name, path: [...path, e, "name"] });
+}
+function checkGuardNames(def, issues) {
+  const sites = def.stages.flatMap(
+    (stage, i) => (stage.guards ?? []).map((guard, g) => ({
+      name: guard.name,
+      path: ["stages", i, "guards", g, "name"]
+    }))
+  );
+  checkDuplicates(
+    sites,
+    "guard name (the guard lake _id derives from it \u2014 unique per definition)",
+    issues
   );
 }
-const GdrSchema = v.strictObject({
-  id: v.pipe(
-    v.string(),
-    v.regex(
-      /^(dataset|canvas|media-library|dashboard):/,
-      "must be a GDR URI of form '<scheme>:<...id-parts>' where scheme is one of: dataset, canvas, media-library, dashboard"
-    )
-  ),
-  type: NonEmpty
-}), SourceSchema = v.lazy(
-  () => v.union([
-    v.strictObject({
-      source: v.literal("literal"),
-      value: v.union([v.string(), v.number(), v.boolean(), v.null()])
-    }),
-    v.strictObject({ source: v.literal("param"), paramId: NonEmpty }),
-    v.strictObject({ source: v.literal("actor") }),
-    v.strictObject({ source: v.literal("now") }),
-    v.strictObject({ source: v.literal("self") }),
-    v.strictObject({ source: v.literal("stageId") }),
-    v.strictObject({
-      source: v.literal("stateRead"),
-      scope: picklist(STATE_SCOPES),
-      slotId: NonEmpty,
-      path: v.optional(v.string())
-    }),
-    // effectsContext lookup — reads from `instance.effectsContext[id === ID].value`.
-    // Used by chained effects where one handler's output feeds another's binding.
-    v.strictObject({
-      source: v.literal("effectOutput"),
-      contextId: NonEmpty,
-      path: v.optional(v.string())
-    }),
-    v.strictObject({ source: v.literal("row"), path: v.optional(v.string()) }),
-    v.strictObject({
-      source: v.literal("parentState"),
-      slotId: NonEmpty,
-      path: v.optional(v.string())
-    }),
-    // Compound object source — resolves each field's Source recursively
-    // and packages the result into a JSON object. Lets ops append rich
-    // rows to `checklist` / `notes` / `assignees` slots, e.g.
-    // `{ source: "object", fields: { signer: { source: "actor" },
-    //   at: { source: "now" } } }`.
-    v.strictObject({
-      source: v.literal("object"),
-      fields: v.record(NonEmpty, SourceSchema)
-    })
-  ])
-), ScopeKeySchema = v.strictObject({
-  scope: picklist(STATE_SCOPES),
-  slotId: NonEmpty
-}), OpPredicateSchema = v.lazy(
-  () => v.union([
-    v.strictObject({
-      field: NonEmpty,
-      equals: SourceSchema
-    }),
-    v.strictObject({ all: v.array(OpPredicateSchema) }),
-    v.strictObject({ any: v.array(OpPredicateSchema) })
+function stateScopes(def) {
+  const scopes = [{ entries: def.state, path: ["state"], label: "workflow state" }];
+  for (const [i, stage] of def.stages.entries()) {
+    scopes.push({
+      entries: stage.state,
+      path: ["stages", i, "state"],
+      label: `stage "${stage.name}" state`
+    });
+    for (const [j, task] of (stage.tasks ?? []).entries())
+      scopes.push({
+        entries: task.state,
+        path: ["stages", i, "tasks", j, "state"],
+        label: `task "${task.name}" state`
+      });
+  }
+  return scopes;
+}
+function checkStateEntryNames(def, issues) {
+  for (const { entries, path, label } of stateScopes(def))
+    checkDuplicates(
+      (entries ?? []).map((entry, n) => ({ name: entry.name, path: [...path, n, "name"] })),
+      `state entry name in ${label}`,
+      issues
+    );
+}
+function checkPredicates(def, issues) {
+  const reserved = new Set(RESERVED_CONDITION_VARS), names = Object.keys(def.predicates ?? {});
+  for (const name of names)
+    reserved.has(name) && issues.push({
+      path: ["predicates", name],
+      message: `predicate "${name}" shadows the built-in $${name} \u2014 pick another name`
+    });
+  for (const [name, groq2] of Object.entries(def.predicates ?? {}))
+    checkPredicateBody(name, groq2, names, issues);
+}
+function checkPredicateBody(name, groq2, names, issues) {
+  for (const caller of PREDICATE_CALLER_VARS)
+    referencesVar(groq2, caller) && issues.push({
+      path: ["predicates", name],
+      message: `predicate "${name}" reads $${caller} \u2014 predicates are instance-level (pre-evaluated once, without a caller); compose caller gates at the condition site instead`
+    });
+  for (const other of names)
+    other === name || !referencesVar(groq2, other) || issues.push({
+      path: ["predicates", name],
+      message: `predicate "${name}" references predicate $${other} \u2014 predicates may read built-in vars only (no cross-references; compose at the condition site instead)`
+    });
+}
+function referencesVar(groq2, name) {
+  return GROQ_IDENTIFIER.test(name) ? new RegExp(`\\$${name}\\b`).test(groq2) : !1;
+}
+function checkCanOutsideActionFilters(def, issues) {
+  for (const site of nonActionFilterConditionSites(def))
+    referencesVar(site.groq, "can") && issues.push({
+      path: site.path,
+      message: `${site.label} reads $can \u2014 $can (the caller's grants) is bound only when an action fires, so it may appear in action filters only`
+    });
+}
+function nonActionFilterConditionSites(def) {
+  const sites = [];
+  for (const [i, stage] of def.stages.entries()) {
+    for (const [k, t] of (stage.transitions ?? []).entries())
+      sites.push({
+        groq: t.filter,
+        path: ["stages", i, "transitions", k, "filter"],
+        label: `transition "${t.name}" filter`
+      }), collectBindingSites(
+        t.effects,
+        ["stages", i, "transitions", k, "effects"],
+        `transition "${t.name}"`,
+        sites
+      );
+    for (const [j, task] of (stage.tasks ?? []).entries())
+      collectTaskConditionSites(task, ["stages", i, "tasks", j], sites);
+  }
+  return sites;
+}
+function collectTaskConditionSites(task, path, sites) {
+  for (const field of ["filter", "completeWhen", "failWhen"]) {
+    const groq2 = task[field];
+    groq2 !== void 0 && sites.push({ groq: groq2, path: [...path, field], label: `task "${task.name}".${field}` });
+  }
+  collectBindingSites(task.effects, [...path, "effects"], `task "${task.name}"`, sites);
+  for (const [a, action] of (task.actions ?? []).entries())
+    collectBindingSites(
+      action.effects,
+      [...path, "actions", a, "effects"],
+      `action "${action.name}"`,
+      sites
+    );
+  collectSubworkflowSites(task, path, sites);
+}
+function collectSubworkflowSites(task, path, sites) {
+  const sub = task.subworkflows;
+  if (sub === void 0) return;
+  const subPath = [...path, "subworkflows"];
+  sites.push({
+    groq: sub.forEach,
+    path: [...subPath, "forEach"],
+    label: `task "${task.name}".subworkflows.forEach`
+  });
+  for (const [group, record] of [
+    ["with", sub.with],
+    ["context", sub.context]
   ])
-), OpSchema = v.variant("type", [
-  v.strictObject({
-    type: v.literal("workflow.op.state.set"),
-    target: ScopeKeySchema,
-    value: SourceSchema
-  }),
-  v.strictObject({
-    type: v.literal("workflow.op.state.append"),
-    target: ScopeKeySchema,
-    item: SourceSchema
-  }),
-  v.strictObject({
-    type: v.literal("workflow.op.state.updateWhere"),
-    target: ScopeKeySchema,
-    where: OpPredicateSchema,
-    merge: v.record(NonEmpty, SourceSchema)
-  }),
-  v.strictObject({
-    type: v.literal("workflow.op.state.removeWhere"),
-    target: ScopeKeySchema,
-    where: OpPredicateSchema
-  }),
-  v.strictObject({
-    type: v.literal("workflow.op.status.set"),
-    taskId: NonEmpty,
-    status: picklist(TASK_STATUSES)
-  })
-]), StateSlotSourceSchema = v.union([
-  v.strictObject({ kind: v.literal("init") }),
-  v.strictObject({
-    kind: v.literal("query"),
-    query: NonEmpty,
-    resource: v.optional(v.union([v.literal("workflow"), v.literal("subject"), GdrSchema]))
-  }),
-  v.strictObject({ kind: v.literal("write") }),
-  /**
-   * Pre-populate the slot at resolution time with a constant value.
-   * Useful for stage- or task-scope slots that should start non-empty
-   * (e.g. a default headline, a starting tally).
-   */
-  v.strictObject({ kind: v.literal("literal"), value: v.unknown() }),
-  /**
-   * Pre-populate by reading another already-resolved slot. `scope:
-   * "workflow"` reads from the workflow-scope `state[]` (resolved at
-   * startInstance). `scope: "stage"` reads from an earlier slot in
-   * this same stage entry's `state[]` (sequential resolution).
-   * Optional `path` selects a nested field (e.g. `path: "id"` on a
-   * doc.ref slot).
-   */
-  v.strictObject({
-    kind: v.literal("stateRead"),
-    scope: v.union([v.literal("workflow"), v.literal("stage")]),
-    slotId: NonEmpty,
-    path: v.optional(v.string())
-  })
-]), StateSlotKindSchema = picklist([
-  "workflow.state.doc.ref",
-  "workflow.state.doc.refs",
-  // Release reference. A workflow declares this slot to say "I target a
-  // Content Release"; the runtime fills it with a specific release at
-  // start time, and the engine auto-derives the instance's read
-  // perspective from it.
-  "workflow.state.release.ref",
-  "workflow.state.query",
-  "workflow.state.value.string",
-  "workflow.state.value.url",
-  "workflow.state.value.number",
-  "workflow.state.value.boolean",
-  "workflow.state.value.dateTime",
-  "workflow.state.value.actor",
-  "workflow.state.checklist",
-  "workflow.state.notes",
-  "workflow.state.assignees"
-]), StateSlotSchema = v.strictObject({
-  type: StateSlotKindSchema,
-  id: NonEmpty,
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  source: StateSlotSourceSchema
-}), FilterSchema = v.union([
-  // Inline GROQ — only reserved params allowed at runtime.
-  NonEmpty,
-  // Reference to a named predicate, optionally with named args.
-  v.strictObject({
-    ref: NonEmpty,
-    args: v.optional(v.record(v.string(), v.unknown()))
-  })
-]), PredicateParamSchema = v.strictObject({
-  id: NonEmpty,
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  type: picklist(["string", "number", "boolean", "string[]", "reference"]),
-  enum: v.optional(v.array(v.string()))
-}), PredicateSchema = v.strictObject({
-  type: v.optional(v.literal("workflow.predicate")),
-  id: NonEmpty,
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  groq: NonEmpty,
-  params: v.optional(v.array(PredicateParamSchema))
-}), EffectSchema = v.strictObject({
-  type: v.optional(v.literal("workflow.effect")),
-  id: NonEmpty,
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  // Bindings resolve typed Source values at commit time, producing
-  // concrete JSON in the queued effect's `params`. NO GROQ.
-  bindings: v.optional(v.record(v.string(), SourceSchema)),
-  input: v.optional(v.record(v.string(), v.unknown()))
-}), TerminalTaskStatus = picklist(["done", "skipped", "failed"]), PermissionSchema = picklist(DOCUMENT_VALUE_PERMISSIONS), ActionParamSchema = v.strictObject({
-  type: v.optional(v.literal("workflow.action.param")),
-  id: NonEmpty,
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  paramType: picklist([
-    "string",
-    "number",
-    "boolean",
-    "url",
-    "dateTime",
-    "actor",
-    "doc.ref",
-    "doc.refs",
-    "json"
-  ]),
-  required: v.optional(v.boolean())
-}), ActionSchema = v.strictObject({
-  type: v.optional(v.literal("workflow.action")),
-  id: NonEmpty,
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  filter: v.optional(FilterSchema),
-  /** Caller-supplied params, validated before ops/effects run. */
-  params: v.optional(v.array(ActionParamSchema)),
-  /**
-   * Status the task flips to when this action fires. Omit to leave
-   * the task status unchanged — used by intermediate `claim` /
-   * `assign` / partial-update actions where the task should stay
-   * active so a later action can fire on it. Declared values must
-   * be terminal (`done` / `skipped` / `failed`); the engine never
-   * mid-flip back to `active` outside of the `workflow.op.status.set`
-   * op explicit path.
-   */
-  setStatus: v.optional(TerminalTaskStatus),
-  /**
-   * Inline state-mutation primitives executed during the action commit.
-   * Each op runs against the in-memory mutation (deterministic, no
-   * external I/O). Resolved Sources turn into concrete JSON before the
-   * op applies. Logged on `history[]` as `workflow.history.opApplied`
-   * and surfaced on the `ActionResult.ranOps`.
-   */
-  ops: v.optional(v.array(OpSchema)),
-  effects: v.optional(v.array(EffectSchema)),
-  /**
-   * Role gating — OR-match against `Actor.roles[]`. If omitted, no role
-   * gate. `"*"` in Actor.roles always matches (bench / all-access).
-   */
-  roles: v.optional(v.array(NonEmpty)),
-  /**
-   * When true, the actor must appear in the task's `assignees[]` (as a
-   * user-kind assignee matching by id) for the action to be allowed.
-   */
-  requireAssignment: v.optional(v.boolean()),
-  /**
-   * Which permission on the workflow.instance document the actor must
-   * hold (per supplied `grants`). Defaults to "update". Only checked
-   * when grants are supplied at evaluate/fireAction time.
-   */
-  requiredPermission: v.optional(PermissionSchema)
-}), CompletionPolicySchema = v.union([
-  v.strictObject({ kind: v.literal("all") }),
-  v.strictObject({ kind: v.literal("any") }),
-  v.strictObject({
-    kind: v.literal("count"),
-    n: PositiveInt
-  })
-]), LogicalDefinitionRefSchema = v.strictObject({
-  workflowId: NonEmpty,
-  version: v.optional(v.union([PositiveInt, v.literal("latest")]))
-}), SpawnForEachSchema = v.strictObject({
-  groq: NonEmpty,
-  as: v.strictObject({
-    initialState: v.optional(
-      v.array(
-        v.strictObject({
-          type: StateSlotKindSchema,
-          id: NonEmpty,
-          value: SourceSchema
-        })
-      )
-    ),
-    effectsContext: v.optional(v.record(v.string(), SourceSchema))
-  })
-}), SpawnSchema = v.strictObject({
-  type: v.optional(v.literal("workflow.spawn")),
-  id: v.optional(v.string()),
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  definitionRef: LogicalDefinitionRefSchema,
-  forEach: SpawnForEachSchema,
-  completionPolicy: v.optional(CompletionPolicySchema)
-}), AssigneeSchema = v.variant("kind", [
-  v.strictObject({ kind: v.literal("user"), id: NonEmpty }),
-  v.strictObject({ kind: v.literal("role"), role: NonEmpty })
-]), TaskSchema = v.strictObject({
-  type: v.optional(v.literal("workflow.task")),
-  id: NonEmpty,
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  assignees: v.optional(v.array(AssigneeSchema)),
-  filter: v.optional(FilterSchema),
-  invokeOn: v.optional(picklist(["stageEnter", "manual"])),
-  /**
-   * Auto-completion predicate — same shape as `transition.filter`. When
-   * truthy at activation or on any subsequent cascade, the engine
-   * flips the task to `done` with a `{ kind: "system", id: "engine.completeWhen" }`
-   * actor. A full filter, not just a wall-clock deadline.
-   */
-  completeWhen: v.optional(FilterSchema),
-  /**
-   * Auto-failure predicate — symmetric to `completeWhen`. Same shape,
-   * same evaluation cadence (activation + every cascade), but flips
-   * the task to `failed` (not `done`) with a `{ kind: "system",
-   * id: "engine.failWhen" }` actor. When both `completeWhen` and
-   * `failWhen` resolve truthy on the same evaluation, `failWhen`
-   * wins — failure is the more notable signal and should not be
-   * silently swallowed.
-   */
-  failWhen: v.optional(FilterSchema),
-  effects: v.optional(v.array(EffectSchema)),
-  actions: v.optional(v.array(ActionSchema)),
-  spawns: v.optional(SpawnSchema),
-  contentRefs: v.optional(v.array(v.unknown())),
-  /** Task-scoped state slots. Resolved at task activation time. */
-  state: v.optional(v.array(StateSlotSchema))
-}), TransitionSchema = v.strictObject({
-  type: v.optional(v.literal("workflow.transition")),
-  id: NonEmpty,
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  to: NonEmpty,
-  on: v.optional(v.string()),
-  filter: v.optional(FilterSchema),
-  effects: v.optional(v.array(EffectSchema))
-}), GuardActionSchema = picklist(MUTATION_GUARD_ACTIONS), GuardMatchSchema = v.strictObject({
-  /** Subject `_type`(s); empty matches any type. */
-  types: v.optional(v.array(NonEmpty)),
-  /** Target docs as `Source`s resolved at deploy to bare ids + the resource. */
-  idRefs: v.optional(v.array(SourceSchema)),
-  /** Glob id patterns (bare, resource-local). */
-  idPatterns: v.optional(v.array(NonEmpty)),
-  actions: v.pipe(
-    v.array(GuardActionSchema),
-    v.minLength(1, "a guard must match at least one action")
-  )
-}), GuardSchema = v.strictObject({
-  name: v.optional(v.string()),
-  description: v.optional(v.string()),
-  match: GuardMatchSchema,
-  /**
-   * Lake GROQ predicate. Reads `document.before`/`document.after`, `mutation`,
-   * `guard`, and `identity()`. Bare ids/fields only — no GDRs. Omitted or
-   * empty means UNCONDITIONAL DENY.
-   */
-  predicate: v.optional(v.string()),
-  /**
-   * Projected workflow state the predicate reads as `guard.metadata.*`. Values
-   * are `Source`s resolved at deploy and re-synced by the engine. Copied data,
-   * never a cross-resource pointer.
-   */
-  metadata: v.optional(v.record(NonEmpty, SourceSchema))
-}), StageKindSchema = picklist(["initial", "intermediate", "terminal", "waiting"]), StageSchema = v.strictObject({
-  type: v.optional(v.literal("workflow.stage")),
-  id: NonEmpty,
-  title: v.optional(v.string()),
-  description: v.optional(v.string()),
-  kind: v.optional(StageKindSchema),
-  tasks: v.optional(v.array(TaskSchema)),
-  transitions: v.optional(v.array(TransitionSchema)),
-  completion: v.optional(FilterSchema),
-  onEnter: v.optional(v.array(EffectSchema)),
-  onExit: v.optional(v.array(EffectSchema)),
-  /**
-   * Lake mutation guards active while this stage holds. Each compiles to a
-   * `temp.system.guard` doc deployed on stage entry and retracted on exit.
-   * Plural because one stage's intent may span resources (one guard each).
-   */
-  guards: v.optional(v.array(GuardSchema)),
-  contentRefs: v.optional(v.array(v.unknown())),
-  /** Stage-scoped state slots. Resolved at stage entry and persisted on
-   *  the StageEntry. */
-  state: v.optional(v.array(StateSlotSchema))
-}), WorkflowDefinitionSchema = v.strictObject({
-  workflowId: NonEmpty,
-  version: PositiveInt,
-  title: NonEmpty,
-  description: v.optional(v.string()),
-  initialStageId: NonEmpty,
-  /**
-   * Workflow-level state slots. Persist for the instance lifetime.
-   * Every stage's filters/ops can read them via
-   * `*[_id == $self][0].state[key == "<key>"][0].value`. Init-sourced
-   * slots are supplied at `startInstance` via `initialState`.
-   */
-  state: v.optional(v.array(StateSlotSchema)),
-  stages: v.pipe(v.array(StageSchema), v.minLength(1, "must declare at least one stage")),
-  predicates: v.optional(v.array(PredicateSchema))
-});
-function formatValidationError(label, issues) {
-  const lines = issues.map((issue) => `  - ${issue.path.length === 0 ? "(root)" : formatPath(issue.path)}: ${issue.message}`);
-  return `${label} failed validation (${issues.length} issue${issues.length === 1 ? "" : "s"}):
-${lines.join(`
-`)}`;
-}
-function issuesFromValibot(issues) {
-  return issues.map((issue) => ({
-    path: issue.path ? issue.path.map((item) => item.key) : [],
-    message: issue.message
-  }));
-}
-function formatPath(path) {
-  let out = "";
-  for (const seg of path)
-    typeof seg == "number" ? out += `[${seg}]` : out += out.length === 0 ? String(seg) : `.${String(seg)}`;
-  return out;
+    for (const [key, groq2] of Object.entries(record ?? {}))
+      sites.push({
+        groq: groq2,
+        path: [...subPath, group, key],
+        label: `task "${task.name}".subworkflows.${group} "${key}"`
+      });
+}
+function collectBindingSites(effects, path, label, sites) {
+  for (const [e, effect] of (effects ?? []).entries())
+    for (const [key, groq2] of Object.entries(effect.bindings ?? {}))
+      sites.push({
+        groq: groq2,
+        path: [...path, e, "bindings", key],
+        label: `${label} effect "${effect.name}" binding "${key}"`
+      });
+}
+function checkAssigneesEntries(def, issues) {
+  for (const { entries, path } of stateScopes(def))
+    (entries ?? []).filter((e) => e.type === "assignees").length <= 1 || issues.push({
+      path,
+      message: "at most one assignees-kind state entry per scope \u2014 the inbox reads it by kind"
+    });
+}
+function checkWorkflowInvariants(def) {
+  const issues = [], stageNames = checkStages(def, issues);
+  return checkInitialStage(def, stageNames, issues), checkTransitionTargets(def, stageNames, issues), checkEffectNames(def, issues), checkGuardNames(def, issues), checkStateEntryNames(def, issues), checkPredicates(def, issues), checkCanOutsideActionFilters(def, issues), checkAssigneesEntries(def, issues), issues;
 }
 function defineWorkflow(definition) {
-  const workflowId = definition.workflowId, label = typeof workflowId == "string" ? `defineWorkflow("${workflowId}")` : "defineWorkflow", parsed = parseOrThrow(WorkflowDefinitionSchema, definition, label), issues = checkWorkflowInvariants(parsed);
+  const label = labelFor("defineWorkflow", definition), parsed = parseOrThrow(AuthoringWorkflowSchema, definition, label), { definition: stored, issues: desugarIssues } = desugarWorkflow(parsed), issues = [...desugarIssues, ...checkWorkflowInvariants(stored)];
   if (issues.length > 0) throw new Error(formatValidationError(label, issues));
-  return parsed;
+  return stored;
 }
 function defineStage(stage) {
-  return parseOrThrow(StageSchema, stage, labelFor("defineStage", stage, "id"));
+  return parseOrThrow(AuthoringStageSchema, stage, labelFor("defineStage", stage));
 }
 function defineTask(task) {
-  return parseOrThrow(TaskSchema, task, labelFor("defineTask", task, "id"));
+  return parseOrThrow(AuthoringTaskSchema, task, labelFor("defineTask", task));
 }
 function defineAction(action) {
-  return parseOrThrow(ActionSchema, action, labelFor("defineAction", action, "id"));
+  return parseOrThrow(AuthoringActionSchema, action, labelFor("defineAction", action));
 }
 function defineTransition(transition) {
-  return parseOrThrow(
-    TransitionSchema,
-    transition,
-    typeof transition.id == "string" ? `defineTransition("${transition.id}")` : typeof transition.to == "string" ? `defineTransition(\u2192 "${transition.to}")` : "defineTransition"
-  );
+  return parseOrThrow(AuthoringTransitionSchema, transition, transitionLabel(transition));
 }
-function defineFilter(filter) {
-  return parseOrThrow(FilterSchema, filter, "defineFilter");
+function defineState(entry) {
+  return parseOrThrow(AuthoringStateEntrySchema, entry, labelFor("defineState", entry));
 }
-function defineAssignee(assignee) {
-  return parseOrThrow(AssigneeSchema, assignee, "defineAssignee");
+function defineOp(op) {
+  return parseOrThrow(AuthoringOpSchema, op, "defineOp");
 }
-function definePredicate(predicate) {
-  return parseOrThrow(PredicateSchema, predicate, labelFor("definePredicate", predicate, "id"));
+function defineGuard(guard) {
+  return parseOrThrow(GuardSchema, guard, labelFor("defineGuard", guard));
 }
 function defineEffect(effect) {
-  return parseOrThrow(EffectSchema, effect, labelFor("defineEffect", effect, "id"));
+  return parseOrThrow(EffectSchema, effect, labelFor("defineEffect", effect));
+}
+function transitionLabel(transition) {
+  const { name, to } = transition;
+  return typeof name == "string" ? `defineTransition("${name}")` : typeof to == "string" ? `defineTransition(\u2192 "${to}")` : "defineTransition";
 }
 function defineEffectDescriptor(descriptor) {
   if (!descriptor.name) throw new Error("EffectDescriptor missing name");
@@ -512,23 +518,24 @@ function parseOrThrow(schema, input, label) {
     throw new Error(formatValidationError(label, issuesFromValibot(result.issues)));
   return result.output;
 }
-function labelFor(fn, value, key) {
-  if (value && typeof value == "object" && key in value) {
-    const raw = value[key];
+function labelFor(fn, value) {
+  if (value && typeof value == "object" && "name" in value) {
+    const raw = value.name;
     if (typeof raw == "string") return `${fn}("${raw}")`;
   }
   return fn;
 }
 export {
   defineAction,
-  defineAssignee,
   defineEffect,
   defineEffectDescriptor,
-  defineFilter,
-  definePredicate,
+  defineGuard,
+  defineOp,
   defineStage,
+  defineState,
   defineTask,
   defineTransition,
-  defineWorkflow
+  defineWorkflow,
+  groq
 };
 //# sourceMappingURL=define.js.map