@pikku/core 0.12.143 → 0.12.145

package/dist/{services → wirings/virtual-user}/http-virtual-users.d.ts

@@ -1,6 +1,7 @@
-import type { ScenarioVirtualUser, ResolvedVirtualUser, ScenarioVirtualUsers, ScenarioInvokeOptions, ScenarioHttpResponse } from './virtual-users-service.js';
-import type { ConverseOptions, ConversationVerdict } from '../wirings/virtual-user/conversation/conversation.types.js';
-import { type VirtualUserSignIn } from './virtual-user-sign-in.js';
+import type { ScenarioVirtualUser, ResolvedVirtualUser, ScenarioVirtualUsers, ScenarioInvokeOptions, ScenarioHttpResponse } from '../../services/virtual-users-service.js';
+import type { ConverseOptions, ConversationVerdict } from './conversation/conversation.types.js';
+import { type VirtualUserSignIn } from '../../services/virtual-user-sign-in.js';
+/** How `createHttpVirtualUsers` reaches the target app and signs each virtual user in. */
 export interface HttpVirtualUsersConfig {
     /**
      * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.

package/dist/{services → wirings/virtual-user}/http-virtual-users.js

@@ -1,9 +1,9 @@
-import { readScenarioHttpResponse } from './virtual-users-service.js';
-import { runConversation } from '../wirings/virtual-user/conversation/run-conversation.js';
-import { createCookieJar, } from './scenario-cookie-jar.js';
-import { authMount } from './virtual-user-sign-in.js';
-import { getSingletonServices } from '../pikku-state.js';
-import { AIProviderNotConfiguredError } from '../errors/errors.js';
+import { readScenarioHttpResponse } from '../../services/virtual-users-service.js';
+import { runConversation } from './conversation/run-conversation.js';
+import { createCookieJar, } from '../../services/scenario-cookie-jar.js';
+import { authMount, } from '../../services/virtual-user-sign-in.js';
+import { getSingletonServices } from '../../pikku-state.js';
+import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 /**
  * Default HTTP-backed virtual user. Signs in lazily on first invoke, holds the
  * session cookies for its lifetime, and re-logs-in once on a 401 mid-run (long

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

@@ -49,7 +49,7 @@ export type { CoreVirtualUser, CoreVirtualUsers, VirtualUserAccountMeta, Virtual
  * imports services, which only a bundler could remove and an unbundled Node or
  * Lambda deploy would load outright.
  */
-export { HttpVirtualUser, createHttpVirtualUsers, type HttpVirtualUsersConfig, } from '../../services/http-virtual-users.js';
+export { HttpVirtualUser, createHttpVirtualUsers, type HttpVirtualUsersConfig, } from './http-virtual-users.js';
 export { statementSignIn, inProcessSignIn, authMount, type VirtualUserSignIn, type VirtualUserStatementMint, type StatementSignInOptions, type InProcessAuth, } from '../../services/virtual-user-sign-in.js';
 export { createCookieJar, type ScenarioCookieJar, } from '../../services/scenario-cookie-jar.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/virtual-users-service.js';

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

@@ -23,7 +23,7 @@ export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './virtual-
  * imports services, which only a bundler could remove and an unbundled Node or
  * Lambda deploy would load outright.
  */
-export { HttpVirtualUser, createHttpVirtualUsers, } from '../../services/http-virtual-users.js';
+export { HttpVirtualUser, createHttpVirtualUsers, } from './http-virtual-users.js';
 export { statementSignIn, inProcessSignIn, authMount, } from '../../services/virtual-user-sign-in.js';
 export { createCookieJar, } from '../../services/scenario-cookie-jar.js';
 export { postScenarioJson, readScenarioHttpResponse, } from '../../services/virtual-users-service.js';

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

@@ -1,5 +1,5 @@
 import type { ResolvedVirtualUser } from '../../services/virtual-users-service.js';
-import type { VirtualUserLLM } from './conversation/run-conversation.js';
+import { type VirtualUserLLM } from './conversation/run-conversation.js';
 import { type VirtualUserTuning } from './virtual-user-dispositions.js';
 import type { ApiCatalogueEntry, IntentSource, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTally, VirtualUserTarget } from './virtual-user.types.js';
 /** What an app-specific oracle is shown about one call. */
@@ -13,6 +13,7 @@ export interface VirtualUserCallContext {
     step: number;
     disposition: VirtualUserDisposition;
 }
+/** Everything one autonomous virtual-user run is given. */
 export interface RunVirtualUserParams {
     /** The person being run — name, job title, personality, goals. */
     virtualUser: ResolvedVirtualUser;

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

@@ -1,3 +1,4 @@
+import { readObject, } from './conversation/run-conversation.js';
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, } from './virtual-user-catalogue.js';
 import { dispositionProfile, } from './virtual-user-dispositions.js';
@@ -39,20 +40,6 @@ const msg = (role, content) => ({
     content,
     createdAt: new Date(),
 });
-/** Read a structured result, falling back to parsing JSON out of the text. */
-const readObject = (result) => {
-    if (result.object && typeof result.object === 'object')
-        return result.object;
-    if (result.text) {
-        try {
-            return JSON.parse(result.text);
-        }
-        catch {
-            return null;
-        }
-    }
-    return null;
-};
 /**
  * The arguments for a call, however the model chose to spell them.
  *

package/dist/wirings/virtual-user/virtual-user-declaration.types.d.ts

@@ -120,9 +120,11 @@ export type CoreVirtualUser = {
 };
 /** Virtual users to declare, keyed by id. */
 export type CoreVirtualUsers = Record<string, CoreVirtualUser>;
+/** Generated metadata for the account a virtual user signs in with. */
 export type VirtualUserAccountMeta = {
     provider?: string;
 };
+/** Generated metadata for one declared virtual user. */
 export type VirtualUserMeta = {
     /** The key it was declared under. */
     id: string;
@@ -146,5 +148,7 @@ export type VirtualUserMeta = {
     app?: string;
     sourceFile?: string;
 };
+/** Every declared virtual user, in declaration order. */
 export type VirtualUserDefinitions = VirtualUserMeta[];
+/** Generated metadata for every declared virtual user, keyed by id. */
 export type VirtualUsersMeta = Record<string, VirtualUserMeta>;

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

@@ -3,7 +3,7 @@ import type { Logger } from '../../services/logger.js';
 import type { MetaService } from '../../services/meta-service.js';
 import type { VariablesService } from '../../services/variables-service.js';
 import type { AgentRunnerService } from '../../services/agent-runner-service.js';
-import type { HttpVirtualUsersConfig } from '../../services/http-virtual-users.js';
+import type { HttpVirtualUsersConfig } from './http-virtual-users.js';
 import type { ResolvedVirtualUser, ScenarioVirtualUsers } from '../../services/virtual-users-service.js';
 import type { VirtualUserEnvironment } from '../virtual-user/virtual-user-environments.js';
 import type { StepRecord, VirtualUserDisposition } from './virtual-user.types.js';
@@ -56,6 +56,11 @@ export declare const VIRTUAL_USER_VARIABLES: {
 export declare const runnableVirtualUser: (virtualUsers: ScaffoldVirtualUsers, virtualUserId: string) => ResolvedVirtualUser;
 /** The store, or the error naming the one to wire. */
 export declare const requireVirtualUserRunStore: (store: VirtualUserRunStore | undefined, reading?: boolean) => VirtualUserRunStore;
+/**
+ * The schedule store, or an error naming the one to wire.
+ *
+ * @throws Error when no `virtualUserScheduleStore` is wired.
+ */
 export declare const requireVirtualUserScheduleStore: (store: VirtualUserScheduleStore | undefined) => VirtualUserScheduleStore;
 /** What a caller asked for, before the declaration fills in what it left out. */
 export interface StartVirtualUserRunParams {
@@ -175,6 +180,9 @@ export declare const serializeVirtualUserSchedule: (schedule: VirtualUserSchedul
         goals: string[];
     };
 };
+/**
+ * What a request to create or change a virtual user's schedule carries. Omitted fields keep their current value.
+ */
 export interface WriteVirtualUserScheduleParams {
     store: VirtualUserScheduleStore | undefined;
     virtualUsers: ScaffoldVirtualUsers;
@@ -228,6 +236,7 @@ export declare const virtualUserScheduleRunInput: (schedule: VirtualUserSchedule
  * otherwise the only trace that a virtual user is still out there working.
  */
 export declare const logVirtualUserTick: (logger: Logger, result: VirtualUserTickResult) => void;
+/** What the scaffolded run worker needs to execute one recorded virtual-user run. */
 export interface ExecuteVirtualUserRunParams {
     runStore: VirtualUserRunStore | undefined;
     metaService: MetaService | undefined;

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

@@ -53,6 +53,11 @@ export const requireVirtualUserRunStore = (store, reading = false) => {
     }
     return store;
 };
+/**
+ * The schedule store, or an error naming the one to wire.
+ *
+ * @throws Error when no `virtualUserScheduleStore` is wired.
+ */
 export const requireVirtualUserScheduleStore = (store) => {
     if (!store) {
         throw new Error(MISSING_SCHEDULE_STORE);

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

@@ -21,6 +21,7 @@ export declare const STALE_RUN_AFTER_MS: number;
  * not the one that finds the most.
  */
 export declare const DEFAULT_MIN_INTERVAL_MS: number;
+/** The upper bound of the default cadence; see {@link DEFAULT_MIN_INTERVAL_MS}. */
 export declare const DEFAULT_MAX_INTERVAL_MS: number;
 /** Whether a row is the tick's business, for stores that cannot ask in a query. */
 export declare const isDue: (schedule: VirtualUserScheduleRecord, now: Date) => boolean;
@@ -33,6 +34,9 @@ export declare const isDue: (schedule: VirtualUserScheduleRecord, now: Date) =>
  */
 export declare const nextRunAt: (schedule: Pick<VirtualUserScheduleRecord, 'minIntervalMs' | 'maxIntervalMs'>, now: Date, random: () => number) => Date;
 export type VirtualUserSkipReason = 'in-flight' | 'dispatch-failed' | 'claimed-elsewhere';
+/**
+ * What one scheduling tick did: runs started, virtual users skipped and why, and stranded runs reaped.
+ */
 export interface VirtualUserTickResult {
     dispatched: {
         virtualUserId: string;
@@ -45,6 +49,7 @@ export interface VirtualUserTickResult {
     /** Runs found stranded at `running` and marked failed. */
     reaped: string[];
 }
+/** The stores a scheduling tick reads and the callback that starts a run. */
 export interface VirtualUserTickParams {
     schedules: VirtualUserScheduleStore;
     runs: VirtualUserRunStore;

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

@@ -19,6 +19,7 @@ export const STALE_RUN_AFTER_MS = 2 * 60 * 60 * 1000;
  * not the one that finds the most.
  */
 export const DEFAULT_MIN_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/** The upper bound of the default cadence; see {@link DEFAULT_MIN_INTERVAL_MS}. */
 export const DEFAULT_MAX_INTERVAL_MS = 24 * 60 * 60 * 1000;
 /** Whether a row is the tick's business, for stores that cannot ask in a query. */
 export const isDue = (schedule, now) => schedule.enabled && schedule.nextRunAt.getTime() <= now.getTime();

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

@@ -1,5 +1,6 @@
 import type { ScenarioVirtualUser } from '../../services/virtual-users-service.js';
 import type { VirtualUserTarget } from './virtual-user.types.js';
+/** Options for `virtualUserTarget`. */
 export interface VirtualUserTargetOptions {
     /** Model the virtual user uses for its side of a conversation with an agent. */
     model?: string;

package/dist/wirings/webhook/define-outgoing-webhook.d.ts

@@ -1,12 +1,14 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Safe } from '../../classification/secret-value.js';
 import type { SendWebhookInput, SendWebhookResult, WebhookService } from '../../services/webhook-service.js';
+/** An outgoing webhook event your app sends: its event name, a title and description for docs, and the schema its payload must satisfy. */
 export type CoreOutgoingWebhook<Event extends string = string, Payload extends StandardSchemaV1 = StandardSchemaV1> = {
     event: Event;
     title: string;
     description?: string;
     payload: Payload;
 };
+/** Generated metadata for one outgoing webhook event. */
 export type OutgoingWebhookMeta = {
     event: string;
     title: string;
@@ -15,14 +17,32 @@ export type OutgoingWebhookMeta = {
     exportedName?: string;
     sourceFile?: string;
 };
+/** Generated metadata for every outgoing webhook event, keyed by event name. */
 export type OutgoingWebhooksMeta = Record<string, OutgoingWebhookMeta>;
+/** The payload type of an outgoing webhook, inferred from its schema's input type. */
 export type OutgoingWebhookPayloadOf<W> = W extends CoreOutgoingWebhook<string, infer S> ? StandardSchemaV1.InferInput<S> : never;
+/** Resolves the `data` a {@link TypedWebhookService.send} call must carry for its `event`: the event's payload when it is a known event, unconstrained otherwise. */
 export type OutgoingWebhookDataFor<TMap, Input> = Input extends {
     event: infer Event;
 } ? Event extends keyof TMap ? {
     data: Safe<TMap[Event]>;
 } : unknown : unknown;
+/**
+ * A `WebhookService` whose `send` checks `data` against the payload of the named event. An app's generated types supply the event-to-payload map.
+ *
+ * `data` must be {@link Safe}: a payload with a `SecretValue` anywhere in it
+ * fails to compile rather than being sent to a third party.
+ */
 export interface TypedWebhookService<TMap = Record<string, unknown>> extends Omit<WebhookService, 'send'> {
     send<const T extends SendWebhookInput>(input: Safe<T> & OutgoingWebhookDataFor<TMap, T>): Promise<SendWebhookResult>;
 }
+/**
+ * Declares an outgoing webhook event and its payload schema. Returns the definition unchanged.
+ *
+ * `pikku` collects these into the generated event-to-payload map, which is what
+ * makes `webhookService.send({ event, data })` type-check `data` against the
+ * schema. Defining an event does not send anything or register a URL.
+ *
+ * @param webhook - The event name, title, optional description, and payload schema.
+ */
 export declare const defineOutgoingWebhook: <const Event extends string, Payload extends StandardSchemaV1>(webhook: CoreOutgoingWebhook<Event, Payload>) => CoreOutgoingWebhook<Event, Payload>;

package/dist/wirings/webhook/define-outgoing-webhook.js

@@ -1 +1,10 @@
+/**
+ * Declares an outgoing webhook event and its payload schema. Returns the definition unchanged.
+ *
+ * `pikku` collects these into the generated event-to-payload map, which is what
+ * makes `webhookService.send({ event, data })` type-check `data` against the
+ * schema. Defining an event does not send anything or register a URL.
+ *
+ * @param webhook - The event name, title, optional description, and payload schema.
+ */
 export const defineOutgoingWebhook = (webhook) => webhook;

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

@@ -528,10 +528,7 @@ export interface WorkflowStepWire {
      */
     fromInvocationId?: string;
 }
-/**
- * Workflow wire object for DSL workflows
- * Provides workflow-specific capabilities to function execution
- */
+/** The outcome of the forward call a `compensate` function is undoing. */
 export type CompensatingFor<Out = unknown> = {
     ok: true;
     output: Out;
@@ -542,6 +539,10 @@ export type CompensatingFor<Out = unknown> = {
     error: SerializedError;
     stepName?: string;
 };
+/**
+ * Workflow wire object for DSL workflows
+ * Provides workflow-specific capabilities to function execution
+ */
 export interface PikkuWorkflowWire {
     /**
      * Set only while a function's `compensate` is running: the outcome of the
@@ -583,6 +584,9 @@ export interface PikkuWorkflowWire {
  * 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>;
+/**
+ * The workflow wire a scenario body receives: every workflow step, plus the expectation steps and the shared `context`.
+ */
 export interface PikkuScenarioWire<Out = unknown> extends PikkuWorkflowWire {
     /**
      * Scratch the body writes and the `before`/`after` hooks read. A hook is a

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

@@ -1 +1,8 @@
+/**
+ * Registers a workflow under its generated name. Called by generated code; an
+ * app declares workflows with `pikkuWorkflowFunc` and its relatives instead.
+ * Skipped with a warning when no metadata was generated for the name.
+ *
+ * @internal
+ */
 export declare const addWorkflow: (workflowName: string, workflowFunc: any, packageName?: string | null) => void;

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

@@ -1,5 +1,12 @@
 import { pikkuState } from '../../../pikku-state.js';
 import { addFunction } from '../../../function/function-runner.js';
+/**
+ * Registers a workflow under its generated name. Called by generated code; an
+ * app declares workflows with `pikkuWorkflowFunc` and its relatives instead.
+ * Skipped with a warning when no metadata was generated for the name.
+ *
+ * @internal
+ */
 export const addWorkflow = (workflowName, workflowFunc, packageName = null) => {
     const meta = pikkuState(packageName, 'workflows', 'meta');
     const workflowMeta = meta[workflowName];

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

@@ -1,6 +1,18 @@
 import type { CoreWorkflow } from './workflow.types.js';
 import type { CoreFeature, FeaturePlanEntry } from './scenario.types.js';
+/**
+ * Registers a scenario feature. Called by generated code for each `pikkuFeature`.
+ *
+ * @internal
+ */
 export declare const addFeature: (featureId: string, feature: CoreFeature, packageName?: string | null) => void;
+/**
+ * Matches each feature's scenarios to the workflow names they are registered
+ * under, merging feature and scenario tags. Entries that name a scenario no
+ * workflow registration holds come back in `unresolved`.
+ *
+ * @internal
+ */
 export declare const resolveFeatureScenarios: (features: Map<string, CoreFeature>, registrations: Map<string, CoreWorkflow>) => {
     entries: FeaturePlanEntry[];
     unresolved: Array<{

package/dist/wirings/workflow/feature.js

@@ -1,7 +1,19 @@
 import { pikkuState } from '../../pikku-state.js';
+/**
+ * Registers a scenario feature. Called by generated code for each `pikkuFeature`.
+ *
+ * @internal
+ */
 export const addFeature = (featureId, feature, packageName = null) => {
     pikkuState(packageName, 'workflows', 'features').set(featureId, feature);
 };
+/**
+ * Matches each feature's scenarios to the workflow names they are registered
+ * under, merging feature and scenario tags. Entries that name a scenario no
+ * workflow registration holds come back in `unresolved`.
+ *
+ * @internal
+ */
 export const resolveFeatureScenarios = (features, registrations) => {
     const nameByConfig = new Map();
     for (const [name, registration] of registrations) {

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

@@ -15,6 +15,11 @@ export type TypedRef<T> = RefValue & {
 type InputWithRefs<T> = {
     [K in keyof T]: T[K] | TypedRef<T[K]>;
 };
+/**
+ * Builds a typed graph-node map for a set of RPCs: given a node-id → RPC-name
+ * map and per-node settings, returns the {@link GraphNodeConfig} for every node,
+ * with refs typed against each RPC's input and output.
+ */
 export declare function createGraph<RPCMap extends Record<string, RPCHandler>>(): <const FuncMap extends Record<string, keyof RPCMap & string>>(funcMap: FuncMap, nodesOrBuilder?: GraphNodeConfigMap<FuncMap, RPCMap> | ((nodes: FuncMap) => GraphNodeConfigMap<FuncMap, RPCMap>)) => Record<Extract<keyof FuncMap, string>, GraphNodeConfig<Extract<keyof FuncMap, string>>>;
 type GraphNodeConfigMap<FuncMap extends Record<string, string>, RPCMap extends Record<string, RPCHandler>> = {
     [K in Extract<keyof FuncMap, string>]?: {

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

@@ -1,3 +1,8 @@
+/**
+ * Builds a typed graph-node map for a set of RPCs: given a node-id → RPC-name
+ * map and per-node settings, returns the {@link GraphNodeConfig} for every node,
+ * with refs typed against each RPC's input and output.
+ */
 export function createGraph() {
     return (funcMap, nodesOrBuilder) => {
         if (!nodesOrBuilder) {

package/dist/wirings/workflow/graph/template.d.ts

@@ -1,3 +1,4 @@
+/** A string interpolated at run time from other nodes' outputs, as `template` builds it. */
 export type TemplateString = {
     $template: {
         parts: string[];
@@ -9,6 +10,11 @@ export type TemplateString = {
 } & {
     __brand: 'TemplateString';
 };
+/**
+ * Builds a {@link TemplateString} for a graph node's input: each `$0`, `$1`, …
+ * in `templateStr` is replaced at run time by the value of the ref at that
+ * index. An index with no ref resolves to an unknown ref.
+ */
 export declare function template(templateStr: string, refs: Array<{
     $ref: string;
     path?: string;

package/dist/wirings/workflow/graph/template.js

@@ -1,3 +1,8 @@
+/**
+ * Builds a {@link TemplateString} for a graph node's input: each `$0`, `$1`, …
+ * in `templateStr` is replaced at run time by the value of the ref at that
+ * index. An index with no ref resolves to an unknown ref.
+ */
 export function template(templateStr, refs) {
     const parts = [];
     const expressions = [];

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

@@ -1,3 +1,4 @@
+/** What `pikkuWorkflowGraph` takes. */
 export interface PikkuWorkflowGraphConfig<FuncMap extends Record<string, string>, T> {
     /** Keeps the graph in the codebase but out of the build. */
     disabled?: true;
@@ -14,6 +15,7 @@ export interface PikkuWorkflowGraphConfig<FuncMap extends Record<string, string>
     /** Free text carried onto the rendered graph, for a reader who needs the reasoning the shape cannot show. */
     notes?: string[];
 }
+/** The marker `pikkuWorkflowGraph` returns; the graph itself is read from source by `pikku all`. */
 export interface PikkuWorkflowGraphResult {
     __type: 'pikkuWorkflowGraph';
     name?: string;
@@ -21,4 +23,14 @@ export interface PikkuWorkflowGraphResult {
     tags?: string[];
     notes?: string[];
 }
+/**
+ * Declares a workflow as a graph: each node names an RPC, and `config` says what
+ * feeds it and which nodes run next. The shape is data, so the console can draw
+ * it and a run records which branch it took.
+ *
+ * The inspector reads the graph from source at build time; at runtime this only
+ * returns a marker carrying the descriptive fields.
+ *
+ * @example snippet: workflowGraph
+ */
 export declare function pikkuWorkflowGraph<const FuncMap extends Record<string, string>>(config: PikkuWorkflowGraphConfig<FuncMap, any>): PikkuWorkflowGraphResult;

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

@@ -1,3 +1,13 @@
+/**
+ * Declares a workflow as a graph: each node names an RPC, and `config` says what
+ * feeds it and which nodes run next. The shape is data, so the console can draw
+ * it and a run records which branch it took.
+ *
+ * The inspector reads the graph from source at build time; at runtime this only
+ * returns a marker carrying the descriptive fields.
+ *
+ * @example snippet: workflowGraph
+ */
 export function pikkuWorkflowGraph(config) {
     return {
         __type: 'pikkuWorkflowGraph',

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

@@ -1,20 +1,31 @@
 import type { TemplateString } from './template.js';
+/** A reference to another node's output, or a path inside it, resolved when the node runs. */
 export interface RefValue {
     __isRef: true;
     nodeId: string;
     path?: string;
 }
 export declare const createRef: (nodeId: string, path?: string) => RefValue;
+/** Whether a value is a {@link RefValue}. */
 export declare const isRef: (value: unknown) => value is RefValue;
 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[]>;
+/** The `template` helper as a graph node's `input` builder receives it. */
 export type TemplateFn = (templateStr: string, refs: Array<{
     $ref: string;
     path?: string;
 }>) => TemplateString;
+/** Refers to the current element (or a path inside it) of a `forEach` node. */
 export type ItemFn = (path?: string) => RefValue;
+/**
+ * The upstream array a `forEach` node iterates: a node id, a ref, or a function returning a ref.
+ */
 export type ForEachConfig<NodeIds extends string = string> = NodeIds | RefValue | ((ref: RefFn<NodeIds>) => RefValue);
+/** Whether a `forEach` node's per-item instances run in parallel or one after another. */
 export type ForEachMode = 'parallel' | 'sequential';
+/**
+ * One node of a workflow graph: the RPC it runs, its input, its outgoing edges and its failure handling.
+ */
 export interface GraphNodeConfig<NodeIds extends string = string> {
     func: string;
     /**

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

@@ -3,6 +3,7 @@ export const createRef = (nodeId, path) => ({
     nodeId,
     path,
 });
+/** Whether a value is a {@link RefValue}. */
 export const isRef = (value) => typeof value === 'object' &&
     value !== null &&
     '__isRef' in value &&

package/dist/{services → wirings/workflow}/in-memory-workflow-service.d.ts

@@ -1,6 +1,11 @@
-import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
-import type { SerializedError } from '../errors/serialized-error.js';
-import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
+import { PikkuWorkflowService } from './pikku-workflow-service.js';
+import type { SerializedError } from '../../errors/serialized-error.js';
+import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
+/**
+ * A workflow service that keeps runs, steps and state in memory and runs every
+ * step inline. For tests and local development: nothing survives a restart, and
+ * it does not wire workflow queues or coordinate with another process.
+ */
 export declare class InMemoryWorkflowService extends PikkuWorkflowService implements WorkflowRunService {
     constructor(options?: WorkflowQueueOptions);
     private sleepTimers;

package/dist/{services → wirings/workflow}/in-memory-workflow-service.js

@@ -1,8 +1,13 @@
-import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
-import { isExpectedError } from '../errors/error-handler.js';
-import { isStepLeaseLive } from '../wirings/workflow/workflow-constants.js';
-import { WorkflowStepSupersededError } from '../wirings/workflow/workflow-errors.js';
+import { PikkuWorkflowService } from './pikku-workflow-service.js';
+import { isExpectedError } from '../../errors/error-handler.js';
+import { isStepLeaseLive } from './workflow-constants.js';
+import { WorkflowStepSupersededError } from './workflow-errors.js';
 // knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
+/**
+ * A workflow service that keeps runs, steps and state in memory and runs every
+ * step inline. For tests and local development: nothing survives a restart, and
+ * it does not wire workflow queues or coordinate with another process.
+ */
 export class InMemoryWorkflowService extends PikkuWorkflowService {
     constructor(options = {}) {
         super({ ...options, wireQueues: false });

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

@@ -1,5 +1,5 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
+import { InMemoryWorkflowService } from './in-memory-workflow-service.js';
 import type { RunLifecycleContext, WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
 import type { ScenarioVirtualUsers } from '../../services/virtual-users-service.js';

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

@@ -3,7 +3,7 @@ import { getSingletonServices, getCreateWireServices, pikkuState, } from '../../
 import { getDurationInMilliseconds } from '../../time-utils.js';
 import { closeWireServices } from '../../utils.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
-import { InMemoryWorkflowService } from '../../services/in-memory-workflow-service.js';
+import { InMemoryWorkflowService } from './in-memory-workflow-service.js';
 import { runScheduledTask } from '../scheduler/scheduler-runner.js';
 import { WorkflowStepNameNotString } from './workflow-errors.js';
 import { resolveScenarioSurfaces, witnessesAgree } from './scenario-surface.js';
@@ -497,7 +497,7 @@ export class PikkuScenarioService {
             apiUrl,
             appUrl: (await variables.get('APP_URL')) ?? undefined,
         };
-        const { createHttpVirtualUsers } = await import('../../services/http-virtual-users.js');
+        const { createHttpVirtualUsers } = await import('../virtual-user/http-virtual-users.js');
         const { inProcessSignIn } = await import('../../services/virtual-user-sign-in.js');
         return createHttpVirtualUsers({
             apiUrl,

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

@@ -8,6 +8,7 @@ import type { PikkuRPC } from '../rpc/rpc-types.js';
 import { type RunTimeline, type ReconstructedRunState } from './run-timeline.js';
 import type { WorkflowRunEngine, WorkflowRunExtension } from './workflow-run-engine.types.js';
 import type { LeaseService } from '../../services/lease-service.js';
+/** The workflow engine; subclasses supply storage. Leases serialise runs and step claims over a shared store. */
 export declare abstract class PikkuWorkflowService implements WorkflowService {
     private runExtension?;
     private runContexts;

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

@@ -26,6 +26,7 @@ import { runDslWorkflowPass } from './workflow-dsl-pass.js';
 import { childRunFailure, failRunOrUnwind, isUnwound, compensatingForStep, cancelAndUnwind, createUnwindHost, driveUnwind, recordHasCompensation, isChildWorkflowRecord, } from './workflow-compensation.js';
 import { runVersionMismatchFallback } from './workflow-version-fallback.js';
 import { RedispatchBackoff, sweepStalledRuns, sweepUndispatchedSteps, } from './workflow-recovery.js';
+/** The workflow engine; subclasses supply storage. Leases serialise runs and step claims over a shared store. */
 export class PikkuWorkflowService {
     runExtension;
     runContexts = new Map();

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

@@ -1,5 +1,6 @@
 import type { SerializedError } from '../../errors/serialized-error.js';
 import type { StepState, StepStatus } from './workflow.types.js';
+/** One lifecycle transition of one step, in run order. */
 export interface RunTimelineEvent {
     seq: number;
     at: Date;
@@ -11,11 +12,19 @@ export interface RunTimelineEvent {
     result?: unknown;
     error?: SerializedError;
 }
+/** Every step transition in a run, ordered by time. */
 export type RunTimeline = RunTimelineEvent[];
+/** One stored step attempt, with the name of the step it belongs to. */
 export type HistoryEntry = StepState & {
     stepName: string;
 };
+/**
+ * Flattens a run's step history into a {@link RunTimeline}: one event per
+ * recorded transition, ordered by timestamp, then lifecycle order, then history
+ * order, and numbered with `seq`.
+ */
 export declare function buildRunTimeline(history: HistoryEntry[]): RunTimeline;
+/** A step as it stood at a point in a run's timeline. */
 export interface ReconstructedStep {
     stepName: string;
     compensating: boolean;
@@ -25,7 +34,11 @@ export interface ReconstructedStep {
     result?: unknown;
     error?: SerializedError;
 }
+/**
+ * Where a reconstructed run stood: nothing started, a step in flight, a step failed, or nothing in flight.
+ */
 export type RunPhase = 'pending' | 'running' | 'failed' | 'idle';
+/** A run's steps, results and path as of one point in its timeline. */
 export interface ReconstructedRunState {
     /** seq of the last applied event, or -1 if the point precedes all events. */
     seq: number;
@@ -35,5 +48,13 @@ export interface ReconstructedRunState {
     path: string[];
     phase: RunPhase;
 }
+/**
+ * Replays a timeline up to a point, for stepping through a run after the fact.
+ *
+ * @param timeline - The run's timeline, from {@link buildRunTimeline}.
+ * @param at - The last event to apply, by `seq`, or every event up to a time.
+ * @returns The run as it stood at that point.
+ */
 export declare function reconstructStateAt(timeline: RunTimeline, at: number | Date): ReconstructedRunState;
+/** The run as its whole timeline leaves it. */
 export declare function reconstructFinalState(timeline: RunTimeline): ReconstructedRunState;