@sanity/workflow-engine 0.19.0 → 0.21.0

package/dist/index.d.ts

@@ -203,7 +203,7 @@ declare const ActionParamSchema: v.SchemaWithPipe<
             "doc.refs",
             "json",
           ],
-          `Invalid option: expected one of ${string}`
+          string
         >;
         readonly name: v.SchemaWithPipe<
           readonly [
@@ -508,15 +508,15 @@ export declare interface ActivityEvaluation {
    */
   scopedOut: boolean;
   /**
-   * The activity's unmet {@link Activity.requirements}, by name — present iff at least
+   * The activity's unmet {@link Activity.requirements}, with authored display copy — present iff at least
    * one is unmet. The activity's own readiness summary: a consumer can explain why
    * the whole activity is gated without inspecting each action (every action also
    * carries the matching `requirements-unmet` `disabledReason`).
    */
-  unmetRequirements?: string[];
+  unmetRequirements?: RequirementDescriptor[];
   /** Derived state per declared requirement, keyed by requirement name.
    *  Present iff the activity declares requirements; `unmetRequirements`
-   *  is exactly the keys whose insight isn't satisfied. */
+   *  contains descriptors for exactly the requirements whose insight isn't satisfied. */
   requirementInsights?: Record<string, ConditionInsight>;
   /** Derived state of the activity's `filter` existence gate. Present iff
    *  declared. Advisory read: the engine's stage entry owns the gate itself. */
@@ -533,7 +533,7 @@ declare type ActivityFields<TField, TAction, TTarget, TGroup> = {
   group?: TGroup | undefined;
   target?: TTarget | undefined;
   filter?: string | undefined;
-  requirements?: Record<string, string> | undefined;
+  requirements?: GroqRequirement[] | undefined;
   actions?: TAction[] | undefined;
   fields?: TField[] | undefined;
 };
@@ -546,20 +546,31 @@ export declare type ActivityStatus = (typeof ACTIVITY_STATUSES)[number];
 
 /**
  * Who is acting — advisory provenance, not an authenticated principal. The
- * engine always resolves it from the client's token (`/users/me`); there is
- * no way to pass or synthesize one. The stamp is still advisory: nothing
- * re-verifies it at read time, and only the lake's own token identity is
- * authenticated — hard enforcement lives there.
+ * engine always resolves it from the client's token; there is no way to pass
+ * or synthesize one. The stamp is still advisory: nothing re-verifies it at
+ * 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.
  */
 export declare interface Actor {
   kind: ActorKind;
   id: string;
   /**
    * Free-form role names — typically a copy of Sanity's `user.roles[].name`
-   * for the token behind the call. The engine treats these as opaque
-   * strings, matched by literal membership: `Action.roles` and `assignees`
-   * roles OR-match against this list. There is no actor-side wildcard — a
-   * `"*"` here is just a literal string and matches nothing on its own.
+   * for the token behind the call, as the workflow resource's host reports
+   * them (project roles for dataset resources). The engine treats these as
+   * opaque strings, matched by literal membership: `Action.roles` and
+   * `assignees` roles OR-match against this list. There is no actor-side
+   * wildcard — a `"*"` here is just a literal string and matches nothing on
+   * its own.
    *
    * To let one role satisfy a gate it doesn't literally name — e.g. an
    * `administrator` satisfying a narrower gate, or one deployment's role
@@ -597,6 +608,9 @@ export declare type ActorResolution<User> =
 
 export { analyzeCondition };
 
+/** Lake `identity()` sentinel for unauthenticated callers. */
+export declare const ANONYMOUS_IDENTITY = "<anonymous>";
+
 /** The definition surface the start contexts read — structural, so authored,
  *  stored, and deployed definition shapes all fit. `name` binds
  *  `$definition` and names the definition in a broken-predicate error. */
@@ -608,7 +622,7 @@ export declare interface ApplicabilitySource {
     | {
         kind?: StartKind | undefined;
         filter?: string | undefined;
-        allowed?: string | undefined;
+        requirements?: StartRequirement[] | undefined;
       }
     | undefined;
 }
@@ -747,10 +761,7 @@ declare type AuthoringFieldRef = v.InferOutput<typeof AuthoringFieldRefSchema>;
 declare const AuthoringFieldRefSchema: v.StrictObjectSchema<
   {
     readonly scope: v.OptionalSchema<
-      v.PicklistSchema<
-        readonly ["workflow", "stage", "activity"],
-        `Invalid option: expected one of ${string}`
-      >,
+      v.PicklistSchema<readonly ["workflow", "stage", "activity"], string>,
       undefined
     >;
     readonly field: v.SchemaWithPipe<
@@ -916,7 +927,7 @@ declare const AuthoringGuardSchema: v.StrictObjectSchema<
             v.ArraySchema<
               v.PicklistSchema<
                 readonly ["create", "update", "delete", "publish", "unpublish"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >,
@@ -1091,7 +1102,7 @@ declare const AuthoringManualTargetSchema: v.VariantSchema<
                 readonly scope: v.OptionalSchema<
                   v.PicklistSchema<
                     readonly ["workflow", "stage", "activity"],
-                    `Invalid option: expected one of ${string}`
+                    string
                   >,
                   undefined
                 >;
@@ -1127,7 +1138,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1152,7 +1163,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1176,7 +1187,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1201,7 +1212,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1232,7 +1243,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1268,7 +1279,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
         >;
         readonly status: v.PicklistSchema<
           readonly ["active", "done", "skipped", "failed"],
-          `Invalid option: expected one of ${string}`
+          string
         >;
       },
       undefined
@@ -1281,7 +1292,7 @@ declare const AuthoringOpSchema: v.VariantSchema<
             readonly scope: v.OptionalSchema<
               v.PicklistSchema<
                 readonly ["workflow", "stage", "activity"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >;
@@ -1609,6 +1620,25 @@ declare type ClaimField = {
   group?: GroupMembership | undefined;
 };
 
+export declare interface ClassifiedPrincipal {
+  namespace: PrincipalNamespace;
+  /**
+   * The account-global id when the string itself carries it: the id verbatim
+   * for `global` and `robot` (a robot's single id IS its universal identity),
+   * the embedded global id for `e-` project ids. Absent for plain `project`
+   * ids (resolving those needs the project-users directory), sentinels, and
+   * unknowns.
+   */
+  globalId?: string;
+}
+
+/**
+ * Classify a bare principal-id string by its namespace. Total — never
+ * throws; ids that fit no known form come back `unknown` so the caller
+ * decides how loud to be.
+ */
+export declare function classifyPrincipalId(id: string): ClassifiedPrincipal;
+
 /**
  * The `@sanity/client`-config fragment that addresses a {@link WorkflowResource}
  * — the one home for the dataset-vs-resource branch every client-building host
@@ -1637,6 +1667,13 @@ declare type ClientForGdr = (parsed: ParsedGdr) => WorkflowClient;
 /** Native project-user response returned by Sanity's project API. */
 export declare interface ClientProjectUser {
   readonly id: string;
+  /**
+   * The person's account-global user id — the canonical identity every
+   * workflow value stores. This is the sanctioned bridge between a
+   * project's local principal namespace and the global one; surfaces use
+   * it to emit assignment values from project-member displays.
+   */
+  readonly sanityUserId?: string;
   readonly displayName?: string;
   readonly email?: string;
   readonly imageUrl?: string | null;
@@ -1969,14 +2006,15 @@ export declare interface ConditionVar {
  *    the rest evaluate to `undefined` — and deploy rejects them at these
  *    sites; a cascade-fired action's per-token gate is `roles`, never its
  *    conditions.
- * 3. **The start contexts** — a definition's `start.filter` and
- *    `start.allowed` evaluate against a CANDIDATE (no instance exists yet):
- *    `*[...]` reads the WORKFLOW resource's dataset and none of the rendered
+ * 3. **The start contexts** — a definition's `start.filter` and start GROQ
+ *    requirements evaluate against a CANDIDATE (no instance exists yet):
+ *    `*[...]` reads the engine-owned `{definition, subject, completedAt}`
+ *    projection of the tag's instances and none of the rendered
  *    condition vars exist. The two split on what a surface can know:
  *    `filter` is browse-time-pure (candidate document as root,
  *    {@link START_FILTER_VARS} — no `$fields`, which cannot exist before
- *    inputs do), `allowed` is the start-time permission predicate
- *    ({@link START_ALLOWED_VARS} — `$fields` bound, never a root).
+ *    inputs do), a `groq` requirement is the start-time readiness predicate
+ *    ({@link START_REQUIREMENT_VARS} — `$fields` bound, never a root).
  * 4. **Guard predicates** — NOT conditions. A lake mutation guard's
  *    `predicate` is groq-js **delta-mode** GROQ over a document mutation:
  *    `before()`/`after()`/`identity()` are dialect natives, and the wire
@@ -1997,10 +2035,9 @@ export declare type ConditionVarBinding = "always" | "caller" | "spawn";
 
 /**
  * The one-doc read a reactive adapter subscribes with to observe a content doc
- * under a perspective stack — the same GROQ as the engine's own hydration read
- * ({@link hydrateSnapshot}), so the adapter and the engine resolve identical
- * content: draft/version content projected onto the published id, a doc that
- * exists only as a draft (or only inside a release) still visible.
+ * under a perspective stack. It uses the same perspective semantics as
+ * {@link hydrateSnapshot}: draft/version content is projected onto the published
+ * id, and a doc that exists only as a draft or release version remains visible.
  */
 export declare function contentDocQuery(documentId: string): CompiledQuery;
 
@@ -2302,6 +2339,24 @@ export declare const DATA_MODEL_CHANGES: readonly [
     applicability: "detectable";
     summary: "Pending-effect claims carry an exact-claim token gating mid-dispatch state reports.";
   }>,
+  Readonly<{
+    id: "classified-principal-ids";
+    introducedInModel: 4;
+    minReaderModel: 4;
+    documentTypes: readonly ["instance"];
+    compatibility: "reader-floor";
+    applicability: "unconditional";
+    summary: string;
+  }>,
+  Readonly<{
+    id: "readiness-requirements";
+    introducedInModel: 4;
+    minReaderModel: 4;
+    documentTypes: readonly ["definition"];
+    compatibility: "reader-floor";
+    applicability: "detectable";
+    summary: "Start and activity readiness use named polymorphic requirement arrays.";
+  }>,
 ];
 
 /**
@@ -2311,7 +2366,7 @@ export declare const DATA_MODEL_CHANGES: readonly [
  * carry a lower floor. Raising this maximum is a declared, DATAMODEL.md-logged
  * decision that requires readers-first fleet sequencing.
  */
-export declare const DATA_MODEL_MIN_READER = 2;
+export declare const DATA_MODEL_MIN_READER = 4;
 
 /**
  * The engine's persisted data-model version — the provenance half of
@@ -2326,7 +2381,7 @@ export declare const DATA_MODEL_MIN_READER = 2;
  * job. Declare every bump in `DATAMODEL.md`; the model-surface snapshot test
  * keeps undeclared drift red.
  */
-export declare const DATA_MODEL_VERSION = 3;
+export declare const DATA_MODEL_VERSION = 4;
 
 export declare interface DataModelChange {
   readonly id: string;
@@ -2515,10 +2570,6 @@ export declare interface DefinitionsForDocumentArgs {
    * perspective the caller loaded the document with.
    */
   document: CandidateDocument;
-  /** Resource-qualified identity of `document`. Required when an applicable
-   *  definition's `start.filter` reads `$subjectHasInFlightInstance`; the
-   *  loaded value's bare `_id` cannot distinguish resources. */
-  subject?: GdrUri;
 }
 
 /** A definition-level site address: every runtime {@link InsightSite}, plus
@@ -2539,9 +2590,8 @@ export declare type DefinitionSiteAddress =
 
 /**
  * GROQ listing EVERY deployed {@link WORKFLOW_DEFINITION_TYPE} visible to the
- * caller's tag, grouped by name. `versionOrder` picks the in-group direction:
- * `'desc'` puts each name's latest first (discovery keeps the head per name),
- * `'asc'` walks history oldest-first (handler verification reads them all).
+ * caller's tag, grouped by name. `versionOrder` picks the in-group direction;
+ * handler verification uses oldest-first order while inspecting every version.
  *
  * Params: `$tag`.
  */
@@ -3045,13 +3095,13 @@ export declare type DisabledReason =
       /**
        * The activity's declared {@link Activity.requirements} aren't all satisfied —
        * the readiness axis. The activity is visible and the actor authorized, but
-       * its own preconditions don't hold yet. `unmetRequirements` names the
-       * failing keys so a consumer can disable the affirmative control and say
+       * its own preconditions don't hold yet. `unmetRequirements` carries the
+       * authored descriptors so a consumer can disable the affirmative control and say
        * which precondition is outstanding. Distinct from `filter-failed`
        * (visibility/authorization) and `mutation-guard-denied` (content-write).
        */
       kind: "requirements-unmet";
-      unmetRequirements: string[];
+      unmetRequirements: RequirementDescriptor[];
     }
   | {
       /**
@@ -3136,7 +3186,8 @@ export declare interface DocumentActionDenialsArgs {
   };
   action: MutationGuardAction;
   guards: readonly MutationGuardDoc[];
-  /** Actor id, resolved as `identity()` in predicates. */
+  /** The caller's principal id in the guarded resource's own namespace,
+   *  resolved as `identity()` in predicates. */
   identity?: string;
 }
 
@@ -3151,10 +3202,8 @@ declare type DocumentEnvelopeKey =
   | "minReaderModel";
 
 /**
- * The document-prefilter GROQ arm — matches instances that MAY reference any
- * of `documents`. A deliberate lake-side SUPERSET (it also matches
- * exited-stage refs); narrow fetched rows to the exact watch-set with
- * {@link instanceWatchesDocument}. Binds `$documents` + `$bareIds` into
+ * The document GROQ arm — matches instances whose reactive watch-set
+ * references any of `documents`. Binds `$documents` + `$bareIds` into
  * `params`. Exposed for list builders that compose their own conditions
  * (e.g. the CLI's cross-partition list); {@link instancesQuery} consumers get
  * it via the `document`/`documents` filter fields instead.
@@ -3457,11 +3506,13 @@ export declare type EffectHandler<
  */
 declare type EffectHandlerContext<Client extends WorkflowClient> = {
   /**
-   * The exact concrete client supplied to `createEngine`, bound to the
-   * workflow resource rather than an
-   * engine wrapper. Its class identity, namespaces, configuration, and
-   * credentials are preserved. Handler-owned requests are not automatically
-   * tagged by the engine.
+   * A concrete sibling of the client supplied to `createEngine`, bound to the
+   * workflow resource with the same namespaces and credentials. Untagged
+   * handler requests on its workflow-client surface carry the `workflow.effect`
+   * request tag by default. A concrete client's explicit tags compose beneath
+   * that prefix. On the structural fallback for minimal clients, pass-through
+   * namespaces are not stamped and core builders expose the engine's minimal
+   * workflow-client surface.
    */
   client: Client;
   /**
@@ -3477,8 +3528,8 @@ declare type EffectHandlerContext<Client extends WorkflowClient> = {
    * {@link GlobalDocumentReference}. Returns the `resourceClients` client
    * for that resource when one is mapped, {@link client} for the workflow
    * resource itself, and a sibling derived from {@link client}'s
-   * credentials otherwise. Mapped clients are returned unchanged; an
-   * unmapped foreign resource necessarily returns a configured sibling.
+   * credentials otherwise. Returned clients preserve their concrete APIs and
+   * apply the same default effect request tag.
    * Throws if `ref` isn't a GDR — a bare id can't
    * be routed, so failing loud beats silently patching the wrong dataset.
    */
@@ -3733,6 +3784,9 @@ export declare interface Engine {
   setStage: (args: SetStageArgs) => Promise<OperationResult>;
   /** Admin override — hard-stop an in-flight instance where it stands. */
   abortInstance: (args: AbortInstanceArgs) => Promise<OperationResult>;
+  /** Admin override — reset a failed/terminal activity in the current stage
+   *  back to `active` (re-run) or `skipped` (bypass), then cascade. */
+  resetActivity: (args: ResetActivityArgs) => Promise<OperationResult>;
   /** Admin override — remove a deployed definition (instances are only ever aborted, never deleted). */
   deleteDefinition: (
     args: DeleteDefinitionArgs,
@@ -3792,12 +3846,13 @@ export declare interface Engine {
     args: DefinitionsForDocumentArgs,
   ) => Promise<DeployedDefinition[]>;
   /** Pre-flight `startInstance`'s gates for a definition + the
-   *  `initialFields` gathered so far: structurally invalid rows, the
-   *  `start.allowed` verdict with its insight, and still-missing required
-   *  inputs. `allowed` is the overall startability signal; `outcome` describes
-   *  only the condition. Bindability-aware — a
-   *  predicate reading a not-yet-supplied entry reports `'unevaluable'`
-   *  with the entries named in `unboundReads`, never a collapsed verdict.
+   *  `initialFields` gathered so far: structurally invalid rows, every
+   *  requirement's ordered descriptor/outcome/insight, and still-missing
+   *  required inputs. `allowed` is the overall startability signal; `outcome`
+   *  aggregates the requirements. Bindability-aware — a requirement reading
+   *  a not-yet-supplied entry (including `singleSubject`'s implicit subject
+   *  read) reports `'unevaluable'` with the entries named
+   *  in `unboundReads`, never a collapsed verdict.
    *  Pure read; the enforcement moment is `startInstance` itself. */
   evaluateStart: (args: EvaluateStartArgs) => Promise<StartEvaluation>;
   /** GROQ query against the engine's workflow resource. `$tag`
@@ -3845,10 +3900,10 @@ export declare interface Engine {
  * {@link WorkflowClient.withConfig}, and `resourceClients`-resolved clients
  * are rebound the same way. A caller's configured `apiVersion` therefore
  * never reaches engine-owned traffic (the caller's own client instance is
- * untouched). Effect handlers are host traffic and deliberately receive the
- * caller's configuration unchanged. The other exception is a client that lacks `withConfig` and so
- * cannot be rebound — it must be built to serve this version; see
- * {@link WorkflowClient.withConfig}.
+ * untouched). Effect handlers keep the caller's `apiVersion`; their derived
+ * clients change only the request-tag prefix. The other exception is a client
+ * that lacks `withConfig` and so cannot be rebound — it must be built to serve
+ * this version; see {@link WorkflowClient.withConfig}.
  */
 export declare const ENGINE_API_VERSION = "2026-04-29";
 
@@ -3969,6 +4024,13 @@ export declare interface EvaluateFromSnapshotArgs {
   instance: WorkflowInstance;
   definition: WorkflowDefinition;
   actor: Actor;
+  /**
+   * The actor's principal id in the workflow resource's own identity
+   * namespace — the comparand for everything the resource's lake evaluates
+   * (`identity()` in guard predicates, the anchor ACL's grant filters).
+   * Omitted when it equals {@link Actor.id} (org-level resources, robots).
+   */
+  localPrincipalId?: string;
   /**
    * Resolved grants for the actor. Omit to leave the rendered `$can`
    * undefined (conditions referencing it fail closed — the real lake
@@ -3998,14 +4060,16 @@ export declare interface EvaluateFromSnapshotArgs {
    */
   guards?: readonly MutationGuardDoc[];
   /**
-   * The actor's ACL grants per FOREIGN subject resource, keyed by
-   * resource-shaped GDR (`<type>:<id>`) — feeds the subject-write forecast on
-   * effects-bearing actions ({@link SubjectPermissionDenial}). Omit, or omit a
-   * resource, to skip that resource's forecast (degrade open — the subject's
-   * lake still enforces). {@link evaluateInstance} resolves this through each
+   * Per-FOREIGN-subject-resource access — the actor's ACL grants PLUS the
+   * actor's principal id in that resource's own namespace — keyed by
+   * resource-shaped GDR (`<type>:<id>`); feeds the subject-write forecast on
+   * effects-bearing actions ({@link SubjectPermissionDenial}). A resource
+   * appears only when both halves resolved; omit it (or the whole map) to
+   * skip that resource's forecast (degrade open — the subject's lake still
+   * enforces). {@link evaluateInstance} resolves this through each
    * resource's own client via {@link subjectResourceGrants}.
    */
-  resourceGrants?: ReadonlyMap<string, Grant[]>;
+  resourceGrants?: ReadonlyMap<string, SubjectResourceAccess>;
 }
 
 /**
@@ -4042,15 +4106,13 @@ export declare interface EvaluateStartArgs {
  * be absent — a root read is then GROQ null, fail-closed or vacuous-pass by
  * shape) as the GROQ root, the {@link StartScope} bindings plus
  * `$definition`, and — when `analyzeCondition` says the filter reads the
- * dataset or the filter reads `$subjectHasInFlightInstance` — the scope's
- * fetched slice as `*`. Cheap pure evaluation otherwise: no I/O rides a
+ * dataset — the scope's fetched slice as `*`. Cheap pure evaluation otherwise: no I/O rides a
  * filter that needs neither. GROQ null ("can't decide") is `false` — every consumer of
  * this verdict fails closed; a parse/evaluation THROW is a malformed
  * predicate, not an unevaluable one — rethrown loud, naming the definition,
  * so every read surface that evaluates the filter reports the same context.
- * A caller that omits the prospective subject required by the synthetic
- * variable also throws as a scope-contract error. A failed slice FETCH
- * propagates as itself: transport trouble, never definition blame.
+ * A failed slice FETCH propagates as itself: transport trouble, never
+ * definition blame.
  */
 export declare function evaluateStartFilter(args: {
   filter: string;
@@ -4167,7 +4229,7 @@ export { explainCondition };
 export { ExplainConditionArgs };
 
 /**
- * Explain one `start.allowed` in the start-allowed context: no root (the
+ * Explain one start GROQ requirement in the start-requirement context: no root (the
  * subject rides `$fields.<entry>.id` — deploy rejects a root read), the
  * {@link StartScope} bindings plus `$definition` and the caller's `$fields`
  * map, and the scope's fetched slice as `*` when the predicate reads the
@@ -4185,8 +4247,8 @@ export { ExplainConditionArgs };
  * bug as an author verdict. Parse/evaluation throws rethrow naming the
  * definition, like the filter's; a failed slice FETCH propagates as itself.
  */
-export declare function explainStartAllowed(args: {
-  allowed: string;
+export declare function explainStartRequirement(args: {
+  query: string;
   definition: Pick<ApplicabilitySource, "name" | "fields">;
   /** The caller's input entries as a `$fields` map — the engine verbs build
    *  it with `startFieldsParam` (field resolution's projection), so the
@@ -4713,6 +4775,11 @@ declare function grantsPermissionOn(args: {
   userId?: string;
 }): Promise<boolean>;
 
+export declare type GroqRequirement = RequirementBase & {
+  type: "groq";
+  query: string;
+};
+
 /** Type-mirror of {@link GroupSchema} — one declared group. */
 export declare type Group = {
   name: string;
@@ -4826,7 +4893,7 @@ export declare type GuardAction = v.InferOutput<typeof GuardActionSchema>;
 
 declare const GuardActionSchema: v.PicklistSchema<
   readonly ["create", "update", "delete", "publish", "unpublish"],
-  `Invalid option: expected one of ${string}`
+  string
 >;
 
 export declare type GuardMatch = Guard["match"];
@@ -4991,7 +5058,7 @@ declare const GuardSchema: v.StrictObjectSchema<
             v.ArraySchema<
               v.PicklistSchema<
                 readonly ["create", "update", "delete", "publish", "unpublish"],
-                `Invalid option: expected one of ${string}`
+                string
               >,
               undefined
             >,
@@ -5098,6 +5165,11 @@ export { guillemets };
  */
 export declare function hashDefinitionContent(def: WorkflowDefinition): string;
 
+/** Whether the definition declares a `singleSubject` start requirement. */
+export declare function hasSingleSubjectRequirement(
+  definition: Pick<ApplicabilitySource, "start">,
+): boolean;
+
 /**
  * History-entry `_type` discriminators. Order roughly matches the
  * order a typical run produces them in a single fire-action commit.
@@ -5527,13 +5599,14 @@ export declare type InsightSite =
 export declare function instanceDocId(tag: string): string;
 
 /**
- * The per-instance guard filter — the single definition of "this instance's
- * guards in one datasource". The engine's verdict load
- * ({@link verdictGuardsForInstance}) fetches it once against the engine
- * datasource; the reactive adapters feed the same query/params to their
- * stores as a live subscription; {@link guardsForInstance} unions it across
- * datasources for housekeeping. Ordinary stage retraction deletes guards, so
- * results represent active persisted guard documents.
+ * The per-instance guard filter — "this instance's guards in one datasource".
+ * The engine's verdict load ({@link verdictGuardsForInstance}) fetches it once
+ * against the engine datasource, and {@link guardsForInstance} unions it
+ * across datasources for housekeeping; the reactive adapters subscribe the
+ * set-shaped {@link instancesGuardQuery} this delegates to (one shared
+ * live query per resource, sliced per `sourceInstanceId`), so every path
+ * reads through one filter definition. Ordinary stage retraction deletes
+ * guards, so results represent active persisted guard documents.
  */
 export declare function instanceGuardQuery(instanceId: string): CompiledQuery;
 
@@ -5586,6 +5659,12 @@ export declare interface InstanceSession {
    *  docs are processed), never from the commit itself — the commit's
    *  outcome is never masked by a store echo's failure. */
   update(docs: LoadedDoc[]): void;
+  /** Replace one held document without rebuilding the rest of the overlay.
+   *  Consumers with per-document streams use this after the initial
+   *  {@link InstanceSession.update} snapshot. Self-doc recency, commit-time
+   *  buffering, and deferred buffered-validation errors follow the same
+   *  contract as {@link InstanceSession.update}. */
+  updateDocument(doc: LoadedDoc): void;
   /** Replace the held live guards (the consumer's guard stream,
    *  last-write-wins). Guards are a separate stream from the watch-set:
    *  {@link InstanceSession.evaluate} pre-flights the instance write against
@@ -5647,6 +5726,18 @@ export declare interface InstancesForDocumentArgs {
   document: GdrUri;
 }
 
+/**
+ * The guard filter for a SET of instances in one datasource — the single
+ * definition every per-instance read delegates to ({@link instanceGuardQuery}).
+ * Reactive adapters subscribe it as ONE shared live query per resource for
+ * every co-mounted session, fanning results back out per `sourceInstanceId`,
+ * so a document's guard subscription count doesn't grow with its instance
+ * count. Deterministically ordered, matching {@link guardsForResource}.
+ */
+export declare function instancesGuardQuery(
+  instanceIds: readonly string[],
+): CompiledQuery;
+
 /**
  * The instance-list GROQ for a {@link InstancesQueryFilter}, ordered by
  * `startedAt` ascending (descending + sliced under
@@ -5666,17 +5757,16 @@ export declare function instancesQuery(args: {
 export declare interface InstancesQueryFilter {
   /**
    * Only instances that may reference this document (resource-qualified GDR
-   * URI). This is a lake-side PREFILTER — a deliberate superset that also
-   * matches exited-stage refs; narrow the fetched rows to the exact reactive
-   * watch-set with {@link instanceWatchesDocument}.
+   * URI). The lake-side predicate matches the reactive watch-set's
+   * workflow, open-stage, activity, ancestor, live-child, and own-id references.
    */
   document?: GdrUri;
   /**
    * The multi-document form of {@link InstancesQueryFilter.document}: one
-   * prefilter matching instances that may reference ANY of the given docs,
+   * predicate matching instances that reference ANY of the given docs,
    * for consumers discovering instances across many open documents at once.
-   * Merged with `document` when both are set; per-document narrowing is the
-   * caller's ({@link instanceWatchesDocument} again). A DEFINED-but-EMPTY
+   * Merged with `document` when both are set. Callers may defensively recheck
+   * with {@link instanceWatchesDocument}. A DEFINED-but-EMPTY
    * array matches nothing (the GROQ-natural reading of membership in an
    * empty set) — omit the field for the unconstrained every-in-flight read.
    */
@@ -5740,6 +5830,10 @@ export declare function isClaimExpired(
   now: string,
 ): boolean;
 
+export declare function isClientProjectUser(
+  value: unknown,
+): value is ClientProjectUser;
+
 export { isComparisonOp };
 
 /**
@@ -5931,12 +6025,35 @@ export declare function lakeGuardId(args: {
 }): string;
 
 /**
- * The latest deployed version of each definition name — the reduction every
- * "what would a start load?" consumer applies over a
- * {@link definitionsListGroq} read (GROQ has no group-by, so it happens
- * client-side). Order-independent: the highest version per name wins under
- * either `versionOrder`; names keep first-appearance order, so a
- * name-ascending read stays name-ascending.
+ * The id a lake-facing check binds for an actor: the resource-local
+ * principal id when the namespaces diverge, otherwise the actor's own
+ * (account-global) id. Every advisory that must agree with the lake's
+ * `identity()` — guard previews and pre-flights, the anchor ACL's `$can`
+ * grant filters — resolves through this one rule; binding `actor.id`
+ * directly at a lake edge reintroduces the divergent-identity mismatch.
+ */
+export declare function lakePrincipalId(args: {
+  actor: {
+    id: string;
+  };
+  localPrincipalId?: string | undefined;
+}): string;
+
+/**
+ * GROQ listing only the latest deployed version of each definition name.
+ * The correlated inner query keeps the reduction in the lake, so discovery
+ * reads do not transfer every historical definition body.
+ *
+ * Params: `$tag`.
+ */
+export declare function latestDefinitionsGroq(): string;
+
+/**
+ * The latest deployed version of each definition name from any supplied row
+ * set. Useful at boundaries that may already hold multiple versions; callers
+ * starting from the lake can use {@link latestDefinitionsGroq}. The highest
+ * version wins regardless of input order, while names keep first-appearance
+ * order.
  */
 export declare function latestDeployedDefinitions<
   T extends {
@@ -6134,9 +6251,10 @@ export declare interface MutationContext {
     | null;
   action: MutationGuardAction;
   /**
-   * Caller-asserted actor id, resolved as `identity()` in the predicate.
-   * Advisory — the engine takes the caller's word for who is acting; only
-   * the lake's own token identity is authenticated.
+   * The caller's principal id in the guarded resource's own namespace
+   * (what that lake's `identity()` returns), resolved as `identity()` in
+   * the predicate. Advisory — the engine takes the caller's word for who
+   * is acting; only the lake's own token identity is authenticated.
    */
   identity?: string;
 }
@@ -6534,6 +6652,24 @@ export declare type PersonActor = Omit<Actor, "kind"> & {
   readonly kind: "person";
 };
 
+/**
+ * The namespace a bare principal-id string belongs to.
+ *
+ * - `global` — account-global (comparable across every org-level context)
+ * - `project` — scoped to ONE project; which project is not in the string,
+ *   it comes from context (for stored engine values: the anchor resource
+ *   the document lives in)
+ * - `robot` — a token principal with one universal id (never needs mapping)
+ * - `sentinel` — `<anonymous>` / `<system>`, never a person
+ * - `unknown` — unclassifiable; treat as unresolvable and surface it
+ */
+export declare type PrincipalNamespace =
+  | "global"
+  | "project"
+  | "robot"
+  | "sentinel"
+  | "unknown";
+
 /**
  * One row of the instance's idempotency ledger — a caller-supplied
  * `idempotencyKey` a state-changing verb already committed under. Recorded in
@@ -6582,14 +6718,19 @@ export declare type ProgressTarget =
       field: string;
     };
 
+/** Project a readable instance into the only row shape start predicates may scan. */
+export declare function projectStartSliceRow(
+  instance: WorkflowInstance,
+): StartSliceRow;
+
 /**
  * Project a store-resolved doc onto its watch ref's identity, the way the
  * lake's perspective reads do: the published-form id becomes `_id` (the form
  * the session keys its overlay and snapshot by), and a draft/version
  * representation's stored id rides along as `_originalId` — session-side
  * conditions (including the `_originalId in path("versions.**")` shape) then
- * read exactly what the engine's own hydration ({@link contentDocQuery})
- * returns. Strict by construction: only the ids in
+ * read the same projected identity as the engine's perspective-aware hydration.
+ * Strict by construction: only the ids in
  * {@link watchRefRepresentations} are accepted — an id that merely *ends* in
  * the watched id (another doc's dotted id under a version prefix), a release
  * the perspective doesn't read, or a draft the perspective makes invisible is
@@ -6638,8 +6779,8 @@ export declare const READER_MODEL_ROLLOUT_URL =
 export declare class ReaderModelAcknowledgementError extends WorkflowError<"reader-model-acknowledgement"> {
   readonly code = "WORKFLOW_READER_MODEL_ACKNOWLEDGEMENT_MISMATCH";
   readonly expectedMinReaderModel: unknown;
-  readonly engineMinReaderModel = 2;
-  readonly engineModelVersion = 3;
+  readonly engineMinReaderModel = 4;
+  readonly engineModelVersion = 4;
   readonly documentationUrl =
     "https://github.com/sanity-io/workflows/blob/main/docs/reader-model-rollout.md";
   constructor(expectedMinReaderModel: unknown, context?: string);
@@ -6805,8 +6946,8 @@ export declare function remediationsFor(
 /**
  * A verb that would unstick a {@link StuckCause} — the *what to do about it*
  * half of a diagnosis. Surface-neutral identifiers; a consumer maps each to
- * its own command or button. `retry-effect` and `reset-activity` are not yet
- * callable engine operations — see {@link SuggestedRemediation.available}.
+ * its own command or button. `retry-effect` is not yet a callable engine
+ * operation — see {@link SuggestedRemediation.available}.
  */
 export declare type RemediationVerb =
   | "retry-effect"
@@ -6849,8 +6990,65 @@ export declare function requiredReaderModel(
   document: unknown,
 ): number;
 
+declare type RequirementBase = {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+};
+
+/** Authored identity and display copy for one readiness requirement. */
+export declare interface RequirementDescriptor {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+}
+
+/**
+ * Names an author's predicate may not use — engine-owned and author names
+ * share one namespace, so a predicate redefining a binding would silently
+ * shadow engine behaviour. Rejected at deploy; derived from the condition
+ * inventory.
+ */
 export declare const RESERVED_CONDITION_VARS: readonly string[];
 
+/**
+ * What to reset a stuck activity INTO — the two non-`failed` outcomes that
+ * unstick a stage gated on it. `active` re-runs it (back in progress, so a
+ * caller drives it to completion again); `skipped` bypasses it (terminal but
+ * resolved, so `$allActivitiesDone` can satisfy and a gated exit transition
+ * fire). `done` is deliberately absent: a reset is recovery, not a silent
+ * declaration that the work succeeded.
+ */
+declare const RESET_ACTIVITY_TARGETS: readonly ["active", "skipped"];
+
+export declare interface ResetActivityArgs extends DedupableOperationArgs {
+  /** Name of the activity to reset, within the instance's current stage. */
+  activity: string;
+  /**
+   * What to reset it into. `active` (the default) re-runs the activity — back
+   * in progress, for a caller to drive to completion again; `skipped` bypasses
+   * it — terminal but resolved, so a `$allActivitiesDone`-gated exit transition
+   * can fire. `done` is intentionally not offered: a reset is recovery, not a
+   * silent success.
+   */
+  to?: ResetActivityTarget;
+}
+
+export declare type ResetActivityResult =
+  | {
+      fired: false;
+    }
+  | {
+      fired: true;
+      stage: StageName;
+      activity: ActivityName;
+      from: ActivityStatus;
+      to: ResetActivityTarget;
+    };
+
+export declare type ResetActivityTarget =
+  (typeof RESET_ACTIVITY_TARGETS)[number];
+
 /**
  * Resolve the engine's `WorkflowAccess` for a client — both halves
  * fetched from its token in parallel and cached. Throws if the client
@@ -6977,8 +7175,8 @@ export declare function resourceAliasesToMap(
  * refs to the resources it stops serving.
  *
  * Engine-owned verb scopes rebind resolved clients onto
- * `ENGINE_API_VERSION`. Effect handlers receive resolver clients unchanged
- * because handler traffic belongs to the host.
+ * `ENGINE_API_VERSION`. Effect handlers derive request-tagged siblings from
+ * resolver clients so their concrete APIs remain available and attributed.
  */
 export declare type ResourceClientResolver = (
   parsed: ParsedGdr,
@@ -7160,6 +7358,34 @@ export declare interface SetStageArgs extends DedupableOperationArgs {
  */
 export declare const silentLogger: EngineLogger;
 
+export declare type SingleSubjectRequirement = RequirementBase & {
+  type: "singleSubject";
+};
+
+/**
+ * Evaluate a declared `singleSubject` requirement — resolves `true` when it
+ * REFUSES the start: an in-flight instance (no `completedAt`) of THIS
+ * definition already holds the prospective subject. The subject resolves from
+ * the `$fields` map's subject entry (a GDR envelope, `.id` the identity),
+ * falling back to `scope.subject`. No subject in hand means nothing to compare — the requirement
+ * passes; a pre-flight surface reports the unbound subject entry as
+ * provisional through {@link unboundRequirementReads}. The rule is
+ * count-shaped, so an absent `scope.fetchDataset` THROWS like a
+ * dataset-reading GROQ requirement — an empty `*` would pass vacuously. One
+ * evaluator serves every moment: the `startInstance` gate enforces it
+ * (`StartNotAllowedError`), the `evaluateStart` verb pre-flights it, and start
+ * surfaces evaluate it directly for their controls — every site gated by
+ * {@link hasSingleSubjectRequirement}, so only a rule this engine knows arrives
+ * here (an absent or unsupported rule is the caller's contract violation).
+ * Advisory under races like every engine-side check.
+ */
+export declare function singleSubjectRequirementRefused(args: {
+  definition: Pick<ApplicabilitySource, "name" | "fields" | "start">;
+  /** A produced `$fields` map (`startFieldsParam`, or a surface's seed map). */
+  fields?: Record<string, unknown> | undefined;
+  scope?: StartScope | undefined;
+}): Promise<boolean>;
+
 /** One site whose verdict a proposed assignment flips. */
 export declare interface SiteConsequence {
   site: InsightSite;
@@ -7287,21 +7513,6 @@ export declare class StaleEffectClaimError extends WorkflowError<"stale-effect-c
   });
 }
 
-/**
- * The vars a definition's `start.allowed` reads — the start-time permission
- * dialect: everything the filter context binds ({@link START_FILTER_VARS})
- * plus `$fields`, which start time always has. No candidate root ever binds
- * here (the subject rides `$fields.<entry>.id`; a root read is
- * deploy-rejected). Pre-flights can omit not-yet-collected input bindings and
- * report those reads as provisional. Bound in one place: `startContextParams`
- * in the applicability evaluator.
- */
-export declare const START_ALLOWED_VARS: readonly {
-  name: string;
-  label: string;
-  description: string;
-}[];
-
 /**
  * The vars a definition's `start.filter` reads — the start-filter dialect,
  * not the rendered condition scope (no {@link ConditionVarBinding}: these
@@ -7309,8 +7520,7 @@ export declare const START_ALLOWED_VARS: readonly {
  * `definitionsForDocument` derivation and the Studio start control).
  * `startInstance` never evaluates the filter. BROWSE-TIME-PURE: `$fields` is
  * deliberately absent — a `$fields` read is deploy-rejected with a pointer
- * to `start.allowed`. The synthetic subject variable requires a prospective
- * subject; evaluation throws when the caller omits that required scope.
+ * to start GROQ requirements.
  * Bound in one place: `startContextParams` in the applicability evaluator.
  */
 export declare const START_FILTER_VARS: readonly {
@@ -7321,6 +7531,21 @@ export declare const START_FILTER_VARS: readonly {
 
 declare const START_KINDS: readonly ["interactive", "autonomous"];
 
+/**
+ * The vars a definition's start GROQ requirements read — the start-time readiness
+ * dialect: everything the filter context binds ({@link START_FILTER_VARS})
+ * plus `$fields`, which start time always has. No candidate root ever binds
+ * here (the subject rides `$fields.<entry>.id`; a root read is
+ * deploy-rejected). Pre-flights can omit not-yet-collected input bindings and
+ * report those reads as provisional. Bound in one place: `startContextParams`
+ * in the applicability evaluator.
+ */
+export declare const START_REQUIREMENT_VARS: readonly {
+  name: string;
+  label: string;
+  description: string;
+}[];
+
 export declare type StartBlock = StartFields & {
   kind: StartKind;
 };
@@ -7341,34 +7566,34 @@ export declare type StartContext = Record<string, unknown>;
  * What `evaluateStart` projects — the same gates `startInstance` enforces,
  * as renderable state. `allowed` and `missingRequired` are deliberately
  * orthogonal: a missing required input is a caller mistake (the verb throws
- * `RequiredFieldNotProvidedError` for it), never a `start.allowed` verdict.
+ * `RequiredFieldNotProvidedError` for it), never a readiness verdict.
  */
 export declare interface StartEvaluation {
   /** Overall preflight startability: every supplied initial-field row is
-   *  valid and the `start.allowed` outcome is satisfied. `outcome` describes
-   *  only the condition; structurally invalid rows can therefore produce
+   *  valid and every declared start requirement is satisfied. `outcome` describes only the
+   *  predicates; structurally invalid rows can therefore produce
    *  `allowed: false` with `outcome: 'satisfied'`. */
   allowed: boolean;
   /**
-   * Three-valued, BINDABILITY-AWARE verdict: `'unsatisfied'` is a definitive
-   * no for these inputs (disable and explain), `'unevaluable'` means the
-   * predicate can't be decided yet — either a null operand reached an
-   * ordered comparison, or the predicate reads an entry `initialFields`
-   * doesn't supply ({@link StartEvaluation.unboundReads} non-empty). Keep
-   * the affordance enabled on `'unevaluable'`; `startInstance` still
-   * enforces the final verdict, where absence is final rather than
-   * provisional.
+   * Three-valued, BINDABILITY-AWARE verdict over the start predicates:
+   * `'unsatisfied'` is a definitive no for these inputs (disable and
+   * explain), `'unevaluable'` means the verdict can't be decided yet —
+   * either a null operand reached an ordered comparison, or a predicate
+   * reads an entry `initialFields` doesn't supply
+   * ({@link StartEvaluation.unboundReads} non-empty). One exception outranks
+   * the provisional rule: any definitive requirement refusal keeps the
+   * aggregate `'unsatisfied'` even while other reads are unbound. Keep the
+   * affordance enabled on `'unevaluable'`; `startInstance` still enforces
+   * the final verdict, where absence is final rather than provisional.
    */
   outcome: ConditionOutcome;
-  /** The `start.allowed` atom breakdown over the SUPPLIED inputs — what to
-   *  render next to a disabled start affordance. Present iff the definition
-   *  declares `allowed`. With `unboundReads` non-empty its own `outcome` may
-   *  be a collapsed provisional answer — the top-level `outcome` is the
-   *  trustworthy one. */
-  insight?: ConditionInsight;
-  /** The `$fields` entries the predicate reads that `initialFields` doesn't
-   *  supply — "fill these to decide". Non-empty forces `outcome:
-   *  'unevaluable'`. Empty when the definition declares no `allowed`. */
+  /** One result per declared readiness node, in author order. */
+  requirements: StartRequirementEvaluation[];
+  /** The `$fields` entries the predicates read that `initialFields` doesn't
+   *  supply — "fill these to decide", including a `singleSubject` node's
+   *  implicit subject read. Non-empty makes undecided requirements
+   *  `'unevaluable'`; a separate definitive refusal still keeps the aggregate
+   *  outcome `'unsatisfied'`. Empty when the definition declares no requirements. */
   unboundReads: string[];
   /** Required input entries `initialFields` doesn't fill yet — the rows a
    *  `startInstance` now would throw `RequiredFieldNotProvidedError` about. */
@@ -7387,12 +7612,12 @@ export declare interface StartEvaluation {
  *  authoring may omit it — so each variant declares it. */
 declare type StartFields = {
   filter?: string | undefined;
-  allowed?: string | undefined;
+  requirements?: StartRequirement[] | undefined;
 };
 
 /**
  * Project caller-supplied `initialFields` into the `$fields` map the
- * start-allowed context binds: one key per declared `input`-sourced entry,
+ * start-requirement context binds: one key per declared `input`-sourced entry,
  * resolved through {@link suppliedFieldFor} — the predicate can only ever see
  * a value the input resolution would persist, and an undeclared supplied name
  * never leaks in. Unsupplied (or null-supplied) entries stay unbound, so a
@@ -7500,19 +7725,21 @@ export declare function startKindOf(definition: {
 }): StartKind;
 
 /**
- * Thrown by `startInstance` when the definition's `start.allowed` predicate
- * is not satisfied for the supplied `initialFields` — evaluated false, or
- * GROQ null ("can't decide"; fail-closed, `insight.outcome` tells the two
- * apart). Carries the full {@link ConditionInsight} so a consumer renders
- * the same explanation the `evaluateStart` pre-flight would have shown.
+ * Thrown by `startInstance` when one or more declared start requirements are
+ * not satisfied for the supplied `initialFields`. Carries every unmet node's
+ * authored descriptor in declaration order; `evaluateStart` provides the
+ * corresponding per-node outcomes and GROQ insights.
  * There is no override arg — like `fireAction`, you don't bypass a verdict,
  * you change what produces it. Advisory under races like every engine-side
  * check.
  */
 export declare class StartNotAllowedError extends WorkflowError<"start-not-allowed"> {
   readonly definition: string;
-  readonly insight: ConditionInsight;
-  constructor(args: { definition: string; insight: ConditionInsight });
+  readonly unmetRequirements: RequirementDescriptor[];
+  constructor(args: {
+    definition: string;
+    unmetRequirements: RequirementDescriptor[];
+  });
 }
 
 /**
@@ -7558,43 +7785,57 @@ export declare function startRefusal(definition: {
   lifecycle?: WorkflowLifecycle | undefined;
 }): string | undefined;
 
+export declare type StartRequirement =
+  | GroqRequirement
+  | SingleSubjectRequirement;
+
+export declare interface StartRequirementEvaluation extends RequirementDescriptor {
+  /** Whether this requirement is satisfied, unsatisfied, or not yet decidable. */
+  outcome: ConditionOutcome;
+  /** GROQ explanation; absent for non-GROQ requirement kinds. */
+  insight?: ConditionInsight | undefined;
+}
+
 /**
  * The caller-side half of the start contexts — everything the evaluating
  * surface knows that the definition doesn't. Every member is optional
  * because the surfaces genuinely differ (a pure consumer may hold no clock):
- * except for the subject identity required by `$subjectHasInFlightInstance`,
- * an absent binding evaluates each read of it to GROQ null, and where that
+ * An absent binding evaluates each read of it to GROQ null, and where that
  * null lands decides the verdict — a predicate that can't decide without
  * the binding fails closed, while a count-of-matches clause over values
  * every row stores passes vacuously (in GROQ null equals only null, so the
  * unbound read matches no stored value). The vars themselves are
- * inventoried in `START_FILTER_VARS` / `START_ALLOWED_VARS`; the caller's
+ * inventoried in `START_FILTER_VARS` / `START_REQUIREMENT_VARS`; the caller's
  * `$fields` map is NOT scope — `start.filter` never binds it, and
- * `explainStartAllowed` takes it as its own argument.
+ * `explainStartRequirement` takes it as its own argument.
  */
 export declare interface StartScope {
   /** The engine's tag partition — binds `$tag`. */
   tag?: string | undefined;
   /** ISO clock reading — binds `$now`. */
   now?: string | undefined;
-  /** Resource-qualified identity of the prospective subject. Required when
-   *  `start.filter` reads `$subjectHasInFlightInstance`; unlike a loaded
+  /** Resource-qualified identity of the prospective subject. Unlike a loaded
    *  document's bare `_id`, this stays collision-free across resources. */
   subject?: GdrUri | undefined;
   /**
-   * The WORKFLOW resource's dataset, for predicates that read it (`*[...]` or
-   * a deref) or `$subjectHasInFlightInstance` — invoked lazily only when the
-   * predicate needs it. A slice is fine as long as it covers what predicates
-   * scan; the engine verbs supply EVERY instance of the tag, completed
-   * included — `*` carries no hidden predicate, so authors qualify in-flight
+   * The engine-owned start slice, for predicates that read `*[...]` or for a
+   * `singleSubject` requirement — invoked lazily only when evaluation needs it.
+   * Each row exposes exactly `{definition, subject, completedAt}`; completed
+   * rows are included, so authors qualify in-flight
    * themselves (`!defined(completedAt)`). Absent ⇒ a dataset-reading filter
    * fails closed (this surface cannot see the dataset, so it cannot decide),
-   * while a dataset-reading `allowed` THROWS — see
-   * {@link explainStartAllowed}.
+   * while a dataset-reading requirement THROWS — see
+   * {@link explainStartRequirement}.
    */
   fetchDataset?: (() => Promise<unknown[]>) | undefined;
 }
 
+export declare interface StartSliceRow {
+  definition: string;
+  subject: GdrUri | null;
+  completedAt: string | null;
+}
+
 /**
  * Declared editability of a field — the generic edit seam's gate. Default
  * (absent) is NOT editable: a field is op-only engine working memory unless the
@@ -7636,7 +7877,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7658,7 +7899,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7679,7 +7920,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7701,7 +7942,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7729,7 +7970,7 @@ declare const StoredFieldOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7759,7 +8000,7 @@ declare const StoredFieldRefSchema: v.StrictObjectSchema<
   {
     readonly scope: v.PicklistSchema<
       readonly ["workflow", "stage", "activity"],
-      `Invalid option: expected one of ${string}`
+      string
     >;
     readonly field: v.SchemaWithPipe<
       readonly [
@@ -7794,7 +8035,7 @@ declare const StoredManualTargetSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7822,7 +8063,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7844,7 +8085,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7865,7 +8106,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7887,7 +8128,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7915,7 +8156,7 @@ declare const StoredOpSchema: v.VariantSchema<
           {
             readonly scope: v.PicklistSchema<
               readonly ["workflow", "stage", "activity"],
-              `Invalid option: expected one of ${string}`
+              string
             >;
             readonly field: v.SchemaWithPipe<
               readonly [
@@ -7946,7 +8187,7 @@ declare const StoredOpSchema: v.VariantSchema<
         >;
         readonly status: v.PicklistSchema<
           readonly ["active", "done", "skipped", "failed"],
-          `Invalid option: expected one of ${string}`
+          string
         >;
       },
       undefined
@@ -8019,6 +8260,17 @@ export declare interface SubjectPermissionDenial {
   permission: DocumentValuePermission;
 }
 
+/** One foreign resource's forecast inputs: the actor's grants there, and the
+ *  actor's principal id in THAT resource's own identity namespace. */
+declare interface SubjectResourceAccess {
+  grants: Grant[];
+  /** What that resource's lake `identity()` returns for the acting token —
+   *  resolved through the resource's own routed client, so a dataset
+   *  resource contributes the actor's per-project user id and an org-level
+   *  resource the account-global id. */
+  actorId: string;
+}
+
 /**
  * A document the reactive layer should subscribe to, with its GDR
  * exploded so consumers never re-parse: the resource-addressing parts
@@ -8220,10 +8472,7 @@ declare const SubworkflowsSchema: v.StrictObjectSchema<
      * `$subworkflows`) decide.
      */
     readonly onExit: v.OptionalSchema<
-      v.PicklistSchema<
-        readonly ["detach", "abort"],
-        `Invalid option: expected one of ${string}`
-      >,
+      v.PicklistSchema<readonly ["detach", "abort"], string>,
       undefined
     >;
   },
@@ -8268,6 +8517,9 @@ export declare interface SweepStaleClaimsResult {
   released: PendingEffect[];
 }
 
+/** Lake `identity()` sentinel for system-initiated actions. */
+export declare const SYSTEM_IDENTITY = "<system>";
+
 /**
  * The engine's read-partition invariant as a GROQ predicate: a document is
  * visible when its `tag` equals the caller's `$tag` param. The single
@@ -8438,7 +8690,7 @@ declare type TransitionFields = {
 export declare function tryParseGdr(uri: string): ParsedGdr | undefined;
 
 /**
- * The `$fields` entries a `start.allowed` predicate reads that `fields` does
+ * The `$fields` entries a start GROQ requirement reads that `fields` does
  * not bind — the BINDABILITY rule every pre-flight surface applies before
  * trusting a verdict over possibly-incomplete inputs. GROQ equality against
  * a missing operand collapses to a definitive-looking answer (`null == x` is
@@ -8455,8 +8707,8 @@ export declare function tryParseGdr(uri: string): ParsedGdr | undefined;
  * seed map) — producers bind only own keys with real values, so key presence
  * IS the supplied-ness rule.
  */
-export declare function unboundAllowedReads(
-  allowed: string,
+export declare function unboundRequirementReads(
+  query: string,
   fields: Record<string, unknown>,
 ): string[];
 
@@ -8541,9 +8793,10 @@ declare type ValueExprInternal =
  * physically scoped: a guard doc in a watched content dataset that
  * self-declares the engine's resource id must never reach a verdict. This
  * keeps the advisory layer consistent (verdicts are UX, not enforcement);
- * it is not itself a security boundary. Runs the same query the reactive
- * adapters subscribe with ({@link instanceGuardQuery}), so the stateless and
- * reactive paths agree.
+ * it is not itself a security boundary. Reads through the same filter
+ * definition the reactive adapters subscribe with
+ * ({@link instanceGuardQuery}, the one-id form of the set-shaped
+ * {@link instancesGuardQuery}), so the stateless and reactive paths agree.
  */
 export declare function verdictGuardsForInstance(
   client: WorkflowClient,
@@ -8651,12 +8904,12 @@ export declare const workflow: {
   /**
    * Spawn a new workflow instance from a deployed definition.
    *
-   * Two gates run before anything is written, in order: the required-input
-   * check — a missing `required` input is a CALLER mistake
-   * ({@link RequiredFieldNotProvidedError}) — then the definition's
-   * `start.allowed` permission predicate, whose false/GROQ-null VERDICT
-   * throws {@link StartNotAllowedError} (declaring the expression is the
-   * opt-in; there is no override arg — pre-flight with `evaluateStart`).
+   * The gates run before anything is written, in order: supplied rows must be
+   * structurally consumable, required inputs must be present
+   * ({@link RequiredFieldNotProvidedError}), then every declared start
+   * requirement is evaluated in author order. All unmet `groq` and
+   * `singleSubject` nodes are reported by one {@link StartNotAllowedError}
+   * (there is no override arg — pre-flight with `evaluateStart`).
    * Per-value SHAPE validation fires during field resolution, after the
    * verdict but still before any write. It does NOT evaluate `start.filter`:
    * that is a read-side visibility rule (see `definitionsForDocument`).
@@ -8788,6 +9041,18 @@ export declare const workflow: {
   abortInstance: (
     rawArgs: Clocked<Telemetered<AbortInstanceArgs & EngineScopeArgs>>,
   ) => Promise<OperationResult>;
+  /**
+   * Admin override — reset a failed (or otherwise terminal) activity in the
+   * instance's current stage: `to: 'active'` re-runs it, `to: 'skipped'`
+   * (the bypass) resolves it so a `$allActivitiesDone`-gated exit can fire.
+   * Defaults to `active`. Cascades after the reset, so an unblocked
+   * transition fires in the same call. ACL gating should be enforced
+   * upstream. `changed: false` means the reset was a no-op (instance
+   * terminal, or the activity already at the target status).
+   */
+  resetActivity: (
+    rawArgs: Clocked<Telemetered<ResetActivityArgs & EngineScopeArgs>>,
+  ) => Promise<OperationResult>;
   /**
    * Fetch a workflow instance by id, scoped to the engine's tag.
    * Throws when the instance doesn't exist or isn't visible to this
@@ -8902,17 +9167,16 @@ export declare const workflow: {
    * For a non-reactive, content-change-driven runtime (a Sanity Function, an
    * Inngest/durable worker, any server) that holds no instances in memory: a
    * document changed; which instances should it `tick`? The watch-set covers
-   * the instance itself, its ancestors, and the docs named by
+   * the instance itself, its ancestors, live spawned children, and the docs named by
    * `doc.ref` / `subject` / `doc.refs` / `release.ref` field entries on the
    * workflow scope
    * **and the current stage** — so a hand-rolled GROQ over `fields[]` gets it
-   * subtly wrong (misses stage-scope refs, `release.ref`, ancestors).
+   * subtly wrong (misses stage-scope refs, `release.ref`, ancestors, and children).
    *
-   * A coarse GROQ prefilter narrows candidates server-side (in-flight,
-   * tag-scoped, mentioning the doc anywhere in state); the authoritative match
-   * is {@link instanceWatchesDocument}, derived from `collectWatchRefs`, so the
-   * reverse stays in lockstep with the forward set and honours the
-   * open-stage-only rule the prefilter deliberately over-approximates.
+   * The GROQ filter narrows candidates server-side (in-flight, tag-scoped,
+   * matching workflow/open-stage refs); {@link instanceWatchesDocument},
+   * derived from `collectWatchRefs`, rechecks the result so the reverse stays
+   * in lockstep with the forward set.
    *
    * Single-resource: instances always live in the engine's own resource, so
    * this reads one client (unlike {@link guardsForInstance}, whose guard docs
@@ -8936,15 +9200,13 @@ export declare const workflow: {
    * ({@link applicableDefinitions}): startable ∧ the `subject`-kind entry
    * accepts the doc's `_type` ∧ `start.filter` passes — evaluated in the
    * browse-time-pure start-filter context with `$tag`/`$definition`/`$now`
-   * bound and the tag's instance slice (completed included) backing dataset
-   * reads. `start.allowed` never participates — permission is a start-time
+   * bound and the tag's projected start slice (completed included) backing dataset
+   * reads. Start requirements never participate — readiness is a start-time
    * question; pre-flight it with {@link workflow.evaluateStart}.
    *
    * Takes the LOADED candidate document, not a ref — applicability evaluates
-   * its content, under whatever perspective the caller read it with. A
-   * resource-qualified `subject` accompanies it when a filter reads
-   * `$subjectHasInFlightInstance`; a bare document id cannot identify a
-   * cross-resource subject. Surfaces ALL matches (name ascending), no engine
+   * its content under whatever perspective the caller read it with. Surfaces
+   * ALL matches (name ascending), no engine
    * ranking — presenting a picker or auto-picking is consumer policy.
    * Advisory like every engine-side check.
    */
@@ -8955,18 +9217,20 @@ export declare const workflow: {
    * Pre-flight the start gates for a definition + candidate `initialFields` —
    * the read `startInstance` enforces, as a {@link StartEvaluation} a surface
    * can render: `missingRequired` mirrors the input contract
-   * ({@link RequiredFieldNotProvidedError}'s rows), and `allowed` /
-   * `outcome` / `insight` carry the `start.allowed` verdict with its atom
-   * breakdown — disable the start affordance on a definitive `false` and say
-   * why. BINDABILITY-AWARE for partial mid-form inputs: when the predicate
-   * reads an entry `initialFields` doesn't supply, `outcome` is
+   * ({@link RequiredFieldNotProvidedError}'s rows), while `requirements`
+   * preserves every declared node's authored descriptor, outcome, and GROQ
+   * insight when applicable. `allowed` / `outcome` aggregate those ordered
+   * results. BINDABILITY-AWARE for partial mid-form inputs: when a predicate
+   * reads an entry `initialFields` doesn't supply — including a
+   * `singleSubject` node's implicit subject read — `outcome` is
    * `'unevaluable'` and `unboundReads` names the entries ("fill these to
    * decide") instead of the collapsed answer GROQ equality would give —
    * this is the ONE deliberate divergence from the gate, where absence is
    * final, not provisional (a rule like `!defined($fields.rush)` genuinely
-   * passes there when `rush` is absent). A definition with no
-   * `start.allowed` is vacuously allowed, exactly like the verb. Pure read;
-   * advisory under races — the enforcement moment is `startInstance` itself.
+   * passes there when `rush` is absent). A definition declaring no start
+   * requirements is vacuously allowed, exactly like
+   * the verb. Pure read; advisory under races — the enforcement moment is
+   * `startInstance` itself.
    */
   evaluateStart: (
     rawArgs: Clocked<EvaluateStartArgs & EngineScopeArgs>,
@@ -9013,6 +9277,16 @@ declare const WORKFLOW_LIFECYCLES: readonly ["standalone", "child"];
  */
 export declare interface WorkflowAccess {
   actor: Actor;
+  /**
+   * The actor's principal id in the workflow resource's OWN identity
+   * namespace — what that resource's lake `identity()` returns for the same
+   * token (the per-project user id for dataset resources; equal to
+   * {@link Actor.id} for org-level resources and robots). In-memory only,
+   * never persisted: it exists for the lake-facing edge — binding
+   * `identity()` in guard previews and grant-filter evaluation so the
+   * advisory verdicts agree with what the lake itself would decide.
+   */
+  localPrincipalId?: string;
   grants?: Grant[];
 }
 
@@ -9026,6 +9300,8 @@ export declare interface WorkflowActionFiredData extends InstanceScopedEventData
   cascaded: number;
 }
 
+export declare const WorkflowActivityReset: WorkflowTelemetryEvent<WorkflowAdminOverrideData>;
+
 /** Outcome flag for the admin-override events — the attempt emits either way. */
 export declare interface WorkflowAdminOverrideData extends InstanceScopedEventData {
   /** `false` = the override was a no-op (already at the target / already terminal). */
@@ -9107,7 +9383,7 @@ export declare interface WorkflowClient {
    * Optional — present on the real `@sanity/client` and the in-memory test
    * fake. Returns a sibling client with the given config overrides,
    * inheriting everything else from the source (token, apiHost). The engine
-   * derives two things from it:
+   * derives three things from it:
    *
    * - **Cross-resource routing** (`resource` + the dataset pair): a sibling
    *   for a foreign GDR when `resourceClients` doesn't map it. A client
@@ -9121,6 +9397,10 @@ export declare interface WorkflowClient {
    *   rebound and is used as-is — it must be built to serve
    *   {@link ENGINE_API_VERSION} already; older dated versions fail
    *   silently incomplete, not loud.
+   * - **Effect request attribution** (`requestTagPrefix`): handlers receive a
+   *   derived client whose untagged traffic carries the effect tag while the
+   *   caller's own client remains untouched. A client without `withConfig`
+   *   uses the structural request wrapper instead.
    *
    * Dataset resources carry the `{projectId, dataset}` pair alongside
    * `resource`: the real client routes by `resource` (it takes precedence in
@@ -9129,7 +9409,7 @@ export declare interface WorkflowClient {
    * only — a canvas/media-library derivation on the fake aliases the current
    * store until the fake learns `resource` upstream.
    */
-  withConfig?: (config: WorkflowClientConfig) => WorkflowClient;
+  withConfig?: (config: WorkflowClientConfig) => this;
   /**
    * Optional — present on the real `@sanity/client`, absent on the
    * in-memory test client. The engine probes for it when auto-resolving
@@ -9155,14 +9435,22 @@ export declare interface WorkflowClient {
 /**
  * The config bag {@link WorkflowClient.withConfig} accepts — all optional: a
  * resource rebind (`resource`, plus the dataset pair for dataset targets), an
- * `apiVersion` rebind, or both. Everything omitted is inherited from the
- * source client.
+ * `apiVersion` rebind, a request-tag prefix, or any combination. Everything
+ * omitted is inherited from the source client.
  */
 export declare interface WorkflowClientConfig {
   resource?: WorkflowResource;
   projectId?: string;
   dataset?: string;
   apiVersion?: string;
+  requestTagPrefix?: string;
+  /**
+   * Host selection, mirroring `@sanity/client`: `false` derives a sibling
+   * addressing the global API host instead of the project host. The engine
+   * uses this for exactly one read — resolving the acting token's
+   * account-global identity from the global `/users/me`.
+   */
+  useProjectHostname?: boolean;
 }
 
 export declare interface WorkflowCommitOptions {
@@ -9212,7 +9500,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
                 ]
               >;
               readonly expectedMinReaderModel: v.OptionalSchema<
-                v.CustomSchema<2, undefined>,
+                v.CustomSchema<4, undefined>,
                 undefined
               >;
               readonly tag: v.SchemaWithPipe<
@@ -9499,7 +9787,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
         v.MinLengthAction<
           {
             name: string;
-            expectedMinReaderModel?: 2 | undefined;
+            expectedMinReaderModel?: 4 | undefined;
             tag: string;
             workflowResource:
               | {
@@ -9560,7 +9848,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
         v.CheckAction<
           {
             name: string;
-            expectedMinReaderModel?: 2 | undefined;
+            expectedMinReaderModel?: 4 | undefined;
             tag: string;
             workflowResource:
               | {
@@ -9619,7 +9907,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
             issue: v.CheckIssue<
               {
                 name: string;
-                expectedMinReaderModel?: 2 | undefined;
+                expectedMinReaderModel?: 4 | undefined;
                 tag: string;
                 workflowResource:
                   | {
@@ -9680,7 +9968,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
         v.CheckAction<
           {
             name: string;
-            expectedMinReaderModel?: 2 | undefined;
+            expectedMinReaderModel?: 4 | undefined;
             tag: string;
             workflowResource:
               | {
@@ -9739,7 +10027,7 @@ declare const WorkflowConfigSchema: v.ObjectSchema<
             issue: v.CheckIssue<
               {
                 name: string;
-                expectedMinReaderModel?: 2 | undefined;
+                expectedMinReaderModel?: 4 | undefined;
                 tag: string;
                 workflowResource:
                   | {
@@ -10089,7 +10377,7 @@ export declare interface WorkflowInstance extends SanityDocument {
   modelVersion?: number;
   /**
    * Reader floor — the oldest engine data model that can safely interpret
-   * this document. Derived from features actually present, bounded by
+   * this document. No lower than the writer's unconditional
    * {@link DATA_MODEL_MIN_READER}, and written alongside
    * {@link WorkflowInstance.modelVersion}. Full persists never lower it.
    */