@sanity/workflow-engine 0.15.0 → 0.17.0

package/dist/_chunks-es/invariants.js

@@ -4,6 +4,26 @@ import { conditionOutcome, runGroq as runGroq$1, evaluateConditionOutcome as eva
 
 import { parse } from "groq-js";
 
+function isCascadeFired(action) {
+    return action.when !== void 0;
+}
+
+function deriveActivityKind(activity) {
+    if (activity.target !== void 0) return "manual";
+    const actions = activity.actions ?? [];
+    return actions.some(a => !isCascadeFired(a)) ? "user" : actions.some(a => (a.effects ?? []).length > 0 || a.spawn !== void 0) ? "service" : actions.length > 0 ? "receive" : "script";
+}
+
+function deriveExecutorClassification(activity) {
+    if (activity.target !== void 0) return "off-system";
+    const actions = activity.actions ?? [], cascadeFired = actions.filter(isCascadeFired).length;
+    return cascadeFired === actions.length ? "autonomous" : cascadeFired === 0 ? "interactive" : "hybrid";
+}
+
+function driverKind(actor) {
+    return actor.kind === "person" || actor.kind === "agent" ? actor.kind : "service";
+}
+
 function errorMessage(err) {
     return (err instanceof Error ? err.message : String(err)).replace(/[^\P{Cc}\n\t]/gu, "");
 }
@@ -279,17 +299,17 @@ function effectNotFoundMessage(args) {
     return args.settled.status === "cancelled" ? `${base} — it was cancelled at ${args.settled.ranAt}${cause}` : `${base} — it already settled "${args.settled.status}" at ${args.settled.ranAt}${cause}`;
 }
 
-const TAG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const LAKE_ID_SEGMENT_RE = /^[a-z0-9][a-z0-9-]*$/, LAKE_ID_SEGMENT_GLOSS = "ASCII lowercase + digits + dashes, no leading dash, no dots";
 
 function validateTag(tag) {
-    if (!TAG_RE.test(tag)) throw new ContractViolationError(`tag: invalid tag "${tag}" — must match ${TAG_RE.source} (ASCII lowercase + digits + dashes, no leading dash, no dots)`);
+    if (!LAKE_ID_SEGMENT_RE.test(tag)) throw new ContractViolationError(`tag: invalid tag "${tag}" — must match ${LAKE_ID_SEGMENT_RE.source} (${LAKE_ID_SEGMENT_GLOSS})`);
 }
 
 function tagScopeFilter() {
     return "tag == $tag";
 }
 
-const NonEmptyString = v.pipe(v.string(), v.nonEmpty("must not be empty"));
+const NonEmptyString$1 = v.pipe(v.string(), v.nonEmpty("must not be empty"));
 
 function asPredicate(validate) {
     return value => {
@@ -303,21 +323,21 @@ function asPredicate(validate) {
 
 const isValidTag = asPredicate(validateTag), isValidAliasName = asPredicate(validateResourceAliasName), isValidDatasetId = asPredicate(datasetResourceParts), WorkflowResourceSchema = v.variant("type", [ v.object({
     type: v.literal("dataset"),
-    id: v.pipe(NonEmptyString, v.check(isValidDatasetId, 'invalid dataset resource id — expected "<projectId>.<dataset>"'))
+    id: v.pipe(NonEmptyString$1, v.check(isValidDatasetId, 'invalid dataset resource id — expected "<projectId>.<dataset>"'))
 }), v.object({
     type: v.literal("canvas"),
-    id: NonEmptyString
+    id: NonEmptyString$1
 }), v.object({
     type: v.literal("media-library"),
-    id: NonEmptyString
+    id: NonEmptyString$1
 }), v.object({
     type: v.literal("dashboard"),
-    id: NonEmptyString
+    id: NonEmptyString$1
 }) ]), ResourceBindingSchema = v.object({
-    name: v.pipe(NonEmptyString, v.check(isValidAliasName, "invalid resource handle name — lowercase letters, digits and dashes only, no leading dash")),
+    name: v.pipe(NonEmptyString$1, v.check(isValidAliasName, "invalid resource handle name — lowercase letters, digits and dashes only, no leading dash")),
     resource: WorkflowResourceSchema
 }), DefinitionSchema = v.custom(input => typeof input == "object" && input !== null && typeof input.name == "string", "expected a workflow definition (an object with a string `name`)"), DeploymentSchema = v.object({
-    name: NonEmptyString,
+    name: NonEmptyString$1,
     tag: v.pipe(v.string(), v.nonEmpty(), v.check(isValidTag, "invalid tag — lowercase letters, digits and dashes only, no leading dash, no dots")),
     workflowResource: WorkflowResourceSchema,
     resourceAliases: v.optional(v.pipe(v.array(ResourceBindingSchema), v.check(bindings => new Set(bindings.map(binding => binding.name)).size === bindings.length, "duplicate resource handle name — each binding name must be unique within a deployment"))),
@@ -381,6 +401,599 @@ function actorFulfillsRole({actorRoles: actorRoles, required: required, aliases:
     return actorRoles.some(role => accepted.has(role));
 }
 
+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} — interpolate JSON-representable values only`);
+    return serialized;
+}
+
+function desugarWorkflow(authoring) {
+    const issues = [];
+    checkReservedRoleAliasKeys(authoring.roleAliases, issues);
+    const roleAliases = normalizeRoleAliases(authoring.roleAliases), ctx = {
+        issues: issues,
+        claimFields: /* @__PURE__ */ new Map,
+        claimedFields: /* @__PURE__ */ new Set,
+        roleAliases: roleAliases
+    }, workflowFields2 = desugarFieldEntries({
+        entries: authoring.fields,
+        path: [ "fields" ],
+        ctx: ctx
+    }), workflowLayer = layerOf(workflowFields2), stages = authoring.stages.map((stage, i) => {
+        const path = [ "stages", i ], stageFields2 = desugarFieldEntries({
+            entries: stage.fields,
+            path: [ ...path, "fields" ],
+            ctx: ctx
+        }), stageEnv = {
+            layers: [ {
+                scope: "stage",
+                entries: layerOf(stageFields2)
+            }, {
+                scope: "workflow",
+                entries: workflowLayer
+            } ]
+        }, activities = (stage.activities ?? []).map((activity, j) => desugarActivity({
+            activity: activity,
+            path: [ ...path, "activities", j ],
+            stageEnv: stageEnv,
+            ctx: ctx
+        })), transitions = (stage.transitions ?? []).map(transition => desugarTransition({
+            transition: transition
+        })), editable = desugarStageEditable({
+            overrides: stage.editable,
+            inScope: editableFieldNames({
+                workflowFields: workflowFields2,
+                stageFields: stageFields2,
+                activities: activities
+            }),
+            path: [ ...path, "editable" ],
+            ctx: ctx
+        });
+        return {
+            ...stripUndefined({
+                name: stage.name,
+                title: stage.title,
+                description: stage.description,
+                groups: stage.groups,
+                guards: stage.guards?.map(desugarGuard)
+            }),
+            ...stageFields2 ? {
+                fields: stageFields2
+            } : {},
+            ...activities.length > 0 ? {
+                activities: activities
+            } : {},
+            ...transitions.length > 0 ? {
+                transitions: transitions
+            } : {},
+            ...editable ? {
+                editable: editable
+            } : {}
+        };
+    });
+    return checkUnclaimedClaimFields(ctx), {
+        definition: {
+            ...stripUndefined({
+                name: authoring.name,
+                title: authoring.title,
+                description: authoring.description,
+                groups: authoring.groups,
+                lifecycle: authoring.lifecycle,
+                start: desugarStart(authoring.start),
+                initialStage: authoring.initialStage,
+                predicates: authoring.predicates,
+                roleAliases: roleAliases
+            }),
+            ...workflowFields2 ? {
+                fields: workflowFields2
+            } : {},
+            stages: stages
+        },
+        issues: ctx.issues
+    };
+}
+
+function desugarStart(start) {
+    if (start !== void 0) return {
+        kind: start.kind ?? "interactive",
+        ...start.filter !== void 0 ? {
+            filter: start.filter
+        } : {},
+        ...start.allowed !== void 0 ? {
+            allowed: start.allowed
+        } : {}
+    };
+}
+
+function checkReservedRoleAliasKeys(aliases, issues) {
+    for (const key of Object.keys(aliases ?? {})) key.startsWith("$") && issues.push({
+        path: [ "roleAliases", key ],
+        message: `role alias key "${key}" uses the reserved "$" prefix — that namespace is the engine's stored spelling for the universal fulfiller. Use "*" to mean "fulfills any gate", or rename the role.`
+    });
+}
+
+const TODOLIST_OF = [ {
+    type: "string",
+    name: "label",
+    title: "Label"
+}, {
+    type: "string",
+    name: "status",
+    title: "Status"
+}, {
+    type: "assignee",
+    name: "assignee",
+    title: "Assignee"
+}, {
+    type: "date",
+    name: "dueDate",
+    title: "Due date"
+} ], NOTES_OF = [ {
+    type: "text",
+    name: "body",
+    title: "Body"
+}, {
+    type: "actor",
+    name: "actor",
+    title: "Actor"
+}, {
+    type: "datetime",
+    name: "at",
+    title: "At"
+} ];
+
+function desugarFieldEntries({entries: entries, path: path, ctx: ctx}) {
+    return !entries || entries.length === 0 ? entries === void 0 ? void 0 : [] : entries.map((entry, i) => desugarFieldEntry({
+        entry: entry,
+        path: [ ...path, i ],
+        ctx: ctx
+    }));
+}
+
+function desugarFieldEntry({entry: entry, path: path, ctx: ctx}) {
+    if (entry.type === "claim") return desugarClaimField({
+        entry: entry,
+        path: path,
+        ctx: ctx
+    });
+    if (entry.type === "todoList" || entry.type === "notes") return desugarListField({
+        entry: entry,
+        path: path,
+        ctx: ctx
+    });
+    const editable = normalizeEditable({
+        editable: entry.editable,
+        path: [ ...path, "editable" ],
+        ctx: ctx
+    });
+    return {
+        ...stripUndefined({
+            type: entry.type,
+            name: entry.name,
+            title: entry.title,
+            description: entry.description,
+            group: normalizeGroup(entry.group),
+            required: entry.required,
+            initialValue: entry.initialValue,
+            editable: editable,
+            types: entry.types,
+            fields: entry.fields,
+            of: entry.of
+        })
+    };
+}
+
+function desugarClaimField({entry: entry, path: path, ctx: ctx}) {
+    const desugared = {
+        ...stripUndefined({
+            name: entry.name,
+            title: entry.title,
+            description: entry.description,
+            group: normalizeGroup(entry.group)
+        }),
+        type: "actor"
+    };
+    return ctx.claimFields.set(desugared, {
+        name: entry.name,
+        path: path
+    }), desugared;
+}
+
+function desugarListField({entry: entry, path: path, ctx: ctx}) {
+    const editable = normalizeEditable({
+        editable: entry.editable,
+        path: [ ...path, "editable" ],
+        ctx: ctx
+    });
+    return {
+        ...stripUndefined({
+            name: entry.name,
+            title: entry.title,
+            description: entry.description,
+            group: normalizeGroup(entry.group),
+            required: entry.required,
+            initialValue: entry.initialValue,
+            editable: editable
+        }),
+        type: "array",
+        of: entry.type === "todoList" ? TODOLIST_OF : NOTES_OF
+    };
+}
+
+function normalizeEditable({editable: editable, path: path, ctx: ctx}) {
+    if (editable === void 0 || editable === !0) return editable;
+    if (Array.isArray(editable)) {
+        const condition = rolesCondition(editable, ctx.roleAliases);
+        if (condition === void 0) {
+            ctx.issues.push({
+                path: path,
+                message: "editable: [] names no roles — use `true` to open the field to anyone in its scope, or list at least one role"
+            });
+            return;
+        }
+        return condition;
+    }
+    return editable;
+}
+
+function editableFieldNames({workflowFields: workflowFields2, stageFields: stageFields2, activities: activities}) {
+    const names = /* @__PURE__ */ new Set, collect = entries => {
+        for (const entry of entries ?? []) entry.editable !== void 0 && names.add(entry.name);
+    };
+    collect(workflowFields2), collect(stageFields2);
+    for (const activity of activities) collect(activity.fields);
+    return names;
+}
+
+function desugarStageEditable({overrides: overrides, inScope: inScope, path: path, ctx: ctx}) {
+    if (overrides === void 0) return;
+    const out = {};
+    for (const [name, value] of Object.entries(overrides)) {
+        if (!inScope.has(name)) {
+            ctx.issues.push({
+                path: [ ...path, name ],
+                message: `stage editable override "${name}" does not narrow an editable field in scope — name a workflow/stage/activity field of this stage that declares \`editable\``
+            });
+            continue;
+        }
+        const normalized = normalizeEditable({
+            editable: value,
+            path: [ ...path, name ],
+            ctx: ctx
+        });
+        normalized !== void 0 && (out[name] = normalized);
+    }
+    return Object.keys(out).length > 0 ? out : void 0;
+}
+
+function layerOf(entries) {
+    return new Map((entries ?? []).map(entry => [ entry.name, entry ]));
+}
+
+function normalizeGroup(group) {
+    return group === void 0 || Array.isArray(group) ? group : [ group ];
+}
+
+function desugarActivity({activity: activity, path: path, stageEnv: stageEnv, ctx: ctx}) {
+    const activityFields2 = desugarFieldEntries({
+        entries: activity.fields,
+        path: [ ...path, "fields" ],
+        ctx: ctx
+    }), env = {
+        layers: [ {
+            scope: "activity",
+            entries: layerOf(activityFields2)
+        }, ...stageEnv.layers ]
+    }, actions = (activity.actions ?? []).map((action, a) => desugarAction({
+        action: action,
+        path: [ ...path, "actions", a ],
+        env: env,
+        activityName: activity.name,
+        ctx: ctx
+    })), target = desugarTarget({
+        target: activity.target,
+        env: env,
+        path: [ ...path, "target" ],
+        ctx: ctx
+    });
+    return {
+        ...stripUndefined({
+            name: activity.name,
+            title: activity.title,
+            description: activity.description,
+            groups: activity.groups,
+            group: normalizeGroup(activity.group),
+            filter: activity.filter,
+            requirements: activity.requirements
+        }),
+        ...target ? {
+            target: target
+        } : {},
+        ...activityFields2 ? {
+            fields: activityFields2
+        } : {},
+        ...actions.length > 0 ? {
+            actions: actions
+        } : {}
+    };
+}
+
+const TARGET_DOC_KINDS = [ "doc.ref", "doc.refs", "release.ref" ];
+
+function desugarTarget({target: target, env: env, path: path, ctx: ctx}) {
+    if (target === void 0 || target.type === "url") return target;
+    const ref = typeof target.field == "string" ? {
+        field: target.field
+    } : target.field, field = resolveRef({
+        ref: ref,
+        env: env,
+        path: [ ...path, "field" ],
+        ctx: ctx
+    }) ?? fallbackRef(ref), entry = entryAt(env, field);
+    return entry && !TARGET_DOC_KINDS.includes(entry.type) && ctx.issues.push({
+        path: [ ...path, "field" ],
+        message: `manual activity target references "${field.field}" of kind "${entry.type}" — a deep-link target needs a document-valued entry (${TARGET_DOC_KINDS.join(", ")})`
+    }), {
+        type: "field",
+        field: field
+    };
+}
+
+function desugarAction({action: action, path: path, env: env, activityName: activityName, ctx: ctx}) {
+    if ("type" in action) return desugarClaimAction({
+        action: action,
+        path: path,
+        env: env,
+        ctx: ctx
+    });
+    action.roles !== void 0 && action.roles.length === 0 && ctx.issues.push({
+        path: [ ...path, "roles" ],
+        message: "roles: [] names no roles — omit it to allow any identity, or list at least one role"
+    });
+    const cascadeFired = isCascadeFired(action), filter = cascadeFired ? action.filter : andConditions([ rolesCondition(action.roles, ctx.roleAliases), action.filter ]), ops = desugarOps({
+        ops: action.ops,
+        path: [ ...path, "ops" ],
+        env: env,
+        firingActivity: activityName,
+        ctx: ctx
+    }) ?? [];
+    return action.status !== void 0 && ops.push({
+        type: "status.set",
+        activity: activityName,
+        status: action.status
+    }), {
+        ...stripUndefined({
+            name: action.name,
+            title: action.title,
+            description: action.description,
+            group: normalizeGroup(action.group),
+            when: action.when,
+            params: action.params,
+            effects: action.effects,
+            spawn: action.spawn
+        }),
+        ...cascadeFired && action.roles !== void 0 && action.roles.length > 0 ? {
+            roles: action.roles
+        } : {},
+        ...filter ? {
+            filter: filter
+        } : {},
+        ...ops.length > 0 ? {
+            ops: ops
+        } : {}
+    };
+}
+
+function desugarClaimAction({action: action, path: path, env: env, ctx: ctx}) {
+    const ref = typeof action.field == "string" ? {
+        field: action.field
+    } : action.field, resolved = resolveRef({
+        ref: ref,
+        env: env,
+        path: [ ...path, "field" ],
+        ctx: ctx
+    });
+    if (resolved) {
+        const entry = entryAt(env, resolved);
+        entry && entry.type !== "actor" && ctx.issues.push({
+            path: [ ...path, "field" ],
+            message: `claim action "${action.name}" references "${resolved.field}" of kind "${entry.type}" — a claim pair needs an actor-valued entry (a "claim" or "actor" field declaration)`
+        }), checkShadowedClaimTarget({
+            actionName: action.name,
+            field: ref.field,
+            resolved: resolved,
+            env: env,
+            path: [ ...path, "field" ],
+            ctx: ctx
+        }), entry && ctx.claimedFields.add(entry);
+    }
+    const noSteal = `!defined($fields.${ref.field})`, filter = andConditions([ noSteal, rolesCondition(action.roles, ctx.roleAliases), action.filter ]), ops = resolved ? [ {
+        type: "field.set",
+        target: resolved,
+        value: {
+            type: "actor"
+        }
+    } ] : [];
+    return {
+        ...stripUndefined({
+            name: action.name,
+            title: action.title,
+            description: action.description,
+            group: normalizeGroup(action.group),
+            params: action.params,
+            effects: action.effects
+        }),
+        filter: filter,
+        ...ops.length > 0 ? {
+            ops: ops
+        } : {}
+    };
+}
+
+function checkShadowedClaimTarget({actionName: actionName, field: field, resolved: resolved, env: env, path: path, ctx: ctx}) {
+    const nearest = env.layers.find(l => l.entries.has(field));
+    nearest === void 0 || nearest.scope === resolved.scope || ctx.issues.push({
+        path: path,
+        message: `claim action "${actionName}" targets "${field}" at scope "${resolved.scope}", but a nearer ${nearest.scope}-scope entry of the same name shadows it in $fields — 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 checkUnclaimedClaimFields(ctx) {
+    for (const [entry, {name: name, path: path}] of ctx.claimFields) ctx.claimedFields.has(entry) || ctx.issues.push({
+        path: path,
+        message: `claim field "${name}" is never referenced by a claim action — you announced the pattern and wrote half of it. Declare a defineAction({ type: "claim", field: "${name}" }) or use a raw actor entry`
+    });
+}
+
+const DEFAULT_TRANSITION_WHEN = "$allActivitiesDone";
+
+function desugarTransition({transition: transition}) {
+    return {
+        ...stripUndefined({
+            name: transition.name,
+            title: transition.title,
+            description: transition.description,
+            to: transition.to
+        }),
+        when: transition.when ?? DEFAULT_TRANSITION_WHEN
+    };
+}
+
+function desugarGuard(guard) {
+    const {match: match, metadata: metadata, ...rest} = guard, {idRefs: idRefs, ...matchRest} = match;
+    return {
+        ...rest,
+        match: {
+            ...matchRest,
+            ...idRefs !== void 0 ? {
+                idRefs: idRefs.map(printGuardRead)
+            } : {}
+        },
+        ...metadata !== void 0 ? {
+            metadata: Object.fromEntries(Object.entries(metadata).map(([key, read]) => [ key, printGuardRead(read) ]))
+        } : {}
+    };
+}
+
+function desugarOps({ops: ops, path: path, env: env, firingActivity: firingActivity, ctx: ctx}) {
+    if (ops) return ops.map((op, i) => desugarOp({
+        op: op,
+        path: [ ...path, i ],
+        env: env,
+        firingActivity: firingActivity,
+        ctx: ctx
+    }));
+}
+
+function desugarOp({op: op, path: path, env: env, firingActivity: firingActivity, ctx: ctx}) {
+    if (op.type === "status.set") return {
+        type: "status.set",
+        activity: op.activity ?? firingActivity,
+        status: op.status
+    };
+    if (op.type === "audit") return desugarAuditOp({
+        op: op,
+        path: path,
+        env: env,
+        ctx: ctx
+    });
+    const target = resolveRef({
+        ref: op.target,
+        env: env,
+        path: [ ...path, "target" ],
+        ctx: ctx
+    }) ?? fallbackRef(op.target);
+    return {
+        ...op,
+        target: target
+    };
+}
+
+const AUDIT_STAMPS = {
+    actor: {
+        type: "actor"
+    },
+    at: {
+        type: "now"
+    }
+};
+
+function desugarAuditOp({op: op, path: path, env: env, ctx: ctx}) {
+    const target = resolveRef({
+        ref: op.target,
+        env: env,
+        path: [ ...path, "target" ],
+        ctx: 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: "field.append",
+        target: 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 — rename yours or remap the stamp via stampFields`
+            });
+            continue;
+        }
+        fields[stamp] = source;
+    }
+    return {
+        type: "field.append",
+        target: target,
+        value: {
+            type: "object",
+            fields: fields
+        }
+    };
+}
+
+function resolveRef({ref: ref, env: env, path: path, ctx: 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.field)) return {
+        scope: layer.scope,
+        field: ref.field
+    };
+    const reachable = env.layers.flatMap(l => [ ...l.entries.keys() ].map(n => `${l.scope}:${n}`));
+    ctx.issues.push({
+        path: path,
+        message: `field reference "${ref.field}"${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.field);
+}
+
+function fallbackRef(ref) {
+    return {
+        scope: ref.scope ?? "workflow",
+        field: ref.field
+    };
+}
+
+function rolesCondition(roles, aliases) {
+    if (!(!roles || roles.length === 0)) return groq`count($actor.roles[@ in ${expandRequiredRoles(roles, aliases)}]) > 0`;
+}
+
+function stripUndefined(obj) {
+    const out = {};
+    for (const [k, value] of Object.entries(obj)) value !== void 0 && (out[k] = value);
+    return out;
+}
+
 function isUnevaluable(result) {
     return result == null;
 }
@@ -400,9 +1013,9 @@ async function evaluateCondition(args) {
 
 async function evaluatePredicates(args) {
     const out = {};
-    for (const [name, groq] of Object.entries(args.predicates ?? {})) {
+    for (const [name, groq2] of Object.entries(args.predicates ?? {})) {
         const result = await runGroq({
-            groq: groq,
+            groq: groq2,
             params: args.params,
             snapshot: args.snapshot
         }), outcome = conditionOutcome(result);
@@ -411,46 +1024,77 @@ async function evaluatePredicates(args) {
     return out;
 }
 
-async function runGroq({groq: groq, params: params, snapshot: snapshot}) {
+async function runGroq({groq: groq2, params: params, snapshot: snapshot}) {
     return runGroq$1({
-        groq: groq,
+        groq: groq2,
         params: params,
         dataset: snapshot.docs
     });
 }
 
-function conditionSyntaxIssues(groq, boundVars) {
+function conditionSyntaxIssues(groq2, boundVars) {
     const issues = [];
     let tree;
     try {
-        tree = parse(groq);
+        tree = parse(groq2);
     } catch (err) {
         issues.push(errorMessage(err));
     }
-    if (/\*\s*\[\s*_type\b/.test(groq) && issues.push('condition scans by `_type` — that\'s a discovery query, not a predicate. Conditions evaluate against the in-memory snapshot (instance + ancestors + field-declared docs). To bring extra docs in scope, declare a `doc.ref` (or `doc.refs`) field entry on the workflow or this stage. For lake scans like "all articles in this release", use `subworkflows.forEach` instead.'), 
-    boundVars !== void 0 && tree !== void 0) for (const name of conditionParameterNames(groq)) boundVars.includes(name) || issues.push(`reads $${name}, which this scope does not bind — an unbound variable evaluates to GROQ null, so the condition silently never matches. Bound here: ` + boundVars.map(n => `$${n}`).join(", "));
+    if (/\*\s*\[\s*_type\b/.test(groq2) && issues.push("condition scans by `_type` — that's a discovery query, not a predicate. Conditions evaluate against the in-memory snapshot (instance + ancestors + field-declared docs). To bring extra docs in scope, declare a `doc.ref` (or `doc.refs`) field entry on the workflow or this stage. For lake scans like \"all articles in this release\", use a spawn action's `forEach` instead."), 
+    boundVars !== void 0 && tree !== void 0) for (const name of conditionParameterNames(groq2)) boundVars.includes(name) || issues.push(`reads $${name}, which this scope does not bind — an unbound variable evaluates to GROQ null, so the condition silently never matches. Bound here: ` + boundVars.map(n => `$${n}`).join(", "));
     return issues;
 }
 
-function conditionParameterNames(groq) {
+function conditionParameterNames(groq2) {
     const read = /* @__PURE__ */ new Set;
-    return walkAstNodes(tryParseGroq(groq), node => {
+    return walkAstNodes(tryParseGroq(groq2), node => {
         node.type === "Parameter" && typeof node.name == "string" && read.add(node.name);
     }), read;
 }
 
-function conditionFieldReadNames(groq) {
-    const read = /* @__PURE__ */ new Set;
-    return walkAstNodes(tryParseGroq(groq), node => {
-        if (node.type !== "AccessAttribute" || typeof node.name != "string") return;
-        const base = node.base;
-        base?.type === "Parameter" && base.name === "fields" && read.add(node.name);
-    }), read;
+function conditionFieldReadNames(groq2) {
+    return new Set(conditionFieldReads(groq2).map(read => read.name));
 }
 
-function conditionEffectReads(groq) {
+function conditionFieldReads(groq2) {
+    const reads = /* @__PURE__ */ new Map;
+    return collectFieldReads(tryParseGroq(groq2), reads), [ ...reads.values() ];
+}
+
+function collectFieldReads(node, reads) {
+    if (Array.isArray(node)) {
+        for (const item of node) collectFieldReads(item, reads);
+        return;
+    }
+    if (typeof node != "object" || node === null) return;
+    const chain = fieldsAttributeChain(node);
+    if (chain !== void 0) {
+        const [name, ...tail] = chain, path = tail.length > 0 ? tail.join(".") : void 0;
+        reads.set(`${name}.${path ?? ""}`, {
+            name: name,
+            path: path
+        });
+        return;
+    }
+    for (const value of Object.values(node)) collectFieldReads(value, reads);
+}
+
+function fieldsAttributeChain(node) {
+    const names = [];
+    let current = node;
+    for (;typeof current == "object" && current !== null; ) {
+        const typed = current;
+        if (typed.type !== "AccessAttribute" || typeof typed.name != "string") return;
+        names.unshift(typed.name);
+        const base = typed.base;
+        if (base?.type === "Parameter" && base.name === "fields") return names;
+        current = base;
+    }
+}
+
+function conditionEffectReads(groq2) {
     const reads = [];
-    return walkAstNodes(tryParseGroq(groq), node => {
+    return walkAstNodes(tryParseGroq(groq2), node => {
         if (node.type !== "AccessAttribute" || typeof node.name != "string") return;
         const base = node.base;
         base?.type !== "AccessAttribute" || typeof base.name != "string" || base.base?.type === "Parameter" && base.base.name === "effects" && reads.push({
@@ -460,9 +1104,34 @@ function conditionEffectReads(groq) {
     }), reads;
 }
 
-function tryParseGroq(groq) {
+function readsRootDocument(groq2) {
+    return nodeReadsRoot(tryParseGroq(groq2), 0);
+}
+
+const SCOPED_CHILD = {
+    Filter: "expr",
+    Projection: "expr",
+    Map: "expr",
+    FlatMap: "expr",
+    PipeFuncCall: "args"
+};
+
+function nodeReadsRoot(node, depth) {
+    if (Array.isArray(node)) return node.some(item => nodeReadsRoot(item, depth));
+    if (typeof node != "object" || node === null) return !1;
+    const typed = node;
+    if (depth === 0 && typed.type === "This" || depth === 0 && typed.type === "AccessAttribute" && typed.base === void 0) return !0;
+    if (typed.type === "Parent") {
+        const climb = typeof typed.n == "number" ? typed.n : 1;
+        return depth - climb <= 0;
+    }
+    const scopedChild = typeof typed.type == "string" ? SCOPED_CHILD[typed.type] : void 0;
+    return scopedChild !== void 0 ? Object.entries(node).some(([key, value]) => nodeReadsRoot(value, key === scopedChild ? depth + 1 : depth)) : Object.values(node).some(value => nodeReadsRoot(value, depth));
+}
+
+function tryParseGroq(groq2) {
     try {
-        return parse(groq);
+        return parse(groq2);
     } catch {
         return;
     }
@@ -479,7 +1148,13 @@ function walkAstNodes(node, visit) {
     }
 }
 
-const CONDITION_VARS = [ {
+const ACTIVITY_STATUSES = [ "active", "done", "skipped", "failed" ], TERMINAL_ACTIVITY_STATUSES = [ "done", "skipped", "failed" ];
+
+function isTerminalActivityStatus(status) {
+    return TERMINAL_ACTIVITY_STATUSES.includes(status);
+}
+
+const FIELD_SCOPES = [ "workflow", "stage", "activity" ], DOCUMENT_VALUE_PERMISSIONS = [ "create", "read", "update" ], MUTATION_GUARD_ACTIONS = [ "create", "update", "delete", "publish", "unpublish" ], ACTIVITY_KINDS = [ "user", "service", "script", "manual", "receive" ], EXECUTOR_CLASSIFICATIONS = [ "autonomous", "interactive", "off-system", "hybrid" ], GROUP_KINDS = [ "core", "details" ], DRIVER_KINDS = [ "person", "agent", "service", "engine" ], CONDITION_VARS = [ {
     name: "self",
     binding: "always",
     label: "this workflow instance",
@@ -488,7 +1163,7 @@ const CONDITION_VARS = [ {
     name: "fields",
     binding: "always",
     label: "the workflow's fields",
-    description: "Declared field entries rendered by name (`$fields.<name>` is the value, no envelope). Stage/activity scopes overlay lexically; `doc.ref` values render the hydrated document when the snapshot holds it."
+    description: "Declared field entries rendered by name (`$fields.<name>` is the value, no wrapper). Stage/activity scopes overlay lexically. What a read puts in your hand follows the declared kind: a singular `doc.ref` DEREFERENCES into the hydrated document (lake `_id`/`_type` plus content fields — which may themselves be named `id`/`type`), while `doc.refs` elements and `release.ref` stay REFERENCES — `{id, type[, releaseName]}` with `id` a GDR URI — because identity reads (membership, counting, joins) must stay total without hydrating every target, and targets may live in resources the evaluation cannot fetch from. Conditions evaluate against the in-memory snapshot only, so a dereferencing plural kind would silently hole wherever hydration lagged."
 }, {
     name: "parent",
     binding: "always",
@@ -509,11 +1184,16 @@ const CONDITION_VARS = [ {
     binding: "always",
     label: "the current time",
     description: "The ISO clock reading shared by every condition in one evaluation pass, so they agree on the time."
+}, {
+    name: "context",
+    binding: "always",
+    label: "start-time context",
+    description: "The instance's `context` bag: values seeded at `startInstance` plus a parent's `spawn.context` handoff, by entry name. Written only at start — never mutated afterwards."
 }, {
     name: "effects",
     binding: "always",
     label: "automation outputs",
-    description: "The `effectsContext` map: stable handler params seeded at start plus completed effects' outputs namespaced by effect name (`$effects['<effect>'].<output>`). Handler fuel — transition filters should read instance/lake state (or $effectStatus) instead."
+    description: "Completed effects' outputs, namespaced by effect name (`$effects['<effect>'].<output>`) — each effect's latest completed run wins. Handler fuel — transition triggers should read instance/lake state (or $effectStatus) instead."
 }, {
     name: "effectStatus",
     binding: "always",
@@ -548,29 +1228,169 @@ const CONDITION_VARS = [ {
     name: "can",
     binding: "caller",
     label: "your permissions",
-    description: "Advisory per-permission booleans computed from the caller's grants; `undefined` without grants. Bound wherever grants ride the evaluation: the projection's rendered scope (action filters, activity requirements, editability predicates) and the fireAction/editField commit gates. Deploy rejects it at every site that evaluates without grants: transition filters, activity `filter`/`completeWhen`/`failWhen`, effect bindings, where-op `where`s, and the subworkflow `forEach`/`with`/`context` sites."
+    description: "Advisory per-permission booleans computed from the caller's grants; `undefined` without grants. Bound wherever grants ride the evaluation: the projection's rendered scope (fireAction-action filters, activity requirements, editability predicates) and the fireAction/editField commit gates. Deploy rejects it at every site that evaluates without grants: transition `when`s, activity filters, cascade-fired actions' `when`/`filter`, effect bindings, where-op `where`s, and the spawn `forEach`/`with`/`context` sites."
 }, {
     name: "row",
     binding: "spawn",
     label: "the spawned row",
-    description: "One `subworkflows.forEach` result row, bound while its `with` map evaluates — and the row under test while a where-op `where` evaluates (per row)."
+    description: "One `spawn.forEach` result row, bound while its `with` map evaluates — and the row under test while a where-op `where` evaluates (per row). Deploy rejects a read at every other site (including `spawn.forEach` itself and `spawn.context`), where it is GROQ null."
 }, {
     name: "params",
     binding: "caller",
     label: "the action's arguments",
-    description: "The firing action's args — they hold values only while that action's effect bindings and where-op `where`s evaluate (activity/transition boundaries bind `{}`; subworkflow sites don't bind it at all). Deploy rejects a read in the cascade gates and in the caller-bound projection (action filters, requirements, editable predicates): args exist only once the caller fires the action, after those sites have evaluated."
+    description: "The firing action's args — they hold values only while a fireAction-fired action's effect bindings and where-op `where`s evaluate (spawn sites don't bind it at all, and a cascade-fired action has no caller to supply args). Deploy rejects a read in the cascade gates, in a cascade-fired action's payload, and in the caller-bound projection (action filters, requirements, editable predicates): args exist only once the caller fires the action, after those sites have evaluated."
 }, {
     name: "subworkflows",
     binding: "always",
     label: "the spawned subworkflows",
-    description: "Every row of the instance's subworkflow registry, faceted by `activity`/`definition`/`rowKey`/`status` (`'active'|'done'|'aborted'`) with `current` marking the open stage entry's cohort and `stage` the child's current stage. Usable anywhere — transition filters, requirements, any stage's gates; the implicit spawn gate is `count($subworkflows[activity == <name> && current && status == 'active']) == 0`."
-} ], RESERVED_CONDITION_VARS = CONDITION_VARS.map(v2 => v2.name), FILTER_SCOPE_VARS = CONDITION_VARS.filter(v2 => v2.binding === "always").map(v2 => v2.name), CALLER_BOUND_VARS = CONDITION_VARS.filter(v2 => v2.binding === "caller").map(v2 => v2.name), GUARD_PREDICATE_VARS = [ {
+    description: "Every row of the instance's subworkflow registry, faceted by `activity`/`action`/`definition`/`rowKey`/`status` (`'active'|'done'|'aborted'`) with `current` marking the open stage entry's cohort and `stage` the child's current stage. Usable anywhere — transition `when`s, requirements, any stage's gates; the settled gate is `count($subworkflows[activity == <name> && current && status == 'active']) == 0`."
+} ], RESERVED_CONDITION_VARS = CONDITION_VARS.map(v2 => v2.name), FILTER_SCOPE_VARS = CONDITION_VARS.filter(v2 => v2.binding === "always").map(v2 => v2.name), CALLER_BOUND_VARS = CONDITION_VARS.filter(v2 => v2.binding === "caller").map(v2 => v2.name), START_FILTER_VARS = [ {
+    name: "tag",
+    description: "The engine's tag partition — scope `*[...]` instance scans with `tag == $tag`."
+}, {
+    name: "definition",
+    description: "The `name` of the definition under evaluation (its own start block binds it)."
+}, {
+    name: "now",
+    description: "The ISO clock reading of the evaluating engine."
+} ], START_ALLOWED_VARS = [ ...START_FILTER_VARS, {
+    name: "fields",
+    description: "The caller's input entries by name (`initialFields` — at `startInstance`, the values the start would seed; at a pre-flight, the values gathered so far, so a read of a not-yet-supplied entry is GROQ null). Document references bind as GDR envelopes — `$fields.<entry>.id` is the GDR URI, never a string authors assemble — a singular `doc.ref` included (nothing hydrates at the gate or the pre-flight). Pathed reads are deploy-checked against these envelope shapes."
+} ], GUARD_PREDICATE_VARS = [ {
     name: "guard",
     description: "The guard document itself (its `metadata` carries deploy-time resolved values)."
 }, {
     name: "mutation",
     description: "The attempted mutation — `mutation.action` is the write kind being gated."
-} ], ACTOR_KINDS = [ "person", "agent", "system" ];
+} ], NonEmptyString = v.pipe(v.string(), v.minLength(1, "must be a non-empty string"));
+
+function isParseableInstant(value) {
+    return typeof value == "string" && !Number.isNaN(Date.parse(value));
+}
+
+const IsoTimestamp = v.pipe(v.string(), v.check(s => isParseableInstant(s), "must be an ISO-8601 datetime string"));
+
+function tolerantObject() {
+    return (entries, ..._exact) => v.looseObject(entries);
+}
+
+function tolerantEntries() {
+    return (entries, ..._exact) => entries;
+}
+
+function schemaTreeShape(schema) {
+    return walkSchemaShape(schema, /* @__PURE__ */ new Set);
+}
+
+function walkSchemaShape(node, path) {
+    if (typeof node != "object" || node === null) return "unknown";
+    if (path.has(node)) return "(circular)";
+    path.add(node);
+    try {
+        const schema = node;
+        return containerShape(schema, path) ?? leafShape(schema);
+    } finally {
+        path.delete(node);
+    }
+}
+
+const objectWalker = (schema, path) => objectEntriesShape(schema.entries, path), unionWalker = (schema, path) => ({
+    union: schema.options.map(option => walkSchemaShape(option, path))
+}), unwrapWalker = (schema, path) => walkSchemaShape(schema.wrapped, path), CONTAINER_WALKERS = {
+    strict_object: objectWalker,
+    loose_object: objectWalker,
+    object: objectWalker,
+    array: (schema, path) => ({
+        array: walkSchemaShape(schema.item, path)
+    }),
+    record: (schema, path) => ({
+        record: walkSchemaShape(schema.value, path)
+    }),
+    union: unionWalker,
+    variant: unionWalker,
+    lazy: (schema, path) => walkSchemaShape(schema.getter(void 0), path),
+    exact_optional: unwrapWalker,
+    optional: unwrapWalker,
+    nullable: unwrapWalker
+};
+
+function containerShape(schema, path) {
+    return CONTAINER_WALKERS[String(schema.type)]?.(schema, path);
+}
+
+function objectEntriesShape(entries, path) {
+    const out = {};
+    for (const [key, entry] of Object.entries(entries)) {
+        const optional = isOptionalEntry(entry), wrapped = optional ? entry.wrapped : entry;
+        out[optional ? `${key}?` : key] = walkSchemaShape(wrapped, path);
+    }
+    return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a < b ? -1 : 1));
+}
+
+function isOptionalEntry(entry) {
+    if (typeof entry != "object" || entry === null) return !1;
+    const kind = entry.type;
+    return kind === "exact_optional" || kind === "optional";
+}
+
+const LEAF_KINDS = /* @__PURE__ */ new Set([ "string", "number", "boolean", "null", "undefined", "unknown", "any" ]);
+
+function leafShape(schema) {
+    if (schema.type === "picklist") return schema.options.join(" | ");
+    if (schema.type === "literal") return `literal ${String(schema.literal)}`;
+    if (schema.type === "custom") return typeof schema.message == "string" ? `custom(${schema.message})` : "custom";
+    if (!LEAF_KINDS.has(String(schema.type))) throw new Error(`schemaTreeShape: unhandled schema kind "${String(schema.type)}" — extend the walker before regenerating the model ledger`);
+    return String(schema.type);
+}
+
+function formatValidationError(label, issues) {
+    const lines = issues.map(issue => `  - ${issue.path.length === 0 ? "(root)" : formatIssuePath(issue.path)}: ${issue.message}`);
+    return `${label} failed validation (${issues.length} issue${issues.length === 1 ? "" : "s"}):\n${lines.join(`\n`)}`;
+}
+
+function issuesFromValibot(issues) {
+    return issues.map(issue => ({
+        path: issue.path ? issue.path.map(item => item.key) : [],
+        message: issue.message
+    }));
+}
+
+function formatIssuePath(path) {
+    let out = "";
+    for (const seg of path) typeof seg == "number" ? out += `[${seg}]` : out += out.length === 0 ? String(seg) : `.${String(seg)}`;
+    return out;
+}
+
+class PersistedDocShapeError extends WorkflowError {
+    documentId;
+    documentType;
+    issues;
+    constructor(args) {
+        super("persisted-doc-shape", formatValidationError(`Persisted ${args.documentType} document "${args.documentId}"`, args.issues)), 
+        this.name = "PersistedDocShapeError", this.documentId = args.documentId, this.documentType = args.documentType, 
+        this.issues = args.issues;
+    }
+}
+
+function parsePersistedDoc(args) {
+    const result = v.safeParse(args.schema, args.doc);
+    if (!result.success) throw new PersistedDocShapeError({
+        documentId: documentIdOf(args.doc),
+        documentType: args.docType,
+        issues: issuesFromValibot(result.issues)
+    });
+    return result.output;
+}
+
+function documentIdOf(doc) {
+    if (typeof doc == "object" && doc !== null) {
+        const id = doc._id;
+        if (typeof id == "string") return id;
+    }
+    return "(unknown id)";
+}
+
+const ACTOR_KINDS = [ "person", "agent", "system" ];
 
 function releaseDocId(releaseName) {
     return `_.releases.${releaseName}`;
@@ -617,29 +1437,28 @@ class FieldValueShapeError extends WorkflowError {
     }
 }
 
-const GdrShape = v.looseObject({
-    id: v.pipe(v.string(), v.check(s => isGdrUri(s), "must be a GDR URI")),
-    type: v.pipe(v.string(), v.minLength(1))
-}), ReleaseRefShape = v.pipe(v.looseObject({
-    id: v.pipe(v.string(), v.check(s => isGdrUri(s), "must be a GDR URI")),
+const GdrUriSchema = v.custom(s => typeof s == "string" && isGdrUri(s), "must be a GDR URI"), GdrShape = tolerantObject()({
+    id: GdrUriSchema,
+    type: NonEmptyString
+}), ReleaseRefShape = v.pipe(tolerantObject()({
+    id: GdrUriSchema,
     type: v.literal("system.release"),
-    releaseName: v.pipe(v.string(), v.minLength(1))
-}), v.check(ref => !isGdrUri(ref.id) || extractDocumentId(ref.id) === releaseDocId(ref.releaseName), "id must point at the `_.releases.<releaseName>` doc named by releaseName")), ActorShape = v.looseObject({
+    releaseName: NonEmptyString
+}), v.check(ref => !isGdrUri(ref.id) || extractDocumentId(ref.id) === releaseDocId(ref.releaseName), "id must point at the `_.releases.<releaseName>` doc named by releaseName")), ActorShape = tolerantObject()({
     kind: v.picklist(ACTOR_KINDS),
-    id: v.pipe(v.string(), v.minLength(1)),
-    roles: v.optional(v.array(v.string())),
-    onBehalfOf: v.optional(v.string())
-}), AssigneeShape = v.union([ v.looseObject({
+    id: NonEmptyString,
+    roles: v.exactOptional(v.array(v.string())),
+    onBehalfOf: v.exactOptional(v.string())
+}), AssigneeShape = v.union([ tolerantObject()({
     type: v.literal("user"),
-    id: v.pipe(v.string(), v.minLength(1))
-}), v.looseObject({
+    id: NonEmptyString
+}), tolerantObject()({
     type: v.literal("role"),
-    role: v.pipe(v.string(), v.minLength(1))
-}) ]), NullableString = v.union([ v.null(), v.string() ]), NullableNumber = v.union([ v.null(), v.number() ]), NullableBoolean = v.union([ v.null(), v.boolean() ]), NullableDateTime = v.union([ v.null(), v.pipe(v.string(), v.check(s => !Number.isNaN(Date.parse(s)), "must be an ISO-8601 datetime string")) ]), NullableDate = v.union([ v.null(), v.pipe(v.string(), v.regex(/^\d{4}-\d{2}-\d{2}$/, "must be a `YYYY-MM-DD` date")) ]), NullableUrl = NullableString, valueSchemas = {
+    role: NonEmptyString
+}) ]), NullableString = v.union([ v.null(), v.string() ]), NullableNumber = v.union([ v.null(), v.number() ]), NullableBoolean = v.union([ v.null(), v.boolean() ]), NullableDateTime = v.union([ v.null(), IsoTimestamp ]), NullableDate = v.union([ v.null(), v.pipe(v.string(), v.regex(/^\d{4}-\d{2}-\d{2}$/, "must be a `YYYY-MM-DD` date")) ]), NullableUrl = NullableString, fieldValueSchemas = {
     "doc.ref": v.union([ v.null(), GdrShape ]),
     "doc.refs": v.array(GdrShape),
     "release.ref": v.union([ v.null(), ReleaseRefShape ]),
-    query: v.any(),
     string: NullableString,
     text: NullableString,
     number: NullableNumber,
@@ -650,6 +1469,9 @@ const GdrShape = v.looseObject({
     actor: v.union([ v.null(), ActorShape ]),
     assignee: v.union([ v.null(), AssigneeShape ]),
     assignees: v.array(AssigneeShape)
+}, valueSchemas = {
+    ...fieldValueSchemas,
+    query: v.any()
 };
 
 function shapeValueSchema(shape, leaf) {
@@ -736,7 +1558,7 @@ function isBareSeedId(id) {
 
 const AuthoringRefId = v.pipe(v.string(), v.check(isAuthoringRefId, "must be a bare document id, a GDR URI, or a portable `@<alias>:<id>` reference")), AuthoringGdrShape = v.looseObject({
     id: AuthoringRefId,
-    type: v.pipe(v.string(), v.minLength(1))
+    type: NonEmptyString
 }), seedValueSchemas = {
     ...valueSchemas,
     "doc.ref": v.union([ v.null(), AuthoringGdrShape ]),
@@ -744,7 +1566,7 @@ const AuthoringRefId = v.pipe(v.string(), v.check(isAuthoringRefId, "must be a b
     "release.ref": v.union([ v.null(), v.looseObject({
         id: AuthoringRefId,
         type: v.literal("system.release"),
-        releaseName: v.pipe(v.string(), v.minLength(1))
+        releaseName: NonEmptyString
     }) ])
 };
 
@@ -787,13 +1609,7 @@ function formatIssues(issues) {
     });
 }
 
-const ACTIVITY_STATUSES = [ "pending", "active", "done", "skipped", "failed" ], TERMINAL_ACTIVITY_STATUSES = [ "done", "skipped", "failed" ];
-
-function isTerminalActivityStatus(status) {
-    return TERMINAL_ACTIVITY_STATUSES.includes(status);
-}
-
-const FIELD_SCOPES = [ "workflow", "stage", "activity" ], DOCUMENT_VALUE_PERMISSIONS = [ "create", "read", "update" ], MUTATION_GUARD_ACTIONS = [ "create", "update", "delete", "publish", "unpublish" ], ACTIVITY_KINDS = [ "user", "service", "script", "manual", "receive" ], GROUP_KINDS = [ "core", "details" ], DRIVER_KINDS = [ "person", "agent", "service", "engine" ], NonEmpty = v.pipe(v.string(), v.minLength(1, "must be a non-empty string")), PositiveInt = v.pipe(v.number(), v.integer(), v.minValue(1)), GROQ_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const NonEmpty = NonEmptyString, PositiveInt = v.pipe(v.number(), v.integer(), v.minValue(1)), GROQ_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
 function groqIdentifier(referencedAs) {
     return v.pipe(v.string(), v.regex(GROQ_IDENTIFIER, `must be a GROQ-safe identifier (letters, digits, underscore; not starting with a digit) because it is referenced as ${referencedAs} in GROQ conditions`));
@@ -892,7 +1708,7 @@ const StoredFieldOpSchema = v.variant("type", [ ...opSchemas(StoredFieldRefSchem
     type: v.literal("status.set"),
     activity: NonEmpty,
     status: picklist(ACTIVITY_STATUSES)
-}) ]), StoredTransitionOpSchema = StoredFieldOpSchema, AuditOpSchema = v.strictObject({
+}) ]), AuditOpSchema = v.strictObject({
     type: v.literal("audit"),
     target: AuthoringFieldRefSchema,
     value: ValueExprSchema,
@@ -1020,6 +1836,15 @@ const TodoListFieldSchema = pinned()(v.strictObject(listSugarFields("todoList"))
     bindings: v.optional(v.record(v.string(), ConditionSchema)),
     input: v.optional(v.record(v.string(), v.unknown())),
     outputs: v.optional(v.array(FieldShapeSchema))
+}), DefinitionRefSchema = v.strictObject({
+    name: NonEmpty,
+    version: v.optional(v.union([ PositiveInt, v.literal("latest") ]))
+}), SubworkflowsSchema = v.strictObject({
+    forEach: NonEmpty,
+    definition: DefinitionRefSchema,
+    with: v.optional(v.record(NonEmpty, ConditionSchema)),
+    context: v.optional(v.record(NonEmpty, ConditionSchema)),
+    onExit: v.optional(picklist([ "detach", "abort" ]))
 }), ActionParamSchema = v.strictObject({
     type: picklist([ "string", "number", "boolean", "url", "dateTime", "actor", "doc.ref", "doc.refs", "json" ]),
     name: NonEmpty,
@@ -1034,14 +1859,19 @@ function actionFields(op, group) {
         title: v.optional(v.string()),
         description: v.optional(v.string()),
         group: v.optional(group),
+        when: v.optional(ConditionSchema),
         filter: v.optional(ConditionSchema),
         params: v.optional(v.array(ActionParamSchema)),
         ops: v.optional(v.array(op)),
-        effects: v.optional(v.array(EffectSchema))
+        effects: v.optional(v.array(EffectSchema)),
+        spawn: v.optional(SubworkflowsSchema)
     };
 }
 
-const StoredActionSchema = pinned()(v.strictObject(actionFields(StoredOpSchema, StoredGroupMembershipSchema))), TerminalActivityStatus = picklist(TERMINAL_ACTIVITY_STATUSES), RawAuthoringActionSchema = pinned()(v.strictObject({
+const StoredActionSchema = pinned()(v.strictObject({
+    ...actionFields(StoredOpSchema, StoredGroupMembershipSchema),
+    roles: v.optional(v.array(NonEmpty))
+})), TerminalActivityStatus = picklist(TERMINAL_ACTIVITY_STATUSES), RawAuthoringActionSchema = pinned()(v.strictObject({
     ...actionFields(AuthoringOpSchema, AuthoringGroupMembershipSchema),
     roles: v.optional(v.array(NonEmpty)),
     status: v.optional(TerminalActivityStatus)
@@ -1056,35 +1886,19 @@ const StoredActionSchema = pinned()(v.strictObject(actionFields(StoredOpSchema,
     filter: v.optional(ConditionSchema),
     params: v.optional(v.array(ActionParamSchema)),
     effects: v.optional(v.array(EffectSchema))
-})), AuthoringActionSchema = pinned()(v.union([ RawAuthoringActionSchema, ClaimActionSchema ])), DefinitionRefSchema = v.strictObject({
-    name: NonEmpty,
-    version: v.optional(v.union([ PositiveInt, v.literal("latest") ]))
-}), SubworkflowsSchema = v.strictObject({
-    forEach: NonEmpty,
-    definition: DefinitionRefSchema,
-    with: v.optional(v.record(NonEmpty, ConditionSchema)),
-    context: v.optional(v.record(NonEmpty, ConditionSchema)),
-    onExit: v.optional(picklist([ "detach", "abort" ]))
-});
+})), AuthoringActionSchema = pinned()(v.lazy(input => typeof input == "object" && input !== null && "type" in input ? ClaimActionSchema : RawAuthoringActionSchema));
 
-function activityFields({field: field, action: action, op: op, target: target, group: group}) {
+function activityFields({field: field, action: action, target: target, group: group}) {
     return {
         name: NonEmpty,
         title: v.optional(v.string()),
         description: v.optional(v.string()),
         groups: v.optional(v.array(GroupSchema)),
         group: v.optional(group),
-        kind: v.optional(picklist(ACTIVITY_KINDS)),
         target: v.optional(target),
-        activation: v.optional(picklist([ "auto", "manual" ])),
         filter: v.optional(ConditionSchema),
         requirements: v.optional(v.record(NonEmpty, ConditionSchema)),
-        completeWhen: v.optional(ConditionSchema),
-        failWhen: v.optional(ConditionSchema),
-        ops: v.optional(v.array(op)),
-        effects: v.optional(v.array(EffectSchema)),
         actions: v.optional(v.array(action)),
-        subworkflows: v.optional(SubworkflowsSchema),
         fields: v.optional(v.array(field))
     };
 }
@@ -1092,30 +1906,26 @@ function activityFields({field: field, action: action, op: op, target: target, g
 const StoredActivitySchema = pinned()(v.strictObject(activityFields({
     field: FieldEntrySchema,
     action: StoredActionSchema,
-    op: StoredOpSchema,
     target: StoredManualTargetSchema,
     group: StoredGroupMembershipSchema
 }))), AuthoringActivitySchema = pinned()(v.strictObject(activityFields({
     field: AuthoringFieldEntrySchema,
     action: AuthoringActionSchema,
-    op: AuthoringOpSchema,
     target: AuthoringManualTargetSchema,
     group: AuthoringGroupMembershipSchema
 })));
 
-function transitionFields(op, filter) {
+function transitionFields(when) {
     return {
         name: NonEmpty,
         title: v.optional(v.string()),
         description: v.optional(v.string()),
         to: NonEmpty,
-        filter: filter,
-        ops: v.optional(v.array(op)),
-        effects: v.optional(v.array(EffectSchema))
+        when: when
     };
 }
 
-const StoredTransitionSchema = pinned()(v.strictObject(transitionFields(StoredTransitionOpSchema, ConditionSchema))), AuthoringTransitionOpSchema = v.variant("type", [ ...opSchemas(AuthoringFieldRefSchema), AuditOpSchema ]), AuthoringTransitionSchema = pinned()(v.strictObject(transitionFields(AuthoringTransitionOpSchema, v.optional(ConditionSchema)))), GuardActionSchema = picklist(MUTATION_GUARD_ACTIONS), GuardReadPath = v.pipe(NonEmpty, v.check(path => !/[\r\n\u2028\u2029]/.test(path), "a guard read path cannot contain a line break")), GuardReadSchema = v.variant("type", [ v.strictObject({
+const StoredTransitionSchema = pinned()(v.strictObject(transitionFields(ConditionSchema))), AuthoringTransitionSchema = pinned()(v.strictObject(transitionFields(v.optional(ConditionSchema)))), GuardActionSchema = picklist(MUTATION_GUARD_ACTIONS), GuardReadPath = v.pipe(NonEmpty, v.check(path => !/[\r\n\u2028\u2029]/.test(path), "a guard read path cannot contain a line break")), GuardReadSchema = v.variant("type", [ v.strictObject({
     type: v.literal("self")
 }), v.strictObject({
     type: v.literal("now")
@@ -1177,16 +1987,26 @@ const StoredStageSchema = pinned()(v.strictObject(stageFields({
     transition: AuthoringTransitionSchema,
     guard: AuthoringGuardSchema,
     editable: AuthoringEditableSchema
-}))), RoleAliasesSchema = v.record(NonEmpty, v.pipe(v.array(NonEmpty), v.minLength(1, "a role alias must list at least one fulfilling role"))), WORKFLOW_LIFECYCLES = [ "standalone", "child" ];
+}))), RoleAliasesSchema = v.record(NonEmpty, v.pipe(v.array(NonEmpty), v.minLength(1, "a role alias must list at least one fulfilling role"))), WORKFLOW_LIFECYCLES = [ "standalone", "child" ], START_KINDS = [ "interactive", "autonomous" ];
+
+function startFields(kind) {
+    return {
+        kind: kind,
+        filter: v.optional(ConditionSchema),
+        allowed: v.optional(ConditionSchema)
+    };
+}
 
-function workflowFields(field, stage) {
+const StoredStartSchema = pinned()(v.strictObject(startFields(picklist(START_KINDS)))), AuthoringStartSchema = pinned()(v.strictObject(startFields(v.optional(picklist(START_KINDS)))));
+
+function workflowFields({field: field, stage: stage, start: start}) {
     return {
         name: NonEmpty,
         title: NonEmpty,
         description: v.optional(v.string()),
         groups: v.optional(v.array(GroupSchema)),
         lifecycle: v.optional(picklist(WORKFLOW_LIFECYCLES)),
-        applicableWhen: v.optional(ConditionSchema),
+        start: v.optional(start),
         initialStage: NonEmpty,
         fields: v.optional(v.array(field)),
         stages: v.pipe(v.array(stage), v.minLength(1, "must declare at least one stage")),
@@ -1195,7 +2015,11 @@ function workflowFields(field, stage) {
     };
 }
 
-const WorkflowDefinitionSchema = pinned()(v.strictObject(workflowFields(FieldEntrySchema, StoredStageSchema)));
+const WorkflowDefinitionSchema = pinned()(v.strictObject(workflowFields({
+    field: FieldEntrySchema,
+    stage: StoredStageSchema,
+    start: StoredStartSchema
+})));
 
 function parseStoredDefinition(input, label) {
     return parseOrThrow({
@@ -1205,28 +2029,26 @@ function parseStoredDefinition(input, label) {
     });
 }
 
-const AuthoringWorkflowSchema = pinned()(v.strictObject(workflowFields(AuthoringFieldEntrySchema, AuthoringStageSchema))), WORKFLOW_DEFINITION_TYPE = "sanity.workflow.definition";
+const AuthoringWorkflowSchema = pinned()(v.strictObject(workflowFields({
+    field: AuthoringFieldEntrySchema,
+    stage: AuthoringStageSchema,
+    start: AuthoringStartSchema
+}))), WORKFLOW_DEFINITION_TYPE = "sanity.workflow.definition";
 
 function isStartableDefinition(definition) {
     return definition.lifecycle !== "child";
 }
 
-function formatValidationError(label, issues) {
-    const lines = issues.map(issue => `  - ${issue.path.length === 0 ? "(root)" : formatIssuePath(issue.path)}: ${issue.message}`);
-    return `${label} failed validation (${issues.length} issue${issues.length === 1 ? "" : "s"}):\n${lines.join(`\n`)}`;
+function startKindOf(definition) {
+    return definition.start?.kind ?? "interactive";
 }
 
-function issuesFromValibot(issues) {
-    return issues.map(issue => ({
-        path: issue.path ? issue.path.map(item => item.key) : [],
-        message: issue.message
-    }));
+function isSubjectEntry(entry) {
+    return entry.required === !0 && (entry.type === "doc.ref" || entry.type === "doc.refs");
 }
 
-function formatIssuePath(path) {
-    let out = "";
-    for (const seg of path) typeof seg == "number" ? out += `[${seg}]` : out += out.length === 0 ? String(seg) : `.${String(seg)}`;
-    return out;
+function isInputSourced(entry) {
+    return entry.initialValue?.type === "input";
 }
 
 function parseOrThrow({schema: schema, input: input, label: label}) {
@@ -1257,6 +2079,13 @@ function checkDuplicates({names: names, what: what, issues: issues}) {
     return seen;
 }
 
+function checkDefinitionName(def, issues) {
+    LAKE_ID_SEGMENT_RE.test(def.name) || issues.push({
+        path: [ "name" ],
+        message: `definition name "${def.name}" does not match the definition-name grammar ${LAKE_ID_SEGMENT_RE.source} (${LAKE_ID_SEGMENT_GLOSS}) — the name is interpolated into every deployed document id (\`<tag>.<name>.v<version>\`), which the engine keeps to the same segment grammar as the tag`
+    });
+}
+
 function checkStages(def, issues) {
     const stageNames = checkDuplicates({
         names: def.stages.map((stage, i) => ({
@@ -1313,12 +2142,6 @@ function checkActivities({def: def, i: i, activityNames: activityNames, issues:
 }
 
 function checkStatusSetTargets({activity: activity, activityNames: activityNames, path: path, issues: issues}) {
-    checkStatusSetOps({
-        ops: activity.ops,
-        activityNames: activityNames,
-        path: [ ...path, "ops" ],
-        issues: issues
-    });
     for (const [a, action] of (activity.actions ?? []).entries()) checkStatusSetOps({
         ops: action.ops,
         activityNames: activityNames,
@@ -1366,25 +2189,11 @@ function checkStageReachability({def: def, stageNames: stageNames, issues: issue
 
 function effectNameSites(def) {
     const sites = [];
-    for (const [i, stage] of def.stages.entries()) {
-        for (const [j, activity] of (stage.activities ?? []).entries()) {
-            collectEffects({
-                effects: activity.effects,
-                path: [ "stages", i, "activities", j, "effects" ],
-                sites: sites
-            });
-            for (const [a, action] of (activity.actions ?? []).entries()) collectEffects({
-                effects: action.effects,
-                path: [ "stages", i, "activities", j, "actions", a, "effects" ],
-                sites: sites
-            });
-        }
-        for (const [k, t] of (stage.transitions ?? []).entries()) collectEffects({
-            effects: t.effects,
-            path: [ "stages", i, "transitions", k, "effects" ],
-            sites: sites
-        });
-    }
+    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) collectEffects({
+        effects: action.effects,
+        path: [ "stages", i, "activities", j, "actions", a, "effects" ],
+        sites: sites
+    });
     return sites;
 }
 
@@ -1413,6 +2222,10 @@ function checkGuardNames(def, issues) {
         what: "guard name (the guard lake _id derives from it — unique per definition)",
         issues: issues
     });
+    for (const {name: name, path: path} of sites) LAKE_ID_SEGMENT_RE.test(name) || issues.push({
+        path: path,
+        message: `guard name "${name}" does not match the guard-name grammar ${LAKE_ID_SEGMENT_RE.source} (${LAKE_ID_SEGMENT_GLOSS}) — the guard's lake _id derives from it at stage entry, so an invalid name would wedge the entering commit with an opaque lake error instead of failing here`
+    });
 }
 
 function fieldScopes(def) {
@@ -1471,19 +2284,23 @@ function checkPredicates(def, issues) {
         path: [ "predicates", name ],
         message: `predicate "${name}" shadows the built-in $${name} — pick another name`
     });
-    for (const [name, groq] of Object.entries(def.predicates ?? {})) checkPredicateBody({
+    for (const [name, groq2] of Object.entries(def.predicates ?? {})) checkPredicateBody({
         name: name,
-        groq: groq,
+        groq: groq2,
         names: names,
         issues: issues
     });
 }
 
-function checkPredicateBody({name: name, groq: groq, names: names, issues: issues}) {
-    const reads = conditionParameterNames(groq);
+function checkPredicateBody({name: name, groq: groq2, names: names, issues: issues}) {
+    const reads = conditionParameterNames(groq2);
     for (const caller of CALLER_BOUND_VARS) reads.has(caller) && issues.push({
         path: [ "predicates", name ],
-        message: `predicate "${name}" reads $${caller} — predicates are instance-level (pre-evaluated once, without a caller); compose caller gates at the condition site instead`
+        message: `predicate "${name}" reads $${caller} — predicates pre-evaluate caller-free; compose caller gates at the condition site instead`
+    });
+    reads.has("row") && issues.push({
+        path: [ "predicates", name ],
+        message: `predicate "${name}" reads $row — ${ROW_BINDING_CLAUSE}; predicates pre-evaluate once per instance, so the read is GROQ null and the predicate can never hold`
     });
     for (const other of names) other === name || !reads.has(other) || issues.push({
         path: [ "predicates", name ],
@@ -1491,32 +2308,43 @@ function checkPredicateBody({name: name, groq: groq, names: names, issues: issue
     });
 }
 
-function entryNames(entries) {
-    return new Set((entries ?? []).map(entry => entry.name));
+function entryMap(entries) {
+    return new Map((entries ?? []).map(entry => [ entry.name, entry ]));
 }
 
-function checkUnboundCallerVars(def, issues) {
+function checkUnboundConditionVars(def, issues) {
     for (const site of conditionSites(def)) {
         const reads = conditionParameterNames(site.groq);
-        for (const name of unboundCallerVars(site.policy)) reads.has(name) && issues.push({
+        for (const name of unboundVarsAt(site)) reads.has(name) && issues.push({
             path: site.path,
-            message: callerVarMessage(site, name)
+            message: name === "row" ? rowVarMessage(site) : callerVarMessage(site, name)
         });
     }
 }
 
+function unboundVarsAt(site) {
+    const callerVars = unboundCallerVars(site.policy);
+    return site.bindsRow === !0 ? callerVars : [ ...callerVars, "row" ];
+}
+
 function unboundCallerVars(policy) {
-    return policy === "cascade" ? CALLER_BOUND_VARS : policy === "caller-bound" ? [ "params" ] : [ "can" ];
+    return policy === "cascade" ? CALLER_BOUND_VARS : policy === "caller-bound" ? [ "params" ] : policy === "triggered-payload" ? [ "can", "params" ] : [ "can" ];
+}
+
+const ROW_BINDING_CLAUSE = "$row (the discovered row in a spawn projection; the stored row under test in a where-op) is bound only while a spawn `with` projection or a where-op `where` evaluates";
+
+function rowVarMessage(site) {
+    return `${site.label} reads $row — ${ROW_BINDING_CLAUSE}; this site never binds it, so the read is GROQ null and the condition can never resolve. Move the per-row read into \`spawn.with\` or a where-op, or gate on instance state instead`;
 }
 
 function callerVarMessage(site, name) {
-    return site.policy === "cascade" ? `${site.label} reads $${name} — the cascade evaluates transition filters and activity gates (filter/completeWhen/failWhen) with no caller bound ($assigned is constant false, the other caller vars hold no value); gate on instance state (e.g. a field an action wrote) instead` : site.policy === "caller-bound" ? `${site.label} reads $${name} — $params (the firing action's args) is bound only while the action's effect bindings and where-op \`where\`s evaluate; this site never binds it, so the condition could never pass. Bind $params in an effect binding or a where-op instead, or gate on a field an action wrote` : `${site.label} reads $can — $can (the caller's grants) is bound only in the caller-bound projection (action filters, requirements, editable predicates) and never holds a value in cascade conditions; move the check to one of those sites or drop $can`;
+    return site.policy === "cascade" ? `${site.label} reads $${name} — cascade gates (transition \`when\`s, activity \`filter\`s, a cascade-fired action's \`when\`/\`filter\`) must resolve identically no matter whose token drives the cascade ($assigned is constant false, the other caller vars hold no value); gate on instance state (e.g. a field an action wrote), or pin executing identities with \`roles\`` : site.policy === "caller-bound" ? `${site.label} reads $${name} — $params (the firing action's args) is bound only while the action's effect bindings and where-op \`where\`s evaluate; this site never binds it, so the condition could never pass. Bind $params in an effect binding or a where-op instead, or gate on a field an action wrote` : site.policy === "triggered-payload" && name === "params" ? `${site.label} reads $params — a cascade-fired action has no caller to supply args, so $params never holds a value in its payload; read fields or effect outputs instead` : `${site.label} reads $can — $can (the caller's grants) is bound only in the caller-bound projection (action filters, requirements, editable predicates) and never holds a value in cascade conditions; move the check to one of those sites or drop $can`;
 }
 
 function conditionSites(def) {
     const sites = [], workflowLayer = {
         scope: "workflow",
-        names: entryNames(def.fields)
+        entries: entryMap(def.fields)
     };
     collectEditableSites({
         entries: def.fields,
@@ -1537,35 +2365,24 @@ function conditionSites(def) {
 function collectStageConditionSites({stage: stage, i: i, workflowLayer: workflowLayer, sites: sites}) {
     const stageLayer = {
         scope: "stage",
-        names: entryNames(stage.fields)
+        entries: entryMap(stage.fields)
     }, stageFields2 = [ stageLayer, workflowLayer ], editableWindow = [ stageLayer, workflowLayer, ...(stage.activities ?? []).map(activity => ({
         scope: "activity",
-        names: entryNames(activity.fields)
+        entries: entryMap(activity.fields)
     })) ];
     for (const [k, t] of (stage.transitions ?? []).entries()) sites.push({
-        groq: t.filter,
-        path: [ "stages", i, "transitions", k, "filter" ],
-        label: `transition "${t.name}" filter`,
+        groq: t.when,
+        path: [ "stages", i, "transitions", k, "when" ],
+        label: `transition "${t.name}" when`,
         policy: "cascade",
         fields: stageFields2
-    }), collectBindingSites({
-        effects: t.effects,
-        path: [ "stages", i, "transitions", k, "effects" ],
-        label: `transition "${t.name}"`,
-        fields: stageFields2,
-        sites: sites
-    }), collectOpWhereSites({
-        ops: t.ops,
-        path: [ "stages", i, "transitions", k, "ops" ],
-        label: `transition "${t.name}"`,
-        fields: stageFields2,
-        sites: sites
     });
     collectEditableSites({
         entries: stage.fields,
         path: [ "stages", i, "fields" ],
         labelPrefix: `stage "${stage.name}"`,
         fields: editableWindow,
+        unionWindow: !0,
         sites: sites
     });
     for (const [name, editable] of Object.entries(stage.editable ?? {})) typeof editable == "string" && sites.push({
@@ -1573,70 +2390,64 @@ function collectStageConditionSites({stage: stage, i: i, workflowLayer: workflow
         path: [ "stages", i, "editable", name ],
         label: `stage "${stage.name}" editable override "${name}"`,
         policy: "caller-bound",
-        fields: editableWindow
+        fields: editableWindow,
+        unionWindow: !0
     });
     for (const [j, activity] of (stage.activities ?? []).entries()) collectActivityConditionSites({
         activity: activity,
         path: [ "stages", i, "activities", j ],
         stageFields: stageFields2,
+        workflowLayer: workflowLayer,
         sites: sites
     });
 }
 
-function collectEditableSites({entries: entries, path: path, labelPrefix: labelPrefix, fields: fields, sites: sites}) {
+function collectEditableSites({entries: entries, path: path, labelPrefix: labelPrefix, fields: fields, unionWindow: unionWindow, sites: sites}) {
     for (const [n, entry] of (entries ?? []).entries()) typeof entry.editable == "string" && sites.push({
         groq: entry.editable,
         path: [ ...path, n, "editable" ],
         label: `${labelPrefix} field "${entry.name}" editable`,
         policy: "caller-bound",
-        fields: fields
+        fields: fields,
+        ...unionWindow === !0 ? {
+            unionWindow: !0
+        } : {}
     });
 }
 
-function collectOpWhereSites({ops: ops, path: path, label: label, fields: fields, sites: sites}) {
+function collectOpWhereSites({ops: ops, path: path, label: label, policy: policy, fields: fields, sites: sites}) {
     for (const [o, op] of (ops ?? []).entries()) op.where !== void 0 && sites.push({
         groq: op.where,
         path: [ ...path, o, "where" ],
         label: `${label} ${op.type} where`,
+        ...policy !== void 0 ? {
+            policy: policy
+        } : {},
+        bindsRow: !0,
         fields: fields
     });
 }
 
-function collectActivityConditionSites({activity: activity, path: path, stageFields: stageFields2, sites: sites}) {
+function collectActivityConditionSites({activity: activity, path: path, stageFields: stageFields2, workflowLayer: workflowLayer, sites: sites}) {
     const fields = [ {
         scope: "activity",
-        names: entryNames(activity.fields)
+        entries: entryMap(activity.fields)
     }, ...stageFields2 ];
-    for (const gate of [ "filter", "completeWhen", "failWhen" ]) {
-        const groq = activity[gate];
-        groq !== void 0 && sites.push({
-            groq: groq,
-            path: [ ...path, gate ],
-            label: `activity "${activity.name}".${gate}`,
-            policy: "cascade",
-            fields: fields
-        });
-    }
-    for (const [name, groq] of Object.entries(activity.requirements ?? {})) sites.push({
-        groq: groq,
+    activity.filter !== void 0 && sites.push({
+        groq: activity.filter,
+        path: [ ...path, "filter" ],
+        label: `activity "${activity.name}".filter`,
+        policy: "cascade",
+        fields: fields
+    });
+    for (const [name, groq2] of Object.entries(activity.requirements ?? {})) sites.push({
+        groq: groq2,
         path: [ ...path, "requirements", name ],
         label: `activity "${activity.name}" requirement "${name}"`,
         policy: "caller-bound",
         fields: fields
     });
-    collectBindingSites({
-        effects: activity.effects,
-        path: [ ...path, "effects" ],
-        label: `activity "${activity.name}"`,
-        fields: fields,
-        sites: sites
-    }), collectOpWhereSites({
-        ops: activity.ops,
-        path: [ ...path, "ops" ],
-        label: `activity "${activity.name}"`,
-        fields: fields,
-        sites: sites
-    }), collectEditableSites({
+    collectEditableSites({
         entries: activity.fields,
         path: [ ...path, "fields" ],
         labelPrefix: `activity "${activity.name}"`,
@@ -1646,60 +2457,84 @@ function collectActivityConditionSites({activity: activity, path: path, stageFie
         activity: activity,
         path: path,
         fields: fields,
-        sites: sites
-    }), collectSubworkflowSites({
-        activity: activity,
-        path: path,
-        fields: fields,
+        workflowLayer: workflowLayer,
         sites: sites
     });
 }
 
-function collectActionConditionSites({activity: activity, path: path, fields: fields, sites: sites}) {
-    for (const [a, action] of (activity.actions ?? []).entries()) action.filter !== void 0 && sites.push({
-        groq: action.filter,
-        path: [ ...path, "actions", a, "filter" ],
-        label: `action "${action.name}" filter`,
-        policy: "caller-bound",
-        fields: fields
-    }), collectBindingSites({
-        effects: action.effects,
-        path: [ ...path, "actions", a, "effects" ],
-        label: `action "${action.name}"`,
-        fields: fields,
-        sites: sites
-    }), collectOpWhereSites({
-        ops: action.ops,
-        path: [ ...path, "actions", a, "ops" ],
-        label: `action "${action.name}"`,
-        fields: fields,
-        sites: sites
-    });
+function collectActionConditionSites({activity: activity, path: path, fields: fields, workflowLayer: workflowLayer, sites: sites}) {
+    for (const [a, action] of (activity.actions ?? []).entries()) {
+        const actionPath = [ ...path, "actions", a ], cascadeFired = action.when !== void 0;
+        action.when !== void 0 && sites.push({
+            groq: action.when,
+            path: [ ...actionPath, "when" ],
+            label: `action "${action.name}" when`,
+            policy: "cascade",
+            fields: fields
+        }), action.filter !== void 0 && sites.push({
+            groq: action.filter,
+            path: [ ...actionPath, "filter" ],
+            label: `action "${action.name}" filter`,
+            policy: cascadeFired ? "cascade" : "caller-bound",
+            fields: fields
+        });
+        const payloadPolicy = cascadeFired ? "triggered-payload" : void 0;
+        collectBindingSites({
+            effects: action.effects,
+            path: [ ...actionPath, "effects" ],
+            label: `action "${action.name}"`,
+            policy: payloadPolicy,
+            fields: fields,
+            sites: sites
+        }), collectOpWhereSites({
+            ops: action.ops,
+            path: [ ...actionPath, "ops" ],
+            label: `action "${action.name}"`,
+            policy: payloadPolicy,
+            fields: fields,
+            sites: sites
+        }), collectSpawnSites({
+            action: action,
+            path: actionPath,
+            fields: fields,
+            workflowLayer: workflowLayer,
+            sites: sites
+        });
+    }
 }
 
-function collectSubworkflowSites({activity: activity, path: path, fields: fields, sites: sites}) {
-    const sub = activity.subworkflows;
-    if (sub === void 0) return;
-    const subPath = [ ...path, "subworkflows" ];
+function collectSpawnSites({action: action, path: path, fields: fields, workflowLayer: workflowLayer, sites: sites}) {
+    const spawn = action.spawn;
+    if (spawn === void 0) return;
+    const spawnPath = [ ...path, "spawn" ];
     sites.push({
-        groq: sub.forEach,
-        path: [ ...subPath, "forEach" ],
-        label: `activity "${activity.name}".subworkflows.forEach`,
-        fields: fields
-    });
-    for (const [group, record] of [ [ "with", sub.with ], [ "context", sub.context ] ]) for (const [key, groq] of Object.entries(record ?? {})) sites.push({
-        groq: groq,
-        path: [ ...subPath, group, key ],
-        label: `activity "${activity.name}".subworkflows.${group} "${key}"`,
+        groq: spawn.forEach,
+        path: [ ...spawnPath, "forEach" ],
+        label: `action "${action.name}".spawn.forEach`,
+        policy: "cascade",
+        fields: [ workflowLayer ],
+        windowNote: "spawn.forEach evaluates against workflow-scope $fields only — stage/activity fields are never bound at discovery time"
+    });
+    for (const [group, record, bindsRow] of [ [ "with", spawn.with, !0 ], [ "context", spawn.context, !1 ] ]) for (const [key, groq2] of Object.entries(record ?? {})) sites.push({
+        groq: groq2,
+        path: [ ...spawnPath, group, key ],
+        label: `action "${action.name}".spawn.${group} "${key}"`,
+        policy: "triggered-payload",
+        ...bindsRow ? {
+            bindsRow: !0
+        } : {},
         fields: fields
     });
 }
 
-function collectBindingSites({effects: effects, path: path, label: label, fields: fields, sites: sites}) {
-    for (const [e, effect] of (effects ?? []).entries()) for (const [key, groq] of Object.entries(effect.bindings ?? {})) sites.push({
-        groq: groq,
+function collectBindingSites({effects: effects, path: path, label: label, policy: policy, fields: fields, sites: 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}"`,
+        ...policy !== void 0 ? {
+            policy: policy
+        } : {},
         fields: fields
     });
 }
@@ -1711,34 +2546,102 @@ function checkAssigneesEntries(def, issues) {
     });
 }
 
-function activityShape(activity) {
-    return {
-        hasActions: (activity.actions ?? []).length > 0,
-        hasEffects: (activity.effects ?? []).length > 0,
-        hasCompleteWhen: activity.completeWhen !== void 0,
-        hasSubworkflows: activity.subworkflows !== void 0
-    };
+function checkActivityTerminalPaths(def, issues) {
+    for (const [i, stage] of def.stages.entries()) {
+        const resolvable = terminallyResolvableActivities(stage);
+        for (const [j, activity] of (stage.activities ?? []).entries()) resolvable.has(activity.name) || issues.push({
+            path: [ "stages", i, "activities", j ],
+            message: `activity "${activity.name}" has no path to a terminal status — no action in stage "${stage.name}" resolves it (\`status: 'done'\` on one of its actions, a \`{when: <condition>, status: 'done'}\` trigger, or a sibling's \`status.set\`), so it can never finish and the stage's \`$allActivitiesDone\` gate would wedge`
+        });
+    }
 }
 
-const KIND_SHAPE_RULES = {
-    user: s => s.hasActions ? [] : [ "needs at least one action for a person to fire" ],
-    service: s => s.hasEffects ? [] : [ "needs at least one effect — the automated work it performs" ],
-    manual: s => [ s.hasActions || s.hasCompleteWhen ? void 0 : "needs a way to complete — an action to acknowledge it, or a `completeWhen` predicate to verify it (otherwise it auto-resolves on activation)", s.hasSubworkflows ? "is off-system work, not a fan-out — drop `subworkflows` or move it to its own activity" : void 0 ].filter(m => m !== void 0),
-    receive: s => [ s.hasCompleteWhen || s.hasSubworkflows ? void 0 : "needs a `completeWhen` (or `subworkflows`) condition to wait on", s.hasActions ? "has no actor, so it cannot carry actions" : void 0 ].filter(m => m !== void 0),
-    script: s => [ s.hasActions ? "runs inline with no actor, so it cannot carry actions" : void 0, s.hasCompleteWhen ? "resolves on activation, so it cannot carry a `completeWhen` (that is a `receive`/`service` wait)" : void 0, s.hasSubworkflows ? "resolves on activation, so it cannot fan out with `subworkflows`" : void 0 ].filter(m => m !== void 0)
-};
+function terminallyResolvableActivities(stage) {
+    const terminalSets = (stage.activities ?? []).flatMap(activity => activity.actions ?? []).flatMap(action => action.ops ?? []).filter(op => op.type === "status.set").filter(op => TERMINAL_ACTIVITY_STATUSES.includes(op.status));
+    return new Set(terminalSets.map(op => op.activity));
+}
 
-function checkActivityKinds(def, issues) {
-    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) {
-        const path = [ "stages", i, "activities", j ];
-        if (activity.target !== void 0 && activity.kind !== "manual" && issues.push({
-            path: [ ...path, "target" ],
-            message: `activity "${activity.name}" has a \`target\` but is not \`kind: "manual"\` — a target is the deep-link for off-system manual work`
-        }), activity.kind !== void 0) for (const fault of KIND_SHAPE_RULES[activity.kind](activityShape(activity))) issues.push({
-            path: [ ...path, "kind" ],
-            message: `activity "${activity.name}" declares kind "${activity.kind}" but ${fault}`
+function checkTerminalStageActivities(def, issues) {
+    for (const [i, stage] of def.stages.entries()) (stage.transitions ?? []).length > 0 || (stage.activities ?? []).length === 0 || issues.push({
+        path: [ "stages", i, "activities" ],
+        message: `stage "${stage.name}" is terminal (no transitions) but declares activities — entering a terminal stage completes the instance, so they can never run. Move the work to a \`when\` action in the source stage (it commits in the hop that moves here), or give the stage a transition out`
+    });
+}
+
+function storedRolesIssue(action) {
+    if (action.roles !== void 0) {
+        if (action.roles.length === 0) return `action "${action.name}" stores \`roles: []\`, which names no roles — the runtime reads an empty pin as "anyone may execute", the opposite of a pin. Omit \`roles\` to allow any identity, or list at least one role`;
+        if (action.when === void 0) return `action "${action.name}" stores \`roles\` but is fireAction-fired (no \`when\`) — the stored pin is only read on cascade fires. Author \`roles\` normally (it desugars into the action's \`filter\`), or add \`when\` to make it a trigger`;
+    }
+}
+
+function checkStoredRolesPlacement(def, issues) {
+    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) {
+        const message = storedRolesIssue(action);
+        message !== void 0 && issues.push({
+            path: [ "stages", i, "activities", j, "actions", a, "roles" ],
+            message: message
+        });
+    }
+}
+
+function checkTriggeredActionParams(def, issues) {
+    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) action.when === void 0 || (action.params ?? []).length === 0 || issues.push({
+        path: [ "stages", i, "activities", j, "actions", a, "params" ],
+        message: `action "${action.name}" declares params but is cascade-fired (\`when\`) — no caller ever supplies args to a trigger. Drop the params, or drop \`when\` to make it a fireAction-fired action`
+    });
+}
+
+function checkStart(def, issues) {
+    if (def.start !== void 0 && (def.lifecycle === "child" && issues.push({
+        path: [ "start" ],
+        message: "a spawn-only (lifecycle 'child') definition declares `start` — children are instantiated by a parent's `spawn`, never started standalone, so the block would never apply. Remove `start`, or drop `lifecycle: 'child'`"
+    }), checkStartFilterReads(def, issues), checkStartAllowedReads(def, issues), def.start.kind === "autonomous")) for (const [n, entry] of (def.fields ?? []).entries()) entry.required !== !0 || isSubjectEntry(entry) || issues.push({
+        path: [ "fields", n, "required" ],
+        message: `start.kind 'autonomous' means runs are initiated by a system reacting to a document, so every required input must be derivable from that triggering document — required entry "${entry.name}" (kind "${entry.type}") is not a document reference. Make it optional, seed it another way (query/literal), or declare it doc.ref / doc.refs`
+    });
+}
+
+function checkStartFilterReads(def, issues) {
+    const filter = def.start?.filter;
+    filter !== void 0 && (conditionParameterNames(filter).has("fields") && issues.push({
+        path: [ "start", "filter" ],
+        message: "start.filter reads $fields, but the filter is browse-time-pure — a start surface evaluates it per document, before any inputs exist, so $fields cannot be bound. Move the input-dependent rule to start.allowed, the start-time permission predicate that binds $fields and is enforced by startInstance"
+    }), readsRootDocument(filter) && !(def.fields ?? []).some(isSubjectEntry) && issues.push({
+        path: [ "start", "filter" ],
+        message: "start.filter reads the candidate document (its root), but the definition declares no required subject entry (a required doc.ref / doc.refs input) — a read surface would never have a document to bind as root, so every root read is GROQ null and the filter silently misevaluates. Declare a required subject entry, or gate on the dataset instead"
+    }));
+}
+
+function checkStartAllowedReads(def, issues) {
+    const allowed = def.start?.allowed;
+    if (allowed === void 0) return;
+    const bindable = new Map((def.fields ?? []).filter(isInputSourced).map(entry => [ entry.name, entry ])), declared = new Set((def.fields ?? []).map(entry => entry.name)), nullVerdict = `so the read is GROQ null and null semantics decide the verdict (refuse-all or vacuously-allow, by the expression's shape), never the caller's real input. Bindable (input) fields: ${knownList(bindable.keys())}`;
+    for (const read of conditionFieldReads(allowed)) {
+        const entry = bindable.get(read.name);
+        if (entry === void 0) {
+            issues.push({
+                path: [ "start", "allowed" ],
+                message: declared.has(read.name) ? `start.allowed reads $fields.${read.name}, but "${read.name}" is not an \`input\`-sourced entry — $fields binds only the caller's input entries (query/literal/fieldRead entries resolve at materialisation, after the start gate), ${nullVerdict}` : `start.allowed reads $fields.${read.name}, but no workflow-scope field entry named "${read.name}" is declared — $fields binds only the caller's input entries, ${nullVerdict}`
+            });
+            continue;
+        }
+        pushFieldReadPathIssue({
+            where: "start.allowed",
+            read: {
+                field: read.name,
+                path: read.path
+            },
+            target: entry,
+            path: [ "start", "allowed" ],
+            issues: issues,
+            nodes: START_ALLOWED_VALUE_NODES
         });
     }
+    readsRootDocument(allowed) && issues.push({
+        path: [ "start", "allowed" ],
+        message: "start.allowed reads the candidate document as its root, but no root ever binds in the start-allowed context — startInstance holds inputs, not a loaded document, so the read is GROQ null and null semantics decide the verdict, never the workflow's real state. Read the subject as $fields.<entry> (its GDR URI is $fields.<entry>.id); a per-document visibility rule belongs in start.filter"
+    });
 }
 
 function checkGroups(def, issues) {
@@ -1848,39 +2751,80 @@ function checkGroupMembership({group: group, reachable: reachable, path: path, l
 }
 
 function checkConditionFieldReads(def, issues) {
-    const everywhere = allDeclaredFieldNames(def);
-    for (const site of conditionSites(def)) for (const name of conditionFieldReadNames(site.groq)) fieldVisibleAtSite({
+    const everywhere = allDeclaredFieldEntries(def);
+    for (const site of conditionSites(def)) checkSiteFieldReads({
         site: site,
-        name: name,
-        everywhere: everywhere
-    }) || issues.push({
-        path: site.path,
-        message: undeclaredFieldReadMessage(site, name)
+        everywhere: everywhere,
+        issues: issues
     });
-    for (const [name, groq] of Object.entries(def.predicates ?? {})) for (const read of conditionFieldReadNames(groq)) everywhere.has(read) || issues.push({
-        path: [ "predicates", name ],
-        message: noFieldAnywhereMessage(`predicate "${name}"`, read)
+    for (const [name, groq2] of Object.entries(def.predicates ?? {})) checkSiteFieldReads({
+        site: {
+            groq: groq2,
+            path: [ "predicates", name ],
+            label: `predicate "${name}"`,
+            fields: "context-dependent"
+        },
+        everywhere: everywhere,
+        issues: issues
     });
 }
 
-function allDeclaredFieldNames(def) {
-    const names = /* @__PURE__ */ new Set;
-    for (const {entries: entries} of fieldScopes(def)) for (const entry of entries ?? []) names.add(entry.name);
-    return names;
+function checkSiteFieldReads({site: site, everywhere: everywhere, issues: issues}) {
+    for (const read of conditionFieldReads(site.groq)) {
+        const targets = readTargets({
+            site: site,
+            read: read,
+            everywhere: everywhere
+        });
+        if (targets === "undeclared") {
+            issues.push({
+                path: site.path,
+                message: undeclaredFieldReadMessage(site, read.name)
+            });
+            continue;
+        }
+        const path = read.path;
+        path !== void 0 && (targets.some(target => fieldValuePathIssue({
+            target: target,
+            path: path
+        }) === void 0) || pushFieldReadPathIssue({
+            where: site.label,
+            read: {
+                field: read.name,
+                path: path
+            },
+            target: targets[0],
+            path: site.path,
+            issues: issues
+        }));
+    }
+}
+
+function readTargets({site: site, read: read, everywhere: everywhere}) {
+    if (site.fields === "context-dependent") return everywhere.get(read.name) ?? "undeclared";
+    const layers = site.fields.filter(layer => layer.entries.has(read.name));
+    if (layers.length === 0) return "undeclared";
+    const entries = layers.map(layer => layer.entries.get(read.name));
+    return site.unionWindow === !0 ? entries : [ entries[0] ];
 }
 
-function fieldVisibleAtSite({site: site, name: name, everywhere: everywhere}) {
-    return site.fields === "context-dependent" ? everywhere.has(name) : site.fields.some(layer => layer.names.has(name));
+function allDeclaredFieldEntries(def) {
+    const declared = /* @__PURE__ */ new Map;
+    for (const {entries: entries} of fieldScopes(def)) for (const entry of entries ?? []) {
+        const list = declared.get(entry.name);
+        list === void 0 ? declared.set(entry.name, [ entry ]) : list.push(entry);
+    }
+    return declared;
 }
 
 function noFieldAnywhereMessage(label, name) {
-    return `${label} reads $fields.${name}, but no field entry named "${name}" is declared anywhere in the definition — the read evaluates to GROQ null, so the condition silently fails closed`;
+    return `${label} reads $fields.${name}, but no field entry named "${name}" is declared anywhere in the definition — the read evaluates to GROQ null, so the condition silently misevaluates`;
 }
 
 function undeclaredFieldReadMessage(site, name) {
     if (site.fields === "context-dependent") return noFieldAnywhereMessage(site.label, name);
-    const visible = site.fields.flatMap(layer => [ ...layer.names ].map(n => `${layer.scope}:${n}`));
-    return `${site.label} reads $fields.${name}, but no field entry named "${name}" is lexically visible here — the read evaluates to GROQ null, so the condition silently fails closed. Visible: ${visible.join(", ") || "(none)"}`;
+    const visible = site.fields.flatMap(layer => [ ...layer.entries.keys() ].map(n => `${layer.scope}:${n}`)), window = site.windowNote === void 0 ? `no field entry named "${name}" is lexically visible here` : `"${name}" is not in this site's window (${site.windowNote})`;
+    return `${site.label} reads $fields.${name}, but ${window} — the read evaluates to GROQ null, so the condition silently misevaluates. Visible: ${visible.join(", ") || "(none)"}`;
 }
 
 function checkFieldReadSeeds(def, issues) {
@@ -1961,38 +2905,29 @@ function seedEarlierSiblingTarget(args) {
     });
 }
 
+function opSites(def) {
+    const sites = [];
+    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) sites.push({
+        ops: action.ops,
+        path: [ "stages", i, "activities", j, "actions", a, "ops" ],
+        label: `action "${action.name}"`,
+        stage: stage,
+        activity: activity
+    });
+    return sites;
+}
+
 function checkFieldReadOpValues(def, issues) {
     const workflowEntries = def.fields ?? [];
-    for (const [i, stage] of def.stages.entries()) {
-        const shared = {
-            workflowEntries: workflowEntries,
-            stageEntries: stage.fields ?? [],
-            issues: issues
-        };
-        for (const [k, t] of (stage.transitions ?? []).entries()) checkOpsFieldReads({
-            ...shared,
-            ops: t.ops,
-            path: [ "stages", i, "transitions", k, "ops" ],
-            label: `transition "${t.name}"`
-        });
-        for (const [j, activity] of (stage.activities ?? []).entries()) {
-            const activityNames = entryNames(activity.fields), activityPath = [ "stages", i, "activities", j ];
-            checkOpsFieldReads({
-                ...shared,
-                ops: activity.ops,
-                path: [ ...activityPath, "ops" ],
-                label: `activity "${activity.name}"`,
-                activityNames: activityNames
-            });
-            for (const [a, action] of (activity.actions ?? []).entries()) checkOpsFieldReads({
-                ...shared,
-                ops: action.ops,
-                path: [ ...activityPath, "actions", a, "ops" ],
-                label: `action "${action.name}"`,
-                activityNames: activityNames
-            });
-        }
-    }
+    for (const site of opSites(def)) checkOpsFieldReads({
+        workflowEntries: workflowEntries,
+        stageEntries: site.stage.fields ?? [],
+        issues: issues,
+        ops: site.ops,
+        path: site.path,
+        label: site.label,
+        activityEntries: entryMap(site.activity.fields)
+    });
 }
 
 function checkOpsFieldReads({ops: ops, path: path, label: label, ...ctx}) {
@@ -2011,7 +2946,7 @@ function fieldReadsIn(value, path) {
     } ] : value.type !== "object" ? [] : Object.entries(value.fields).flatMap(([key, sub]) => fieldReadsIn(sub, [ ...path, "fields", key ]));
 }
 
-function checkOpFieldRead({read: read, where: where, path: path, workflowEntries: workflowEntries, stageEntries: stageEntries, activityNames: activityNames, issues: issues}) {
+function checkOpFieldRead({read: read, where: where, path: path, workflowEntries: workflowEntries, stageEntries: stageEntries, activityEntries: activityEntries, issues: issues}) {
     const hosts = [ {
         scope: "stage",
         entries: stageEntries
@@ -2026,7 +2961,7 @@ function checkOpFieldRead({read: read, where: where, path: path, workflowEntries
                 read: read,
                 where: where,
                 hosts: hosts,
-                activityNames: activityNames
+                activityEntries: activityEntries
             })
         });
         return;
@@ -2040,11 +2975,54 @@ function checkOpFieldRead({read: read, where: where, path: path, workflowEntries
     });
 }
 
-function opFieldReadMissMessage({read: read, where: where, hosts: hosts, activityNames: activityNames}) {
-    const searched = read.scope === void 0 ? "stage or workflow scope" : `${read.scope} scope`, activityHint = activityNames?.has(read.field) ? ` "${read.field}" is an activity-scope field, and op-time field reads resolve against stage and workflow scopes only — declare it at stage scope to read it from an op.` : "", known = hosts.flatMap(host => host.entries.map(entry => `${host.scope}:${entry.name}`));
+function opFieldReadMissMessage({read: read, where: where, hosts: hosts, activityEntries: activityEntries}) {
+    const searched = read.scope === void 0 ? "stage or workflow scope" : `${read.scope} scope`, activityHint = activityEntries?.has(read.field) ? ` "${read.field}" is an activity-scope field, and op-time field reads resolve against stage and workflow scopes only — declare it at stage scope to read it from an op.` : "", known = hosts.flatMap(host => host.entries.map(entry => `${host.scope}:${entry.name}`));
     return `${where} reads field "${read.field}", which is not declared at ${searched} — the read resolves to undefined at op time, so the write silently lands empty.${activityHint} Known: ${known.join(", ") || "(none)"}`;
 }
 
+function checkUpdateWhereOps(def, issues) {
+    const workflow = def.fields ?? [];
+    for (const site of opSites(def)) for (const [o, op] of (site.ops ?? []).entries()) {
+        if (op.type !== "field.updateWhere") continue;
+        const scopes = {
+            workflow: workflow,
+            stage: site.stage.fields ?? [],
+            activity: site.activity.fields ?? []
+        };
+        checkUpdateWhereTargetKind({
+            op: op,
+            path: [ ...site.path, o ],
+            label: site.label,
+            scopes: scopes,
+            issues: issues
+        }), checkUpdateWhereMergeKeys({
+            op: op,
+            path: [ ...site.path, o ],
+            label: site.label,
+            issues: issues
+        });
+    }
+}
+
+function checkUpdateWhereTargetKind({op: op, path: path, label: label, scopes: scopes, issues: issues}) {
+    const target = scopes[op.target.scope]?.find(entry => entry.name === op.target.field);
+    target === void 0 || target.type === "array" || issues.push({
+        path: [ ...path, "target" ],
+        message: `${label} field.updateWhere targets ${op.target.scope}-scope "${op.target.field}" (${target.type}) — updateWhere merges declared row sub-fields, so its target must be an \`array\` entry${rowOpsHint(target.type)}`
+    });
+}
+
+function rowOpsHint(type) {
+    return type === "doc.refs" || type === "assignees" ? `; to add or drop ${type} rows use field.append / field.removeWhere` : "";
+}
+
+function checkUpdateWhereMergeKeys({op: op, path: path, label: label, issues: issues}) {
+    if (op.value.type === "object") for (const key of Object.keys(op.value.fields)) key !== "_key" && key !== "_type" || issues.push({
+        path: [ ...path, "value", "fields", key ],
+        message: `${label} field.updateWhere merge writes the reserved row key "${key}" — row identity and bookkeeping are engine-stamped, and a merge would restamp every matched row with the same literal`
+    });
+}
+
 function checkGuardFieldReads(def, issues) {
     const reads = {
         workflowEntries: def.fields ?? [],
@@ -2106,11 +3084,14 @@ function checkGuardFieldRead({name: name, valuePath: valuePath, where: where, pa
     });
 }
 
-function pushFieldReadPathIssue({where: where, read: read, target: target, path: path, issues: issues}) {
+function pushFieldReadPathIssue({where: where, read: read, target: target, path: path, issues: issues, nodes: nodes}) {
     if (read.path === void 0) return;
     const pathIssue = fieldValuePathIssue({
         target: target,
-        path: read.path
+        path: read.path,
+        ...nodes ? {
+            nodes: nodes
+        } : {}
     });
     pathIssue !== void 0 && issues.push({
         path: path,
@@ -2181,22 +3162,26 @@ const SCALAR = {
         kind: "rows",
         of: shape.of ?? []
     })
+}, START_ALLOWED_VALUE_NODES = {
+    ...VALUE_NODES,
+    "doc.ref": () => GDR_VALUE
 };
 
-function valueNodeFor(shape) {
-    return Object.hasOwn(VALUE_NODES, shape.type) ? VALUE_NODES[shape.type](shape) : void 0;
+function valueNodeFor(shape, nodes) {
+    return Object.hasOwn(nodes, shape.type) ? nodes[shape.type](shape) : void 0;
 }
 
 const INDEX_SEGMENT = /^\d+$/;
 
-function stepIntoValueNode(node, segment) {
+function stepIntoValueNode(args) {
+    const {node: node, segment: segment, nodes: nodes} = args;
     switch (node.kind) {
       case "scalar":
         return "the value is a scalar with no sub-paths";
 
       case "object":
         {
-            const sub = node.fields.find(f => f.name === segment), next = sub === void 0 ? void 0 : valueNodeFor(sub);
+            const sub = node.fields.find(f => f.name === segment), next = sub === void 0 ? void 0 : valueNodeFor(sub, nodes);
             return next !== void 0 ? next : `an object value has sub-fields ${knownList(node.fields.map(f => f.name))} — "${segment}" is not one`;
         }
 
@@ -2217,18 +3202,24 @@ function stepIntoValueNode(node, segment) {
     }
 }
 
-function fieldValuePathIssue({target: target, path: path}) {
-    let node = valueNodeFor(target);
+function fieldValuePathIssue({target: target, path: path, nodes: nodes = VALUE_NODES}) {
+    let node = valueNodeFor(target, nodes);
     if (node === void 0) return `"${String(target.type)}" is not a known field kind`;
     for (const segment of path.split(".")) {
-        const next = stepIntoValueNode(node, segment);
+        const next = stepIntoValueNode({
+            node: node,
+            segment: segment,
+            nodes: nodes
+        });
         if (typeof next == "string") return `at segment "${segment}": ${next}`;
         node = next;
     }
 }
 
 function checkWorkflowInvariants(def) {
-    const issues = [], stageNames = checkStages(def, issues);
+    const issues = [];
+    checkDefinitionName(def, issues);
+    const stageNames = checkStages(def, issues);
     return checkInitialStage({
         def: def,
         stageNames: stageNames,
@@ -2242,10 +3233,12 @@ function checkWorkflowInvariants(def) {
         stageNames: stageNames,
         issues: issues
     }), checkEffectNames(def, issues), checkGuardNames(def, issues), checkFieldEntryNames(def, issues), 
-    checkRequiredField(def, issues), checkPredicates(def, issues), checkUnboundCallerVars(def, issues), 
-    checkConditionFieldReads(def, issues), checkFieldReadSeeds(def, issues), checkFieldReadOpValues(def, issues), 
-    checkGuardFieldReads(def, issues), checkAssigneesEntries(def, issues), checkActivityKinds(def, issues), 
+    checkRequiredField(def, issues), checkStart(def, issues), checkPredicates(def, issues), 
+    checkUnboundConditionVars(def, issues), checkConditionFieldReads(def, issues), checkFieldReadSeeds(def, issues), 
+    checkFieldReadOpValues(def, issues), checkUpdateWhereOps(def, issues), checkGuardFieldReads(def, issues), 
+    checkAssigneesEntries(def, issues), checkActivityTerminalPaths(def, issues), checkTerminalStageActivities(def, issues), 
+    checkTriggeredActionParams(def, issues), checkStoredRolesPlacement(def, issues), 
     checkGroups(def, issues), issues;
 }
 
-export { ACTIVITY_KINDS, ACTOR_KINDS, AuthoringActionSchema, AuthoringActivitySchema, AuthoringFieldEntrySchema, AuthoringGuardSchema, AuthoringOpSchema, AuthoringStageSchema, AuthoringTransitionSchema, AuthoringWorkflowSchema, CALLER_BOUND_VARS, CONDITION_VARS, ContractViolationError, DOCUMENT_VALUE_PERMISSIONS, DRIVER_KINDS, DefinitionInUseError, DefinitionNotFoundError, EFFECTS_READ, EffectNotFoundError, EffectSchema, FIELD_READ, FILTER_SCOPE_VARS, FieldValueShapeError, GROUP_KINDS, GUARD_PREDICATE_VARS, GroupSchema, InstanceNotFoundError, RESERVED_CONDITION_VARS, RESOURCE_ALIAS_NAME_SOURCE, StoredFieldOpSchema, WORKFLOW_DEFINITION_TYPE, WorkflowConfigSchema, WorkflowError, actorFulfillsRole, andConditions, checkFieldValue, checkWorkflowInvariants, clientConfigFromResource, conditionEffectReads, conditionParameterNames, conditionSyntaxIssues, datasetResourceParts, definitionDocId, errorMessage, evaluateCondition, evaluateConditionOutcome, evaluatePredicates, expandRequiredRoles, extractDocumentId, formatIssuePath, formatIssues, formatValidationError, gdrFromResource, gdrRef, gdrResourcePrefix, gdrUri, groupMembershipNames, isBareSeedId, isGdr, isGdrUri, isGuardReadExpr, isNotesEntry, isStartableDefinition, isTerminalActivityStatus, isTodoListEntry, isTodoListItem, isUnevaluable, labelFor, normalizeRoleAliases, parseGdr, parseOrThrow, parseResourceGdr, parseStoredDefinition, printGuardRead, refCanvas, refDashboard, refDataset, refMediaLibrary, refTypeIssues, rejectedRefTypes, releaseDocId, releaseRef, resourceAliasesToMap, resourceFromGdrUri, resourceFromParsed, resourceGdr, rethrowWithContext, runGroq, sameResource, selfGdr, tagScopeFilter, toBareId, toPhysicalGdr, tryParseGdr, validateFieldAppendItem, validateFieldValue, validateResourceAliasName, validateTag };
+export { ACTIVITY_KINDS, ACTIVITY_STATUSES, ACTOR_KINDS, ActorShape, AuthoringActionSchema, AuthoringActivitySchema, AuthoringFieldEntrySchema, AuthoringGuardSchema, AuthoringOpSchema, AuthoringStageSchema, AuthoringTransitionSchema, AuthoringWorkflowSchema, CALLER_BOUND_VARS, CONDITION_VARS, ContractViolationError, DEFAULT_TRANSITION_WHEN, DOCUMENT_VALUE_PERMISSIONS, DRIVER_KINDS, DefinitionInUseError, DefinitionNotFoundError, EFFECTS_READ, EXECUTOR_CLASSIFICATIONS, EffectNotFoundError, EffectSchema, FIELD_READ, FIELD_SCOPES, FIELD_VALUE_KINDS, FILTER_SCOPE_VARS, FieldValueShapeError, GROUP_KINDS, GUARD_PREDICATE_VARS, GdrShape, GroupSchema, InstanceNotFoundError, IsoTimestamp, MUTATION_GUARD_ACTIONS, NonEmptyString, PersistedDocShapeError, RESERVED_CONDITION_VARS, RESOURCE_ALIAS_NAME_SOURCE, START_ALLOWED_VARS, START_FILTER_VARS, StoredFieldOpSchema, WORKFLOW_DEFINITION_TYPE, WorkflowConfigSchema, WorkflowError, actorFulfillsRole, andConditions, checkFieldValue, checkWorkflowInvariants, clientConfigFromResource, conditionEffectReads, conditionFieldReadNames, conditionParameterNames, conditionSyntaxIssues, datasetResourceParts, definitionDocId, deriveActivityKind, deriveExecutorClassification, desugarWorkflow, driverKind, errorMessage, evaluateCondition, evaluateConditionOutcome, evaluatePredicates, extractDocumentId, fieldValueSchemas, formatIssuePath, formatIssues, formatValidationError, gdrFromResource, gdrRef, gdrResourcePrefix, gdrUri, groq, groupMembershipNames, isBareSeedId, isCascadeFired, isGdr, isGdrUri, isGuardReadExpr, isInputSourced, isNotesEntry, isParseableInstant, isStartableDefinition, isSubjectEntry, isTerminalActivityStatus, isTodoListEntry, isTodoListItem, isUnevaluable, labelFor, parseGdr, parseOrThrow, parsePersistedDoc, parseResourceGdr, parseStoredDefinition, readsRootDocument, refCanvas, refDashboard, refDataset, refMediaLibrary, refTypeIssues, rejectedRefTypes, releaseDocId, releaseRef, resourceAliasesToMap, resourceFromGdrUri, resourceFromParsed, resourceGdr, rethrowWithContext, runGroq, sameResource, schemaTreeShape, selfGdr, startKindOf, tagScopeFilter, toBareId, toPhysicalGdr, tolerantEntries, tolerantObject, tryParseGdr, validateFieldAppendItem, validateFieldValue, validateResourceAliasName, validateTag };