@rigkit/engine 0.2.2 → 0.2.4

package/src/types.ts

@@ -52,18 +52,25 @@ export type CommandOptions = ExecOptions & {
   name?: string;
 };
 
-export type ProviderWorkspaceContext = object;
-
 export type LocalWorkspaceRuntime = {
   open(target: string): MaybePromise<void>;
   command?(input: LocalCommandRequest): MaybePromise<LocalCommandResult>;
-  requestCapability?<Result = unknown>(capability: string, params: unknown): MaybePromise<Result>;
+  requestCapability?<Result = unknown>(
+    capability: string,
+    params: unknown,
+    options?: LocalHostCapabilityRequestOptions,
+  ): MaybePromise<Result>;
   requestCapabilitySession?<Result = unknown>(
     capability: string,
     params: unknown,
+    options?: LocalHostCapabilityRequestOptions,
   ): MaybePromise<HostCapabilitySession<Result>>;
 };
 
+export type LocalHostCapabilityRequestOptions = {
+  nodePath?: string;
+};
+
 export type HostCapabilitySession<Result = unknown> = {
   result: Result;
   closed: Promise<void>;
@@ -94,22 +101,19 @@ export type WorkflowProviderDefinition<
   ProviderId extends string = string,
   Config extends object = Record<string, unknown>,
   Runtime = unknown,
-  WorkspaceContext extends ProviderWorkspaceContext = ProviderWorkspaceContext,
 > = {
   readonly kind: "rigkit.provider";
   readonly providerId: ProviderId;
   readonly config: ResolvableObject<Config>;
   readonly plugin?: unknown;
   readonly __runtime?: Runtime;
-  readonly __workspaceContext?: WorkspaceContext;
 };
 
 export type DevProviderDefinition<
   ProviderId extends string = string,
   Config extends object = Record<string, unknown>,
   Runtime = unknown,
-  WorkspaceContext extends ProviderWorkspaceContext = ProviderWorkspaceContext,
-> = WorkflowProviderDefinition<ProviderId, Config, Runtime, WorkspaceContext>;
+> = WorkflowProviderDefinition<ProviderId, Config, Runtime>;
 
 export type LoadedProviderDefinition<
   ProviderId extends string = string,
@@ -120,18 +124,13 @@ export type LoadedProviderDefinition<
   plugin?: unknown;
 };
 
-export type WorkflowProviderMap = Record<string, WorkflowProviderDefinition<string, any, any, any>>;
+export type WorkflowProviderMap = Record<string, WorkflowProviderDefinition<string, any, any>>;
 
 export type ProviderRuntimeOf<Provider> =
-  Provider extends WorkflowProviderDefinition<any, any, infer Runtime, any>
+  Provider extends WorkflowProviderDefinition<any, any, infer Runtime>
     ? Runtime
     : never;
 
-export type ProviderWorkspaceContextOf<Provider> =
-  Provider extends WorkflowProviderDefinition<any, any, any, infer WorkspaceContext extends ProviderWorkspaceContext>
-    ? WorkspaceContext
-    : ProviderWorkspaceContext;
-
 export type ProviderRuntimeMap<Providers extends WorkflowProviderMap> = {
   readonly [Key in keyof Providers]: ProviderRuntimeOf<Providers[Key]>;
 };
@@ -143,48 +142,47 @@ export type WorkflowRuntimeHelpers = {
   log(data: string, options?: { stream?: WorkflowLogStream; label?: string }): void;
 };
 
-export type WorkflowTaskRuntime<
-  Providers extends WorkflowProviderMap,
-  Context extends JsonObject,
-> = ProviderRuntimeMap<Providers> & {
-  readonly providers: ProviderRuntimeMap<Providers>;
-  readonly ctx: Readonly<Context>;
-  readonly runtime: WorkflowRuntimeHelpers;
+export const STEP_INVALIDATION_KIND = "rigkit.step.invalidate" as const;
+
+export type WorkflowStepInvalidation<Target extends string = string> = {
+  readonly kind: typeof STEP_INVALIDATION_KIND;
+  readonly target: Target;
+  readonly targetNodePath: string;
 };
 
-export type WorkflowTaskResult = void | undefined | JsonObject;
+export type WorkflowStepRuntime<
+  Context extends JsonObject = JsonObject,
+  PreviousTaskIds extends string = string,
+> = WorkflowRuntimeHelpers & {
+  readonly ctx: Readonly<Context>;
+  invalidate<const Target extends PreviousTaskIds>(target: Target): WorkflowStepInvalidation<Target>;
+};
 
-export type WorkflowTaskHandler<
-  Providers extends WorkflowProviderMap,
-  Context extends JsonObject,
-  Result extends WorkflowTaskResult = WorkflowTaskResult,
-> = (context: WorkflowTaskRuntime<Providers, Context>) => MaybePromise<Result>;
+export type WorkflowTaskContextResult<Context extends JsonObject = JsonObject> = {
+  readonly ctx: Context;
+};
 
-export type WorkflowCreateRuntime<
+export type WorkflowTaskRuntime<
   Providers extends WorkflowProviderMap,
   Context extends JsonObject,
+  PreviousTaskIds extends string = string,
 > = ProviderRuntimeMap<Providers> & {
-  readonly ctx: Readonly<Context>;
-  readonly name: string;
   readonly providers: ProviderRuntimeMap<Providers>;
-  readonly local: LocalWorkspaceRuntime;
-  readonly workflow: string;
+  readonly step: WorkflowStepRuntime<Context, PreviousTaskIds>;
 };
 
-export type WorkflowCreateResult = JsonObject;
+export type WorkflowTaskResult =
+  | void
+  | undefined
+  | WorkflowTaskContextResult<JsonObject>
+  | WorkflowStepInvalidation<string>;
 
-export type WorkflowCreateHandler<
+export type WorkflowTaskHandler<
   Providers extends WorkflowProviderMap,
   Context extends JsonObject,
-  Result extends WorkflowCreateResult = WorkflowCreateResult,
-> = (context: WorkflowCreateRuntime<Providers, Context>) => MaybePromise<Result>;
-
-export type WorkflowCreateDefinition<
-  Providers extends WorkflowProviderMap = WorkflowProviderMap,
-  Context extends JsonObject = JsonObject,
-> = {
-  readonly handler: WorkflowCreateHandler<Providers, Context, any>;
-};
+  PreviousTaskIds extends string = string,
+  Result extends WorkflowTaskResult = WorkflowTaskResult,
+> = (context: WorkflowTaskRuntime<Providers, Context, PreviousTaskIds>) => MaybePromise<Result>;
 
 export type WorkflowInputFieldKind = "workspace" | "string" | "boolean" | "number";
 
@@ -199,9 +197,7 @@ export type WorkflowInputFieldDefinition<Value = unknown> = {
 };
 
 export type WorkflowOperationWorkspaceInput<Name extends string> = {
-  [Key in Name]: WorkspaceRuntimeRecord & {
-    data: Record<string, JsonValue>;
-  };
+  [Key in Name]: WorkspaceRuntimeRecord;
 };
 
 export type WorkflowInputShape = Record<string, WorkflowInputFieldDefinition<any>>;
@@ -262,6 +258,7 @@ export type WorkflowOperationRuntime<
   readonly providers: ProviderRuntimeMap<Providers>;
   readonly local: LocalWorkspaceRuntime;
   readonly workflow: string;
+  readonly step: WorkflowStepRuntime;
 };
 
 export type WorkflowOperationResult = void | undefined | JsonValue;
@@ -272,25 +269,87 @@ export type WorkflowOperationHandler<
   Result extends WorkflowOperationResult = WorkflowOperationResult,
 > = (context: WorkflowOperationRuntime<Providers, Input>) => MaybePromise<Result>;
 
-export type WorkflowHostMethodRequirement = {
-  readonly id: string;
-  readonly modes?: readonly string[];
+export type WorkflowRuntimeContext<Context extends JsonObject> = {
+  readonly name: string;
+  readonly ctx: Readonly<Context>;
 };
 
-export type WorkflowHostCapabilityRequirement = {
-  readonly id: string;
-  readonly schemaHash?: string;
+export type ReadonlyWorkspaceContext<Context extends JsonObject> = {
+  readonly [Key in keyof Context]: Context[Key];
+};
+
+export type WorkspaceCreateRuntimeRecord = {
+  readonly name: string;
+};
+
+export type WorkspaceRuntimeRecord<Context extends object = JsonObject> = {
+  readonly name: string;
+  readonly ctx: Context;
+};
+
+export type WorkflowWorkspaceCreateRuntime<
+  Providers extends WorkflowProviderMap,
+  Context extends JsonObject,
+> = ProviderRuntimeMap<Providers> & {
+  readonly workflow: WorkflowRuntimeContext<Context>;
+  readonly workspace: WorkspaceCreateRuntimeRecord;
+  readonly providers: ProviderRuntimeMap<Providers>;
+  readonly local: LocalWorkspaceRuntime;
+  readonly step: WorkflowStepRuntime;
 };
 
+export type WorkflowWorkspaceCreateHandler<
+  Providers extends WorkflowProviderMap,
+  Context extends JsonObject,
+  Data extends JsonObject,
+> = (context: WorkflowWorkspaceCreateRuntime<Providers, Context>) => MaybePromise<Data>;
+
+export type WorkflowWorkspaceRemoveRuntime<
+  Providers extends WorkflowProviderMap,
+  Context extends JsonObject,
+  Data extends JsonObject,
+> = ProviderRuntimeMap<Providers> & {
+  readonly workflow: WorkflowRuntimeContext<Context>;
+  readonly workspace: WorkspaceRuntimeRecord<ReadonlyWorkspaceContext<Data>>;
+  readonly providers: ProviderRuntimeMap<Providers>;
+  readonly local: LocalWorkspaceRuntime;
+  readonly step: WorkflowStepRuntime;
+};
+
+export type WorkflowWorkspaceRemoveHandler<
+  Providers extends WorkflowProviderMap,
+  Context extends JsonObject,
+  Data extends JsonObject,
+> = (context: WorkflowWorkspaceRemoveRuntime<Providers, Context, Data>) => MaybePromise<void>;
+
+export type WorkflowWorkspaceOperationRuntime<
+  Providers extends WorkflowProviderMap,
+  Context extends JsonObject,
+  Data extends object,
+  Input extends object,
+> = ProviderRuntimeMap<Providers> & {
+  readonly workflow: WorkflowRuntimeContext<Context>;
+  readonly input: Readonly<Input>;
+  readonly workspace: WorkspaceRuntimeRecord<Data>;
+  readonly providers: ProviderRuntimeMap<Providers>;
+  readonly local: LocalWorkspaceRuntime;
+  readonly step: WorkflowStepRuntime;
+};
+
+export type WorkflowWorkspaceOperationHandler<
+  Providers extends WorkflowProviderMap,
+  Context extends JsonObject,
+  Data extends object,
+  Input extends object,
+  Result extends WorkflowOperationResult = WorkflowOperationResult,
+> = (context: WorkflowWorkspaceOperationRuntime<Providers, Context, Data, Input>) => MaybePromise<Result>;
+
 export type WorkflowOperationOptions<
   Providers extends WorkflowProviderMap,
   Input extends object = {},
 > = {
   title?: string;
   description?: string;
-  createsWorkspace?: boolean;
-  requiredHostMethods?: readonly WorkflowHostMethodRequirement[];
-  requiredHostCapabilities?: readonly WorkflowHostCapabilityRequirement[];
   input?: WorkflowOperationInputBuilder<Input> | ((workflow: WorkflowOperationInputHelpers) => WorkflowOperationInputBuilder<Input>);
   run: WorkflowOperationHandler<Providers, Input>;
 };
@@ -302,13 +361,35 @@ export type WorkflowOperationDefinition<
   readonly id: string;
   readonly title?: string;
   readonly description?: string;
-  readonly createsWorkspace?: boolean;
-  readonly requiredHostMethods?: readonly WorkflowHostMethodRequirement[];
-  readonly requiredHostCapabilities?: readonly WorkflowHostCapabilityRequirement[];
   readonly input?: WorkflowOperationInputBuilder<Input>;
   readonly run: WorkflowOperationHandler<Providers, Input>;
 };
 
+export type WorkflowWorkspaceOperationOptions<
+  Providers extends WorkflowProviderMap,
+  Context extends JsonObject,
+  Data extends object,
+  Input extends object = {},
+> = {
+  title?: string;
+  description?: string;
+  input?: WorkflowOperationInputBuilder<Input> | ((workflow: WorkflowOperationInputHelpers) => WorkflowOperationInputBuilder<Input>);
+  run: WorkflowWorkspaceOperationHandler<Providers, Context, Data, Input>;
+};
+
+export type WorkflowWorkspaceOperationDefinition<
+  Providers extends WorkflowProviderMap = WorkflowProviderMap,
+  Context extends JsonObject = JsonObject,
+  Data extends object = JsonObject,
+  Input extends object = object,
+> = {
+  readonly id: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly input?: WorkflowOperationInputBuilder<Input>;
+  readonly run: WorkflowWorkspaceOperationHandler<Providers, Context, Data, Input>;
+};
+
 export type OutputSchema<Output extends JsonObject = JsonObject> =
   | { parse(value: unknown): Output }
   | {
@@ -329,8 +410,19 @@ export type OutputSchemaValue<Schema> =
 export type WorkflowTaskOptions<Output extends JsonObject = JsonObject> = {
   output?: OutputSchema<Output>;
   version?: string;
+  cacheTTL?: WorkflowTaskCacheTTL;
 };
 
+export type WorkflowTaskCacheTTL =
+  | number
+  | string
+  | {
+      seconds?: number;
+      minutes?: number;
+      hours?: number;
+      days?: number;
+    };
+
 export type WorkflowNodeKind = "task" | "sequence" | "parallel";
 
 export type WorkflowDefinition<
@@ -344,29 +436,39 @@ export type WorkflowDefinition<
   sequence<InputContext extends JsonObject = {}>(name: string): WorkflowSequenceBuilder<
     Providers,
     InputContext,
-    InputContext
+    InputContext,
+    JsonObject,
+    never,
+    never,
+    never
   >;
 
   task<Result extends WorkflowTaskResult>(
     name: string,
-    handler: WorkflowTaskHandler<Providers, {}, Result>,
+    handler: WorkflowTaskHandler<Providers, {}, never, Result>,
   ): WorkflowTaskNode<Providers, {}, TaskReturnContext<Result>>;
 
-  task<Schema extends OutputSchema<JsonObject>, Result extends MaybePromise<OutputSchemaValue<Schema> | void>>(
+  task<
+    Schema extends OutputSchema<JsonObject>,
+    Result extends MaybePromise<WorkflowTaskContextResult<OutputSchemaValue<Schema>> | WorkflowStepInvalidation<string> | void>,
+  >(
     name: string,
     options: WorkflowTaskOptions<OutputSchemaValue<Schema>>,
-    handler: WorkflowTaskHandler<Providers, {}, Awaited<Result> & WorkflowTaskResult>,
+    handler: WorkflowTaskHandler<Providers, {}, never, Awaited<Result> & WorkflowTaskResult>,
   ): WorkflowTaskNode<Providers, {}, TaskReturnContext<Result>>;
 
   step<Result extends WorkflowTaskResult>(
     name: string,
-    handler: WorkflowTaskHandler<Providers, {}, Result>,
+    handler: WorkflowTaskHandler<Providers, {}, never, Result>,
   ): WorkflowTaskNode<Providers, {}, TaskReturnContext<Result>>;
 
-  step<Schema extends OutputSchema<JsonObject>, Result extends MaybePromise<OutputSchemaValue<Schema> | void>>(
+  step<
+    Schema extends OutputSchema<JsonObject>,
+    Result extends MaybePromise<WorkflowTaskContextResult<OutputSchemaValue<Schema>> | WorkflowStepInvalidation<string> | void>,
+  >(
     name: string,
     options: WorkflowTaskOptions<OutputSchemaValue<Schema>>,
-    handler: WorkflowTaskHandler<Providers, {}, Awaited<Result> & WorkflowTaskResult>,
+    handler: WorkflowTaskHandler<Providers, {}, never, Awaited<Result> & WorkflowTaskResult>,
   ): WorkflowTaskNode<Providers, {}, TaskReturnContext<Result>>;
 };
 
@@ -389,8 +491,8 @@ export type WorkflowNodeDefinition<
   readonly name: string;
   readonly workflow: WorkflowDefinition<string, Providers>;
   readonly workspaceDefinition?: WorkflowWorkspaceDefinition<Providers, OutputContext>;
-  readonly createDefinition?: WorkflowCreateDefinition<Providers, OutputContext>;
   readonly operations?: readonly WorkflowOperationDefinition<Providers, any>[];
+  readonly workspaceOperations?: readonly WorkflowWorkspaceOperationDefinition<Providers, OutputContext, any, any>[];
   readonly __providers?: Providers;
   readonly __input?: InputContext;
   readonly __output?: OutputContext;
@@ -403,42 +505,94 @@ export type WorkflowTaskNode<
 > = WorkflowNodeDefinition<Providers, InputContext, OutputContext> & {
   readonly nodeKind: "task";
   readonly options?: WorkflowTaskOptions;
-  readonly handler: WorkflowTaskHandler<Providers, InputContext, any>;
+  readonly handler: WorkflowTaskHandler<Providers, InputContext, string, any>;
 };
 
 export type WorkflowSequenceBuilder<
   Providers extends WorkflowProviderMap,
   InputContext extends JsonObject,
   OutputContext extends JsonObject,
+  WorkspaceData extends object = JsonObject,
+  OperationIds extends string = never,
+  WorkspaceOperationIds extends string = never,
+  PreviousTaskIds extends string = never,
 > = WorkflowNodeDefinition<Providers, InputContext, OutputContext> & {
   readonly nodeKind: "sequence";
   readonly children: readonly WorkflowNodeDefinition<Providers, any, any>[];
 
-  task<Result extends WorkflowTaskResult>(
-    name: string,
-    handler: WorkflowTaskHandler<Providers, OutputContext, Result>,
-  ): WorkflowSequenceBuilder<Providers, InputContext, Merge<OutputContext, TaskReturnContext<Result>>>;
+  task<const Id extends string, Result extends WorkflowTaskResult>(
+    name: Id & WorkflowTaskIdConstraint<Id, PreviousTaskIds>,
+    handler: WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, Result>,
+  ): WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    TaskReturnContext<Result>,
+    WorkspaceData,
+    OperationIds,
+    WorkspaceOperationIds,
+    PreviousTaskIds | Id
+  >;
 
-  task<Schema extends OutputSchema<JsonObject>, Result extends MaybePromise<OutputSchemaValue<Schema> | void>>(
-    name: string,
+  task<
+    const Id extends string,
+    Schema extends OutputSchema<JsonObject>,
+    Result extends MaybePromise<WorkflowTaskContextResult<OutputSchemaValue<Schema>> | WorkflowStepInvalidation<string> | void>,
+  >(
+    name: Id & WorkflowTaskIdConstraint<Id, PreviousTaskIds>,
     options: WorkflowTaskOptions<OutputSchemaValue<Schema>>,
-    handler: WorkflowTaskHandler<Providers, OutputContext, Awaited<Result> & WorkflowTaskResult>,
-  ): WorkflowSequenceBuilder<Providers, InputContext, Merge<OutputContext, TaskReturnContext<Result>>>;
+    handler: WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, Awaited<Result> & WorkflowTaskResult>,
+  ): WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    TaskReturnContext<Result>,
+    WorkspaceData,
+    OperationIds,
+    WorkspaceOperationIds,
+    PreviousTaskIds | Id
+  >;
 
-  step<Result extends WorkflowTaskResult>(
-    name: string,
-    handler: WorkflowTaskHandler<Providers, OutputContext, Result>,
-  ): WorkflowSequenceBuilder<Providers, InputContext, Merge<OutputContext, TaskReturnContext<Result>>>;
+  step<const Id extends string, Result extends WorkflowTaskResult>(
+    name: Id & WorkflowTaskIdConstraint<Id, PreviousTaskIds>,
+    handler: WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, Result>,
+  ): WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    TaskReturnContext<Result>,
+    WorkspaceData,
+    OperationIds,
+    WorkspaceOperationIds,
+    PreviousTaskIds | Id
+  >;
 
-  step<Schema extends OutputSchema<JsonObject>, Result extends MaybePromise<OutputSchemaValue<Schema> | void>>(
-    name: string,
+  step<
+    const Id extends string,
+    Schema extends OutputSchema<JsonObject>,
+    Result extends MaybePromise<WorkflowTaskContextResult<OutputSchemaValue<Schema>> | WorkflowStepInvalidation<string> | void>,
+  >(
+    name: Id & WorkflowTaskIdConstraint<Id, PreviousTaskIds>,
     options: WorkflowTaskOptions<OutputSchemaValue<Schema>>,
-    handler: WorkflowTaskHandler<Providers, OutputContext, Awaited<Result> & WorkflowTaskResult>,
-  ): WorkflowSequenceBuilder<Providers, InputContext, Merge<OutputContext, TaskReturnContext<Result>>>;
+    handler: WorkflowTaskHandler<Providers, OutputContext, PreviousTaskIds, Awaited<Result> & WorkflowTaskResult>,
+  ): WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    TaskReturnContext<Result>,
+    WorkspaceData,
+    OperationIds,
+    WorkspaceOperationIds,
+    PreviousTaskIds | Id
+  >;
 
   add<Node extends WorkflowNodeDefinition<Providers, any, any>>(
     node: OutputContext extends WorkflowNodeInput<Node> ? Node : never,
-  ): WorkflowSequenceBuilder<Providers, InputContext, Merge<OutputContext, WorkflowNodeOutput<Node>>>;
+  ): WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    WorkflowNodeOutput<Node>,
+    WorkspaceData,
+    OperationIds,
+    WorkspaceOperationIds,
+    PreviousTaskIds
+  >;
 
   parallel<const Branches extends Record<string, WorkflowNodeDefinition<Providers, any, any>>>(
     branches: {
@@ -446,22 +600,105 @@ export type WorkflowSequenceBuilder<
         ? Branches[Key]
         : never;
     },
-  ): WorkflowSequenceBuilder<Providers, InputContext, Merge<OutputContext, ParallelOutput<Branches>>>;
-
-  workspace(
-    definition: WorkflowWorkspaceDefinition<Providers, OutputContext>,
-  ): WorkflowSequenceBuilder<Providers, InputContext, OutputContext>;
+  ): WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    Merge<OutputContext, ParallelOutput<Branches>>,
+    WorkspaceData,
+    OperationIds,
+    WorkspaceOperationIds,
+    PreviousTaskIds
+  >;
 
-  create<Result extends WorkflowCreateResult>(
-    handler: WorkflowCreateHandler<Providers, OutputContext, Result>,
-  ): WorkflowSequenceBuilder<Providers, InputContext, OutputContext>;
+  workspace<Data extends JsonObject>(
+    definition: WorkflowWorkspaceDefinition<Providers, OutputContext, Data>,
+  ): WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    OutputContext,
+    ReadonlyWorkspaceContext<Data>,
+    OperationIds,
+    WorkspaceOperationIds,
+    PreviousTaskIds
+  >;
 
   operation<const Id extends string, Input extends object = {}>(
-    id: Id,
+    id: Id & WorkflowOperationIdConstraint<Id, OperationIds>,
     options: WorkflowOperationOptions<Providers, Input>,
-  ): WorkflowSequenceBuilder<Providers, InputContext, OutputContext>;
+  ): WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    OutputContext,
+    WorkspaceData,
+    OperationIds | Id,
+    WorkspaceOperationIds,
+    PreviousTaskIds
+  >;
+
+  workspaceOperation<const Id extends string, Input extends object = {}>(
+    id: Id & WorkflowOperationIdConstraint<Id, WorkspaceOperationIds>,
+    options: WorkflowWorkspaceOperationOptions<Providers, OutputContext, WorkspaceData, Input>,
+  ): WorkflowSequenceBuilder<
+    Providers,
+    InputContext,
+    OutputContext,
+    WorkspaceData,
+    OperationIds,
+    WorkspaceOperationIds | Id,
+    PreviousTaskIds
+  >;
 };
 
+export const RESERVED_WORKFLOW_OPERATION_IDS = [
+  "apply",
+  "completion",
+  "create",
+  "doctor",
+  "fork",
+  "help",
+  "init",
+  "ls",
+  "plan",
+  "projects",
+  "remove",
+  "run",
+  "version",
+] as const;
+
+export type ReservedWorkflowOperationId = typeof RESERVED_WORKFLOW_OPERATION_IDS[number];
+
+type WorkflowOperationIdError<Message extends string> = {
+  readonly __rigkitOperationIdError: Message;
+};
+
+export type WorkflowOperationIdConstraint<
+  Id extends string,
+  Existing extends string,
+> = string extends Id
+  ? unknown
+  : Id extends Existing
+    ? WorkflowOperationIdError<`Operation id "${Id}" is already defined`>
+    : Id extends ReservedWorkflowOperationId
+      ? WorkflowOperationIdError<`Operation id "${Id}" is reserved by Rigkit`>
+      : Id extends `${string}/${string}`
+        ? WorkflowOperationIdError<`Operation id "${Id}" cannot contain "/"`>
+        : unknown;
+
+type WorkflowTaskIdError<Message extends string> = {
+  readonly __rigkitTaskIdError: Message;
+};
+
+export type WorkflowTaskIdConstraint<
+  Id extends string,
+  Existing extends string,
+> = string extends Id
+  ? unknown
+  : Id extends Existing
+    ? WorkflowTaskIdError<`Task id "${Id}" is already defined`>
+    : Id extends ""
+      ? WorkflowTaskIdError<"Task ids must be non-empty">
+      : unknown;
+
 export type WorkflowNodeInput<Node> =
   Node extends WorkflowNodeDefinition<any, infer Input extends JsonObject, any>
     ? Input
@@ -476,13 +713,14 @@ export type ParallelOutput<Branches extends Record<string, WorkflowNodeDefinitio
   [Key in keyof Branches & string]: WorkflowNodeOutput<Branches[Key]>;
 };
 
-export type TaskReturnContext<Return> = Exclude<Awaited<Return>, void | undefined> extends infer Context
-  ? [Context] extends [never]
-    ? {}
-    : Context extends JsonObject
-      ? Context
-      : never
-  : {};
+export type TaskReturnContext<Return> =
+  Exclude<Awaited<Return>, void | undefined | WorkflowStepInvalidation<string>> extends infer Result
+    ? [Result] extends [never]
+      ? {}
+      : Result extends { ctx: infer Context extends JsonObject }
+        ? Simplify<Context>
+        : never
+    : {};
 
 export type Merge<Left extends JsonObject, Right extends JsonObject> =
   Simplify<Omit<Left, keyof Right> & Right>;
@@ -492,42 +730,19 @@ export type Simplify<Value> = { [Key in keyof Value]: Value[Key] } & {};
 export type WorkflowWorkspaceDefinition<
   Providers extends WorkflowProviderMap = WorkflowProviderMap,
   Context extends JsonObject = JsonObject,
+  Data extends JsonObject = JsonObject,
 > = {
-  source?: (ctx: Readonly<Context>) => JsonValue;
-  cwd?: string | ((ctx: Readonly<Context>) => string | undefined);
-  ports?: readonly number[];
-  onCreated?: (context: WorkflowWorkspaceCreatedContext<Providers, Context>) => MaybePromise<void>;
-  onOpen?: (context: WorkflowWorkspaceOpenContext<Providers, Context>) => MaybePromise<void>;
-};
-
-export type WorkflowWorkspaceCreatedContext<
-  Providers extends WorkflowProviderMap = WorkflowProviderMap,
-  Context extends JsonObject = JsonObject,
-> = WorkflowWorkspaceLifecycleContext<Providers, Context>;
-
-export type WorkflowWorkspaceOpenContext<
-  Providers extends WorkflowProviderMap = WorkflowProviderMap,
-  Context extends JsonObject = JsonObject,
-> = WorkflowWorkspaceLifecycleContext<Providers, Context>;
-
-export type WorkflowWorkspaceLifecycleContext<
-  Providers extends WorkflowProviderMap = WorkflowProviderMap,
-  Context extends JsonObject = JsonObject,
-> = {
-  workspace: WorkspaceRuntimeRecord;
-  ctx: Readonly<Context>;
-  providers: ProviderRuntimeMap<Providers>;
-  providerContext: ProviderWorkspaceContext;
-  local: LocalWorkspaceRuntime;
+  create: WorkflowWorkspaceCreateHandler<Providers, Context, Data>;
+  remove: WorkflowWorkspaceRemoveHandler<Providers, Context, Data>;
 };
 
 export type LoadedWorkflow = {
   name: string;
   providers: Record<string, LoadedProviderDefinition>;
   root: WorkflowNodeDefinition<any, any, any>;
-  workspace?: WorkflowWorkspaceDefinition<any, any>;
-  create?: WorkflowCreateDefinition<any, any>;
+  workspace?: WorkflowWorkspaceDefinition<any, any, any>;
   operations: readonly WorkflowOperationDefinition<any, any>[];
+  workspaceOperations: readonly WorkflowWorkspaceOperationDefinition<any, any, any, any>[];
 };
 
 export type WorkflowPlanNode = {
@@ -554,19 +769,11 @@ export type MachinePlan = WorkflowPlan;
 export type WorkspaceRecord = {
   id: string;
   name: string;
-  providerId: string;
   workflow: string;
-  resourceId: string;
-  snapshotId?: string;
-  sourceRef: JsonValue;
-  context: Record<string, JsonValue>;
+  workflowCtx: Record<string, JsonValue>;
+  ctx: Record<string, JsonValue>;
   createdAt: string;
   updatedAt: string;
-  metadata: Record<string, JsonValue>;
-};
-
-export type WorkspaceRuntimeRecord = WorkspaceRecord & {
-  cwd?: string;
 };
 
 export type WorkflowEvent =
@@ -597,7 +804,7 @@ export type WorkflowEvent =
       title: string;
     }
   | { type: "artifact.created"; nodePath: string; providerId: string; kind: string; ref: JsonValue }
-  | { type: "workspace.ready"; workspaceId: string; providerId: string; resourceId: string; snapshotId?: string };
+  | { type: "workspace.ready"; workspaceId: string };
 
 export type DevMachineEvent = WorkflowEvent;