@pikku/core 0.12.72 → 0.12.74

package/src/wirings/workflow/run-timeline.test.ts

@@ -12,7 +12,6 @@ type HistoryEntry = StepState & { stepName: string }
 
 const T = (ms: number) => new Date(1_700_000_000_000 + ms)
 
-/** A succeeded step attempt with the standard lifecycle timestamps. */
 const ok = (
   stepName: string,
   base: number,
@@ -56,25 +55,19 @@ describe('buildRunTimeline', () => {
       tl.map((e) => e.type),
       ['pending', 'running', 'succeeded']
     )
-    // seq is monotonic from 0
     assert.deepEqual(
       tl.map((e) => e.seq),
       [0, 1, 2]
     )
-    // result rides only on the succeeded event
     assert.deepEqual(tl[2]!.result, { n: 1 })
     assert.equal(tl[0]!.result, undefined)
   })
 
   test('orders across steps by timestamp, lifecycle, then history index', () => {
-    // two steps; b created at the same instant begin succeeds
     const tl = buildRunTimeline([
       ok('begin', 0, { result: 1 }),
       ok('next', 2, { from: 'begin', result: 2 }),
     ])
-    // begin.pending(0) begin.running(1) begin.succeeded(2)==next.pending(2)
-    // → succeeded sorts before pending at the same instant (lifecycle 3 vs 0)?
-    // No: pending=0 < succeeded=3, so next.pending precedes begin.succeeded.
     const at2 = tl.filter((e) => e.at.getTime() === T(2).getTime())
     assert.deepEqual(
       at2.map((e) => `${e.stepName}:${e.type}`),
@@ -93,8 +86,6 @@ describe('buildRunTimeline', () => {
   })
 
   test('terminal event is driven by status, not lifecycle timestamps', () => {
-    // Kysely leaves succeededAt/runningAt null but the row's status + result
-    // are authoritative — the terminal event must still fire (off updatedAt).
     const noStamps = {
       stepId: 's-1',
       stepName: 'begin',
@@ -110,14 +101,17 @@ describe('buildRunTimeline', () => {
       ['pending', 'succeeded']
     )
     const succeeded = tl.find((e) => e.type === 'succeeded')!
-    assert.equal(succeeded.at.getTime(), T(5).getTime(), 'falls back to updatedAt')
+    assert.equal(
+      succeeded.at.getTime(),
+      T(5).getTime(),
+      'falls back to updatedAt'
+    )
     assert.deepEqual(succeeded.result, { ok: 1 })
     assert.deepEqual(reconstructFinalState(tl).results, { begin: { ok: 1 } })
   })
 })
 
 describe('reconstructStateAt', () => {
-  // begin → next → finish, each succeeding in order
   const history: HistoryEntry[] = [
     ok('begin', 0, { result: { step: 'begin' } }),
     ok('next', 10, { from: 'begin', result: { step: 'next' } }),
@@ -134,30 +128,25 @@ describe('reconstructStateAt', () => {
   })
 
   test('mid-run by seq: only steps up to that event exist', () => {
-    // fold through begin.succeeded (seq 2)
     const s = reconstructStateAt(tl, 2)
     assert.deepEqual(s.path, ['begin'])
     assert.equal(s.steps[0]!.status, 'succeeded')
     assert.deepEqual(s.results, { begin: { step: 'begin' } })
-    // next hasn't been created yet at this point
     assert.equal(s.phase, 'idle')
   })
 
   test('mid-run captures an in-flight step as running', () => {
-    // begin done (0,1,2), next created+running (3,4) but not yet succeeded
     const s = reconstructStateAt(tl, 4)
     assert.deepEqual(s.path, ['begin', 'next'])
     assert.equal(s.steps[1]!.stepName, 'next')
     assert.equal(s.steps[1]!.status, 'running')
     assert.equal(s.steps[1]!.fromStepName, 'begin')
     assert.equal(s.phase, 'running')
-    // next's result not yet available in the replay cache
     assert.deepEqual(s.results, { begin: { step: 'begin' } })
   })
 
   test('time-travel by Date folds every event at or before the instant', () => {
     const s = reconstructStateAt(tl, T(12))
-    // begin fully done (<=2), next created(10)+running(11) but succeeded at 12
     assert.deepEqual(s.path, ['begin', 'next'])
     assert.equal(s.steps[1]!.status, 'succeeded')
     assert.deepEqual(s.results, {
@@ -179,7 +168,6 @@ describe('reconstructStateAt', () => {
 })
 
 describe('reconstructStateAt — retries', () => {
-  // attempt 1 fails, attempt 2 (created later) succeeds
   const history: HistoryEntry[] = [
     failed('flaky', 0, { message: 'first try' }),
     ok('flaky', 10, { result: { ok: true }, attempt: 2 }),
@@ -187,7 +175,7 @@ describe('reconstructStateAt — retries', () => {
   const tl = buildRunTimeline(history)
 
   test('between attempts the step is failed', () => {
-    const s = reconstructStateAt(tl, T(2)) // through failedAt of attempt 1
+    const s = reconstructStateAt(tl, T(2))
     assert.equal(s.steps[0]!.status, 'failed')
     assert.equal(s.steps[0]!.error?.message, 'first try')
     assert.equal(s.phase, 'failed')
@@ -195,7 +183,7 @@ describe('reconstructStateAt — retries', () => {
   })
 
   test("the retry's created event reopens the step and clears the error", () => {
-    const s = reconstructStateAt(tl, T(10)) // attempt-2 pending
+    const s = reconstructStateAt(tl, T(10))
     assert.equal(s.steps[0]!.status, 'pending')
     assert.equal(s.steps[0]!.error, undefined)
     assert.equal(s.steps[0]!.attemptCount, 2)

package/src/wirings/workflow/run-timeline.ts

@@ -1,41 +1,17 @@
 import type { SerializedError } from '../../types/core.types.js'
 import type { StepState, StepStatus } from './workflow.types.js'
 
-/**
- * Time-travel over a workflow run.
- *
- * A run's durable history (`getRunHistory`) is one row per step *attempt*, each
- * carrying lifecycle timestamps (created/scheduled/running/succeeded/failed).
- * `buildRunTimeline` explodes those rows into a flat, chronologically-ordered
- * event stream, and `reconstructStateAt` folds the stream up to any point to
- * recover what the run "knew" then — the same step cache a replay would hold:
- * per-step status, accumulated results, and the walked path.
- *
- * These are pure functions over history — no IO — so they're trivially testable
- * and transport-independent (the same fold works for Redis/Kysely/in-memory).
- */
-
-/** A single observable transition of one step attempt. */
 export interface RunTimelineEvent {
-  /** Monotonic 0-based position in the timeline. */
   seq: number
-  /** When it happened. */
   at: Date
-  /** The step's new status at this event (matches StepStatus lifecycle). */
   type: Extract<
     StepStatus,
     'pending' | 'scheduled' | 'running' | 'succeeded' | 'failed'
   >
-  /** Physical step name (includes revisit ordinal, e.g. `attempt#2`). */
   stepName: string
-  /** Which attempt this event belongs to (1-based). */
   attemptCount: number
-  /** Predecessor that scheduled this step — only on the `pending` (created)
-   *  event; undefined for entry steps. Reconstructs the walked edge. */
   fromStepName?: string
-  /** Result snapshot — only on `succeeded`. */
   result?: unknown
-  /** Error snapshot — only on `failed`. */
   error?: SerializedError
 }
 
@@ -43,7 +19,6 @@ export type RunTimeline = RunTimelineEvent[]
 
 type HistoryEntry = StepState & { stepName: string }
 
-/** Lifecycle tiebreak for events that share a timestamp. */
 const LIFECYCLE_ORDER: Record<RunTimelineEvent['type'], number> = {
   pending: 0,
   scheduled: 1,
@@ -52,12 +27,6 @@ const LIFECYCLE_ORDER: Record<RunTimelineEvent['type'], number> = {
   failed: 3,
 }
 
-/**
- * Build the ordered event stream for a run from its raw history.
- *
- * History is expected oldest-first but is sorted defensively by (timestamp,
- * lifecycle, original index) so simultaneous timestamps stay deterministic.
- */
 export function buildRunTimeline(history: HistoryEntry[]): RunTimeline {
   const raw: Array<Omit<RunTimelineEvent, 'seq'> & { order: number }> = []
 
@@ -67,24 +36,18 @@ export function buildRunTimeline(history: HistoryEntry[]): RunTimeline {
       attemptCount: entry.attemptCount,
       order,
     }
-    // The created event always exists; it carries provenance.
     raw.push({
       ...base,
       at: entry.createdAt,
       type: 'pending',
       fromStepName: entry.fromStepName,
     })
-    // Intermediate events are optional enrichment — emit only if the backend
-    // recorded their timestamp.
     if (entry.scheduledAt) {
       raw.push({ ...base, at: entry.scheduledAt, type: 'scheduled' })
     }
     if (entry.runningAt) {
       raw.push({ ...base, at: entry.runningAt, type: 'running' })
     }
-    // The terminal event is driven by the row's authoritative status (the
-    // lifecycle timestamps aren't populated by every backend — Kysely leaves
-    // them null), falling back to updatedAt when the specific stamp is absent.
     if (entry.status === 'succeeded') {
       raw.push({
         ...base,
@@ -115,7 +78,6 @@ export function buildRunTimeline(history: HistoryEntry[]): RunTimeline {
   return raw.map(({ order: _order, ...event }, seq) => ({ ...event, seq }))
 }
 
-/** A step's reconstructed state at a point in the timeline. */
 export interface ReconstructedStep {
   stepName: string
   status: StepStatus
@@ -125,24 +87,15 @@ export interface ReconstructedStep {
   error?: SerializedError
 }
 
-/** Coarse run phase derived purely from step states (not the run's output). */
 export type RunPhase = 'pending' | 'running' | 'failed' | 'idle'
 
-/** The whole run's reconstructed state at a point in the timeline. */
 export interface ReconstructedRunState {
   /** seq of the last applied event, or -1 if the point precedes all events. */
   seq: number
-  /** Wall-clock time of the last applied event. */
   at?: Date
-  /** Per-step latest state, in first-seen (walked) order. */
   steps: ReconstructedStep[]
-  /** Outputs available to downstream steps — the replay step cache at this
-   *  point (succeeded steps only). */
   results: Record<string, unknown>
-  /** Step names in the order they were first created — the walked path. */
   path: string[]
-  /** Derived phase: `running` if any step is in-flight, else `failed` if a step
-   *  is failed with no in-flight work, else `idle` (between transitions). */
   phase: RunPhase
 }
 
@@ -152,13 +105,6 @@ const IN_FLIGHT: ReadonlySet<StepStatus> = new Set([
   'running',
 ])
 
-/**
- * Fold the timeline up to `at` and return the run's state at that point.
- *
- * `at` is either a seq index (inclusive — apply events `0..at`) or a `Date`
- * (inclusive — apply every event at or before that instant). A point before the
- * first event yields the empty initial state.
- */
 export function reconstructStateAt(
   timeline: RunTimeline,
   at: number | Date
@@ -194,7 +140,6 @@ export function reconstructStateAt(
     if (event.fromStepName !== undefined) {
       step.fromStepName = event.fromStepName
     }
-    // A retry's created event reopens the step — drop the prior outcome.
     if (event.type === 'pending') {
       delete step.result
       delete step.error
@@ -226,7 +171,6 @@ export function reconstructStateAt(
   }
 }
 
-/** Reconstruct the final state (fold the whole timeline). */
 export function reconstructFinalState(
   timeline: RunTimeline
 ): ReconstructedRunState {

package/src/wirings/workflow/scenario-cookie-jar.test.ts

@@ -4,7 +4,6 @@ import { createServer, type Server } from 'node:http'
 
 import { createCookieJar } from './scenario-cookie-jar.js'
 
-// Minimal target: hands out cookies, and reports back what it was sent.
 const startTarget = async () => {
   let issued = 0
   const server: Server = createServer((req, res) => {

package/src/wirings/workflow/scenario-cookie-jar.ts

@@ -1,32 +1,9 @@
-/** A session held the way a browser holds one, for code driving a real target. */
 export interface ScenarioCookieJar {
-  /** `fetch`, but it sends what the target has set and keeps what it sets. */
   fetch: typeof fetch
-  /** Forgets the session — what an actor does before signing in again. */
   clear(): void
-  /**
-   * Whether the target has set anything yet. This is a fact about the jar, not
-   * about the session: a target that sets a CSRF or locale cookie before anyone
-   * signs in fills the jar without establishing one. Whoever needs to know
-   * whether a sign-in happened has to track the sign-in.
-   */
   readonly empty: boolean
 }
 
-/**
- * A `fetch` that remembers cookies.
- *
- * A browser persists the session cookie on its own; anything driving a target
- * from this process has to. Every response is read, not just the sign-in, so a
- * cookie the target rotates mid-session is followed rather than dropped.
- *
- * The jar is a closure local, so two jars never share a session — which is what
- * lets one scenario sign in as several people without one of them inheriting
- * the other's session.
- *
- * It also stamps `Origin`, because Better Auth rejects a state-changing POST
- * whose Origin does not match its baseURL.
- */
 export const createCookieJar = (apiUrl: string): ScenarioCookieJar => {
   const jar = new Map<string, string>()
   const origin = new URL(apiUrl).origin
@@ -46,8 +23,6 @@ export const createCookieJar = (apiUrl: string): ScenarioCookieJar => {
         if (separator > 0) {
           const name = pair!.slice(0, separator)
           const value = pair!.slice(separator + 1)
-          // An empty value is how a target deletes a cookie — drop the name
-          // rather than holding a cookie whose value says it is gone.
           if (value) {
             jar.set(name, value)
           } else {

package/src/wirings/workflow/scenario-expectations.test.ts

@@ -4,14 +4,14 @@ import assert from 'node:assert/strict'
 import { createScenarioRunner } from './pikku-scenario-service.js'
 import type { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
-import type { ScenarioActor } from '../../services/scenario-actors-service.js'
+import type { ScenarioPersona } from '../../services/personas-service.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 
 const fakeActor = (
   name: string,
   handler: (rpcName: string, data: unknown) => Promise<unknown>
-): ScenarioActor => ({
+): ScenarioPersona => ({
   name,
   email: `${name}@actors.local`,
   invoke: async (rpcName: string, data: unknown) => handler(rpcName, data),
@@ -33,11 +33,6 @@ const setup = async (ws: InMemoryWorkflowService) => {
   return runId
 }
 
-/**
- * The scenario wire, wrapped rather than returned directly: it carries a
- * `then` — the Gherkin phase, not a promise — so awaiting one is awaiting a
- * thenable, and the runtime calls it as a step.
- */
 const scenarioWire = async (rpcService: any = {}): Promise<{ wire: any }> => {
   const { workflowService } = createScenarioRunner()
   const ws = workflowService as InMemoryWorkflowService

package/src/wirings/workflow/scenario-hooks.test.ts

@@ -4,7 +4,7 @@ import assert from 'node:assert/strict'
 import { createScenarioRunner } from './pikku-scenario-service.js'
 import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 import { addWorkflow } from './dsl/workflow-runner.js'
-import type { ScenarioActors } from '../../services/scenario-actors-service.js'
+import type { ScenarioPersonas } from '../../services/personas-service.js'
 
 const noopLogger = {
   error() {},
@@ -20,18 +20,13 @@ const actors = {
     invoke: async () => ({}),
     invokeRaw: async () => ({ status: 200, ok: true, body: {} }),
   },
-} as unknown as ScenarioActors
+} as unknown as ScenarioPersonas
 
 type ScenarioHooks = {
   before?: (services: any, data: any, wire: any) => Promise<void> | void
   after?: (services: any, data: any, wire: any) => Promise<void> | void
 }
 
-/**
- * Registers a scenario (or, with `source: 'dsl'`, a plain workflow) and runs it
- * inline, returning the error it threw rather than propagating — every hook
- * assertion here is about what ran, not about how the caller saw it.
- */
 const runScenario = async (
   name: string,
   config: ScenarioHooks & { func: (...args: any[]) => any },

package/src/wirings/workflow/scenario-poll.test.ts

@@ -49,8 +49,6 @@ describe('pollUntil', () => {
   })
 
   test('treats a falsy-but-defined answer as an answer', async () => {
-    // `false` is what a "did it happen?" probe returns, and it is a result —
-    // only `undefined` means "not yet".
     let attempts = 0
     const found = await pollUntil(
       () => {

package/src/wirings/workflow/scenario-poll.ts

@@ -1,23 +1,8 @@
-/** How long to keep trying, and how long to wait between tries. */
 export interface PollOptions {
-  /** Total time to keep attempting before giving up. Default 15s. */
   timeoutMs?: number
-  /** Gap between attempts. Default 250ms. */
   intervalMs?: number
 }
 
-/**
- * Attempt something until it answers, or the deadline passes.
- *
- * `undefined` means "not yet" and nothing else — `false`, `0` and `''` are all
- * answers, because a probe asking whether something happened reports `false`
- * when it did not. Answering `undefined` at the deadline rather than throwing
- * leaves the error to the caller, who is the only one who knows what was being
- * waited for.
- *
- * A step that polls its target — a delivery reaching a terminal status, a run
- * finishing — reaches for this rather than writing the deadline loop again.
- */
 export const pollUntil = async <T>(
   attempt: () => Promise<T | undefined> | T | undefined,
   { timeoutMs = 15_000, intervalMs = 250 }: PollOptions = {}

package/src/wirings/workflow/scenario-prose.ts

@@ -1,23 +1,5 @@
 import type { ScenarioStepPhase } from './scenario-step.types.js'
 
-/**
- * Renders the English sentence a reporter shows for a scenario step.
- *
- * This is the inversion of cucumber: rather than parsing English into a call,
- * we render English out of a typed call, so the readable report survives
- * without a regex registry paying for it.
- *
- * Lives in core so the CLI reporter and the console render identically.
- */
-/**
- * Fill a step's `template` from the input that step was actually called with,
- * so the reported sentence names the values under test — "sees @pikku/addon-todos"
- * rather than "sees an addon in the gallery" repeated three times.
- *
- * A placeholder with no recorded value renders as nothing and the surrounding
- * whitespace collapses, so an optional input that was omitted reads as a shorter
- * sentence rather than a literal `{state}` leaking into the report.
- */
 export const renderStepTemplate = (
   template: string,
   input: unknown
@@ -50,19 +32,9 @@ export const composeStepProse = ({
 }: {
   phase: ScenarioStepPhase
   description: string
-  /**
-   * The prose this step renders, with `{placeholders}` filled from `input`.
-   * Unlike `description`, which documents what the step does, this is what a
-   * reader of the report sees. Falls back to `description` when absent.
-   */
   template?: string
-  /** The input this step was called with, as recorded on the run. */
   input?: unknown
   actor?: string
-  /**
-   * Pad the keyword to this width so a ladder of steps lines its sentences up
-   * under each other. Omit for inline prose.
-   */
   keywordWidth?: number
 }): string => {
   const keyword = phase === 'step' ? '' : capitalise(phase)

package/src/wirings/workflow/scenario-service.test.ts

@@ -10,23 +10,16 @@ import { pikkuState, resetPikkuState } from '../../pikku-state.js'
 
 const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
 
-/**
- * Members that only a scenario run reaches. None of them may live on the class
- * a production app instantiates: a bundler removes unused *modules*, never
- * unused class members, so anything declared here ships in every server built
- * on Pikku whether or not the app has a single scenario.
- */
 const SCENARIO_MEMBERS = [
   'scenarioStep',
   'runScenarioHook',
-  'resolveScenarioActors',
+  'resolvePersonas',
   'setScenarioBrowserProvider',
   'getScenarioBrowserProvider',
   'setScenarioEnvironment',
   'getScenarioEnvironment',
 ]
 
-/** Wire members declared by `PikkuScenarioWire` and absent from `PikkuWorkflowWire`. */
 const SCENARIO_WIRE_MEMBERS = [
   'step',
   'given',
@@ -99,7 +92,7 @@ describe('the production workflow service carries no scenario surface', () => {
       'utf8'
     )
     assert.ok(
-      !source.includes('http-scenario-actors'),
+      !source.includes('http-personas'),
       'PikkuWorkflowService must not reference the HTTP actor client — it pulls the AI persona loop into every bundle'
     )
   })

package/src/wirings/workflow/scenario-step-guards.ts

@@ -3,14 +3,6 @@ import type {
   ScenarioEnvironment,
 } from './scenario-step.types.js'
 
-/**
- * The actor this step was called with, or a loud error naming the step.
- *
- * A step that talks to the target app needs an identity, but `actor` is
- * optional on the wire because a pure assertion step needs none. This is the
- * one place that narrowing happens, so every step file stops writing its own
- * `actorOf(...)` guard.
- */
 export const requireActor = <TActor>(
   scenarioStep: PikkuScenarioStepWire<TActor> | undefined
 ): TActor => {
@@ -24,11 +16,6 @@ export const requireActor = <TActor>(
   return actor
 }
 
-/**
- * The environment this run targets, or a loud error naming the step. A run
- * started outside `pikku scenario run` only carries one when the server has
- * `API_URL` configured.
- */
 export const requireScenarioEnv = (
   scenarioStep: PikkuScenarioStepWire<unknown> | undefined
 ): ScenarioEnvironment => {
@@ -36,7 +23,7 @@ export const requireScenarioEnv = (
   if (!env) {
     throw new Error(
       `[scenario] step '${scenarioStep?.name ?? 'unknown'}' needs the target environment, but this run carries none. ` +
-        `Run it through 'pikku scenario run <environment>' with scenarios.environments.<environment> declared in pikku.config.json.`
+        `Run it through 'pikku scenario run <environment>' with environments.<environment> declared in pikku.config.json.`
     )
   }
   return env