@pikku/core 0.12.78 → 0.12.80

package/src/wirings/virtual-user/run-virtual-user.test.ts

@@ -41,7 +41,11 @@ const CATALOGUE: ApiCatalogueEntry[] = [
 ]
 
 const INTENTS: IntentSource[] = [
-  { id: 'onboard', title: 'set up your first project', steps: ['sign in', 'make a project'] },
+  {
+    id: 'onboard',
+    title: 'set up your first project',
+    steps: ['sign in', 'make a project'],
+  },
 ]
 
 const PERSONA = {
@@ -84,10 +88,7 @@ const scripted = (
   return { llm, turns: () => turn }
 }
 
-const respond = <T>(
-  status: number,
-  body: T
-): ScenarioHttpResponse<T> => ({
+const respond = <T>(status: number, body: T): ScenarioHttpResponse<T> => ({
   status,
   ok: status >= 200 && status < 300,
   body,
@@ -126,7 +127,12 @@ describe('running a virtual user', () => {
       { kind: 'complete', summary: 'done' },
     ])
 
-    const result = await runVirtualUser({ ...base, target, llm, budget: { steps: 3 } })
+    const result = await runVirtualUser({
+      ...base,
+      target,
+      llm,
+      budget: { steps: 3 },
+    })
 
     // The first attempt cost a step and bought the schema; only the second
     // reached the server.
@@ -355,7 +361,9 @@ describe('what a virtual user reports', () => {
   })
 
   test('an app-specific oracle can add what the engine cannot know', async () => {
-    const target = recordingTarget(() => respond(200, { orgId: 'someone-else' }))
+    const target = recordingTarget(() =>
+      respond(200, { orgId: 'someone-else' })
+    )
     const { llm } = scripted(walkTo('listProjects'))
 
     const result = await runVirtualUser({
@@ -595,8 +603,9 @@ describe('goals and persona', () => {
   test('goals in the user’s own words become intents alongside the derived ones', async () => {
     const seen: string[] = []
     const target = recordingTarget(() => respond(200, {}))
-    const { llm } = scripted([{ kind: 'complete' }, { kind: 'complete' }], (_i, m) =>
-      seen.push(...m)
+    const { llm } = scripted(
+      [{ kind: 'complete' }, { kind: 'complete' }],
+      (_i, m) => seen.push(...m)
     )
 
     const result = await runVirtualUser({

package/src/wirings/virtual-user/run-virtual-user.ts

@@ -143,8 +143,12 @@ const msg = (role: AIMessage['role'], content: string): AIMessage => ({
 })
 
 /** Read a structured result, falling back to parsing JSON out of the text. */
-const readObject = <T>(result: { object?: unknown; text?: string }): T | null => {
-  if (result.object && typeof result.object === 'object') return result.object as T
+const readObject = <T>(result: {
+  object?: unknown
+  text?: string
+}): T | null => {
+  if (result.object && typeof result.object === 'object')
+    return result.object as T
   if (result.text) {
     try {
       return JSON.parse(result.text) as T
@@ -201,7 +205,11 @@ export const rememberIds = (
     return into
   }
   for (const [key, value] of Object.entries(body)) {
-    if (typeof value === 'string' && MEMORABLE.test(key) && value.length < 200) {
+    if (
+      typeof value === 'string' &&
+      MEMORABLE.test(key) &&
+      value.length < 200
+    ) {
       into[key] = value
     } else if (typeof value === 'object') {
       rememberIds(value, into, depth + 1)
@@ -237,7 +245,10 @@ const personaInstructions = (
     '',
     agents.length
       ? `Assistants you can talk to:\n${agents
-          .map((agent) => `- ${agent.name}${agent.description ? `: ${agent.description}` : ''}`)
+          .map(
+            (agent) =>
+              `- ${agent.name}${agent.description ? `: ${agent.description}` : ''}`
+          )
           .join('\n')}`
       : '',
     fixtures.length ? `Files you have: ${fixtures.join(', ')}` : '',
@@ -351,7 +362,10 @@ export const runVirtualUser = async (
       stoppedBy = 'budget-duration'
       break
     }
-    if (budget?.mutations !== undefined && tally.mutations >= budget.mutations) {
+    if (
+      budget?.mutations !== undefined &&
+      tally.mutations >= budget.mutations
+    ) {
       stoppedBy = 'budget-mutations'
       break
     }
@@ -402,10 +416,7 @@ export const runVirtualUser = async (
         )
       )
     }
-    // Whether this user trusts its notes this turn or goes and looks again.
-    // `stale` almost always trusts them, a newcomer has none to trust, and an
-    // auditor checks nearly everything — which is the whole difference between
-    // those runs, expressed as one roll rather than as prose.
+    // knowledge: decisions/internals/a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md
     if (Object.keys(memory).length && !rng.chance(profile.reReadRate)) {
       messages.push(
         msg(
@@ -448,7 +459,9 @@ export const runVirtualUser = async (
 
     if (!raw || typeof raw.kind !== 'string') {
       steps.push(record)
-      messages.push(msg('user', 'That was not a valid action. Choose one action.'))
+      messages.push(
+        msg('user', 'That was not a valid action. Choose one action.')
+      )
       continue
     }
 
@@ -550,10 +563,7 @@ export const runVirtualUser = async (
       continue
     }
 
-    // What may be called is decided once, when the catalogue is narrowed: a
-    // read-only disposition is never offered a mutation and an approval-gated
-    // endpoint is never offered at all, so `index` is the gate and there is no
-    // second one here to drift out of step with it.
+    // knowledge: decisions/internals/the-virtual-user-catalogue-is-the-only-gate-on-what-may-be-called.md
     const mutating = !isReadOnly(entry)
 
     const args = readArgs((action as { args?: unknown }).args)
@@ -566,7 +576,10 @@ export const runVirtualUser = async (
       try {
         response = await target.call(entry.name, args)
       } catch (error) {
-        record.findingKinds = [...(record.findingKinds ?? []), 'transport-error']
+        record.findingKinds = [
+          ...(record.findingKinds ?? []),
+          'transport-error',
+        ]
         addFinding({
           kind: 'transport-error',
           detail: `${entry.name} threw: ${(error as Error).message}`,

package/src/wirings/virtual-user/virtual-user-agents.test.ts

@@ -45,7 +45,10 @@ describe('reachableAgents', () => {
 
   test('carries the description through, which is what the model chooses on', () => {
     const [router] = reachableAgents(AGENTS, ['content:write'])
-    assert.equal(router!.description, 'Routes requests to the right domain agent')
+    assert.equal(
+      router!.description,
+      'Routes requests to the right domain agent'
+    )
   })
 
   test('omits description rather than passing undefined', () => {

package/src/wirings/virtual-user/virtual-user-derive.ts

@@ -31,23 +31,9 @@ export const deriveCatalogue = (
 ): ApiCatalogueEntry[] => {
   const entries: ApiCatalogueEntry[] = []
   for (const [name, meta] of Object.entries(functions ?? {})) {
-    // Scenario bodies and their steps are never network-callable — they are
-    // held out of every deployed unit — so offering one would only ever waste
-    // a turn on a 404.
-    //
-    // For a platform or addon step this is not an efficiency argument but the
-    // oracle: a virtual user's findings are worth something only because it
-    // cannot manufacture the outcomes it is meant to discover. One that could
-    // invoke "Stripe's webhook arrives" would forge its own payment success,
-    // and every finding downstream of that is worthless. Same class of argument
-    // as `allowApprovalRequired` defaulting to false — and enforced here, at
-    // derivation, rather than by convention.
+    // knowledge: decisions/security/a-virtual-user-is-never-offered-a-step-that-would-forge-its-own-oracle.md
     if (meta.scenario || meta.scenarioStep || meta.scenarioStepKind) continue
-    // `expose: true` is what puts a function on the rpc transport, and that is
-    // what the shipped target calls over. Absent is not permissive: an unexposed
-    // function 404s, and offering one spends a step to learn nothing about the
-    // product. Measured on the e2e app, 34 of its 72 functions are in exactly
-    // that state — nearly half a catalogue that cannot be called.
+    // knowledge: decisions/internals/only-exposed-functions-enter-a-virtual-user-catalogue.md
     if (meta.expose !== true) continue
 
     const inputSchema = meta.inputSchemaName
@@ -103,10 +89,7 @@ const scenarioSteps = (meta: {
     )
   }
 
-  // Insertion order is the order the CLI wrote the nodes in, which is the order
-  // the scenario declares them. Following `next` instead would buy an ordering
-  // that is already true and cost a traversal that has to decide what a branch
-  // means to a reader who will never take one.
+  // knowledge: decisions/internals/virtual-user-step-order-comes-from-insertion-order.md
   return Object.values(meta.nodes ?? {}).flatMap((node) => {
     const { rpcName, scenarioStepPhase, actor } = (node ?? {}) as {
       rpcName?: string
@@ -149,11 +132,7 @@ export const deriveIntents = (
       steps.push(
         composeStepProse({
           phase: step.phase,
-          // The template goes in unfilled, braces and all. A reporter fills its
-          // placeholders from a run that happened; there is no run yet, and
-          // "invites {email}" tells a user to pick someone where the filled-in
-          // form would have told it whom — which is the scenario's answer, not
-          // the user's own.
+          // knowledge: decisions/internals/a-scenario-step-template-is-offered-unfilled.md
           description: template ?? description ?? '',
           actor: step.actor,
         })

package/src/wirings/virtual-user/virtual-user-dispositions.test.ts

@@ -1,6 +1,9 @@
 import { strict as assert } from 'assert'
 import { describe, test } from 'node:test'
-import { DISPOSITIONS, dispositionProfile } from './virtual-user-dispositions.js'
+import {
+  DISPOSITIONS,
+  dispositionProfile,
+} from './virtual-user-dispositions.js'
 
 describe('resolving a disposition profile', () => {
   test('an unknown disposition falls back to realistic rather than throwing', () => {
@@ -46,7 +49,9 @@ describe('resolving a disposition profile', () => {
     const profile = dispositionProfile('careless', {
       instructions: 'Paste ids from other tabs.',
     })
-    assert.ok(profile.instructions.startsWith(DISPOSITIONS.careless.instructions))
+    assert.ok(
+      profile.instructions.startsWith(DISPOSITIONS.careless.instructions)
+    )
     assert.ok(profile.instructions.endsWith('Paste ids from other tabs.'))
   })
 

package/src/wirings/virtual-user/virtual-user-dispositions.ts

@@ -154,10 +154,7 @@ export const DISPOSITIONS: Readonly<
     invertedOracle: true,
   },
 
-  // The only disposition that is not testing anything. It is doing the job, so
-  // it abandons rarely, runs cool, and is told to stop and say so rather than
-  // guess — the failure mode here is a wrong action nobody asked for, not a
-  // missed bug.
+  // knowledge: decisions/internals/the-worker-disposition-is-the-one-that-is-not-testing.md
   accountable: {
     ...REALISTIC,
     instructions: [

package/src/wirings/virtual-user/virtual-user-intents.test.ts

@@ -3,7 +3,10 @@ import assert from 'node:assert/strict'
 
 import { IntentStack, intentsForPersona } from './virtual-user-intents.js'
 import { createRng } from './virtual-user-rng.js'
-import { DISPOSITIONS, type DispositionProfile } from './virtual-user-dispositions.js'
+import {
+  DISPOSITIONS,
+  type DispositionProfile,
+} from './virtual-user-dispositions.js'
 import type { IntentSource } from './virtual-user.types.js'
 
 const profileWith = (
@@ -182,7 +185,11 @@ describe('intents for an actor', () => {
   const catalogue: IntentSource[] = [
     { id: 'a', title: 'invite a teammate', personas: ['orgAdmin'] },
     { id: 'b', title: 'read the dashboard' },
-    { id: 'c', title: 'deploy a stage', personas: ['platformAdmin', 'orgAdmin'] },
+    {
+      id: 'c',
+      title: 'deploy a stage',
+      personas: ['platformAdmin', 'orgAdmin'],
+    },
   ]
 
   test('an actor gets what names it, plus anything that names nobody', () => {
@@ -201,7 +208,10 @@ describe('intents for an actor', () => {
 
   test('an empty actor list means everyone', () => {
     assert.deepEqual(
-      intentsForPersona([{ id: 'x', title: 'anything', personas: [] }], 'nobody'),
+      intentsForPersona(
+        [{ id: 'x', title: 'anything', personas: [] }],
+        'nobody'
+      ),
       [{ id: 'x', title: 'anything', personas: [] }]
     )
   })

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

@@ -311,7 +311,7 @@ export interface ReturnStepMeta {
 }
 
 /**
- * Inline step metadata (legacy support)
+ * Inline step metadata
  */
 export interface InlineStepMeta {
   /** Inline form - local execution */
@@ -528,7 +528,40 @@ export interface PikkuWorkflowWire {
   approval: WorkflowWireApproval
 }
 
-export interface PikkuScenarioWire extends PikkuWorkflowWire {
+/**
+ * What a scenario has accumulated so far, shared by its body and its hooks.
+ *
+ * Typed as a partial of the scenario's own output because a scenario can fail
+ * at any step: the shape describes what a *completed* run produces, and the
+ * context holds however much of it this run reached. A scenario declaring no
+ * object output gets an open record rather than `Partial<never>`.
+ *
+ * `any` collapses to `any`, not to the union of both branches. `PikkuWire`'s
+ * default depends on that: the wire type is also used 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, so it cannot see the body's locals — which
+   * is why teardown had nowhere to learn the ids the body minted. Assigning
+   * them here (`scenario.context.projectId = project.projectId`) hands them to
+   * `after`, which runs in a `finally` and so cleans up on a failed run too.
+   *
+   * 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.

package/src/wirings/workflow/feature.ts

@@ -32,9 +32,11 @@ export const resolveFeatureScenarios = (
     const scenarios = feature.scenarios ?? []
     for (let index = 0; index < scenarios.length; index++) {
       const entry = scenarios[index]!
-      const paired =
+      const pairing =
         typeof entry === 'object' && entry !== null && 'scenario' in entry
-      const config = paired ? (entry as any).scenario : entry
+          ? (entry as { scenario: unknown; data?: unknown })
+          : undefined
+      const config = pairing ? pairing.scenario : entry
       const scenarioName = nameByConfig.get(config)
       if (!scenarioName) {
         unresolved.push({ featureId, index })
@@ -44,10 +46,11 @@ export const resolveFeatureScenarios = (
         featureId,
         featureName: feature.name ?? featureId,
         scenarioName,
-        data: paired ? (entry as any).data : undefined,
+        data: pairing?.data,
         tags: [
           ...new Set([
-            ...((registrations.get(scenarioName)?.func as any)?.tags ?? []),
+            ...((registrations.get(scenarioName)?.func as { tags?: string[] })
+              ?.tags ?? []),
             ...(feature.tags ?? []),
           ]),
         ],

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

@@ -65,7 +65,7 @@ export function createGraph<RPCMap extends Record<string, RPCHandler>>() {
     for (const [nodeId, def] of Object.entries(nodes) as [string, any][]) {
       result[nodeId] = {
         func: funcMap[nodeId] as string,
-        input: def?.input as any,
+        input: def?.input,
         next: def?.next,
         onError: def?.onError,
         retries: def?.retries,

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

@@ -10,7 +10,7 @@ import {
 import type { WorkflowRuntimeMeta } from '../workflow.types.js'
 import { pikkuState } from '../../../pikku-state.js'
 import { RPCNotFoundError } from '../../rpc/rpc-runner.js'
-import { DEFAULT_STEP_RETRIES } from '../pikku-workflow-service.js'
+import { DEFAULT_STEP_RETRIES } from '../workflow-constants.js'
 
 describe('graph-runner bugs', () => {
   test('continueGraph should NOT mark workflow completed while nodes are still running', async () => {
@@ -828,7 +828,9 @@ describe('graph-runner bugs', () => {
       name: 'testRetries',
       pikkuFuncId: 'testRetries',
       source: 'graph',
-      entryNodeIds: ['a'],
+      // All three are dependency-free, so all three are entry nodes — a
+      // `startNode` may only name one the graph declared.
+      entryNodeIds: ['a', 'b', 'c'],
       graphHash: 'retries-hash',
       nodes: {
         a: {

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

@@ -1,9 +1,9 @@
+import type { PikkuWorkflowService } from '../pikku-workflow-service.js'
 import {
-  type PikkuWorkflowService,
   WorkflowAsyncException,
   WorkflowSuspendedException,
-  DEFAULT_STEP_RETRIES,
-} from '../pikku-workflow-service.js'
+} from '../workflow-errors.js'
+import { DEFAULT_STEP_RETRIES } from '../workflow-constants.js'
 import type { GraphWireState, PikkuGraphWire } from './workflow-graph.types.js'
 import { pikkuState, getSingletonServices } from '../../../pikku-state.js'
 import type { WorkflowRuntimeMeta, WorkflowRunWire } from '../workflow.types.js'
@@ -211,7 +211,7 @@ function isDataRef(value: unknown): value is { $ref: string; path?: string } {
     typeof value === 'object' &&
     value !== null &&
     '$ref' in value &&
-    typeof (value as any).$ref === 'string'
+    typeof (value as { $ref?: unknown }).$ref === 'string'
   )
 }
 
@@ -227,7 +227,7 @@ function isTemplate(value: unknown): value is TemplateValue {
     typeof value === 'object' &&
     value !== null &&
     '$template' in value &&
-    typeof (value as any).$template === 'object'
+    typeof (value as { $template?: unknown }).$template === 'object'
   )
 }
 
@@ -695,14 +695,6 @@ export async function executeGraphStep(
   }
 }
 
-export async function onGraphNodeComplete(
-  workflowService: PikkuWorkflowService,
-  runId: string,
-  graphName: string
-): Promise<void> {
-  await continueGraph(workflowService, runId, graphName)
-}
-
 export async function runFromMeta(
   workflowService: PikkuWorkflowService,
   runId: string,
@@ -928,9 +920,14 @@ export async function runWorkflowGraph(
   }
 
   const nodes = meta.nodes
-  const entryNodes: string[] = startNode
-    ? [startNode]
-    : (meta.entryNodeIds ?? [])
+  const declaredEntryNodes = meta.entryNodeIds ?? []
+  // knowledge: decisions/security/a-graph-run-starts-at-an-entry-node-the-graph-declared.md
+  if (startNode && !declaredEntryNodes.includes(startNode)) {
+    throw new Error(
+      `Workflow graph '${graphName}': '${startNode}' is not an entry node`
+    )
+  }
+  const entryNodes: string[] = startNode ? [startNode] : declaredEntryNodes
   validateGraphReferences(graphName, nodes, entryNodes)
 
   if (entryNodes.length === 0) {

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

@@ -16,11 +16,6 @@ export const isRef = (value: unknown): value is RefValue =>
   '__isRef' in value &&
   (value as RefValue).__isRef === true
 
-export interface InputRef {
-  nodeId: string
-  path?: string
-}
-
 export type RefFn<NodeIds extends string = string> = (
   nodeId: NodeIds,
   path?: string

package/src/wirings/workflow/index.ts

@@ -1,20 +1,28 @@
+export { PikkuWorkflowService } from './pikku-workflow-service.js'
 export {
-  PikkuWorkflowService,
   WorkflowCancelledException,
   WorkflowSuspendedException,
   WorkflowDispatchException,
   WorkflowNotFoundError,
   WorkflowRunNotFoundError,
   WorkflowApprovalResolvedError,
-  DEFAULT_STEP_RETRIES,
-} from './pikku-workflow-service.js'
+  WorkflowStepFunctionMismatchError,
+} from './workflow-errors.js'
+export { DEFAULT_STEP_RETRIES } from './workflow-constants.js'
+export {
+  assertWorkflowRunOwner,
+  WorkflowRunForbiddenError,
+} from './workflow-run-ownership.js'
 export type {
   RunLifecycleContext,
   WorkflowRunEngine,
   WorkflowRunExtension,
-} from './pikku-workflow-service.js'
+} from './workflow-run-engine.types.js'
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js'
 
+export { isRef } from './graph/workflow-graph.types.js'
+export type { RefValue } from './graph/workflow-graph.types.js'
+
 export {
   buildRunTimeline,
   reconstructStateAt,