@sanity/workflow-engine 0.34.0 → 0.35.0

package/dist/index.d.cts

@@ -2271,7 +2271,7 @@ export declare function definitionDeployedData(
     status: WorkflowDefinitionDeployedData["status"];
     deployId: string;
   },
-): WorkflowDefinitionDeployedData;
+): DerivedEventData<WorkflowDefinitionDeployedData>;
 
 /** One declared group at one level, with the members lexically attributed to it. */
 export declare interface DefinitionGroupSite {
@@ -2593,6 +2593,14 @@ export declare interface DeriveAutonomyOptions {
   children?: ReadonlyMap<string, WorkflowDefinition>;
 }
 
+/**
+ * A payload builder's half: everything the event carries except the
+ * {@link ExecutionScopedEventData} stamp, which the emit site supplies. A
+ * caller assembling an event payload itself has to add those fields.
+ */
+export declare type DerivedEventData<Data extends ExecutionScopedEventData> =
+  Omit<Data, keyof ExecutionScopedEventData>;
+
 /** Who fires the activity's actions, from shape alone — a separate causal
  *  check decides whether it actually resolves without a caller. A `target`
  *  is `off-system`; all-cascade actions are `autonomous`, none are
@@ -4080,7 +4088,7 @@ export declare const EXECUTION_KINDS: {
   readonly script: "script";
   readonly test: "test";
   readonly studio: "studio";
-  readonly sdkApp: "sdk-app";
+  readonly sdkApp: "sdk";
 };
 
 /**
@@ -4098,6 +4106,22 @@ export declare interface ExecutionContext {
   id?: string;
 }
 
+/**
+ * The caller-provenance fields every engine event payload carries: the
+ * engine's own view of the host that invoked it. `ExecutionContext.id` is
+ * never reported.
+ */
+export declare interface ExecutionScopedEventData {
+  /** The JavaScript runtime the engine inferred for itself, matching the
+   *  `executionContext.runtime` the same operation stamps on its history
+   *  entries. */
+  executionRuntime: string;
+  /** Where the operation came from: the host's declared
+   *  {@link EXECUTION_KINDS} value projected onto the reported vocabulary,
+   *  or `other` for a kind outside it. Absent when the host declared none. */
+  executionKind?: ReportedExecutionKind;
+}
+
 /**
  * Executor classifications — who, if anyone, fires an activity's actions
  * (shape-derived; see `./activity-kind.ts`).
@@ -6635,6 +6659,24 @@ export declare function parseDefinitionSnapshotValue(
   instance: Pick<WorkflowInstance, "_id" | "definitionSnapshot">,
 ): WorkflowDefinition;
 
+/**
+ * Parse definitions at the deploy boundary and derive the reader model their
+ * parsed shape requires, the one sequence `workflow.deployDefinitions` applies
+ * before it checks an acknowledgement. `caller` prefixes any parse error, and a
+ * definition the parser rejects throws instead of yielding a floor.
+ *
+ * Anything that checks an acknowledgement against definitions must derive the
+ * floor through this. Unsupported outside the Workflows packages.
+ * @internal
+ */
+export declare function _parseDefinitionsWithReaderModel(
+  definitions: readonly Record<string, unknown>[],
+  caller: string,
+): {
+  definitions: WorkflowDefinition[];
+  requiredMinReaderModel: number;
+};
+
 export declare interface ParsedGdr {
   scheme: GdrScheme;
   /** For `dataset`: `<projectId>` */
@@ -7115,6 +7157,21 @@ export declare type RemediationVerb =
   | "set-stage"
   | "abort";
 
+/**
+ * Where an engine event came from. Narrower than the vocabulary a host can
+ * declare, because {@link EXECUTION_KINDS} values naming a role rather than
+ * a host are projected onto one: `drainer` reports `server`, and
+ * `interactive`, `script`, and `test` report `other`, as does any value
+ * outside the vocabulary. Every other shipped value reports itself.
+ */
+export declare type ReportedExecutionKind =
+  | "cli"
+  | "mcp"
+  | "other"
+  | "sdk"
+  | "server"
+  | "studio";
+
 /** @internal Validated project-member reads shared by workspace adapters; not a supported consumer API. */
 export declare function _requestProjectMembers(
   request: (options: { url: string }) => Promise<unknown>,
@@ -9160,7 +9217,8 @@ export declare interface WorkflowAccess {
 
 export declare const WorkflowActionFired: WorkflowTelemetryEvent<WorkflowActionFiredData>;
 
-export declare interface WorkflowActionFiredData extends InstanceScopedEventData {
+export declare interface WorkflowActionFiredData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Effective kind of the activity the action fired on. */
   activityKind?: ActivityKind;
   hasParams: boolean;
@@ -9171,7 +9229,8 @@ export declare interface WorkflowActionFiredData extends InstanceScopedEventData
 export declare const WorkflowActivityReset: WorkflowTelemetryEvent<WorkflowAdminOverrideData>;
 
 /** Outcome flag for the admin-override events — the attempt emits either way. */
-export declare interface WorkflowAdminOverrideData extends InstanceScopedEventData {
+export declare interface WorkflowAdminOverrideData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** `false` = the override was a no-op (already at the target / already terminal). */
   changed: boolean;
 }
@@ -9951,7 +10010,7 @@ export declare type WorkflowDefinition = v.InferOutput<
 
 export declare const WorkflowDefinitionDeleted: WorkflowTelemetryEvent<WorkflowDefinitionDeletedData>;
 
-export declare interface WorkflowDefinitionDeletedData {
+export declare interface WorkflowDefinitionDeletedData extends ExecutionScopedEventData {
   /** Deployed versions removed by this delete. */
   deletedVersionCount: number;
   /** Non-terminal instances cascade-aborted before the delete. */
@@ -9962,7 +10021,7 @@ export declare interface WorkflowDefinitionDeletedData {
 
 export declare const WorkflowDefinitionDeployed: WorkflowTelemetryEvent<WorkflowDefinitionDeployedData>;
 
-export declare interface WorkflowDefinitionDeployedData {
+export declare interface WorkflowDefinitionDeployedData extends ExecutionScopedEventData {
   /** Content fingerprint of the deployed content. */
   contentHash: string;
   /** Whether this deploy minted a new version or matched the latest one.
@@ -10051,7 +10110,8 @@ export declare type WorkflowDeploymentInput = Omit<
 
 export declare const WorkflowEffectCompleted: WorkflowTelemetryEvent<WorkflowEffectCompletedData>;
 
-export declare interface WorkflowEffectCompletedData extends InstanceScopedEventData {
+export declare interface WorkflowEffectCompletedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** The effect's author-chosen name — one of the payload policy's two
    *  deliberate customer-string exceptions (module doc); unique per
    *  definition. */
@@ -10068,7 +10128,8 @@ export declare interface WorkflowEffectCompletedData extends InstanceScopedEvent
 
 export declare const WorkflowEffectsDrained: WorkflowTelemetryEvent<WorkflowEffectsDrainedData>;
 
-export declare interface WorkflowEffectsDrainedData extends InstanceScopedEventData {
+export declare interface WorkflowEffectsDrainedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Pending effects dispatched to a registered handler in this drain —
    *  0 for an empty poll (the pass itself is the signal). */
   drainedCount: number;
@@ -10080,7 +10141,8 @@ export declare interface WorkflowEffectsDrainedData extends InstanceScopedEventD
 
 export declare const WorkflowEffectStateReported: WorkflowTelemetryEvent<WorkflowEffectStateReportedData>;
 
-export declare interface WorkflowEffectStateReportedData extends InstanceScopedEventData {
+export declare interface WorkflowEffectStateReportedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** The reporting effect's author-chosen name — one of the payload policy's
    *  two deliberate customer-string exceptions (module doc). */
   effect: EffectName;
@@ -10214,7 +10276,8 @@ export declare interface WorkflowFetchOptions {
 
 export declare const WorkflowFieldEdited: WorkflowTelemetryEvent<WorkflowFieldEditedData>;
 
-export declare interface WorkflowFieldEditedData extends InstanceScopedEventData {
+export declare interface WorkflowFieldEditedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Declared kind of the edited field entry. */
   fieldKind?: FieldKind;
   mode: EditMode;
@@ -10421,7 +10484,8 @@ export declare const WorkflowInstanceSchema: v.GenericSchema<WorkflowInstance>;
 
 export declare const WorkflowInstanceStarted: WorkflowTelemetryEvent<WorkflowInstanceStartedData>;
 
-export declare interface WorkflowInstanceStartedData extends InstanceScopedEventData {
+export declare interface WorkflowInstanceStartedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Caller-supplied initial-field entries — `initialFields` for a direct
    *  start, the parent's projected `with` bindings for a spawned child. */
   initialFieldCount: number;
@@ -10433,7 +10497,8 @@ export declare interface WorkflowInstanceStartedData extends InstanceScopedEvent
 
 export declare const WorkflowInstanceTicked: WorkflowTelemetryEvent<WorkflowInstanceTickedData>;
 
-export declare interface WorkflowInstanceTickedData extends InstanceScopedEventData {
+export declare interface WorkflowInstanceTickedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Auto-transitions fired during the cascade. */
   cascaded: number;
 }
@@ -10520,7 +10585,8 @@ export declare const WorkflowStageSet: WorkflowTelemetryEvent<WorkflowAdminOverr
 
 export declare const WorkflowStageTransitioned: WorkflowTelemetryEvent<WorkflowStageTransitionedData>;
 
-export declare interface WorkflowStageTransitionedData extends InstanceScopedEventData {
+export declare interface WorkflowStageTransitionedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Positional index of the exited stage in the definition's `stages[]`
    *  order — indexes, never names, so the payload stays content-free. */
   fromStageIndex: number;

package/dist/index.d.ts

@@ -2271,7 +2271,7 @@ export declare function definitionDeployedData(
     status: WorkflowDefinitionDeployedData["status"];
     deployId: string;
   },
-): WorkflowDefinitionDeployedData;
+): DerivedEventData<WorkflowDefinitionDeployedData>;
 
 /** One declared group at one level, with the members lexically attributed to it. */
 export declare interface DefinitionGroupSite {
@@ -2593,6 +2593,14 @@ export declare interface DeriveAutonomyOptions {
   children?: ReadonlyMap<string, WorkflowDefinition>;
 }
 
+/**
+ * A payload builder's half: everything the event carries except the
+ * {@link ExecutionScopedEventData} stamp, which the emit site supplies. A
+ * caller assembling an event payload itself has to add those fields.
+ */
+export declare type DerivedEventData<Data extends ExecutionScopedEventData> =
+  Omit<Data, keyof ExecutionScopedEventData>;
+
 /** Who fires the activity's actions, from shape alone — a separate causal
  *  check decides whether it actually resolves without a caller. A `target`
  *  is `off-system`; all-cascade actions are `autonomous`, none are
@@ -4080,7 +4088,7 @@ export declare const EXECUTION_KINDS: {
   readonly script: "script";
   readonly test: "test";
   readonly studio: "studio";
-  readonly sdkApp: "sdk-app";
+  readonly sdkApp: "sdk";
 };
 
 /**
@@ -4098,6 +4106,22 @@ export declare interface ExecutionContext {
   id?: string;
 }
 
+/**
+ * The caller-provenance fields every engine event payload carries: the
+ * engine's own view of the host that invoked it. `ExecutionContext.id` is
+ * never reported.
+ */
+export declare interface ExecutionScopedEventData {
+  /** The JavaScript runtime the engine inferred for itself, matching the
+   *  `executionContext.runtime` the same operation stamps on its history
+   *  entries. */
+  executionRuntime: string;
+  /** Where the operation came from: the host's declared
+   *  {@link EXECUTION_KINDS} value projected onto the reported vocabulary,
+   *  or `other` for a kind outside it. Absent when the host declared none. */
+  executionKind?: ReportedExecutionKind;
+}
+
 /**
  * Executor classifications — who, if anyone, fires an activity's actions
  * (shape-derived; see `./activity-kind.ts`).
@@ -6635,6 +6659,24 @@ export declare function parseDefinitionSnapshotValue(
   instance: Pick<WorkflowInstance, "_id" | "definitionSnapshot">,
 ): WorkflowDefinition;
 
+/**
+ * Parse definitions at the deploy boundary and derive the reader model their
+ * parsed shape requires, the one sequence `workflow.deployDefinitions` applies
+ * before it checks an acknowledgement. `caller` prefixes any parse error, and a
+ * definition the parser rejects throws instead of yielding a floor.
+ *
+ * Anything that checks an acknowledgement against definitions must derive the
+ * floor through this. Unsupported outside the Workflows packages.
+ * @internal
+ */
+export declare function _parseDefinitionsWithReaderModel(
+  definitions: readonly Record<string, unknown>[],
+  caller: string,
+): {
+  definitions: WorkflowDefinition[];
+  requiredMinReaderModel: number;
+};
+
 export declare interface ParsedGdr {
   scheme: GdrScheme;
   /** For `dataset`: `<projectId>` */
@@ -7115,6 +7157,21 @@ export declare type RemediationVerb =
   | "set-stage"
   | "abort";
 
+/**
+ * Where an engine event came from. Narrower than the vocabulary a host can
+ * declare, because {@link EXECUTION_KINDS} values naming a role rather than
+ * a host are projected onto one: `drainer` reports `server`, and
+ * `interactive`, `script`, and `test` report `other`, as does any value
+ * outside the vocabulary. Every other shipped value reports itself.
+ */
+export declare type ReportedExecutionKind =
+  | "cli"
+  | "mcp"
+  | "other"
+  | "sdk"
+  | "server"
+  | "studio";
+
 /** @internal Validated project-member reads shared by workspace adapters; not a supported consumer API. */
 export declare function _requestProjectMembers(
   request: (options: { url: string }) => Promise<unknown>,
@@ -9160,7 +9217,8 @@ export declare interface WorkflowAccess {
 
 export declare const WorkflowActionFired: WorkflowTelemetryEvent<WorkflowActionFiredData>;
 
-export declare interface WorkflowActionFiredData extends InstanceScopedEventData {
+export declare interface WorkflowActionFiredData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Effective kind of the activity the action fired on. */
   activityKind?: ActivityKind;
   hasParams: boolean;
@@ -9171,7 +9229,8 @@ export declare interface WorkflowActionFiredData extends InstanceScopedEventData
 export declare const WorkflowActivityReset: WorkflowTelemetryEvent<WorkflowAdminOverrideData>;
 
 /** Outcome flag for the admin-override events — the attempt emits either way. */
-export declare interface WorkflowAdminOverrideData extends InstanceScopedEventData {
+export declare interface WorkflowAdminOverrideData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** `false` = the override was a no-op (already at the target / already terminal). */
   changed: boolean;
 }
@@ -9951,7 +10010,7 @@ export declare type WorkflowDefinition = v.InferOutput<
 
 export declare const WorkflowDefinitionDeleted: WorkflowTelemetryEvent<WorkflowDefinitionDeletedData>;
 
-export declare interface WorkflowDefinitionDeletedData {
+export declare interface WorkflowDefinitionDeletedData extends ExecutionScopedEventData {
   /** Deployed versions removed by this delete. */
   deletedVersionCount: number;
   /** Non-terminal instances cascade-aborted before the delete. */
@@ -9962,7 +10021,7 @@ export declare interface WorkflowDefinitionDeletedData {
 
 export declare const WorkflowDefinitionDeployed: WorkflowTelemetryEvent<WorkflowDefinitionDeployedData>;
 
-export declare interface WorkflowDefinitionDeployedData {
+export declare interface WorkflowDefinitionDeployedData extends ExecutionScopedEventData {
   /** Content fingerprint of the deployed content. */
   contentHash: string;
   /** Whether this deploy minted a new version or matched the latest one.
@@ -10051,7 +10110,8 @@ export declare type WorkflowDeploymentInput = Omit<
 
 export declare const WorkflowEffectCompleted: WorkflowTelemetryEvent<WorkflowEffectCompletedData>;
 
-export declare interface WorkflowEffectCompletedData extends InstanceScopedEventData {
+export declare interface WorkflowEffectCompletedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** The effect's author-chosen name — one of the payload policy's two
    *  deliberate customer-string exceptions (module doc); unique per
    *  definition. */
@@ -10068,7 +10128,8 @@ export declare interface WorkflowEffectCompletedData extends InstanceScopedEvent
 
 export declare const WorkflowEffectsDrained: WorkflowTelemetryEvent<WorkflowEffectsDrainedData>;
 
-export declare interface WorkflowEffectsDrainedData extends InstanceScopedEventData {
+export declare interface WorkflowEffectsDrainedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Pending effects dispatched to a registered handler in this drain —
    *  0 for an empty poll (the pass itself is the signal). */
   drainedCount: number;
@@ -10080,7 +10141,8 @@ export declare interface WorkflowEffectsDrainedData extends InstanceScopedEventD
 
 export declare const WorkflowEffectStateReported: WorkflowTelemetryEvent<WorkflowEffectStateReportedData>;
 
-export declare interface WorkflowEffectStateReportedData extends InstanceScopedEventData {
+export declare interface WorkflowEffectStateReportedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** The reporting effect's author-chosen name — one of the payload policy's
    *  two deliberate customer-string exceptions (module doc). */
   effect: EffectName;
@@ -10214,7 +10276,8 @@ export declare interface WorkflowFetchOptions {
 
 export declare const WorkflowFieldEdited: WorkflowTelemetryEvent<WorkflowFieldEditedData>;
 
-export declare interface WorkflowFieldEditedData extends InstanceScopedEventData {
+export declare interface WorkflowFieldEditedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Declared kind of the edited field entry. */
   fieldKind?: FieldKind;
   mode: EditMode;
@@ -10421,7 +10484,8 @@ export declare const WorkflowInstanceSchema: v.GenericSchema<WorkflowInstance>;
 
 export declare const WorkflowInstanceStarted: WorkflowTelemetryEvent<WorkflowInstanceStartedData>;
 
-export declare interface WorkflowInstanceStartedData extends InstanceScopedEventData {
+export declare interface WorkflowInstanceStartedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Caller-supplied initial-field entries — `initialFields` for a direct
    *  start, the parent's projected `with` bindings for a spawned child. */
   initialFieldCount: number;
@@ -10433,7 +10497,8 @@ export declare interface WorkflowInstanceStartedData extends InstanceScopedEvent
 
 export declare const WorkflowInstanceTicked: WorkflowTelemetryEvent<WorkflowInstanceTickedData>;
 
-export declare interface WorkflowInstanceTickedData extends InstanceScopedEventData {
+export declare interface WorkflowInstanceTickedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Auto-transitions fired during the cascade. */
   cascaded: number;
 }
@@ -10520,7 +10585,8 @@ export declare const WorkflowStageSet: WorkflowTelemetryEvent<WorkflowAdminOverr
 
 export declare const WorkflowStageTransitioned: WorkflowTelemetryEvent<WorkflowStageTransitionedData>;
 
-export declare interface WorkflowStageTransitionedData extends InstanceScopedEventData {
+export declare interface WorkflowStageTransitionedData
+  extends ExecutionScopedEventData, InstanceScopedEventData {
   /** Positional index of the exited stage in the definition's `stages[]`
    *  order — indexes, never names, so the payload stays content-free. */
   fromStageIndex: number;