@sanity/workflow-engine 0.19.0 → 0.21.0

package/dist/_chunks-es/invariants.js

@@ -4,6 +4,8 @@ import { conditionOutcome, runGroq as runGroq$1, evaluateConditionOutcome as eva
 
 import { parse } from "groq-js";
 
+import { isDraftId, isVersionId, getPublishedId } from "@sanity/id-utils";
+
 class WorkflowError extends Error {
     kind;
     constructor(kind, message, options) {
@@ -99,12 +101,33 @@ function isUnprimed(instance) {
 
 function parseDefinitionSnapshotValue(instance) {
     try {
-        return JSON.parse(instance.definitionSnapshot);
+        return normalizeLegacyActivityRequirements(JSON.parse(instance.definitionSnapshot));
     } catch (err) {
         rethrowWithContext(err, `Failed to parse definitionSnapshot on instance "${instance._id}"`);
     }
 }
 
+function normalizeLegacyActivityRequirements(value) {
+    for (const stage of arrayMember(value, "stages")) for (const activity of arrayMember(stage, "activities")) normalizeLegacyRequirementMap(activity);
+    return value;
+}
+
+function arrayMember(value, key) {
+    if (typeof value != "object" || value === null) return [];
+    const member = value[key];
+    return Array.isArray(member) ? member : [];
+}
+
+function normalizeLegacyRequirementMap(value) {
+    if (typeof value != "object" || value === null) return;
+    const activity = value, requirements = activity.requirements;
+    typeof requirements != "object" || requirements === null || Array.isArray(requirements) || (activity.requirements = Object.entries(requirements).map(([name, query]) => ({
+        type: "groq",
+        name: name,
+        query: query
+    })));
+}
+
 function parseDefinitionSnapshot(instance) {
     return parseDefinitionSnapshotValue(instance);
 }
@@ -113,7 +136,7 @@ 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";
+const DATA_MODEL_VERSION = 4, DATA_MODEL_MIN_READER = 4, 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";
@@ -123,7 +146,7 @@ class ReaderModelAcknowledgementError extends WorkflowError {
     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}`), 
+        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. Instances written before the new floor may stop matching user-identity queries, and older readers refuse documents this engine touches — a prerelease deployment with no data worth migrating can reset every engine-owned document with \`sanity-workflows nuke\` and start fresh. ${READER_MODEL_ROLLOUT_URL}`), 
         this.name = "ReaderModelAcknowledgementError", this.expectedMinReaderModel = expectedMinReaderModel;
     }
 }
@@ -188,6 +211,22 @@ const DATA_MODEL_CHANGES = Object.freeze([ Object.freeze({
     compatibility: "additive",
     applicability: "detectable",
     summary: "Pending-effect claims carry an exact-claim token gating mid-dispatch state reports."
+}), Object.freeze({
+    id: "classified-principal-ids",
+    introducedInModel: 4,
+    minReaderModel: 4,
+    documentTypes: Object.freeze([ "instance" ]),
+    compatibility: "reader-floor",
+    applicability: "unconditional",
+    summary: "Principal ids are namespace-classified: actor and assignee writes carry the account-global user id only, and readers resolve legacy project-scoped ids through the prefix classifier at the instance read funnel."
+}), Object.freeze({
+    id: "readiness-requirements",
+    introducedInModel: 4,
+    minReaderModel: 4,
+    documentTypes: Object.freeze([ "definition" ]),
+    compatibility: "reader-floor",
+    applicability: "detectable",
+    summary: "Start and activity readiness use named polymorphic requirement arrays."
 }) ]);
 
 function recordOf(value) {
@@ -248,6 +287,11 @@ function hasClaimTokens(document) {
     });
 }
 
+function hasReadinessRequirements(document) {
+    const root = recordOf(document);
+    return root === void 0 ? !1 : Array.isArray(recordOf(root.start)?.requirements) ? !0 : recordsAt(root, "stages").some(stage => recordsAt(stage, "activities").some(activity => Array.isArray(activity.requirements)));
+}
+
 const featureDetectors = {
     "governed-model-stamps": () => !0,
     "subject-field-kind": document => hasFieldKind(document, "subject"),
@@ -255,7 +299,9 @@ const featureDetectors = {
     "action-semantics": hasActionSemantics,
     "inclusive-scalar-bounds": hasScalarValidation,
     "progress-field-kind": document => hasFieldKind(document, "progress"),
-    "effect-claim-tokens": hasClaimTokens
+    "effect-claim-tokens": hasClaimTokens,
+    "classified-principal-ids": () => !0,
+    "readiness-requirements": hasReadinessRequirements
 };
 
 function requiredModelFeatures(documentType, document) {
@@ -269,7 +315,7 @@ function requiredReaderModel(documentType, document) {
 function modelStampFor(args) {
     return {
         modelVersion: DATA_MODEL_VERSION,
-        minReaderModel: Math.max(args.storedMinReaderModel ?? 0, requiredReaderModel(args.documentType, args.document))
+        minReaderModel: Math.max(DATA_MODEL_MIN_READER, args.storedMinReaderModel ?? 0, requiredReaderModel(args.documentType, args.document))
     };
 }
 
@@ -342,6 +388,21 @@ function andConditions(parts) {
 
 const KNOWN_SCHEMES = /* @__PURE__ */ new Set([ "dataset", "canvas", "media-library", "dashboard" ]), KNOWN_SCHEMES_TEXT = [ ...KNOWN_SCHEMES ].join(", ");
 
+class VersionSpecificDatasetGdrError extends Error {
+    documentId;
+    stableDocumentId;
+    constructor(documentId, uri) {
+        const stableDocumentId = getPublishedId(documentId);
+        super(`Invalid GDR "${uri}": dataset document ID "${documentId}" identifies a stored draft or release version. Use the stable document ID "${stableDocumentId}" and select drafts/releases through the workflow perspective.`), 
+        this.name = "VersionSpecificDatasetGdrError", this.documentId = documentId, this.stableDocumentId = stableDocumentId;
+    }
+}
+
+function assertStableDatasetDocumentId(documentId, uri) {
+    const sanityId = documentId;
+    if (!(!isDraftId(sanityId) && !isVersionId(sanityId))) throw new VersionSpecificDatasetGdrError(documentId, uri);
+}
+
 function parseGdr(uri) {
     const colon = uri.indexOf(":");
     if (colon < 0) throw new Error(`Invalid GDR "${uri}": must be a URI of form "<scheme>:<...id-parts>". Known schemes: ${KNOWN_SCHEMES_TEXT}.`);
@@ -351,11 +412,12 @@ function parseGdr(uri) {
     if (parts.some(part => part.length === 0)) throw new Error(`Invalid GDR "${uri}": id parts must be non-empty (no leading, trailing, or doubled ":").`);
     if (scheme === "dataset") {
         if (parts.length !== 3) throw new Error(`Invalid GDR "${uri}": dataset scheme requires <projectId>:<dataset>:<documentId> (3 parts after scheme); got ${parts.length}.`);
-        return {
+        const documentId = parts[2];
+        return assertStableDatasetDocumentId(documentId, uri), {
             scheme: "dataset",
             projectId: parts[0],
             dataset: parts[1],
-            documentId: parts[2]
+            documentId: documentId
         };
     }
     if (parts.length !== 2) throw new Error(`Invalid GDR "${uri}": ${scheme} scheme requires <resourceId>:<documentId> (2 parts after scheme); got ${parts.length}.`);
@@ -375,7 +437,11 @@ function tryParseGdr(uri) {
 }
 
 function gdrUri(parts) {
-    return parts.scheme === "dataset" ? `dataset:${parts.projectId}:${parts.dataset}:${parts.documentId}` : `${parts.scheme}:${parts.resourceId}:${parts.documentId}`;
+    if (parts.scheme === "dataset") {
+        const uri = `dataset:${parts.projectId}:${parts.dataset}:${parts.documentId}`;
+        return assertStableDatasetDocumentId(parts.documentId, uri), uri;
+    }
+    return `${parts.scheme}:${parts.resourceId}:${parts.documentId}`;
 }
 
 function extractDocumentId(gdrUriString) {
@@ -778,8 +844,8 @@ function desugarStart(start) {
         ...start.filter !== void 0 ? {
             filter: start.filter
         } : {},
-        ...start.allowed !== void 0 ? {
-            allowed: start.allowed
+        ...start.requirements !== void 0 ? {
+            requirements: start.requirements
         } : {}
     };
 }
@@ -1541,7 +1607,7 @@ const ACTION_SEMANTICS = [ "decision.accept", "decision.decline" ], FIELD_SCOPES
     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`."
-} ], 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 = [ {
+} ], RESERVED_CONDITION_VARS = CONDITION_VARS.map(v2 => v2.name), FILTER_SCOPE_VARS = CONDITION_VARS.filter(v2 => v2.binding === "always").map(v2 => v2.name), CALLER_BOUND_VARS = CONDITION_VARS.filter(v2 => v2.binding === "caller").map(v2 => v2.name), START_FILTER_VARS = [ {
     name: "tag",
     label: "this engine tag",
     description: "The engine's tag partition — scope `*[...]` instance scans with `tag == $tag`."
@@ -1553,11 +1619,7 @@ const ACTION_SEMANTICS = [ "decision.accept", "decision.decline" ], FIELD_SCOPES
     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, {
+} ], START_REQUIREMENT_VARS = [ ...START_FILTER_VARS, {
     name: "fields",
     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."
@@ -1742,6 +1804,37 @@ function isNotesEntry(entry) {
     return columns !== void 0 && columns.has("body") && columns.has("actor") && columns.has("at");
 }
 
+const ANONYMOUS_IDENTITY = "<anonymous>", SYSTEM_IDENTITY = "<system>", E_PREFIXED_PROJECT_ID = /^e-(.+)$/;
+
+function classifyPrincipalId(id) {
+    if (id === ANONYMOUS_IDENTITY || id === SYSTEM_IDENTITY) return {
+        namespace: "sentinel"
+    };
+    if (id.startsWith("g")) return {
+        namespace: "global",
+        globalId: id
+    };
+    if (id.startsWith("p-")) return {
+        namespace: "robot",
+        globalId: id
+    };
+    const embeddedGlobal = E_PREFIXED_PROJECT_ID.exec(id)?.[1];
+    return embeddedGlobal !== void 0 ? embeddedGlobal.startsWith("g") ? {
+        namespace: "project",
+        globalId: embeddedGlobal
+    } : {
+        namespace: "unknown"
+    } : id.startsWith("p") ? {
+        namespace: "project"
+    } : {
+        namespace: "unknown"
+    };
+}
+
+function lakePrincipalId(args) {
+    return args.localPrincipalId ?? args.actor.id;
+}
+
 class FieldValueShapeError extends WorkflowError {
     entryType;
     entryName;
@@ -1782,11 +1875,11 @@ 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({
+    const kind = normalizedChoiceKind(entryType), issues = options.list.flatMap((option, index) => issuesOf(checkValueAgainst({
         entryType: kind,
         value: option.value,
         validation: validation
-    }, valueSchemas)?.map(issue => `at options.list.${index}.value: ${issue}`) ?? []), seen = /* @__PURE__ */ new Set;
+    }, 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;
@@ -1812,8 +1905,27 @@ const fieldValueSchemas = {
     actor: v.union([ v.null(), ActorShape ]),
     assignee: v.union([ v.null(), AssigneeShape ]),
     assignees: v.array(AssigneeShape)
-}, valueSchemas = {
+}, WritePrincipalId = v.pipe(NonEmptyString, v.rawTransform(({dataset: dataset, addIssue: addIssue}) => {
+    const classified = classifyPrincipalId(dataset.value);
+    return classified.namespace === "global" || classified.namespace === "robot" ? dataset.value : classified.namespace === "project" && classified.globalId !== void 0 ? classified.globalId : (addIssue({
+        message: `principal id "${dataset.value}" is not an account-global user id. Workflow user ids are the global \`sanityUserId\` (or a robot token's id). Resolve project members through your surface's member hook, or /projects/<projectId>/users/<id> → sanityUserId.`
+    }), dataset.value);
+})), ActorWriteShape = tolerantObject()({
+    kind: v.picklist(ACTOR_KINDS),
+    id: WritePrincipalId,
+    roles: v.exactOptional(v.array(v.string())),
+    onBehalfOf: v.exactOptional(v.string())
+}), AssigneeWriteShape = v.union([ tolerantObject()({
+    type: v.literal("user"),
+    id: WritePrincipalId
+}), tolerantObject()({
+    type: v.literal("role"),
+    role: NonEmptyString
+}) ]), valueSchemas = {
     ...fieldValueSchemas,
+    actor: v.nullable(ActorWriteShape),
+    assignee: v.nullable(AssigneeWriteShape),
+    assignees: v.array(AssigneeWriteShape),
     query: v.any()
 };
 
@@ -1884,7 +1996,7 @@ function wholeValueSchema(args) {
 function appendItemSchema(entryType, shape) {
     if (entryType === "array") return objectSchema(shape.of ?? [], valueSchemas);
     if (entryType === "doc.refs") return GdrShape;
-    if (entryType === "assignees") return AssigneeShape;
+    if (entryType === "assignees") return AssigneeWriteShape;
 }
 
 function rejectedRefTypes(args) {
@@ -1909,7 +2021,7 @@ function gdrTypeOf(item) {
     return typeof t == "string" ? t : void 0;
 }
 
-function checkFieldValue(args) {
+function parseFieldValue(args) {
     return checkValueAgainst(args, valueSchemas);
 }
 
@@ -1919,9 +2031,14 @@ function checkValueAgainst(args, leaf) {
         shape: args,
         leaf: leaf
     });
-    if (schema === void 0) return [ `unknown field entry type ${args.entryType}` ];
+    if (schema === void 0) return {
+        issues: [ `unknown field entry type ${args.entryType}` ]
+    };
     const result = v.safeParse(schema, args.value);
-    return result.success ? refTypeIssues({
+    if (!result.success) return {
+        issues: formatIssues(result.issues)
+    };
+    const postIssues = refTypeIssues({
         entryType: args.entryType,
         types: args.types,
         value: args.value
@@ -1929,17 +2046,27 @@ function checkValueAgainst(args, leaf) {
         entryType: args.entryType,
         validation: args.validation,
         value: args.value
-    }) : formatIssues(result.issues);
+    });
+    return postIssues !== void 0 ? {
+        issues: postIssues
+    } : {
+        output: result.output
+    };
+}
+
+function issuesOf(check) {
+    return "issues" in check ? check.issues : void 0;
 }
 
 function validateFieldValue(args) {
-    const issues = checkFieldValue(args);
-    if (issues !== void 0) throw new FieldValueShapeError({
+    const check = checkValueAgainst(args, valueSchemas);
+    if ("issues" in check) throw new FieldValueShapeError({
         entryType: args.entryType,
         entryName: args.entryName,
-        issues: issues,
+        issues: check.issues,
         mode: "value"
     });
+    return check.output;
 }
 
 const BARE_ID_SOURCE = "[A-Za-z0-9_][A-Za-z0-9._-]*", BARE_ID_RE = new RegExp(`^${BARE_ID_SOURCE}$`), ALIAS_REF_RE = new RegExp(`^@${RESOURCE_ALIAS_NAME_SOURCE}:${BARE_ID_SOURCE}$`);
@@ -1968,7 +2095,7 @@ const AuthoringRefId = v.pipe(v.string(), v.check(isAuthoringRefId, "must be a b
 };
 
 function checkLiteralSeed(args) {
-    return args.value === null ? [ "a literal seed cannot be null — omit `initialValue` to start the field empty" ] : checkValueAgainst(args, seedValueSchemas);
+    return args.value === null ? [ "a literal seed cannot be null — omit `initialValue` to start the field empty" ] : issuesOf(checkValueAgainst(args, seedValueSchemas));
 }
 
 function validateFieldAppendItem(args) {
@@ -1997,13 +2124,15 @@ function validateFieldAppendItem(args) {
         issues: typeIssues,
         mode: "item"
     });
+    return result.output;
 }
 
 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(".")}: ` : ""}${formatMessage(i)}`;
-    });
+    const formatOne = (issue, prefix) => {
+        const keys = [ ...prefix, ...issue.path?.map(p => p.key) ?? [] ], sub = issue.issues?.filter(candidate => candidate.expected !== "null");
+        return sub !== void 0 && sub.length > 0 ? sub.flatMap(candidate => formatOne(candidate, keys)) : [ `${keys.length > 0 ? `at ${keys.join(".")}: ` : ""}${formatMessage(issue)}` ];
+    };
+    return issues.flatMap(issue => formatOne(issue, []));
 }
 
 const NonEmpty = NonEmptyString, PositiveInt = v.pipe(v.number(), v.integer(), v.minValue(1)), GROQ_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -2013,7 +2142,15 @@ function groqIdentifier(referencedAs) {
 }
 
 function picklist(options) {
-    return v.picklist(options, `Invalid option: expected one of ${options.map(o => `"${o}"`).join("|")}`);
+    return v.picklist(options, invalidOptionMessage(options));
+}
+
+function invalidOptionMessage(options) {
+    return `Invalid option: expected one of ${options.map(option => `"${option}"`).join("|")}`;
+}
+
+function exhaustiveOptions() {
+    return options => options;
 }
 
 function pinned() {
@@ -2028,12 +2165,12 @@ const LiteralSchema = v.strictObject({
     scope: v.optional(v.union([ v.literal("workflow"), v.literal("stage") ])),
     field: NonEmpty,
     path: v.optional(v.string())
-}), FieldSourceSchema = v.union([ v.strictObject({
+}), FieldSourceSchema = v.variant("type", [ v.strictObject({
     type: v.literal("input")
 }), v.strictObject({
     type: v.literal("query"),
     query: NonEmpty
-}), LiteralSchema, FieldReadSchema ]), ValueExprSchema = v.lazy(() => v.union([ LiteralSchema, FieldReadSchema, v.strictObject({
+}), LiteralSchema, FieldReadSchema ]), ValueExprSchema = v.lazy(() => v.variant("type", [ LiteralSchema, FieldReadSchema, v.strictObject({
     type: v.literal("param"),
     param: NonEmpty
 }), v.strictObject({
@@ -2128,7 +2265,7 @@ function groupMembershipNames(group) {
     return group === void 0 ? [] : typeof group == "string" ? [ group ] : [ ...group ];
 }
 
-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({
+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), AUTHORING_FIELD_SUGAR_KINDS = exhaustiveOptions()([ "claim", "todoList", "notes" ]), AUTHORING_FIELD_KINDS = [ ...FIELD_VALUE_KINDS, ...AUTHORING_FIELD_SUGAR_KINDS ], AuthoringRawFieldKindSchema = v.picklist(FIELD_VALUE_KINDS, issue => `${invalidOptionMessage(AUTHORING_FIELD_KINDS)} but received ${JSON.stringify(issue.input)}`), 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({
@@ -2193,9 +2330,9 @@ function fieldBase(editable, group) {
     };
 }
 
-function fieldEntryFields(editable, group) {
+function fieldEntryFields({editable: editable, group: group, kind: kind = FieldKindSchema}) {
     return {
-        type: FieldKindSchema,
+        type: kind,
         ...fieldBase(editable, group),
         options: v.optional(ChoiceOptionsSchema),
         validation: v.optional(ScalarValidationSchema),
@@ -2256,7 +2393,14 @@ function scalarValidationDeclarationIssues(entry) {
     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({
+const FieldEntrySchema = pinned()(v.pipe(compositeChecked(fieldEntryFields({
+    editable: StoredEditableSchema,
+    group: StoredGroupMembershipSchema
+})), refTypesCheck(), choiceOptionsCheck(), scalarValidationCheck(), literalSeedCheck())), RawAuthoringFieldEntrySchema = pinned()(v.pipe(compositeChecked(fieldEntryFields({
+    editable: AuthoringEditableSchema,
+    group: AuthoringGroupMembershipSchema,
+    kind: AuthoringRawFieldKindSchema
+})), refTypesCheck(), choiceOptionsCheck(), scalarValidationCheck(), literalSeedCheck())), ClaimFieldSchema = pinned()(v.strictObject({
     type: v.literal("claim"),
     name: FieldEntryName,
     title: v.optional(v.string()),
@@ -2271,7 +2415,10 @@ function listSugarFields(type) {
     };
 }
 
-const TodoListFieldSchema = pinned()(v.strictObject(listSugarFields("todoList"))), NotesFieldSchema = pinned()(v.strictObject(listSugarFields("notes"))), AuthoringFieldEntrySchema = pinned()(v.union([ RawAuthoringFieldEntrySchema, ClaimFieldSchema, TodoListFieldSchema, NotesFieldSchema ])), EffectSchema = v.strictObject({
+const TodoListFieldSchema = pinned()(v.strictObject(listSugarFields("todoList"))), NotesFieldSchema = pinned()(v.strictObject(listSugarFields("notes"))), AuthoringFieldEntrySchema = pinned()(v.lazy(input => {
+    const type = asShape(input).type;
+    return type === "claim" ? ClaimFieldSchema : type === "todoList" ? TodoListFieldSchema : type === "notes" ? NotesFieldSchema : RawAuthoringFieldEntrySchema;
+})), EffectSchema = v.strictObject({
     name: NonEmpty,
     title: v.optional(v.string()),
     description: v.optional(v.string()),
@@ -2336,7 +2483,18 @@ const StoredActionSchema = pinned()(v.strictObject({
     filter: v.optional(ConditionSchema),
     params: v.optional(v.array(ActionParamSchema)),
     effects: v.optional(v.array(EffectSchema))
-})), AuthoringActionSchema = pinned()(v.lazy(input => typeof input == "object" && input !== null && "type" in input ? ClaimActionSchema : RawAuthoringActionSchema));
+})), AuthoringActionSchema = pinned()(v.lazy(input => typeof input == "object" && input !== null && "type" in input ? ClaimActionSchema : RawAuthoringActionSchema)), requirementBase = {
+    name: NonEmpty,
+    title: v.optional(v.string()),
+    description: v.optional(v.string())
+}, GroqRequirementSchemaRaw = v.strictObject({
+    ...requirementBase,
+    type: v.literal("groq"),
+    query: ConditionSchema
+}), SingleSubjectRequirementSchemaRaw = v.strictObject({
+    ...requirementBase,
+    type: v.literal("singleSubject")
+}), GroqRequirementSchema = pinned()(GroqRequirementSchemaRaw), StartRequirementSchema = pinned()(v.variant("type", [ GroqRequirementSchemaRaw, SingleSubjectRequirementSchemaRaw ]));
 
 function activityFields({field: field, action: action, target: target, group: group}) {
     return {
@@ -2347,7 +2505,7 @@ function activityFields({field: field, action: action, target: target, group: gr
         group: v.optional(group),
         target: v.optional(target),
         filter: v.optional(ConditionSchema),
-        requirements: v.optional(v.record(NonEmpty, ConditionSchema)),
+        requirements: v.optional(v.array(GroqRequirementSchema)),
         actions: v.optional(v.array(action)),
         fields: v.optional(v.array(field))
     };
@@ -2443,7 +2601,7 @@ function startFields(kind) {
     return {
         kind: kind,
         filter: v.optional(ConditionSchema),
-        allowed: v.optional(ConditionSchema)
+        requirements: v.optional(v.array(StartRequirementSchema))
     };
 }
 
@@ -2582,6 +2740,13 @@ function checkActivities({def: def, i: i, activityNames: activityNames, issues:
             })),
             what: `action name in activity "${activity.name}"`,
             issues: issues
+        }), checkDuplicates({
+            names: (activity.requirements ?? []).map((requirement, r) => ({
+                name: requirement.name,
+                path: [ ...path, "requirements", r, "name" ]
+            })),
+            what: `requirement name in activity "${activity.name}"`,
+            issues: issues
         }), checkStatusSetTargets({
             activity: activity,
             activityNames: activityNames,
@@ -2890,10 +3055,10 @@ function collectActivityConditionSites({activity: activity, path: path, stageFie
         policy: "cascade",
         fields: fields
     });
-    for (const [name, groq2] of Object.entries(activity.requirements ?? {})) sites.push({
-        groq: groq2,
-        path: [ ...path, "requirements", name ],
-        label: `activity "${activity.name}" requirement "${name}"`,
+    for (const [index, requirement] of (activity.requirements ?? []).entries()) sites.push({
+        groq: requirement.query,
+        path: [ ...path, "requirements", index, "query" ],
+        label: `activity "${activity.name}" requirement "${requirement.name}"`,
         policy: "caller-bound",
         fields: fields
     });
@@ -3089,73 +3254,83 @@ function checkTriggeredActionParams(def, issues) {
 }
 
 function checkStart(def, issues) {
-    if (def.start !== void 0 && (def.lifecycle === "child" && issues.push({
+    if (def.start !== void 0 && (checkDuplicates({
+        names: (def.start.requirements ?? []).map((requirement, index) => ({
+            name: requirement.name,
+            path: [ "start", "requirements", index, "name" ]
+        })),
+        what: "start requirement name",
+        issues: issues
+    }), 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), checkStartSubjectVariable(def, issues), 
-    def.start.kind === "autonomous")) for (const [n, entry] of (def.fields ?? []).entries()) entry.required !== !0 || isSubjectEntry(entry) || issues.push({
+    }), checkStartFilterReads(def, issues), checkStartRequirementReads(def, issues), 
+    checkSingleSubjectRequirements(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 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) {
+function checkSingleSubjectRequirements(def, issues) {
+    const indexes = (def.start?.requirements ?? []).map((requirement, index) => ({
+        requirement: requirement,
+        index: index
+    })).filter(({requirement: requirement}) => requirement.type === "singleSubject"), [first] = indexes;
+    if (first === void 0) return;
     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`
+    if (subject === void 0) {
+        issues.push({
+            path: [ "start", "requirements", first.index ],
+            message: "a singleSubject start requirement caps the definition at one in-flight run per subject, but the definition declares no `subject` entry — there is no subject identity to dedupe on, so the rule could never apply. Declare a `subject` entry (the document the workflow is about), or remove the requirement"
         });
+        return;
     }
+    isInputSourced(subject) || issues.push({
+        path: [ "start", "requirements", first.index ],
+        message: `a singleSubject start requirement matches the prospective subject against in-flight runs, but the definition's subject entry "${subject.name}" is not \`input\`-sourced — the start gate cannot bind a prospective subject. Make the subject input-sourced, or remove the requirement`
+    });
 }
 
 function checkStartFilterReads(def, issues) {
     const filter = def.start?.filter;
     filter !== void 0 && (conditionParameterNames(filter).has("fields") && issues.push({
         path: [ "start", "filter" ],
-        message: "start.filter reads $fields, but the filter is browse-time-pure — a start surface evaluates it per document, before any inputs exist, so $fields cannot be bound. Move the input-dependent rule to start.allowed, the start-time permission predicate that binds $fields and is enforced by startInstance"
+        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 a start requirement, the start-time readiness 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 `subject` entry — a read surface would never have a document to bind as root, so every root read is GROQ null and the filter silently misevaluates. Declare a `subject` entry (the document the workflow is about), or gate on the dataset instead"
     }));
 }
 
-function checkStartAllowedReads(def, issues) {
-    const allowed = def.start?.allowed;
-    if (allowed === void 0) return;
+function checkStartRequirementReads(def, issues) {
     const bindable = new Map((def.fields ?? []).filter(isInputSourced).map(entry => [ entry.name, entry ])), declared = new Set((def.fields ?? []).map(entry => entry.name)), nullVerdict = `so the read is GROQ null and null semantics decide the verdict (refuse-all or vacuously-allow, by the expression's shape), never the caller's real input. Bindable (input) fields: ${knownList(bindable.keys())}`;
-    for (const read of conditionFieldReads(allowed)) {
-        const entry = bindable.get(read.name);
-        if (entry === void 0) {
-            issues.push({
-                path: [ "start", "allowed" ],
-                message: declared.has(read.name) ? `start.allowed reads $fields.${read.name}, but "${read.name}" is not an \`input\`-sourced entry — $fields binds only the caller's input entries (query/literal/fieldRead entries resolve at materialisation, after the start gate), ${nullVerdict}` : `start.allowed reads $fields.${read.name}, but no workflow-scope field entry named "${read.name}" is declared — $fields binds only the caller's input entries, ${nullVerdict}`
+    for (const [index, requirement] of (def.start?.requirements ?? []).entries()) if (requirement.type === "groq") {
+        for (const read of conditionFieldReads(requirement.query)) {
+            const entry = bindable.get(read.name);
+            if (entry === void 0) {
+                issues.push({
+                    path: [ "start", "requirements", index, "query" ],
+                    message: declared.has(read.name) ? `start requirement reads $fields.${read.name}, but "${read.name}" is not an \`input\`-sourced entry — $fields binds only the caller's input entries (query/literal/fieldRead entries resolve at materialisation, after the start gate), ${nullVerdict}` : `start requirement reads $fields.${read.name}, but no workflow-scope field entry named "${read.name}" is declared — $fields binds only the caller's input entries, ${nullVerdict}`
+                });
+                continue;
+            }
+            pushFieldReadPathIssue({
+                where: "start requirement",
+                read: {
+                    field: read.name,
+                    path: read.path
+                },
+                target: entry,
+                path: [ "start", "requirements", index, "query" ],
+                issues: issues,
+                nodes: START_REQUIREMENT_VALUE_NODES
             });
-            continue;
         }
-        pushFieldReadPathIssue({
-            where: "start.allowed",
-            read: {
-                field: read.name,
-                path: read.path
-            },
-            target: entry,
-            path: [ "start", "allowed" ],
-            issues: issues,
-            nodes: START_ALLOWED_VALUE_NODES
+        readsRootDocument(requirement.query) && issues.push({
+            path: [ "start", "requirements", index, "query" ],
+            message: "start requirement reads the candidate document as its root, but no root ever binds in the start-requirement context — startInstance holds inputs, not a loaded document, so the read is GROQ null and null semantics decide the verdict, never the workflow's real state. Read the subject as $fields.<entry> (its GDR URI is $fields.<entry>.id); a per-document visibility rule belongs in start.filter"
         });
     }
-    readsRootDocument(allowed) && issues.push({
-        path: [ "start", "allowed" ],
-        message: "start.allowed reads the candidate document as its root, but no root ever binds in the start-allowed context — startInstance holds inputs, not a loaded document, so the read is GROQ null and null semantics decide the verdict, never the workflow's real state. Read the subject as $fields.<entry> (its GDR URI is $fields.<entry>.id); a per-document visibility rule belongs in start.filter"
-    });
 }
 
 function checkGroups(def, issues) {
@@ -3680,7 +3855,7 @@ const SCALAR = {
         kind: "rows",
         of: shape.of ?? []
     })
-}, START_ALLOWED_VALUE_NODES = {
+}, START_REQUIREMENT_VALUE_NODES = {
     ...VALUE_NODES,
     "doc.ref": () => GDR_VALUE,
     subject: () => GDR_VALUE
@@ -3761,4 +3936,4 @@ function checkWorkflowInvariants(def) {
     checkGroups(def, issues), issues;
 }
 
-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 };
+export { ACTION_SEMANTICS, ACTIVITY_KINDS, ACTIVITY_STATUSES, ACTOR_KINDS, ANONYMOUS_IDENTITY, 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_FILTER_VARS, START_REQUIREMENT_VARS, SYSTEM_IDENTITY, SpawnContractsInvalidError, StoredFieldOpSchema, VersionSpecificDatasetGdrError, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, WorkflowConfigSchema, WorkflowError, actorFulfillsRole, andConditions, assertReadableModel, assertReaderModelAcknowledgement, checkWorkflowInvariants, choiceValueIssues, classifyPrincipalId, 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, lakePrincipalId, minReaderModelOf, modelStampFor, modelVersionOf, parentRef, parseDefinitionSnapshot, parseFieldValue, 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 };