@pikku/core 0.12.107 → 0.12.112

package/src/wirings/workflow/dsl/workflow-dsl.types.ts

@@ -1,709 +0,0 @@
-/**
- * DSL (Domain Specific Language) workflow types
- * These types define the step-based workflow format extracted by the inspector
- */
-
-import type { StandardSchemaV1 } from '@standard-schema/spec'
-
-import type { WorkflowRun } from '../workflow.types.js'
-import type { ScenarioPersona } from '../../../services/personas-service.js'
-import type {
-  ScenarioStepOptions,
-  ScenarioStepPhase,
-  ScenarioSurface,
-} from '../scenario-step.types.js'
-
-/**
- * Workflow step options
- */
-export interface WorkflowStepOptions {
-  /** Display name for logs/UI (optional, doesn't affect execution) */
-  description?: string
-  /** Number of retry attempts for failed steps (only applies to local execution) */
-  retries?: number
-  /** Delay between retry attempts (e.g., '1s', '2s', '2min') */
-  retryDelay?: string | number
-  /**
-   * RPC to invoke for compensation when this step fails after exhausting its
-   * retries. Mirrors a graph node's `onError`: the handler receives
-   * `{ error: { message } }` and the original error is still thrown, so the
-   * workflow fails — this is compensation, not recovery.
-   */
-  onError?: string
-  /**
-   * Run this step as an actor (scenarios). The RPC is sent through the
-   * actor's authenticated client over the REAL transport — never dispatched
-   * internally — so auth middleware and permissions are exercised end-to-end.
-   * The step is recorded durably like any RPC step.
-   */
-  actor?: ScenarioPersona
-  // Future: timeout, failFast, priority
-}
-
-/**
- * Options for workflow.expectEventually() — a durable polling step used by
- * scenarios to await async effects (a notification landing, a job finishing).
- */
-export interface WorkflowExpectEventuallyOptions extends WorkflowStepOptions {
-  /** Give up after this long (e.g. '30s'). Default '30s'. */
-  within?: string | number
-  /** Poll interval (e.g. '1s'). Default '1s'. */
-  interval?: string | number
-}
-
-/** Options for workflow.expectError() */
-export interface WorkflowExpectErrorOptions extends WorkflowStepOptions {
-  /** Assert the error message matches (string = substring match). */
-  matches?: string | RegExp
-}
-
-/** Options for workflow.expectService() */
-export interface WorkflowExpectServiceOptions extends WorkflowStepOptions {
-  /** Assert a recorded call's first argument deep-equals this value. */
-  calledWith?: unknown
-  /** Assert the exact number of matching calls. Default: at least one. */
-  times?: number
-}
-
-/** Options for workflow.expectScore() */
-export interface WorkflowExpectScoreOptions extends WorkflowStepOptions {
-  /** Fail below this score. Defaults to 0.5 — a scorer that answered at all. */
-  atLeast?: number
-  /** Fail above this score, for a scorer where high is the failure. */
-  atMost?: number
-  /**
-   * The known-correct answer, which is what a reference-based judge grades
-   * against. Live traffic has no answer key, so a judge declared
-   * `requiresReference` is only ever reachable from a scenario.
-   */
-  reference?: string
-}
-
-/**
- * Type signature for workflow.do() RPC form - used by inspector
- */
-export type WorkflowWireDoRPC = <TOutput = any, TInput = any>(
-  stepName: string,
-  rpcName: string,
-  data: TInput,
-  options?: WorkflowStepOptions
-) => Promise<TOutput>
-
-/**
- * Type signature for workflow.do() inline form - used by inspector
- */
-export type WorkflowWireDoInline = <T>(
-  stepName: string,
-  fn: () => Promise<T> | T,
-  options?: WorkflowStepOptions
-) => Promise<T>
-
-/**
- * Type signature for scenario.given/when/then - used by inspector.
- *
- * Deliberately mirrors WorkflowWireDoRPC's shape: the target is a string, not
- * an imported symbol, so the extractor reads it as a literal.
- */
-export type ScenarioStepInvocation = <TOutput = any, TInput = any>(
-  stepName: string,
-  stepFunc: string,
-  data?: TInput,
-  options?: ScenarioStepOptions
-) => Promise<TOutput>
-
-/**
- * Type signature for workflow.sleep() - used by inspector
- */
-export type WorkflowWireSleep = (
-  stepName: string,
-  duration: string
-) => Promise<void>
-
-/**
- * Type signature for workflow.suspend() - used by inspector.
- * `reason` is both the human-readable message stored on the suspended run and
- * the suspend point's stable identity (used raw as the durable step name), so a
- * workflow can have multiple independent suspends — including dynamic reasons in
- * loops, like dynamic `do()` step names.
- */
-export type WorkflowWireSuspend = (reason: string) => Promise<void>
-
-/**
- * Who is allowed to answer an approval gate, relative to the user who started
- * the run.
- *
- * - `any` — anyone the approve entrypoint lets through. The gate is a pause for
- *   a decision, not an authorization boundary.
- * - `owner` — only the user who started the run, so a gate can be used to
- *   confirm an action against the same person who requested it.
- * - `not-initiator` — anyone *except* the user who started the run: four-eyes.
- *   A run with no recorded initiator has nobody to exclude, so this degrades to
- *   requiring a signed-in decider.
- */
-export type WorkflowApprovalApprovers = 'any' | 'owner' | 'not-initiator'
-
-/**
- * Who may answer an approval gate. Declared on the gate rather than the
- * entrypoint because it is a property of the decision being made, and because
- * one workflow can hold several gates with different requirements.
- */
-export interface WorkflowApprovalPolicy {
-  /**
-   * Defaults to `any`. See {@link WorkflowApprovalApprovers}.
-   */
-  approvers?: WorkflowApprovalApprovers
-  /**
-   * Additionally require the decider's session to hold this scope, so
-   * "a second pair of eyes" can be narrowed to "a second pair of *senior*
-   * eyes". Combines with `approvers` — both must pass.
-   */
-  approverScope?: string
-}
-
-/**
- * The decider, reduced to the two facts a policy can be expressed in terms of.
- * Recorded alongside the decision so the gate can be judged on replay — the
- * session itself is long gone by then — and carried into the settled outcome so
- * the answer keeps its provenance.
- */
-export interface ApprovalDecider {
-  userId?: string
-  scopes?: string[]
-}
-
-/**
- * Options for workflow.approval().
- */
-export interface WorkflowApprovalOptions<
-  TSchema extends StandardSchemaV1 = StandardSchemaV1,
-> extends WorkflowApprovalPolicy {
-  /**
-   * Schema the decision payload is validated against. This is a VALUE, not a
-   * type generic: the payload arrives from an untrusted caller over the approve
-   * wire, and a generic is erased at compile time — it would validate nothing.
-   * Any standard-schema library (zod, valibot, arktype) satisfies this.
-   */
-  schema: TSchema
-  /**
-   * Give up waiting after this long (e.g. '3d'), yielding `{ status: 'expired' }`
-   * instead of waiting forever. Evaluated on replay from a recorded deadline, so
-   * the answer is correct even if the wake-up timer is never delivered.
-   */
-  expiry?: string | number
-}
-
-/**
- * The result of an approval gate. A union rather than a throw so that callers
- * must handle the deadline case, and so "skip it and carry on" stays trivial.
- * `decided` means a human answered — whether that answer was yes or no is
- * carried in `data` and is the application's business, not the framework's.
- */
-export type ApprovalOutcome<T> =
-  | {
-      status: 'decided'
-      data: T
-      /**
-       * Who answered, and when. Run state holds the decision only while the gate
-       * is open — it is overwritten by the next write and cleared outright when a
-       * decision is refused — so the settled answer carries its own provenance
-       * into the step result, which is append-only.
-       */
-      decidedBy?: ApprovalDecider
-      decidedAt?: string
-    }
-  | { status: 'expired' }
-
-/**
- * Type signature for workflow.approval() - used by inspector.
- * Like {@link WorkflowWireSuspend}, `reason` is the approval point's stable
- * durable identity. Unlike suspend, the gate stays closed until a decision is
- * recorded against it, and the decision is handed back to the caller.
- */
-export type WorkflowWireApproval = <TSchema extends StandardSchemaV1>(
-  reason: string,
-  options: WorkflowApprovalOptions<TSchema>
-) => Promise<ApprovalOutcome<StandardSchemaV1.InferOutput<TSchema>>>
-
-/**
- * Input source for step arguments in DSL workflows
- */
-export type InputSource =
-  | { from: 'input'; path: string }
-  | { from: 'outputVar'; name: string; path?: string }
-  | { from: 'item'; path: string }
-  | { from: 'literal'; value: unknown }
-  | { from: 'template'; parts: string[]; expressions: InputSource[] }
-
-/**
- * Output binding for return statements in DSL workflows
- */
-export type OutputBinding =
-  | { from: 'outputVar'; name: string; path?: string }
-  | { from: 'stateVar'; name: string; path?: string }
-  | { from: 'input'; path: string }
-  | { from: 'literal'; value: unknown }
-  | { from: 'expression'; expression: string }
-
-/**
- * RPC step metadata (base form)
- */
-export interface RpcStepMeta {
-  /** RPC form - generates queue worker */
-  type: 'rpc'
-  /** Cache key (stepName from workflow.do) */
-  stepName: string
-  /** RPC to invoke */
-  rpcName: string
-  /** Output variable name (if assigned) */
-  outputVar?: string
-  /** Input source mappings, or 'passthrough' when entire data is passed */
-  inputs?: Record<string, InputSource> | 'passthrough'
-  /** Step options */
-  options?: WorkflowStepOptions
-  /** Scenario actor name this step runs as ({ actor: actors.x }) */
-  actor?: string
-  /** True for workflow.expectEventually polling steps */
-  expectEventually?: boolean
-}
-
-/**
- * Scenario step metadata — a call to `scenario.given/when/then`.
- *
- * Distinct from RpcStepMeta on purpose: a step runs locally through
- * runPikkuFunc and must never be treated as dispatchable on the queue/replay
- * path, nor registered as a callable RPC (a browser-driving step must not be
- * network-invocable).
- */
-export interface ScenarioStepMeta {
-  type: 'scenarioStep'
-  /** Cache key (first argument), ordinal-suffixed by the engine when repeated */
-  stepName: string
-  /** Registered name of the step function being run */
-  stepFunc: string
-  /** Which keyword the reporter prefixes — Given, When or Then */
-  phase: ScenarioStepPhase
-  /** Output variable name (if assigned) */
-  outputVar?: string
-  /** Input source mappings, or 'passthrough' when entire data is passed */
-  inputs?: Record<string, InputSource> | 'passthrough'
-  /** Step options */
-  options?: WorkflowStepOptions
-  /** Scenario actor name this step runs as ({ actor: actors.x }) */
-  actor?: string
-  /** Mirrors the surfaces the step function declares a binding for */
-  surfaces?: ScenarioSurface[]
-}
-
-/**
- * Simple condition expression (leaf node)
- */
-export interface SimpleCondition {
-  type: 'simple'
-  expression: string
-}
-
-/**
- * Nested condition structure supporting AND/OR operations
- */
-export type Condition =
-  | SimpleCondition
-  | { type: 'and'; conditions: Condition[] }
-  | { type: 'or'; conditions: Condition[] }
-
-/**
- * A single branch in an if/else-if chain
- */
-export interface BranchCase {
-  /** Condition for this branch */
-  condition: Condition
-  /** Steps to execute when condition is true */
-  steps: WorkflowStepMeta[]
-}
-
-/**
- * Branch step metadata (if/else-if/else control flow)
- */
-export interface BranchStepMeta {
-  type: 'branch'
-  /** Branches in order: first is "if", rest are "else if" */
-  branches: BranchCase[]
-  /** Else branch steps (when no conditions match) */
-  elseSteps?: WorkflowStepMeta[]
-}
-
-/**
- * Parallel group step metadata (Promise.all with multiple steps)
- */
-export interface ParallelGroupStepMeta {
-  type: 'parallel'
-  /** Child steps to execute in parallel */
-  children: Array<RpcStepMeta | ScenarioStepMeta>
-}
-
-/**
- * Fanout step metadata (parallel or sequential iteration)
- */
-export interface FanoutStepMeta {
-  type: 'fanout'
-  /**
-   * Step name for this fanout. Optional: a fanout is not itself a cached step,
-   * and node ids are step names — borrowing a body step's name would give the
-   * loop and that step the same id, collapsing one onto the other.
-   */
-  stepName?: string
-  /** Source array variable name */
-  sourceVar: string
-  /** Iterator variable name */
-  itemVar: string
-  /** Execution mode */
-  mode: 'parallel' | 'sequential'
-  /** Steps to execute inline per iteration, in order */
-  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta | ScenarioStepMeta>
-  /** Time between iterations (sequential mode only) */
-  timeBetween?: string
-}
-
-/**
- * Return step metadata (workflow output)
- */
-export interface ReturnStepMeta {
-  type: 'return'
-  /** Output bindings */
-  outputs: Record<string, OutputBinding>
-  /**
-   * Variables spread into the returned object (`return { ...r }`), or the sole
-   * returned variable (`return r`). Their fields are not enumerable statically,
-   * so they are recorded by name rather than expanded into `outputs`.
-   */
-  spread?: string[]
-}
-
-/**
- * Inline step metadata
- */
-export interface InlineStepMeta {
-  /** Inline form - local execution */
-  type: 'inline'
-  /** Cache key (stepName from workflow.do) */
-  stepName: string
-  /** Display name */
-  description?: string
-  /** Step options */
-  options?: WorkflowStepOptions
-}
-
-/**
- * Sleep step metadata
- */
-export interface SleepStepMeta {
-  /** Sleep step */
-  type: 'sleep'
-  /** Cache key (stepName from workflow.sleep) */
-  stepName: string
-  /** Sleep duration */
-  duration: string | number
-  /**
-   * Source text of a duration only known at runtime (e.g. a loop variable).
-   * The closure evaluates it, so it is legal DSL; it is kept separate from
-   * `duration` so regenerated code emits it raw rather than as a string
-   * literal, exactly as `expression` does on a set step.
-   */
-  expression?: string
-}
-
-/**
- * Cancel step metadata
- */
-export interface CancelStepMeta {
-  /** Cancel step */
-  type: 'cancel'
-  /** Optional cancellation reason */
-  reason?: string
-}
-
-/**
- * Set step metadata (context variable assignment)
- */
-export interface SetStepMeta {
-  /** Set step */
-  type: 'set'
-  /** Variable name to set (must be in context) */
-  variable: string
-  /** Literal value to assign. Mutually exclusive with `expression`. */
-  value?: unknown
-  /**
-   * Source text of a non-literal assignment (e.g. `count + 1`). Kept separate
-   * from `value` so regenerated code can emit it raw — a string `value` is a
-   * string literal, an `expression` is code.
-   */
-  expression?: string
-}
-
-/**
- * Switch case metadata
- */
-export interface SwitchCaseMeta {
-  /** Case value (literal) or expression */
-  value?: string | number | boolean | null
-  /** Case expression (for complex cases) */
-  expression?: string
-  /** Steps to execute for this case */
-  steps: WorkflowStepMeta[]
-}
-
-/**
- * Switch step metadata (switch/case control flow)
- */
-export interface SwitchStepMeta {
-  type: 'switch'
-  /** Expression being switched on */
-  expression: string
-  /** Case branches */
-  cases: SwitchCaseMeta[]
-  /** Default case steps (optional) */
-  defaultSteps?: WorkflowStepMeta[]
-}
-
-/**
- * Suspend step metadata (workflow.suspend())
- */
-export interface SuspendStepMeta {
-  type: 'suspend'
-  /** Reason string passed to workflow.suspend() — becomes the durable step key */
-  reason: string
-}
-
-/**
- * Approval step metadata (workflow.approval())
- */
-export interface ApprovalStepMeta {
-  type: 'approval'
-  /** Reason string passed to workflow.approval() — becomes the durable step key */
-  reason: string
-  /** Output variable name (if assigned) */
-  outputVar?: string
-  /** Expiry duration, when one was given */
-  expiry?: string | number
-  /** Who may answer the gate, when the default was not used */
-  approvers?: WorkflowApprovalApprovers
-  /** Scope the decider must hold, when one was required */
-  approverScope?: string
-}
-
-/**
- * Filter step metadata (array.filter)
- */
-export interface FilterStepMeta {
-  type: 'filter'
-  /** Source array variable name */
-  sourceVar: string
-  /** Iterator variable name */
-  itemVar: string
-  /** Filter condition */
-  condition: Condition
-  /** Output variable name (if assigned) */
-  outputVar?: string
-}
-
-/**
- * Array predicate step metadata (array.some, array.every)
- */
-export interface ArrayPredicateStepMeta {
-  type: 'arrayPredicate'
-  /** Predicate mode */
-  mode: 'some' | 'every'
-  /** Source array variable name */
-  sourceVar: string
-  /** Iterator variable name */
-  itemVar: string
-  /** Predicate condition */
-  condition: Condition
-  /** Output variable name (if assigned) */
-  outputVar?: string
-}
-
-/**
- * Workflow step metadata (extracted by inspector)
- */
-export type WorkflowStepMeta =
-  | RpcStepMeta
-  | ScenarioStepMeta
-  | BranchStepMeta
-  | ParallelGroupStepMeta
-  | FanoutStepMeta
-  | ReturnStepMeta
-  | InlineStepMeta
-  | SleepStepMeta
-  | CancelStepMeta
-  | SuspendStepMeta
-  | ApprovalStepMeta
-  | SwitchStepMeta
-  | FilterStepMeta
-  | ArrayPredicateStepMeta
-  | SetStepMeta
-
-/**
- * Workflow step wire context for RPC functions
- * Provides step-level metadata including retry attempt tracking
- */
-export interface WorkflowStepWire {
-  /** The workflow run ID */
-  runId: string
-  /**
-   * The step row ID. Whether it stays the same or is minted fresh per attempt is
-   * STORE-SPECIFIC (in-memory mints a new one each attempt; the SQL store reuses
-   * the row) — do NOT use it as a dedupe key. Use `invocationId`.
-   */
-  stepId: string
-  /**
-   * Stable identity of this step invocation — the idempotency / dedupe key.
-   * Identical across every retry of the same call (derived from runId + step
-   * name) regardless of storage backend, so a step can `ON CONFLICT (invocationId)`
-   * or pass it as an external idempotency key and have retries collapse onto the
-   * first attempt.
-   */
-  invocationId: string
-  /** Current attempt number (1-indexed, increments on retry) */
-  attemptCount: number
-  /**
-   * Invocation ID of the predecessor step this one was reached from (the walked
-   * transition/edge). Undefined for entry steps. Lets a step know its origin —
-   * e.g. in a cyclic graph `a → b → a → c`, the second `a` carries `b`'s id.
-   */
-  fromInvocationId?: string
-}
-
-/**
- * Workflow wire object for DSL workflows
- * Provides workflow-specific capabilities to function execution
- */
-export interface PikkuWorkflowWire {
-  /** The workflow name */
-  name: string
-  /** The current run ID */
-  runId: string
-  /** Pikku user ID propagated from the originating request for credential resolution */
-  pikkuUserId?: string
-  /** Get the current workflow run */
-  getRun: () => Promise<WorkflowRun>
-
-  /** Execute a workflow step (overloaded - RPC or inline form) */
-  do: WorkflowWireDoRPC & WorkflowWireDoInline
-
-  /** Sleep for a duration */
-  sleep: WorkflowWireSleep
-
-  /** Suspend workflow until explicitly resumed */
-  suspend: WorkflowWireSuspend
-
-  /** Suspend workflow until a human records a decision against this gate */
-  approval: WorkflowWireApproval
-}
-
-/**
- * What a scenario has accumulated so far, shared by its body and its hooks.
- *
- * `Partial` because a scenario can fail at any step: `Out` describes what a
- * *completed* run produces, and the context holds however much of it this run
- * reached.
- *
- * The `0 extends 1 & Out` branch keeps `any` collapsing to `any` rather than to
- * the union of the other two. `PikkuWire` and `PikkuFunctionConfig` both use
- * this type as a generic *constraint*, and a constraint carrying a concrete
- * context would reject every wire whose scenario output differs from it.
- */
-export type ScenarioContext<Out = unknown> = 0 extends 1 & Out
-  ? any
-  : Out extends object
-    ? Partial<Out>
-    : Record<string, unknown>
-
-export interface PikkuScenarioWire<Out = unknown> extends PikkuWorkflowWire {
-  /**
-   * Scratch the body writes and the `before`/`after` hooks read. A hook is a
-   * separate function and cannot see the body's locals, so this is how teardown
-   * learns the ids the body minted.
-   *
-   * Deliberately *not* a world: it is scoped to one run, and scenario steps
-   * cannot reach it. Steps stay pure functions of their declared inputs, so the
-   * ladder in the report remains a complete account of what a step saw.
-   */
-  context: ScenarioContext<Out>
-
-  /**
-   * Durable polling step: invoke `rpcName` (as an actor when `options.actor`
-   * is set) until `predicate` passes or `options.within` elapses.
-   */
-  expectEventually: <TOutput = any, TInput = any>(
-    stepName: string,
-    rpcName: string,
-    data: TInput,
-    predicate: (output: TOutput) => boolean,
-    options?: WorkflowExpectEventuallyOptions
-  ) => Promise<TOutput>
-
-  /** Error-path step: succeeds only when the RPC throws; returns the message */
-  expectError: <TInput = any>(
-    stepName: string,
-    rpcName: string,
-    data: TInput,
-    options?: WorkflowExpectErrorOptions
-  ) => Promise<string>
-
-  /** Stub-assertion step: asserts `service.method` was called on the target server */
-  expectService: (
-    stepName: string,
-    serviceMethod: string,
-    options?: WorkflowExpectServiceOptions
-  ) => Promise<void>
-
-  /**
-   * Grade-assertion step: runs one declared scorer against a finished agent run
-   * and asserts the score. Returns the grade, so a scenario can report the
-   * reason a judge gave rather than only that it fell short.
-   */
-  expectScore: (
-    stepName: string,
-    runId: string,
-    scorerName: string,
-    options?: WorkflowExpectScoreOptions
-  ) => Promise<{ score: number; reason?: string }>
-
-  /**
-   * Run a registered scenario step, as the setup the scenario starts from.
-   *
-   * Shaped exactly like `do`'s RPC form — `(stepName, target, data, options)` —
-   * so the inspector reads the target as a string literal rather than resolving
-   * an imported symbol.
-   *
-   * The generated `TypedScenario` narrows these over `FlattenedScenarioStepMap`.
-   */
-  given(
-    stepName: string,
-    stepFunc: string,
-    data?: any,
-    options?: ScenarioStepOptions
-  ): Promise<any>
-
-  /** `when`: the same call as `given`, rendered as the action under test */
-  when(
-    stepName: string,
-    stepFunc: string,
-    data?: any,
-    options?: ScenarioStepOptions
-  ): Promise<any>
-
-  /**
-   * `then`: a claim about what the action left behind. Unlike `given`/`when`
-   * this is not prose alone — the step's bindings become witnesses, so every
-   * declared surface is observed and the observations must agree.
-   */
-  then(
-    stepName: string,
-    stepFunc: string,
-    data?: any,
-    options?: ScenarioStepOptions
-  ): Promise<any>
-
-  runScheduledTask: (name: string) => Promise<unknown>
-}