@sanity/workflow-engine 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # @sanity/workflow-engine
 
+## 0.25.0
+
+### Minor Changes
+
+- 177d600: Deployed workflow environment tags are now discoverable.
+
+  The engine gains two cross-partition GROQ builders: `deployedTagsGroq()` lists
+  every tag holding a deployed definition in a resource, and
+  `definitionTagsGroq()` narrows that to one definition name via `$definition`.
+  Both deliberately span tag partitions — every other read is tag-scoped, and
+  `workflow.query` refuses GROQ that isn't — so they answer "which environments
+  exist here" for a caller holding a resource but no tag. They report what is
+  _observed_: a tag with nothing deployed does not appear.
+
+  The stdio MCP server adds a `list_workflow_tags` tool taking a
+  `workflow_resource` and no tag. It is registered by the host rather than exported
+  as a tool def, because a def is only ever handed an engine and an engine is
+  pinned to one tag. `LIST_WORKFLOW_TAGS_TOOL_NAME` and
+  `LIST_WORKFLOW_TAGS_DESCRIPTION` are exported so an embedding host registers the
+  same capability under the same name without re-authoring the model-facing
+  wording. The `tag` parameter's description now points an agent at that tool where
+  a server offers it and at the user otherwise, and requires confirmation either
+  way — having the list does not license picking from it.
+
+  Both registration paths share one outcome path, `withToolTelemetry`, so the
+  result envelope, error rendering, and the `Editorial Workflows MCP Tool Called`
+  event cannot diverge between a def-backed tool and a host-registered one. Tag
+  discovery reports its adoption event like every other tool, and because it names
+  a resource it can also initialize the stdio server's deferred telemetry shell —
+  which matters when discovery is an agent's first call.
+
+  The CLI's definition-tags probe runs the engine's builder instead of its own
+  copy of the query, so its `params` key is `definition` rather than `name`, and
+  the tag partitions it names in an ambiguity error arrive sorted from the lake.
+
+### Patch Changes
+
+- fc12989: Fixes actor resolution failing with `principal id "…" is not an account-global
+user id` for a session scoped to a single project, such as a SAML-SSO Studio
+  session.
+
+  `actor.id` is always the account-global user id, and the id's namespace decides
+  which read supplies it rather than the host that answered. Whichever `/users/me`
+  read returns an already-account-global id supplies it; a project-scoped id is
+  bridged to its account-global form first — by string surgery for an
+  `e-<globalId>` principal, otherwise through the project's own user directory
+  (`/projects/<id>/users/<principal>` → `sanityUserId`). A SAML-SSO session
+  resolves through that directory, because the global host holds no
+  account-global record for it.
+
+  A session whose id is already account-global issues no directory request. A
+  project-scoped id that no route can bridge is refused, naming both failed
+  routes.
+
+  The project-user directory admits only a row answering the id it asked for,
+  matching the batched member join: a row for another principal reports
+  inaccessible rather than resolving to that person's identity.
+
+## 0.24.0
+
+### Minor Changes
+
+- 0bc4328: Render diagram tooltips in the Studio's own idiom, through one seam instead of six hand-assembled bodies:
+  - Pin the chrome once (padding 2, radius 3, shadow 2, 280px sentence cap / 400px for dev mode's label-value grids). Bodies no longer carry their own outer padding, which had stacked a `padding={3}` box inside the tooltip's own padding.
+  - A title with nothing under it renders in regular weight — it is the whole message, not a heading. Semibold is reserved for a title that actually heads content, one per tooltip: gate headings now separate from their checklist rows by full-strength versus muted text rather than a second bold.
+  - Checklists, the grouped-edge roster, the group vertex's stage list and an activity's causal waits render as real `<ul>`/`<li>` rows, so wrapping and nesting come from the browser. Previously these were flattened into padded strings with `white-space: pre-wrap`, which left a wrapped row's continuation aligned under its own marker. Each row leads with its glyph in a fixed-width column and hangs its wrapped lines back to the text: one column for a bullet and a verdict alike, where a `list-style-type` marker box is sized by its own content and put the two on different left edges within one tooltip. The glyph is inline content rather than a marker, so it is selected and copied with the row it belongs to.
+  - Space the body on one three-step rhythm, named by the role a gap plays: independent blocks (the activity roster, each gate) separate furthest, a lead-in sits closer to the list it introduces, and rows within a list sit closest. A stage tooltip nests several of these, and at one flat step the whole explanation read as a single mass.
+  - `MetaTable` renders rows only; the title and description come from the shared body, so dev-mode and end-user tooltips head identically.
+
+  `OUTCOME_MARKS` and `NEUTRAL_MARK` are now exported (from `@sanity/groq-condition-describe`, re-exported by `@sanity/workflow-engine`), so a structured checklist renderer and `checklistLines` draw their verdict glyphs from one vocabulary.
+
+- 41a3f02: Add `dueDate` and `dueDatetime` field kinds — elevated aliases of `date` / `datetime` (same stored value and validation) that mark THE due date of a level, so surfaces can identify a deadline by kind instead of guessing which date field means "due". Declarable at workflow, stage, and activity scope; optional (no field becomes required). The kind reserves a level's single due slot, so deploy enforces both halves of that: at most one due-\* (either kind, combined) per scope, and none below scope level — a due-\* nested in an `object`/`array` sub-field or an effect's `outputs` is rejected, naming `date` / `datetime` as the fix, because no deadline reader looks there. A `todoList` row's `dueDate` column is unaffected; it is a `date` named `dueDate`, not the kind. Choice lists (`options`) work on the due kinds exactly as on `date` / `datetime`. Persisted-model version 5 (additive, reader floor unchanged).
+
+  The Studio plugin edits and renders the new kinds exactly like the base kinds they elevate: the calendar picker in the start dialog, the Overview pills, the inline field editors and the activity row's date control, a locale-formatted face, and the Workflows tool's Date filter. Every date-family branch now routes through one shared kind predicate, so an elevated alias can't drift out of a site.
+
+### Patch Changes
+
+- Updated dependencies [0bc4328]
+  - @sanity/groq-condition-describe@0.4.0
+
 ## 0.23.0
 
 ### Minor Changes

package/DATAMODEL.md

@@ -666,6 +666,42 @@ from that snapshot. Definitions are create-only and instance persists retain
 unknown fields, so model-4 data survives round trips; the floor prevents an
 older engine from interpreting it in the first place.
 
+### Model 5 — the `dueDate` / `dueDatetime` field kinds (reader floor: 4)
+
+One additive growth ships as model 5 — model 4 was released before it landed,
+so it mints the next version rather than amending a shipped one. It does not
+raise the reader floor; the writer maximum stays 4.
+
+Two elevated scalar aliases mark THE due date for a level (workflow, stage, or
+activity): `dueDate` aliases `date` (same stored `YYYY-MM-DD` value and
+validation) and `dueDatetime` aliases `datetime` (same stored ISO-8601 value
+and validation). The kind lets surfaces identify a level's deadline instead of
+guessing which date field means "due". Both are optional; a deploy invariant
+allows at most one due-\* (either kind, combined) per scope, so "the due date"
+is never ambiguous. Both stamped trees grow the value:
+
+- **Definition tree** — `fields[].type` admits `'dueDate'` and `'dueDatetime'`
+  on a scope's own entries only. A due-\* nested in an `object`/`array`
+  sub-field, or in an effect's `outputs`, is rejected at deploy: the kind names
+  the deadline OF A LEVEL, and every deadline reader consults scope entries, so
+  a nested one is dead configuration. Nested dates stay `date` / `datetime`.
+  Existing `todoList` sugar is unaffected — its `dueDate` row column is a
+  `date` named `dueDate`, not the kind.
+- **Instance tree** — resolved `fields[]` entries admit `_type: 'dueDate'` and
+  `_type: 'dueDatetime'` (the same arm shapes as `date` / `datetime`).
+
+Manifest feature: `due-date-field-kinds` (definition + instance, additive,
+detectable, floor 0).
+
+Would an old reader misread the kinds (rule 5)? No — the same loud refusal as
+the `subject` and `progress` kinds: an older engine (model 4 and below) that
+loaded a due-date-carrying instance fails the strict `fields[]` variant with
+`PersistedDocShapeError` before interpreting anything, and cannot deploy or
+evaluate a due-date-declaring definition. The stored value is byte-identical to
+its base `date` / `datetime`, so no older code path can write it while skipping
+validation — there is no silent bypass to fence, and the kinds leave the floor
+at 0.
+
 ## Pending governed changes
 
 - **`temp.system.guard` → `system.guard`** — the guard doc type's `temp.`

package/dist/_chunks-cjs/invariants.cjs

@@ -150,7 +150,7 @@ function parentRef(instance) {
     return instance.ancestors.at(-1);
 }
 
-const DATA_MODEL_VERSION = 4, DATA_MODEL_MIN_READER = 4, READER_MODEL_ROLLOUT_URL = "https://www.sanity.io/docs/editorial-workflows/prerelease";
+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";
@@ -241,6 +241,14 @@ const DATA_MODEL_CHANGES = Object.freeze([ Object.freeze({
     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) {
@@ -315,7 +323,8 @@ const featureDetectors = {
     "progress-field-kind": document => hasFieldKind(document, "progress"),
     "effect-claim-tokens": hasClaimTokens,
     "classified-principal-ids": () => !0,
-    "readiness-requirements": hasReadinessRequirements
+    "readiness-requirements": hasReadinessRequirements,
+    "due-date-field-kinds": document => hasFieldKind(document, "dueDate") || hasFieldKind(document, "dueDatetime")
 };
 
 function requiredModelFeatures(documentType, document) {
@@ -1845,6 +1854,18 @@ function classifyPrincipalId(id) {
     };
 }
 
+function directoryBridgeId(sanityUserId) {
+    if (typeof sanityUserId == "string") return classifyPrincipalId(sanityUserId).namespace === "global" ? sanityUserId : void 0;
+}
+
+function firstCarriedGlobalId(candidates) {
+    for (const candidate of candidates) {
+        if (candidate === void 0) continue;
+        const {globalId: globalId} = classifyPrincipalId(candidate);
+        if (globalId !== void 0) return globalId;
+    }
+}
+
 function lakePrincipalId(args) {
     return args.localPrincipalId ?? args.actor.id;
 }
@@ -1879,7 +1900,7 @@ const GdrUriSchema = v__namespace.custom(s => typeof s == "string" && isGdrUri(s
 }), tolerantObject()({
     type: v__namespace.literal("role"),
     role: NonEmptyString
-}) ]), NullableString = v__namespace.union([ v__namespace.null(), v__namespace.string() ]), NullableNumber = v__namespace.union([ v__namespace.null(), v__namespace.number() ]), NullableBoolean = v__namespace.union([ v__namespace.null(), v__namespace.boolean() ]), NullableProgress = v__namespace.union([ v__namespace.null(), v__namespace.pipe(v__namespace.number(), v__namespace.finite("progress must be a finite number"), v__namespace.minValue(0, "progress must be at least 0"), v__namespace.maxValue(100, "progress must be at most 100")) ]), NullableDateTime = v__namespace.union([ v__namespace.null(), IsoTimestamp ]), NullableDate = v__namespace.union([ v__namespace.null(), v__namespace.pipe(v__namespace.string(), v__namespace.regex(/^\d{4}-\d{2}-\d{2}$/, "must be a `YYYY-MM-DD` date")) ]), NullableUrl = NullableString, CHOICE_KINDS = /* @__PURE__ */ new Set([ "string", "text", "number", "url", "date", "datetime", "dateTime" ]);
+}) ]), NullableString = v__namespace.union([ v__namespace.null(), v__namespace.string() ]), NullableNumber = v__namespace.union([ v__namespace.null(), v__namespace.number() ]), NullableBoolean = v__namespace.union([ v__namespace.null(), v__namespace.boolean() ]), NullableProgress = v__namespace.union([ v__namespace.null(), v__namespace.pipe(v__namespace.number(), v__namespace.finite("progress must be a finite number"), v__namespace.minValue(0, "progress must be at least 0"), v__namespace.maxValue(100, "progress must be at most 100")) ]), NullableDateTime = v__namespace.union([ v__namespace.null(), IsoTimestamp ]), NullableDate = v__namespace.union([ v__namespace.null(), v__namespace.pipe(v__namespace.string(), v__namespace.regex(/^\d{4}-\d{2}-\d{2}$/, "must be a `YYYY-MM-DD` date")) ]), NullableUrl = NullableString, CHOICE_KINDS = /* @__PURE__ */ new Set([ "string", "text", "number", "url", "date", "dueDate", "datetime", "dueDatetime", "dateTime" ]);
 
 function normalizedChoiceKind(kind) {
     return kind === "dateTime" ? "datetime" : kind;
@@ -1914,7 +1935,9 @@ const fieldValueSchemas = {
     progress: NullableProgress,
     boolean: NullableBoolean,
     date: NullableDate,
+    dueDate: NullableDate,
     datetime: NullableDateTime,
+    dueDatetime: NullableDateTime,
     url: NullableUrl,
     actor: v__namespace.union([ v__namespace.null(), ActorShape ]),
     assignee: v__namespace.union([ v__namespace.null(), AssigneeShape ]),
@@ -2279,7 +2302,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), AUTHORING_FIELD_SUGAR_KINDS = exhaustiveOptions()([ "claim", "todoList", "notes" ]), AUTHORING_FIELD_KINDS = [ ...FIELD_VALUE_KINDS, ...AUTHORING_FIELD_SUGAR_KINDS ], AuthoringRawFieldKindSchema = v__namespace.picklist(FIELD_VALUE_KINDS, issue => `${invalidOptionMessage(AUTHORING_FIELD_KINDS)} but received ${JSON.stringify(issue.input)}`), FieldEntryName = groqIdentifier("`$fields.<name>`"), FiniteNumber = v__namespace.pipe(v__namespace.number(), v__namespace.finite("must be finite")), ScalarValidationSchema = v__namespace.pipe(v__namespace.strictObject({
+const FIELD_VALUE_KINDS = [ "doc.ref", "doc.refs", "subject", "release.ref", "string", "text", "number", "progress", "boolean", "date", "dueDate", "datetime", "dueDatetime", "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__namespace.picklist(FIELD_VALUE_KINDS, issue => `${invalidOptionMessage(AUTHORING_FIELD_KINDS)} but received ${JSON.stringify(issue.input)}`), FieldEntryName = groqIdentifier("`$fields.<name>`"), FiniteNumber = v__namespace.pipe(v__namespace.number(), v__namespace.finite("must be finite")), ScalarValidationSchema = v__namespace.pipe(v__namespace.strictObject({
     min: v__namespace.optional(FiniteNumber),
     max: v__namespace.optional(FiniteNumber)
 }), v__namespace.check(validation => validation.min !== void 0 || validation.max !== void 0, "declare at least one bound, or omit `validation`"), v__namespace.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__namespace.strictObject({
@@ -2669,6 +2692,10 @@ function isSubjectEntry(entry) {
     return entry.type === "subject";
 }
 
+function isDueDateEntry(entry) {
+    return entry.type === "dueDate" || entry.type === "dueDatetime";
+}
+
 function isInputSourced(entry) {
     return entry.initialValue?.type === "input";
 }
@@ -3175,25 +3202,79 @@ function checkAssigneesEntries(def, issues) {
     });
 }
 
-function nestedSubjectPaths(shapes, base) {
-    return (shapes ?? []).flatMap((shape, i) => isSubjectEntry(shape) ? [ [ ...base, i, "type" ] ] : [ ...nestedSubjectPaths(shape.fields, [ ...base, i, "fields" ]), ...nestedSubjectPaths(shape.of, [ ...base, i, "of" ]) ]);
+function checkDueDateEntries(def, issues) {
+    for (const {entries: entries, path: path, label: label} of fieldScopes(def)) {
+        (entries ?? []).filter(isDueDateEntry).length > 1 && issues.push({
+            path: path,
+            message: "at most one due-date field entry per scope (dueDate or dueDatetime combined) — surfaces identify the deadline by kind"
+        });
+        for (const site of belowScopeNestedSites({
+            entries: entries,
+            path: path,
+            isKind: isDueDateEntry
+        })) issues.push({
+            path: site.path,
+            message: `${label} entry "${site.entry.name}" declares a due-date sub-field — a due-* kind marks THE deadline of a level, so nothing reads one below scope level. Declare \`date\` or \`datetime\` for a nested date`
+        });
+    }
+}
+
+function nestedKindPaths(args) {
+    const {shapes: shapes, base: base, isKind: isKind} = args;
+    return (shapes ?? []).flatMap((shape, i) => isKind(shape) ? [ [ ...base, i, "type" ] ] : [ ...nestedKindPaths({
+        shapes: shape.fields,
+        base: [ ...base, i, "fields" ],
+        isKind: isKind
+    }), ...nestedKindPaths({
+        shapes: shape.of,
+        base: [ ...base, i, "of" ],
+        isKind: isKind
+    }) ]);
 }
 
-function checkSubjectEffectOutputs(def, issues) {
-    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) pushSubjectOutputIssues({
+function belowScopeNestedSites(args) {
+    const {entries: entries, path: path, isKind: isKind} = args;
+    return (entries ?? []).flatMap((entry, n) => [ ...nestedKindPaths({
+        shapes: entry.fields,
+        base: [ ...path, n, "fields" ],
+        isKind: isKind
+    }), ...nestedKindPaths({
+        shapes: entry.of,
+        base: [ ...path, n, "of" ],
+        isKind: isKind
+    }) ].map(nestedPath => ({
+        path: nestedPath,
+        entry: entry
+    })));
+}
+
+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({
         action: action,
         path: [ "stages", i, "activities", j, "actions", a ],
         issues: issues
     });
 }
 
-function pushSubjectOutputIssues(args) {
+const LEVEL_KIND_OUTPUT_RULES = [ {
+    isKind: isSubjectEntry,
+    message: name => `effect "${name}" declares a \`subject\` output shape — no subject reader ever looks at effect outputs. Declare \`doc.ref\` for a document-valued output`
+}, {
+    isKind: isDueDateEntry,
+    message: name => `effect "${name}" declares a due-date output shape — a due-* kind marks THE deadline of a level, and no deadline reader looks at effect outputs. Declare \`date\` or \`datetime\` for a dated output`
+} ];
+
+function pushOutputIssues(args) {
     const {action: action, path: path, issues: issues} = args;
     for (const [e, effect] of (action.effects ?? []).entries()) {
         const base = [ ...path, "effects", e, "outputs" ];
-        for (const nestedPath of nestedSubjectPaths(effect.outputs, base)) issues.push({
+        for (const {isKind: isKind, message: message} of LEVEL_KIND_OUTPUT_RULES) for (const nestedPath of nestedKindPaths({
+            shapes: effect.outputs,
+            base: base,
+            isKind: isKind
+        })) issues.push({
             path: nestedPath,
-            message: `effect "${effect.name}" declares a \`subject\` output shape — no subject reader ever looks at effect outputs. Declare \`doc.ref\` for a document-valued output`
+            message: message(effect.name)
         });
     }
 }
@@ -3211,13 +3292,14 @@ function checkSubjectEntries(def, issues) {
             path: [ ...path, n ],
             message: "at most one subject-kind field entry per workflow — the runtime identifies THE subject by kind, and a second one makes it ambiguous"
         });
-        for (const [n, entry] of (entries ?? []).entries()) {
-            const nested = [ ...nestedSubjectPaths(entry.fields, [ ...path, n, "fields" ]), ...nestedSubjectPaths(entry.of, [ ...path, n, "of" ]) ];
-            for (const nestedPath of nested) issues.push({
-                path: nestedPath,
-                message: `${label} entry "${entry.name}" declares a \`subject\` sub-field — a nested subject can never be read as the workflow's subject. Declare \`doc.ref\` for a nested reference`
-            });
-        }
+        for (const site of belowScopeNestedSites({
+            entries: entries,
+            path: path,
+            isKind: isSubjectEntry
+        })) issues.push({
+            path: site.path,
+            message: `${label} entry "${site.entry.name}" declares a \`subject\` sub-field — a nested subject can never be read as the workflow's subject. Declare \`doc.ref\` for a nested reference`
+        });
     }
 }
 
@@ -3853,7 +3935,9 @@ const SCALAR = {
     progress: () => SCALAR,
     boolean: () => SCALAR,
     date: () => SCALAR,
+    dueDate: () => SCALAR,
     datetime: () => SCALAR,
+    dueDatetime: () => SCALAR,
     url: () => SCALAR,
     actor: () => ACTOR_VALUE,
     assignee: () => ASSIGNEE_VALUE,
@@ -3944,10 +4028,10 @@ function checkWorkflowInvariants(def) {
     checkRequiredField(def, issues), checkStart(def, issues), checkPredicates(def, issues), 
     checkUnboundConditionVars(def, issues), checkConditionFieldReads(def, issues), checkFieldReadSeeds(def, issues), 
     checkFieldReadOpValues(def, issues), checkUpdateWhereOps(def, issues), checkGuardFieldReads(def, issues), 
-    checkAssigneesEntries(def, issues), checkSubjectEntries(def, issues), checkSubjectEffectOutputs(def, issues), 
-    checkActivityTerminalPaths(def, issues), checkTerminalStageActivities(def, issues), 
-    checkTriggeredActionParams(def, issues), checkStoredRolesPlacement(def, issues), 
-    checkGroups(def, issues), issues;
+    checkAssigneesEntries(def, issues), checkDueDateEntries(def, issues), checkSubjectEntries(def, issues), 
+    checkLevelKindEffectOutputs(def, issues), checkActivityTerminalPaths(def, issues), 
+    checkTerminalStageActivities(def, issues), checkTriggeredActionParams(def, issues), 
+    checkStoredRolesPlacement(def, issues), checkGroups(def, issues), issues;
 }
 
 exports.ACTION_SEMANTICS = ACTION_SEMANTICS;
@@ -4100,6 +4184,8 @@ exports.deriveExecutorClassification = deriveExecutorClassification;
 
 exports.desugarWorkflow = desugarWorkflow;
 
+exports.directoryBridgeId = directoryBridgeId;
+
 exports.driverKind = driverKind;
 
 exports.errorMessage = errorMessage;
@@ -4116,6 +4202,8 @@ exports.fieldTreeShape = fieldTreeShape;
 
 exports.fieldValueSchemas = fieldValueSchemas;
 
+exports.firstCarriedGlobalId = firstCarriedGlobalId;
+
 exports.formatIssuePath = formatIssuePath;
 
 exports.formatIssues = formatIssues;

package/dist/_chunks-es/invariants.js

@@ -136,7 +136,7 @@ function parentRef(instance) {
     return instance.ancestors.at(-1);
 }
 
-const DATA_MODEL_VERSION = 4, DATA_MODEL_MIN_READER = 4, READER_MODEL_ROLLOUT_URL = "https://www.sanity.io/docs/editorial-workflows/prerelease";
+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";
@@ -227,6 +227,14 @@ const DATA_MODEL_CHANGES = Object.freeze([ Object.freeze({
     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) {
@@ -301,7 +309,8 @@ const featureDetectors = {
     "progress-field-kind": document => hasFieldKind(document, "progress"),
     "effect-claim-tokens": hasClaimTokens,
     "classified-principal-ids": () => !0,
-    "readiness-requirements": hasReadinessRequirements
+    "readiness-requirements": hasReadinessRequirements,
+    "due-date-field-kinds": document => hasFieldKind(document, "dueDate") || hasFieldKind(document, "dueDatetime")
 };
 
 function requiredModelFeatures(documentType, document) {
@@ -1831,6 +1840,18 @@ function classifyPrincipalId(id) {
     };
 }
 
+function directoryBridgeId(sanityUserId) {
+    if (typeof sanityUserId == "string") return classifyPrincipalId(sanityUserId).namespace === "global" ? sanityUserId : void 0;
+}
+
+function firstCarriedGlobalId(candidates) {
+    for (const candidate of candidates) {
+        if (candidate === void 0) continue;
+        const {globalId: globalId} = classifyPrincipalId(candidate);
+        if (globalId !== void 0) return globalId;
+    }
+}
+
 function lakePrincipalId(args) {
     return args.localPrincipalId ?? args.actor.id;
 }
@@ -1865,7 +1886,7 @@ const GdrUriSchema = v.custom(s => typeof s == "string" && isGdrUri(s), "must be
 }), tolerantObject()({
     type: v.literal("role"),
     role: NonEmptyString
-}) ]), NullableString = v.union([ v.null(), v.string() ]), NullableNumber = v.union([ v.null(), v.number() ]), NullableBoolean = v.union([ v.null(), v.boolean() ]), NullableProgress = v.union([ v.null(), v.pipe(v.number(), v.finite("progress must be a finite number"), v.minValue(0, "progress must be at least 0"), v.maxValue(100, "progress must be at most 100")) ]), NullableDateTime = v.union([ v.null(), IsoTimestamp ]), NullableDate = v.union([ v.null(), v.pipe(v.string(), v.regex(/^\d{4}-\d{2}-\d{2}$/, "must be a `YYYY-MM-DD` date")) ]), NullableUrl = NullableString, CHOICE_KINDS = /* @__PURE__ */ new Set([ "string", "text", "number", "url", "date", "datetime", "dateTime" ]);
+}) ]), NullableString = v.union([ v.null(), v.string() ]), NullableNumber = v.union([ v.null(), v.number() ]), NullableBoolean = v.union([ v.null(), v.boolean() ]), NullableProgress = v.union([ v.null(), v.pipe(v.number(), v.finite("progress must be a finite number"), v.minValue(0, "progress must be at least 0"), v.maxValue(100, "progress must be at most 100")) ]), NullableDateTime = v.union([ v.null(), IsoTimestamp ]), NullableDate = v.union([ v.null(), v.pipe(v.string(), v.regex(/^\d{4}-\d{2}-\d{2}$/, "must be a `YYYY-MM-DD` date")) ]), NullableUrl = NullableString, CHOICE_KINDS = /* @__PURE__ */ new Set([ "string", "text", "number", "url", "date", "dueDate", "datetime", "dueDatetime", "dateTime" ]);
 
 function normalizedChoiceKind(kind) {
     return kind === "dateTime" ? "datetime" : kind;
@@ -1900,7 +1921,9 @@ const fieldValueSchemas = {
     progress: NullableProgress,
     boolean: NullableBoolean,
     date: NullableDate,
+    dueDate: NullableDate,
     datetime: NullableDateTime,
+    dueDatetime: NullableDateTime,
     url: NullableUrl,
     actor: v.union([ v.null(), ActorShape ]),
     assignee: v.union([ v.null(), AssigneeShape ]),
@@ -2265,7 +2288,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), 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({
+const FIELD_VALUE_KINDS = [ "doc.ref", "doc.refs", "subject", "release.ref", "string", "text", "number", "progress", "boolean", "date", "dueDate", "datetime", "dueDatetime", "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({
@@ -2655,6 +2678,10 @@ function isSubjectEntry(entry) {
     return entry.type === "subject";
 }
 
+function isDueDateEntry(entry) {
+    return entry.type === "dueDate" || entry.type === "dueDatetime";
+}
+
 function isInputSourced(entry) {
     return entry.initialValue?.type === "input";
 }
@@ -3161,25 +3188,79 @@ function checkAssigneesEntries(def, issues) {
     });
 }
 
-function nestedSubjectPaths(shapes, base) {
-    return (shapes ?? []).flatMap((shape, i) => isSubjectEntry(shape) ? [ [ ...base, i, "type" ] ] : [ ...nestedSubjectPaths(shape.fields, [ ...base, i, "fields" ]), ...nestedSubjectPaths(shape.of, [ ...base, i, "of" ]) ]);
+function checkDueDateEntries(def, issues) {
+    for (const {entries: entries, path: path, label: label} of fieldScopes(def)) {
+        (entries ?? []).filter(isDueDateEntry).length > 1 && issues.push({
+            path: path,
+            message: "at most one due-date field entry per scope (dueDate or dueDatetime combined) — surfaces identify the deadline by kind"
+        });
+        for (const site of belowScopeNestedSites({
+            entries: entries,
+            path: path,
+            isKind: isDueDateEntry
+        })) issues.push({
+            path: site.path,
+            message: `${label} entry "${site.entry.name}" declares a due-date sub-field — a due-* kind marks THE deadline of a level, so nothing reads one below scope level. Declare \`date\` or \`datetime\` for a nested date`
+        });
+    }
+}
+
+function nestedKindPaths(args) {
+    const {shapes: shapes, base: base, isKind: isKind} = args;
+    return (shapes ?? []).flatMap((shape, i) => isKind(shape) ? [ [ ...base, i, "type" ] ] : [ ...nestedKindPaths({
+        shapes: shape.fields,
+        base: [ ...base, i, "fields" ],
+        isKind: isKind
+    }), ...nestedKindPaths({
+        shapes: shape.of,
+        base: [ ...base, i, "of" ],
+        isKind: isKind
+    }) ]);
+}
+
+function belowScopeNestedSites(args) {
+    const {entries: entries, path: path, isKind: isKind} = args;
+    return (entries ?? []).flatMap((entry, n) => [ ...nestedKindPaths({
+        shapes: entry.fields,
+        base: [ ...path, n, "fields" ],
+        isKind: isKind
+    }), ...nestedKindPaths({
+        shapes: entry.of,
+        base: [ ...path, n, "of" ],
+        isKind: isKind
+    }) ].map(nestedPath => ({
+        path: nestedPath,
+        entry: entry
+    })));
 }
 
-function checkSubjectEffectOutputs(def, issues) {
-    for (const [i, stage] of def.stages.entries()) for (const [j, activity] of (stage.activities ?? []).entries()) for (const [a, action] of (activity.actions ?? []).entries()) pushSubjectOutputIssues({
+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({
         action: action,
         path: [ "stages", i, "activities", j, "actions", a ],
         issues: issues
     });
 }
 
-function pushSubjectOutputIssues(args) {
+const LEVEL_KIND_OUTPUT_RULES = [ {
+    isKind: isSubjectEntry,
+    message: name => `effect "${name}" declares a \`subject\` output shape — no subject reader ever looks at effect outputs. Declare \`doc.ref\` for a document-valued output`
+}, {
+    isKind: isDueDateEntry,
+    message: name => `effect "${name}" declares a due-date output shape — a due-* kind marks THE deadline of a level, and no deadline reader looks at effect outputs. Declare \`date\` or \`datetime\` for a dated output`
+} ];
+
+function pushOutputIssues(args) {
     const {action: action, path: path, issues: issues} = args;
     for (const [e, effect] of (action.effects ?? []).entries()) {
         const base = [ ...path, "effects", e, "outputs" ];
-        for (const nestedPath of nestedSubjectPaths(effect.outputs, base)) issues.push({
+        for (const {isKind: isKind, message: message} of LEVEL_KIND_OUTPUT_RULES) for (const nestedPath of nestedKindPaths({
+            shapes: effect.outputs,
+            base: base,
+            isKind: isKind
+        })) issues.push({
             path: nestedPath,
-            message: `effect "${effect.name}" declares a \`subject\` output shape — no subject reader ever looks at effect outputs. Declare \`doc.ref\` for a document-valued output`
+            message: message(effect.name)
         });
     }
 }
@@ -3197,13 +3278,14 @@ function checkSubjectEntries(def, issues) {
             path: [ ...path, n ],
             message: "at most one subject-kind field entry per workflow — the runtime identifies THE subject by kind, and a second one makes it ambiguous"
         });
-        for (const [n, entry] of (entries ?? []).entries()) {
-            const nested = [ ...nestedSubjectPaths(entry.fields, [ ...path, n, "fields" ]), ...nestedSubjectPaths(entry.of, [ ...path, n, "of" ]) ];
-            for (const nestedPath of nested) issues.push({
-                path: nestedPath,
-                message: `${label} entry "${entry.name}" declares a \`subject\` sub-field — a nested subject can never be read as the workflow's subject. Declare \`doc.ref\` for a nested reference`
-            });
-        }
+        for (const site of belowScopeNestedSites({
+            entries: entries,
+            path: path,
+            isKind: isSubjectEntry
+        })) issues.push({
+            path: site.path,
+            message: `${label} entry "${site.entry.name}" declares a \`subject\` sub-field — a nested subject can never be read as the workflow's subject. Declare \`doc.ref\` for a nested reference`
+        });
     }
 }
 
@@ -3839,7 +3921,9 @@ const SCALAR = {
     progress: () => SCALAR,
     boolean: () => SCALAR,
     date: () => SCALAR,
+    dueDate: () => SCALAR,
     datetime: () => SCALAR,
+    dueDatetime: () => SCALAR,
     url: () => SCALAR,
     actor: () => ACTOR_VALUE,
     assignee: () => ASSIGNEE_VALUE,
@@ -3930,10 +4014,10 @@ function checkWorkflowInvariants(def) {
     checkRequiredField(def, issues), checkStart(def, issues), checkPredicates(def, issues), 
     checkUnboundConditionVars(def, issues), checkConditionFieldReads(def, issues), checkFieldReadSeeds(def, issues), 
     checkFieldReadOpValues(def, issues), checkUpdateWhereOps(def, issues), checkGuardFieldReads(def, issues), 
-    checkAssigneesEntries(def, issues), checkSubjectEntries(def, issues), checkSubjectEffectOutputs(def, issues), 
-    checkActivityTerminalPaths(def, issues), checkTerminalStageActivities(def, issues), 
-    checkTriggeredActionParams(def, issues), checkStoredRolesPlacement(def, issues), 
-    checkGroups(def, issues), issues;
+    checkAssigneesEntries(def, issues), checkDueDateEntries(def, issues), checkSubjectEntries(def, issues), 
+    checkLevelKindEffectOutputs(def, issues), checkActivityTerminalPaths(def, issues), 
+    checkTerminalStageActivities(def, issues), checkTriggeredActionParams(def, issues), 
+    checkStoredRolesPlacement(def, issues), checkGroups(def, issues), issues;
 }
 
-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, parseDefinitionSnapshotValue, 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 };
+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, directoryBridgeId, driverKind, errorMessage, evaluateCondition, evaluateConditionOutcome, evaluatePredicates, extractDocumentId, fieldTreeShape, fieldValueSchemas, firstCarriedGlobalId, 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, parseDefinitionSnapshotValue, 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 };

package/dist/define.d.cts

@@ -1148,7 +1148,9 @@ declare const FIELD_VALUE_KINDS: readonly [
   "progress",
   "boolean",
   "date",
+  "dueDate",
   "datetime",
+  "dueDatetime",
   "url",
   "actor",
   "assignee",
@@ -1879,6 +1881,10 @@ declare type TerminalActivityStatus =
  * `todoList` — ad-hoc, status-tracked work items. Sugar over `array of object
  * { label, status, assignee?, dueDate? }`; a plain checklist is this used with
  * `{label, status}` only (open ↔ done). Never a stored kind.
+ *
+ * The `dueDate` column is a `date` NAMED `dueDate`, not the {@link
+ * FieldValueMap.dueDate} kind — that kind reserves one deadline slot per level,
+ * and a repeating row has nothing to reserve.
  */
 declare type TodoListField = FieldBase<AuthoringEditable, GroupMembership> & {
   type: "todoList";