@sanity/workflow-engine 0.27.0 → 0.28.0

package/dist/index.d.cts

@@ -5975,6 +5975,17 @@ export declare function isNotesEntry(
 /** Whether a project-user API failure explicitly means the user is absent. */
 export declare function isProjectUserNotFoundError(error: unknown): boolean;
 
+/**
+ * True when a write looks like a lost optimistic lock — every `statusCode: 409`
+ * from the real client, or the bench's `ifRevisionId check failed` message.
+ * A bare 409 is not exclusively a lost fence: a `create` against an existing id
+ * (`documentAlreadyExistsError`) carries the same status. Narrow the error to
+ * one rev-guarded write before asking — anything wider (a whole cascade, or a
+ * commit together with its guard deploy) reads a create collision as a lost
+ * race.
+ */
+export declare function isRevisionConflict(error: unknown): boolean;
+
 /** Entry-level {@link isSingleDocRefKind}: narrows a resolved entry to the
  *  single-GDR arms (`doc.ref` / `subject`) — the value is one GDR (or null)
  *  and the entry may carry the accepted-target `types`. */
@@ -6586,11 +6597,6 @@ export declare interface ParsedGdr {
   documentId: string;
 }
 
-declare type ParsedWorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
-
-declare type ParsedWorkflowDeployment =
-  ParsedWorkflowConfig["deployments"][number];
-
 /**
  * Parse a GDR URI into its scheme + addressing parts. Throws on
  * unknown scheme or malformed shape.
@@ -9582,11 +9588,18 @@ export declare interface WorkflowCommitOptions {
   tag?: string;
 }
 
-export declare type WorkflowConfig = Omit<
-  ParsedWorkflowConfig,
+export declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
+
+/**
+ * What an author writes for a whole config: every deployment is a
+ * {@link WorkflowDeploymentInput}. `defineWorkflowConfig` accepts this and
+ * returns the looser {@link WorkflowConfig}.
+ */
+export declare type WorkflowConfigInput = Omit<
+  WorkflowConfig,
   "deployments"
 > & {
-  deployments: WorkflowDeployment[];
+  deployments: WorkflowDeploymentInput[];
 };
 
 declare const WorkflowConfigSchema: v.ObjectSchema<
@@ -10297,15 +10310,25 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
   WorkflowFields<FieldEntry, Stage, StartBlock>
 >;
 
-export declare type WorkflowDeployment = Omit<
-  ParsedWorkflowDeployment,
+/** One deployment as loaded from a config: the floor is optional/unverified so
+ *  a command that never selects a deployment can hold a stale or missing
+ *  acknowledgement. Deployment-scoped paths assert before they act; authors
+ *  write {@link WorkflowDeploymentInput}. */
+export declare type WorkflowDeployment = WorkflowConfig["deployments"][number];
+
+/**
+ * What an author writes for one deployment: the current reader floor as the
+ * reviewed literal. Compile-time only — omitting it or setting a wrong value
+ * is a type error in the editor. Runtime parse still tolerates a stale or
+ * missing floor on {@link WorkflowDeployment} so commands that never select a
+ * deployment still run; deployment-scoped paths assert the selected
+ * deployment (instance-id commands do not).
+ */
+export declare type WorkflowDeploymentInput = Omit<
+  WorkflowDeployment,
   "expectedMinReaderModel"
 > & {
-  /**
-   * Reviewed numeric literal. Runtime validation owns the exact installed-floor check so a stale
-   * acknowledgement reaches the readers-first rollout guidance instead of becoming a type error.
-   */
-  expectedMinReaderModel: number;
+  expectedMinReaderModel: typeof DATA_MODEL_MIN_READER;
 };
 
 export declare const WorkflowEffectCompleted: WorkflowTelemetryEvent<WorkflowEffectCompletedData>;

package/dist/index.d.ts

@@ -5975,6 +5975,17 @@ export declare function isNotesEntry(
 /** Whether a project-user API failure explicitly means the user is absent. */
 export declare function isProjectUserNotFoundError(error: unknown): boolean;
 
+/**
+ * True when a write looks like a lost optimistic lock — every `statusCode: 409`
+ * from the real client, or the bench's `ifRevisionId check failed` message.
+ * A bare 409 is not exclusively a lost fence: a `create` against an existing id
+ * (`documentAlreadyExistsError`) carries the same status. Narrow the error to
+ * one rev-guarded write before asking — anything wider (a whole cascade, or a
+ * commit together with its guard deploy) reads a create collision as a lost
+ * race.
+ */
+export declare function isRevisionConflict(error: unknown): boolean;
+
 /** Entry-level {@link isSingleDocRefKind}: narrows a resolved entry to the
  *  single-GDR arms (`doc.ref` / `subject`) — the value is one GDR (or null)
  *  and the entry may carry the accepted-target `types`. */
@@ -6586,11 +6597,6 @@ export declare interface ParsedGdr {
   documentId: string;
 }
 
-declare type ParsedWorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
-
-declare type ParsedWorkflowDeployment =
-  ParsedWorkflowConfig["deployments"][number];
-
 /**
  * Parse a GDR URI into its scheme + addressing parts. Throws on
  * unknown scheme or malformed shape.
@@ -9582,11 +9588,18 @@ export declare interface WorkflowCommitOptions {
   tag?: string;
 }
 
-export declare type WorkflowConfig = Omit<
-  ParsedWorkflowConfig,
+export declare type WorkflowConfig = v.InferOutput<typeof WorkflowConfigSchema>;
+
+/**
+ * What an author writes for a whole config: every deployment is a
+ * {@link WorkflowDeploymentInput}. `defineWorkflowConfig` accepts this and
+ * returns the looser {@link WorkflowConfig}.
+ */
+export declare type WorkflowConfigInput = Omit<
+  WorkflowConfig,
   "deployments"
 > & {
-  deployments: WorkflowDeployment[];
+  deployments: WorkflowDeploymentInput[];
 };
 
 declare const WorkflowConfigSchema: v.ObjectSchema<
@@ -10297,15 +10310,25 @@ declare const WorkflowDefinitionSchema: v.GenericSchema<
   WorkflowFields<FieldEntry, Stage, StartBlock>
 >;
 
-export declare type WorkflowDeployment = Omit<
-  ParsedWorkflowDeployment,
+/** One deployment as loaded from a config: the floor is optional/unverified so
+ *  a command that never selects a deployment can hold a stale or missing
+ *  acknowledgement. Deployment-scoped paths assert before they act; authors
+ *  write {@link WorkflowDeploymentInput}. */
+export declare type WorkflowDeployment = WorkflowConfig["deployments"][number];
+
+/**
+ * What an author writes for one deployment: the current reader floor as the
+ * reviewed literal. Compile-time only — omitting it or setting a wrong value
+ * is a type error in the editor. Runtime parse still tolerates a stale or
+ * missing floor on {@link WorkflowDeployment} so commands that never select a
+ * deployment still run; deployment-scoped paths assert the selected
+ * deployment (instance-id commands do not).
+ */
+export declare type WorkflowDeploymentInput = Omit<
+  WorkflowDeployment,
   "expectedMinReaderModel"
 > & {
-  /**
-   * Reviewed numeric literal. Runtime validation owns the exact installed-floor check so a stale
-   * acknowledgement reaches the readers-first rollout guidance instead of becoming a type error.
-   */
-  expectedMinReaderModel: number;
+  expectedMinReaderModel: typeof DATA_MODEL_MIN_READER;
 };
 
 export declare const WorkflowEffectCompleted: WorkflowTelemetryEvent<WorkflowEffectCompletedData>;

package/dist/index.js

@@ -1,6 +1,6 @@
-import { terminalState, andConditions, deriveActivityKind, parseDefinitionSnapshot, CALLER_BOUND_VARS, START_REQUIREMENT_VARS, CONDITION_VARS, isSubjectEntry, isUnevaluable, ContractViolationError, isStartableDefinition, conditionFieldReadNames, rethrowWithContext, isGdr, errorMessage, conditionParameterNames, START_FILTER_VARS, gdrFromResource, selfGdr, isSingleDocRefKind, parentRef, actorFulfillsRole, toBareId, WorkflowError, sameResource, resourceFromParsed, tryParseGdr, isTerminalActivityStatus, FieldValueShapeError, validateFieldValue, validateFieldAppendItem, evaluateCondition, isSingleDocRefEntry, choiceValueIssues, scalarValidationIssues, StoredFieldOpSchema, formatIssues, conditionSyntaxIssues, checkWorkflowInvariants, formatIssuePath, isGuardReadExpr, conditionEffectReads, EFFECTS_READ, datasetResourceParts, evaluatePredicates, WORKFLOW_DEFINITION_TYPE, tagScopeFilter, isCascadeFired, WORKFLOW_INSTANCE_TYPE, parseGdr, isGdrUri, gdrRef, isInputSourced, parseFieldValue, VersionSpecificDatasetGdrError, toPhysicalGdr, isBareSeedId, tolerantEntries, NonEmptyString, FIELD_VALUE_KINDS, tolerantObject, ActorShape, IsoTimestamp, ACTIVITY_STATUSES, GdrShape, DRIVER_KINDS, FIELD_SCOPES, fieldValueSchemas, parsePersistedDoc, ACTOR_KINDS, classifyPrincipalId, directoryBridgeId, assertReadableModel, InstanceNotFoundError, modelStampFor, evaluateConditionOutcome, runGroq, FIELD_READ, MUTATION_GUARD_ACTIONS, resourceGdr, minReaderModelOf, resourceFromGdrUri, refTypeIssues, rejectedRefTypes, DOCUMENT_VALUE_PERMISSIONS, lakePrincipalId, driverKind, EffectNotFoundError, firstCarriedGlobalId, deriveExecutorClassification, validateTag, extractDocumentId, parseStoredDefinition, validateResourceAliasName, labelFor, DefinitionNotFoundError, definitionDocId, SpawnContractsInvalidError, gdrResourcePrefix, RESOURCE_ALIAS_NAME_SOURCE, isUnprimed, DefinitionInUseError, assertReaderModelAcknowledgement, isParseableInstant, groupMembershipNames } from "./_chunks-es/invariants.js";
+import { rethrowWithContext, andConditions, deriveActivityKind, WorkflowError, CALLER_BOUND_VARS, START_REQUIREMENT_VARS, CONDITION_VARS, isSubjectEntry, isUnevaluable, ContractViolationError, isStartableDefinition, conditionFieldReadNames, isGdr, errorMessage, conditionParameterNames, START_FILTER_VARS, gdrFromResource, selfGdr, isSingleDocRefKind, actorFulfillsRole, toBareId, sameResource, resourceFromParsed, tryParseGdr, isTerminalActivityStatus, FieldValueShapeError, validateFieldValue, validateFieldAppendItem, evaluateCondition, isSingleDocRefEntry, choiceValueIssues, scalarValidationIssues, StoredFieldOpSchema, formatIssues, conditionSyntaxIssues, checkWorkflowInvariants, formatIssuePath, isGuardReadExpr, conditionEffectReads, EFFECTS_READ, datasetResourceParts, evaluatePredicates, WORKFLOW_DEFINITION_TYPE, tagScopeFilter, isCascadeFired, parseGdr, isGdrUri, gdrRef, isInputSourced, parseFieldValue, VersionSpecificDatasetGdrError, toPhysicalGdr, isBareSeedId, tolerantEntries, NonEmptyString, FIELD_VALUE_KINDS, tolerantObject, ActorShape, IsoTimestamp, ACTIVITY_STATUSES, GdrShape, DRIVER_KINDS, FIELD_SCOPES, fieldValueSchemas, parsePersistedDoc, ACTOR_KINDS, classifyPrincipalId, directoryBridgeId, InstanceNotFoundError, evaluateConditionOutcome, runGroq, FIELD_READ, MUTATION_GUARD_ACTIONS, resourceGdr, resourceFromGdrUri, refTypeIssues, rejectedRefTypes, DOCUMENT_VALUE_PERMISSIONS, lakePrincipalId, driverKind, EffectNotFoundError, firstCarriedGlobalId, deriveExecutorClassification, validateTag, extractDocumentId, parseStoredDefinition, validateResourceAliasName, labelFor, DefinitionNotFoundError, definitionDocId, SpawnContractsInvalidError, gdrResourcePrefix, RESOURCE_ALIAS_NAME_SOURCE, DefinitionInUseError, isParseableInstant, groupMembershipNames } from "./_chunks-es/invariants.js";
 
-import { ACTION_SEMANTICS, ACTIVITY_KINDS, ANONYMOUS_IDENTITY, DATA_MODEL_CHANGES, DATA_MODEL_MIN_READER, DATA_MODEL_VERSION, DEFAULT_TRANSITION_WHEN, EXECUTOR_CLASSIFICATIONS, FILTER_SCOPE_VARS, GROUP_KINDS, GUARD_PREDICATE_VARS, ModelVersionAheadError, PersistedDocShapeError, READER_MODEL_ROLLOUT_URL, RESERVED_CONDITION_VARS, ReaderModelAcknowledgementError, SYSTEM_IDENTITY, clientConfigFromResource, fieldTreeShape, gdrUri, isNotesEntry, isTodoListEntry, isTodoListItem, modelVersionOf, parseDefinitionSnapshotValue, parseResourceGdr, readsRootDocument, refCanvas, refDashboard, refDataset, refKindAcceptsTypes, refMediaLibrary, releaseDocId, releaseRef, requiredModelFeatures, requiredReaderModel, resourceAliasesToMap, schemaTreeShape, startKindOf } from "./_chunks-es/invariants.js";
+import { ACTION_SEMANTICS, ACTIVITY_KINDS, ANONYMOUS_IDENTITY, DEFAULT_TRANSITION_WHEN, EXECUTOR_CLASSIFICATIONS, FILTER_SCOPE_VARS, GROUP_KINDS, GUARD_PREDICATE_VARS, PersistedDocShapeError, RESERVED_CONDITION_VARS, SYSTEM_IDENTITY, clientConfigFromResource, gdrUri, isNotesEntry, isTodoListEntry, isTodoListItem, parseResourceGdr, readsRootDocument, refCanvas, refDashboard, refDataset, refKindAcceptsTypes, refMediaLibrary, releaseDocId, releaseRef, resourceAliasesToMap, schemaTreeShape, startKindOf } from "./_chunks-es/invariants.js";
 
 import { atomNode, dedupeBy, analyzeCondition, atomReadsDataset, checklistLines as checklistLines$1, phrase, quoted, listAnd, describeAtom as describeAtom$1, describeCondition as describeCondition$1, guillemets, formatValue, humanize, listOr, scopeReadOf, describeRead, explainCondition, dedupeReads, whatIfCondition, MAX_COUNTERFACTUAL_INDEX } from "@sanity/groq-condition-describe";
 
@@ -41,6 +41,53 @@ function findCurrentActivityEntry(host, activityName) {
     return findOpenStageEntry(host)?.activities.find(a => a.name === activityName);
 }
 
+const WORKFLOW_INSTANCE_TYPE = "sanity.workflow.instance";
+
+function terminalState(instance) {
+    return instance.abortedAt !== void 0 ? "aborted" : instance.completedAt !== void 0 ? "completed" : "in-flight";
+}
+
+function isUnprimed(instance) {
+    return instance.stages.length === 0 && terminalState(instance) === "in-flight";
+}
+
+function 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);
+}
+
 function effectiveEditable(baseline, override) {
     if (baseline === void 0) return;
     if (override === void 0) return baseline;
@@ -388,6 +435,240 @@ function fieldEditedData(args) {
     };
 }
 
+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}.\nDo not change the acknowledgement yet: accepting ${DATA_MODEL_MIN_READER} authorizes this engine to write documents that older readers will refuse.\nUpgrade 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.\nRollout 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 effectSites(def) {
     const sites = [];
     for (const stage of def.stages ?? []) for (const activity of stage.activities ?? []) for (const action of activity.actions ?? []) for (const effect of action.effects ?? []) sites.push({
@@ -2258,6 +2539,12 @@ function isRevisionConflict(error) {
     return statusCode === 409 ? !0 : typeof message == "string" && message.includes("ifRevisionId check failed");
 }
 
+function isCreateIdCollision(error) {
+    if (typeof error != "object" || error === null) return !1;
+    const {message: message, responseBody: responseBody} = error;
+    return typeof message == "string" && message.includes("already exists") && (message.includes("Document by ID") || message.includes("create() failed")) ? !0 : typeof responseBody == "string" && responseBody.includes("documentAlreadyExistsError");
+}
+
 class ConcurrentEditFieldError extends WorkflowError {
     instanceId;
     target;
@@ -5883,12 +6170,14 @@ function resolveGuard({guard: guard, instance: instance, stageName: stageName, n
 
 async function upsertGuard(args) {
     const {client: client, doc: doc, exists: exists} = args;
-    if (!exists) {
+    if (!exists) try {
         await client.create(doc, {
             ...SYNC_COMMIT,
             tag: REQUEST_TAG.guardDeploy
         });
         return;
+    } catch (error) {
+        if (!isCreateIdCollision(error)) throw error;
     }
     const {_id: _id, _type: _type, _rev: _rev, _createdAt: _createdAt, _updatedAt: _updatedAt, ...body} = doc;
     await client.patch(doc._id).set(body).commit({
@@ -13002,4 +13291,4 @@ function displayDescription(typeKey) {
     if (typeKey) return DISPLAY[typeKey]?.description;
 }
 
-export { ACTION_SEMANTICS, ACTIVITY_KINDS, ACTIVITY_KIND_DISPLAY, ACTOR_KINDS, ANONYMOUS_IDENTITY, AUTHORING_DISPLAY, ActionDisabledError, ActionParamsInvalidError, CONDITION_VARS, CONTEXT_ENTRY_DISPLAY, CascadeLimitError, ConcurrentCommitEffectOpsError, ConcurrentCompleteEffectError, ConcurrentEditFieldError, ConcurrentFireActionError, ContractViolationError, DATA_MODEL_CHANGES, DATA_MODEL_MIN_READER, DATA_MODEL_VERSION, DEFAULT_CONTENT_PERSPECTIVE, DEFAULT_EFFECT_LEASE_MS, DEFAULT_IDEMPOTENCY_TTL_MS, DEFAULT_TRANSITION_WHEN, DISPLAY, DRIVER_KINDS, DRIVER_KIND_DISPLAY, DefinitionInUseError, DefinitionNotFoundError, EFFECT_COMMIT_DISPATCH_CAP, EFFECT_COMMIT_QUEUE_DEPTH, ENGINE_API_VERSION, EXECUTION_KINDS, EXECUTOR_CLASSIFICATIONS, EXECUTOR_CLASSIFICATION_DISPLAY, EditFieldDeniedError, EffectCommitQueueOverflowError, EffectNotFoundError, EffectOpsInvalidError, EffectOutputsInvalidError, FIELD_KIND_DISPLAY, FILTER_SCOPE_VARS, FieldValueShapeError, GROUP_KINDS, GROUP_KIND_DISPLAY, GUARD_DOC_TYPE, GUARD_OWNER, GUARD_PREDICATE_VARS, HISTORY_DISPLAY, InitialFieldsInvalidError, InstanceNotFoundError, MAX_COUNTERFACTUAL_INDEX2 as MAX_COUNTERFACTUAL_INDEX, MissingHandlerError, ModelVersionAheadError, MutationGuardDeniedError, MutationGuardDocSchema, NEUTRAL_MARK, OP_DISPLAY, OUTCOME_MARKS, PartialGuardDeployError, PersistedDocShapeError, READER_MODEL_ROLLOUT_URL, RESERVED_CONDITION_VARS, ReaderModelAcknowledgementError, RefResourceUndeclaredError, RequiredFieldNotProvidedError, START_FILTER_VARS, START_REQUIREMENT_VARS, SYSTEM_IDENTITY, SpawnContractsInvalidError, StaleEffectClaimError, StartNotAllowedError, StartNotPrimedError, StartNotSettledError, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, WorkflowActionFired, WorkflowActivityReset, WorkflowDefinitionDeleted, WorkflowDefinitionDeployed, WorkflowEffectCompleted, WorkflowEffectStateReported, WorkflowEffectsDrained, WorkflowError, WorkflowFieldEdited, WorkflowInstanceAborted, WorkflowInstanceSchema, WorkflowInstanceStarted, WorkflowInstanceTicked, WorkflowStageSet, WorkflowStageTransitioned, WorkflowStateDivergedError, abortReason, acceptsDocumentType, aclPathForResource, actionDisabledDetail, actionRendering, actionVerdict, activityAutonomyOf, analyzeCondition2 as analyzeCondition, applicableDefinitions, assertReadableModel, assertReaderModelAcknowledgement, atomReadsDataset2 as atomReadsDataset, autonomySummary, availableActions, buildInitialFields, buildSnapshot, checklistLines, classifyPrincipalId, clientConfigFromResource, clientProjectUserDirectory, compileGuard, computeDiffEntries, conditionFieldReadNames, conditionSitesOf, contentDocQuery, contentDraftFallback, contentReleaseName, contextMap, createEngine, createTelemetryIntake, datasetResourceParts, defaultLoggerFactory, definitionDeployedData, definitionLookupGroq, definitionTagsGroq, definitionsListGroq, deniedGuardLabels, deniedGuardRefs, denyingGuards, deployStageGuards, deployedTagsGroq, deriveActivityKind, deriveExecutorClassification, deriveWorkflowAutonomy, describeAtom, describeAutonomyWait, describeCondition, describeDefinition, describeFieldInsight, describeNode, describeSite, describeSiteHeading, diagnoseInputFromEvaluation, diagnoseInstance, diffEntry, displayDescription, displayTitle, documentActionDenials, documentPrefilter, driverKind, effectOutputsMap, entryDocRefs, errorMessage, evaluateFromSnapshot, evaluateMutationGuard, evaluateStartFilter, expandResourceAliases, explainCondition2 as explainCondition, explainStartRequirement, extractDocumentId, fieldTreeShape, findCurrentActivityEntry, findOpenStageEntry, formatRead, gdrFromResource, gdrRef, gdrUri, groupMembershipNames, groupSitesOf, guardMatches, guardsForDefinition, guardsForInstance, guardsForResource, guillemets2 as guillemets, hasSingleSubjectRequirement, hashDefinitionContent, humanize2 as humanize, inFlightFilter, initialFieldIssues, instanceDocId, instanceGuardQuery, instanceWatchesDocument, instancesGuardQuery, instancesQuery, isCascadeFired, isClaimExpired, isClientProjectUser, isComparisonOp, isDefinitionApplicable, isFilterScopedOut, isGdr, isInputSourced, isNotesEntry, isProjectUserNotFoundError, isSingleDocRefEntry, isSingleDocRefKind, isStartableDefinition, isSubjectEntry, isTelemetryEnvDenied, isTerminalActivityStatus, isTerminalStage, isTodoListEntry, isTodoListItem, isUnprimed, lakeGuardId, lakePrincipalId, latestDefinitionsGroq, latestDeployedDefinitions, lintEffectOutputs, minReaderModelOf, missingRequiredInputs, modelVersionOf, narrateAutonomyWaits, noopTelemetry, parentRef, parseDefinitionInput, parseDefinitionSnapshot, parseDefinitionSnapshotValue, parseGdr, parseGuardDocument, parseInstanceDocument, parseResourceGdr, processShellUserProperties, projectStartSliceRow, projectToWatchRef, quoted2 as quoted, readInstanceDoc, readsRaw, readsRootDocument, refCanvas, refDashboard, refDataset, refKindAcceptsTypes, refMediaLibrary, refsOf, rejectedRefTypes, releaseDocId, releaseRef, remediationsFor, requiredModelFeatures, requiredReaderModel, resolveAccess, resolveActor, resolveClientActor, resolveFieldEntry$1 as resolveFieldEntry, resourceAliasesToMap, resourceFromParsed, resourceGdr, retractStageGuards, sameResource, scalarValidationIssues, schemaTreeShape, sentenceCase, silentLogger, singleSubjectRequirementRefused, stageAutonomyOf, startFieldsParam, startKindOf, startRefusal, stripSystemFields, subjectDenialLabels, subscriptionDocument, subscriptionDocumentsForInstance, sweepStaleClaims, tagScopeFilter, terminalState, toBareId, tryParseGdr, unboundRequirementReads, unsatisfiedTransitionSummaries, userLoginProvider, validateDefinition, validateTag, verdictGuardsForInstance, wallClock, whatIfCondition2 as whatIfCondition, withAssignment, workflow };
+export { ACTION_SEMANTICS, ACTIVITY_KINDS, ACTIVITY_KIND_DISPLAY, ACTOR_KINDS, ANONYMOUS_IDENTITY, AUTHORING_DISPLAY, ActionDisabledError, ActionParamsInvalidError, CONDITION_VARS, CONTEXT_ENTRY_DISPLAY, CascadeLimitError, ConcurrentCommitEffectOpsError, ConcurrentCompleteEffectError, ConcurrentEditFieldError, ConcurrentFireActionError, ContractViolationError, DATA_MODEL_CHANGES, DATA_MODEL_MIN_READER, DATA_MODEL_VERSION, DEFAULT_CONTENT_PERSPECTIVE, DEFAULT_EFFECT_LEASE_MS, DEFAULT_IDEMPOTENCY_TTL_MS, DEFAULT_TRANSITION_WHEN, DISPLAY, DRIVER_KINDS, DRIVER_KIND_DISPLAY, DefinitionInUseError, DefinitionNotFoundError, EFFECT_COMMIT_DISPATCH_CAP, EFFECT_COMMIT_QUEUE_DEPTH, ENGINE_API_VERSION, EXECUTION_KINDS, EXECUTOR_CLASSIFICATIONS, EXECUTOR_CLASSIFICATION_DISPLAY, EditFieldDeniedError, EffectCommitQueueOverflowError, EffectNotFoundError, EffectOpsInvalidError, EffectOutputsInvalidError, FIELD_KIND_DISPLAY, FILTER_SCOPE_VARS, FieldValueShapeError, GROUP_KINDS, GROUP_KIND_DISPLAY, GUARD_DOC_TYPE, GUARD_OWNER, GUARD_PREDICATE_VARS, HISTORY_DISPLAY, InitialFieldsInvalidError, InstanceNotFoundError, MAX_COUNTERFACTUAL_INDEX2 as MAX_COUNTERFACTUAL_INDEX, MissingHandlerError, ModelVersionAheadError, MutationGuardDeniedError, MutationGuardDocSchema, NEUTRAL_MARK, OP_DISPLAY, OUTCOME_MARKS, PartialGuardDeployError, PersistedDocShapeError, READER_MODEL_ROLLOUT_URL, RESERVED_CONDITION_VARS, ReaderModelAcknowledgementError, RefResourceUndeclaredError, RequiredFieldNotProvidedError, START_FILTER_VARS, START_REQUIREMENT_VARS, SYSTEM_IDENTITY, SpawnContractsInvalidError, StaleEffectClaimError, StartNotAllowedError, StartNotPrimedError, StartNotSettledError, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, WorkflowActionFired, WorkflowActivityReset, WorkflowDefinitionDeleted, WorkflowDefinitionDeployed, WorkflowEffectCompleted, WorkflowEffectStateReported, WorkflowEffectsDrained, WorkflowError, WorkflowFieldEdited, WorkflowInstanceAborted, WorkflowInstanceSchema, WorkflowInstanceStarted, WorkflowInstanceTicked, WorkflowStageSet, WorkflowStageTransitioned, WorkflowStateDivergedError, abortReason, acceptsDocumentType, aclPathForResource, actionDisabledDetail, actionRendering, actionVerdict, activityAutonomyOf, analyzeCondition2 as analyzeCondition, applicableDefinitions, assertReadableModel, assertReaderModelAcknowledgement, atomReadsDataset2 as atomReadsDataset, autonomySummary, availableActions, buildInitialFields, buildSnapshot, checklistLines, classifyPrincipalId, clientConfigFromResource, clientProjectUserDirectory, compileGuard, computeDiffEntries, conditionFieldReadNames, conditionSitesOf, contentDocQuery, contentDraftFallback, contentReleaseName, contextMap, createEngine, createTelemetryIntake, datasetResourceParts, defaultLoggerFactory, definitionDeployedData, definitionLookupGroq, definitionTagsGroq, definitionsListGroq, deniedGuardLabels, deniedGuardRefs, denyingGuards, deployStageGuards, deployedTagsGroq, deriveActivityKind, deriveExecutorClassification, deriveWorkflowAutonomy, describeAtom, describeAutonomyWait, describeCondition, describeDefinition, describeFieldInsight, describeNode, describeSite, describeSiteHeading, diagnoseInputFromEvaluation, diagnoseInstance, diffEntry, displayDescription, displayTitle, documentActionDenials, documentPrefilter, driverKind, effectOutputsMap, entryDocRefs, errorMessage, evaluateFromSnapshot, evaluateMutationGuard, evaluateStartFilter, expandResourceAliases, explainCondition2 as explainCondition, explainStartRequirement, extractDocumentId, fieldTreeShape, findCurrentActivityEntry, findOpenStageEntry, formatRead, gdrFromResource, gdrRef, gdrUri, groupMembershipNames, groupSitesOf, guardMatches, guardsForDefinition, guardsForInstance, guardsForResource, guillemets2 as guillemets, hasSingleSubjectRequirement, hashDefinitionContent, humanize2 as humanize, inFlightFilter, initialFieldIssues, instanceDocId, instanceGuardQuery, instanceWatchesDocument, instancesGuardQuery, instancesQuery, isCascadeFired, isClaimExpired, isClientProjectUser, isComparisonOp, isDefinitionApplicable, isFilterScopedOut, isGdr, isInputSourced, isNotesEntry, isProjectUserNotFoundError, isRevisionConflict, isSingleDocRefEntry, isSingleDocRefKind, isStartableDefinition, isSubjectEntry, isTelemetryEnvDenied, isTerminalActivityStatus, isTerminalStage, isTodoListEntry, isTodoListItem, isUnprimed, lakeGuardId, lakePrincipalId, latestDefinitionsGroq, latestDeployedDefinitions, lintEffectOutputs, minReaderModelOf, missingRequiredInputs, modelVersionOf, narrateAutonomyWaits, noopTelemetry, parentRef, parseDefinitionInput, parseDefinitionSnapshot, parseDefinitionSnapshotValue, parseGdr, parseGuardDocument, parseInstanceDocument, parseResourceGdr, processShellUserProperties, projectStartSliceRow, projectToWatchRef, quoted2 as quoted, readInstanceDoc, readsRaw, readsRootDocument, refCanvas, refDashboard, refDataset, refKindAcceptsTypes, refMediaLibrary, refsOf, rejectedRefTypes, releaseDocId, releaseRef, remediationsFor, requiredModelFeatures, requiredReaderModel, resolveAccess, resolveActor, resolveClientActor, resolveFieldEntry$1 as resolveFieldEntry, resourceAliasesToMap, resourceFromParsed, resourceGdr, retractStageGuards, sameResource, scalarValidationIssues, schemaTreeShape, sentenceCase, silentLogger, singleSubjectRequirementRefused, stageAutonomyOf, startFieldsParam, startKindOf, startRefusal, stripSystemFields, subjectDenialLabels, subscriptionDocument, subscriptionDocumentsForInstance, sweepStaleClaims, tagScopeFilter, terminalState, toBareId, tryParseGdr, unboundRequirementReads, unsatisfiedTransitionSummaries, userLoginProvider, validateDefinition, validateTag, verdictGuardsForInstance, wallClock, whatIfCondition2 as whatIfCondition, withAssignment, workflow };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-engine",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Workflow / BPM engine for Sanity content — define workflows as data, run them as instances against a Sanity client.",
   "keywords": [
     "bpm",