@pikku/core 0.12.80 → 0.12.83

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';
 };
@@ -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)
@@ -476,25 +541,21 @@ 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 : 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.
+     * 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
@@ -510,6 +571,15 @@ export interface PikkuScenarioWire<Out = unknown> 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.d.ts

@@ -1,4 +1,5 @@
-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 declare const addFeature: (featureId: string, feature: CoreFeature, packageName?: string | null) => void;
 export declare const resolveFeatureScenarios: (features: Map<string, CoreFeature>, registrations: Map<string, CoreWorkflow>) => {
     entries: FeaturePlanEntry[];

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

@@ -2,27 +2,16 @@ 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 type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension, } from './workflow-run-engine.types.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 { 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 { 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';
-export type { PikkuBrowserWire, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
-export { composeStepProse, renderStepTemplate } from './scenario-prose.js';
+export type { WorkflowService, WorkflowQueueOptions, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, 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, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';

package/dist/wirings/workflow/index.js

@@ -2,18 +2,10 @@ 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 { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
-export { pollUntil } from './scenario-poll.js';
-export { createCookieJar } from './scenario-cookie-jar.js';
-export { composeStepProse, renderStepTemplate } from './scenario-prose.js';

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

@@ -5,6 +5,16 @@ 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';
+export { addFeature, resolveFeatureScenarios } from './feature.js';
+export type * from './scenario.types.js';
+export { SCENARIO_SURFACES } from './scenario-step.types.js';
+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';
 /**
  * A workflow service with the scenario capability attached — the two lines
  * `pikku scenario run` needs, in one call so no caller has to remember that the
@@ -156,16 +166,16 @@ export declare class PikkuScenarioService implements WorkflowRunExtension {
     }): Promise<void>;
     detachRunContext(runId: string): void;
     /**
-     * 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.
      */
     getRunContext(runId: string): Record<string, unknown> | undefined;
     /**
-     * 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;
     decorateRunWire(wire: PikkuRawWire, context: {

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

@@ -7,6 +7,15 @@ import { InMemoryWorkflowService } from '../../services/in-memory-workflow-servi
 import { runScheduledTask } from '../scheduler/scheduler-runner.js';
 import { WorkflowStepNameNotString } from './workflow-errors.js';
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
+export { addFeature, resolveFeatureScenarios } from './feature.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 } from './scenario-poll.js';
+export { createCookieJar } from './scenario-cookie-jar.js';
+export { composeStepProse, renderStepTemplate } from './scenario-prose.js';
+export { requireActor, requireScenarioEnv } from './scenario-step-guards.js';
+// The readers themselves live on `@pikku/core/persona`
 /**
  * A workflow service with the scenario capability attached — the two lines
  * `pikku scenario run` needs, in one call so no caller has to remember that the
@@ -176,9 +185,9 @@ 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:
-    // 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.
     runContexts = new Map();
     scenarioBrowserProvider;
     scenarioEnvironment;
@@ -235,18 +244,18 @@ export class PikkuScenarioService {
         this.runContexts.delete(runId);
     }
     /**
-     * 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.
      */
     getRunContext(runId) {
         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`.
      */
     contextForRun(runId) {
         let runContext = this.runContexts.get(runId);
@@ -397,9 +406,6 @@ export class PikkuScenarioService {
             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
             // set) until the predicate passes or `within` elapses. The whole poll is
@@ -485,6 +491,35 @@ export class PikkuScenarioService {
                     }
                 }, options);
             },
+            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),

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

@@ -6,7 +6,7 @@ import { isExpectedError } from '../../errors/error-handler.js';
 import { PikkuMissingMetaError } from '../../errors/errors.js';
 import { RPCNotFoundError } from '../rpc/rpc-runner.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, } from './run-timeline.js';
 import { DEFAULT_STEP_RETRIES, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, } from './workflow-constants.js';
 import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepFunctionMismatchError, WorkflowStepNameNotString, WorkflowSuspendedException, } from './workflow-errors.js';
@@ -14,6 +14,7 @@ import { resolveWorkflowMeta } from './workflow-meta-resolver.js';
 import { jobGroupFor, orchestratorQueueName, resolveWorkflowConfig, stepJobOptions, stepWorkerQueueName, } from './workflow-queue-routing.js';
 import { wireWorkflowQueueWorkers } from './workflow-queue-wiring.js';
 import { approvalStepNameFor, evaluateApprovalStep, recordApprovalDecision, } from './workflow-approval.js';
+import { auditApprovalDecision } from './workflow-approval-audit.js';
 import { recordSuspension, suspendStepNameFor } from './workflow-suspend.js';
 import { RedispatchBackoff, sweepStalledRuns, sweepUndispatchedSteps, } from './workflow-recovery.js';
 export class PikkuWorkflowService {
@@ -371,6 +372,18 @@ export class PikkuWorkflowService {
             throw new WorkflowNotFoundError(name);
         }
         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(this, name, input, rpcService, shouldInline, options?.startNode, wire, workflowMeta);
         }
@@ -1014,11 +1027,12 @@ export class PikkuWorkflowService {
             updateRunState: (runId, key, value) => 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),
         };
     }
     async approveStep(runId, reason, decision, session) {
-        assertWorkflowRunOwner((await this.getRunIdentity(runId))?.wire, session);
-        return recordApprovalDecision(this.approvalStore, runId, reason, decision);
+        return recordApprovalDecision(this.approvalStore, runId, reason, decision, approvalDeciderFrom(session));
     }
     async approvalStep(runId, reason, options) {
         const fromStepName = this.lastStepName(runId);

package/dist/wirings/workflow/scenario-step.types.d.ts

@@ -210,6 +210,14 @@ export interface ScenarioBrowserProvider {
      * scenario cannot leave the next signed in as somebody else.
      */
     reset?(): Promise<void>;
+    /**
+     * Name the scenario about to run, so anything it captures is filed under it.
+     *
+     * Called before each scenario. A provider that is never told has to fall
+     * back to one shared label, which puts every run's artifacts in a single
+     * folder — findable only by timestamp.
+     */
+    beginScenario?(scenario: string): void;
     /**
      * Snapshot every open window for a failed scenario. `label` identifies the
      * scenario in artifact filenames. Never throws: a failure to capture must

package/dist/wirings/workflow/scenario.types.d.ts

@@ -0,0 +1,37 @@
+import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
+export type { ScenarioStepInvocation, ScenarioStepMeta, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
+export type { ScenarioStepPhase, ScenarioStepKind, ScenarioStepOptions, PikkuScenarioStepWire, ScenarioEnvironment, ScenarioSurface, ScenarioSurfaceResolution, PikkuBrowserWire, TestIdSelector, ScenarioBrowserProvider, ScenarioBrowserFailure, } from './scenario-step.types.js';
+export type CoreFeatureScenario = CorePikkuFunctionConfig<any, any, any> | {
+    scenario: CorePikkuFunctionConfig<any, any, any>;
+    data: unknown;
+};
+export type CoreFeature = {
+    name: string;
+    description?: string;
+    tags?: string[];
+    scenarios: readonly CoreFeatureScenario[];
+    before?: CorePikkuFunctionHook;
+    after?: CorePikkuFunctionHook;
+};
+export type FeatureMetaEntry = {
+    scenario: string;
+    data?: unknown;
+};
+export type FeatureMeta = {
+    id: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    entries: FeatureMetaEntry[];
+    unresolvedEntries: number;
+    hasBefore: boolean;
+    hasAfter: boolean;
+};
+export type FeaturesMeta = Record<string, FeatureMeta>;
+export type FeaturePlanEntry = {
+    featureId: string;
+    featureName: string;
+    scenarioName: string;
+    data?: unknown;
+    tags: string[];
+};

package/dist/wirings/workflow/workflow-approval-audit.d.ts

@@ -0,0 +1,16 @@
+import type { ApprovalAuditEvent } from './workflow-approval.js';
+/** The audit type an answer to an approval gate is recorded under. */
+export declare const APPROVAL_AUDIT_TYPE = "workflow.approval.decided";
+/**
+ * Record an answer to an approval gate where it outlives the run.
+ *
+ * The step result carries the settled decision, but it is deleted with the run
+ * — `deleteRun` cascades to steps and to history — and a refused attempt never
+ * reaches a step at all. An approval is asked for precisely so it can be
+ * answered for afterwards, so the answer also goes to the audit sink, which
+ * holds no foreign key to the run.
+ *
+ * A project with no sink wired records nothing, and a sink that fails is logged
+ * rather than thrown: the trail must not be the reason a decision is lost.
+ */
+export declare const auditApprovalDecision: (event: ApprovalAuditEvent) => Promise<void>;

package/dist/wirings/workflow/workflow-approval-audit.js

@@ -0,0 +1,40 @@
+import { getSingletonServices } from '../../pikku-state.js';
+/** The audit type an answer to an approval gate is recorded under. */
+export const APPROVAL_AUDIT_TYPE = 'workflow.approval.decided';
+/**
+ * Record an answer to an approval gate where it outlives the run.
+ *
+ * The step result carries the settled decision, but it is deleted with the run
+ * — `deleteRun` cascades to steps and to history — and a refused attempt never
+ * reaches a step at all. An approval is asked for precisely so it can be
+ * answered for afterwards, so the answer also goes to the audit sink, which
+ * holds no foreign key to the run.
+ *
+ * A project with no sink wired records nothing, and a sink that fails is logged
+ * rather than thrown: the trail must not be the reason a decision is lost.
+ */
+export const auditApprovalDecision = async (event) => {
+    const services = getSingletonServices();
+    if (!services?.audit) {
+        return;
+    }
+    try {
+        await services.audit.audit({
+            type: APPROVAL_AUDIT_TYPE,
+            source: 'explicit',
+            outcome: event.outcome,
+            occurredAt: new Date().toISOString(),
+            wireType: 'workflow',
+            userIdentity: { pikkuUserId: event.decidedBy?.userId },
+            metadata: {
+                runId: event.runId,
+                reason: event.reason,
+                scopes: event.decidedBy?.scopes,
+                refusal: event.refusal,
+            },
+        });
+    }
+    catch (error) {
+        services.logger?.warn(`Failed to audit the decision on approval '${event.reason}' for run ${event.runId}`, error);
+    }
+};

package/dist/wirings/workflow/workflow-approval-policy.d.ts

@@ -0,0 +1,20 @@
+import { ForbiddenError } from '../../errors/errors.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { ApprovalDecider, WorkflowApprovalPolicy } from './dsl/workflow-dsl.types.js';
+export declare class WorkflowApprovalForbiddenError extends ForbiddenError {
+    payload: {
+        reason: string;
+        detail: string;
+    };
+    constructor(reason: string, detail: string);
+}
+export declare const approvalDeciderFrom: (session: CoreUserSession | undefined) => ApprovalDecider | undefined;
+/**
+ * Judge a decision against the gate's declared policy, returning the reason it
+ * is refused or `undefined` if it stands.
+ *
+ * Returns a message rather than throwing because the same judgement is needed
+ * in two places with different outcomes: refusing a live submission with a 403,
+ * and clearing an already-recorded decision on replay.
+ */
+export declare const approvalPolicyRefusal: (policy: WorkflowApprovalPolicy, owner: string | undefined, decider: ApprovalDecider | undefined) => string | undefined;

package/dist/wirings/workflow/workflow-approval-policy.js

@@ -0,0 +1,48 @@
+import { ForbiddenError } from '../../errors/errors.js';
+import { addError } from '../../errors/error-handler.js';
+export class WorkflowApprovalForbiddenError extends ForbiddenError {
+    payload;
+    constructor(reason, detail) {
+        super(detail);
+        this.payload = { reason, detail };
+    }
+}
+addError(WorkflowApprovalForbiddenError, {
+    status: 403,
+    message: 'Not authorized to answer this approval.',
+});
+export const approvalDeciderFrom = (session) => session ? { userId: session.userId, scopes: session.scopes } : undefined;
+/**
+ * Judge a decision against the gate's declared policy, returning the reason it
+ * is refused or `undefined` if it stands.
+ *
+ * Returns a message rather than throwing because the same judgement is needed
+ * in two places with different outcomes: refusing a live submission with a 403,
+ * and clearing an already-recorded decision on replay.
+ */
+export const approvalPolicyRefusal = (policy, owner, decider) => {
+    if (policy.approverScope &&
+        !decider?.scopes?.includes(policy.approverScope)) {
+        return `Answering this approval requires the '${policy.approverScope}' scope`;
+    }
+    switch (policy.approvers ?? 'any') {
+        case 'owner':
+            if (!owner) {
+                return undefined;
+            }
+            if (!decider?.userId || decider.userId !== owner) {
+                return 'Only the user who started this run may answer this approval';
+            }
+            return undefined;
+        case 'not-initiator':
+            if (!decider?.userId) {
+                return 'Answering this approval requires a signed-in user';
+            }
+            if (owner && decider.userId === owner) {
+                return 'The user who started this run may not answer this approval';
+            }
+            return undefined;
+        case 'any':
+            return undefined;
+    }
+};