@sanity/workflow-engine 0.17.0 → 0.18.0

package/dist/index.js

@@ -1,12 +1,12 @@
-import { rethrowWithContext, andConditions, deriveActivityKind, CALLER_BOUND_VARS, CONDITION_VARS, isSubjectEntry, isUnevaluable, ContractViolationError, isStartableDefinition, conditionFieldReadNames, conditionParameterNames, START_FILTER_VARS, START_ALLOWED_VARS, gdrFromResource, selfGdr, isGdr, actorFulfillsRole, toBareId, WorkflowError, sameResource, resourceFromParsed, tryParseGdr, isTerminalActivityStatus, errorMessage, validateFieldValue, validateFieldAppendItem, evaluateCondition, StoredFieldOpSchema, formatIssues, conditionSyntaxIssues, checkWorkflowInvariants, formatIssuePath, isGuardReadExpr, conditionEffectReads, EFFECTS_READ, datasetResourceParts, evaluatePredicates, WORKFLOW_DEFINITION_TYPE, tagScopeFilter, isCascadeFired, runGroq, parseGdr, isGdrUri, gdrRef, isInputSourced, checkFieldValue, toPhysicalGdr, isBareSeedId, tolerantEntries, NonEmptyString, FIELD_VALUE_KINDS, tolerantObject, ActorShape, IsoTimestamp, ACTIVITY_STATUSES, GdrShape, DRIVER_KINDS, FIELD_SCOPES, fieldValueSchemas, parsePersistedDoc, InstanceNotFoundError, evaluateConditionOutcome, FIELD_READ, MUTATION_GUARD_ACTIONS, resourceGdr, resourceFromGdrUri, refTypeIssues, rejectedRefTypes, DOCUMENT_VALUE_PERMISSIONS, deriveExecutorClassification, validateTag, driverKind, EffectNotFoundError, extractDocumentId, parseStoredDefinition, labelFor, DefinitionNotFoundError, definitionDocId, validateResourceAliasName, gdrResourcePrefix, RESOURCE_ALIAS_NAME_SOURCE, DefinitionInUseError, FieldValueShapeError, isParseableInstant, groupMembershipNames } from "./_chunks-es/invariants.js";
+import { terminalState, andConditions, deriveActivityKind, parseDefinitionSnapshot, CALLER_BOUND_VARS, START_ALLOWED_VARS, CONDITION_VARS, SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR, isSubjectEntry, isUnevaluable, ContractViolationError, isStartableDefinition, conditionFieldReadNames, rethrowWithContext, conditionParameterNames, isGdr, WORKFLOW_INSTANCE_TYPE, START_FILTER_VARS, gdrFromResource, selfGdr, isSingleDocRefKind, parentRef, actorFulfillsRole, toBareId, WorkflowError, sameResource, resourceFromParsed, tryParseGdr, isTerminalActivityStatus, errorMessage, validateFieldValue, validateFieldAppendItem, evaluateCondition, isSingleDocRefEntry, choiceValueIssues, scalarValidationIssues, StoredFieldOpSchema, formatIssues, conditionSyntaxIssues, checkWorkflowInvariants, formatIssuePath, isGuardReadExpr, conditionEffectReads, EFFECTS_READ, datasetResourceParts, evaluatePredicates, WORKFLOW_DEFINITION_TYPE, tagScopeFilter, isCascadeFired, runGroq, parseGdr, isGdrUri, gdrRef, isInputSourced, checkFieldValue, toPhysicalGdr, isBareSeedId, tolerantEntries, NonEmptyString, FIELD_VALUE_KINDS, tolerantObject, ActorShape, IsoTimestamp, ACTIVITY_STATUSES, GdrShape, DRIVER_KINDS, FIELD_SCOPES, fieldValueSchemas, parsePersistedDoc, assertReadableModel, InstanceNotFoundError, modelStampFor, evaluateConditionOutcome, FIELD_READ, MUTATION_GUARD_ACTIONS, resourceGdr, minReaderModelOf, resourceFromGdrUri, refTypeIssues, rejectedRefTypes, DOCUMENT_VALUE_PERMISSIONS, deriveExecutorClassification, validateTag, driverKind, EffectNotFoundError, extractDocumentId, parseStoredDefinition, validateResourceAliasName, labelFor, DefinitionNotFoundError, definitionDocId, SpawnContractsInvalidError, gdrResourcePrefix, RESOURCE_ALIAS_NAME_SOURCE, isUnprimed, DefinitionInUseError, assertReaderModelAcknowledgement, FieldValueShapeError, isParseableInstant, groupMembershipNames } from "./_chunks-es/invariants.js";
 
-import { ACTIVITY_KINDS, ACTOR_KINDS, DEFAULT_TRANSITION_WHEN, EXECUTOR_CLASSIFICATIONS, FILTER_SCOPE_VARS, GROUP_KINDS, GUARD_PREDICATE_VARS, PersistedDocShapeError, RESERVED_CONDITION_VARS, clientConfigFromResource, gdrUri, isNotesEntry, isTodoListEntry, isTodoListItem, parseResourceGdr, readsRootDocument, refCanvas, refDashboard, refDataset, refMediaLibrary, releaseDocId, releaseRef, resourceAliasesToMap, schemaTreeShape, startKindOf } from "./_chunks-es/invariants.js";
+import { ACTION_SEMANTICS, ACTIVITY_KINDS, ACTOR_KINDS, DATA_MODEL_CHANGES, DATA_MODEL_MIN_READER, DATA_MODEL_VERSION, DEFAULT_TRANSITION_WHEN, EXECUTOR_CLASSIFICATIONS, FILTER_SCOPE_VARS, GROUP_KINDS, GUARD_PREDICATE_VARS, ModelVersionAheadError, PersistedDocShapeError, READER_MODEL_ROLLOUT_URL, RESERVED_CONDITION_VARS, ReaderModelAcknowledgementError, clientConfigFromResource, fieldTreeShape, gdrUri, isNotesEntry, isTodoListEntry, isTodoListItem, modelVersionOf, parseResourceGdr, readsRootDocument, refCanvas, refDashboard, refDataset, refKindAcceptsTypes, refMediaLibrary, releaseDocId, releaseRef, requiredModelFeatures, requiredReaderModel, resourceAliasesToMap, schemaTreeShape, startKindOf } from "./_chunks-es/invariants.js";
 
 import { atomNode, dedupeBy, analyzeCondition, atomReadsDataset, checklistLines as checklistLines$1, phrase, quoted, listAnd, describeAtom as describeAtom$1, describeCondition as describeCondition$1, guillemets, formatValue, humanize, listOr, scopeReadOf, describeRead, explainCondition, dedupeReads, whatIfCondition, MAX_COUNTERFACTUAL_INDEX } from "@sanity/groq-condition-describe";
 
 import { MAX_COUNTERFACTUAL_INDEX as MAX_COUNTERFACTUAL_INDEX2, analyzeCondition as analyzeCondition2, atomReadsDataset as atomReadsDataset2, explainCondition as explainCondition2, formatRead, guillemets as guillemets2, humanize as humanize2, isComparisonOp, quoted as quoted2, sentenceCase, whatIfCondition as whatIfCondition2, withAssignment } from "@sanity/groq-condition-describe";
 
-import { parse, evaluate } from "groq-js";
+import { evaluate, parse } from "groq-js";
 
 import * as v from "valibot";
 
@@ -41,28 +41,6 @@ function findCurrentActivityEntry(host, activityName) {
     return findOpenStageEntry(host)?.activities.find(a => a.name === activityName);
 }
 
-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 parseDefinitionSnapshot(instance) {
-    try {
-        return JSON.parse(instance.definitionSnapshot);
-    } catch (err) {
-        rethrowWithContext(err, `Failed to parse definitionSnapshot on instance "${instance._id}"`);
-    }
-}
-
-function parentRef(instance) {
-    return instance.ancestors.at(-1);
-}
-
 function effectiveEditable(baseline, override) {
     if (baseline === void 0) return;
     if (override === void 0) return baseline;
@@ -102,6 +80,9 @@ function resolveFieldSite(site, stage) {
         ...site.entry.title !== void 0 ? {
             title: site.entry.title
         } : {},
+        ...site.entry.validation !== void 0 ? {
+            validation: site.entry.validation
+        } : {},
         ref: {
             scope: site.scope,
             field: site.entry.name
@@ -189,14 +170,8 @@ function editDisabledReason(args) {
         kind: "not-editable"
     };
     if (!window.open) {
-        const terminal = terminalState(instance);
-        return terminal === "aborted" && instance.abortedAt !== void 0 ? {
-            kind: "instance-aborted",
-            abortedAt: instance.abortedAt
-        } : terminal === "completed" && instance.completedAt !== void 0 ? {
-            kind: "instance-completed",
-            completedAt: instance.completedAt
-        } : {
+        const terminalReason = instanceTerminalReason(instance);
+        return terminalReason !== void 0 ? terminalReason : {
             kind: "edit-window-closed",
             detail: window.detail ?? "closed"
         };
@@ -208,6 +183,18 @@ function editDisabledReason(args) {
     };
 }
 
+function instanceTerminalReason(instance) {
+    const terminal = terminalState(instance);
+    if (terminal === "aborted" && instance.abortedAt !== void 0) return {
+        kind: "instance-aborted",
+        abortedAt: instance.abortedAt
+    };
+    if (terminal === "completed" && instance.completedAt !== void 0) return {
+        kind: "instance-completed",
+        completedAt: instance.completedAt
+    };
+}
+
 function defineWorkflowEvent(options) {
     return {
         type: "log",
@@ -847,13 +834,13 @@ const checklistLines = checklistLines$1;
 function toGroqDescribeContext(ctx) {
     return {
         renderRead: read => renderWorkflowRead(read, ctx),
-        renderRequirement: workflowRequirement,
+        renderRequirement: requirement => workflowRequirement(requirement, ctx),
         atomPatterns: [ rolesGateText, claimGateText ],
         nowParam: "now"
     };
 }
 
-const VAR_LABELS = new Map(CONDITION_VARS.map(entry => [ entry.name, entry.label ]));
+const VAR_LABELS = new Map([ ...START_ALLOWED_VARS, ...CONDITION_VARS ].map(entry => [ entry.name, entry.label ]));
 
 function renderWorkflowRead(read, ctx) {
     if (read.variable === "fields" && typeof read.path[0] == "string") {
@@ -893,7 +880,7 @@ function renderWorkflowRead(read, ctx) {
     });
 }
 
-function workflowRequirement(requirement) {
+function workflowRequirement(requirement, ctx) {
     const {target: target} = requirement, clause = clauseVarRequirement(requirement);
     if (clause !== void 0) return clause;
     if (target.variable === "assigned" && target.path.length === 0) {
@@ -906,7 +893,7 @@ function workflowRequirement(requirement) {
             text: "you must not be assigned to this activity"
         });
     }
-    if (target.variable === "effectStatus" && typeof target.path[0] == "string") return effectStatusPhrase(requirement, target.path[0]);
+    return effectStatusPhrase(requirement, ctx);
 }
 
 function clauseVarRequirement(requirement) {
@@ -926,28 +913,40 @@ function clauseVarRequirement(requirement) {
             params: {},
             text: "no activity in this stage may have failed"
         });
+        if (target.variable === SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR) return kind === "truthy" ? phrase("requirement.subject-has-in-flight-instance", {
+            params: {},
+            text: "the subject must already have an in-flight workflow"
+        }) : phrase("requirement.subject-has-no-in-flight-instance", {
+            params: {},
+            text: "the subject must not already have an in-flight workflow"
+        });
     }
 }
 
-function effectStatusPhrase(requirement, effect) {
-    const name = `the ${quoted(effect)} automation`;
+function effectStatusPhrase(requirement, ctx) {
+    const {target: target} = requirement;
+    if (target.variable !== "effectStatus" || typeof target.path[0] != "string") return;
+    const effect = target.path[0], title = effectTitleOf(effect, ctx), name = `the ${quoted(title)} automation`;
     if (requirement.kind === "equals" && requirement.value === "done") return phrase("requirement.effect-done", {
         params: {
-            effect: effect
+            effect: effect,
+            title: title
         },
-        text: `${name} must have completed`
+        text: `${name} must have succeeded`
     });
     if (requirement.kind === "equals" && requirement.value === "failed") return phrase("requirement.effect-failed", {
         params: {
-            effect: effect
+            effect: effect,
+            title: title
         },
         text: `${name} must have failed`
     });
     if (requirement.kind === "defined") return phrase("requirement.effect-settled", {
         params: {
-            effect: effect
+            effect: effect,
+            title: title
         },
-        text: `${name} must have settled`
+        text: `${name} must have finished`
     });
 }
 
@@ -1235,12 +1234,16 @@ const WAIT_TEXTS = {
         },
         text: `waits on editor content matching ${quoted(wait.condition)}`
     }),
-    effect: wait => phrase("autonomy-wait.effect", {
-        params: {
-            effect: wait.effect
-        },
-        text: `waits on the ${quoted(wait.effect)} automation`
-    }),
+    effect: (wait, ctx) => {
+        const title = effectTitleOf(wait.effect, ctx);
+        return phrase("autonomy-wait.effect", {
+            params: {
+                effect: wait.effect,
+                title: title
+            },
+            text: `waits on the ${quoted(title)} automation`
+        });
+    },
     "start-input": (wait, ctx) => {
         const title = fieldTitleOf({
             path: [ wait.field ]
@@ -1353,6 +1356,10 @@ function actionTitle(site, ctx) {
     return ctx.definition.stages.flatMap(stage => stage.activities ?? []).filter(activity => activity.name === site.activity).flatMap(activity => activity.actions ?? []).find(candidate => candidate.name === site.action)?.title ?? humanize(site.action);
 }
 
+function effectTitleOf(name, ctx) {
+    return findEffect(ctx.definition, name)?.title ?? name;
+}
+
 function conditionSitesOf(definition) {
     const sites = [];
     for (const [predicate, condition] of Object.entries(definition.predicates ?? {})) sites.push({
@@ -1480,25 +1487,17 @@ async function applicableDefinitions(args) {
 }
 
 async function evaluateStartFilter(args) {
-    const {filter: filter, definition: definition, document: document, scope: scope} = args;
-    let parsed;
-    try {
-        parsed = {
-            tree: parse(filter),
-            needsDataset: analyzeCondition(filter).readsDataset
-        };
-    } catch (err) {
-        rethrowNamingDefinition({
-            err: err,
-            definition: definition,
-            key: "filter"
-        });
-    }
-    let dataset = [];
-    if (parsed.needsDataset) {
-        if (scope?.fetchDataset === void 0) return !1;
-        dataset = await scope.fetchDataset();
-    }
+    const {filter: filter, definition: definition, document: document, scope: scope} = args, parsed = parseStartFilter({
+        filter: filter,
+        definition: definition
+    });
+    assertFilterSubject({
+        readsSubject: parsed.readsSubject,
+        definition: definition,
+        scope: scope
+    });
+    const dataset = await filterDataset(parsed.needsDataset, scope);
+    if (dataset === void 0) return !1;
     try {
         const result = await (await evaluate(parsed.tree, {
             ...document !== void 0 ? {
@@ -1507,7 +1506,8 @@ async function evaluateStartFilter(args) {
             dataset: dataset,
             params: startContextParams({
                 definition: definition,
-                scope: scope
+                scope: scope,
+                dataset: dataset
             })
         })).get();
         return isUnevaluable(result) ? !1 : !!result;
@@ -1520,11 +1520,38 @@ async function evaluateStartFilter(args) {
     }
 }
 
+function parseStartFilter(args) {
+    const {filter: filter, definition: definition} = args;
+    try {
+        const readsSubject = readsSubjectHasInFlightInstance(filter);
+        return {
+            tree: parse(filter),
+            needsDataset: analyzeCondition(filter).readsDataset || readsSubject,
+            readsSubject: readsSubject
+        };
+    } catch (err) {
+        rethrowNamingDefinition({
+            err: err,
+            definition: definition,
+            key: "filter"
+        });
+    }
+}
+
+function assertFilterSubject(args) {
+    if (!(!args.readsSubject || args.scope?.subject !== void 0)) throw new ContractViolationError(`start.filter on definition "${args.definition.name ?? "<unnamed>"}" reads $${SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR}, but the caller supplied no resource-qualified \`scope.subject\` — a loaded document alone cannot identify its project and dataset.`);
+}
+
+async function filterDataset(needsDataset, scope) {
+    if (!needsDataset) return [];
+    if (scope?.fetchDataset !== void 0) return scope.fetchDataset();
+}
+
 async function explainStartAllowed(args) {
     const {allowed: allowed, definition: definition, fields: fields, scope: scope} = args;
     let needsDataset;
     try {
-        needsDataset = analyzeCondition(allowed).readsDataset;
+        needsDataset = analyzeCondition(allowed).readsDataset || readsSubjectHasInFlightInstance(allowed);
     } catch (err) {
         rethrowNamingDefinition({
             err: err,
@@ -1544,7 +1571,8 @@ async function explainStartAllowed(args) {
             params: startContextParams({
                 definition: definition,
                 scope: scope,
-                fields: fields
+                fields: fields,
+                dataset: dataset
             })
         });
     } catch (err) {
@@ -1560,11 +1588,23 @@ function unboundAllowedReads(allowed, fields) {
     return [ ...conditionFieldReadNames(allowed) ].filter(name => !Object.hasOwn(fields, name));
 }
 
+function unboundAllowedReadsWithSubject(args) {
+    const {allowed: allowed, fields: fields, definition: definition} = args, subjectField = (definition.fields ?? []).find(isSubjectEntry)?.name, reads = unboundAllowedReads(allowed, fields);
+    return subjectField !== void 0 && readsSubjectHasInFlightInstance(allowed) && !Object.hasOwn(fields, subjectField) && !reads.includes(subjectField) && reads.push(subjectField), 
+    reads;
+}
+
 function rethrowNamingDefinition({err: err, definition: definition, key: key}) {
-    rethrowWithContext(err, `start.${key} on definition "${definition.name ?? "<unnamed>"}" failed to evaluate (deploy validation rejects this — was the definition written around it?)`);
+    rethrowWithContext(err, `start.${key} on definition "${definition.name ?? "<unnamed>"}" failed to evaluate (check the predicate and its evaluation inputs)`);
 }
 
-function startContextParams({definition: definition, scope: scope, fields: fields}) {
+function startContextParams({definition: definition, scope: scope, fields: fields, dataset: dataset}) {
+    const subject = fields === void 0 ? scope?.subject : startSubject(definition, fields) ?? scope?.subject, params = baseStartParams(definition, scope);
+    return fields !== void 0 && (params.fields = fields), subject !== void 0 && (params[SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR] = subjectHasInFlightInstance(dataset, subject)), 
+    params;
+}
+
+function baseStartParams(definition, scope) {
     return {
         ...definition.name !== void 0 ? {
             definition: definition.name
@@ -1574,13 +1614,33 @@ function startContextParams({definition: definition, scope: scope, fields: field
         } : {},
         ...scope?.now !== void 0 ? {
             now: scope.now
-        } : {},
-        ...fields !== void 0 ? {
-            fields: fields
         } : {}
     };
 }
 
+function readsSubjectHasInFlightInstance(groq) {
+    return conditionParameterNames(groq).has(SUBJECT_HAS_IN_FLIGHT_INSTANCE_VAR);
+}
+
+function startSubject(definition, fields) {
+    const subjectEntry = (definition.fields ?? []).find(isSubjectEntry);
+    if (subjectEntry === void 0) return;
+    const value = fields[subjectEntry.name];
+    return isGdr(value) ? value.id : void 0;
+}
+
+function subjectHasInFlightInstance(dataset, subject) {
+    return dataset.some(row => {
+        if (typeof row != "object" || row === null) return !1;
+        const instance = row;
+        return instance._type !== WORKFLOW_INSTANCE_TYPE || instance.completedAt !== void 0 || !Array.isArray(instance.fields) ? !1 : instance.fields.some(entry => {
+            if (typeof entry != "object" || entry === null) return !1;
+            const field = entry;
+            return field._type === "subject" && isGdr(field.value) && field.value.id === subject;
+        });
+    });
+}
+
 async function evaluateDeclaredStartFilter(args) {
     const {definition: definition, document: document, scope: scope} = args, filter = definition.start?.filter;
     return filter === void 0 ? !0 : evaluateStartFilter({
@@ -1716,9 +1776,9 @@ function overlayInstanceInSnapshot(snapshot, instance) {
 
 function resolveFieldRead(args) {
     const {kind: kind, value: value, path: path, snapshot: snapshot, targetKind: targetKind} = args;
-    if (kind === "doc.ref") {
+    if (isSingleDocRefKind(kind)) {
         if (!isGdr(value)) return null;
-        if (path === void 0 && targetKind === "doc.ref") return value;
+        if (path === void 0 && targetKind !== void 0 && isSingleDocRefKind(targetKind)) return value;
         const base = derefBase(value, snapshot);
         return path === void 0 ? base : walkDocPath(base, path);
     }
@@ -1891,7 +1951,7 @@ function instanceDocId(tag) {
 
 function mapFieldRefValues(args) {
     const {entryType: entryType, value: value, fields: fields, of: of, mapRef: mapRef} = args;
-    return value == null ? value : entryType === "doc.ref" || entryType === "release.ref" ? mapRef(value) : entryType === "doc.refs" ? mapItems(value, mapRef) : entryType === "object" ? mapRowRefValues({
+    return value == null ? value : isSingleDocRefKind(entryType) || entryType === "release.ref" ? mapRef(value) : entryType === "doc.refs" ? mapItems(value, mapRef) : entryType === "object" ? mapRowRefValues({
         row: value,
         shapes: fields ?? [],
         mapRef: mapRef
@@ -2097,6 +2157,27 @@ class RequiredFieldNotProvidedError extends WorkflowError {
     }
 }
 
+class InitialFieldsInvalidError extends WorkflowError {
+    definition;
+    issues;
+    constructor(args) {
+        const where = args.definition === void 0 ? "" : ` for workflow "${args.definition}"`, lines = args.issues.map(formatInitialFieldIssue).join(`\n`);
+        super("initial-fields-invalid", `Initial fields${where} contain rows the engine cannot consume:\n${lines}\nRemove or correct every listed row before retrying.`), 
+        this.name = "InitialFieldsInvalidError", args.definition !== void 0 && (this.definition = args.definition), 
+        this.issues = args.issues;
+    }
+}
+
+function formatInitialFieldIssue(issue) {
+    const row = `  - row ${issue.index}: ${issue.name} (${issue.type})`;
+    if (issue.reason === "duplicate") return `${row} duplicates rows ${issue.duplicateIndexes.join(", ")}`;
+    if (issue.reason === "undeclared") return `${row} is not declared by the workflow`;
+    if (issue.reason === "wrong-kind") return `${row} has the wrong kind; expected ${issue.expectedTypes.join(" or ")}`;
+    if (issue.reason === "not-input") return `${row} is ${issue.source}-sourced, not caller-input-sourced`;
+    const scope = issue.scope === "activity" ? `activity "${issue.activity}" in stage "${issue.stage}"` : `stage "${issue.stage}"`;
+    return `${row} targets ${scope}, not workflow scope (declared as ${issue.declaredType})`;
+}
+
 class WorkflowStateDivergedError extends WorkflowError {
     instanceId;
     guardError;
@@ -2220,10 +2301,28 @@ function validateActionParams({action: action, activityName: activityName, calle
             });
             continue;
         }
-        present && (checkParamType(value, decl) || issues.push({
+        if (!present) continue;
+        if (!checkParamType(value, decl)) {
+            issues.push({
+                param: decl.name,
+                reason: `expected type=${decl.type}, got ${typeof value}`
+            });
+            continue;
+        }
+        const choiceIssues = choiceValueIssues(decl.options, value);
+        choiceIssues !== void 0 && issues.push({
             param: decl.name,
-            reason: `expected type=${decl.type}, got ${typeof value}`
-        }));
+            reason: choiceIssues.join("; ")
+        });
+        const validationIssues = scalarValidationIssues({
+            entryType: decl.type,
+            validation: decl.validation,
+            value: value
+        });
+        validationIssues !== void 0 && issues.push({
+            param: decl.name,
+            reason: validationIssues.join("; ")
+        });
     }
     if (issues.length > 0) throw new ActionParamsInvalidError({
         action: action.name,
@@ -2333,7 +2432,10 @@ function validateEffectOps(ops, effectName) {
     const result = v.safeParse(v.array(StoredFieldOpSchema), ops);
     if (!result.success) throw new EffectOpsInvalidError({
         effect: effectName,
-        issues: formatIssues(result.issues)
+        issues: formatIssues(result.issues, issue => {
+            const path = issue.path;
+            return issue.input === void 0 && path?.at(-2)?.key === "target" && path.at(-1)?.key === "scope" ? "Effect completion field ops require target.scope: 'workflow' | 'stage'." : issue.message;
+        })
     });
     const activityScoped = result.output.find(op => op.target.scope === "activity");
     if (activityScoped !== void 0) throw new EffectOpsInvalidError({
@@ -2414,9 +2516,16 @@ function entryShape(entry) {
         fields: entry.fields
     } : entry._type === "array" ? {
         of: entry.of
-    } : entry._type === "doc.ref" || entry._type === "doc.refs" ? entry.types !== void 0 ? {
+    } : isSingleDocRefEntry(entry) || entry._type === "doc.refs" ? entry.types !== void 0 ? {
         types: entry.types
-    } : {} : {};
+    } : {} : {
+        ...entry.options !== void 0 ? {
+            options: entry.options
+        } : {},
+        ...entry.validation !== void 0 ? {
+            validation: entry.validation
+        } : {}
+    };
 }
 
 function entrySlot(entry) {
@@ -2655,10 +2764,12 @@ function resolveOpValue(args) {
 }
 
 function readEntryFromMutation(ctx, src) {
-    const scopes = src.scope !== void 0 ? [ src.scope ] : [ "stage", "workflow" ], stageEntry = findOpenStageEntry(ctx.mutation);
+    const scopes = src.scope !== void 0 ? [ src.scope ] : [ "activity", "stage", "workflow" ], stageEntry = findOpenStageEntry(ctx.mutation);
     for (const scope of scopes) {
-        const entry = (scope === "workflow" ? ctx.mutation.fields : stageEntry?.fields)?.find(s => s.name === src.field);
-        if (entry !== void 0 && entry.value !== void 0) return entry;
+        let host;
+        scope === "workflow" ? host = ctx.mutation.fields : scope === "stage" ? host = stageEntry?.fields : host = findCurrentActivityEntry(ctx.mutation, ctx.activityName)?.fields;
+        const entry = host?.find(s => s.name === src.field);
+        if (entry !== void 0) return entry;
     }
 }
 
@@ -3099,53 +3210,6 @@ async function assertInstanceWriteAllowed(args) {
     });
 }
 
-const DATA_MODEL_VERSION = 1, DATA_MODEL_MIN_READER = 0, MODEL_STAMP = {
-    modelVersion: DATA_MODEL_VERSION,
-    minReaderModel: DATA_MODEL_MIN_READER
-};
-
-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 requiredReaderModel = minReaderModelOf(doc);
-    if (requiredReaderModel > DATA_MODEL_VERSION) throw new ModelVersionAheadError({
-        documentId: doc._id,
-        documentModelVersion: modelVersionOf(doc),
-        requiredReaderModel: requiredReaderModel
-    });
-    return doc;
-}
-
 async function renderConditionScope(source, opts) {
     const {instance: instance, definition: definition, snapshot: snapshot, now: now} = source, base = buildParams({
         instance: instance,
@@ -3519,7 +3583,7 @@ function instanceWatchesDocument(instance, document) {
 }
 
 function entryDocRefs(entries) {
-    return fieldEntries(entries).flatMap(entry => entry._type === "doc.ref" ? isGdr(entry.value) ? [ entry.value ] : [] : entry._type === "doc.refs" ? Array.isArray(entry.value) ? entry.value.filter(isGdr) : [] : []);
+    return fieldEntries(entries).flatMap(entry => typeof entry._type == "string" && isSingleDocRefKind(entry._type) ? isGdr(entry.value) ? [ entry.value ] : [] : entry._type === "doc.refs" ? Array.isArray(entry.value) ? entry.value.filter(isGdr) : [] : []);
 }
 
 function entryReleaseRefs(entries) {
@@ -3527,7 +3591,7 @@ function entryReleaseRefs(entries) {
 }
 
 function entrySubjectRefs(entries) {
-    return fieldEntries(entries).flatMap(entry => (entry._type === "doc.ref" || entry._type === "release.ref") && isGdr(entry.value) ? [ entry.value ] : []);
+    return fieldEntries(entries).flatMap(entry => (typeof entry._type == "string" && isSingleDocRefKind(entry._type) || entry._type === "release.ref") && isGdr(entry.value) ? [ entry.value ] : []);
 }
 
 function fieldEntries(entries) {
@@ -3550,7 +3614,13 @@ function perspectiveFromReleaseValue(value) {
 
 async function resolveDeclaredFields(args) {
     const {entryDefs: entryDefs, initialFields: initialFields, ctx: ctx, randomKey: randomKey2} = args;
-    if (entryDefs === void 0 || entryDefs.length === 0) return [];
+    if (assertInitialFieldsConsumable({
+        workflowFields: entryDefs ?? [],
+        initialFields: initialFields,
+        ...ctx.definitionName !== void 0 ? {
+            definitionName: ctx.definitionName
+        } : {}
+    }), entryDefs === void 0 || entryDefs.length === 0) return [];
     assertRequiredInputProvided({
         entryDefs: entryDefs,
         initialFields: initialFields,
@@ -3572,6 +3642,83 @@ async function resolveDeclaredFields(args) {
     return out;
 }
 
+function initialFieldIssues(args) {
+    const duplicateIndexes = /* @__PURE__ */ new Map;
+    return args.initialFields.forEach((field, index) => {
+        const key = `${field.name}\0${field.type}`, indexes = duplicateIndexes.get(key) ?? [];
+        indexes.push(index), duplicateIndexes.set(key, indexes);
+    }), args.initialFields.flatMap((field, index) => {
+        const issues = [], indexes = duplicateIndexes.get(`${field.name}\0${field.type}`) ?? [];
+        indexes.length > 1 && issues.push({
+            index: index,
+            name: field.name,
+            type: field.type,
+            reason: "duplicate",
+            duplicateIndexes: indexes.filter(candidate => candidate !== index)
+        });
+        const workflowMatches = args.workflowFields.filter(entry => entry.name === field.name);
+        if (workflowMatches.length > 0) {
+            const exact = workflowMatches.find(entry => entry.type === field.type);
+            return exact === void 0 ? issues.push({
+                index: index,
+                name: field.name,
+                type: field.type,
+                reason: "wrong-kind",
+                expectedTypes: [ ...new Set(workflowMatches.map(entry => entry.type)) ]
+            }) : exact.initialValue?.type !== "input" && issues.push({
+                index: index,
+                name: field.name,
+                type: field.type,
+                reason: "not-input",
+                source: exact.initialValue?.type ?? "working-memory"
+            }), issues;
+        }
+        const scoped = findNonWorkflowDeclaration(args.stages ?? [], field.name);
+        return scoped !== void 0 ? issues.push({
+            index: index,
+            name: field.name,
+            type: field.type,
+            reason: "invalid-scope",
+            ...scoped
+        }) : issues.push({
+            index: index,
+            name: field.name,
+            type: field.type,
+            reason: "undeclared"
+        }), issues;
+    });
+}
+
+function findNonWorkflowDeclaration(stages, name) {
+    for (const stage of stages) {
+        const stageField = stage.fields?.find(entry => entry.name === name);
+        if (stageField !== void 0) return {
+            scope: "stage",
+            stage: stage.name,
+            declaredType: stageField.type
+        };
+        for (const activity of stage.activities ?? []) {
+            const activityField = activity.fields?.find(entry => entry.name === name);
+            if (activityField !== void 0) return {
+                scope: "activity",
+                stage: stage.name,
+                activity: activity.name,
+                declaredType: activityField.type
+            };
+        }
+    }
+}
+
+function assertInitialFieldsConsumable(args) {
+    const issues = initialFieldIssues(args);
+    if (issues.length !== 0) throw new InitialFieldsInvalidError({
+        ...args.definitionName !== void 0 ? {
+            definition: args.definitionName
+        } : {},
+        issues: issues
+    });
+}
+
 function missingRequiredInputs(args) {
     return args.entryDefs.filter(entry => entry.required === !0 && isInputSourced(entry)).filter(entry => {
         const match = suppliedFieldFor(entry, args.initialFields);
@@ -3711,6 +3858,12 @@ function buildResolvedEntry({entry: entry, value: value, _key: _key, now: now})
         ...entry.description !== void 0 ? {
             description: entry.description
         } : {},
+        ...entry.options !== void 0 ? {
+            options: entry.options
+        } : {},
+        ...entry.validation !== void 0 ? {
+            validation: entry.validation
+        } : {},
         value: value,
         ...entry.initialValue?.type === "query" ? {
             resolvedAt: now
@@ -3740,7 +3893,9 @@ async function resolveOneEntry({entry: entry, initialFields: initialFields, ctx:
             value: value,
             types: entry.types,
             fields: entry.fields,
-            of: entry.of
+            of: entry.of,
+            options: entry.options,
+            validation: entry.validation
         });
         return issues !== void 0 ? (ctx.recordDiscard?.({
             field: entry.name,
@@ -3763,7 +3918,9 @@ async function resolveOneEntry({entry: entry, initialFields: initialFields, ctx:
         value: value,
         types: entry.types,
         fields: entry.fields,
-        of: entry.of
+        of: entry.of,
+        options: entry.options,
+        validation: entry.validation
     }), entry.initialValue?.type === "input" && ctx.inputProvenance !== "definition" && assertRefsWithinSurface({
         entryType: entry.type,
         entryName: entry.name,
@@ -3786,8 +3943,8 @@ function fieldMapFromResolved(entries) {
 }
 
 function assertInputValueShape(entry, value) {
-    if (entry.type === "doc.ref") {
-        assertGdrShape(value, `field entry "${entry.name}" (doc.ref)`);
+    if (isSingleDocRefKind(entry.type)) {
+        assertGdrShape(value, `field entry "${entry.name}" (${entry.type})`);
         return;
     }
     if (entry.type === "release.ref") {
@@ -3810,7 +3967,7 @@ function assertGdrShape(value, context) {
 }
 
 function normalizeQueryResult({entryType: entryType, raw: raw, workflowResource: workflowResource}) {
-    return raw == null ? raw : entryType === "doc.ref" ? coerceToGdr(raw, workflowResource) : entryType === "doc.refs" ? Array.isArray(raw) ? raw.map(item => coerceToGdr(item, workflowResource)).filter(v2 => v2 !== null) : [] : raw;
+    return raw == null ? raw : isSingleDocRefKind(entryType) ? coerceToGdr(raw, workflowResource) : entryType === "doc.refs" ? Array.isArray(raw) ? raw.map(item => coerceToGdr(item, workflowResource)).filter(v2 => v2 !== null) : [] : raw;
 }
 
 function coerceGdrShape(raw, workflowResource) {
@@ -3841,11 +3998,21 @@ function coerceToGdr(raw, workflowResource) {
     } : null;
 }
 
-const EFFECT_RUN_STATUSES = [ "done", "failed", "cancelled" ], NonEmpty = NonEmptyString, UnknownRecord = v.record(v.string(), v.unknown()), PersistedFieldShapeSchema = v.lazy(() => v.looseObject(tolerantEntries()({
+const EFFECT_RUN_STATUSES = [ "done", "failed", "cancelled" ], NonEmpty = NonEmptyString, UnknownRecord = v.record(v.string(), v.unknown()), PersistedChoiceOptionsSchema = v.looseObject({
+    list: v.array(v.looseObject({
+        title: v.string(),
+        value: v.union([ v.string(), v.number() ])
+    }))
+}), PersistedScalarValidationSchema = v.looseObject({
+    min: v.optional(v.number()),
+    max: v.optional(v.number())
+}), PersistedFieldShapeSchema = v.lazy(() => v.looseObject(tolerantEntries()({
     type: v.picklist(FIELD_VALUE_KINDS),
     name: NonEmpty,
     title: v.optional(v.string()),
     description: v.optional(v.string()),
+    options: v.optional(PersistedChoiceOptionsSchema),
+    validation: v.optional(PersistedScalarValidationSchema),
     fields: v.optional(v.array(PersistedFieldShapeSchema)),
     of: v.optional(v.array(PersistedFieldShapeSchema))
 }))), ExecutionContextSchema = tolerantObject()({
@@ -3875,6 +4042,8 @@ function fieldArm(kind, value) {
         name: NonEmpty,
         title: v.exactOptional(v.string()),
         description: v.exactOptional(v.string()),
+        options: v.exactOptional(PersistedChoiceOptionsSchema),
+        validation: v.exactOptional(PersistedScalarValidationSchema),
         value: value,
         resolvedAt: v.exactOptional(IsoTimestamp)
     };
@@ -3886,6 +4055,9 @@ const OptionalRefTypes = v.exactOptional(v.array(v.string())), ResolvedFieldEntr
 })), v.looseObject(tolerantEntries()({
     ...fieldArm("doc.refs", fieldValueSchemas["doc.refs"]),
     types: OptionalRefTypes
+})), v.looseObject(tolerantEntries()({
+    ...fieldArm("subject", fieldValueSchemas.subject),
+    types: OptionalRefTypes
 })), v.looseObject(tolerantEntries()(fieldArm("release.ref", fieldValueSchemas["release.ref"]))), v.looseObject(tolerantEntries()(fieldArm("string", fieldValueSchemas.string))), v.looseObject(tolerantEntries()(fieldArm("text", fieldValueSchemas.text))), v.looseObject(tolerantEntries()(fieldArm("number", fieldValueSchemas.number))), v.looseObject(tolerantEntries()(fieldArm("boolean", fieldValueSchemas.boolean))), v.looseObject(tolerantEntries()(fieldArm("date", fieldValueSchemas.date))), v.looseObject(tolerantEntries()(fieldArm("datetime", fieldValueSchemas.datetime))), v.looseObject(tolerantEntries()(fieldArm("url", fieldValueSchemas.url))), v.looseObject(tolerantEntries()(fieldArm("actor", fieldValueSchemas.actor))), v.looseObject(tolerantEntries()(fieldArm("assignee", fieldValueSchemas.assignee))), v.looseObject(tolerantEntries()(fieldArm("assignees", fieldValueSchemas.assignees))), v.looseObject(tolerantEntries()({
     ...fieldArm("object", v.union([ v.null(), UnknownRecord ])),
     fields: v.array(PersistedFieldShapeSchema)
@@ -4211,14 +4383,12 @@ function buildInstanceBase(args) {
         ...actor !== void 0 ? {
             actor: actor
         } : {}
-    }, ...args.extraHistory ?? [] ], history = executionContext !== void 0 ? stampHistoryEntries(entries, executionContext) : entries;
-    return {
+    }, ...args.extraHistory ?? [] ], history = executionContext !== void 0 ? stampHistoryEntries(entries, executionContext) : entries, body = {
         _id: id,
         _type: WORKFLOW_INSTANCE_TYPE,
         _rev: "",
         _createdAt: now,
         _updatedAt: now,
-        ...MODEL_STAMP,
         tag: args.tag,
         workflowResource: args.workflowResource,
         definition: args.definitionName,
@@ -4242,6 +4412,13 @@ function buildInstanceBase(args) {
         startedAt: now,
         lastChangedAt: now
     };
+    return {
+        ...body,
+        ...modelStampFor({
+            documentType: "instance",
+            document: body
+        })
+    };
 }
 
 async function hydrateSnapshot(args) {
@@ -4922,11 +5099,7 @@ function dedupById(guards) {
     return [ ...new Map(guards.map(g => [ g._id, g ])).values() ].sort((a, b) => a._id.localeCompare(b._id));
 }
 
-const GUARD_OWNER = "robot:workflow-engine", GUARD_LIFTED_PREDICATE = "true";
-
-function isGuardLifted(guard) {
-    return guard.predicate === GUARD_LIFTED_PREDICATE;
-}
+const GUARD_OWNER = "robot:workflow-engine";
 
 function resolveGuardRoute(guard, ctx) {
     const targets = resolveIdRefTargets(guard.match.idRefs, ctx);
@@ -5054,15 +5227,30 @@ async function deployStageGuards(args) {
 }
 
 async function retractStageGuards(args) {
+    const observed = [];
+    for (const {client: client, guardId: guardId} of resolvedStageGuardRoutes(args)) {
+        const guard = await client.getDocument(guardId, {
+            tag: REQUEST_TAG.guardRetract
+        });
+        if (guard) {
+            if (guard._rev === void 0) throw new Error(`Cannot retract guard ${guardId}: persisted document has no revision`);
+            observed.push({
+                client: client,
+                guardId: guardId,
+                predicate: guard.predicate,
+                revision: guard._rev
+            });
+        }
+    }
     const live = await committedInstance(args);
-    if (live !== void 0 && !(live.currentStage === args.stageName && live.abortedAt === void 0)) for (const {client: client, guardId: guardId} of resolvedStageGuardRoutes(args)) await client.getDocument(guardId, {
-        tag: REQUEST_TAG.guardRetract
-    }) && await client.patch(guardId).set({
-        predicate: GUARD_LIFTED_PREDICATE
-    }).commit({
-        ...SYNC_COMMIT,
-        tag: REQUEST_TAG.guardRetract
-    });
+    if (live !== void 0 && !(live.currentStage === args.stageName && live.abortedAt === void 0)) for (const {client: client, guardId: guardId, predicate: predicate, revision: revision} of observed) {
+        const revisionCheck = client.patch(guardId).set({
+            predicate: predicate
+        }).ifRevisionId(revision);
+        await client.transaction().patch(revisionCheck).delete(guardId).commit({
+            tag: REQUEST_TAG.guardRetract
+        });
+    }
 }
 
 async function deleteOrphanedDefinitionGuards(args) {
@@ -5592,7 +5780,7 @@ async function resolveContextHandoff({ctx: ctx, sub: sub, parentScope: parentSco
 }
 
 function canonicaliseSpawnValue({kind: kind, value: value, cx: cx}) {
-    return kind === "doc.ref" ? coerceSpawnGdr(value, cx) : kind === "doc.refs" && Array.isArray(value) ? value.map(v2 => coerceSpawnGdr(v2, cx)).filter(v2 => v2 !== null) : value;
+    return isSingleDocRefKind(kind) ? coerceSpawnGdr(value, cx) : kind === "doc.refs" && Array.isArray(value) ? value.map(v2 => coerceSpawnGdr(v2, cx)).filter(v2 => v2 !== null) : value;
 }
 
 function assertBareIdRootsCorrectly(id, cx) {
@@ -6318,6 +6506,9 @@ async function evaluateEditableFields(args) {
             ...site.title !== void 0 ? {
                 title: site.title
             } : {},
+            ...site.validation !== void 0 ? {
+                validation: site.validation
+            } : {},
             value: value,
             editable: reason === void 0,
             ...reason !== void 0 ? {
@@ -6543,7 +6734,7 @@ function triggeredActionVerdict({action: action, when: when, insights: insights}
         },
         ...insights
     }) : {
-        action: action,
+        ...actionEvaluationIdentity(action),
         allowed: !1,
         triggered: !0,
         disabledReason: {
@@ -6589,12 +6780,21 @@ function fireableActionVerdict({args: args, insights: insights}) {
         },
         ...insights
     }) : {
-        action: action,
+        ...actionEvaluationIdentity(action),
         allowed: !0,
         ...insights
     };
 }
 
+function actionEvaluationIdentity(action) {
+    return {
+        action: action,
+        ...action.semantics !== void 0 ? {
+            semantics: action.semantics
+        } : {}
+    };
+}
+
 async function instanceGuardReason({instance: instance, actor: actor, guards: guards}) {
     if (guards === void 0 || guards.length === 0) return;
     const denied = await instanceWriteDenials({
@@ -6609,15 +6809,8 @@ async function instanceGuardReason({instance: instance, actor: actor, guards: gu
 }
 
 function lifecycleReason({instance: instance, status: status, stageHasExits: stageHasExits}) {
-    const terminal = terminalState(instance);
-    if (terminal === "aborted" && instance.abortedAt !== void 0) return {
-        kind: "instance-aborted",
-        abortedAt: instance.abortedAt
-    };
-    if (terminal === "completed" && instance.completedAt !== void 0) return {
-        kind: "instance-completed",
-        completedAt: instance.completedAt
-    };
+    const terminalReason = instanceTerminalReason(instance);
+    if (terminalReason !== void 0) return terminalReason;
     if (!stageHasExits) return {
         kind: "stage-terminal",
         stage: instance.currentStage
@@ -6630,7 +6823,7 @@ function lifecycleReason({instance: instance, status: status, stageHasExits: sta
 
 function disabled(args) {
     return {
-        action: args.action,
+        ...actionEvaluationIdentity(args.action),
         allowed: !1,
         disabledReason: args.reason,
         ...args.insight !== void 0 ? {
@@ -7441,9 +7634,7 @@ function startMutation(instance) {
 }
 
 function instanceStateFields(src) {
-    const fields = {
-        modelVersion: DATA_MODEL_VERSION,
-        minReaderModel: Math.max(src.minReaderModel, DATA_MODEL_MIN_READER),
+    const state = {
         currentStage: src.currentStage,
         fields: src.fields,
         stages: src.stages,
@@ -7452,10 +7643,22 @@ function instanceStateFields(src) {
         effectHistory: src.effectHistory,
         context: src.context,
         history: src.history,
-        processedRequests: src.processedRequests ?? []
+        processedRequests: src.processedRequests ?? [],
+        ...src.completedAt !== void 0 ? {
+            completedAt: src.completedAt
+        } : {},
+        ...src.abortedAt !== void 0 ? {
+            abortedAt: src.abortedAt
+        } : {}
+    };
+    return {
+        ...modelStampFor({
+            documentType: "instance",
+            document: state,
+            storedMinReaderModel: src.minReaderModel
+        }),
+        ...state
     };
-    return src.completedAt !== void 0 && (fields.completedAt = src.completedAt), src.abortedAt !== void 0 && (fields.abortedAt = src.abortedAt), 
-    fields;
 }
 
 function liveViewContext(ctx, mutation) {
@@ -7667,16 +7870,7 @@ function validateEffectOutputs(args) {
             issues.push(`"${key}" is not a declared output`);
             continue;
         }
-        const shapeIssues = checkFieldValue({
-            entryType: shape.type,
-            value: value,
-            ...shape.fields !== void 0 ? {
-                fields: shape.fields
-            } : {},
-            ...shape.of !== void 0 ? {
-                of: shape.of
-            } : {}
-        });
+        const shapeIssues = effectOutputIssues(shape, value);
         shapeIssues !== void 0 && issues.push(...shapeIssues.map(i => `"${key}": ${i}`));
     }
     if (issues.length > 0) throw new EffectOutputsInvalidError({
@@ -7685,6 +7879,25 @@ function validateEffectOutputs(args) {
     });
 }
 
+function effectOutputIssues(shape, value) {
+    return checkFieldValue({
+        entryType: shape.type,
+        value: value,
+        ...shape.fields !== void 0 ? {
+            fields: shape.fields
+        } : {},
+        ...shape.of !== void 0 ? {
+            of: shape.of
+        } : {},
+        ...shape.options !== void 0 ? {
+            options: shape.options
+        } : {},
+        ...shape.validation !== void 0 ? {
+            validation: shape.validation
+        } : {}
+    });
+}
+
 function requirePendingEffect(instance, effectKey) {
     const pending = instance.pendingEffects.find(e => e._key === effectKey);
     if (pending !== void 0) return pending;
@@ -7905,7 +8118,7 @@ async function sortByDependencies({client: client, definitions: definitions, tag
         byName.set(def.name, def);
     }
     const findInBatch = ref => findRefInBatch(byName, ref);
-    return await assertCrossBatchRefsDeployed({
+    return await assertSpawnContracts({
         client: client,
         definitions: definitions,
         ctx: {
@@ -7921,31 +8134,76 @@ function findRefInBatch(byName, ref) {
     if (typeof ref.version != "number") return byName.get(ref.name);
 }
 
-async function assertCrossBatchRefsDeployed({client: client, definitions: definitions, ctx: ctx}) {
-    const missing = [];
-    for (const def of definitions) for (const ref of refsOf(def)) {
-        if (ctx.findInBatch(ref) !== void 0) continue;
-        const label = await resolveDeployedRefLabel({
+async function assertSpawnContracts({client: client, definitions: definitions, ctx: ctx}) {
+    const missing = [], invalidHandoffs = [];
+    for (const def of definitions) for (const spawn of spawnSitesOf(def)) {
+        const ref = logicalRefOf(spawn.definition), child = ctx.findInBatch(ref) ?? await resolveDeployedRef({
             client: client,
             ref: ref,
             tag: ctx.tag
         });
-        label !== void 0 && missing.push({
-            from: def.name,
-            ref: label
-        });
+        if (child === void 0) {
+            missing.push({
+                reason: "unresolved-definition",
+                from: def.name,
+                ref: logicalRefLabel(ref)
+            });
+            continue;
+        }
+        for (const field of Object.keys(spawn.with ?? {})) {
+            const entry = (child.fields ?? []).find(candidate => candidate.name === field);
+            entry === void 0 ? invalidHandoffs.push({
+                reason: "unconsumable-field",
+                from: def.name,
+                child: child.name,
+                field: field,
+                detail: "the child declares no workflow field with that name"
+            }) : isInputSourced(entry) || invalidHandoffs.push({
+                reason: "unconsumable-field",
+                from: def.name,
+                child: child.name,
+                field: field,
+                detail: `the child field is ${entry.initialValue?.type ?? "working-memory"}-sourced, not input-sourced`
+            });
+        }
     }
-    if (missing.length === 0) return;
-    const lines = missing.map(m => `  - ${m.from} → ${m.ref} (neither in batch nor deployed)`);
-    throw new Error(`workflow.deployDefinitions: ${missing.length} unresolved reference${missing.length === 1 ? "" : "s"}:\n` + lines.join(`\n`));
+    if (missing.length === 0 && invalidHandoffs.length === 0) return;
+    if (invalidHandoffs.length === 0) {
+        const lines2 = missing.map(issue => `  - ${issue.from} → ${issue.ref} (neither in batch nor deployed)`);
+        throw new Error(`workflow.deployDefinitions: ${missing.length} unresolved reference${missing.length === 1 ? "" : "s"}:\n` + lines2.join(`\n`));
+    }
+    const issues = [ ...missing, ...invalidHandoffs ], lines = [ ...missing.map(m => `  - ${m.from} → ${m.ref} (neither in batch nor deployed)`), ...invalidHandoffs.map(issue => `  - ${issue.from} → ${issue.child}: spawn.with["${issue.field}"] cannot be consumed — ${issue.detail}`) ], count = lines.length;
+    throw new SpawnContractsInvalidError({
+        issues: issues,
+        message: `workflow.deployDefinitions: ${count} invalid spawn contract${count === 1 ? "" : "s"}:\n` + lines.join(`\n`)
+    });
 }
 
-async function resolveDeployedRefLabel({client: client, ref: ref, tag: tag}) {
+async function resolveDeployedRef({client: client, ref: ref, tag: tag}) {
     const wantsExplicit = typeof ref.version == "number", params = {
         definition: ref.name,
         tag: tag
     };
-    if (wantsExplicit && (params.version = ref.version), !await client.fetch(definitionLookupGroq(wantsExplicit), params)) return wantsExplicit ? `${ref.name} v${ref.version}` : ref.name;
+    wantsExplicit && (params.version = ref.version);
+    const doc = await client.fetch(definitionLookupGroq(wantsExplicit), params);
+    if (doc) return parseDefinitionInput(doc, `workflow.deployDefinitions child "${logicalRefLabel(ref)}"`);
+}
+
+function logicalRefLabel(ref) {
+    return typeof ref.version == "number" ? `${ref.name} v${ref.version}` : ref.name;
+}
+
+function logicalRefOf(ref) {
+    return {
+        name: ref.name,
+        ...ref.version !== void 0 ? {
+            version: ref.version
+        } : {}
+    };
+}
+
+function spawnSitesOf(def) {
+    return def.stages.flatMap(stage => stage.activities ?? []).flatMap(activity => activity.actions ?? []).flatMap(action => action.spawn === void 0 ? [] : [ action.spawn ]);
 }
 
 function topoSortDefinitions(definitions, ctx) {
@@ -7965,12 +8223,7 @@ function topoSortDefinitions(definitions, ctx) {
 }
 
 function refsOf(def) {
-    return def.stages.flatMap(stage => stage.activities ?? []).flatMap(activity => activity.actions ?? []).flatMap(action => action.spawn === void 0 ? [] : [ action.spawn.definition ]).map(ref => ({
-        name: ref.name,
-        ...ref.version !== void 0 ? {
-            version: ref.version
-        } : {}
-    }));
+    return spawnSitesOf(def).map(spawn => logicalRefOf(spawn.definition));
 }
 
 function hashDefinitionContent(def) {
@@ -7993,7 +8246,10 @@ function planDefinitionDeploy({def: def, latest: latest, target: target}) {
         tag: target.tag,
         version: version,
         contentHash: contentHash,
-        ...MODEL_STAMP
+        ...modelStampFor({
+            documentType: "definition",
+            document: expanded
+        })
     };
     return {
         status: unchanged ? "unchanged" : "create",
@@ -8836,6 +9092,7 @@ async function fetchStartSlice(args) {
 
 const workflow = {
     deployDefinitions: async rawArgs => {
+        assertReaderModelAcknowledgement(rawArgs.expectedMinReaderModel);
         const args = taggedScope(rawArgs, REQUEST_TAG.deploy), {client: client, tag: tag, resourceAliases: resourceAliases} = args;
         validateTag(tag);
         const definitions = args.definitions.map(def => parseDefinitionInput(def, "workflow.deployDefinitions"));
@@ -8908,8 +9165,8 @@ const workflow = {
         }), result;
     },
     startInstance: async rawArgs => {
-        const args = taggedScope(rawArgs, REQUEST_TAG.start), {client: client, tag: tag, workflowResource: workflowResource, definition: definitionName, version: version, initialFields: initialFields, ancestors: ancestors, context: context, instanceId: instanceId, perspective: perspective, executionContext: executionContext} = args, {actor: actor, clientForGdr: clientForGdr, refSurface: refSurface} = await resolveOperationContext(args), clock = args.clock ?? wallClock, seedFields = initialFields ?? [], existing = instanceId !== void 0 ? await getInstanceDocument(client, instanceId) : void 0;
-        if (existing !== void 0 && existing.tag === tag) return resumeStart({
+        const args = taggedScope(rawArgs, REQUEST_TAG.start), {client: client, tag: tag, definition: definitionName, version: version, initialFields: initialFields, instanceId: instanceId, executionContext: executionContext} = args, operationContext = await resolveOperationContext(args), {actor: actor, clientForGdr: clientForGdr, refSurface: refSurface} = operationContext, clock = args.clock ?? wallClock, seedFields = initialFields ?? [], existing = instanceId !== void 0 ? await getInstanceDocument(client, instanceId) : void 0;
+        return existing !== void 0 && existing.tag === tag ? resumeStart({
             client: client,
             tag: tag,
             existing: existing,
@@ -8926,105 +9183,12 @@ const workflow = {
             ...args.telemetry !== void 0 ? {
                 telemetry: args.telemetry
             } : {}
-        });
-        const definition = await loadDefinition({
-            client: client,
-            definition: definitionName,
-            version: version,
-            tag: tag
-        }), id = instanceId ?? instanceDocId(tag);
-        if (definition.stages.find(s => s.name === definition.initialStage) === void 0) throw new Error(`Initial stage "${definition.initialStage}" missing in ${definitionName} v${definition.version}`);
-        const now = clock();
-        if (assertRequiredInputProvided({
-            entryDefs: definition.fields ?? [],
-            initialFields: seedFields,
-            definitionName: definition.name
-        }), definition.start?.allowed !== void 0) {
-            const insight = await startAllowedInsight({
-                client: client,
-                tag: tag,
-                definition: definition,
-                allowed: definition.start.allowed,
-                initialFields: seedFields,
-                now: now
-            });
-            if (insight.outcome !== "satisfied") throw new StartNotAllowedError({
-                definition: definition.name,
-                insight: insight
-            });
-        }
-        const contextEntries = context ? toContextEntries(context) : [], fieldDiscards = [], resolvedFields = await resolveDeclaredFields({
-            entryDefs: definition.fields ?? [],
-            initialFields: seedFields,
-            ctx: {
-                client: client,
-                now: now,
-                selfId: id,
-                tag: tag,
-                workflowResource: workflowResource,
-                definitionName: definition.name,
-                refSurface: refSurface,
-                ...perspective !== void 0 ? {
-                    perspective: perspective
-                } : {},
-                recordDiscard: recordFieldDiscards({
-                    target: fieldDiscards,
-                    scope: "workflow",
-                    at: now
-                })
-            },
-            randomKey: randomKey
-        }), effectivePerspective = perspective ?? derivePerspectiveFromFields(resolvedFields), base = buildInstanceBase({
-            id: id,
-            now: now,
-            tag: tag,
-            workflowResource: workflowResource,
-            definitionName: definition.name,
-            pinnedVersion: definition.version,
-            pinnedContentHash: definition.contentHash,
-            definition: definition,
-            fields: resolvedFields,
-            context: contextEntries,
-            ancestors: ancestors ?? [],
-            perspective: effectivePerspective,
-            initialStage: definition.initialStage,
-            actor: actor,
-            executionContext: resolveExecutionContext(executionContext),
-            ...fieldDiscards.length > 0 ? {
-                extraHistory: fieldDiscards
-            } : {}
-        });
-        await client.create(base, SYNC_COMMIT);
-        const cascaded = await settleStart({
-            client: client,
-            tag: tag,
-            instanceId: id,
-            actor: actor,
-            clientForGdr: clientForGdr,
-            refSurface: refSurface,
+        }) : startFreshInstance({
+            args: args,
+            operationContext: operationContext,
             clock: clock,
-            ...executionContext !== void 0 ? {
-                executionContext: executionContext
-            } : {},
-            ...args.telemetry !== void 0 ? {
-                telemetry: args.telemetry
-            } : {},
-            emitStarted: () => resolveTelemetry(args.telemetry).log(WorkflowInstanceStarted, instanceStartedData({
-                definition: definition,
-                instanceId: id,
-                initialFieldCount: seedFields.length,
-                viaSpawn: !1
-            }))
+            seedFields: seedFields
         });
-        return {
-            instance: await reload({
-                client: client,
-                instanceId: id,
-                tag: tag
-            }),
-            cascaded: cascaded,
-            changed: !0
-        };
     },
     fireAction: async rawArgs => {
         const args = taggedScope(rawArgs, REQUEST_TAG.fireAction), {client: client, tag: tag, workflowResource: workflowResource, instanceId: instanceId, activity: activity, action: action, params: params, idempotent: idempotent, resourceClients: resourceClients, grantsFromPath: grantsFromPath, executionContext: executionContext} = args;
@@ -9510,7 +9674,7 @@ const workflow = {
         return (await client.fetch(query, params)).map(readInstanceDoc).filter(instance => instanceWatchesDocument(instance, document));
     },
     definitionsForDocument: async rawArgs => {
-        const args = taggedScope(rawArgs, REQUEST_TAG.definitionsForDocument), {client: client, tag: tag, document: document} = args;
+        const args = taggedScope(rawArgs, REQUEST_TAG.definitionsForDocument), {client: client, tag: tag, document: document, subject: subject} = args;
         validateTag(tag);
         const clock = args.clock ?? wallClock, deployed = (await client.fetch(definitionsListGroq("desc"), {
             tag: tag
@@ -9522,6 +9686,9 @@ const workflow = {
             scope: {
                 tag: tag,
                 now: clock(),
+                ...subject !== void 0 ? {
+                    subject: subject
+                } : {},
                 fetchDataset: () => slice ??= fetchStartSlice({
                     client: client,
                     tag: tag
@@ -9537,20 +9704,29 @@ const workflow = {
             definition: definitionName,
             version: version,
             tag: tag
+        }), invalidInitialFields = initialFieldIssues({
+            workflowFields: definition.fields ?? [],
+            stages: definition.stages,
+            initialFields: initialFields ?? []
         }), missingRequired = missingRequiredInputs({
             entryDefs: definition.fields ?? [],
             initialFields: initialFields ?? []
         }), allowed = definition.start?.allowed;
         if (allowed === void 0) return {
-            allowed: !0,
+            allowed: invalidInitialFields.length === 0,
             outcome: "satisfied",
             unboundReads: [],
-            missingRequired: missingRequired
+            missingRequired: missingRequired,
+            invalidInitialFields: invalidInitialFields
         };
-        const unboundReads = unboundAllowedReads(allowed, startFieldsParam({
-            entryDefs: definition.fields ?? [],
-            initialFields: initialFields ?? []
-        })), insight = await startAllowedInsight({
+        const unboundReads = unboundAllowedReadsWithSubject({
+            allowed: allowed,
+            fields: startFieldsParam({
+                entryDefs: definition.fields ?? [],
+                initialFields: initialFields ?? []
+            }),
+            definition: definition
+        }), insight = await startAllowedInsight({
             client: client,
             tag: tag,
             definition: definition,
@@ -9559,11 +9735,12 @@ const workflow = {
             now: clock()
         }), provisional = unboundReads.length > 0;
         return {
-            allowed: !provisional && insight.outcome === "satisfied",
+            allowed: invalidInitialFields.length === 0 && !provisional && insight.outcome === "satisfied",
             outcome: provisional ? "unevaluable" : insight.outcome,
             insight: insight,
             unboundReads: unboundReads,
-            missingRequired: missingRequired
+            missingRequired: missingRequired,
+            invalidInitialFields: invalidInitialFields
         };
     },
     permissions: {
@@ -9593,6 +9770,239 @@ async function startAllowedInsight(args) {
     });
 }
 
+async function startFreshInstance(args) {
+    const {args: startArgs, operationContext: operationContext, clock: clock, seedFields: seedFields} = args, {client: client, tag: tag, workflowResource: workflowResource, definition: definitionName, version: version, ancestors: ancestors, context: context, instanceId: instanceId, perspective: perspective, executionContext: executionContext} = startArgs, {actor: actor, clientForGdr: clientForGdr, refSurface: refSurface} = operationContext, definition = await loadDefinition({
+        client: client,
+        definition: definitionName,
+        version: version,
+        tag: tag
+    }), id = instanceId ?? instanceDocId(tag);
+    assertInitialStageExists(definition);
+    const now = clock();
+    await assertStartInputs({
+        client: client,
+        tag: tag,
+        definition: definition,
+        initialFields: seedFields,
+        now: now
+    });
+    const {resolvedFields: resolvedFields, fieldDiscards: fieldDiscards} = await resolveStartFields({
+        client: client,
+        tag: tag,
+        workflowResource: workflowResource,
+        definition: definition,
+        initialFields: seedFields,
+        id: id,
+        now: now,
+        refSurface: refSurface,
+        ...perspective !== void 0 ? {
+            perspective: perspective
+        } : {}
+    }), base = buildInstanceBase({
+        id: id,
+        now: now,
+        tag: tag,
+        workflowResource: workflowResource,
+        definitionName: definition.name,
+        pinnedVersion: definition.version,
+        pinnedContentHash: definition.contentHash,
+        definition: definition,
+        fields: resolvedFields,
+        context: context ? toContextEntries(context) : [],
+        ancestors: ancestors ?? [],
+        perspective: perspective ?? derivePerspectiveFromFields(resolvedFields),
+        initialStage: definition.initialStage,
+        actor: actor,
+        executionContext: resolveExecutionContext(executionContext),
+        ...fieldDiscards.length > 0 ? {
+            extraHistory: fieldDiscards
+        } : {}
+    });
+    await client.create(base, SYNC_COMMIT);
+    const cascaded = await settleStart({
+        client: client,
+        tag: tag,
+        instanceId: id,
+        actor: actor,
+        clientForGdr: clientForGdr,
+        refSurface: refSurface,
+        clock: clock,
+        ...executionContext !== void 0 ? {
+            executionContext: executionContext
+        } : {},
+        ...startArgs.telemetry !== void 0 ? {
+            telemetry: startArgs.telemetry
+        } : {},
+        emitStarted: () => resolveTelemetry(startArgs.telemetry).log(WorkflowInstanceStarted, instanceStartedData({
+            definition: definition,
+            instanceId: id,
+            initialFieldCount: seedFields.length,
+            viaSpawn: !1
+        }))
+    });
+    return {
+        instance: await reload({
+            client: client,
+            instanceId: id,
+            tag: tag
+        }),
+        cascaded: cascaded,
+        changed: !0
+    };
+}
+
+function assertInitialStageExists(definition) {
+    if (!definition.stages.some(stage => stage.name === definition.initialStage)) throw new Error(`Initial stage "${definition.initialStage}" missing in ${definition.name} v${definition.version}`);
+}
+
+async function assertStartInputs(args) {
+    const {client: client, tag: tag, definition: definition, initialFields: initialFields, now: now} = args;
+    assertInitialFieldsConsumable({
+        workflowFields: definition.fields ?? [],
+        stages: definition.stages,
+        initialFields: initialFields,
+        definitionName: definition.name
+    }), assertRequiredInputProvided({
+        entryDefs: definition.fields ?? [],
+        initialFields: initialFields,
+        definitionName: definition.name
+    });
+    const allowed = definition.start?.allowed;
+    if (allowed === void 0) return;
+    const insight = await startAllowedInsight({
+        client: client,
+        tag: tag,
+        definition: definition,
+        allowed: allowed,
+        initialFields: initialFields,
+        now: now
+    });
+    if (insight.outcome !== "satisfied") throw new StartNotAllowedError({
+        definition: definition.name,
+        insight: insight
+    });
+}
+
+async function resolveStartFields(args) {
+    const {client: client, tag: tag, workflowResource: workflowResource, definition: definition, initialFields: initialFields, id: id, now: now, refSurface: refSurface, perspective: perspective} = args, fieldDiscards = [];
+    return {
+        resolvedFields: await resolveDeclaredFields({
+            entryDefs: definition.fields ?? [],
+            initialFields: initialFields,
+            ctx: {
+                client: client,
+                now: now,
+                selfId: id,
+                tag: tag,
+                workflowResource: workflowResource,
+                definitionName: definition.name,
+                refSurface: refSurface,
+                ...perspective !== void 0 ? {
+                    perspective: perspective
+                } : {},
+                recordDiscard: recordFieldDiscards({
+                    target: fieldDiscards,
+                    scope: "workflow",
+                    at: now
+                })
+            },
+            randomKey: randomKey
+        }),
+        fieldDiscards: fieldDiscards
+    };
+}
+
+function isRecord(value) {
+    return typeof value == "object" && value !== null && !Array.isArray(value);
+}
+
+function isClientProjectUser(value) {
+    return isRecord(value) && typeof value.id == "string" && (value.displayName === void 0 || typeof value.displayName == "string") && (value.email === void 0 || typeof value.email == "string") && (value.imageUrl === void 0 || value.imageUrl === null || typeof value.imageUrl == "string");
+}
+
+function objectProperty(value, property) {
+    if (!isRecord(value)) return;
+    const propertyValue = value[property];
+    return typeof propertyValue == "object" && propertyValue !== null ? propertyValue : void 0;
+}
+
+function stringProperty(value, property) {
+    const propertyValue = Reflect.get(value, property);
+    return typeof propertyValue == "string" ? propertyValue : void 0;
+}
+
+function apiErrorType(error) {
+    const response = objectProperty(error, "response"), body = objectProperty(response, "body");
+    if (!body) return;
+    const nestedError = objectProperty(body, "error");
+    return (nestedError ? stringProperty(nestedError, "type") : void 0) ?? stringProperty(body, "type");
+}
+
+function isProjectUserNotFoundError(error) {
+    return apiErrorType(error) === "projectUserNotFoundError";
+}
+
+function clientProjectUserDirectory(client, projectId) {
+    return {
+        findById: async id => {
+            if (!client.request) return {
+                status: "inaccessible",
+                cause: new Error("Project-user resolution requires WorkflowClient.request")
+            };
+            try {
+                const response = await client.request({
+                    uri: `/projects/${encodeURIComponent(projectId)}/users/${encodeURIComponent(id)}`
+                }), candidate = Array.isArray(response) ? response[0] : response;
+                return candidate == null ? {
+                    status: "missing"
+                } : isClientProjectUser(candidate) ? {
+                    status: "resolved",
+                    user: candidate
+                } : {
+                    status: "inaccessible",
+                    cause: new Error("Project-user response had an invalid shape")
+                };
+            } catch (cause) {
+                return isProjectUserNotFoundError(cause) ? {
+                    status: "missing"
+                } : {
+                    status: "inaccessible",
+                    cause: cause
+                };
+            }
+        }
+    };
+}
+
+function resolveClientActor(client, args) {
+    return resolveActor(clientProjectUserDirectory(client, args.projectId), args.actor);
+}
+
+async function resolveActor(directory, actor) {
+    if (actor.kind !== "person") return {
+        status: "not-person",
+        actor: actor
+    };
+    const personActor = {
+        ...actor,
+        kind: "person"
+    }, lookup = await directory.findById(personActor.id);
+    return lookup.status === "resolved" ? {
+        status: "resolved",
+        actor: personActor,
+        user: lookup.user
+    } : lookup.status === "inaccessible" ? {
+        status: "inaccessible",
+        actor: personActor,
+        ...lookup.cause === void 0 ? {} : {
+            cause: lookup.cause
+        }
+    } : {
+        status: "missing",
+        actor: personActor
+    };
+}
+
 const DEFAULT_EFFECT_LEASE_MS = 300 * 1e3;
 
 function isClaimExpired(claim, now) {
@@ -9735,11 +10145,11 @@ function isCancelledCompletion(data) {
 }
 
 async function drainEffectsInternal(args) {
-    const {tag: tag, workflowResource: workflowResource, instanceId: instanceId, effectHandlers: effectHandlers, missingHandler: missingHandler, logger: logger} = args, cascadeTelemetry = drainCascadeTelemetry(args.telemetry), {client: client, resourceClients: resourceClients} = taggedScope(args, REQUEST_TAG.drain), leaseMs = args.leaseMs ?? DEFAULT_EFFECT_LEASE_MS, clock = args.clock ?? wallClock, routeGdr = buildClientForGdr({
-        client: client,
+    const {tag: tag, workflowResource: workflowResource, instanceId: instanceId, effectHandlers: effectHandlers, missingHandler: missingHandler, logger: logger, handlerClient: handlerClient, handlerResourceClients: handlerResourceClients} = args, cascadeTelemetry = drainCascadeTelemetry(args.telemetry), {client: client, resourceClients: resourceClients} = taggedScope(args, REQUEST_TAG.drain), leaseMs = args.leaseMs ?? DEFAULT_EFFECT_LEASE_MS, clock = args.clock ?? wallClock, routeGdr = buildClientForGdr({
+        client: handlerClient,
         workflowResource: workflowResource,
-        resourceClients: resourceClients
-    }), clientFor = ref => withRequestTag(routeGdr(parseGdr(typeof ref == "string" ? ref : ref.id)), REQUEST_TAG.effect), {actor: drainerActor} = await resolveAccess(client), executionContext = args.executionContext;
+        resourceClients: handlerResourceClients
+    }), clientFor = ref => routeGdr(parseGdr(typeof ref == "string" ? ref : ref.id)), {actor: drainerActor} = await resolveAccess(client), executionContext = args.executionContext;
     validateTag(tag);
     const log = logger("drainEffects"), buckets = {
         drained: [],
@@ -9785,6 +10195,7 @@ async function drainEffectsInternal(args) {
             handler: handler,
             candidate: candidate,
             client: client,
+            handlerClient: handlerClient,
             tag: tag,
             workflowResource: workflowResource,
             ...resourceClients !== void 0 ? {
@@ -9810,11 +10221,11 @@ function findClaimableCandidate({instance: instance, now: now, skippedKeys: skip
 }
 
 async function dispatchAndReport(args) {
-    const {handler: handler, candidate: candidate, client: client, tag: tag, workflowResource: workflowResource, resourceClients: resourceClients, instanceId: instanceId, clientFor: clientFor, logger: logger, log: log, executionContext: executionContext, telemetry: telemetry, clock: clock} = args, {outputs: outputs, ops: ops, dispatchError: dispatchError} = await dispatchEffect({
+    const {handler: handler, candidate: candidate, client: client, handlerClient: handlerClient, tag: tag, workflowResource: workflowResource, resourceClients: resourceClients, instanceId: instanceId, clientFor: clientFor, logger: logger, log: log, executionContext: executionContext, telemetry: telemetry, clock: clock} = args, {outputs: outputs, ops: ops, dispatchError: dispatchError} = await dispatchEffect({
         handler: handler,
         candidate: candidate,
         ctx: {
-            client: client,
+            client: handlerClient,
             clientFor: clientFor,
             instanceId: instanceId,
             logger: logger
@@ -9920,7 +10331,7 @@ async function claimPendingEffect({client: client, instance: instance, candidate
 async function dispatchEffect({handler: handler, candidate: candidate, ctx: ctx}) {
     try {
         const result = await handler(candidate.params, {
-            client: withRequestTag(ctx.client, REQUEST_TAG.effect),
+            client: ctx.client,
             clientFor: ctx.clientFor,
             instanceId: ctx.instanceId,
             effectKey: candidate._key,
@@ -10414,6 +10825,7 @@ function createEngine(args) {
         missingHandler: missingHandler,
         logger: logger,
         telemetry: telemetry,
+        resolveActor: rest => resolveClientActor(client, rest),
         deployDefinitions: async rest => {
             const result = await workflow.deployDefinitions(withScope(rest));
             return logDeployWarnings(result, logger), result;
@@ -10454,6 +10866,10 @@ function createEngine(args) {
         drainEffects: async ({instanceId: instanceId}) => {
             const result = await drainEffectsInternal({
                 client: client,
+                handlerClient: args.client,
+                ...args.resourceClients !== void 0 ? {
+                    handlerResourceClients: args.resourceClients
+                } : {},
                 tag: tag,
                 workflowResource: workflowResource,
                 ...optionalScope,
@@ -10650,6 +11066,7 @@ function attributeMember({member: member, group: group, chain: chain}) {
 }
 
 function diffEntry({def: rawDef, latestRaw: latestRaw, target: target}) {
+    assertReaderModelAcknowledgement(target.expectedMinReaderModel);
     const def = parseDefinitionInput(rawDef, "diffEntry"), plan = planDefinitionDeploy({
         def: def,
         latest: asLatest(latestRaw),
@@ -10681,6 +11098,7 @@ function asLatest(raw) {
 }
 
 async function computeDiffEntries({client: client, defs: defs, target: target}) {
+    assertReaderModelAcknowledgement(target.expectedMinReaderModel);
     const entries = [];
     for (const rawDef of defs) {
         const def = parseDefinitionInput(rawDef, "computeDiffEntries"), latest = await loadLatestDeployed({
@@ -10702,7 +11120,7 @@ function buildInitialFields({declared: declared, values: values}) {
     return Object.entries(values).map(([name, value]) => {
         const entry = declared.find(f => f.name === name);
         if (entry === void 0) throw new Error(settable.length > 0 ? `workflow declares no field "${name}" — input fields: ${settableNames}` : `workflow declares no field "${name}" — it declares no input fields at all`);
-        if (entry.initialValue?.type !== "input") throw new Error(`field "${name}" is not input-sourced — the engine would silently ignore the value. ` + (settable.length > 0 ? `Input fields: ${settableNames}` : "This workflow has no input fields."));
+        if (entry.initialValue?.type !== "input") throw new Error(`field "${name}" is not input-sourced and cannot accept a start value. ` + (settable.length > 0 ? `Input fields: ${settableNames}` : "This workflow has no input fields."));
         return {
             type: entry.type,
             name: name,
@@ -10766,7 +11184,7 @@ const HISTORY_DISPLAY = {
     },
     aborted: {
         title: "Instance aborted",
-        description: "An admin hard-stopped the instance — pending effects cancelled, stage guards lifted, abortedAt + completedAt stamped."
+        description: "An admin hard-stopped the instance — pending effects cancelled, stage guards removed, abortedAt + completedAt stamped."
     },
     opApplied: {
         title: "Op applied",
@@ -10802,6 +11220,10 @@ const HISTORY_DISPLAY = {
         title: "Document references",
         description: "Ordered list of GDR pointers — multi-doc selection."
     },
+    subject: {
+        title: "Subject document",
+        description: "Single GDR pointer at THE document the workflow is about — same value as a document reference, elevated so surfaces identify the subject by kind."
+    },
     "release.ref": {
         title: "Content Release reference",
         description: "GDR pointer at a Content Release system doc, carrying the release name the engine derives the instance's read perspective from."
@@ -10980,4 +11402,4 @@ function displayDescription(typeKey) {
     if (typeKey) return DISPLAY[typeKey]?.description;
 }
 
-export { ACTIVITY_KINDS, ACTIVITY_KIND_DISPLAY, ACTOR_KINDS, AUTHORING_DISPLAY, ActionDisabledError, ActionParamsInvalidError, CONDITION_VARS, CONTEXT_ENTRY_DISPLAY, CascadeLimitError, ConcurrentCompleteEffectError, ConcurrentEditFieldError, ConcurrentFireActionError, ContractViolationError, DATA_MODEL_MIN_READER, DATA_MODEL_VERSION, DEFAULT_CONTENT_PERSPECTIVE, DEFAULT_EFFECT_LEASE_MS, DEFAULT_IDEMPOTENCY_TTL_MS, DEFAULT_TRANSITION_WHEN, DISPLAY, DRIVER_KINDS, DRIVER_KIND_DISPLAY, DefinitionInUseError, DefinitionNotFoundError, ENGINE_API_VERSION, EXECUTION_KINDS, EXECUTOR_CLASSIFICATIONS, EXECUTOR_CLASSIFICATION_DISPLAY, EditFieldDeniedError, EffectNotFoundError, EffectOpsInvalidError, EffectOutputsInvalidError, FIELD_KIND_DISPLAY, FILTER_SCOPE_VARS, FieldValueShapeError, GROUP_KINDS, GROUP_KIND_DISPLAY, GUARD_DOC_TYPE, GUARD_LIFTED_PREDICATE, GUARD_OWNER, GUARD_PREDICATE_VARS, HISTORY_DISPLAY, InstanceNotFoundError, MAX_COUNTERFACTUAL_INDEX2 as MAX_COUNTERFACTUAL_INDEX, MissingHandlerError, ModelVersionAheadError, MutationGuardDeniedError, MutationGuardDocSchema, OP_DISPLAY, PartialGuardDeployError, PersistedDocShapeError, RESERVED_CONDITION_VARS, RefResourceUndeclaredError, RequiredFieldNotProvidedError, START_ALLOWED_VARS, START_FILTER_VARS, StartNotAllowedError, StartNotPrimedError, StartNotSettledError, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, WorkflowActionFired, WorkflowDefinitionDeleted, WorkflowDefinitionDeployed, WorkflowEffectCompleted, WorkflowEffectsDrained, WorkflowError, WorkflowFieldEdited, WorkflowInstanceAborted, WorkflowInstanceSchema, WorkflowInstanceStarted, WorkflowInstanceTicked, WorkflowStageSet, WorkflowStageTransitioned, WorkflowStateDivergedError, abortReason, acceptsDocumentType, aclPathForResource, actionDisabledDetail, actionRendering, actionVerdict, activityAutonomyOf, analyzeCondition2 as analyzeCondition, applicableDefinitions, assertReadableModel, atomReadsDataset2 as atomReadsDataset, autonomySummary, availableActions, buildInitialFields, buildSnapshot, checklistLines, clientConfigFromResource, compileGuard, computeDiffEntries, conditionFieldReadNames, conditionSitesOf, contentDocQuery, contentDraftFallback, contentReleaseName, contextMap, createEngine, createTelemetryIntake, datasetResourceParts, defaultLoggerFactory, definitionDeployedData, definitionLookupGroq, definitionsListGroq, deniedGuardLabels, deniedGuardRefs, denyingGuards, deployStageGuards, deriveActivityKind, deriveExecutorClassification, deriveWorkflowAutonomy, describeAtom, describeAutonomyWait, describeCondition, describeDefinition, describeFieldInsight, describeNode, describeSite, describeSiteHeading, diagnoseInputFromEvaluation, diagnoseInstance, diffEntry, displayDescription, displayTitle, documentActionDenials, documentPrefilter, driverKind, effectOutputsMap, entryDocRefs, errorMessage, evaluateFromSnapshot, evaluateMutationGuard, evaluateStartFilter, explainCondition2 as explainCondition, explainStartAllowed, extractDocumentId, fieldTreeShape, findCurrentActivityEntry, findOpenStageEntry, formatRead, gdrFromResource, gdrRef, gdrUri, groupMembershipNames, groupSitesOf, guardMatches, guardsForDefinition, guardsForInstance, guardsForResource, guillemets2 as guillemets, hashDefinitionContent, humanize2 as humanize, inFlightFilter, instanceDocId, instanceGuardQuery, instanceWatchesDocument, instancesQuery, isCascadeFired, isClaimExpired, isComparisonOp, isDefinitionApplicable, isFilterScopedOut, isGdr, isGuardLifted, isNotesEntry, isStartableDefinition, isSubjectEntry, isTelemetryEnvDenied, isTerminalActivityStatus, isTerminalStage, isTodoListEntry, isTodoListItem, isUnprimed, lakeGuardId, latestDeployedDefinitions, lintEffectOutputs, minReaderModelOf, missingRequiredInputs, modelVersionOf, narrateAutonomyWaits, noopTelemetry, parentRef, parseDefinitionInput, parseDefinitionSnapshot, parseGdr, parseGuardDocument, parseInstanceDocument, parseResourceGdr, processShellUserProperties, projectToWatchRef, quoted2 as quoted, readInstanceDoc, readsRaw, readsRootDocument, refCanvas, refDashboard, refDataset, refMediaLibrary, rejectedRefTypes, releaseDocId, releaseRef, remediationsFor, resolveAccess, resolveFieldEntry$1 as resolveFieldEntry, resourceAliasesToMap, resourceFromParsed, resourceGdr, retractStageGuards, sameResource, schemaTreeShape, sentenceCase, silentLogger, stageAutonomyOf, startFieldsParam, startKindOf, startRefusal, stripSystemFields, subjectDenialLabels, subscriptionDocument, subscriptionDocumentsForInstance, sweepStaleClaims, tagScopeFilter, terminalState, toBareId, tryParseGdr, unboundAllowedReads, unsatisfiedTransitionSummaries, validateDefinition, validateTag, verdictGuardsForInstance, wallClock, whatIfCondition2 as whatIfCondition, withAssignment, workflow };
+export { ACTION_SEMANTICS, ACTIVITY_KINDS, ACTIVITY_KIND_DISPLAY, ACTOR_KINDS, AUTHORING_DISPLAY, ActionDisabledError, ActionParamsInvalidError, CONDITION_VARS, CONTEXT_ENTRY_DISPLAY, CascadeLimitError, ConcurrentCompleteEffectError, ConcurrentEditFieldError, ConcurrentFireActionError, ContractViolationError, DATA_MODEL_CHANGES, DATA_MODEL_MIN_READER, DATA_MODEL_VERSION, DEFAULT_CONTENT_PERSPECTIVE, DEFAULT_EFFECT_LEASE_MS, DEFAULT_IDEMPOTENCY_TTL_MS, DEFAULT_TRANSITION_WHEN, DISPLAY, DRIVER_KINDS, DRIVER_KIND_DISPLAY, DefinitionInUseError, DefinitionNotFoundError, ENGINE_API_VERSION, EXECUTION_KINDS, EXECUTOR_CLASSIFICATIONS, EXECUTOR_CLASSIFICATION_DISPLAY, EditFieldDeniedError, EffectNotFoundError, EffectOpsInvalidError, EffectOutputsInvalidError, FIELD_KIND_DISPLAY, FILTER_SCOPE_VARS, FieldValueShapeError, GROUP_KINDS, GROUP_KIND_DISPLAY, GUARD_DOC_TYPE, GUARD_OWNER, GUARD_PREDICATE_VARS, HISTORY_DISPLAY, InitialFieldsInvalidError, InstanceNotFoundError, MAX_COUNTERFACTUAL_INDEX2 as MAX_COUNTERFACTUAL_INDEX, MissingHandlerError, ModelVersionAheadError, MutationGuardDeniedError, MutationGuardDocSchema, OP_DISPLAY, PartialGuardDeployError, PersistedDocShapeError, READER_MODEL_ROLLOUT_URL, RESERVED_CONDITION_VARS, ReaderModelAcknowledgementError, RefResourceUndeclaredError, RequiredFieldNotProvidedError, START_ALLOWED_VARS, START_FILTER_VARS, SpawnContractsInvalidError, StartNotAllowedError, StartNotPrimedError, StartNotSettledError, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, WorkflowActionFired, WorkflowDefinitionDeleted, WorkflowDefinitionDeployed, WorkflowEffectCompleted, WorkflowEffectsDrained, WorkflowError, WorkflowFieldEdited, WorkflowInstanceAborted, WorkflowInstanceSchema, WorkflowInstanceStarted, WorkflowInstanceTicked, WorkflowStageSet, WorkflowStageTransitioned, WorkflowStateDivergedError, abortReason, acceptsDocumentType, aclPathForResource, actionDisabledDetail, actionRendering, actionVerdict, activityAutonomyOf, analyzeCondition2 as analyzeCondition, applicableDefinitions, assertReadableModel, assertReaderModelAcknowledgement, atomReadsDataset2 as atomReadsDataset, autonomySummary, availableActions, buildInitialFields, buildSnapshot, checklistLines, clientConfigFromResource, clientProjectUserDirectory, compileGuard, computeDiffEntries, conditionFieldReadNames, conditionSitesOf, contentDocQuery, contentDraftFallback, contentReleaseName, contextMap, createEngine, createTelemetryIntake, datasetResourceParts, defaultLoggerFactory, definitionDeployedData, definitionLookupGroq, definitionsListGroq, deniedGuardLabels, deniedGuardRefs, denyingGuards, deployStageGuards, deriveActivityKind, deriveExecutorClassification, deriveWorkflowAutonomy, describeAtom, describeAutonomyWait, describeCondition, describeDefinition, describeFieldInsight, describeNode, describeSite, describeSiteHeading, diagnoseInputFromEvaluation, diagnoseInstance, diffEntry, displayDescription, displayTitle, documentActionDenials, documentPrefilter, driverKind, effectOutputsMap, entryDocRefs, errorMessage, evaluateFromSnapshot, evaluateMutationGuard, evaluateStartFilter, expandResourceAliases, explainCondition2 as explainCondition, explainStartAllowed, extractDocumentId, fieldTreeShape, findCurrentActivityEntry, findOpenStageEntry, formatRead, gdrFromResource, gdrRef, gdrUri, groupMembershipNames, groupSitesOf, guardMatches, guardsForDefinition, guardsForInstance, guardsForResource, guillemets2 as guillemets, hashDefinitionContent, humanize2 as humanize, inFlightFilter, initialFieldIssues, instanceDocId, instanceGuardQuery, instanceWatchesDocument, instancesQuery, isCascadeFired, isClaimExpired, isComparisonOp, isDefinitionApplicable, isFilterScopedOut, isGdr, isInputSourced, isNotesEntry, isProjectUserNotFoundError, isSingleDocRefEntry, isSingleDocRefKind, isStartableDefinition, isSubjectEntry, isTelemetryEnvDenied, isTerminalActivityStatus, isTerminalStage, isTodoListEntry, isTodoListItem, isUnprimed, lakeGuardId, latestDeployedDefinitions, lintEffectOutputs, minReaderModelOf, missingRequiredInputs, modelVersionOf, narrateAutonomyWaits, noopTelemetry, parentRef, parseDefinitionInput, parseDefinitionSnapshot, parseGdr, parseGuardDocument, parseInstanceDocument, parseResourceGdr, processShellUserProperties, projectToWatchRef, quoted2 as quoted, readInstanceDoc, readsRaw, readsRootDocument, refCanvas, refDashboard, refDataset, refKindAcceptsTypes, refMediaLibrary, refsOf, rejectedRefTypes, releaseDocId, releaseRef, remediationsFor, requiredModelFeatures, requiredReaderModel, resolveAccess, resolveActor, resolveClientActor, resolveFieldEntry$1 as resolveFieldEntry, resourceAliasesToMap, resourceFromParsed, resourceGdr, retractStageGuards, sameResource, scalarValidationIssues, schemaTreeShape, sentenceCase, silentLogger, stageAutonomyOf, startFieldsParam, startKindOf, startRefusal, stripSystemFields, subjectDenialLabels, subscriptionDocument, subscriptionDocumentsForInstance, sweepStaleClaims, tagScopeFilter, terminalState, toBareId, tryParseGdr, unboundAllowedReads, unsatisfiedTransitionSummaries, validateDefinition, validateTag, verdictGuardsForInstance, wallClock, whatIfCondition2 as whatIfCondition, withAssignment, workflow };