@pikku/core 0.12.70 → 0.12.71

package/CHANGELOG.md

@@ -1,3 +1,91 @@
+## 0.12.71
+
+### Patch Changes
+
+- 8a2c993: Make the workflow service cheaper to run, and fix two ways it lost state.
+
+  The SQL workflow tables had no indexes at all, so every step read, every
+  history walk and every orchestrator tick was a sequential scan; five indexes
+  now cover the columns the engine actually queries by. A replay used to ask for
+  each step's row individually — O(N) reads per replay, O(N^2) over a run — and
+  now takes one read of the run's steps and serves the walk from it. A step
+  transition wrote the step row and its history row as two separate statements,
+  so a crash between them left a step saying `succeeded` whose history still said
+  `running`; both halves are now one transaction, and the history row is found by
+  attempt number rather than by sorting on `created_at`, which two attempts can
+  share. Resolving a dynamic workflow read and parsed every AI-generated workflow
+  in the deployment to `.find()` one by name; it is a point lookup now.
+
+  Waiting on a run no longer polls at a fixed interval. `pollIntervalMs` became a
+  ceiling rather than a cadence: polling starts at 10ms and widens towards it, so
+  a workflow that finishes in milliseconds is no longer held for a full second,
+  and a long-running one is not read at full rate for its whole life.
+
+  Two backend-specific defects: Redis kept a run's state as one JSON blob and
+  read-modified-wrote it, so parallel branches setting different variables
+  overwrote each other — state is a field per variable now, with the old blob
+  still read underneath so runs in flight keep what they had. Mongo's
+  `setStepScheduled` never wrote history, leaving a queued step reading as never
+  dispatched.
+
+  Also: dispatch no longer JSON round-trips every step payload before handing it
+  to a queue that serialises it anyway — the in-process dev queue, which is the
+  only one that was relying on it, does it itself now.
+
+  Two more defects. A transition whose step had no live attempt wrote its status
+  to the step row and silently nothing to history — the exact divergence the
+  transaction exists to prevent — and now repairs the step and writes the
+  missing row. And resolving a dynamic workflow was non-deterministic on all
+  three backends: a name can hold several active versions, and none of them
+  ordered the candidates, so which one ran could change between two calls
+  reading identical data. The newest version wins, with the graph hash breaking
+  a tie.
+
+  The two attempt columns and the five indexes are declared in the workflow
+  schema, so a fresh database gets them at boot. An existing one gets them from
+  a migration — `pikku db generate` writes the declaration down — rather than
+  from DDL issued at boot.
+
+- a261006: **Breaking:** removed dynamic workflows — runtime-defined workflow graphs stored in the database and resolved by name instead of by codegen.
+
+  The feature was already half-gone. Its authoring surface (`createAgentWorkflow`, `saveAgentWorkflow`, `listAgentWorkflows`, `executeAgentWorkflow`, and the AI-agent instruction builder) was deleted in April 2026 along with its entire e2e suite, and nothing has written a dynamic workflow since. What remained could not execute one either: `executeAgentWorkflow` gated on `pikkuState('workflows', 'meta')`, which only codegen ever populates, so a graph that existed solely in the database was never findable. The two backend families had also drifted onto different `source` sentinels (`'ai-agent'` vs `'dynamic-workflow'`), and the two Redis implementations disagreed on key escaping — so at least one of them matched nothing. Rather than keep shipping plumbing for a path no caller could complete, it is removed until it can be reintroduced deliberately.
+
+  Removed:
+  - `getAIGeneratedWorkflows` from `WorkflowService` and `WorkflowRunService`, and from every backend (in-memory, Redis, MongoDB, Kysely, and the Cloudflare Durable Object service and client — the last two were already a `return []` stub and a rejection).
+  - The database-lookup fallbacks in `startWorkflow` and `runWorkflowJob` that resolved a workflow name against stored graphs when static meta had no match.
+  - `'dynamic-workflow'` from the `WorkflowRuntimeMeta['source']` union.
+  - `validateWorkflowWiring` and `computeEntryNodeIds` from `@pikku/core/workflow`. These validated AI-authored graphs and had no callers in core; the inspector keeps its own private entry-node computation for static graph wiring, which is unaffected.
+  - The `workflow-created` AI stream event and its AG-UI `pikku:workflow-created` custom event. Its only emitter went with the April deletion, so it could never fire.
+  - The console's `console:getAIWorkflows` RPC, the `useAIWorkflows` hook, the "Dynamic" workflow filter and badge, and the trigger-schema scraper that derived an input form from a stored graph's `$ref` bindings.
+
+  Kept, because static graph workflows depend on them and this is not a change to versioning:
+  - `upsertWorkflowVersion`, `getWorkflowVersion`, `updateWorkflowVersionStatus`, and the `workflowVersions` storage in every backend. These back version-mismatch replay: when a deployed graph's hash changes, in-flight runs continue against the exact graph they started on. No schema migration is needed — the table, its columns, and its `(workflowName, graphHash)` upsert key are unchanged.
+  - `generateMermaidDiagram`, which renders any workflow graph and is not specific to dynamic ones.
+
+  Static `pikkuWorkflowGraph` and DSL workflows are entirely unaffected: they resolve from codegen'd meta, which was always the only path that worked.
+
+  To revive this post-MVP, the deleted authoring code is recoverable in full — its prompt engineering (a compact tool table upfront, full schemas with flattened dotted output paths returned only after a validation failure) is worth reading before rewriting:
+
+  ```
+  git show f52f3308b^:packages/core/src/wirings/ai-agent/agent-dynamic-workflow.ts
+  git show f52f3308b^:packages/core/src/wirings/workflow/graph/graph-validation.ts
+  git show f52f3308b --stat   # the April removal, incl. the three e2e feature files
+  ```
+
+  Note that reviving it needs more than restoring those files: the queued-step path (`executeWorkflowStep`), `onError` compensation, and sub-workflow resolution all read static meta only and would need a fallback for a graph that exists solely in the database.
+
+- 09973b9: Scenarios, features and steps no longer reach a deployment.
+
+  Steps were already held back from the app bootstrap, so a deployed server never imported a step body. Everything _about_ a scenario still travelled with the application: a `pikkuScenario(...)` is a function, so its name, schemas and hashes sat in the app function meta; the schemas it and its steps validate against sat in the app's `register.gen.ts` — on one project 458 of the 582 registered schemas belonged to tests; its name sat in the internal RPC meta; and because a scenario is _also_ a workflow, the inspector synthesised a `wf-orchestrator-<scenario>` queue worker for each one. The deploy analyzer, which reads inspector state rather than the partitioned codegen output, then read all of it back as application code: a unit per scenario, a `WorkflowDefinition` per scenario, and a real queue per scenario. A 13-scenario suite turned into 13 production queues named after tests, waiting for a provider to create them.
+
+  The existing scenario/app partition is now applied everywhere it was missing. `FunctionRuntimeMeta` gains a `scenario` marker (the counterpart of `scenarioStep`) so a scenario body is recognisable without walking the workflow graph; scenario bodies join their steps on the scenario side of the function-meta and registration split; schemas only a scenario or step needs are written and registered under `.pikku/scenarios/schemas/` and imported by the scenario bootstrap alone; scenario names are dropped from the internal RPC meta; no orchestrator queue worker is synthesised for a scenario; and the deploy analyzer drops both scenario functions and scenario workflows before it decides what a deployment contains.
+
+  The MCP metas are keyed by wiring rather than by function, so a scenario wired as an MCP tool, resource or prompt was the one id that still reached the manifest after the function and workflow filters — as an endpoint on the gateway plus a gateway dependency on a unit that was never emitted. Those ids are now filtered too.
+
+  `scenarioSchemaDirectory` is rejected when it resolves to the same directory as `schemaDirectory`. A schema write owns its directory — it emits `register.gen.ts` and prunes every schema file its own required-set does not name — so sharing one would replace the application register with the scenario-only one and delete the app's schema files, which nothing downstream can detect.
+
+  Nothing changes for `pikku scenario run` — the scenario bootstrap still registers every scenario, feature, step, meta and schema. What changes is that a bundle stops carrying them.
+
 ## 0.12.70
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 - present Yasser Fadl and Pikku contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/services/in-memory-queue-service.d.ts

@@ -5,6 +5,12 @@ import type { QueueService, JobOptions } from '../wirings/queue/queue.types.js';
  * a real queue — and redelivers a failed job up to `options.attempts` times with
  * backoff, so a transiently-failing workflow step recovers exactly as it would
  * on pg-boss/bullmq instead of being silently dropped on its first error.
+ *
+ * Payloads are JSON round-tripped on the way in, because every real backend
+ * puts the job on a wire (SQS body, Redis value, jsonb column) and the worker
+ * therefore never sees the caller's live object. Doing it here keeps dev
+ * behaviour honest, and keeps the callers — who cannot know which backend they
+ * are talking to — from having to serialise defensively.
  */
 export declare class InMemoryQueueService implements QueueService {
     readonly supportsResults = false;

package/dist/services/in-memory-queue-service.js

@@ -5,6 +5,12 @@ import { runQueueJob } from '../wirings/queue/queue-runner.js';
  * a real queue — and redelivers a failed job up to `options.attempts` times with
  * backoff, so a transiently-failing workflow step recovers exactly as it would
  * on pg-boss/bullmq instead of being silently dropped on its first error.
+ *
+ * Payloads are JSON round-tripped on the way in, because every real backend
+ * puts the job on a wire (SQS body, Redis value, jsonb column) and the worker
+ * therefore never sees the caller's live object. Doing it here keeps dev
+ * behaviour honest, and keeps the callers — who cannot know which backend they
+ * are talking to — from having to serialise defensively.
  */
 export class InMemoryQueueService {
     supportsResults = false;
@@ -14,12 +20,13 @@ export class InMemoryQueueService {
         const maxAttempts = Math.max(1, options?.attempts ?? 1);
         let attemptsMade = 0;
         const createdAt = new Date();
+        const payload = data === undefined ? data : JSON.parse(JSON.stringify(data));
         const runAttempt = async () => {
             attemptsMade++;
             const job = {
                 id: jobId,
                 queueName,
-                data,
+                data: payload,
                 status: () => 'active',
                 metadata: () => ({ attemptsMade, maxAttempts, createdAt }),
                 pikkuUserId: options?.pikkuUserId,

package/dist/services/in-memory-workflow-service.d.ts

@@ -66,6 +66,9 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
         branchKeys: Record<string, string>;
     }>;
     getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
+    protected listStepStates(runId: string): Promise<Array<StepState & {
+        stepName: string;
+    }>>;
     getStepInstances(runId: string): Promise<Array<{
         stepName: string;
         status: StepStatus;
@@ -82,9 +85,4 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
         graph: any;
         source: string;
     } | null>;
-    getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
-        workflowName: string;
-        graphHash: string;
-        graph: any;
-    }>>;
 }

package/dist/services/in-memory-workflow-service.js

@@ -324,6 +324,16 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         }
         return nodeIds.filter((id) => !existingSteps.has(id));
     }
+    async listStepStates(runId) {
+        const prefix = `${runId}:`;
+        const steps = [];
+        for (const [key, step] of this.steps.entries()) {
+            if (!key.startsWith(prefix))
+                continue;
+            steps.push({ ...step, stepName: key.substring(prefix.length) });
+        }
+        return steps;
+    }
     async getStepInstances(runId) {
         const prefix = `${runId}:`;
         const instances = [];
@@ -387,23 +397,4 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
             return null;
         return { graph: version.graph, source: version.source };
     }
-    async getAIGeneratedWorkflows(agentName) {
-        const results = [];
-        const prefix = agentName ? `ai:${agentName}:` : 'ai:';
-        for (const [key, value] of this.workflowVersions) {
-            if (value.source !== 'ai-agent' || value.status !== 'active')
-                continue;
-            const separatorIdx = key.lastIndexOf(':');
-            const wfName = key.substring(0, separatorIdx);
-            const hash = key.substring(separatorIdx + 1);
-            if (wfName.startsWith(prefix)) {
-                results.push({
-                    workflowName: wfName,
-                    graphHash: hash,
-                    graph: value.graph,
-                });
-            }
-        }
-        return results;
-    }
 }

package/dist/services/workflow-service.d.ts

@@ -35,6 +35,13 @@ export interface WorkflowService {
     }): Promise<{
         runId: string;
     }>;
+    /**
+     * Start a run and wait for it to end.
+     *
+     * `pollIntervalMs` is the ceiling on the wait between reads of the run, not a
+     * fixed cadence: polling starts far shorter than this and widens towards it,
+     * so a run that finishes quickly is not held for a whole interval.
+     */
     runToCompletion<I>(name: string, input: I, rpcService: any, options?: {
         pollIntervalMs?: number;
         wire?: WorkflowRunWire;
@@ -60,9 +67,4 @@ export interface WorkflowService {
         graph: any;
         source: string;
     } | null>;
-    getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
-        workflowName: string;
-        graphHash: string;
-        graph: any;
-    }>>;
 }

package/dist/types/core.types.d.ts

@@ -95,6 +95,13 @@ export type FunctionRuntimeMeta = {
      * may drive a browser or assert against fixtures.
      */
     scenarioStep?: boolean;
+    /**
+     * The function behind a `pikkuScenario(...)` — a scenario's own body, as
+     * opposed to the steps it calls. Marked for the same reason as
+     * `scenarioStep`: a scenario is only ever run by `pikku scenario run`, so it
+     * has to be held back from the app bootstrap and from every deployed unit.
+     */
+    scenario?: boolean;
     mcp?: boolean;
     readonly?: boolean;
     deploy?: 'serverless' | 'server' | 'auto';

package/dist/wirings/ai-agent/ai-agent-agui.js

@@ -256,14 +256,6 @@ export function wrapChannelWithAGUI(inner, options) {
                     });
                     break;
                 }
-                case 'workflow-created': {
-                    send({
-                        type: 'CUSTOM',
-                        name: 'pikku:workflow-created',
-                        value: { workflowName: event.workflowName, graph: event.graph },
-                    });
-                    break;
-                }
                 case 'agent-call': {
                     send({
                         type: 'CUSTOM',

package/dist/wirings/ai-agent/ai-agent-prepare.js

@@ -312,8 +312,7 @@ export function createScopedChannel(parent, agentName, session) {
                 event.type === 'tool-call' ||
                 event.type === 'tool-result' ||
                 event.type === 'usage' ||
-                event.type === 'error' ||
-                event.type === 'workflow-created') {
+                event.type === 'error') {
                 parent.send({ ...event, agent: agentName, session });
             }
             else {

package/dist/wirings/ai-agent/ai-agent.types.d.ts

@@ -346,12 +346,6 @@ export type AIStreamEvent = {
     type: 'audio-done';
     agent?: string;
     session?: string;
-} | {
-    type: 'workflow-created';
-    workflowName: string;
-    graph: any;
-    agent?: string;
-    session?: string;
 } | {
     type: 'data';
     name: string;

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

@@ -399,8 +399,9 @@ export async function continueGraph(workflowService, runId, graphName, overrideM
         }
         return;
     }
-    const run = await workflowService.getRun(runId);
-    const triggerInput = run?.input;
+    // The same run read a few lines up: nothing between here and there writes it,
+    // and `input` is fixed at creation anyway.
+    const triggerInput = currentRun?.input;
     for (const fire of plan.toFire) {
         const node = nodes[fire.logical];
         if (!node?.rpcName)

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

@@ -1,3 +1 @@
-export declare function computeEntryNodeIds(nodes: Record<string, any>): string[];
-export declare function validateWorkflowWiring(nodes: Record<string, any>, toolNames: string[]): string[];
 export declare function generateMermaidDiagram(workflowName: string, nodes: Record<string, any>, entryNodeIds: string[]): string;

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

@@ -1,5 +1,3 @@
-import { pikkuState } from '../../../pikku-state.js';
-import { resolveNamespace } from '../../rpc/rpc-runner.js';
 function normalizeTargets(value) {
     if (!value)
         return [];
@@ -16,146 +14,6 @@ function normalizeTargets(value) {
     }
     return [];
 }
-function collectRefs(value, refs) {
-    if (typeof value === 'object' &&
-        value !== null &&
-        '$ref' in value &&
-        typeof value.$ref === 'string') {
-        refs.add(value.$ref);
-        return;
-    }
-    if (Array.isArray(value)) {
-        for (const item of value)
-            collectRefs(item, refs);
-        return;
-    }
-    if (typeof value === 'object' && value !== null) {
-        for (const v of Object.values(value))
-            collectRefs(v, refs);
-    }
-}
-function resolveToolMeta(toolName) {
-    const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null;
-    if (resolved) {
-        const fnMeta = pikkuState(resolved.package, 'function', 'meta')[resolved.function];
-        const schemas = pikkuState(resolved.package, 'misc', 'schemas');
-        return fnMeta ? { fnMeta, schemas } : null;
-    }
-    const rpcMeta = pikkuState(null, 'rpc', 'meta');
-    const pikkuFuncId = rpcMeta[toolName];
-    if (!pikkuFuncId)
-        return null;
-    const fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId];
-    const schemas = pikkuState(null, 'misc', 'schemas');
-    return fnMeta ? { fnMeta, schemas } : null;
-}
-export function computeEntryNodeIds(nodes) {
-    const referenced = new Set();
-    for (const node of Object.values(nodes)) {
-        if (node.next) {
-            for (const target of normalizeTargets(node.next)) {
-                referenced.add(target);
-            }
-        }
-        if (node.onError) {
-            for (const target of normalizeTargets(node.onError)) {
-                referenced.add(target);
-            }
-        }
-    }
-    return Object.keys(nodes).filter((id) => !referenced.has(id));
-}
-export function validateWorkflowWiring(nodes, toolNames) {
-    const errors = [];
-    const nodeIds = new Set(Object.keys(nodes));
-    const toolSet = new Set(toolNames);
-    for (const [nodeId, node] of Object.entries(nodes)) {
-        if (!node.rpcName) {
-            errors.push(`Node '${nodeId}' is missing 'rpcName'`);
-            continue;
-        }
-        if (!toolSet.has(node.rpcName)) {
-            errors.push(`Node '${nodeId}' references unknown tool '${node.rpcName}'. Available tools: ${toolNames.join(', ')}`);
-            continue;
-        }
-        const nextTargets = normalizeTargets(node.next);
-        for (const target of nextTargets) {
-            if (!nodeIds.has(target)) {
-                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'next'`);
-            }
-        }
-        const errorTargets = normalizeTargets(node.onError);
-        for (const target of errorTargets) {
-            if (!nodeIds.has(target)) {
-                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'onError'`);
-            }
-        }
-        if (!node.input)
-            continue;
-        const refs = new Set();
-        collectRefs(node.input, refs);
-        for (const ref of refs) {
-            if (ref === 'trigger' || ref === '$item') {
-                const targetMeta = resolveToolMeta(node.rpcName);
-                if (targetMeta?.fnMeta?.inputSchemaName) {
-                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
-                    if (targetSchema?.properties) {
-                        for (const [field, fieldValue] of Object.entries(node.input)) {
-                            if (typeof fieldValue === 'object' &&
-                                fieldValue !== null &&
-                                fieldValue.$ref === ref &&
-                                !fieldValue.path) {
-                                const targetType = targetSchema.properties[field]?.type;
-                                if (targetType && targetType !== 'object') {
-                                    errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but references the whole ${ref} object without a path. Use { $ref: "${ref}", path: "${field}" } to extract the field.`);
-                                }
-                            }
-                        }
-                    }
-                }
-                continue;
-            }
-            if (!nodeIds.has(ref)) {
-                errors.push(`Node '${nodeId}' references unknown node '${ref}' in input`);
-                continue;
-            }
-            const sourceNode = nodes[ref];
-            if (!sourceNode?.rpcName)
-                continue;
-            const sourceMeta = resolveToolMeta(sourceNode.rpcName);
-            if (!sourceMeta?.fnMeta?.outputSchemaName)
-                continue;
-            const sourceSchema = sourceMeta.schemas.get(sourceMeta.fnMeta.outputSchemaName);
-            if (!sourceSchema?.properties)
-                continue;
-            for (const [field, fieldValue] of Object.entries(node.input)) {
-                if (typeof fieldValue === 'object' &&
-                    fieldValue !== null &&
-                    fieldValue.$ref === ref &&
-                    fieldValue.path) {
-                    const pathRoot = fieldValue.path.split('.')[0];
-                    if (sourceSchema.properties &&
-                        !(pathRoot in sourceSchema.properties)) {
-                        errors.push(`Node '${nodeId}' input field '${field}' references path '${fieldValue.path}' but node '${ref}' (${sourceNode.rpcName}) output has no property '${pathRoot}'`);
-                        continue;
-                    }
-                    const targetMeta = resolveToolMeta(node.rpcName);
-                    if (!targetMeta?.fnMeta?.inputSchemaName)
-                        continue;
-                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
-                    if (!targetSchema?.properties?.[field])
-                        continue;
-                    const sourceType = sourceSchema.properties[pathRoot]?.type;
-                    const targetType = targetSchema.properties[field].type;
-                    if (sourceType && targetType && sourceType !== targetType) {
-                        errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but node '${ref}' output field '${pathRoot}' is type '${sourceType}'`);
-                    }
-                }
-            }
-        }
-    }
-    return errors;
-}
 export function generateMermaidDiagram(workflowName, nodes, entryNodeIds) {
     const lines = ['graph TD'];
     for (const [nodeId, node] of Object.entries(nodes)) {

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

@@ -2,4 +2,4 @@ export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runW
 export { template } from './template.js';
 export type { TemplateString } from './template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './wire-workflow-graph.js';
-export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';
+export { generateMermaidDiagram } from './graph-validation.js';

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

@@ -1,4 +1,4 @@
 export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runWorkflowGraph, } from './graph-runner.js';
 export { template } from './template.js';
 export { pikkuWorkflowGraph, } from './wire-workflow-graph.js';
-export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';
+export { generateMermaidDiagram } from './graph-validation.js';

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

@@ -10,7 +10,6 @@ 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 { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.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, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';

package/dist/wirings/workflow/index.js

@@ -11,8 +11,6 @@ export { addFeature, resolveFeatureScenarios } from './feature.js';
 // Graph helpers (template, pikkuWorkflowGraph)
 export { template } from './graph/template.js';
 export { pikkuWorkflowGraph, } from './graph/wire-workflow-graph.js';
-// Graph validation and dynamic workflow utilities
-export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-validation.js';
 // Queue worker functions (registered by codegen, executed at runtime)
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 // Narrows the optional halves of the step wire, with a message that says what to do

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

@@ -154,14 +154,12 @@ export interface WorkflowRunExtension {
      */
     onAfterRunFunc(context: RunLifecycleContext, outcome: 'completed' | 'failed' | 'interrupted', failure: unknown): Promise<void>;
 }
-/**
- * Abstract workflow state service
- * Implementations provide pluggable storage backends (SQLite, PostgreSQL, etc.)
- * Combines orchestration and step execution
- */
 export declare abstract class PikkuWorkflowService implements WorkflowService {
-    private inlineRuns;
     private runExtension?;
+    private runContexts;
+    private contextFor;
+    /** Drop a run's context once nothing is holding it open. */
+    private releaseContext;
     protected get logger(): import("../../services/logger.js").Logger;
     protected mirror?: WorkflowRunMirror;
     protected readonly queueStrategy: 'per-workflow' | 'shared-groups';
@@ -171,7 +169,18 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         wireQueues?: boolean;
         mirror?: WorkflowRunMirror;
     } & WorkflowQueueOptions);
-    private safeMirror;
+    /**
+     * Perform a state write, then shadow it to the mirror.
+     *
+     * The mirror is an observability sink, never a second source of truth, and
+     * both halves of that follow from this one shape: it is only ever told about
+     * a write that already landed, and a mirror that is down or throwing cannot
+     * fail — or even be seen by — the workflow it is watching.
+     *
+     * @param write - the authoritative write; its result is what the caller gets
+     * @param mirror - shadows the write, given the live mirror and what was written
+     */
+    private mirrored;
     /**
      * Wire the queue-based orchestrator/step/sleeper workers.
      * Subclasses that orchestrate without queues (e.g. Durable Objects) should
@@ -392,11 +401,6 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         graph: any;
         source: string;
     } | null>;
-    abstract getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
-        workflowName: string;
-        graphHash: string;
-        graph: any;
-    }>>;
     /**
      * Resume a paused workflow by triggering the orchestrator
      * @param runId - Run ID
@@ -480,9 +484,59 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
         pollIntervalMs?: number;
         wire?: WorkflowRunWire;
     }): Promise<any>;
-    private stepOrdinals;
-    private stepLineage;
-    private resetStepOrdinals;
+    /**
+     * Read a run until it reaches an end state, backing off as it drags on.
+     *
+     * A fixed interval is wrong at both ends: it makes a workflow that finished
+     * in milliseconds wait out the whole interval anyway, and it keeps reading a
+     * long-running one at full rate for as long as it lasts. Starting short and
+     * growing to `maxIntervalMs` returns quick runs promptly while a slow run's
+     * read cost grows logarithmically rather than linearly with its duration.
+     */
+    protected awaitRunEnd(runId: string, maxIntervalMs: number): Promise<WorkflowRun>;
+    /**
+     * Wait between two reads of a run.
+     *
+     * Its own method so the backoff schedule can be asserted on directly. Timing
+     * a poll loop by the clock measures the host's scheduler as much as the
+     * policy — `setTimeout(40)` routinely returns late on a loaded runner — which
+     * makes the obvious test both slow and flaky.
+     */
+    protected waitBeforeNextRead(ms: number): Promise<void>;
+    /**
+     * Every step of a run in one read, or `null` if this backend has no bulk read.
+     *
+     * A replay walks the DSL body from the top, and each step it passes asks for
+     * its own row — so a run of N steps costs N reads per replay and O(N^2) over
+     * its lifetime. Backends that can answer this in a single query collapse that
+     * to one read per replay.
+     */
+    protected listStepStates(_runId: string): Promise<Array<StepState & {
+        stepName: string;
+    }> | null>;
+    /**
+     * Begin a replay pass: fresh ordinal counters, and one read of the steps the
+     * run has already taken so the walk back to where it left off is served from
+     * memory. Safe because a pass reaches each step key at most once, and the
+     * steps it replays past are `succeeded` and therefore immutable.
+     */
+    private beginReplay;
+    private endReplay;
+    /**
+     * The step row for `stepName`, creating it if the run has not reached it
+     * before. Served from the replay snapshot when one is loaded.
+     */
+    private loadOrCreateStep;
+    /**
+     * The run's immutable half — which workflow it is, the wire it was started
+     * on, its input. `getRun` is otherwise called several times per step for
+     * answers that were all fixed at creation, so a replay reads it once and
+     * hands the same object to everyone who only needs that half.
+     *
+     * Anyone who needs `status`, `output`, `error` or `state` must call `getRun`:
+     * those move while the run executes, and a cached copy would be a lie.
+     */
+    private getRunIdentity;
     /** The step the DSL walk last reached (the predecessor for the next step). */
     private lastStepName;
     /**