@pikku/core 0.12.80 → 0.12.82

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

@@ -156,16 +156,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

@@ -176,9 +176,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 +235,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 +397,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 +482,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/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;
+    }
+};

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

@@ -1,4 +1,5 @@
 import type { ApprovalOutcome, StepState, WorkflowApprovalOptions } from './workflow.types.js';
+import type { ApprovalDecider } from './dsl/workflow-dsl.types.js';
 /** The durable step name an approval point is recorded under. */
 export declare const approvalStepNameFor: (reason: string) => string;
 /**
@@ -9,6 +10,20 @@ export declare const approvalStepNameFor: (reason: string) => string;
  * shadow, another key.
  */
 export declare const approvalStateKey: (stepName: string) => string;
+/**
+ * An answer to an approval gate, as the audit trail sees it.
+ *
+ * `denied` covers both a submission refused at the door and a decision cleared
+ * on replay — from the trail's point of view they are the same event, someone
+ * tried to answer a gate they could not.
+ */
+export type ApprovalAuditEvent = {
+    runId: string;
+    reason: string;
+    outcome: 'success' | 'denied';
+    decidedBy?: ApprovalDecider;
+    refusal?: string;
+};
 /** What the approval gate needs from the workflow service. */
 export type ApprovalStore = {
     getStepState: (runId: string, stepName: string) => Promise<StepState>;
@@ -19,6 +34,8 @@ export type ApprovalStore = {
     updateRunState: (runId: string, key: string, value: unknown) => Promise<void>;
     resumeWorkflow: (runId: string) => Promise<void>;
     scheduleRunWake: (runId: string, delay: number) => Promise<void>;
+    getRunOwner: (runId: string) => Promise<string | undefined>;
+    auditApproval: (event: ApprovalAuditEvent) => Promise<void>;
 };
 /**
  * Record a decision against an approval point and wake the run.
@@ -26,8 +43,14 @@ export type ApprovalStore = {
  * A decision arriving for an already-settled approval is refused rather than
  * overwriting it: the run has moved on, and a second answer would be recorded
  * against a gate nobody is waiting at.
+ *
+ * The decider is recorded rather than judged here, for the same reason the
+ * payload is: the gate's policy is a value on the workflow, and a decision can
+ * legitimately arrive before the run has ever reached the gate. Where the run
+ * has already published its policy, it is applied eagerly so a caller who
+ * cannot answer is told so rather than left waiting.
  */
-export declare const recordApprovalDecision: (store: ApprovalStore, runId: string, reason: string, decision: unknown) => Promise<void>;
+export declare const recordApprovalDecision: (store: ApprovalStore, runId: string, reason: string, decision: unknown, decidedBy?: ApprovalDecider) => Promise<void>;
 /**
  * Evaluate an approval gate on replay.
  *
@@ -35,5 +58,10 @@ export declare const recordApprovalDecision: (store: ApprovalStore, runId: strin
  * schema is a value on the workflow and only the workflow has it. A payload
  * that fails validation is cleared and the run suspends again, so a bad
  * submission cannot settle the gate.
+ *
+ * The decider is judged here for the same reason, and for one more: a decision
+ * can be recorded before the run has ever reached the gate, so submission time
+ * is not a point at which the policy is reliably knowable. Judging on replay is
+ * what makes the policy hold in every ordering.
  */
 export declare const evaluateApprovalStep: (store: ApprovalStore, runId: string, reason: string, approvalStepName: string, fromStepName: string | undefined, options: WorkflowApprovalOptions) => Promise<ApprovalOutcome<unknown>>;

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

@@ -1,5 +1,6 @@
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { WorkflowApprovalResolvedError, WorkflowSuspendedException, } from './workflow-errors.js';
+import { approvalPolicyRefusal, WorkflowApprovalForbiddenError, } from './workflow-approval-policy.js';
 /** The durable step name an approval point is recorded under. */
 export const approvalStepNameFor = (reason) => `__workflow_approval:${reason}`;
 /**
@@ -22,8 +23,14 @@ export const approvalStateKey = (stepName) => {
  * A decision arriving for an already-settled approval is refused rather than
  * overwriting it: the run has moved on, and a second answer would be recorded
  * against a gate nobody is waiting at.
+ *
+ * The decider is recorded rather than judged here, for the same reason the
+ * payload is: the gate's policy is a value on the workflow, and a decision can
+ * legitimately arrive before the run has ever reached the gate. Where the run
+ * has already published its policy, it is applied eagerly so a caller who
+ * cannot answer is told so rather than left waiting.
  */
-export const recordApprovalDecision = async (store, runId, reason, decision) => {
+export const recordApprovalDecision = async (store, runId, reason, decision, decidedBy) => {
     const stepName = approvalStepNameFor(reason);
     const stateKey = approvalStateKey(stepName);
     let resolved;
@@ -39,12 +46,27 @@ export const recordApprovalDecision = async (store, runId, reason, decision) =>
     }
     const state = await store.getRunState(runId);
     const record = (state[stateKey] ?? {});
+    if (record.policy) {
+        const refusal = approvalPolicyRefusal(record.policy, await store.getRunOwner(runId), decidedBy);
+        if (refusal) {
+            await store.auditApproval({
+                runId,
+                reason,
+                outcome: 'denied',
+                decidedBy,
+                refusal,
+            });
+            throw new WorkflowApprovalForbiddenError(reason, refusal);
+        }
+    }
     await store.updateRunState(runId, stateKey, {
         ...record,
         decision,
         decidedAt: new Date().toISOString(),
+        decidedBy,
         error: undefined,
     });
+    await store.auditApproval({ runId, reason, outcome: 'success', decidedBy });
     await store.resumeWorkflow(runId);
 };
 /**
@@ -54,9 +76,19 @@ export const recordApprovalDecision = async (store, runId, reason, decision) =>
  * schema is a value on the workflow and only the workflow has it. A payload
  * that fails validation is cleared and the run suspends again, so a bad
  * submission cannot settle the gate.
+ *
+ * The decider is judged here for the same reason, and for one more: a decision
+ * can be recorded before the run has ever reached the gate, so submission time
+ * is not a point at which the policy is reliably knowable. Judging on replay is
+ * what makes the policy hold in every ordering.
  */
 export const evaluateApprovalStep = async (store, runId, reason, approvalStepName, fromStepName, options) => {
-    const insert = () => store.insertStepState(runId, approvalStepName, 'pikkuWorkflowApproval', { reason, expiry: options.expiry }, undefined, fromStepName);
+    const insert = () => store.insertStepState(runId, approvalStepName, 'pikkuWorkflowApproval', {
+        reason,
+        expiry: options.expiry,
+        approvers: options.approvers,
+        approverScope: options.approverScope,
+    }, undefined, fromStepName);
     let stepState;
     try {
         stepState = await store.getStepState(runId, approvalStepName);
@@ -72,8 +104,13 @@ export const evaluateApprovalStep = async (store, runId, reason, approvalStepNam
     }
     const stateKey = approvalStateKey(approvalStepName);
     let record = ((await store.getRunState(runId))[stateKey] ?? {});
+    const policy = {
+        approvers: options.approvers,
+        approverScope: options.approverScope,
+    };
     if (stepState.status === 'pending') {
         await store.setStepRunning(stepState.stepId);
+        record = { ...record, policy };
         if (options.expiry !== undefined && !record.expiresAt) {
             const expiry = getDurationInMilliseconds(options.expiry);
             record = {
@@ -83,14 +120,36 @@ export const evaluateApprovalStep = async (store, runId, reason, approvalStepNam
             await store.updateRunState(runId, stateKey, record);
             await store.scheduleRunWake(runId, expiry);
         }
+        else {
+            await store.updateRunState(runId, stateKey, record);
+        }
     }
     if (record.decision !== undefined) {
+        const refusal = approvalPolicyRefusal(policy, await store.getRunOwner(runId), record.decidedBy);
+        if (refusal) {
+            await store.updateRunState(runId, stateKey, {
+                ...record,
+                decision: undefined,
+                decidedAt: undefined,
+                decidedBy: undefined,
+                error: [{ message: refusal }],
+            });
+            await store.auditApproval({
+                runId,
+                reason,
+                outcome: 'denied',
+                decidedBy: record.decidedBy,
+                refusal,
+            });
+            throw new WorkflowSuspendedException(runId, reason);
+        }
         const validation = await options.schema['~standard'].validate(record.decision);
         if (validation.issues) {
             await store.updateRunState(runId, stateKey, {
                 ...record,
                 decision: undefined,
                 decidedAt: undefined,
+                decidedBy: undefined,
                 error: validation.issues.map((issue) => ({
                     message: issue.message,
                     path: issue.path?.map((segment) => typeof segment === 'object' ? segment.key : segment),
@@ -98,9 +157,13 @@ export const evaluateApprovalStep = async (store, runId, reason, approvalStepNam
             });
             throw new WorkflowSuspendedException(runId, reason);
         }
+        // Spread rather than assigned, so a gate answered without a session keeps
+        // the shape it had before there was anything to record.
         const outcome = {
             status: 'decided',
             data: validation.value,
+            ...(record.decidedBy ? { decidedBy: record.decidedBy } : {}),
+            ...(record.decidedAt ? { decidedAt: record.decidedAt } : {}),
         };
         await store.setStepResult(stepState.stepId, outcome);
         return outcome;

package/dist/wirings/workflow/workflow-run-ownership.d.ts

@@ -6,7 +6,8 @@ export declare class WorkflowRunForbiddenError extends ForbiddenError {
 }
 /**
  * A run started through a session records that session's user as its owner, and
- * only that user may read it or answer its approval gates.
+ * only that user may read it. Who may *answer* a run's approval gates is the
+ * gate's own declaration — see `approvers` on `workflow.approval()`.
  *
  * A run with no recorded owner — started by a trigger, a scheduler, or a route
  * wired without auth — has nobody to compare a caller against, so ownership is

package/dist/wirings/workflow/workflow-run-ownership.js

@@ -11,7 +11,8 @@ addError(WorkflowRunForbiddenError, {
 });
 /**
  * A run started through a session records that session's user as its owner, and
- * only that user may read it or answer its approval gates.
+ * only that user may read it. Who may *answer* a run's approval gates is the
+ * gate's own declaration — see `approvers` on `workflow.approval()`.
  *
  * A run with no recorded owner — started by a trigger, a scheduler, or a route
  * wired without auth — has nobody to compare a caller against, so ownership is

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

@@ -2,7 +2,7 @@ import type { SerializedError, CommonWireMeta } from '../../types/core.types.js'
 import type { CorePikkuFunctionConfig, CorePikkuFunctionHook } from '../../function/functions.types.js';
 import type { GroupConcurrencyConfig } from '../queue/queue.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, 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 './dsl/workflow-dsl.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 './dsl/workflow-dsl.types.js';
 export type { ScenarioStepPhase, ScenarioStepOptions, PikkuScenarioStepWire, PikkuBrowserWire, ScenarioBrowserProvider, } from './scenario-step.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {

package/knowledge/decisions/internals/addon-pikku-meta-ships-at-the-package-root-or-under-dist.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: An addon's .pikku meta ships at the package root or under dist, and readers probe both
+description: The layout depends on the addon's build and files field, so a consumer resolving the directory by path must try `<pkg>/.pikku` and `<pkg>/dist/.pikku` before concluding an addon declares nothing
+tags: services
+---
+
+# An addon's .pikku meta ships at the package root or under dist, and readers probe both
+
+An addon generates `.pikku/` at its project root, and whether that directory
+reaches the published tarball at the root or inside `dist/` depends on the
+addon's own `tsconfig` and `files` — both layouts are in the wild and both are
+supported. The published `exports` map hides the difference for anyone
+resolving by specifier: `"./.pikku/*"` points at wherever it landed, so
+`require.resolve('<pkg>/.pikku/scopes/pikku-scopes-meta.gen.json')` works for
+either shape, and that is the resolution every consumer should prefer.
+
+Code that builds the path itself must probe both. `addonPikkuDir`
+(`packages/addon/pikku-console/src/lib/derive-instance-overrides.ts`) tries
+`<pkg>/.pikku` then `<pkg>/dist/.pikku` and returns `null` when neither exists.
+The reason to say so out loud is the failure mode: a reader that assumes the
+root finds nothing under a `dist`-shipping addon and cannot distinguish that
+from an addon that declares no secrets, variables or scopes at all. Both answers
+are "empty", and the wrong one is indistinguishable from a correct one until
+something downstream reports an addon as ready when its secrets were never
+checked.
+
+**What this rules out:** hardcoding either path in a consumer, and treating a
+missing directory as evidence an addon declares nothing without having tried
+both. It also rules out normalising the layout by making the CLI move the
+directory at publish time — the export map already makes the layout private to
+the package, and the addons shipping each shape are already published.

package/knowledge/decisions/internals/an-addon-scope-root-loses-to-a-root-the-host-already-declares.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: An addon's scope root loses to a root the host app already declares
+description: loadAddonFunctionsMeta merges addon scope trees by root name, first declaration wins, so an addon sharing a root with its host contributes nothing — silently
+tags: services
+---
+
+# An addon's scope root loses to a root the host app already declares
+
+`loadAddonFunctionsMeta`
+(`packages/inspector/src/utils/load-addon-functions-meta.ts`) reads each wired
+addon's `pikku-scopes-meta.gen.json` and pushes its entries into
+`state.scopes.definitions`, skipping any whose root name is already present. The
+host app's own declarations were inspected first, so the host always wins.
+
+The skip is per **root**, not per node. An addon declaring `admin.console.*` in
+an app that declares `admin` contributes none of it — not the root it shares,
+and not the branch the app never declared. Nothing errors: the scopes simply do
+not exist, so `ScopeId` never gains them, no role can be granted one, and every
+addon function requiring one denies everybody. The failure surfaces as a
+`MissingScopeError` against a scope that cannot be granted, which reads as a
+permissions bug rather than a merge that dropped.
+
+This is a different rule from
+[scope roots may be co-declared by an addon and its host
+app](scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md): that one
+is about `flattenScopeDefinitions` deduping ids *within* a build where both
+declarations are present and identical. This one is about the addon's copy never
+arriving. The consequence for addon authors is the same either way — own a root
+outright, named for the package or vendor, and nest everything under it. It is
+why `@pikku/addon-console` declares `pikku:console:*` rather than
+`admin:console:*`.
+
+**What this rules out:** shipping an addon whose scopes hang off a root a host
+is likely to declare, and deep-merging the two trees here so both survive. A
+merge would have to reconcile conflicting descriptions and display names for the
+shared nodes, and would let an addon graft capabilities onto the host's `admin`
+tree — where a role granting `admin` would pick them up without anyone having
+asked for them.