@pikku/core 0.12.79 → 0.12.82

package/dist/wirings/virtual-user/index.d.ts

@@ -16,15 +16,14 @@
  * {@link VirtualUserTarget}, which in production is an `HttpPersona`
  * signed in as a real user against staging or production.
  */
-export type { ApiCatalogueEntry, IntentRecord, IntentSource, IntentStatus, StepRecord, VirtualUserAction, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserFindingKind, VirtualUserRunResult, VirtualUserTally, VirtualUserTarget, } from './virtual-user.types.js';
+export type { ApiCatalogueEntry, IntentSource, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTarget, } from './virtual-user.types.js';
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
-export { runVirtualUser, rememberIds, type RunVirtualUserParams, type VirtualUserCallContext, } from './run-virtual-user.js';
+export { runVirtualUser, type RunVirtualUserParams, } from './run-virtual-user.js';
 export { personaScopes, prepareVirtualUserRun, type VirtualUserPreparation, } from './prepare-virtual-user-run.js';
 export type { VirtualUserRunOutcome, VirtualUserRunRecord, VirtualUserRunStart, VirtualUserRunStore, } from './virtual-user-run-store.js';
 export { DISPOSITIONS, dispositionProfile, type DispositionProfile, type VirtualUserTuning, } from './virtual-user-dispositions.js';
-export { catalogueClassification, catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
-export { reachableAgents, type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';
-export { IntentStack, intentsForPersona, type IntentMove, type ScheduledTick, } from './virtual-user-intents.js';
-export { createRng, type VirtualUserRng } from './virtual-user-rng.js';
+export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
+export { type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';
+export { IntentStack, intentsForPersona, } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, type SchemaMap, } from './virtual-user-derive.js';
 export { personaVirtualUserTarget, type PersonaTargetOptions, } from './virtual-user-target.js';

package/dist/wirings/virtual-user/index.js

@@ -1,10 +1,8 @@
 export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
-export { runVirtualUser, rememberIds, } from './run-virtual-user.js';
+export { runVirtualUser, } from './run-virtual-user.js';
 export { personaScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
 export { DISPOSITIONS, dispositionProfile, } from './virtual-user-dispositions.js';
-export { catalogueClassification, catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
-export { reachableAgents, } from './virtual-user-agents.js';
+export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { IntentStack, intentsForPersona, } from './virtual-user-intents.js';
-export { createRng } from './virtual-user-rng.js';
 export { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
 export { personaVirtualUserTarget, } from './virtual-user-target.js';

package/dist/wirings/virtual-user/run-virtual-user.js

@@ -97,7 +97,9 @@ export const rememberIds = (body, into, depth = 0) => {
         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') {
@@ -203,7 +205,8 @@ export const runVirtualUser = async (params) => {
             stoppedBy = 'budget-duration';
             break;
         }
-        if (budget?.mutations !== undefined && tally.mutations >= budget.mutations) {
+        if (budget?.mutations !== undefined &&
+            tally.mutations >= budget.mutations) {
             stoppedBy = 'budget-mutations';
             break;
         }
@@ -243,10 +246,7 @@ export const runVirtualUser = async (params) => {
         if (tick.move === 'resume' || tick.move === 'suspend') {
             messages.push(msg('user', `You were pulled away and have come back to this. Things may have changed since.`));
         }
-        // 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('user', `Things you have noted down: ${Object.entries(memory)
                 .slice(-25)
@@ -365,10 +365,7 @@ export const runVirtualUser = async (params) => {
             steps.push(record);
             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.args);
         const repeats = profile.repeatRate > 0 && rng.chance(profile.repeatRate) ? 2 : 1;
@@ -379,7 +376,10 @@ export const runVirtualUser = async (params) => {
                 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.message}`,

package/dist/wirings/virtual-user/virtual-user-derive.js

@@ -18,24 +18,10 @@ const topLevelKeys = (schema) => {
 export const deriveCatalogue = (functions, schemas = {}) => {
     const entries = [];
     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
@@ -76,10 +62,7 @@ const scenarioSteps = (meta) => {
             ? [{ stepFunc: step.stepFunc, phase: step.phase, actor: step.actor }]
             : []);
     }
-    // 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 ?? {});
         if (!rpcName || !scenarioStepPhase)
@@ -115,11 +98,7 @@ export const deriveIntents = (workflows, functions = {}) => {
                 continue;
             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/dist/wirings/virtual-user/virtual-user-dispositions.js

@@ -78,10 +78,7 @@ export const DISPOSITIONS = {
         reReadRate: 0.2,
         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/dist/wirings/workflow/dsl/workflow-dsl.types.d.ts

@@ -53,6 +53,19 @@ export interface WorkflowExpectServiceOptions extends WorkflowStepOptions {
     /** Assert the exact number of matching calls. Default: at least one. */
     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
  */
@@ -80,10 +93,50 @@ export type WorkflowWireSleep = (stepName: string, duration: string) => Promise<
  * loops, like dynamic `do()` step names.
  */
 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> {
+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
@@ -107,6 +160,14 @@ export interface WorkflowApprovalOptions<TSchema extends StandardSchemaV1 = Stan
 export type ApprovalOutcome<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';
 };
@@ -288,7 +349,7 @@ export interface ReturnStepMeta {
     spread?: string[];
 }
 /**
- * Inline step metadata (legacy support)
+ * Inline step metadata
  */
 export interface InlineStepMeta {
     /** Inline form - local execution */
@@ -386,6 +447,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;
 }
 /**
  * Filter step metadata (array.filter)
@@ -473,7 +538,30 @@ export interface PikkuWorkflowWire {
     /** Suspend workflow until a human records a decision against this gate */
     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.
@@ -483,6 +571,15 @@ export interface PikkuScenarioWire extends PikkuWorkflowWire {
     expectError: <TInput = any>(stepName: string, rpcName: string, data: TInput, options?: WorkflowExpectErrorOptions) => Promise<string>;
     /** Stub-assertion step: asserts `service.method` was called on the target server */
     expectService: (stepName: string, serviceMethod: string, 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/dist/wirings/workflow/feature.js

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

package/dist/wirings/workflow/graph/graph-runner.d.ts

@@ -1,4 +1,4 @@
-import { type PikkuWorkflowService } from '../pikku-workflow-service.js';
+import type { PikkuWorkflowService } from '../pikku-workflow-service.js';
 import type { WorkflowRuntimeMeta, WorkflowRunWire } from '../workflow.types.js';
 export declare class ChildWorkflowStartedException extends Error {
     parentRunId: string;
@@ -9,7 +9,6 @@ export declare class ChildWorkflowStartedException extends Error {
 }
 export declare function continueGraph(workflowService: PikkuWorkflowService, runId: string, graphName: string, overrideMeta?: WorkflowRuntimeMeta): Promise<void>;
 export declare function executeGraphStep(workflowService: PikkuWorkflowService, rpcService: any, runId: string, stepId: string, nodeId: string, rpcName: string, data: any, graphName: string): Promise<any>;
-export declare function onGraphNodeComplete(workflowService: PikkuWorkflowService, runId: string, graphName: string): Promise<void>;
 export declare function runFromMeta(workflowService: PikkuWorkflowService, runId: string, meta: WorkflowRuntimeMeta, _rpcService: any): Promise<void>;
 export declare function runWorkflowGraph(workflowService: PikkuWorkflowService, graphName: string, triggerInput: any, rpcService?: any, inline?: boolean, startNode?: string, wire?: WorkflowRunWire, overrideMeta?: WorkflowRuntimeMeta): Promise<{
     runId: string;

package/dist/wirings/workflow/graph/graph-runner.js

@@ -1,4 +1,5 @@
-import { WorkflowAsyncException, WorkflowSuspendedException, DEFAULT_STEP_RETRIES, } from '../pikku-workflow-service.js';
+import { WorkflowAsyncException, WorkflowSuspendedException, } from '../workflow-errors.js';
+import { DEFAULT_STEP_RETRIES } from '../workflow-constants.js';
 import { pikkuState, getSingletonServices } from '../../../pikku-state.js';
 import { RPCNotFoundError } from '../../rpc/rpc-runner.js';
 export class ChildWorkflowStartedException extends Error {
@@ -491,9 +492,6 @@ export async function executeGraphStep(workflowService, rpcService, runId, stepI
         throw error;
     }
 }
-export async function onGraphNodeComplete(workflowService, runId, graphName) {
-    await continueGraph(workflowService, runId, graphName);
-}
 export async function runFromMeta(workflowService, runId, meta, _rpcService) {
     await continueGraph(workflowService, runId, meta.name, meta);
 }
@@ -610,9 +608,12 @@ export async function runWorkflowGraph(workflowService, graphName, triggerInput,
         throw new Error(`Workflow graph '${graphName}' not found`);
     }
     const nodes = meta.nodes;
-    const entryNodes = 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 = startNode ? [startNode] : declaredEntryNodes;
     validateGraphReferences(graphName, nodes, entryNodes);
     if (entryNodes.length === 0) {
         throw new Error(`Workflow graph '${graphName}': no entry nodes found in meta or startNode`);

package/dist/wirings/workflow/graph/workflow-graph.types.d.ts

@@ -5,10 +5,6 @@ export interface RefValue {
 }
 export declare const createRef: (nodeId: string, path?: string) => RefValue;
 export declare const isRef: (value: unknown) => value is RefValue;
-export interface InputRef {
-    nodeId: string;
-    path?: string;
-}
 export type RefFn<NodeIds extends string = string> = (nodeId: NodeIds, path?: string) => RefValue;
 export type NextConfig<NodeIds extends string = string> = NodeIds | NodeIds[] | Record<string, NodeIds | NodeIds[]>;
 export interface GraphNodeConfig<NodeIds extends string = string> {

package/dist/wirings/workflow/index.d.ts

@@ -1,19 +1,24 @@
-export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
-export type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension, } from './pikku-workflow-service.js';
+export { PikkuWorkflowService } from './pikku-workflow-service.js';
+export { WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, 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 { WorkflowRunEngine, WorkflowRunExtension, } 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, 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 { pikkuWorkflowGraph, 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, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
-export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, 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, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, ScenarioStepInvocation, ScenarioStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';
+export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, CoreFeature, FeatureMeta, FeaturesMeta, FeaturePlanEntry, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowsRuntimeMeta, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, Condition, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, 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';
-export { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
+export { resolveScenarioSurfaces } 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';

package/dist/wirings/workflow/index.js

@@ -1,14 +1,18 @@
-export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
+export { PikkuWorkflowService } from './pikku-workflow-service.js';
+export { WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, 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 { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
+export { isRef } from './graph/workflow-graph.types.js';
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
 export { addWorkflow } from './dsl/workflow-runner.js';
 export { addFeature, resolveFeatureScenarios } from './feature.js';
 export { template } from './graph/template.js';
 export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
-export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.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 { resolveScenarioSurfaces } from './scenario-surface.js';
 export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
 export { pollUntil } from './scenario-poll.js';
 export { createCookieJar } from './scenario-cookie-jar.js';

package/dist/wirings/workflow/pikku-scenario-service.d.ts

@@ -1,7 +1,7 @@
 import { PikkuError } from '../../errors/error-handler.js';
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
-import { type RunLifecycleContext, type WorkflowRunEngine, type WorkflowRunExtension } from './pikku-workflow-service.js';
-import type { PikkuWire } from '../../types/core.types.js';
+import type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
+import type { PikkuRawWire } from '../../types/core.types.js';
 import type { ScenarioPersonas } from '../../services/personas-service.js';
 import type { ScenarioBrowserProvider, ScenarioEnvironment, ScenarioSurface } from './scenario-step.types.js';
 import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
@@ -126,6 +126,7 @@ export declare class ScenarioNoWitness extends PikkuError {
 export declare class PikkuScenarioService implements WorkflowRunExtension {
     private readonly engine;
     private runActors;
+    private runContexts;
     private scenarioBrowserProvider?;
     private scenarioEnvironment?;
     private runSurface;
@@ -154,7 +155,20 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
         actors?: ScenarioPersonas;
     }): Promise<void>;
     detachRunContext(runId: string): void;
-    decorateRunWire(wire: PikkuWire, context: {
+    /**
+     * 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.
+     */
+    getRunContext(runId: string): Record<string, unknown> | undefined;
+    /**
+     * The run's context, created on demand because the wire is also built on
+     * paths that skip `attachRunContext`.
+     */
+    private contextForRun;
+    decorateRunWire(wire: PikkuRawWire, context: {
         runId: string;
         workflowMeta: any;
         workflowWire: PikkuWorkflowWire;

package/dist/wirings/workflow/pikku-scenario-service.js

@@ -5,7 +5,7 @@ import { closeWireServices } from '../../utils.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
 import { runScheduledTask } from '../scheduler/scheduler-runner.js';
-import { WorkflowStepNameNotString, } from './pikku-workflow-service.js';
+import { WorkflowStepNameNotString } from './workflow-errors.js';
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
 /**
  * A workflow service with the scenario capability attached — the two lines
@@ -176,6 +176,10 @@ export class PikkuScenarioService {
     // Scenario actors per run: live authenticated clients (cookie jars) are
     // process-local by nature, so they ride this map, never the persisted wire.
     runActors = new Map();
+    // 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.
+    runContexts = new Map();
     scenarioBrowserProvider;
     scenarioEnvironment;
     runSurface = 'default';
@@ -222,9 +226,35 @@ export class PikkuScenarioService {
         if (actors) {
             this.runActors.set(runId, actors);
         }
+        if (workflowMeta.source === 'scenario') {
+            this.runContexts.set(runId, {});
+        }
     }
     detachRunContext(runId) {
         this.runActors.delete(runId);
+        this.runContexts.delete(runId);
+    }
+    /**
+     * 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.
+     */
+    getRunContext(runId) {
+        return this.runContexts.get(runId);
+    }
+    /**
+     * The run's context, created on demand because the wire is also built on
+     * paths that skip `attachRunContext`.
+     */
+    contextForRun(runId) {
+        let runContext = this.runContexts.get(runId);
+        if (!runContext) {
+            runContext = {};
+            this.runContexts.set(runId, runContext);
+        }
+        return runContext;
     }
     decorateRunWire(wire, context) {
         wire.scenario =
@@ -367,6 +397,7 @@ export class PikkuScenarioService {
             rpcService,
         });
         Object.assign(workflowWire, {
+            context: this.contextForRun(runId),
             // Durable polling step: invoke an RPC (as an actor when options.as is
             // set) until the predicate passes or `within` elapses. The whole poll is
             // ONE recorded step, so replay returns the cached outcome.
@@ -451,12 +482,36 @@ export class PikkuScenarioService {
                     }
                 }, options);
             },
-            // Scenario steps: a named `pikkuScenarioStep` run as one durable step.
-            // `given`/`when` are sugar for each other, differing only in the
-            // prose a reporter renders. `then` is not: the phase is what decides
-            // whether the step's bindings are alternatives or witnesses, so the same
-            // step function called two ways runs differently. See
-            // {@link resolveScenarioSurfaces}.
+            expectScore: async (stepName, agentRunId, scorerName, options) => {
+                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 = 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('given', scenarioStepContext(), stepName, stepFunc, data, options),
             when: (stepName, stepFunc, data, options) => this.scenarioStep('when', scenarioStepContext(), stepName, stepFunc, data, options),
             then: (stepName, stepFunc, data, options) => this.scenarioStep('then', scenarioStepContext(), stepName, stepFunc, data, options),
@@ -466,7 +521,7 @@ export class PikkuScenarioService {
         });
     }
     async scenarioStep(phase, context, stepName, stepFunc, data, options) {
-        const { runId, workflowName, addonNamespace, workflowWire, rpcService } = context;
+        const { runId, workflowName, addonNamespace, workflowWire } = context;
         // Also the guard for `then` being a wire member: an accidental
         // `await scenario` calls it with a resolve function, which lands here as a
         // loud, named error instead of a silent hang.
@@ -486,11 +541,10 @@ export class PikkuScenarioService {
         const resolution = resolveScenarioSurfaces(phase, declared, this.runSurface);
         return await this.engine.inlineStep(runId, stepName, async () => {
             const runOnSurface = async (surface) => {
+                // No `rpc` yet — runPikkuFunc attaches it lazily for the invocation.
                 const wire = {
                     workflow: workflowWire,
                     scenario: workflowWire,
-                    rpc: rpcService?.wire?.rpc,
-                    session: rpcService?.wire?.session,
                     pikkuUserId: workflowWire.pikkuUserId,
                     actors: this.runActors.get(runId),
                     scenarioStep: {