@sanity/workflow-engine 0.23.0 → 0.25.0

package/dist/define.d.ts

@@ -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";

package/dist/index.cjs

@@ -3316,6 +3316,14 @@ function latestDefinitionsGroq() {
     return `*[${scoped} && version == math::max(*[${scoped} && name == ^.name].version)] | order(name asc)`;
 }
 
+function deployedTagsGroq() {
+    return `array::unique(*[_type == "${invariants.WORKFLOW_DEFINITION_TYPE}"].tag) | order(@ asc)`;
+}
+
+function definitionTagsGroq() {
+    return `array::unique(*[_type == "${invariants.WORKFLOW_DEFINITION_TYPE}" && name == $definition].tag) | order(@ asc)`;
+}
+
 function latestDeployedDefinitions(rows) {
     const byName = /* @__PURE__ */ new Map;
     for (const row of rows) {
@@ -4128,7 +4136,7 @@ const OptionalRefTypes = v__namespace.exactOptional(v__namespace.array(v__namesp
 })), v__namespace.looseObject(invariants.tolerantEntries()({
     ...fieldArm("subject", invariants.fieldValueSchemas.subject),
     types: OptionalRefTypes
-})), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("release.ref", invariants.fieldValueSchemas["release.ref"]))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("string", invariants.fieldValueSchemas.string))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("text", invariants.fieldValueSchemas.text))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("number", invariants.fieldValueSchemas.number))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("progress", invariants.fieldValueSchemas.progress))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("boolean", invariants.fieldValueSchemas.boolean))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("date", invariants.fieldValueSchemas.date))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("datetime", invariants.fieldValueSchemas.datetime))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("url", invariants.fieldValueSchemas.url))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("actor", invariants.fieldValueSchemas.actor))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("assignee", invariants.fieldValueSchemas.assignee))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("assignees", invariants.fieldValueSchemas.assignees))), v__namespace.looseObject(invariants.tolerantEntries()({
+})), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("release.ref", invariants.fieldValueSchemas["release.ref"]))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("string", invariants.fieldValueSchemas.string))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("text", invariants.fieldValueSchemas.text))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("number", invariants.fieldValueSchemas.number))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("progress", invariants.fieldValueSchemas.progress))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("boolean", invariants.fieldValueSchemas.boolean))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("date", invariants.fieldValueSchemas.date))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("dueDate", invariants.fieldValueSchemas.dueDate))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("datetime", invariants.fieldValueSchemas.datetime))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("dueDatetime", invariants.fieldValueSchemas.dueDatetime))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("url", invariants.fieldValueSchemas.url))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("actor", invariants.fieldValueSchemas.actor))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("assignee", invariants.fieldValueSchemas.assignee))), v__namespace.looseObject(invariants.tolerantEntries()(fieldArm("assignees", invariants.fieldValueSchemas.assignees))), v__namespace.looseObject(invariants.tolerantEntries()({
     ...fieldArm("object", v__namespace.union([ v__namespace.null(), UnknownRecord ])),
     fields: v__namespace.array(PersistedFieldShapeSchema)
 })), v__namespace.looseObject(invariants.tolerantEntries()({
@@ -4805,8 +4813,11 @@ function cacheFor(client) {
 
 function ingestDirectoryRows(args) {
     const records = Array.isArray(args.response) ? args.response : [ args.response ];
-    for (const row of records) typeof row?.id != "string" || typeof row.sanityUserId != "string" || args.requested.has(row.id) && invariants.classifyPrincipalId(row.sanityUserId).namespace === "global" && (args.cache.set(row.id, row.sanityUserId), 
-    args.out.set(row.id, row.sanityUserId));
+    for (const row of records) {
+        if (typeof row?.id != "string" || !args.requested.has(row.id)) continue;
+        const globalId = invariants.directoryBridgeId(row.sanityUserId);
+        globalId !== void 0 && (args.cache.set(row.id, globalId), args.out.set(row.id, globalId));
+    }
 }
 
 async function getInstanceDocument(client, instanceId) {
@@ -5452,10 +5463,14 @@ async function resolveGlobalProjectUser(args) {
 async function ingestMemberJoin(args) {
     const {request: request, projectId: projectId, cache: cache} = args, memberIds = await projectMemberIds(request, projectId);
     if (memberIds.length === 0) return;
-    const response = await request({
+    const requested = new Set(memberIds), response = await request({
         uri: `/projects/${encodeURIComponent(projectId)}/users/${memberIds.map(encodeURIComponent).join(",")}`
     });
-    for (const row of Array.isArray(response) ? response : [ response ]) isClientProjectUser(row) && typeof row.sanityUserId == "string" && cache.set(`${projectId}:${row.sanityUserId}`, row);
+    for (const row of Array.isArray(response) ? response : [ response ]) {
+        if (!isClientProjectUser(row) || !requested.has(row.id)) continue;
+        const globalId = invariants.directoryBridgeId(row.sanityUserId);
+        globalId !== void 0 && cache.set(`${projectId}:${globalId}`, row);
+    }
 }
 
 function clientProjectUserDirectory(client, projectId) {
@@ -5477,7 +5492,10 @@ function clientProjectUserDirectory(client, projectId) {
                 }), candidate = Array.isArray(response) ? response[0] : response;
                 return candidate == null ? {
                     status: "missing"
-                } : isClientProjectUser(candidate) ? {
+                } : isClientProjectUser(candidate) ? candidate.id !== id ? {
+                    status: "inaccessible",
+                    cause: new Error(`Project-user response answered id "${candidate.id}", not the requested "${id}"`)
+                } : {
                     status: "resolved",
                     user: candidate
                 } : {
@@ -8439,14 +8457,20 @@ function cachedGrants({client: client, requestFn: requestFn, resourcePath: resou
 }
 
 async function fetchActor(client, requestFn) {
-    const [resourceUser, globalUser] = await Promise.all([ fetchCurrentUser(requestFn, "the workflow resource host"), fetchGlobalUser(client) ]), resourceId = usableId(resourceUser), globalId = usableId(globalUser.user), id = globalId ?? resourceId;
-    if (id === void 0) return;
-    refuseProjectPrincipalWithoutGlobal({
-        resourceId: resourceId,
-        globalId: globalId,
-        globalUser: globalUser
-    });
-    const roleNames = (resourceUser?.roles?.length ? resourceUser : globalUser.user)?.roles?.map(r => r.name).filter(n => !!n) ?? [];
+    const [resourceUser, globalUser] = await Promise.all([ fetchCurrentUser(requestFn, "the workflow resource host"), fetchGlobalUser(client) ]), resourceId = usableId(resourceUser), globalHostId = usableId(globalUser.user), carriedId = invariants.firstCarriedGlobalId([ globalHostId, resourceId ]), sessionId = carriedId ?? globalHostId ?? resourceId;
+    if (sessionId === void 0) return;
+    const bridge = carriedId === void 0 ? await bridgeProjectPrincipal({
+        client: client,
+        sessionId: sessionId,
+        resourceId: resourceId
+    }) : NO_BRIDGE, id = bridge.status === "resolved" ? bridge.globalId : sessionId;
+    refuseProjectScopedActor({
+        id: id,
+        globalUser: globalUser,
+        globalHostId: globalHostId,
+        bridgeFailure: bridge.status === "unavailable" ? bridge : void 0
+    });
+    const roleNames = roleNamesFor(resourceUser, globalUser);
     return {
         actor: {
             kind: "person",
@@ -8461,13 +8485,62 @@ async function fetchActor(client, requestFn) {
     };
 }
 
-function refuseProjectPrincipalWithoutGlobal(args) {
-    const {resourceId: resourceId, globalId: globalId, globalUser: globalUser} = args;
-    if (globalId !== void 0 || resourceId === void 0 || invariants.classifyPrincipalId(resourceId).namespace !== "project") return;
-    const reason = "reason" in globalUser ? globalUser.reason : "no record";
-    throw new Error(`workflow: the caller's identity on the workflow resource host is project-scoped ("${resourceId}") and the account-global record could not be resolved (${reason}). The engine speaks account-global user ids only and never acts as a project-scoped principal.`, "cause" in globalUser ? {
-        cause: globalUser.cause
-    } : void 0);
+function roleNamesFor(resourceUser, globalUser) {
+    return (resourceUser?.roles?.length ? resourceUser : globalUser.user)?.roles?.map(r => r.name).filter(n => !!n) ?? [];
+}
+
+const NO_BRIDGE = {
+    status: "not-applicable"
+};
+
+function globalRouteReason(globalUser, globalHostId) {
+    return "reason" in globalUser ? globalUser.reason : globalHostId === void 0 ? "no record" : `the global host answered with project-scoped principal "${globalHostId}"`;
+}
+
+async function bridgeProjectPrincipal(args) {
+    const {client: client, sessionId: sessionId, resourceId: resourceId} = args;
+    return invariants.classifyPrincipalId(sessionId).namespace !== "project" ? NO_BRIDGE : resourceId === void 0 || invariants.classifyPrincipalId(resourceId).namespace !== "project" ? {
+        status: "unavailable",
+        reason: "no project-scoped principal from the resource host to address the directory with"
+    } : directoryGlobalId({
+        client: client,
+        principalId: resourceId
+    });
+}
+
+async function directoryGlobalId(args) {
+    const {client: client, principalId: principalId} = args, projectId = typeof client.config == "function" ? client.config().projectId : void 0;
+    if (projectId === void 0) return {
+        status: "unavailable",
+        reason: "the client reports no projectId, so its user directory has no address"
+    };
+    const lookup = await clientProjectUserDirectory(withRequestTag(client, REQUEST_TAG.accessResolveActor), projectId).findById(principalId);
+    if (lookup.status !== "resolved") return {
+        status: "unavailable",
+        reason: `project "${projectId}"'s user directory reported the principal ${lookup.status}`,
+        ...lookup.status === "inaccessible" && lookup.cause !== void 0 ? {
+            cause: lookup.cause
+        } : {}
+    };
+    const globalId = invariants.directoryBridgeId(lookup.user.sanityUserId);
+    return globalId === void 0 ? {
+        status: "unavailable",
+        reason: `project "${projectId}"'s user directory row for the principal carries no account-global sanityUserId`
+    } : {
+        status: "resolved",
+        globalId: globalId
+    };
+}
+
+function refuseProjectScopedActor(args) {
+    const {id: id, globalUser: globalUser, globalHostId: globalHostId, bridgeFailure: bridgeFailure} = args;
+    if (invariants.classifyPrincipalId(id).namespace !== "project") return;
+    const routes = [ `The account-global record: ${globalRouteReason(globalUser, globalHostId)}.` ];
+    bridgeFailure !== void 0 && routes.push(`The project user directory: ${bridgeFailure.reason}.`);
+    const cause = bridgeFailure?.cause ?? ("cause" in globalUser ? globalUser.cause : void 0);
+    throw new Error(`workflow: the caller's identity resolves to the project-scoped principal "${id}" and its account-global id could not be resolved. ${routes.join(" ")} The engine speaks account-global user ids only and never acts as a project-scoped principal.`, cause === void 0 ? void 0 : {
+        cause: cause
+    });
 }
 
 function usableId(user) {
@@ -12775,10 +12848,18 @@ const HISTORY_DISPLAY = {
         title: "Date value",
         description: "Date-only (YYYY-MM-DD) entry, no time component."
     },
+    dueDate: {
+        title: "Due date",
+        description: "THE due date for a level — same value as a date, elevated so surfaces identify the deadline by kind."
+    },
     datetime: {
         title: "Date / time value",
         description: "ISO-8601 timestamp entry."
     },
+    dueDatetime: {
+        title: "Due date / time",
+        description: "THE due datetime for a level — same value as a date/time, the timestamp counterpart of a due date."
+    },
     url: {
         title: "URL value",
         description: "Validated URL entry."
@@ -13118,6 +13199,20 @@ Object.defineProperty(exports, "MAX_COUNTERFACTUAL_INDEX", {
     }
 });
 
+Object.defineProperty(exports, "NEUTRAL_MARK", {
+    enumerable: !0,
+    get: function() {
+        return groqConditionDescribe.NEUTRAL_MARK;
+    }
+});
+
+Object.defineProperty(exports, "OUTCOME_MARKS", {
+    enumerable: !0,
+    get: function() {
+        return groqConditionDescribe.OUTCOME_MARKS;
+    }
+});
+
 Object.defineProperty(exports, "analyzeCondition", {
     enumerable: !0,
     get: function() {
@@ -13359,6 +13454,8 @@ exports.definitionDeployedData = definitionDeployedData;
 
 exports.definitionLookupGroq = definitionLookupGroq;
 
+exports.definitionTagsGroq = definitionTagsGroq;
+
 exports.definitionsListGroq = definitionsListGroq;
 
 exports.deniedGuardLabels = deniedGuardLabels;
@@ -13369,6 +13466,8 @@ exports.denyingGuards = denyingGuards;
 
 exports.deployStageGuards = deployStageGuards;
 
+exports.deployedTagsGroq = deployedTagsGroq;
+
 exports.deriveWorkflowAutonomy = deriveWorkflowAutonomy;
 
 exports.describeAtom = describeAtom;

package/dist/index.d.cts

@@ -20,6 +20,8 @@ import { humanize } from "@sanity/groq-condition-describe";
 import { InsightPhrase } from "@sanity/groq-condition-describe";
 import { isComparisonOp } from "@sanity/groq-condition-describe";
 import { MAX_COUNTERFACTUAL_INDEX } from "@sanity/groq-condition-describe";
+import { NEUTRAL_MARK } from "@sanity/groq-condition-describe";
+import { OUTCOME_MARKS } from "@sanity/groq-condition-describe";
 import { quoted } from "@sanity/groq-condition-describe";
 import type { SanityDocument } from "@sanity/types";
 import { ScopeAssignment } from "@sanity/groq-condition-describe";
@@ -551,14 +553,17 @@ export declare type ActivityStatus = (typeof ACTIVITY_STATUSES)[number];
  * read time, and only the lake's own token identity is authenticated — hard
  * enforcement lives there.
  *
- * `id` is the account-global user id (the global API host's `/users/me`) —
- * the one identity namespace that is stable across projects and org-level
- * resources. Robot tokens carry a single universal id, so for them `id`
- * equals what every host returns. Instances written before ids were
- * namespace-classified carry the workflow resource's local principal id in
- * `id` instead; readers interpret those through the prefix classifier in
- * `core/identity.ts` with the document's home resource as the implied
- * scope.
+ * `id` is the account-global user id — the one identity namespace that is
+ * stable across projects and org-level resources. The engine takes it from the
+ * first route that can answer for the token: an id either host's `/users/me`
+ * already carries in account-global form (the id itself, or the one embedded in
+ * an `e-` principal), and otherwise the project's own user directory
+ * (`sanityUserId`) — the route a session scoped to a single project depends on,
+ * since no global record exists for it. Robot tokens carry a single universal
+ * id, so for them `id` equals what every host returns. Instances written before
+ * ids were namespace-classified carry the workflow resource's local principal id
+ * in `id` instead; readers interpret those through the prefix classifier in
+ * `core/identity.ts` with the document's home resource as the implied scope.
  */
 export declare interface Actor {
   kind: ActorKind;
@@ -1680,7 +1685,8 @@ export declare interface ClientProjectUser {
   readonly [key: string]: unknown;
 }
 
-/** Project-user directory for CLI, MCP, and server runtimes using the engine client. */
+/** Project-user directory served straight from the engine's own client — the
+ *  project API's user endpoints, no host adapter. */
 export declare function clientProjectUserDirectory(
   client: WorkflowClient,
   projectId: string,
@@ -2357,6 +2363,15 @@ export declare const DATA_MODEL_CHANGES: readonly [
     applicability: "detectable";
     summary: "Start and activity readiness use named polymorphic requirement arrays.";
   }>,
+  Readonly<{
+    id: "due-date-field-kinds";
+    introducedInModel: 5;
+    minReaderModel: 0;
+    documentTypes: readonly ["definition", "instance"];
+    compatibility: "additive";
+    applicability: "detectable";
+    summary: string;
+  }>,
 ];
 
 /**
@@ -2381,7 +2396,7 @@ export declare const DATA_MODEL_MIN_READER = 4;
  * job. Declare every bump in `DATAMODEL.md`; the model-surface snapshot test
  * keeps undeclared drift red.
  */
-export declare const DATA_MODEL_VERSION = 4;
+export declare const DATA_MODEL_VERSION = 5;
 
 export declare interface DataModelChange {
   readonly id: string;
@@ -2537,10 +2552,13 @@ export declare class DefinitionInUseError extends WorkflowError<"definition-in-u
 }
 
 /**
- * Pure GROQ builder for resolving a deployed workflow definition. Composes the
- * doc-type constant and the tag-scope predicate so the engine's internal
- * lookups and the CLI share one definition of "tag-scoped, latest-or-pinned
+ * Pure GROQ builders for deployed workflow definitions. Composes the doc-type
+ * constant and the tag-scope predicate so the engine's internal lookups and the
+ * CLI share one definition of "tag-scoped, latest-or-pinned
  * `workflow.definition`" instead of hand-writing the query at each call site.
+ *
+ * The tag enumerations are the deliberate exception: they span partitions, for a
+ * caller holding a resource but no tag yet.
  */
 /**
  * GROQ resolving a single deployed {@link WORKFLOW_DEFINITION_TYPE} visible to
@@ -2599,6 +2617,19 @@ export declare function definitionsListGroq(
   versionOrder: "asc" | "desc",
 ): string;
 
+/**
+ * GROQ listing every tag partition that holds any version of one definition
+ * name — {@link deployedTagsGroq} narrowed from "what exists here" to "where
+ * is this".
+ *
+ * Several hits is ambiguity to refuse, not resolve: version numbers are
+ * per-partition, so the highest one may sit in an environment the caller did
+ * not mean, and the answer would carry no sign of it.
+ *
+ * Params: `$definition`.
+ */
+export declare function definitionTagsGroq(): string;
+
 export declare interface DeleteDefinitionArgs {
   /** The definition's `name` — delete addresses the workflow, not a doc id. */
   definition: string;
@@ -2748,6 +2779,13 @@ export declare type DeployedDefinition = WorkflowDefinition & {
   minReaderModel?: number;
 };
 
+/**
+ * GROQ listing every tag partition holding a deployed
+ * {@link WORKFLOW_DEFINITION_TYPE} in the resource. The un-scoped
+ * inverse of {@link tagScopeFilter}, this deliberately spans partitions.
+ */
+export declare function deployedTagsGroq(): string;
+
 /**
  * Deploy every guard for a stage being entered (idempotent upsert), but only
  * while the instance is still committed to that stage. A deploy that lost the
@@ -3999,7 +4037,7 @@ export declare interface EvaluateArgs {
   instanceId: string;
   /**
    * URL path on the supplied client where the engine should fetch
-   * grants. The actor always token-resolves via `/users/me`; without
+   * grants. The actor always token-resolves from the supplied client; without
    * a grants path the rendered `$can` is undefined, so conditions
    * referencing it fail closed — and the real Sanity write boundary
    * still enforces.
@@ -4337,10 +4375,18 @@ export declare const FIELD_KIND_DISPLAY: {
     title: string;
     description: string;
   };
+  dueDate: {
+    title: string;
+    description: string;
+  };
   datetime: {
     title: string;
     description: string;
   };
+  dueDatetime: {
+    title: string;
+    description: string;
+  };
   url: {
     title: string;
     description: string;
@@ -4389,7 +4435,9 @@ declare const FIELD_VALUE_KINDS: readonly [
   "progress",
   "boolean",
   "date",
+  "dueDate",
   "datetime",
+  "dueDatetime",
   "url",
   "actor",
   "assignee",
@@ -4534,8 +4582,12 @@ export declare interface FieldValueMap {
   boolean: boolean | null;
   /** Date-only (`YYYY-MM-DD`), no time component. */
   date: string | null;
+  /** THE due date of a level — same value as {@link FieldValueMap.date}. */
+  dueDate: string | null;
   /** ISO-8601 timestamp. */
   datetime: string | null;
+  /** THE due datetime of a level — same value as {@link FieldValueMap.datetime}. */
+  dueDatetime: string | null;
   url: string | null;
   actor: Actor | null;
   /** A single {@link Assignee} — the singular of {@link FieldValueMap.assignees}. */
@@ -6368,6 +6420,8 @@ export declare function narrateAutonomyWaits(
   ctx: DescribeContext,
 ): string[];
 
+export { NEUTRAL_MARK };
+
 /** The default logger: emit nothing. The engine's twin of `@sanity/telemetry`'s `noopLogger`. */
 export declare const noopTelemetry: WorkflowTelemetryLogger;
 
@@ -6470,6 +6524,8 @@ export declare interface OperationResult {
   ranOps?: OpAppliedSummary[];
 }
 
+export { OUTCOME_MARKS };
+
 /**
  * The instance's direct parent — the last entry of the root-first
  * {@link WorkflowInstance.ancestors} chain; `undefined` for a root instance.
@@ -6796,7 +6852,7 @@ export declare class ReaderModelAcknowledgementError extends WorkflowError<"read
   readonly code = "WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH";
   readonly expectedMinReaderModel: unknown;
   readonly engineMinReaderModel = 4;
-  readonly engineModelVersion = 4;
+  readonly engineModelVersion = 5;
   readonly documentationUrl =
     "https://www.sanity.io/docs/editorial-workflows/prerelease";
   constructor(expectedMinReaderModel: unknown, context?: string);
@@ -7690,8 +7746,8 @@ export declare interface StartInstanceArgs {
   instanceId?: string;
   /**
    * URL path on the supplied client where the engine fetches the
-   * caller's ACL grants. Identity is always token-resolved — `actor`
-   * comes from `client.request({ uri: "/users/me" })` — and grants
+   * caller's ACL grants. Identity is always token-resolved — `actor` is
+   * resolved from the supplied client's token, never passed in — and grants
    * feed the advisory `$can.*` params action conditions can read;
    * omitting this leaves the rendered `$can` undefined (conditions
    * referencing it fail closed, nothing else is gated engine-side —
@@ -8639,6 +8695,10 @@ export declare function toBareId(id: string): string;
  * `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";
@@ -9332,10 +9392,14 @@ export declare interface WorkflowAutonomy extends AutonomyAnswer {
 
 export declare interface WorkflowClient {
   /**
-   * Read the effective client configuration. The engine probes `apiHost`
-   * before deriving the global `/users/me` sibling because `@sanity/client`
-   * shallow-merges `withConfig` overrides and otherwise preserves an explicit
-   * project host even when `useProjectHostname` is set to `false`.
+   * Read the effective client configuration. The engine reads two fields from
+   * it. `apiHost` is probed before deriving the global `/users/me` sibling,
+   * because `@sanity/client` shallow-merges `withConfig` overrides and
+   * otherwise preserves an explicit project host even when
+   * `useProjectHostname` is set to `false`. `projectId` addresses the project's
+   * user directory when a project-scoped principal has to be bridged to its
+   * account-global id — a client reporting none has no directory to ask, and
+   * such a session is refused rather than stamped locally.
    */
   config?: () => WorkflowClientConfig;
   fetch: <T = unknown>(