@sanity/workflow-engine 0.27.0 → 0.29.0

package/dist/_chunks-cjs/invariants.cjs

@@ -20,6 +20,41 @@ function _interopNamespaceCompat(e) {
 
 var v__namespace = /* @__PURE__ */ _interopNamespaceCompat(v);
 
+function isCascadeFired(action) {
+    return action.when !== void 0;
+}
+
+function deriveActivityKind(activity) {
+    if (activity.target !== void 0) return "manual";
+    const actions = activity.actions ?? [];
+    return actions.some(a => !isCascadeFired(a)) ? "user" : actions.some(a => (a.effects ?? []).length > 0 || a.spawn !== void 0) ? "service" : actions.length > 0 ? "receive" : "script";
+}
+
+function deriveExecutorClassification(activity) {
+    if (activity.target !== void 0) return "off-system";
+    const actions = activity.actions ?? [], cascadeFired = actions.filter(isCascadeFired).length;
+    return cascadeFired === actions.length ? "autonomous" : cascadeFired === 0 ? "interactive" : "hybrid";
+}
+
+function driverKind(actor) {
+    return actor.kind === "person" || actor.kind === "agent" ? actor.kind : "service";
+}
+
+function errorMessage(err) {
+    return (err instanceof Error ? err.message : String(err)).replace(/[^\P{Cc}\n\t]/gu, "");
+}
+
+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(" && ");
+}
+
 class WorkflowError extends Error {
     kind;
     constructor(kind, message, options) {
@@ -93,322 +128,6 @@ function effectNotFoundMessage(args) {
     return args.settled.status === "cancelled" ? `${base} — it was cancelled at ${args.settled.ranAt}${cause}` : `${base} — it already settled "${args.settled.status}" at ${args.settled.ranAt}${cause}`;
 }
 
-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 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);
-}
-
-function parentRef(instance) {
-    return instance.ancestors.at(-1);
-}
-
-const DATA_MODEL_VERSION = 5, DATA_MODEL_MIN_READER = 4, READER_MODEL_ROLLOUT_URL = "https://www.sanity.io/docs/editorial-workflows/prerelease";
-
-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}. Do not change the acknowledgement yet: accepting ${DATA_MODEL_MIN_READER} authorizes this engine to write documents that older readers will refuse. Upgrade every Studio, CLI, MCP server, Function, and other runtime that reads engine-owned documents; verify that rollout in every environment sharing the workflow resource; then change the literal in deployment configuration and deploy the writer. Rollout guide: ${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."
-}), 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."
-}), Object.freeze({
-    id: "due-date-field-kinds",
-    introducedInModel: 5,
-    minReaderModel: 0,
-    documentTypes: Object.freeze([ "definition", "instance" ]),
-    compatibility: "additive",
-    applicability: "detectable",
-    summary: "Due-date field kinds (dueDate, dueDatetime) mark a level deadline, elevated aliases of date/datetime carrying the same stored value."
-}) ]);
-
-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";
-    });
-}
-
-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"),
-    "typed-scalar-choice-lists": hasChoiceList,
-    "action-semantics": hasActionSemantics,
-    "inclusive-scalar-bounds": hasScalarValidation,
-    "progress-field-kind": document => hasFieldKind(document, "progress"),
-    "effect-claim-tokens": hasClaimTokens,
-    "classified-principal-ids": () => !0,
-    "readiness-requirements": hasReadinessRequirements,
-    "due-date-field-kinds": document => hasFieldKind(document, "dueDate") || hasFieldKind(document, "dueDatetime")
-};
-
-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(DATA_MODEL_MIN_READER, 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;
-}
-
-function deriveActivityKind(activity) {
-    if (activity.target !== void 0) return "manual";
-    const actions = activity.actions ?? [];
-    return actions.some(a => !isCascadeFired(a)) ? "user" : actions.some(a => (a.effects ?? []).length > 0 || a.spawn !== void 0) ? "service" : actions.length > 0 ? "receive" : "script";
-}
-
-function deriveExecutorClassification(activity) {
-    if (activity.target !== void 0) return "off-system";
-    const actions = activity.actions ?? [], cascadeFired = actions.filter(isCascadeFired).length;
-    return cascadeFired === actions.length ? "autonomous" : cascadeFired === 0 ? "interactive" : "hybrid";
-}
-
-function driverKind(actor) {
-    return actor.kind === "person" || actor.kind === "agent" ? actor.kind : "service";
-}
-
-function 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(" && ");
-}
-
 const KNOWN_SCHEMES = /* @__PURE__ */ new Set([ "dataset", "canvas", "media-library", "dashboard" ]), KNOWN_SCHEMES_TEXT = [ ...KNOWN_SCHEMES ].join(", ");
 
 class VersionSpecificDatasetGdrError extends Error {
@@ -820,6 +539,7 @@ function desugarWorkflow(authoring) {
         return {
             ...stripUndefined({
                 name: stage.name,
+                semantics: stage.semantics,
                 title: stage.title,
                 description: stage.description,
                 groups: stage.groups,
@@ -843,6 +563,7 @@ function desugarWorkflow(authoring) {
         definition: {
             ...stripUndefined({
                 name: authoring.name,
+                semantics: authoring.semantics,
                 title: authoring.title,
                 description: authoring.description,
                 groups: authoring.groups,
@@ -1069,6 +790,7 @@ function desugarActivity({activity: activity, path: path, stageEnv: stageEnv, ct
     return {
         ...stripUndefined({
             name: activity.name,
+            semantics: activity.semantics,
             title: activity.title,
             description: activity.description,
             groups: activity.groups,
@@ -1540,7 +1262,58 @@ function isTerminalActivityStatus(status) {
     return TERMINAL_ACTIVITY_STATUSES.includes(status);
 }
 
-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 = [ {
+const SIGNAL_SEMANTICS = [ "signal.positive", "signal.caution", "signal.critical" ], DECISION_SEMANTICS = [ "decision.accept", "decision.decline" ], ACTION_SEMANTICS = [ ...DECISION_SEMANTICS, ...SIGNAL_SEMANTICS ], 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" ];
+
+function releaseDocId(releaseName) {
+    return `_.releases.${releaseName}`;
+}
+
+function releaseRef({res: res, releaseName: releaseName}) {
+    if (releaseName.length === 0) throw new ContractViolationError("releaseRef: releaseName must be a non-empty release name");
+    return {
+        id: gdrFromResource(res, releaseDocId(releaseName)),
+        type: "system.release",
+        releaseName: releaseName
+    };
+}
+
+function isAlwaysArrayFieldKind(kind) {
+    return kind === "doc.refs" || kind === "assignees" || kind === "array";
+}
+
+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;
+    return typeof candidate._key == "string" && typeof candidate.label == "string" && (status == null || typeof status == "string");
+}
+
+function declaredRowColumns(entry) {
+    if (("_type" in entry ? entry._type : entry.type) === "array") return new Set((("of" in entry ? entry.of : void 0) ?? []).map(shape => shape.name));
+}
+
+function isTodoListEntry(entry) {
+    const columns = declaredRowColumns(entry);
+    return columns !== void 0 && columns.has("label") && columns.has("status");
+}
+
+function isNotesEntry(entry) {
+    const columns = declaredRowColumns(entry);
+    return columns !== void 0 && columns.has("body") && columns.has("actor") && columns.has("at");
+}
+
+const CONDITION_VARS = [ {
     name: "self",
     binding: "always",
     label: "this workflow instance",
@@ -1615,6 +1388,11 @@ const ACTION_SEMANTICS = [ "decision.accept", "decision.decline" ], FIELD_SCOPES
     binding: "caller",
     label: "your permissions",
     description: "Advisory per-permission booleans computed from the caller's grants; `undefined` without grants. Bound wherever grants ride the evaluation: the projection's rendered scope (fireAction-action filters, activity requirements, editability predicates) and the fireAction/editField commit gates. Deploy rejects it at every site that evaluates without grants: transition `when`s, activity filters, cascade-fired actions' `when`/`filter`, effect bindings, where-op `where`s, and the spawn `forEach`/`with`/`context` sites."
+}, {
+    name: "attributes",
+    binding: "caller",
+    label: "your attributes",
+    description: "Advisory org-level User Attributes for the caller (Enterprise — same values as lake `user::attributes()`), keyed by attribute name with each active scalar or array value. `undefined` on expected HTTP absence; unexpected fetch failures throw; empty page binds `{}`. Bound wherever grants ride the evaluation (same sites as `$can`). Soft-gate paths fetch at most 100 attributes (no further pages) and warn when the envelope reports `hasMore: true` (partial bag still binds). Not a security boundary — the Content Lake remains the only enforcement point."
 }, {
     name: "row",
     binding: "spawn",
@@ -1780,54 +1558,7 @@ function documentIdOf(doc) {
     return "(unknown id)";
 }
 
-const ACTOR_KINDS = [ "person", "agent", "system" ];
-
-function releaseDocId(releaseName) {
-    return `_.releases.${releaseName}`;
-}
-
-function releaseRef({res: res, releaseName: releaseName}) {
-    if (releaseName.length === 0) throw new ContractViolationError("releaseRef: releaseName must be a non-empty release name");
-    return {
-        id: gdrFromResource(res, releaseDocId(releaseName)),
-        type: "system.release",
-        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;
-    return typeof candidate._key == "string" && typeof candidate.label == "string" && (status == null || typeof status == "string");
-}
-
-function declaredRowColumns(entry) {
-    if (("_type" in entry ? entry._type : entry.type) === "array") return new Set((("of" in entry ? entry.of : void 0) ?? []).map(shape => shape.name));
-}
-
-function isTodoListEntry(entry) {
-    const columns = declaredRowColumns(entry);
-    return columns !== void 0 && columns.has("label") && columns.has("status");
-}
-
-function isNotesEntry(entry) {
-    const columns = declaredRowColumns(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-(.+)$/;
+const ACTOR_KINDS = [ "person", "agent", "system" ], ANONYMOUS_IDENTITY = "<anonymous>", SYSTEM_IDENTITY = "<system>", E_PREFIXED_PROJECT_ID = /^e-(.+)$/;
 
 function classifyPrincipalId(id) {
     if (id === ANONYMOUS_IDENTITY || id === SYSTEM_IDENTITY) return {
@@ -2256,6 +1987,10 @@ function opSchemas(targetSchema) {
         type: v__namespace.literal("field.set"),
         target: targetSchema,
         value: ValueExprSchema
+    }), v__namespace.strictObject({
+        type: v__namespace.literal("field.setIfMissing"),
+        target: targetSchema,
+        value: ValueExprSchema
     }), v__namespace.strictObject({
         type: v__namespace.literal("field.unset"),
         target: targetSchema
@@ -2263,6 +1998,14 @@ function opSchemas(targetSchema) {
         type: v__namespace.literal("field.append"),
         target: targetSchema,
         value: ValueExprSchema
+    }), v__namespace.strictObject({
+        type: v__namespace.literal("field.inc"),
+        target: targetSchema,
+        value: v__namespace.optional(ValueExprSchema)
+    }), v__namespace.strictObject({
+        type: v__namespace.literal("field.dec"),
+        target: targetSchema,
+        value: v__namespace.optional(ValueExprSchema)
     }), v__namespace.strictObject({
         type: v__namespace.literal("field.updateWhere"),
         target: targetSchema,
@@ -2479,17 +2222,27 @@ const TodoListFieldSchema = pinned()(v__namespace.strictObject(listSugarFields("
     required: v__namespace.optional(v__namespace.boolean()),
     options: v__namespace.optional(ChoiceOptionsSchema),
     validation: v__namespace.optional(ScalarValidationSchema)
-}), choiceOptionsCheck(), scalarValidationCheck());
+}), choiceOptionsCheck(), scalarValidationCheck()), CUSTOM_SEMANTIC_HINT = "`custom.<camelCaseMeaning>`", CustomSemanticSchema = v__namespace.custom(input => typeof input == "string" && /^custom\.[a-z][a-zA-Z0-9]*$/.test(input)), SemanticSchema = v__namespace.union([ picklist(SIGNAL_SEMANTICS), CustomSemanticSchema ], `expected ${SIGNAL_SEMANTICS.join(", ")}, or ${CUSTOM_SEMANTIC_HINT}`), ActionSemanticSchema = v__namespace.union([ picklist(ACTION_SEMANTICS), CustomSemanticSchema ], `expected ${ACTION_SEMANTICS.join(", ")}, or ${CUSTOM_SEMANTIC_HINT}`);
+
+function semanticNamespace(semantic) {
+    return semantic.startsWith("custom.") ? semantic : semantic.split(".", 1)[0] ?? semantic;
+}
 
 function hasUniqueSemanticNamespaces(semantics) {
-    const namespaces = semantics.map(semantic => semantic.split(".", 1)[0]);
+    const namespaces = semantics.map(semanticNamespace);
     return new Set(namespaces).size === namespaces.length;
 }
 
+function semanticsFieldSchema(semantic) {
+    return v__namespace.optional(v__namespace.pipe(v__namespace.array(semantic), v__namespace.minLength(1, "declare at least one semantic, or omit `semantics`"), v__namespace.check(hasUniqueSemanticNamespaces, "declare at most one semantic from each namespace")));
+}
+
+const SemanticsFieldSchema = semanticsFieldSchema(SemanticSchema), ActionSemanticsFieldSchema = semanticsFieldSchema(ActionSemanticSchema);
+
 function actionFields(op, group) {
     return {
         name: NonEmpty,
-        semantics: v__namespace.optional(v__namespace.pipe(v__namespace.array(picklist(ACTION_SEMANTICS)), v__namespace.minLength(1, "declare at least one semantic, or omit `semantics`"), v__namespace.check(hasUniqueSemanticNamespaces, "declare at most one semantic from each namespace"))),
+        semantics: ActionSemanticsFieldSchema,
         title: v__namespace.optional(v__namespace.string()),
         description: v__namespace.optional(v__namespace.string()),
         group: v__namespace.optional(group),
@@ -2536,6 +2289,7 @@ const StoredActionSchema = pinned()(v__namespace.strictObject({
 function activityFields({field: field, action: action, target: target, group: group}) {
     return {
         name: NonEmpty,
+        semantics: SemanticsFieldSchema,
         title: v__namespace.optional(v__namespace.string()),
         description: v__namespace.optional(v__namespace.string()),
         groups: v__namespace.optional(v__namespace.array(GroupSchema)),
@@ -2609,6 +2363,7 @@ const GuardSchema = v__namespace.strictObject(guardFields(NonEmpty)), AuthoringG
 function stageFields({field: field, activity: activity, transition: transition, guard: guard, editable: editable}) {
     return {
         name: NonEmpty,
+        semantics: SemanticsFieldSchema,
         title: v__namespace.optional(v__namespace.string()),
         description: v__namespace.optional(v__namespace.string()),
         groups: v__namespace.optional(v__namespace.array(GroupSchema)),
@@ -2647,6 +2402,7 @@ const StoredStartSchema = pinned()(v__namespace.strictObject(startFields(picklis
 function workflowFields({field: field, stage: stage, start: start}) {
     return {
         name: NonEmpty,
+        semantics: SemanticsFieldSchema,
         title: NonEmpty,
         description: v__namespace.optional(v__namespace.string()),
         groups: v__namespace.optional(v__namespace.array(GroupSchema)),
@@ -2843,11 +2599,20 @@ function checkStageReachability({def: def, stageNames: stageNames, issues: issue
     });
 }
 
+function actionSites(def) {
+    return def.stages.flatMap((stage, i) => (stage.activities ?? []).flatMap((activity, j) => (activity.actions ?? []).map((action, a) => ({
+        action: action,
+        activity: activity,
+        stage: stage,
+        path: [ "stages", i, "activities", j, "actions", a ]
+    }))));
+}
+
 function effectNameSites(def) {
     const sites = [];
-    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) collectEffects({
+    for (const {action: action, path: path} of actionSites(def)) collectEffects({
         effects: action.effects,
-        path: [ "stages", i, "activities", j, "actions", a, "effects" ],
+        path: [ ...path, "effects" ],
         sites: sites
     });
     return sites;
@@ -2978,13 +2743,22 @@ function checkUnboundConditionVars(def, issues) {
     }
 }
 
+const SOFT_GATE_VARS = {
+    can: {
+        noun: "the caller's grants"
+    },
+    attributes: {
+        noun: "the caller's org-level user attributes"
+    }
+}, SOFT_GATE_VAR_NAMES = Object.keys(SOFT_GATE_VARS);
+
 function unboundVarsAt(site) {
     const callerVars = unboundCallerVars(site.policy);
     return site.bindsRow === !0 ? callerVars : [ ...callerVars, "row" ];
 }
 
 function unboundCallerVars(policy) {
-    return policy === "cascade" ? CALLER_BOUND_VARS : policy === "caller-bound" ? [ "params" ] : policy === "triggered-payload" ? [ "can", "params" ] : [ "can" ];
+    return policy === "cascade" ? CALLER_BOUND_VARS : policy === "caller-bound" ? [ "params" ] : policy === "triggered-payload" ? [ ...SOFT_GATE_VAR_NAMES, "params" ] : SOFT_GATE_VAR_NAMES;
 }
 
 const ROW_BINDING_CLAUSE = "$row (the discovered row in a spawn projection; the stored row under test in a where-op) is bound only while a spawn `with` projection or a where-op `where` evaluates";
@@ -2994,7 +2768,12 @@ function rowVarMessage(site) {
 }
 
 function callerVarMessage(site, name) {
-    return site.policy === "cascade" ? `${site.label} reads $${name} — cascade gates (transition \`when\`s, activity \`filter\`s, a cascade-fired action's \`when\`/\`filter\`) must resolve identically no matter whose token drives the cascade ($assigned is constant false, the other caller vars hold no value); gate on instance state (e.g. a field an action wrote), or pin executing identities with \`roles\`` : site.policy === "caller-bound" ? `${site.label} reads $${name} — $params (the firing action's args) is bound only while the action's effect bindings and where-op \`where\`s evaluate; this site never binds it, so the condition could never pass. Bind $params in an effect binding or a where-op instead, or gate on a field an action wrote` : site.policy === "triggered-payload" && name === "params" ? `${site.label} reads $params — a cascade-fired action has no caller to supply args, so $params never holds a value in its payload; read fields or effect outputs instead` : `${site.label} reads $can — $can (the caller's grants) is bound only in the caller-bound projection (action filters, requirements, editable predicates) and never holds a value in cascade conditions; move the check to one of those sites or drop $can`;
+    if (site.policy === "cascade") return `${site.label} reads $${name} — cascade gates (transition \`when\`s, activity \`filter\`s, a cascade-fired action's \`when\`/\`filter\`) must resolve identically no matter whose token drives the cascade ($assigned is constant false, the other caller vars hold no value); gate on instance state (e.g. a field an action wrote), or pin executing identities with \`roles\``;
+    if (site.policy === "caller-bound") return `${site.label} reads $${name} — $params (the firing action's args) is bound only while the action's effect bindings and where-op \`where\`s evaluate; this site never binds it, so the condition could never pass. Bind $params in an effect binding or a where-op instead, or gate on a field an action wrote`;
+    if (site.policy === "triggered-payload" && name === "params") return `${site.label} reads $params — a cascade-fired action has no caller to supply args, so $params never holds a value in its payload; read fields or effect outputs instead`;
+    const softGate = SOFT_GATE_VARS[name];
+    if (softGate !== void 0) return `${site.label} reads $${name} — $${name} (${softGate.noun}) is bound only in the caller-bound projection (action filters, requirements, editable predicates); this site never binds it. Move the check to one of those sites or drop $${name}`;
+    throw new Error(`callerVarMessage: unreachable for $${name} at ${site.label} (policy ${site.policy})`);
 }
 
 function conditionSites(def) {
@@ -3249,9 +3028,9 @@ function belowScopeNestedSites(args) {
 }
 
 function checkLevelKindEffectOutputs(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()) pushOutputIssues({
+    for (const {action: action, path: path} of actionSites(def)) pushOutputIssues({
         action: action,
-        path: [ "stages", i, "activities", j, "actions", a ],
+        path: path,
         issues: issues
     });
 }
@@ -3333,18 +3112,18 @@ function storedRolesIssue(action) {
 }
 
 function checkStoredRolesPlacement(def, issues) {
-    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) {
+    for (const {action: action, path: path} of actionSites(def)) {
         const message = storedRolesIssue(action);
         message !== void 0 && issues.push({
-            path: [ "stages", i, "activities", j, "actions", a, "roles" ],
+            path: [ ...path, "roles" ],
             message: message
         });
     }
 }
 
 function checkTriggeredActionParams(def, issues) {
-    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) action.when === void 0 || (action.params ?? []).length === 0 || issues.push({
-        path: [ "stages", i, "activities", j, "actions", a, "params" ],
+    for (const {action: action, path: path} of actionSites(def)) action.when === void 0 || (action.params ?? []).length === 0 || issues.push({
+        path: [ ...path, "params" ],
         message: `action "${action.name}" declares params but is cascade-fired (\`when\`) — no caller ever supplies args to a trigger. Drop the params, or drop \`when\` to make it a fireAction-fired action`
     });
 }
@@ -3389,13 +3168,20 @@ function checkSingleSubjectRequirements(def, issues) {
 
 function checkStartFilterReads(def, issues) {
     const filter = def.start?.filter;
-    filter !== void 0 && (conditionParameterNames(filter).has("fields") && issues.push({
+    if (filter === void 0) return;
+    const params = conditionParameterNames(filter);
+    params.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 a start requirement, the start-time readiness predicate that binds $fields and is enforced by startInstance"
-    }), readsRootDocument(filter) && !(def.fields ?? []).some(isSubjectEntry) && issues.push({
+    });
+    for (const name of CALLER_BOUND_VARS) params.has(name) && issues.push({
+        path: [ "start", "filter" ],
+        message: `start.filter reads $${name} — start.filter is a read-side document-visibility rule (definitionsForDocument / start controls); startInstance never evaluates it, and no caller bag binds there, so the read is GROQ null and the filter can never match. Drop $${name} from start.filter. A "who may start" rule belongs in a start requirement, not in the browse-time filter`
+    });
+    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 checkStartRequirementReads(def, issues) {
@@ -3691,15 +3477,13 @@ function seedEarlierSiblingTarget(args) {
 }
 
 function opSites(def) {
-    const sites = [];
-    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) sites.push({
+    return actionSites(def).map(({action: action, activity: activity, stage: stage, path: path}) => ({
         ops: action.ops,
-        path: [ "stages", i, "activities", j, "actions", a, "ops" ],
+        path: [ ...path, "ops" ],
         label: `action "${action.name}"`,
         stage: stage,
         activity: activity
-    });
-    return sites;
+    }));
 }
 
 function checkFieldReadOpValues(def, issues) {
@@ -3716,7 +3500,7 @@ function checkFieldReadOpValues(def, issues) {
 }
 
 function checkOpsFieldReads({ops: ops, path: path, label: label, ...ctx}) {
-    for (const [o, op] of (ops ?? []).entries()) if ("value" in op) for (const {read: read, path: readPath} of fieldReadsIn(op.value, [ ...path, o, "value" ])) checkOpFieldRead({
+    for (const [o, op] of (ops ?? []).entries()) if (!(!("value" in op) || op.value === void 0)) for (const {read: read, path: readPath} of fieldReadsIn(op.value, [ ...path, o, "value" ])) checkOpFieldRead({
         ...ctx,
         read: read,
         path: readPath,
@@ -3767,35 +3551,55 @@ function opFieldReadMissMessage({read: read, where: where, hosts: hosts}) {
     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) {
+function checkFieldTargetOps(def, issues) {
     const workflow = def.fields ?? [];
     for (const site of opSites(def)) for (const [o, op] of (site.ops ?? []).entries()) {
-        if (op.type !== "field.updateWhere") continue;
-        const scopes = {
-            workflow: workflow,
-            stage: site.stage.fields ?? [],
-            activity: site.activity.fields ?? []
-        };
-        checkUpdateWhereTargetKind({
+        const path = [ ...site.path, o ], rule = TARGET_KIND_RULES[op.type];
+        rule !== void 0 && "target" in op && checkTargetKind({
             op: op,
-            path: [ ...site.path, o ],
+            path: [ ...path, "target" ],
             label: site.label,
-            scopes: scopes,
+            scopes: opTargetScopes(workflow, site),
+            rule: rule,
             issues: issues
-        }), checkUpdateWhereMergeKeys({
+        }), op.type === "field.updateWhere" && checkUpdateWhereMergeKeys({
             op: op,
-            path: [ ...site.path, o ],
+            path: path,
             label: site.label,
             issues: issues
         });
     }
 }
 
-function checkUpdateWhereTargetKind({op: op, path: path, label: label, scopes: scopes, issues: issues}) {
+const arithmeticTargetRule = {
+    accepts: target => target.type === "number",
+    issue: () => "arithmetic ops target `number` entries only"
+}, TARGET_KIND_RULES = {
+    "field.inc": arithmeticTargetRule,
+    "field.dec": arithmeticTargetRule,
+    "field.setIfMissing": {
+        accepts: target => !isAlwaysArrayFieldKind(target.type),
+        issue: () => "setIfMissing applies to nullable entries only; an empty array entry already holds []"
+    },
+    "field.updateWhere": {
+        accepts: target => target.type === "array",
+        issue: target => "updateWhere merges declared row sub-fields, so its target must be an `array` entry" + rowOpsHint(target.type)
+    }
+};
+
+function opTargetScopes(workflow, site) {
+    return {
+        workflow: workflow,
+        stage: site.stage.fields ?? [],
+        activity: site.activity.fields ?? []
+    };
+}
+
+function checkTargetKind({op: op, path: path, label: label, scopes: scopes, rule: rule, issues: issues}) {
     const target = scopes[op.target.scope]?.find(entry => entry.name === op.target.field);
-    target === void 0 || target.type === "array" || issues.push({
-        path: [ ...path, "target" ],
-        message: `${label} field.updateWhere targets ${op.target.scope}-scope "${op.target.field}" (${target.type}) — updateWhere merges declared row sub-fields, so its target must be an \`array\` entry${rowOpsHint(target.type)}`
+    target === void 0 || rule.accepts(target) || issues.push({
+        path: path,
+        message: `${label} ${op.type} targets ${op.target.scope}-scope "${op.target.field}" (${target.type}) — ${rule.issue(target)}`
     });
 }
 
@@ -4027,7 +3831,7 @@ function checkWorkflowInvariants(def) {
     }), checkEffectNames(def, issues), checkGuardNames(def, issues), checkFieldEntryNames(def, issues), 
     checkRequiredField(def, issues), checkStart(def, issues), checkPredicates(def, issues), 
     checkUnboundConditionVars(def, issues), checkConditionFieldReads(def, issues), checkFieldReadSeeds(def, issues), 
-    checkFieldReadOpValues(def, issues), checkUpdateWhereOps(def, issues), checkGuardFieldReads(def, issues), 
+    checkFieldReadOpValues(def, issues), checkFieldTargetOps(def, issues), checkGuardFieldReads(def, issues), 
     checkAssigneesEntries(def, issues), checkDueDateEntries(def, issues), checkSubjectEntries(def, issues), 
     checkLevelKindEffectOutputs(def, issues), checkActivityTerminalPaths(def, issues), 
     checkTerminalStageActivities(def, issues), checkTriggeredActionParams(def, issues), 
@@ -4068,11 +3872,7 @@ exports.CONDITION_VARS = CONDITION_VARS;
 
 exports.ContractViolationError = ContractViolationError;
 
-exports.DATA_MODEL_CHANGES = DATA_MODEL_CHANGES;
-
-exports.DATA_MODEL_MIN_READER = DATA_MODEL_MIN_READER;
-
-exports.DATA_MODEL_VERSION = DATA_MODEL_VERSION;
+exports.DECISION_SEMANTICS = DECISION_SEMANTICS;
 
 exports.DEFAULT_TRANSITION_WHEN = DEFAULT_TRANSITION_WHEN;
 
@@ -4116,19 +3916,15 @@ exports.IsoTimestamp = IsoTimestamp;
 
 exports.MUTATION_GUARD_ACTIONS = MUTATION_GUARD_ACTIONS;
 
-exports.ModelVersionAheadError = ModelVersionAheadError;
-
 exports.NonEmptyString = NonEmptyString;
 
 exports.PersistedDocShapeError = PersistedDocShapeError;
 
-exports.READER_MODEL_ROLLOUT_URL = READER_MODEL_ROLLOUT_URL;
-
 exports.RESERVED_CONDITION_VARS = RESERVED_CONDITION_VARS;
 
 exports.RESOURCE_ALIAS_NAME_SOURCE = RESOURCE_ALIAS_NAME_SOURCE;
 
-exports.ReaderModelAcknowledgementError = ReaderModelAcknowledgementError;
+exports.SIGNAL_SEMANTICS = SIGNAL_SEMANTICS;
 
 exports.START_FILTER_VARS = START_FILTER_VARS;
 
@@ -4144,8 +3940,6 @@ exports.VersionSpecificDatasetGdrError = VersionSpecificDatasetGdrError;
 
 exports.WORKFLOW_DEFINITION_TYPE = WORKFLOW_DEFINITION_TYPE;
 
-exports.WORKFLOW_INSTANCE_TYPE = WORKFLOW_INSTANCE_TYPE;
-
 exports.WorkflowConfigSchema = WorkflowConfigSchema;
 
 exports.WorkflowError = WorkflowError;
@@ -4154,10 +3948,6 @@ exports.actorFulfillsRole = actorFulfillsRole;
 
 exports.andConditions = andConditions;
 
-exports.assertReadableModel = assertReadableModel;
-
-exports.assertReaderModelAcknowledgement = assertReaderModelAcknowledgement;
-
 exports.checkWorkflowInvariants = checkWorkflowInvariants;
 
 exports.choiceValueIssues = choiceValueIssues;
@@ -4198,8 +3988,6 @@ exports.evaluatePredicates = evaluatePredicates;
 
 exports.extractDocumentId = extractDocumentId;
 
-exports.fieldTreeShape = fieldTreeShape;
-
 exports.fieldValueSchemas = fieldValueSchemas;
 
 exports.firstCarriedGlobalId = firstCarriedGlobalId;
@@ -4222,6 +4010,8 @@ exports.groq = groq;
 
 exports.groupMembershipNames = groupMembershipNames;
 
+exports.isAlwaysArrayFieldKind = isAlwaysArrayFieldKind;
+
 exports.isBareSeedId = isBareSeedId;
 
 exports.isCascadeFired = isCascadeFired;
@@ -4254,24 +4044,10 @@ exports.isTodoListItem = isTodoListItem;
 
 exports.isUnevaluable = isUnevaluable;
 
-exports.isUnprimed = isUnprimed;
-
 exports.labelFor = labelFor;
 
 exports.lakePrincipalId = lakePrincipalId;
 
-exports.minReaderModelOf = minReaderModelOf;
-
-exports.modelStampFor = modelStampFor;
-
-exports.modelVersionOf = modelVersionOf;
-
-exports.parentRef = parentRef;
-
-exports.parseDefinitionSnapshot = parseDefinitionSnapshot;
-
-exports.parseDefinitionSnapshotValue = parseDefinitionSnapshotValue;
-
 exports.parseFieldValue = parseFieldValue;
 
 exports.parseGdr = parseGdr;
@@ -4304,10 +4080,6 @@ exports.releaseDocId = releaseDocId;
 
 exports.releaseRef = releaseRef;
 
-exports.requiredModelFeatures = requiredModelFeatures;
-
-exports.requiredReaderModel = requiredReaderModel;
-
 exports.resourceAliasesToMap = resourceAliasesToMap;
 
 exports.resourceFromGdrUri = resourceFromGdrUri;
@@ -4332,8 +4104,6 @@ exports.startKindOf = startKindOf;
 
 exports.tagScopeFilter = tagScopeFilter;
 
-exports.terminalState = terminalState;
-
 exports.toBareId = toBareId;
 
 exports.toPhysicalGdr = toPhysicalGdr;