@pikku/core 0.12.80 → 0.12.83

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' }
 
 /**
@@ -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
 }
 
 /**
@@ -531,15 +603,14 @@ export interface 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>`.
+ * `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.
  *
- * `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.
+ * 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
@@ -549,12 +620,9 @@ export type ScenarioContext<Out = unknown> = 0 extends 1 & Out
 
 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.
+   * 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
@@ -589,6 +657,18 @@ export interface PikkuScenarioWire<Out = unknown> 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

@@ -1,9 +1,6 @@
 import { pikkuState } from '../../pikku-state.js'
-import type {
-  CoreFeature,
-  CoreWorkflow,
-  FeaturePlanEntry,
-} from './workflow.types.js'
+import type { CoreWorkflow } from './workflow.types.js'
+import type { CoreFeature, FeaturePlanEntry } from './scenario.types.js'
 
 export const addFeature = (
   featureId: string,

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

@@ -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()
 

package/src/wirings/workflow/index.ts

@@ -13,8 +13,8 @@ export {
   assertWorkflowRunOwner,
   WorkflowRunForbiddenError,
 } from './workflow-run-ownership.js'
+export { WorkflowApprovalForbiddenError } from './workflow-approval-policy.js'
 export type {
-  RunLifecycleContext,
   WorkflowRunEngine,
   WorkflowRunExtension,
 } from './workflow-run-engine.types.js'
@@ -28,16 +28,9 @@ export {
   reconstructStateAt,
   reconstructFinalState,
 } from './run-timeline.js'
-export type {
-  RunTimeline,
-  RunTimelineEvent,
-  ReconstructedRunState,
-  ReconstructedStep,
-  RunPhase,
-} from './run-timeline.js'
+export type { RunTimeline, ReconstructedRunState } from './run-timeline.js'
 
 export { addWorkflow } from './dsl/workflow-runner.js'
-export { addFeature, resolveFeatureScenarios } from './feature.js'
 
 export { template, type TemplateString } from './graph/template.js'
 export {
@@ -45,12 +38,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,
@@ -72,35 +59,22 @@ export type {
   WorkflowRunService,
   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,
@@ -115,47 +89,7 @@ export type {
   SwitchStepMeta,
   FilterStepMeta,
   ArrayPredicateStepMeta,
-  ScenarioStepInvocation,
-  ScenarioStepMeta,
   WorkflowStepMeta,
   WorkflowStepWire,
   PikkuWorkflowWire,
-  PikkuScenarioWire,
 } from './workflow.types.js'
-
-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'
-
-export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
-
-export { pollUntil, type PollOptions } from './scenario-poll.js'
-
-export { createCookieJar } from './scenario-cookie-jar.js'
-export type { ScenarioCookieJar } from './scenario-cookie-jar.js'
-
-export type {
-  ScenarioHttpResponse,
-  ScenarioJsonRequest,
-} 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,
-  TestIdSelector,
-  ScenarioBrowserProvider,
-  ScenarioBrowserFailure,
-} from './scenario-step.types.js'
-
-export { composeStepProse, renderStepTemplate } from './scenario-prose.js'

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

@@ -27,13 +27,36 @@ import type {
 } from './scenario-step.types.js'
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js'
 import type {
-  PikkuScenarioWire,
   PikkuWorkflowWire,
+  WorkflowQueueOptions,
+} from './workflow.types.js'
+import type { PikkuScenarioWire } from './scenario.types.js'
+import type {
   WorkflowExpectEventuallyOptions,
   WorkflowExpectErrorOptions,
+  WorkflowExpectScoreOptions,
   WorkflowExpectServiceOptions,
-  WorkflowQueueOptions,
-} from './workflow.types.js'
+} from './dsl/workflow-dsl.types.js'
+
+export { addFeature, resolveFeatureScenarios } from './feature.js'
+export type * from './scenario.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 } from './scenario-surface.js'
+
+export { pollUntil, type PollOptions } from './scenario-poll.js'
+export { createCookieJar } from './scenario-cookie-jar.js'
+export type { ScenarioCookieJar } from './scenario-cookie-jar.js'
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js'
+
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js'
+
+export type {
+  ScenarioHttpResponse,
+  ScenarioJsonRequest,
+} from '../../services/personas-service.js'
+// The readers themselves live on `@pikku/core/persona`
 
 /**
  * A workflow service with the scenario capability attached — the two lines
@@ -245,9 +268,9 @@ export class PikkuScenarioService implements WorkflowRunExtension {
   // Scenario actors per run: live authenticated clients (cookie jars) are
   // process-local by nature, so they ride this map, never the persisted wire.
   private runActors = new Map<string, ScenarioPersonas>()
-  // What each run has accumulated so far. Process-local like the actors above:
-  // a scenario is a single in-process run, so the body and its hooks share one
-  // object rather than reading it back off the persisted wire.
+  // What each run has accumulated so far — process-local like the actors above,
+  // so the body and its hooks share one object rather than reading it back off
+  // the persisted wire.
   private runContexts = new Map<string, Record<string, unknown>>()
   private scenarioBrowserProvider?: ScenarioBrowserProvider
   private scenarioEnvironment?: ScenarioEnvironment
@@ -319,19 +342,19 @@ export class PikkuScenarioService implements WorkflowRunExtension {
   }
 
   /**
-   * What the run has accumulated, for a reporter that wants to say what a
-   * failed scenario left behind. Undefined for a plain workflow.
+   * What the run has accumulated.
+   *
+   * Undefined only for a run whose wire was never decorated — decoration calls
+   * `contextForRun` unconditionally, so a plain workflow that has reached a
+   * step holds an empty context rather than none.
    */
   public getRunContext(runId: string): Record<string, unknown> | undefined {
     return this.runContexts.get(runId)
   }
 
   /**
-   * The run's context, created on demand.
-   *
-   * `attachRunContext` seeds it for an ordinary scenario run, but the wire is
-   * also built on paths that skip attach; without this the body would be
-   * writing to an `undefined` and teardown would read nothing.
+   * The run's context, created on demand because the wire is also built on
+   * paths that skip `attachRunContext`.
    */
   private contextForRun(runId: string): Record<string, unknown> {
     let runContext = this.runContexts.get(runId)
@@ -539,9 +562,6 @@ export class PikkuScenarioService implements WorkflowRunExtension {
       rpcService,
     })
     Object.assign(workflowWire, {
-      // One object per run, resolved through the map rather than created here,
-      // so the body and its before/after hooks share the same scratch even
-      // though the hooks are separate functions that cannot see its locals.
       context: this.contextForRun(runId),
 
       // Durable polling step: invoke an RPC (as an actor when options.as is
@@ -684,6 +704,51 @@ export class PikkuScenarioService implements WorkflowRunExtension {
         )
       },
 
+      expectScore: async (
+        stepName: string,
+        agentRunId: string,
+        scorerName: string,
+        options?: WorkflowExpectScoreOptions
+      ) => {
+        this.engine.verifyStepName(stepName)
+        return await this.engine.inlineStep(
+          runId,
+          stepName,
+          async () => {
+            const rpcName = 'pikkuScenarioGradeRun'
+            const data = {
+              runId: agentRunId,
+              scorer: scorerName,
+              ...(options?.reference !== undefined
+                ? { reference: options.reference }
+                : {}),
+            }
+            const grade: { score: number; reason?: string } = options?.actor
+              ? await options.actor.invoke(rpcName, data)
+              : await rpcService.rpcWithWire(rpcName, data, {})
+
+            // A scorer that graded is a scorer that answered, so an unstated
+            // bound still fails a zero rather than passing anything at all.
+            const atLeast = options?.atLeast ?? 0.5
+            const failed =
+              grade.score < atLeast ||
+              (options?.atMost !== undefined && grade.score > options.atMost)
+            if (failed) {
+              const bound =
+                options?.atMost !== undefined
+                  ? `between ${atLeast} and ${options.atMost}`
+                  : `at least ${atLeast}`
+              throw new Error(
+                `[workflow] expectScore '${stepName}' expected '${scorerName}' to grade run ${agentRunId} ${bound}, got ${grade.score}` +
+                  `${grade.reason ? `: ${grade.reason}` : ''}`
+              )
+            }
+            return grade
+          },
+          options
+        )
+      },
+
       // knowledge: decisions/internals/scenario-given-and-when-are-sugar-but-then-is-not.md
       given: (stepName, stepFunc, data, options) =>
         this.scenarioStep(

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

@@ -661,12 +661,9 @@ describe('pikku-workflow-service approval', () => {
 
     const run = await ws.getRun(runId)
     assert.equal(run?.status, 'completed')
-    assert.deepEqual(run?.output, {
-      decision: {
-        status: 'decided',
-        data: { approved: true, comment: 'lgtm' },
-      },
-    })
+    const decision = (run?.output as any)?.decision
+    assert.equal(decision.status, 'decided')
+    assert.deepEqual(decision.data, { approved: true, comment: 'lgtm' })
 
     cleanup()
   })
@@ -714,9 +711,9 @@ describe('pikku-workflow-service approval', () => {
     await ws.runWorkflowJob(runId, {})
     const run = await ws.getRun(runId)
     assert.equal(run?.status, 'completed')
-    assert.deepEqual(run?.output, {
-      decision: { status: 'decided', data: { approved: false } },
-    })
+    const decision = (run?.output as any)?.decision
+    assert.equal(decision.status, 'decided')
+    assert.deepEqual(decision.data, { approved: false })
 
     cleanup()
   })
@@ -834,9 +831,13 @@ describe('pikku-workflow-service approval', () => {
 
     const run = await ws.getRun(runId)
     assert.equal(run?.status, 'completed')
-    assert.deepEqual(run?.output, {
-      decision: { status: 'decided', data: { approved: true } },
-    })
+    const decision = (run?.output as any)?.decision
+    assert.equal(decision.status, 'decided')
+    assert.deepEqual(decision.data, { approved: true })
+    // Answered with no session, so there is nobody to name — but when the
+    // answer arrived is recorded either way.
+    assert.equal(decision.decidedBy, undefined)
+    assert.ok(!Number.isNaN(Date.parse(decision.decidedAt)))
 
     cleanup()
   })

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

@@ -47,7 +47,7 @@ import { PikkuMissingMetaError } from '../../errors/errors.js'
 import { RPCNotFoundError } from '../rpc/rpc-runner.js'
 import type { PikkuRPC } from '../rpc/rpc-types.js'
 import { deriveInvocationId } from './workflow-invocation-id.js'
-import { assertWorkflowRunOwner } from './workflow-run-ownership.js'
+import { approvalDeciderFrom } from './workflow-approval-policy.js'
 import {
   buildRunTimeline,
   reconstructStateAt,
@@ -95,6 +95,7 @@ import {
   recordApprovalDecision,
   type ApprovalStore,
 } from './workflow-approval.js'
+import { auditApprovalDecision } from './workflow-approval-audit.js'
 import { recordSuspension, suspendStepNameFor } from './workflow-suspend.js'
 import {
   RedispatchBackoff,
@@ -844,6 +845,22 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     }
 
     if (workflowMeta.source === 'graph') {
+      // A caller-supplied startNode must be one of the graph's declared entry
+      // nodes. startWorkflow is the boundary the public
+      // `/workflow/:name/graph/:nodeId` route and triggers enter through, so
+      // without this a request could name any dependency-free node — one whose
+      // input reads only `trigger` — and fire its RPC directly with
+      // attacker-chosen data, skipping every upstream eligibility, validation or
+      // approval node. (Internal resume/replay drives runWorkflowGraph directly
+      // and is unaffected.)
+      if (
+        options?.startNode &&
+        !(workflowMeta.entryNodeIds ?? []).includes(options.startNode)
+      ) {
+        throw new Error(
+          `Workflow graph '${name}': '${options.startNode}' is not a declared entry node`
+        )
+      }
       const shouldInline =
         options?.inline || !getSingletonServices()?.queueService
       return runWorkflowGraph(
@@ -1840,6 +1857,9 @@ export abstract class PikkuWorkflowService implements WorkflowService {
         this.updateRunState(runId, key, value),
       resumeWorkflow: (runId) => this.resumeWorkflow(runId),
       scheduleRunWake: (runId, delay) => this.scheduleRunWake(runId, delay),
+      getRunOwner: async (runId) =>
+        (await this.getRunIdentity(runId))?.wire?.pikkuUserId,
+      auditApproval: (event) => auditApprovalDecision(event),
     }
   }
 
@@ -1849,9 +1869,13 @@ export abstract class PikkuWorkflowService implements WorkflowService {
     decision: unknown,
     session?: CoreUserSession
   ): Promise<void> {
-    assertWorkflowRunOwner((await this.getRunIdentity(runId))?.wire, session)
-
-    return recordApprovalDecision(this.approvalStore, runId, reason, decision)
+    return recordApprovalDecision(
+      this.approvalStore,
+      runId,
+      reason,
+      decision,
+      approvalDeciderFrom(session)
+    )
   }
 
   private async approvalStep(