@pikku/core 0.12.79 → 0.12.82

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

@@ -65,6 +65,20 @@ export interface WorkflowExpectServiceOptions extends WorkflowStepOptions {
   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
  */
@@ -114,12 +128,55 @@ export type WorkflowWireSleep = (
  */
 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
@@ -142,7 +199,18 @@ export interface WorkflowApprovalOptions<
  * carried in `data` and is the application's business, not the framework's.
  */
 export type ApprovalOutcome<T> =
-  | { status: 'decided'; data: 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' }
 
 /**
@@ -311,7 +379,7 @@ export interface ReturnStepMeta {
 }
 
 /**
- * Inline step metadata (legacy support)
+ * Inline step metadata
  */
 export interface InlineStepMeta {
   /** Inline form - local execution */
@@ -416,6 +484,10 @@ export interface ApprovalStepMeta {
   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
 }
 
 /**
@@ -528,7 +600,36 @@ export interface PikkuWorkflowWire {
   approval: WorkflowWireApproval
 }
 
-export interface PikkuScenarioWire extends PikkuWorkflowWire {
+/**
+ * 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.
@@ -556,6 +657,18 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     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.
    *

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 () => {
@@ -54,6 +54,78 @@ describe('graph-runner bugs', () => {
     assert.equal(run?.status, 'running')
   })
 
+  test('startWorkflow rejects a startNode that is not a declared entry node', async () => {
+    const ws = new InMemoryWorkflowService()
+    const metaState = pikkuState(null, 'workflows', 'meta')
+    metaState['testStartNodeGate'] = {
+      name: 'testStartNodeGate',
+      pikkuFuncId: 'testStartNodeGate',
+      source: 'graph',
+      entryNodeIds: ['gate'],
+      graphHash: 'startnode-hash',
+      nodes: {
+        // 'charge' reads only trigger input, so it is dependency-free and would
+        // otherwise be directly startable — skipping the 'gate' entry node.
+        gate: { nodeId: 'gate', rpcName: 'checkEligibility', next: 'charge' },
+        charge: { nodeId: 'charge', rpcName: 'capturePayment' },
+      },
+    }
+
+    await assert.rejects(
+      () =>
+        ws.startWorkflow(
+          'testStartNodeGate',
+          {},
+          { type: 'test' },
+          { rpcWithWire: async () => ({}) },
+          { startNode: 'charge', inline: true }
+        ),
+      /not a declared entry node/
+    )
+    assert.equal(
+      [...(ws as any).runs.keys()].length,
+      0,
+      'no run should be created for a non-entry startNode'
+    )
+    delete metaState['testStartNodeGate']
+  })
+
+  test('startWorkflow accepts a startNode that is a declared entry node', async () => {
+    const ws = new InMemoryWorkflowService()
+    const metaState = pikkuState(null, 'workflows', 'meta')
+    // 'b' is a declared entry but carries an unknown input ref, so it clears the
+    // startNode gate and then throws at reference validation — proving the gate
+    // admitted it, without dispatching real work.
+    metaState['testStartNodeAllowed'] = {
+      name: 'testStartNodeAllowed',
+      pikkuFuncId: 'testStartNodeAllowed',
+      source: 'graph',
+      entryNodeIds: ['a', 'b'],
+      graphHash: 'startnode-ok-hash',
+      nodes: {
+        a: { nodeId: 'a', rpcName: 'doA' },
+        b: {
+          nodeId: 'b',
+          rpcName: 'doB',
+          input: { dep: { $ref: 'missingNode', path: 'value' } },
+        },
+      },
+    }
+    await assert.rejects(
+      () =>
+        ws.startWorkflow(
+          'testStartNodeAllowed',
+          {},
+          { type: 'test' },
+          { rpcWithWire: async () => ({}) },
+          { startNode: 'b', inline: true }
+        ),
+      /references unknown node 'missingNode'/,
+      'a declared entry node must pass the startNode gate (reaching ref validation)'
+    )
+    delete metaState['testStartNodeAllowed']
+  })
+
   test('runWorkflowGraph should throw and not create a run for unknown input refs', async () => {
     const ws = new InMemoryWorkflowService()
 
@@ -828,7 +900,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 { WorkflowApprovalForbiddenError } from './workflow-approval-policy.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,
@@ -22,10 +30,7 @@ export {
 } from './run-timeline.js'
 export type {
   RunTimeline,
-  RunTimelineEvent,
   ReconstructedRunState,
-  ReconstructedStep,
-  RunPhase,
 } from './run-timeline.js'
 
 export { addWorkflow } from './dsl/workflow-runner.js'
@@ -37,12 +42,6 @@ export {
   type PikkuWorkflowGraphConfig,
   type PikkuWorkflowGraphResult,
 } from './graph/wire-workflow-graph.js'
-
-export {
-  pikkuWorkflowWorkerFunc,
-  pikkuWorkflowOrchestratorFunc,
-  pikkuWorkflowSleeperFunc,
-} from './workflow-queue-workers.js'
 export type {
   WorkflowStepInput as WorkflowStepQueueInput,
   PikkuWorkflowOrchestratorInput,
@@ -65,34 +64,25 @@ export type {
   WorkflowRunMirror,
   CoreWorkflow,
   CoreFeature,
-  CoreFeatureScenario,
   FeatureMeta,
-  FeatureMetaEntry,
   FeaturesMeta,
   FeaturePlanEntry,
   PikkuWorkflow,
   ContextVariable,
   WorkflowContext,
   WorkflowsMeta,
-  WorkflowRuntimeMeta,
   WorkflowsRuntimeMeta,
 } from './workflow.types.js'
 
 export type {
   WorkflowStepOptions,
   WorkflowWireDoRPC,
-  WorkflowWireDoInline,
-  WorkflowWireSleep,
-  WorkflowWireSuspend,
-  WorkflowWireApproval,
   WorkflowApprovalOptions,
   ApprovalOutcome,
   InputSource,
   OutputBinding,
   RpcStepMeta,
-  SimpleCondition,
   Condition,
-  BranchCase,
   BranchStepMeta,
   ParallelGroupStepMeta,
   FanoutStepMeta,
@@ -127,7 +117,7 @@ export type {
 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'
+export { resolveScenarioSurfaces } from './scenario-surface.js'
 
 export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'