@pikku/core 0.12.94 → 0.12.96

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

@@ -192,8 +192,11 @@ describe('pikku-workflow-service run-level inline', () => {
 
 describe('pikku-workflow-service per-function step dispatch', () => {
   class TestWorkflowService extends InMemoryWorkflowService {
-    public callDispatchStep(rpcName: string) {
-      return this.dispatchStep('run-1', 'step-1', rpcName, {})
+    public callDispatchStep(rpcName: string, runId = 'run-1') {
+      return this.dispatchStep(runId, 'step-1', rpcName, {})
+    }
+    public markInline(runId: string) {
+      this.registerInlineRun(runId)
     }
   }
 
@@ -249,6 +252,72 @@ describe('pikku-workflow-service per-function step dispatch', () => {
     cleanup('queuedStep')
   })
 
+  const setupWorkflow = (name: string) => {
+    pikkuState(null, 'workflows', 'meta')[name] = {
+      name,
+      pikkuFuncId: name,
+      graphHash: 'hash',
+    } as any
+  }
+
+  const cleanupWorkflow = (name: string) => {
+    delete pikkuState(null, 'workflows', 'meta')[name]
+  }
+
+  test('a step naming a workflow queues even though it is unmarked', async () => {
+    const ws = new TestWorkflowService()
+    let queued = false
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: { error() {}, info() {}, warn() {}, debug() {} },
+      queueService: {
+        add: async () => {
+          queued = true
+        },
+      },
+    } as any)
+
+    setupWorkflow('childWorkflowStep')
+    const dispatched = await ws.callDispatchStep('childWorkflowStep')
+    assert.equal(dispatched, true, 'a child workflow should dispatch')
+    assert.equal(queued, true, 'a child workflow should queue')
+    cleanupWorkflow('childWorkflowStep')
+  })
+
+  test('a step naming a workflow stays inline when the parent run is inline', async () => {
+    const ws = new TestWorkflowService()
+    let queued = false
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: { error() {}, info() {}, warn() {}, debug() {} },
+      queueService: {
+        add: async () => {
+          queued = true
+        },
+      },
+    } as any)
+
+    setupWorkflow('childOfInlineParent')
+    ws.markInline('inline-parent')
+    const dispatched = await ws.callDispatchStep(
+      'childOfInlineParent',
+      'inline-parent'
+    )
+    assert.equal(dispatched, false, 'an inline parent keeps its child inline')
+    assert.equal(queued, false, 'an inline parent queues nothing')
+    cleanupWorkflow('childOfInlineParent')
+  })
+
+  test('a step naming a workflow stays inline when there is no queueService', async () => {
+    const ws = new TestWorkflowService()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: { error() {}, info() {}, warn() {}, debug() {} },
+    } as any)
+
+    setupWorkflow('childWorkflowNoQueue')
+    const dispatched = await ws.callDispatchStep('childWorkflowNoQueue')
+    assert.equal(dispatched, false, 'no queue leaves the child inline')
+    cleanupWorkflow('childWorkflowNoQueue')
+  })
+
   test('workflowQueued: true step throws when no queueService is configured', async () => {
     const ws = new TestWorkflowService()
     pikkuState(null, 'package', 'singletonServices', {

package/src/wirings/workflow/pikku-workflow-service.ts

@@ -83,6 +83,7 @@ import {
   jobGroupFor,
   orchestratorQueueName,
   resolveWorkflowConfig,
+  stepDispatchTarget,
   stepJobOptions,
   stepWorkerQueueName,
 } from './workflow-queue-routing.js'
@@ -760,19 +761,12 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     stepOptions?: WorkflowStepOptions,
     fromStepName?: string
   ): Promise<boolean> {
-    const functionsMeta = pikkuState(null, 'function', 'meta')
-    const rpcFuncId = pikkuState(null, 'rpc', 'meta')[rpcName]
-    const rpcMeta =
-      typeof rpcFuncId === 'string' ? functionsMeta[rpcFuncId] : undefined
-    const forceQueue = rpcMeta?.workflowQueued === true
-    if (!forceQueue) {
+    const target = await stepDispatchTarget(rpcName, stepName, () =>
+      this.isInline(runId)
+    )
+    if (target === 'inline') {
       return false
     }
-    if (!getSingletonServices()?.queueService) {
-      throw new Error(
-        `Workflow step '${stepName}' (function '${rpcName}') is marked 'workflowQueued: true' but no queue service is configured.`
-      )
-    }
     try {
       await getSingletonServices()!.queueService!.add(
         this.getStepWorkerQueueName(rpcName),

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

@@ -63,7 +63,7 @@ describe('composeStepProse', () => {
         input: { packageName: '@pikku/addon-todos' },
         actor: 'admin',
       }),
-      'Then the admin sees @pikku/addon-todos'
+      'Then admin sees @pikku/addon-todos'
     )
   })
 
@@ -75,7 +75,121 @@ describe('composeStepProse', () => {
         input: { packageName: '@pikku/addon-todos' },
         actor: 'admin',
       }),
-      'Then the admin sees an addon in the gallery'
+      'Then admin sees an addon in the gallery'
+    )
+  })
+})
+
+describe('composeStepProse with an actor role', () => {
+  test('the role renders as an apposition after the actor', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'given',
+        description: 'signs in',
+        actor: 'yasser',
+        actorRole: 'founder',
+      }),
+      'Given yasser (the founder) signs in'
+    )
+  })
+
+  test('no role renders exactly as it did before', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'given',
+        description: 'signs in',
+        actor: 'yasser',
+      }),
+      'Given yasser signs in'
+    )
+  })
+
+  test('a role without an actor has nothing to qualify, so it is dropped', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'then',
+        description: 'the receipt totals 4.50',
+        actorRole: 'founder',
+      }),
+      'Then the receipt totals 4.50'
+    )
+  })
+
+  test('the role sits inside the padded sentence, not the keyword column', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'when',
+        description: 'opens /app',
+        actor: 'nadia',
+        actorRole: 'head of ops',
+        keywordWidth: 5,
+      }),
+      'When  nadia (the head of ops) opens /app'
+    )
+  })
+})
+
+describe('composeStepProse continuations', () => {
+  test('a repeated phase reads as And', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'given',
+        description: 'is invited',
+        actor: 'nadia',
+        continuesPhase: true,
+      }),
+      'And nadia is invited'
+    )
+  })
+
+  test('the same actor continuing drops the repeated subject', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'when',
+        description: 'sees the audit log',
+        actor: 'yasser',
+        continuesPhase: true,
+        continuesActor: true,
+      }),
+      'And sees the audit log'
+    )
+  })
+
+  test('a new actor keeps their name even under And', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'given',
+        description: 'is invited',
+        actor: 'nadia',
+        continuesPhase: true,
+        continuesActor: false,
+      }),
+      'And nadia is invited'
+    )
+  })
+
+  test('the same actor across a phase change keeps the subject', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'when',
+        description: 'opens the dashboard',
+        actor: 'yasser',
+        continuesActor: true,
+      }),
+      'When yasser opens the dashboard'
+    )
+  })
+
+  test('an introduction is never dropped by a continuation', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'given',
+        description: 'is invited',
+        actor: 'nadia',
+        actorRole: 'reviewer',
+        continuesPhase: true,
+      }),
+      'And nadia (the reviewer) is invited'
     )
   })
 })
@@ -88,7 +202,7 @@ describe('composeStepProse basics', () => {
         description: 'buys an apple',
         actor: 'shopper',
       }),
-      'Given the shopper buys an apple'
+      'Given shopper buys an apple'
     )
     assert.equal(
       composeStepProse({
@@ -96,7 +210,18 @@ describe('composeStepProse basics', () => {
         description: 'sees a receipt',
         actor: 'shopper',
       }),
-      'Then the shopper sees a receipt'
+      'Then shopper sees a receipt'
+    )
+  })
+
+  test('a persona named after a person reads as that person', () => {
+    assert.equal(
+      composeStepProse({
+        phase: 'when',
+        description: 'opens /app',
+        actor: 'nadia',
+      }),
+      'When nadia opens /app'
     )
   })
 
@@ -117,7 +242,7 @@ describe('composeStepProse basics', () => {
         description: 'refreshes the dashboard',
         actor: 'admin',
       }),
-      'When the admin refreshes the dashboard'
+      'When admin refreshes the dashboard'
     )
   })
 
@@ -133,11 +258,11 @@ describe('composeStepProse basics', () => {
     )
 
     assert.deepEqual(rendered, [
-      'Given the shopper buys an apple',
-      'When  the shopper checks out',
-      'Then  the shopper sees a receipt',
+      'Given shopper buys an apple',
+      'When  shopper checks out',
+      'Then  shopper sees a receipt',
     ])
-    const columns = new Set(rendered.map((line) => line.indexOf('the shopper')))
+    const columns = new Set(rendered.map((line) => line.indexOf('shopper')))
     assert.equal(columns.size, 1, 'every sentence starts in the same column')
   })
 

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

@@ -28,6 +28,9 @@ export const composeStepProse = ({
   template,
   input,
   actor,
+  actorRole,
+  continuesPhase,
+  continuesActor,
   keywordWidth,
 }: {
   phase: ScenarioStepPhase
@@ -35,10 +38,37 @@ export const composeStepProse = ({
   template?: string
   input?: unknown
   actor?: string
+  /**
+   * What this actor is, rendered as an apposition after their key — "yasser
+   * (the founder)". Only pass it where the actor has not been named yet: an
+   * ordinary run repeats one actor for a dozen steps, and repeating the role
+   * with them turns the one piece of context into the noise around it.
+   */
+  actorRole?: string
+  /**
+   * This step repeats the phase of the one before it, so it reads as `And`
+   * rather than saying `Given` three times — the same thing Gherkin does.
+   */
+  continuesPhase?: boolean
+  /**
+   * The step before this one had the same actor. Combined with `continuesPhase`
+   * the subject is dropped, because English drops a repeated subject in a
+   * compound predicate: "yasser opens the dashboard / and sees the audit log".
+   *
+   * It takes both. Dropping the subject across a phase change gives "When opens
+   * the dashboard", and a pronoun instead of a name would give "they sees",
+   * since step templates are authored in the third person singular.
+   */
+  continuesActor?: boolean
   keywordWidth?: number
 }): string => {
-  const keyword = capitalise(phase)
-  const subject = actor ? `the ${actor}` : ''
+  const keyword = capitalise(continuesPhase ? 'and' : phase)
+  // The actor key is the subject verbatim, with no article in front of it.
+  // "the ${actor}" only reads as English when the key happens to be a role
+  // noun — it turns a persona named after a person into "the nadia", which
+  // is the reporter quietly imposing a naming convention on the author.
+  const subject =
+    continuesPhase && continuesActor ? '' : composeSubject(actor, actorRole)
   const rendered = template ? renderStepTemplate(template, input) : description
   const sentence = [subject, rendered].filter(Boolean).join(' ')
   if (keywordWidth === undefined) {
@@ -47,5 +77,10 @@ export const composeStepProse = ({
   return `${keyword.padEnd(keywordWidth)} ${sentence}`
 }
 
+const composeSubject = (actor?: string, actorRole?: string): string => {
+  if (!actor) return ''
+  return actorRole ? `${actor} (the ${actorRole})` : actor
+}
+
 const capitalise = (value: string) =>
   value.charAt(0).toUpperCase() + value.slice(1)

package/src/wirings/workflow/scenario-run.types.ts

@@ -38,6 +38,13 @@ export interface ScenarioArtifact {
 /** One step of a run, already joined to the prose that declared it. */
 export interface ScenarioStepRow {
   sentence: string
+  /**
+   * The same sentence with the actor's role in it — "yasser (the founder)
+   * signs in". Set only on the step that first names each actor, and only
+   * when a persona declares a job title or a role, so a reader who wants the
+   * context picks this and one who wants the bare run picks `sentence`.
+   */
+  sentenceWithRole?: string
   status: string
   durationMs?: number
   error?: string

package/src/wirings/workflow/workflow-child-run-session.test.ts

@@ -87,3 +87,82 @@ describe('a child workflow inherits the parent run wire pikkuUserId', () => {
     assert.ok(wire.parentRunId, 'the child must name the run that started it')
   })
 })
+
+/**
+ * Queuing a child workflow is only worth anything if the parent comes back with
+ * the child's output. The routing tests assert which way a step goes; this
+ * asserts what the parent is left holding once the child it queued has ended.
+ */
+describe('a queued child workflow hands its output back to the parent step', () => {
+  const CHILD_OUTPUT = { invoiceId: 'inv-42' }
+
+  const setup = async () => {
+    resetPikkuState()
+    pikkuState(null, 'package', 'singletonServices', {
+      logger: silentLogger,
+      queueService: { add: async () => {} },
+    } as any)
+    registerChildWorkflow('childFlow')
+    pikkuState(null, 'function', 'functions').set('childFlow', {
+      func: async () => CHILD_OUTPUT,
+    } as any)
+
+    const ws = new InMemoryWorkflowService()
+    const parentRunId = await ws.createRun('parentFlow', {}, false, '', {
+      type: 'test',
+    })
+    const step = await ws.insertStepState(
+      parentRunId,
+      'callChild',
+      'childFlow',
+      {}
+    )
+    const stepId = (step as any).stepId ?? (step as any).id
+    assert.ok(stepId, 'the parent step must have an id to hand back to')
+    return { ws, parentRunId, stepId }
+  }
+
+  const childRunIdOf = async (ws: InMemoryWorkflowService) => {
+    for (const id of (ws as any).runs?.keys?.() ?? []) {
+      const run = await ws.getRun(id)
+      if (run?.workflow === 'childFlow') return run.id
+    }
+    throw new Error('no child run was started')
+  }
+
+  test('the parent step carries the child output once the child completes', async () => {
+    const { ws, parentRunId, stepId } = await setup()
+
+    // The step worker that picked the queued job off runs this; it starts the
+    // child and unwinds the parent rather than waiting on it.
+    await (ws as any).executeWorkflowStepInner(
+      parentRunId,
+      'callChild',
+      'childFlow',
+      {},
+      {}
+    )
+
+    const childRunId = await childRunIdOf(ws)
+    const childRun = await ws.getRun(childRunId)
+    assert.equal(
+      childRun?.wire?.parentStepId,
+      stepId,
+      'the child must name the step it has to hand its output back to'
+    )
+
+    await ws.updateRunStatus(childRunId, 'completed', CHILD_OUTPUT)
+    await (ws as any).onChildWorkflowCompleted(
+      await ws.getRun(childRunId),
+      CHILD_OUTPUT
+    )
+
+    const steps = await ws.getRunSteps(parentRunId)
+    const callChild = steps.find((s: any) => s.stepName === 'callChild')
+    assert.deepEqual(
+      callChild?.result,
+      CHILD_OUTPUT,
+      'the parent step must end up holding what the child returned'
+    )
+  })
+})

package/src/wirings/workflow/workflow-queue-routing.ts

@@ -64,6 +64,50 @@ export const stepWorkerQueueName = (
     resolveWorkflowConfig().stepWorkerQueueName
   )
 
+/**
+ * How a step reaches its worker: on the queue, or here in the orchestrator.
+ *
+ * A step naming a workflow queues whenever a queue exists, even unmarked. Run
+ * here, it holds the parent's run lock — and its lock connection — until the
+ * child ends, and marks the child inline so the child's own `sleep` degrades
+ * from a suspension into a real in-process wait. Workflows cannot opt in
+ * through `workflowQueued`: that flag is read off `rpc` meta, and `addWorkflow`
+ * never registers there.
+ *
+ * Throws only for a step that asked for the queue by name and has none, which
+ * is a deployment missing a service rather than a routing choice.
+ *
+ * `parentIsInline` is a thunk because resolving it can read the run store, and
+ * every step dispatch would pay for that — only a step that names a workflow
+ * and has a queue to reach ever asks.
+ */
+export const stepDispatchTarget = async (
+  rpcName: string,
+  stepName: string,
+  parentIsInline: () => Promise<boolean>
+): Promise<'queue' | 'inline'> => {
+  const rpcFuncId = pikkuState(null, 'rpc', 'meta')[rpcName]
+  const rpcMeta =
+    typeof rpcFuncId === 'string'
+      ? pikkuState(null, 'function', 'meta')[rpcFuncId]
+      : undefined
+  const hasQueue = getSingletonServices()?.queueService !== undefined
+  if (rpcMeta?.workflowQueued === true) {
+    if (!hasQueue) {
+      throw new Error(
+        `Workflow step '${stepName}' (function '${rpcName}') is marked 'workflowQueued: true' but no queue service is configured.`
+      )
+    }
+    return 'queue'
+  }
+  const isWorkflow =
+    pikkuState(null, 'workflows', 'meta')[rpcName] !== undefined
+  if (!isWorkflow || !hasQueue) {
+    return 'inline'
+  }
+  return (await parentIsInline()) ? 'inline' : 'queue'
+}
+
 export const jobGroupFor = (
   strategy: WorkflowQueueStrategy,
   id?: string