@sanity/workflow-engine 0.17.0 → 0.19.0

package/dist/_chunks-es/invariants.js

@@ -4,6 +4,317 @@ 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 = 3, 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."
+}), Object.freeze({
+    id: "progress-field-kind",
+    introducedInModel: 3,
+    minReaderModel: 0,
+    documentTypes: Object.freeze([ "definition", "instance" ]),
+    compatibility: "additive",
+    applicability: "detectable",
+    summary: "A progress field kind carries application-defined 0–100 completion."
+}), Object.freeze({
+    id: "effect-claim-tokens",
+    introducedInModel: 3,
+    minReaderModel: 0,
+    documentTypes: Object.freeze([ "instance" ]),
+    compatibility: "additive",
+    applicability: "detectable",
+    summary: "Pending-effect claims carry an exact-claim token gating mid-dispatch state reports."
+}) ]);
+
+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 hasFieldKind(document, kind) {
+    return persistedFieldEntries(document).some(entry => entry.type === kind || entry._type === kind);
+}
+
+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";
+    });
+}
+
+function hasClaimTokens(document) {
+    const root = recordOf(document);
+    return root === void 0 ? !1 : recordsAt(root, "pendingEffects").some(entry => {
+        const claim = recordOf(entry.claim);
+        return claim !== void 0 && typeof claim.claimToken == "string";
+    });
+}
+
+const featureDetectors = {
+    "governed-model-stamps": () => !0,
+    "subject-field-kind": document => hasFieldKind(document, "subject"),
+    "typed-scalar-choice-lists": hasChoiceList,
+    "action-semantics": hasActionSemantics,
+    "inclusive-scalar-bounds": hasScalarValidation,
+    "progress-field-kind": document => hasFieldKind(document, "progress"),
+    "effect-claim-tokens": hasClaimTokens
+};
+
+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 +335,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,71 +535,6 @@ 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 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) {
@@ -321,7 +557,13 @@ function asPredicate(validate) {
     };
 }
 
-const isValidTag = asPredicate(validateTag), isValidAliasName = asPredicate(validateResourceAliasName), isValidDatasetId = asPredicate(datasetResourceParts), WorkflowResourceSchema = v.variant("type", [ v.object({
+const isValidTag = asPredicate(validateTag), isValidAliasName = asPredicate(validateResourceAliasName), isValidDatasetId = asPredicate(datasetResourceParts);
+
+function lakeSegment(label) {
+    return v.pipe(v.string(), v.nonEmpty(), v.check(isValidTag, `invalid ${label} — ${LAKE_ID_SEGMENT_GLOSS}`));
+}
+
+const WorkflowResourceSchema = v.variant("type", [ v.object({
     type: v.literal("dataset"),
     id: v.pipe(NonEmptyString$1, v.check(isValidDatasetId, 'invalid dataset resource id — expected "<projectId>.<dataset>"'))
 }), v.object({
@@ -337,13 +579,46 @@ const isValidTag = asPredicate(validateTag), isValidAliasName = asPredicate(vali
     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$1,
-    tag: v.pipe(v.string(), v.nonEmpty(), v.check(isValidTag, "invalid tag — lowercase letters, digits and dashes only, no leading dash, no dots")),
+    name: lakeSegment("name"),
+    expectedMinReaderModel: v.optional(v.custom(() => !0), void 0),
+    tag: lakeSegment("tag"),
     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"))),
+    resourceAliases: v.optional(v.pipe(v.array(ResourceBindingSchema), v.check(bindings => duplicateHandleMessage(bindings) === void 0, issue => duplicateHandleMessage(issue.input) ?? "duplicate resource handle name"))),
     definitions: v.pipe(v.array(DefinitionSchema), v.minLength(1, "a deployment needs at least one definition"))
-}), TelemetryLoggerSchema = v.custom(input => typeof input == "object" && input !== null && typeof input.log == "function", "expected a telemetry logger (an object with a `log` function)"), WorkflowConfigSchema = v.object({
-    deployments: v.pipe(v.array(DeploymentSchema), v.minLength(1, "a config needs at least one deployment"), v.check(deployments => new Set(deployments.map(deployment => deployment.tag)).size === deployments.length, "duplicate deployment tag — each deployment must use a unique tag")),
+});
+
+function firstDuplicatePair(items, keyOf) {
+    const seen = /* @__PURE__ */ new Map;
+    for (const item of items) {
+        const key = keyOf(item), earlier = seen.get(key);
+        if (earlier !== void 0) return [ earlier, item ];
+        seen.set(key, item);
+    }
+}
+
+function duplicateHandleMessage(bindings) {
+    const pair = firstDuplicatePair(bindings, binding => binding.name);
+    if (pair !== void 0) return `duplicate resource handle name "${pair[1].name}" — each binding name must be unique within a deployment`;
+}
+
+function duplicateNameMessage(deployments) {
+    const pair = firstDuplicatePair(deployments, deployment => deployment.name);
+    if (pair !== void 0) return `duplicate deployment name "${pair[1].name}" — each deployment must use a unique name`;
+}
+
+function partitionKey(deployment) {
+    return `${resourceGdr(deployment.workflowResource)} ${deployment.tag}`;
+}
+
+function partitionCollisionMessage(deployments) {
+    const pair = firstDuplicatePair(deployments, partitionKey);
+    if (pair === void 0) return;
+    const [first, second] = pair;
+    return `deployments "${first.name}" and "${second.name}" share workflow resource + tag "${second.tag}" — both would write into the same partition; change one deployment’s tag or resource`;
+}
+
+const TelemetryLoggerSchema = v.custom(input => typeof input == "object" && input !== null && typeof input.log == "function", "expected a telemetry logger (an object with a `log` function)"), WorkflowConfigSchema = v.object({
+    deployments: v.pipe(v.array(DeploymentSchema), v.minLength(1, "a config needs at least one deployment"), v.check(deployments => duplicateNameMessage(deployments) === void 0, issue => duplicateNameMessage(issue.input) ?? "duplicate deployment name"), v.check(deployments => partitionCollisionMessage(deployments) === void 0, issue => partitionCollisionMessage(issue.input) ?? "duplicate deployment partition")),
     telemetry: v.optional(TelemetryLoggerSchema)
 });
 
@@ -580,6 +855,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
@@ -722,7 +999,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;
@@ -743,18 +1020,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,
@@ -765,9 +1039,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),
@@ -1154,7 +1451,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",
@@ -1163,7 +1460,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 wrapper). Stage/activity scopes overlay lexically. What a read puts in your hand follows the declared kind: a singular `doc.ref` DEREFERENCES into the hydrated document (lake `_id`/`_type` plus content fields — which may themselves be named `id`/`type`), while `doc.refs` elements and `release.ref` stay REFERENCES — `{id, type[, releaseName]}` with `id` a GDR URI — because identity reads (membership, counting, joins) must stay total without hydrating every target, and targets may live in resources the evaluation cannot fetch from. Conditions evaluate against the in-memory snapshot only, so a dereferencing plural kind would silently hole wherever hydration lagged."
+    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",
@@ -1244,18 +1541,26 @@ 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",
+    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 caller's input entries by name (`initialFields` — at `startInstance`, the values the start would seed; at a pre-flight, the values gathered so far, so a read of a not-yet-supplied entry is GROQ null). Document references bind as GDR envelopes — `$fields.<entry>.id` is the GDR URI, never a string authors assemble — a singular `doc.ref` included (nothing hydrates at the gate or the pre-flight). Pathed reads are deploy-checked against these envelope shapes."
+    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)."
@@ -1405,6 +1710,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;
@@ -1455,13 +1772,39 @@ const GdrUriSchema = v.custom(s => typeof s == "string" && isGdrUri(s), "must be
 }), tolerantObject()({
     type: v.literal("role"),
     role: NonEmptyString
-}) ]), NullableString = v.union([ v.null(), v.string() ]), NullableNumber = v.union([ v.null(), v.number() ]), NullableBoolean = v.union([ v.null(), v.boolean() ]), NullableDateTime = v.union([ v.null(), IsoTimestamp ]), NullableDate = v.union([ v.null(), v.pipe(v.string(), v.regex(/^\d{4}-\d{2}-\d{2}$/, "must be a `YYYY-MM-DD` date")) ]), NullableUrl = NullableString, fieldValueSchemas = {
+}) ]), NullableString = v.union([ v.null(), v.string() ]), NullableNumber = v.union([ v.null(), v.number() ]), NullableBoolean = v.union([ v.null(), v.boolean() ]), NullableProgress = v.union([ v.null(), v.pipe(v.number(), v.finite("progress must be a finite number"), v.minValue(0, "progress must be at least 0"), v.maxValue(100, "progress must be at most 100")) ]), 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 ]),
     string: NullableString,
     text: NullableString,
     number: NullableNumber,
+    progress: NullableProgress,
     boolean: NullableBoolean,
     date: NullableDate,
     datetime: NullableDateTime,
@@ -1475,7 +1818,56 @@ const GdrUriSchema = v.custom(s => typeof s == "string" && isGdrUri(s), "must be
 };
 
 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" || entryType === "progress") && 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" || entryType === "progress" ? "" : "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) {
@@ -1498,7 +1890,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))) ];
@@ -1533,6 +1925,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);
 }
 
@@ -1563,6 +1959,7 @@ const AuthoringRefId = v.pipe(v.string(), v.check(isAuthoringRefId, "must be a b
     ...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"),
@@ -1602,10 +1999,10 @@ 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)}`;
     });
 }
 
@@ -1731,7 +2128,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", "progress", "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 : {};
@@ -1765,14 +2170,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 {
@@ -1790,6 +2197,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))
@@ -1802,7 +2211,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
     });
 }
 
@@ -1811,10 +2222,41 @@ 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", "progress" ]);
+
+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\` / \`progress\` values, not "${type}"` ];
+    if (type === "progress") {
+        const issues2 = Object.entries(validation).flatMap(([bound, value]) => typeof value == "number" && value >= 0 && value <= 100 ? [] : [ `\`validation.${bound}\` must stay within the progress kind's 0–100 contract` ]);
+        return issues2.length === 0 ? void 0 : issues2;
+    }
+    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()),
@@ -1845,17 +2287,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),
@@ -2044,7 +2494,7 @@ 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) {
@@ -2546,6 +2996,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);
@@ -2596,12 +3092,30 @@ function checkStart(def, issues) {
     if (def.start !== void 0 && (def.lifecycle === "child" && issues.push({
         path: [ "start" ],
         message: "a spawn-only (lifecycle 'child') definition declares `start` — children are instantiated by a parent's `spawn`, never started standalone, so the block would never apply. Remove `start`, or drop `lifecycle: 'child'`"
-    }), checkStartFilterReads(def, issues), checkStartAllowedReads(def, issues), def.start.kind === "autonomous")) for (const [n, entry] of (def.fields ?? []).entries()) entry.required !== !0 || isSubjectEntry(entry) || issues.push({
+    }), 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;
     filter !== void 0 && (conditionParameterNames(filter).has("fields") && issues.push({
@@ -2609,7 +3123,7 @@ function checkStartFilterReads(def, issues) {
         message: "start.filter reads $fields, but the filter is browse-time-pure — a start surface evaluates it per document, before any inputs exist, so $fields cannot be bound. Move the input-dependent rule to start.allowed, the start-time permission predicate that binds $fields and is enforced by startInstance"
     }), readsRootDocument(filter) && !(def.fields ?? []).some(isSubjectEntry) && issues.push({
         path: [ "start", "filter" ],
-        message: "start.filter reads the candidate document (its root), but the definition declares no required subject entry (a required doc.ref / doc.refs input) — a read surface would never have a document to bind as root, so every root read is GROQ null and the filter silently misevaluates. Declare a required subject entry, or gate on the dataset instead"
+        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"
     }));
 }
 
@@ -2926,7 +3440,7 @@ function checkFieldReadOpValues(def, issues) {
         ops: site.ops,
         path: site.path,
         label: site.label,
-        activityEntries: entryMap(site.activity.fields)
+        activityEntries: site.activity.fields ?? []
     });
 }
 
@@ -2948,6 +3462,9 @@ function fieldReadsIn(value, path) {
 
 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
     }, {
@@ -2960,8 +3477,7 @@ function checkOpFieldRead({read: read, where: where, path: path, workflowEntries
             message: opFieldReadMissMessage({
                 read: read,
                 where: where,
-                hosts: hosts,
-                activityEntries: activityEntries
+                hosts: hosts
             })
         });
         return;
@@ -2975,9 +3491,9 @@ function checkOpFieldRead({read: read, where: where, path: path, workflowEntries
     });
 }
 
-function opFieldReadMissMessage({read: read, where: where, hosts: hosts, activityEntries: activityEntries}) {
-    const searched = read.scope === void 0 ? "stage or workflow scope" : `${read.scope} scope`, activityHint = activityEntries?.has(read.field) ? ` "${read.field}" is an activity-scope field, and op-time field reads resolve against stage and workflow scopes only — declare it at stage scope to read it from an op.` : "", known = hosts.flatMap(host => host.entries.map(entry => `${host.scope}:${entry.name}`));
-    return `${where} reads field "${read.field}", which is not declared at ${searched} — the read resolves to undefined at op time, so the write silently lands empty.${activityHint} Known: ${known.join(", ") || "(none)"}`;
+function 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) {
@@ -3140,10 +3656,12 @@ const SCALAR = {
         kind: "list",
         item: GDR_VALUE
     }),
+    subject: () => DOC_CONTENT,
     "release.ref": () => RELEASE_VALUE,
     string: () => SCALAR,
     text: () => SCALAR,
     number: () => SCALAR,
+    progress: () => SCALAR,
     boolean: () => SCALAR,
     date: () => SCALAR,
     datetime: () => SCALAR,
@@ -3164,7 +3682,8 @@ const SCALAR = {
     })
 }, START_ALLOWED_VALUE_NODES = {
     ...VALUE_NODES,
-    "doc.ref": () => GDR_VALUE
+    "doc.ref": () => GDR_VALUE,
+    subject: () => GDR_VALUE
 };
 
 function valueNodeFor(shape, nodes) {
@@ -3236,9 +3755,10 @@ function checkWorkflowInvariants(def) {
     checkRequiredField(def, issues), checkStart(def, issues), checkPredicates(def, issues), 
     checkUnboundConditionVars(def, issues), checkConditionFieldReads(def, issues), checkFieldReadSeeds(def, issues), 
     checkFieldReadOpValues(def, issues), checkUpdateWhereOps(def, issues), checkGuardFieldReads(def, issues), 
-    checkAssigneesEntries(def, issues), checkActivityTerminalPaths(def, issues), checkTerminalStageActivities(def, issues), 
+    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, ACTIVITY_STATUSES, ACTOR_KINDS, ActorShape, AuthoringActionSchema, AuthoringActivitySchema, AuthoringFieldEntrySchema, AuthoringGuardSchema, AuthoringOpSchema, AuthoringStageSchema, AuthoringTransitionSchema, AuthoringWorkflowSchema, CALLER_BOUND_VARS, CONDITION_VARS, ContractViolationError, DEFAULT_TRANSITION_WHEN, DOCUMENT_VALUE_PERMISSIONS, DRIVER_KINDS, DefinitionInUseError, DefinitionNotFoundError, EFFECTS_READ, EXECUTOR_CLASSIFICATIONS, EffectNotFoundError, EffectSchema, FIELD_READ, FIELD_SCOPES, FIELD_VALUE_KINDS, FILTER_SCOPE_VARS, FieldValueShapeError, GROUP_KINDS, GUARD_PREDICATE_VARS, GdrShape, GroupSchema, InstanceNotFoundError, IsoTimestamp, MUTATION_GUARD_ACTIONS, NonEmptyString, PersistedDocShapeError, RESERVED_CONDITION_VARS, RESOURCE_ALIAS_NAME_SOURCE, START_ALLOWED_VARS, START_FILTER_VARS, StoredFieldOpSchema, WORKFLOW_DEFINITION_TYPE, WorkflowConfigSchema, WorkflowError, actorFulfillsRole, andConditions, checkFieldValue, checkWorkflowInvariants, clientConfigFromResource, conditionEffectReads, conditionFieldReadNames, conditionParameterNames, conditionSyntaxIssues, datasetResourceParts, definitionDocId, deriveActivityKind, deriveExecutorClassification, desugarWorkflow, driverKind, errorMessage, evaluateCondition, evaluateConditionOutcome, evaluatePredicates, extractDocumentId, fieldValueSchemas, formatIssuePath, formatIssues, formatValidationError, gdrFromResource, gdrRef, gdrResourcePrefix, gdrUri, groq, groupMembershipNames, isBareSeedId, isCascadeFired, isGdr, isGdrUri, isGuardReadExpr, isInputSourced, isNotesEntry, isParseableInstant, isStartableDefinition, isSubjectEntry, isTerminalActivityStatus, isTodoListEntry, isTodoListItem, isUnevaluable, labelFor, parseGdr, parseOrThrow, parsePersistedDoc, parseResourceGdr, parseStoredDefinition, readsRootDocument, refCanvas, refDashboard, refDataset, refMediaLibrary, refTypeIssues, rejectedRefTypes, releaseDocId, releaseRef, resourceAliasesToMap, resourceFromGdrUri, resourceFromParsed, resourceGdr, rethrowWithContext, runGroq, sameResource, schemaTreeShape, selfGdr, startKindOf, tagScopeFilter, toBareId, toPhysicalGdr, tolerantEntries, tolerantObject, tryParseGdr, validateFieldAppendItem, validateFieldValue, validateResourceAliasName, validateTag };
+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 };