@pikku/core 0.12.72 → 0.12.74

package/src/wirings/workflow/graph/graph-runner.ts

@@ -29,7 +29,6 @@ function buildTemplateRegex(nodeId: string): RegExp | null {
   return new RegExp(`^${escaped}$`)
 }
 
-/** Strip a trailing revisit ordinal (`node#2` → `node`); leaves other names as-is. */
 function stripInstanceOrdinal(name: string): string {
   const hash = name.lastIndexOf('#')
   if (hash <= 0) return name
@@ -48,7 +47,6 @@ function remapStepNamesToNodeIds(
   }
   return stepNames.map((name) => {
     if (nodes[name]) return name
-    // Revisit instance (`node#N`) maps to its logical node.
     const base = stripInstanceOrdinal(name)
     if (base !== name && nodes[base]) return base
     const matches: string[] = []
@@ -69,8 +67,6 @@ function remapStepNamesToNodeIds(
 
 const ENTRY_FROM = '__entry__'
 
-/** Whether `target` can reach `source` over `next` edges — i.e. an edge
- *  source→target closes a cycle (a back-edge), vs a plain forward edge. */
 function closesCycle(
   source: string,
   target: string,
@@ -88,15 +84,6 @@ function closesCycle(
   return false
 }
 
-/**
- * Decide which next steps to fire this tick. Two kinds of edge:
- *  - forward edge → node-once: fire the target only if it has no instance yet,
- *    so converging edges (joins) collapse to a single run (unchanged behavior).
- *  - back-edge (target can reach the source, closing a cycle) → revisit: fire a
- *    fresh ordinal instance (`target#1`, …), edge-once on `from → target` so it
- *    doesn't re-fire every tick. Cycles terminate when branch routing stops
- *    looping back; a node always records the predecessor it was reached from.
- */
 function planGraphTransitions(
   nodes: Record<string, any>,
   instances: Array<{ stepName: string; status: string; fromStepName?: string }>,
@@ -122,7 +109,6 @@ function planGraphTransitions(
   const completed = instances.filter((i) => i.status === 'succeeded')
   const completedLogical = new Set(completed.map((i) => toLogical(i.stepName)))
 
-  // Available edges: entry edges + each completed instance's resolved `next`.
   const edges: Array<{
     from?: string
     fromKey: string
@@ -140,7 +126,12 @@ function planGraphTransitions(
       node.next,
       branchByStep[inst.stepName]
     )) {
-      edges.push({ from: inst.stepName, fromKey: inst.stepName, fromLogical, target })
+      edges.push({
+        from: inst.stepName,
+        fromKey: inst.stepName,
+        fromLogical,
+        target,
+      })
     }
   }
 
@@ -158,7 +149,6 @@ function planGraphTransitions(
     const isBackEdge =
       edge.fromLogical !== undefined &&
       closesCycle(edge.fromLogical, target, nodes)
-    // Forward edge into an already-started node = a join; node-once.
     if (!isBackEdge && visits > 0) {
       consumed.add(edgeKey)
       continue
@@ -457,8 +447,6 @@ async function queueGraphNode(
   nodeConfig?: { retries?: number; retryDelay?: string | number },
   fromStepName?: string
 ): Promise<void> {
-  // Default to the workflow-wide retry policy when the node sets none, so the
-  // persisted step retries match the queue `attempts` (see resolveStepJobOptions).
   const stepOptions = {
     retries: nodeConfig?.retries ?? DEFAULT_STEP_RETRIES,
     retryDelay: nodeConfig?.retryDelay,
@@ -500,8 +488,6 @@ export async function continueGraph(
     failedNodeIds: rawFailed,
     branchKeys: branchByStep,
   } = await workflowService.getCompletedGraphState(runId)
-  // Validate step/branch names map to unambiguous nodes (planning keys
-  // physically; these calls only surface ambiguous template configs).
   remapStepNamesToNodeIds(rawCompleted, nodes, graphName)
   remapBranchKeys(branchByStep, nodes, graphName)
   const failedNodeIds = remapStepNamesToNodeIds(rawFailed, nodes, graphName)
@@ -531,15 +517,12 @@ export async function continueGraph(
   )
 
   if (plan.toFire.length === 0) {
-    // Nothing left to fire and nothing running/blocked → the run is done.
     if (!plan.hasInFlight && !plan.blockedWaiting) {
       await workflowService.updateRunStatus(runId, 'completed')
     }
     return
   }
 
-  // The same run read a few lines up: nothing between here and there writes it,
-  // and `input` is fixed at creation anyway.
   const triggerInput = currentRun?.input
 
   for (const fire of plan.toFire) {
@@ -569,13 +552,6 @@ export async function continueGraph(
   }
 }
 
-/**
- * Invoke a graph node's RPC with the graph + workflow wires, capturing any
- * branch the node selects and persisting it. Shared by the queued
- * (executeGraphStep) and inline (executeGraphNodeInline) executors so both build
- * the wire and record the branch identically — only their child-workflow and
- * onError handling differs around this call.
- */
 async function invokeGraphNodeRpc(
   workflowService: PikkuWorkflowService,
   rpcService: any,
@@ -752,9 +728,6 @@ async function executeGraphNodeInline(
 
   const rpcName = node.rpcName
 
-  // Persist under the physical instance key (node, node#1 … for revisits) and
-  // record the predecessor — same as the queued path (queueGraphNode), so an
-  // inline graph run stores identical step rows + provenance.
   const stepState = await workflowService.insertStepState(
     runId,
     instanceKey,
@@ -864,19 +837,12 @@ async function continueGraphInline(
   triggerInput: any,
   entryNodeIds: string[]
 ): Promise<void> {
-  // Drive the run to completion in-process using the SAME planner as the queued
-  // path (continueGraph): each loop plans the next wave of transitions, executes
-  // them inline (vs queueGraphNode dispatch), then re-plans. Sharing the planner
-  // gives the inline path joins, cycle revisits and fromStepName provenance
-  // identical to the queue — instead of a second, weaker traversal.
   while (true) {
     const {
       failedNodeIds: rawFailed,
       branchKeys: branchByStep,
       completedNodeIds: rawCompleted,
     } = await workflowService.getCompletedGraphState(runId)
-    // Validate step/branch names map to unambiguous nodes (planning keys
-    // physically; these calls only surface ambiguous template configs).
     remapStepNamesToNodeIds(rawCompleted, nodes, graphName)
     remapBranchKeys(branchByStep, nodes, graphName)
     const failedNodeIds = remapStepNamesToNodeIds(rawFailed, nodes, graphName)
@@ -942,7 +908,6 @@ async function continueGraphInline(
         )
       })
     )
-    // Nothing executable fired (e.g. nodes without an rpcName) → can't progress.
     if (executed === 0) return
   }
 }

package/src/wirings/workflow/graph/wire-workflow-graph.ts

@@ -8,10 +8,6 @@ export interface PikkuWorkflowGraphConfig<
   tags?: string[]
   nodes: FuncMap
   config?: T
-  /**
-   * Graph-level free-text notes (e.g. imported sticky notes). Non-semantic:
-   * excluded from the graph topology hash.
-   */
   notes?: string[]
 }
 

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

@@ -1,113 +1,55 @@
-/**
- * Ref value - internal representation after input callback is evaluated
- */
 export interface RefValue {
   __isRef: true
   nodeId: string
   path?: string
 }
 
-/**
- * Helper to create a ref value
- */
 export const createRef = (nodeId: string, path?: string): RefValue => ({
   __isRef: true,
   nodeId,
   path,
 })
 
-/**
- * Check if a value is a ref
- */
 export const isRef = (value: unknown): value is RefValue =>
   typeof value === 'object' &&
   value !== null &&
   '__isRef' in value &&
   (value as RefValue).__isRef === true
 
-/**
- * Input reference for fetching step results
- */
 export interface InputRef {
   nodeId: string
   path?: string
 }
 
-/**
- * Ref function type - provides type-safe references to other nodes' outputs
- * The actual typing is done at the pikkuWorkflowGraph level
- */
 export type RefFn<NodeIds extends string = string> = (
   nodeId: NodeIds,
   path?: string
 ) => RefValue
 
-/**
- * Next node configuration - fully serializable
- * - string: single next node
- * - string[]: parallel execution (all run concurrently)
- * - Record<string, string | string[]>: branching (function calls graph.branch('key'))
- */
 export type NextConfig<NodeIds extends string = string> =
   | NodeIds
   | NodeIds[]
   | Record<string, NodeIds | NodeIds[]>
 
-/**
- * Graph node configuration - references functions by RPC name
- */
 export interface GraphNodeConfig<NodeIds extends string = string> {
-  /** RPC function name */
   func: string
-  /** Input mapping callback - receives ref function, returns input object */
   input?: (ref: RefFn<NodeIds>) => Record<string, unknown>
-  /** Next nodes - string, array, or record for branching */
   next?: NextConfig<NodeIds>
-  /** Error routing - node(s) to execute on error */
   onError?: NodeIds | NodeIds[]
-  /** Maximum retry attempts allowed (excludes the initial attempt) */
   retries?: number
-  /** Delay between retries — milliseconds, duration string, or 'exponential' */
   retryDelay?: string | number
-  /**
-   * Free-text documentation for this node. Non-semantic: excluded from the
-   * graph topology hash, so editing a note never marks the workflow as changed.
-   */
   notes?: string
 }
 
-/**
- * Graph wire context - available to functions running in a workflow graph
- */
 export interface PikkuGraphWire {
-  /** Workflow run ID */
   runId: string
-  /** Graph name */
   graphName: string
-  /** Current node ID */
   nodeId: string
-  /**
-   * Select which branch to take for Record-based next config.
-   * Must be called if the node has a Record `next` configuration.
-   * @param key - The branch key to take (must match a key in the next Record)
-   */
   branch: (key: string) => void
-  /**
-   * Set a state variable value.
-   * @param name - Variable name
-   * @param value - Value to store
-   */
   setState: (name: string, value: unknown) => Promise<void>
-  /**
-   * Get the entire state object.
-   * @returns The state object with all variables
-   */
   getState: () => Promise<Record<string, unknown>>
 }
 
-/**
- * Internal mutable state for graph wire (used by runner to capture branch)
- */
 export interface GraphWireState {
   branchKey?: string
 }

package/src/wirings/workflow/index.ts

@@ -1,6 +1,3 @@
-/**
- * Workflow module exports
- */
 export {
   PikkuWorkflowService,
   WorkflowCancelledException,
@@ -18,7 +15,6 @@ export type {
 } from './pikku-workflow-service.js'
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js'
 
-// Time-travel: reconstruct run state at any point from durable history
 export {
   buildRunTimeline,
   reconstructStateAt,
@@ -32,11 +28,9 @@ export type {
   RunPhase,
 } from './run-timeline.js'
 
-// Internal registration functions (used by generated code)
 export { addWorkflow } from './dsl/workflow-runner.js'
 export { addFeature, resolveFeatureScenarios } from './feature.js'
 
-// Graph helpers (template, pikkuWorkflowGraph)
 export { template, type TemplateString } from './graph/template.js'
 export {
   pikkuWorkflowGraph,
@@ -44,7 +38,6 @@ export {
   type PikkuWorkflowGraphResult,
 } from './graph/wire-workflow-graph.js'
 
-// Queue worker functions (registered by codegen, executed at runtime)
 export {
   pikkuWorkflowWorkerFunc,
   pikkuWorkflowOrchestratorFunc,
@@ -56,7 +49,6 @@ export type {
   PikkuWorkflowSleeperInput,
 } from './workflow-queue-workers.js'
 
-// Re-export all types from workflow.types
 export type {
   WorkflowService,
   WorkflowQueueOptions,
@@ -84,12 +76,8 @@ export type {
   WorkflowsMeta,
   WorkflowRuntimeMeta,
   WorkflowsRuntimeMeta,
-  WorkflowStepInput,
-  WorkflowOrchestratorInput,
-  WorkflowSleeperInput,
 } from './workflow.types.js'
 
-// Re-export DSL types
 export type {
   WorkflowStepOptions,
   WorkflowWireDoRPC,
@@ -127,48 +115,33 @@ export type {
   PikkuScenarioWire,
 } from './workflow.types.js'
 
-/* ------------------------------------------------------------------ *
- * Scenarios — writing a step
- *
- * What a step file imports. Everything here is reached from inside a
- * `pikkuScenarioStep` body.
- * ------------------------------------------------------------------ */
-
-// The step's own wire, and the shape of what it was given
 export type {
   ScenarioStepPhase,
+  ScenarioStepKind,
   ScenarioStepOptions,
   PikkuScenarioStepWire,
   ScenarioEnvironment,
+  ScenarioSurface,
+  ScenarioSurfaceResolution,
 } from './scenario-step.types.js'
+export { SCENARIO_SURFACES } from './scenario-step.types.js'
+
+// Which of a step's bindings run: one for an action, every witness for a `then`
+export { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js'
 
-// Narrows the optional halves of the step wire, with a message that says what to do
 export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
 
-// Waits for the target to catch up, without every step writing the loop again
 export { pollUntil, type PollOptions } from './scenario-poll.js'
 
-// Persists cookies across a step's requests, the way a browser would
 export { createCookieJar } from './scenario-cookie-jar.js'
 export type { ScenarioCookieJar } from './scenario-cookie-jar.js'
 
-// What the transport answered — an actor's `invokeRaw`, or a route reached
-// directly — and the one way to POST JSON at a route and keep its status
 export type {
   ScenarioHttpResponse,
   ScenarioJsonRequest,
-} from '../../services/scenario-actors-service.js'
-export {
-  readScenarioHttpResponse,
-  postScenarioJson,
-} from '../../services/scenario-actors-service.js'
-
-/* ------------------------------------------------------------------ *
- * Scenarios — driving a browser
- *
- * How a step names an element, and what a driver package
- * (`@pikku/playwright`, or another) implements.
- * ------------------------------------------------------------------ */
+} from '../../services/personas-service.js'
+// The readers themselves live on `@pikku/core/persona`; workflow is a production
+// wiring and must not pull scenario runtime in behind it.
 
 export type {
   PikkuBrowserWire,
@@ -177,11 +150,4 @@ export type {
   ScenarioBrowserFailure,
 } from './scenario-step.types.js'
 
-/* ------------------------------------------------------------------ *
- * Scenarios — reporting a run
- *
- * Used by the CLI reporter and the console, so the two render the same
- * sentence for the same step. A step body needs none of it.
- * ------------------------------------------------------------------ */
-
 export { composeStepProse, renderStepTemplate } from './scenario-prose.js'