@sanity/workflow-engine 0.16.0 → 0.18.0

package/dist/_chunks-es/invariants.js

@@ -4,6 +4,291 @@ import { conditionOutcome, runGroq as runGroq$1, evaluateConditionOutcome as eva
 
 import { parse } from "groq-js";
 
+class WorkflowError extends Error {
+    kind;
+    constructor(kind, message, options) {
+        super(message, options), this.kind = kind;
+    }
+}
+
+class ContractViolationError extends WorkflowError {
+    constructor(message) {
+        super("contract-violation", message), this.name = "ContractViolationError";
+    }
+}
+
+class InstanceNotFoundError extends WorkflowError {
+    instanceId;
+    constructor(args) {
+        super("instance-not-found", `Workflow instance ${args.instanceId} not found${args.detail ? ` (${args.detail})` : ""}`), 
+        this.name = "InstanceNotFoundError", this.instanceId = args.instanceId;
+    }
+}
+
+class DefinitionNotFoundError extends WorkflowError {
+    definition;
+    version;
+    constructor(args) {
+        super("definition-not-found", args.version !== void 0 ? `Workflow definition ${args.definition} v${args.version} not deployed` : `Workflow definition ${args.definition} has no deployed versions`), 
+        this.name = "DefinitionNotFoundError", this.definition = args.definition, args.version !== void 0 && (this.version = args.version);
+    }
+}
+
+class SpawnContractsInvalidError extends WorkflowError {
+    issues;
+    constructor(args) {
+        super("spawn-contracts-invalid", args.message), this.name = "SpawnContractsInvalidError", 
+        this.issues = args.issues;
+    }
+}
+
+class DefinitionInUseError extends WorkflowError {
+    definition;
+    blockedBy;
+    constructor(args) {
+        super("definition-in-use", definitionInUseMessage(args.definition, args.blockedBy)), 
+        this.name = "DefinitionInUseError", this.definition = args.definition, this.blockedBy = args.blockedBy;
+    }
+}
+
+function definitionInUseMessage(definition, blockedBy) {
+    if (blockedBy.reason === "non-terminal-instances") {
+        const head = blockedBy.instanceIds.slice(0, 3).join(", "), preview = blockedBy.instanceIds.length > 3 ? `${head}, …` : head;
+        return `Cannot delete ${definition}: ${blockedBy.instanceIds.length} non-terminal instance(s) exist (${preview}). Pass cascade to abort them first — instances are aborted in place, never deleted.`;
+    }
+    const names = blockedBy.referrers.map(r => `${r.definition} v${r.version}`).join(", ");
+    return `Cannot delete ${definition}: still spawn-referenced by deployed definition(s) ${names}. Delete or redeploy the referrer(s) first.`;
+}
+
+class EffectNotFoundError extends WorkflowError {
+    instanceId;
+    effectKey;
+    settled;
+    constructor(args) {
+        super("effect-not-found", effectNotFoundMessage(args)), this.name = "EffectNotFoundError", 
+        this.instanceId = args.instanceId, this.effectKey = args.effectKey, args.settled !== void 0 && (this.settled = args.settled);
+    }
+}
+
+function effectNotFoundMessage(args) {
+    const base = `Pending effect "${args.effectKey}" not found on instance ${args.instanceId}`;
+    if (args.settled === void 0) return base;
+    const cause = args.settled.detail !== void 0 ? ` (${args.settled.detail})` : "";
+    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}`;
+}
+
+function errorMessage(err) {
+    return (err instanceof Error ? err.message : String(err)).replace(/[^\P{Cc}\n\t]/gu, "");
+}
+
+function rethrowWithContext(err, context) {
+    throw new Error(`${context}: ${errorMessage(err)}`, {
+        cause: err
+    });
+}
+
+const WORKFLOW_INSTANCE_TYPE = "sanity.workflow.instance";
+
+function terminalState(instance) {
+    return instance.abortedAt !== void 0 ? "aborted" : instance.completedAt !== void 0 ? "completed" : "in-flight";
+}
+
+function isUnprimed(instance) {
+    return instance.stages.length === 0 && terminalState(instance) === "in-flight";
+}
+
+function parseDefinitionSnapshotValue(instance) {
+    try {
+        return JSON.parse(instance.definitionSnapshot);
+    } catch (err) {
+        rethrowWithContext(err, `Failed to parse definitionSnapshot on instance "${instance._id}"`);
+    }
+}
+
+function parseDefinitionSnapshot(instance) {
+    return parseDefinitionSnapshotValue(instance);
+}
+
+function parentRef(instance) {
+    return instance.ancestors.at(-1);
+}
+
+const DATA_MODEL_VERSION = 2, DATA_MODEL_MIN_READER = 2, READER_MODEL_ROLLOUT_URL = "https://github.com/sanity-io/workflows/blob/main/docs/reader-model-rollout.md";
+
+class ReaderModelAcknowledgementError extends WorkflowError {
+    code="WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH";
+    expectedMinReaderModel;
+    engineMinReaderModel=DATA_MODEL_MIN_READER;
+    engineModelVersion=DATA_MODEL_VERSION;
+    documentationUrl=READER_MODEL_ROLLOUT_URL;
+    constructor(expectedMinReaderModel, context = "Deployment") {
+        const expected = expectedMinReaderModel === void 0 ? "missing" : String(expectedMinReaderModel);
+        super("reader-model-acknowledgement", `${context} expected reader floor ${expected}; the installed engine requires acknowledgement ${DATA_MODEL_MIN_READER}. Dependency upgrades can change writer compatibility. Upgrade all readers and Functions before accepting a higher floor; after verifying the rollout, change the literal in deployment configuration. ${READER_MODEL_ROLLOUT_URL}`), 
+        this.name = "ReaderModelAcknowledgementError", this.expectedMinReaderModel = expectedMinReaderModel;
+    }
+}
+
+function assertReaderModelAcknowledgement(expectedMinReaderModel, context) {
+    if (typeof expectedMinReaderModel != "number" || !Number.isFinite(expectedMinReaderModel) || !Number.isInteger(expectedMinReaderModel) || expectedMinReaderModel < 0 || expectedMinReaderModel !== DATA_MODEL_MIN_READER) throw new ReaderModelAcknowledgementError(expectedMinReaderModel, context);
+}
+
+const DATA_MODEL_CHANGES = Object.freeze([ Object.freeze({
+    id: "governed-model-stamps",
+    introducedInModel: 1,
+    minReaderModel: 0,
+    documentTypes: Object.freeze([ "definition", "instance" ]),
+    compatibility: "additive",
+    applicability: "unconditional",
+    summary: "Definition and instance documents carry model provenance and reader-floor stamps."
+}), Object.freeze({
+    id: "subject-field-kind",
+    introducedInModel: 2,
+    minReaderModel: 0,
+    documentTypes: Object.freeze([ "definition", "instance" ]),
+    compatibility: "additive",
+    applicability: "detectable",
+    summary: "A workflow-level subject field identifies the document a workflow is about."
+}), Object.freeze({
+    id: "typed-scalar-choice-lists",
+    introducedInModel: 2,
+    minReaderModel: 2,
+    documentTypes: Object.freeze([ "definition", "instance" ]),
+    compatibility: "reader-floor",
+    applicability: "detectable",
+    summary: "Scalar fields may constrain writes to a persisted typed choice list."
+}), Object.freeze({
+    id: "action-semantics",
+    introducedInModel: 2,
+    minReaderModel: 0,
+    documentTypes: Object.freeze([ "definition" ]),
+    compatibility: "additive",
+    applicability: "detectable",
+    summary: "Ordinary actions may carry a closed bag of advisory workflow semantics."
+}), Object.freeze({
+    id: "inclusive-scalar-bounds",
+    introducedInModel: 2,
+    minReaderModel: 2,
+    documentTypes: Object.freeze([ "definition", "instance" ]),
+    compatibility: "reader-floor",
+    applicability: "detectable",
+    summary: "String, text, and number values may carry persisted inclusive bounds."
+}) ]);
+
+function recordOf(value) {
+    return value !== null && typeof value == "object" && !Array.isArray(value) ? value : void 0;
+}
+
+function recordsAt(record, key) {
+    const value = record[key];
+    return Array.isArray(value) ? value.map(recordOf).filter(item => item !== void 0) : [];
+}
+
+function nestedFieldEntries(entries) {
+    return entries.flatMap(entry => [ entry, ...nestedFieldEntries(recordsAt(entry, "fields")), ...nestedFieldEntries(recordsAt(entry, "of")) ]);
+}
+
+function parsedDefinitionSnapshot(root) {
+    if (typeof root.definitionSnapshot == "string") return recordOf(parseDefinitionSnapshotValue({
+        _id: typeof root._id == "string" ? root._id : "<unknown instance>",
+        definitionSnapshot: root.definitionSnapshot
+    }));
+}
+
+function persistedFieldEntries(document) {
+    const root = recordOf(document);
+    if (root === void 0) return [];
+    const snapshot = parsedDefinitionSnapshot(root), roots = snapshot === void 0 ? [ root ] : [ root, snapshot ], stages = roots.flatMap(candidate => recordsAt(candidate, "stages")), activities = stages.flatMap(stage => recordsAt(stage, "activities")), actions = activities.flatMap(activity => recordsAt(activity, "actions")), effects = actions.flatMap(action => recordsAt(action, "effects"));
+    return nestedFieldEntries([ ...roots.flatMap(candidate => recordsAt(candidate, "fields")), ...stages.flatMap(stage => recordsAt(stage, "fields")), ...activities.flatMap(activity => recordsAt(activity, "fields")), ...actions.flatMap(action => recordsAt(action, "params")), ...effects.flatMap(effect => recordsAt(effect, "outputs")) ]);
+}
+
+function hasChoiceList(document) {
+    return persistedFieldEntries(document).some(entry => {
+        const options = recordOf(entry.options);
+        return options !== void 0 && Array.isArray(options.list);
+    });
+}
+
+function hasSubjectField(document) {
+    return persistedFieldEntries(document).some(entry => entry.type === "subject" || entry._type === "subject");
+}
+
+function hasActionSemantics(document) {
+    const root = recordOf(document);
+    return root === void 0 ? !1 : recordsAt(root, "stages").flatMap(stage => recordsAt(stage, "activities")).flatMap(activity => recordsAt(activity, "actions")).some(action => Array.isArray(action.semantics));
+}
+
+function hasScalarValidation(document) {
+    return persistedFieldEntries(document).some(entry => {
+        const validation = recordOf(entry.validation);
+        return typeof validation?.min == "number" || typeof validation?.max == "number";
+    });
+}
+
+const featureDetectors = {
+    "governed-model-stamps": () => !0,
+    "subject-field-kind": hasSubjectField,
+    "typed-scalar-choice-lists": hasChoiceList,
+    "action-semantics": hasActionSemantics,
+    "inclusive-scalar-bounds": hasScalarValidation
+};
+
+function requiredModelFeatures(documentType, document) {
+    return DATA_MODEL_CHANGES.filter(change => change.documentTypes.some(candidate => candidate === documentType) && featureDetectors[change.id](document));
+}
+
+function requiredReaderModel(documentType, document) {
+    return Math.max(0, ...requiredModelFeatures(documentType, document).map(change => change.minReaderModel));
+}
+
+function modelStampFor(args) {
+    return {
+        modelVersion: DATA_MODEL_VERSION,
+        minReaderModel: Math.max(args.storedMinReaderModel ?? 0, requiredReaderModel(args.documentType, args.document))
+    };
+}
+
+function fieldTreeShape(value) {
+    if (Array.isArray(value)) return value.map(fieldTreeShape);
+    if (value === null) return "null";
+    if (typeof value == "object") {
+        const record = value;
+        return Object.fromEntries(Object.keys(record).toSorted().map(key => [ key, fieldTreeShape(record[key]) ]));
+    }
+    return typeof value;
+}
+
+function modelVersionOf(doc) {
+    const stamp = doc.modelVersion;
+    return typeof stamp == "number" ? stamp : 0;
+}
+
+function minReaderModelOf(doc) {
+    const floor = doc.minReaderModel;
+    return typeof floor == "number" ? floor : modelVersionOf(doc);
+}
+
+class ModelVersionAheadError extends WorkflowError {
+    documentId;
+    documentModelVersion;
+    requiredReaderModel;
+    engineModelVersion;
+    constructor(args) {
+        super("model-version-ahead", `Document "${args.documentId}" was written by engine data model ${args.documentModelVersion} and requires a reader at model ${args.requiredReaderModel} or newer; this engine reads up to model ${DATA_MODEL_VERSION}. Upgrade @sanity/workflow-engine to a version that understands it.`), 
+        this.name = "ModelVersionAheadError", this.documentId = args.documentId, this.documentModelVersion = args.documentModelVersion, 
+        this.requiredReaderModel = args.requiredReaderModel, this.engineModelVersion = DATA_MODEL_VERSION;
+    }
+}
+
+function assertReadableModel(doc) {
+    const documentReaderModel = minReaderModelOf(doc);
+    if (documentReaderModel > DATA_MODEL_VERSION) throw new ModelVersionAheadError({
+        documentId: doc._id,
+        documentModelVersion: modelVersionOf(doc),
+        requiredReaderModel: documentReaderModel
+    });
+    return doc;
+}
+
 function isCascadeFired(action) {
     return action.when !== void 0;
 }
@@ -24,16 +309,6 @@ 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, "");
-}
-
-function rethrowWithContext(err, context) {
-    throw new Error(`${context}: ${errorMessage(err)}`, {
-        cause: err
-    });
-}
-
 function andConditions(parts) {
     const present = parts.filter(p => p !== void 0);
     if (present.length !== 0) return present.length === 1 ? present[0] : present.map(p => `(${p})`).join(" && ");
@@ -234,82 +509,17 @@ function isGdr(value) {
     return typeof value == "object" && value !== null && typeof value.id == "string" && typeof value.type == "string";
 }
 
-class WorkflowError extends Error {
-    kind;
-    constructor(kind, message, options) {
-        super(message, options), this.kind = kind;
-    }
-}
-
-class ContractViolationError extends WorkflowError {
-    constructor(message) {
-        super("contract-violation", message), this.name = "ContractViolationError";
-    }
-}
-
-class InstanceNotFoundError extends WorkflowError {
-    instanceId;
-    constructor(args) {
-        super("instance-not-found", `Workflow instance ${args.instanceId} not found${args.detail ? ` (${args.detail})` : ""}`), 
-        this.name = "InstanceNotFoundError", this.instanceId = args.instanceId;
-    }
-}
-
-class DefinitionNotFoundError extends WorkflowError {
-    definition;
-    version;
-    constructor(args) {
-        super("definition-not-found", args.version !== void 0 ? `Workflow definition ${args.definition} v${args.version} not deployed` : `Workflow definition ${args.definition} has no deployed versions`), 
-        this.name = "DefinitionNotFoundError", this.definition = args.definition, args.version !== void 0 && (this.version = args.version);
-    }
-}
-
-class DefinitionInUseError extends WorkflowError {
-    definition;
-    blockedBy;
-    constructor(args) {
-        super("definition-in-use", definitionInUseMessage(args.definition, args.blockedBy)), 
-        this.name = "DefinitionInUseError", this.definition = args.definition, this.blockedBy = args.blockedBy;
-    }
-}
-
-function definitionInUseMessage(definition, blockedBy) {
-    if (blockedBy.reason === "non-terminal-instances") {
-        const head = blockedBy.instanceIds.slice(0, 3).join(", "), preview = blockedBy.instanceIds.length > 3 ? `${head}, …` : head;
-        return `Cannot delete ${definition}: ${blockedBy.instanceIds.length} non-terminal instance(s) exist (${preview}). Pass cascade to abort them first — instances are aborted in place, never deleted.`;
-    }
-    const names = blockedBy.referrers.map(r => `${r.definition} v${r.version}`).join(", ");
-    return `Cannot delete ${definition}: still spawn-referenced by deployed definition(s) ${names}. Delete or redeploy the referrer(s) first.`;
-}
-
-class EffectNotFoundError extends WorkflowError {
-    instanceId;
-    effectKey;
-    settled;
-    constructor(args) {
-        super("effect-not-found", effectNotFoundMessage(args)), this.name = "EffectNotFoundError", 
-        this.instanceId = args.instanceId, this.effectKey = args.effectKey, args.settled !== void 0 && (this.settled = args.settled);
-    }
-}
-
-function effectNotFoundMessage(args) {
-    const base = `Pending effect "${args.effectKey}" not found on instance ${args.instanceId}`;
-    if (args.settled === void 0) return base;
-    const cause = args.settled.detail !== void 0 ? ` (${args.settled.detail})` : "";
-    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 => {
@@ -323,21 +533,22 @@ 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,
+    expectedMinReaderModel: v.optional(v.custom(() => !0), void 0),
     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"))),
@@ -502,6 +713,9 @@ function desugarStart(start) {
         kind: start.kind ?? "interactive",
         ...start.filter !== void 0 ? {
             filter: start.filter
+        } : {},
+        ...start.allowed !== void 0 ? {
+            allowed: start.allowed
         } : {}
     };
 }
@@ -577,6 +791,8 @@ function desugarFieldEntry({entry: entry, path: path, ctx: ctx}) {
             required: entry.required,
             initialValue: entry.initialValue,
             editable: editable,
+            options: entry.options,
+            validation: entry.validation,
             types: entry.types,
             fields: entry.fields,
             of: entry.of
@@ -719,7 +935,7 @@ function desugarActivity({activity: activity, path: path, stageEnv: stageEnv, ct
     };
 }
 
-const TARGET_DOC_KINDS = [ "doc.ref", "doc.refs", "release.ref" ];
+const TARGET_DOC_KINDS = [ "doc.ref", "doc.refs", "subject", "release.ref" ];
 
 function desugarTarget({target: target, env: env, path: path, ctx: ctx}) {
     if (target === void 0 || target.type === "url") return target;
@@ -740,18 +956,15 @@ function desugarTarget({target: target, env: env, path: path, ctx: ctx}) {
     };
 }
 
-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({
+function reportEmptyActionRoles({action: action, path: path, 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({
+}
+
+function desugarActionOps(args) {
+    const {action: action, path: path, env: env, activityName: activityName, ctx: ctx} = args, ops = desugarOps({
         ops: action.ops,
         path: [ ...path, "ops" ],
         env: env,
@@ -762,9 +975,32 @@ function desugarAction({action: action, path: path, env: env, activityName: acti
         type: "status.set",
         activity: activityName,
         status: action.status
-    }), {
+    }), ops;
+}
+
+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
+    });
+    reportEmptyActionRoles({
+        action: action,
+        path: path,
+        ctx: ctx
+    });
+    const cascadeFired = isCascadeFired(action), filter = cascadeFired ? action.filter : andConditions([ rolesCondition(action.roles, ctx.roleAliases), action.filter ]), ops = desugarActionOps({
+        action: action,
+        path: path,
+        env: env,
+        activityName: activityName,
+        ctx: ctx
+    });
+    return {
         ...stripUndefined({
             name: action.name,
+            semantics: action.semantics,
             title: action.title,
             description: action.description,
             group: normalizeGroup(action.group),
@@ -1050,12 +1286,43 @@ function conditionParameterNames(groq2) {
 }
 
 function conditionFieldReadNames(groq2) {
-    const read = /* @__PURE__ */ new Set;
-    return walkAstNodes(tryParseGroq(groq2), 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;
+    return new Set(conditionFieldReads(groq2).map(read => read.name));
+}
+
+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) {
@@ -1120,7 +1387,7 @@ 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 = [ {
+const ACTION_SEMANTICS = [ "decision.accept", "decision.decline" ], 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",
@@ -1129,7 +1396,7 @@ const FIELD_SCOPES = [ "workflow", "stage", "activity" ], DOCUMENT_VALUE_PERMISS
     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` (or `subject`) 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",
@@ -1199,7 +1466,7 @@ const FIELD_SCOPES = [ "workflow", "stage", "activity" ], DOCUMENT_VALUE_PERMISS
     name: "row",
     binding: "spawn",
     label: "the spawned 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)."
+    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",
@@ -1210,25 +1477,161 @@ const FIELD_SCOPES = [ "workflow", "stage", "activity" ], DOCUMENT_VALUE_PERMISS
     binding: "always",
     label: "the spawned subworkflows",
     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 = [ {
+} ], SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR = "subjectHasInFlightInstance", RESERVED_CONDITION_VARS = [ ...CONDITION_VARS.map(v2 => v2.name), SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR ], 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",
+    label: "this engine 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.filter binds it)."
+    label: "this workflow definition",
+    description: "The `name` of the definition under evaluation (its own start block binds it)."
 }, {
     name: "now",
+    label: "the current time",
     description: "The ISO clock reading of the evaluating engine."
 }, {
+    name: SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR,
+    label: "the subject already has an in-flight workflow",
+    description: "Whether any instance in this engine tag, across all definitions, has the same resource-qualified subject and no `completedAt`. Advisory under concurrent starts."
+} ], START_ALLOWED_VARS = [ ...START_FILTER_VARS, {
     name: "fields",
-    description: "The candidate initialFields by entry name, when the read surface has them (the Studio start control: yes; a per-doc picker: no). Document references bind as GDR envelopes — `$fields.<entry>.id` is the GDR URI, never a string authors assemble."
+    label: "the start's input 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` or `subject` 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}`;
@@ -1243,6 +1646,18 @@ function releaseRef({res: res, releaseName: releaseName}) {
     };
 }
 
+function isSingleDocRefKind(kind) {
+    return kind === "doc.ref" || kind === "subject";
+}
+
+function refKindAcceptsTypes(kind) {
+    return isSingleDocRefKind(kind) || kind === "doc.refs";
+}
+
+function isSingleDocRefEntry(entry) {
+    return isSingleDocRefKind(entry._type);
+}
+
 function isTodoListItem(row) {
     if (typeof row != "object" || row === null) return !1;
     const candidate = row, status = candidate.status;
@@ -1275,29 +1690,53 @@ 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, CHOICE_KINDS = /* @__PURE__ */ new Set([ "string", "text", "number", "url", "date", "datetime", "dateTime" ]);
+
+function normalizedChoiceKind(kind) {
+    return kind === "dateTime" ? "datetime" : kind;
+}
+
+function checkChoiceList(args) {
+    const {entryType: entryType, options: options, validation: validation} = args;
+    if (options === void 0) return;
+    if (!CHOICE_KINDS.has(entryType)) return [ `\`options\` is not valid on "${entryType}" values` ];
+    const kind = normalizedChoiceKind(entryType), issues = options.list.flatMap((option, index) => checkValueAgainst({
+        entryType: kind,
+        value: option.value,
+        validation: validation
+    }, valueSchemas)?.map(issue => `at options.list.${index}.value: ${issue}`) ?? []), seen = /* @__PURE__ */ new Set;
+    for (const option of options.list) seen.has(option.value) && issues.push(`duplicate option value ${JSON.stringify(option.value)}`), 
+    seen.add(option.value);
+    return issues.length === 0 ? void 0 : issues;
+}
+
+function choiceValueIssues(options, value) {
+    if (!(options === void 0 || value === null || value === void 0)) return options.list.some(option => Object.is(option.value, value)) ? void 0 : [ `value ${JSON.stringify(value)} is not declared in \`options.list\`; expected one of ${options.list.map(option => JSON.stringify(option.value)).join(", ")}` ];
+}
+
+const fieldValueSchemas = {
     "doc.ref": v.union([ v.null(), GdrShape ]),
     "doc.refs": v.array(GdrShape),
+    subject: v.union([ v.null(), GdrShape ]),
     "release.ref": v.union([ v.null(), ReleaseRefShape ]),
-    query: v.any(),
     string: NullableString,
     text: NullableString,
     number: NullableNumber,
@@ -1308,10 +1747,62 @@ 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) {
-    return shape.type === "object" ? objectSchema(shape.fields ?? [], leaf) : shape.type === "array" ? v.array(objectSchema(shape.of ?? [], leaf)) : leaf[shape.type] ?? v.any();
+    if (shape.type === "object") return objectSchema(shape.fields ?? [], leaf);
+    if (shape.type === "array") return v.array(objectSchema(shape.of ?? [], leaf));
+    const schema = leaf[shape.type] ?? v.any();
+    return constrainedScalarSchema({
+        schema: schema,
+        entryType: shape.type,
+        ...shape
+    });
+}
+
+function scalarMeasurement(entryType, value) {
+    if (entryType === "number" && typeof value == "number") return value;
+    if ((entryType === "string" || entryType === "text") && typeof value == "string") return value.length;
+}
+
+function scalarBoundIssue(args) {
+    const {entryType: entryType, measured: measured, bound: bound, limit: limit} = args;
+    return bound === void 0 || limit === "min" && measured >= bound || limit === "max" && measured <= bound ? void 0 : `${entryType === "number" ? "" : "length "}must be ${limit === "min" ? "greater than or equal to" : "less than or equal to"} ${bound}`;
+}
+
+function scalarValidationIssues(args) {
+    const {entryType: entryType, validation: validation, value: value} = args;
+    if (validation === void 0 || value === null || value === void 0) return;
+    const measured = scalarMeasurement(entryType, value);
+    if (measured === void 0) return;
+    const issues = [ scalarBoundIssue({
+        entryType: entryType,
+        measured: measured,
+        bound: validation.min,
+        limit: "min"
+    }), scalarBoundIssue({
+        entryType: entryType,
+        measured: measured,
+        bound: validation.max,
+        limit: "max"
+    }) ].filter(issue => issue !== void 0);
+    return issues.length === 0 ? void 0 : issues;
+}
+
+function constrainedScalarSchema(args) {
+    const {schema: schema, entryType: entryType, options: options, validation: validation} = args;
+    return options === void 0 && validation === void 0 ? schema : v.pipe(schema, v.check(value => choiceValueIssues(options, value) === void 0 && scalarValidationIssues({
+        entryType: entryType,
+        validation: validation,
+        value: value
+    }) === void 0, issue => [ ...choiceValueIssues(options, issue.input) ?? [], ...scalarValidationIssues({
+        entryType: entryType,
+        validation: validation,
+        value: issue.input
+    }) ?? [] ].join("; ")));
 }
 
 function objectSchema(fields, leaf) {
@@ -1334,7 +1825,7 @@ function appendItemSchema(entryType, shape) {
 function rejectedRefTypes(args) {
     const {entryType: entryType, types: types, value: value} = args;
     if (types === void 0 || value === null || value === void 0) return [];
-    if (entryType !== "doc.ref" && entryType !== "doc.refs") return [];
+    if (!refKindAcceptsTypes(entryType)) return [];
     let items = [ value ];
     return entryType === "doc.refs" && (items = Array.isArray(value) ? value : []), 
     [ ...new Set(items.map(gdrTypeOf).filter(t => t !== void 0 && !types.includes(t))) ];
@@ -1369,6 +1860,10 @@ function checkValueAgainst(args, leaf) {
         entryType: args.entryType,
         types: args.types,
         value: args.value
+    }) ?? choiceValueIssues(args.options, args.value) ?? scalarValidationIssues({
+        entryType: args.entryType,
+        validation: args.validation,
+        value: args.value
     }) : formatIssues(result.issues);
 }
 
@@ -1394,15 +1889,16 @@ 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 ]),
     "doc.refs": v.array(AuthoringGdrShape),
+    subject: v.union([ v.null(), AuthoringGdrShape ]),
     "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
     }) ])
 };
 
@@ -1438,14 +1934,14 @@ function validateFieldAppendItem(args) {
     });
 }
 
-function formatIssues(issues) {
+function formatIssues(issues, formatMessage = issue => issue.message) {
     return issues.map(i => {
         const keys = i.path?.map(p => p.key) ?? [];
-        return `${keys.length > 0 ? `at ${keys.join(".")}: ` : ""}${i.message}`;
+        return `${keys.length > 0 ? `at ${keys.join(".")}: ` : ""}${formatMessage(i)}`;
     });
 }
 
-const 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`));
@@ -1567,7 +2063,15 @@ function groupMembershipNames(group) {
     return group === void 0 ? [] : typeof group == "string" ? [ group ] : [ ...group ];
 }
 
-const FIELD_VALUE_KINDS = [ "doc.ref", "doc.refs", "release.ref", "string", "text", "number", "boolean", "date", "datetime", "url", "actor", "assignee", "assignees", "object", "array" ], FieldValueKindSchema = picklist(FIELD_VALUE_KINDS), FieldKindSchema = picklist(FIELD_VALUE_KINDS), FieldEntryName = groqIdentifier("`$fields.<name>`");
+const FIELD_VALUE_KINDS = [ "doc.ref", "doc.refs", "subject", "release.ref", "string", "text", "number", "boolean", "date", "datetime", "url", "actor", "assignee", "assignees", "object", "array" ], FieldValueKindSchema = picklist(FIELD_VALUE_KINDS), FieldKindSchema = picklist(FIELD_VALUE_KINDS), FieldEntryName = groqIdentifier("`$fields.<name>`"), FiniteNumber = v.pipe(v.number(), v.finite("must be finite")), ScalarValidationSchema = v.pipe(v.strictObject({
+    min: v.optional(FiniteNumber),
+    max: v.optional(FiniteNumber)
+}), v.check(validation => validation.min !== void 0 || validation.max !== void 0, "declare at least one bound, or omit `validation`"), v.check(validation => validation.min === void 0 || validation.max === void 0 || validation.min <= validation.max, "`min` must be less than or equal to `max`")), ChoiceOptionsSchema = v.strictObject({
+    list: v.pipe(v.array(v.strictObject({
+        title: NonEmpty,
+        value: v.union([ v.string(), v.number() ])
+    })), v.minLength(1, "declare at least one choice, or omit `options`"))
+});
 
 function asShape(input) {
     return typeof input == "object" && input !== null ? input : {};
@@ -1601,14 +2105,16 @@ function compositeChecked(entries) {
     return v.pipe(v.strictObject(entries), v.check(input => compositeShapeOk(input), issue => compositeShapeMessage(issue.input)), v.check(input => duplicateSubfieldName(input) === void 0, issue => `duplicate sub-field name "${duplicateSubfieldName(issue.input)}" — sub-field names must be unique within \`fields\` / \`of\``));
 }
 
-const FieldShapeSchema = v.lazy(() => compositeChecked({
+const FieldShapeSchema = v.lazy(() => v.pipe(compositeChecked({
     type: FieldValueKindSchema,
     name: FieldEntryName,
     title: v.optional(v.string()),
     description: v.optional(v.string()),
+    options: v.optional(ChoiceOptionsSchema),
+    validation: v.optional(ScalarValidationSchema),
     fields: v.optional(v.array(FieldShapeSchema)),
     of: v.optional(v.array(FieldShapeSchema))
-})), StoredEditableSchema = v.union([ v.literal(!0), NonEmpty ]), AuthoringEditableSchema = v.union([ v.literal(!0), v.array(NonEmpty), NonEmpty ]);
+}), choiceOptionsCheck(), scalarValidationCheck())), StoredEditableSchema = v.union([ v.literal(!0), NonEmpty ]), AuthoringEditableSchema = v.union([ v.literal(!0), v.array(NonEmpty), NonEmpty ]);
 
 function fieldBase(editable, group) {
     return {
@@ -1626,6 +2132,8 @@ function fieldEntryFields(editable, group) {
     return {
         type: FieldKindSchema,
         ...fieldBase(editable, group),
+        options: v.optional(ChoiceOptionsSchema),
+        validation: v.optional(ScalarValidationSchema),
         types: v.optional(v.pipe(v.array(NonEmpty), v.minLength(1, "declare at least one accepted type, or omit `types` to accept any"))),
         fields: v.optional(v.array(FieldShapeSchema)),
         of: v.optional(v.array(FieldShapeSchema))
@@ -1638,7 +2146,9 @@ function literalSeedIssues(entry) {
         value: entry.initialValue.value,
         types: entry.types,
         fields: entry.fields,
-        of: entry.of
+        of: entry.of,
+        options: entry.options,
+        validation: entry.validation
     });
 }
 
@@ -1647,10 +2157,37 @@ function literalSeedCheck() {
 }
 
 function refTypesCheck() {
-    return v.check(entry => entry.types === void 0 || entry.type === "doc.ref" || entry.type === "doc.refs", issue => `\`types\` is only valid on \`doc.ref\` / \`doc.refs\` entries, not "${issue.input.type}"`);
+    return v.check(entry => entry.types === void 0 || refKindAcceptsTypes(entry.type), issue => `\`types\` is only valid on \`doc.ref\` / \`doc.refs\` / \`subject\` entries, not "${issue.input.type}"`);
 }
 
-const FieldEntrySchema = pinned()(v.pipe(compositeChecked(fieldEntryFields(StoredEditableSchema, StoredGroupMembershipSchema)), refTypesCheck(), literalSeedCheck())), RawAuthoringFieldEntrySchema = pinned()(v.pipe(compositeChecked(fieldEntryFields(AuthoringEditableSchema, AuthoringGroupMembershipSchema)), refTypesCheck(), literalSeedCheck())), ClaimFieldSchema = pinned()(v.strictObject({
+function choiceOptionsCheck() {
+    return v.check(entry => checkChoiceList({
+        entryType: entry.type,
+        options: entry.options,
+        validation: entry.validation
+    }) === void 0, issue => (checkChoiceList({
+        entryType: issue.input.type,
+        options: issue.input.options,
+        validation: issue.input.validation
+    }) ?? []).join("; "));
+}
+
+const SCALAR_VALIDATION_KINDS = /* @__PURE__ */ new Set([ "string", "text", "number" ]);
+
+function scalarValidationCheck() {
+    return v.check(entry => scalarValidationDeclarationIssues(entry) === void 0, issue => (scalarValidationDeclarationIssues(issue.input) ?? []).join("; "));
+}
+
+function scalarValidationDeclarationIssues(entry) {
+    const {type: type, validation: validation} = entry;
+    if (validation === void 0) return;
+    if (!SCALAR_VALIDATION_KINDS.has(type)) return [ `\`validation\` is only valid on \`string\` / \`text\` / \`number\` values, not "${type}"` ];
+    if (type === "number") return;
+    const issues = Object.entries(validation).flatMap(([bound, value]) => Number.isInteger(value) && value >= 0 ? [] : [ `\`validation.${bound}\` must be a non-negative integer for ${type} length` ]);
+    return issues.length === 0 ? void 0 : issues;
+}
+
+const FieldEntrySchema = pinned()(v.pipe(compositeChecked(fieldEntryFields(StoredEditableSchema, StoredGroupMembershipSchema)), refTypesCheck(), choiceOptionsCheck(), scalarValidationCheck(), literalSeedCheck())), RawAuthoringFieldEntrySchema = pinned()(v.pipe(compositeChecked(fieldEntryFields(AuthoringEditableSchema, AuthoringGroupMembershipSchema)), refTypesCheck(), choiceOptionsCheck(), scalarValidationCheck(), literalSeedCheck())), ClaimFieldSchema = pinned()(v.strictObject({
     type: v.literal("claim"),
     name: FieldEntryName,
     title: v.optional(v.string()),
@@ -1681,17 +2218,25 @@ const TodoListFieldSchema = pinned()(v.strictObject(listSugarFields("todoList"))
     with: v.optional(v.record(NonEmpty, ConditionSchema)),
     context: v.optional(v.record(NonEmpty, ConditionSchema)),
     onExit: v.optional(picklist([ "detach", "abort" ]))
-}), ActionParamSchema = v.strictObject({
+}), ActionParamSchema = v.pipe(v.strictObject({
     type: picklist([ "string", "number", "boolean", "url", "dateTime", "actor", "doc.ref", "doc.refs", "json" ]),
     name: NonEmpty,
     title: v.optional(v.string()),
     description: v.optional(v.string()),
-    required: v.optional(v.boolean())
-});
+    required: v.optional(v.boolean()),
+    options: v.optional(ChoiceOptionsSchema),
+    validation: v.optional(ScalarValidationSchema)
+}), choiceOptionsCheck(), scalarValidationCheck());
+
+function hasUniqueSemanticNamespaces(semantics) {
+    const namespaces = semantics.map(semantic => semantic.split(".", 1)[0]);
+    return new Set(namespaces).size === namespaces.length;
+}
 
 function actionFields(op, group) {
     return {
         name: NonEmpty,
+        semantics: v.optional(v.pipe(v.array(picklist(ACTION_SEMANTICS)), v.minLength(1, "declare at least one semantic, or omit `semantics`"), v.check(hasUniqueSemanticNamespaces, "declare at most one semantic from each namespace"))),
         title: v.optional(v.string()),
         description: v.optional(v.string()),
         group: v.optional(group),
@@ -1828,7 +2373,8 @@ const StoredStageSchema = pinned()(v.strictObject(stageFields({
 function startFields(kind) {
     return {
         kind: kind,
-        filter: v.optional(ConditionSchema)
+        filter: v.optional(ConditionSchema),
+        allowed: v.optional(ConditionSchema)
     };
 }
 
@@ -1879,31 +2425,13 @@ function startKindOf(definition) {
 }
 
 function isSubjectEntry(entry) {
-    return entry.required === !0 && (entry.type === "doc.ref" || entry.type === "doc.refs");
+    return entry.type === "subject";
 }
 
 function isInputSourced(entry) {
     return entry.initialValue?.type === "input";
 }
 
-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;
-}
-
 function parseOrThrow({schema: schema, input: input, label: label}) {
     const result = v.safeParse(schema, input);
     if (!result.success) throw new Error(formatValidationError(label, issuesFromValibot(result.issues)));
@@ -1932,6 +2460,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) => ({
@@ -2068,6 +2603,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) {
@@ -2138,7 +2677,11 @@ function checkPredicateBody({name: name, groq: groq2, names: names, issues: issu
     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 ],
@@ -2146,24 +2689,35 @@ function checkPredicateBody({name: name, groq: groq2, names: names, issues: issu
     });
 }
 
-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" ] : 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} — 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`;
 }
@@ -2171,7 +2725,7 @@ function callerVarMessage(site, name) {
 function conditionSites(def) {
     const sites = [], workflowLayer = {
         scope: "workflow",
-        names: entryNames(def.fields)
+        entries: entryMap(def.fields)
     };
     collectEditableSites({
         entries: def.fields,
@@ -2192,10 +2746,10 @@ 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.when,
@@ -2209,6 +2763,7 @@ function collectStageConditionSites({stage: stage, i: i, workflowLayer: workflow
         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({
@@ -2216,23 +2771,28 @@ 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
+        } : {}
     });
 }
 
@@ -2244,14 +2804,15 @@ function collectOpWhereSites({ops: ops, path: path, label: label, policy: policy
         ...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 ];
     activity.filter !== void 0 && sites.push({
         groq: activity.filter,
@@ -2277,11 +2838,12 @@ function collectActivityConditionSites({activity: activity, path: path, stageFie
         activity: activity,
         path: path,
         fields: fields,
+        workflowLayer: workflowLayer,
         sites: sites
     });
 }
 
-function collectActionConditionSites({activity: activity, path: path, 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({
@@ -2316,12 +2878,13 @@ function collectActionConditionSites({activity: activity, path: path, fields: fi
             action: action,
             path: actionPath,
             fields: fields,
+            workflowLayer: workflowLayer,
             sites: sites
         });
     }
 }
 
-function collectSpawnSites({action: action, path: path, fields: fields, sites: sites}) {
+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" ];
@@ -2330,13 +2893,17 @@ function collectSpawnSites({action: action, path: path, fields: fields, sites: s
         path: [ ...spawnPath, "forEach" ],
         label: `action "${action.name}".spawn.forEach`,
         policy: "cascade",
-        fields: fields
+        fields: [ workflowLayer ],
+        windowNote: "spawn.forEach evaluates against workflow-scope $fields only — stage/activity fields are never bound at discovery time"
     });
-    for (const [group, record] of [ [ "with", spawn.with ], [ "context", spawn.context ] ]) for (const [key, groq2] of Object.entries(record ?? {})) sites.push({
+    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
     });
 }
@@ -2360,6 +2927,52 @@ function checkAssigneesEntries(def, issues) {
     });
 }
 
+function nestedSubjectPaths(shapes, base) {
+    return (shapes ?? []).flatMap((shape, i) => isSubjectEntry(shape) ? [ [ ...base, i, "type" ] ] : [ ...nestedSubjectPaths(shape.fields, [ ...base, i, "fields" ]), ...nestedSubjectPaths(shape.of, [ ...base, i, "of" ]) ]);
+}
+
+function checkSubjectEffectOutputs(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()) pushSubjectOutputIssues({
+        action: action,
+        path: [ "stages", i, "activities", j, "actions", a ],
+        issues: issues
+    });
+}
+
+function pushSubjectOutputIssues(args) {
+    const {action: action, path: path, issues: issues} = args;
+    for (const [e, effect] of (action.effects ?? []).entries()) {
+        const base = [ ...path, "effects", e, "outputs" ];
+        for (const nestedPath of nestedSubjectPaths(effect.outputs, base)) issues.push({
+            path: nestedPath,
+            message: `effect "${effect.name}" declares a \`subject\` output shape — no subject reader ever looks at effect outputs. Declare \`doc.ref\` for a document-valued output`
+        });
+    }
+}
+
+function checkSubjectEntries(def, issues) {
+    for (const {entries: entries, scope: scope, path: path, label: label} of fieldScopes(def)) {
+        const subjects = (entries ?? []).flatMap((entry, n) => isSubjectEntry(entry) ? [ {
+            entry: entry,
+            n: n
+        } ] : []);
+        if (scope !== "workflow") for (const {entry: entry, n: n} of subjects) issues.push({
+            path: [ ...path, n, "type" ],
+            message: `${label} entry "${entry.name}" is a \`subject\` — the subject names the document the WORKFLOW is about, so it is valid only on a workflow-scope entry. Declare \`doc.ref\` for a plain reference here`
+        }); else for (const {n: n} of subjects.slice(1)) issues.push({
+            path: [ ...path, n ],
+            message: "at most one subject-kind field entry per workflow — the runtime identifies THE subject by kind, and a second one makes it ambiguous"
+        });
+        for (const [n, entry] of (entries ?? []).entries()) {
+            const nested = [ ...nestedSubjectPaths(entry.fields, [ ...path, n, "fields" ]), ...nestedSubjectPaths(entry.of, [ ...path, n, "of" ]) ];
+            for (const nestedPath of nested) issues.push({
+                path: nestedPath,
+                message: `${label} entry "${entry.name}" declares a \`subject\` sub-field — a nested subject can never be read as the workflow's subject. Declare \`doc.ref\` for a nested reference`
+            });
+        }
+    }
+}
+
 function checkActivityTerminalPaths(def, issues) {
     for (const [i, stage] of def.stages.entries()) {
         const resolvable = terminallyResolvableActivities(stage);
@@ -2410,23 +3023,69 @@ 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), def.start.kind === "autonomous")) for (const [n, entry] of (def.fields ?? []).entries()) entry.required !== !0 || isSubjectEntry(entry) || issues.push({
+    }), checkStartFilterReads(def, issues), checkStartAllowedReads(def, issues), checkStartSubjectVariable(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`
+        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 the workflow's subject. Make it optional, seed it another way (query/literal), or declare it the \`subject\` entry (the document the run is about)`
     });
 }
 
+function checkStartSubjectVariable(def, issues) {
+    const subject = (def.fields ?? []).find(isSubjectEntry);
+    for (const [key, condition] of [ [ "filter", def.start?.filter ], [ "allowed", def.start?.allowed ] ]) if (condition !== void 0 && conditionParameterNames(condition).has(SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR)) {
+        if (subject === void 0) {
+            issues.push({
+                path: [ "start", key ],
+                message: `start.${key} reads $${SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR}, but the definition declares no \`subject\` entry — the engine has no prospective subject identity to match. Declare a \`subject\` entry (the document the workflow is about), or remove the variable`
+            });
+            continue;
+        }
+        key === "allowed" && !isInputSourced(subject) && issues.push({
+            path: [ "start", key ],
+            message: `start.allowed reads $${SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR}, but the definition's subject entry "${subject.name}" is not \`input\`-sourced — the start gate cannot bind its prospective subject. Make the subject input-sourced, or remove the variable`
+        });
+    }
+}
+
 function checkStartFilterReads(def, issues) {
     const filter = def.start?.filter;
-    if (filter === void 0) return;
-    const bindable = new Set((def.fields ?? []).filter(isInputSourced).map(entry => entry.name)), declared = new Set((def.fields ?? []).map(entry => entry.name));
-    for (const name of conditionFieldReadNames(filter)) bindable.has(name) || issues.push({
+    filter !== void 0 && (conditionParameterNames(filter).has("fields") && issues.push({
         path: [ "start", "filter" ],
-        message: declared.has(name) ? `start.filter reads $fields.${name}, but "${name}" is not an \`input\`-sourced entry — $fields binds only the caller's input entries (query/literal/fieldRead entries resolve at materialisation, after any read-side evaluation), so the read is GROQ null and the filter silently never passes. Bindable (input) fields: ${knownList(bindable)}` : `start.filter reads $fields.${name}, but no workflow-scope field entry named "${name}" is declared — $fields binds only the caller's input entries, so the read is GROQ null and the filter silently never passes. Bindable (input) fields: ${knownList(bindable)}`
-    });
-    readsRootDocument(filter) && !(def.fields ?? []).some(isSubjectEntry) && issues.push({
+        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 the filter could never pass. Declare a required subject entry, or gate on $fields / the dataset instead"
+        message: "start.filter reads the candidate document (its root), but the definition declares no `subject` entry — 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 `subject` entry (the document the workflow is about), 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"
     });
 }
 
@@ -2537,39 +3196,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, groq2] of Object.entries(def.predicates ?? {})) for (const read of conditionFieldReadNames(groq2)) 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) {
@@ -2671,7 +3371,7 @@ function checkFieldReadOpValues(def, issues) {
         ops: site.ops,
         path: site.path,
         label: site.label,
-        activityNames: entryNames(site.activity.fields)
+        activityEntries: site.activity.fields ?? []
     });
 }
 
@@ -2691,8 +3391,11 @@ 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: "activity",
+        entries: activityEntries
+    }, {
         scope: "stage",
         entries: stageEntries
     }, {
@@ -2705,8 +3408,7 @@ function checkOpFieldRead({read: read, where: where, path: path, workflowEntries
             message: opFieldReadMissMessage({
                 read: read,
                 where: where,
-                hosts: hosts,
-                activityNames: activityNames
+                hosts: hosts
             })
         });
         return;
@@ -2720,9 +3422,9 @@ 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}`));
-    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 opFieldReadMissMessage({read: read, where: where, hosts: hosts}) {
+    const searched = read.scope === void 0 ? "activity, stage, or workflow scope" : `${read.scope} scope`, 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. Known: ${known.join(", ") || "(none)"}`;
 }
 
 function checkUpdateWhereOps(def, issues) {
@@ -2829,11 +3531,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,
@@ -2882,6 +3587,7 @@ const SCALAR = {
         kind: "list",
         item: GDR_VALUE
     }),
+    subject: () => DOC_CONTENT,
     "release.ref": () => RELEASE_VALUE,
     string: () => SCALAR,
     text: () => SCALAR,
@@ -2904,22 +3610,27 @@ const SCALAR = {
         kind: "rows",
         of: shape.of ?? []
     })
+}, START_ALLOWED_VALUE_NODES = {
+    ...VALUE_NODES,
+    "doc.ref": () => GDR_VALUE,
+    subject: () => 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`;
         }
 
@@ -2940,18 +3651,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,
@@ -2966,11 +3683,12 @@ function checkWorkflowInvariants(def) {
         issues: issues
     }), checkEffectNames(def, issues), checkGuardNames(def, issues), checkFieldEntryNames(def, issues), 
     checkRequiredField(def, issues), checkStart(def, issues), checkPredicates(def, issues), 
-    checkUnboundCallerVars(def, issues), checkConditionFieldReads(def, issues), checkFieldReadSeeds(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), 
+    checkAssigneesEntries(def, issues), checkSubjectEntries(def, issues), checkSubjectEffectOutputs(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, DEFAULT_TRANSITION_WHEN, DOCUMENT_VALUE_PERMISSIONS, DRIVER_KINDS, DefinitionInUseError, DefinitionNotFoundError, EFFECTS_READ, EXECUTOR_CLASSIFICATIONS, EffectNotFoundError, EffectSchema, FIELD_READ, FILTER_SCOPE_VARS, FieldValueShapeError, GROUP_KINDS, GUARD_PREDICATE_VARS, GroupSchema, InstanceNotFoundError, RESERVED_CONDITION_VARS, RESOURCE_ALIAS_NAME_SOURCE, 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, formatIssuePath, formatIssues, formatValidationError, gdrFromResource, gdrRef, gdrResourcePrefix, gdrUri, groq, groupMembershipNames, isBareSeedId, isCascadeFired, isGdr, isGdrUri, isGuardReadExpr, isInputSourced, isNotesEntry, isStartableDefinition, isSubjectEntry, isTerminalActivityStatus, isTodoListEntry, isTodoListItem, isUnevaluable, labelFor, parseGdr, parseOrThrow, parseResourceGdr, parseStoredDefinition, readsRootDocument, refCanvas, refDashboard, refDataset, refMediaLibrary, refTypeIssues, rejectedRefTypes, releaseDocId, releaseRef, resourceAliasesToMap, resourceFromGdrUri, resourceFromParsed, resourceGdr, rethrowWithContext, runGroq, sameResource, selfGdr, startKindOf, tagScopeFilter, toBareId, toPhysicalGdr, tryParseGdr, validateFieldAppendItem, validateFieldValue, validateResourceAliasName, validateTag };
+export { ACTION_SEMANTICS, ACTIVITY_KINDS, ACTIVITY_STATUSES, ACTOR_KINDS, ActorShape, AuthoringActionSchema, AuthoringActivitySchema, AuthoringFieldEntrySchema, AuthoringGuardSchema, AuthoringOpSchema, AuthoringStageSchema, AuthoringTransitionSchema, AuthoringWorkflowSchema, CALLER_BOUND_VARS, CONDITION_VARS, ContractViolationError, DATA_MODEL_CHANGES, DATA_MODEL_MIN_READER, DATA_MODEL_VERSION, 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, ModelVersionAheadError, NonEmptyString, PersistedDocShapeError, READER_MODEL_ROLLOUT_URL, RESERVED_CONDITION_VARS, RESOURCE_ALIAS_NAME_SOURCE, ReaderModelAcknowledgementError, START_ALLOWED_VARS, START_FILTER_VARS, SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR, SpawnContractsInvalidError, StoredFieldOpSchema, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, WorkflowConfigSchema, WorkflowError, actorFulfillsRole, andConditions, assertReadableModel, assertReaderModelAcknowledgement, checkFieldValue, checkWorkflowInvariants, choiceValueIssues, clientConfigFromResource, conditionEffectReads, conditionFieldReadNames, conditionParameterNames, conditionSyntaxIssues, datasetResourceParts, definitionDocId, deriveActivityKind, deriveExecutorClassification, desugarWorkflow, driverKind, errorMessage, evaluateCondition, evaluateConditionOutcome, evaluatePredicates, extractDocumentId, fieldTreeShape, fieldValueSchemas, formatIssuePath, formatIssues, formatValidationError, gdrFromResource, gdrRef, gdrResourcePrefix, gdrUri, groq, groupMembershipNames, isBareSeedId, isCascadeFired, isGdr, isGdrUri, isGuardReadExpr, isInputSourced, isNotesEntry, isParseableInstant, isSingleDocRefEntry, isSingleDocRefKind, isStartableDefinition, isSubjectEntry, isTerminalActivityStatus, isTodoListEntry, isTodoListItem, isUnevaluable, isUnprimed, labelFor, minReaderModelOf, modelStampFor, modelVersionOf, parentRef, parseDefinitionSnapshot, parseGdr, parseOrThrow, parsePersistedDoc, parseResourceGdr, parseStoredDefinition, readsRootDocument, refCanvas, refDashboard, refDataset, refKindAcceptsTypes, refMediaLibrary, refTypeIssues, rejectedRefTypes, releaseDocId, releaseRef, requiredModelFeatures, requiredReaderModel, resourceAliasesToMap, resourceFromGdrUri, resourceFromParsed, resourceGdr, rethrowWithContext, runGroq, sameResource, scalarValidationIssues, schemaTreeShape, selfGdr, startKindOf, tagScopeFilter, terminalState, toBareId, toPhysicalGdr, tolerantEntries, tolerantObject, tryParseGdr, validateFieldAppendItem, validateFieldValue, validateResourceAliasName, validateTag };