@pikku/core 0.12.62 → 0.12.64

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

@@ -49,6 +49,11 @@ export interface GraphNodeConfig<NodeIds extends string = string> {
     retries?: number;
     /** Delay between retries — milliseconds, duration string, or 'exponential' */
     retryDelay?: string | number;
+    /**
+     * Free-text documentation for this node. Non-semantic: excluded from the
+     * graph topology hash, so editing a note never marks the workflow as changed.
+     */
+    notes?: string;
 }
 /**
  * Graph wire context - available to functions running in a workflow graph

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

@@ -1,7 +1,7 @@
 /**
  * Workflow module exports
  */
-export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
+export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';
 export type { RunTimeline, RunTimelineEvent, ReconstructedRunState, ReconstructedStep, RunPhase, } from './run-timeline.js';
@@ -12,4 +12,4 @@ export { validateWorkflowWiring, computeEntryNodeIds, } from './graph/graph-vali
 export { pikkuWorkflowWorkerFunc, pikkuWorkflowOrchestratorFunc, pikkuWorkflowSleeperFunc, } from './workflow-queue-workers.js';
 export type { WorkflowStepInput as WorkflowStepQueueInput, PikkuWorkflowOrchestratorInput, PikkuWorkflowSleeperInput, } from './workflow-queue-workers.js';
 export type { WorkflowService, WorkflowServiceConfig, WorkflowPlannedStep, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, WorkflowRunStatus, StepState, WorkflowRunService, WorkflowRunMirror, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
-export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';
+export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, WorkflowWireApproval, WorkflowApprovalOptions, ApprovalOutcome, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, ApprovalStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './workflow.types.js';

package/dist/wirings/workflow/index.js

@@ -1,7 +1,7 @@
 /**
  * Workflow module exports
  */
-export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
+export { PikkuWorkflowService, WorkflowCancelledException, WorkflowSuspendedException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunNotFoundError, WorkflowApprovalResolvedError, DEFAULT_STEP_RETRIES, } from './pikku-workflow-service.js';
 export { deriveInvocationId, uuidv5 } from './workflow-invocation-id.js';
 // Time-travel: reconstruct run state at any point from durable history
 export { buildRunTimeline, reconstructStateAt, reconstructFinalState, } from './run-timeline.js';

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

@@ -1,5 +1,5 @@
 import type { SerializedError } from '../../types/core.types.js';
-import type { PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
+import type { ApprovalOutcome, PikkuScenarioWire, StepState, StepStatus, WorkflowPlannedStep, WorkflowRun, WorkflowRunMirror, WorkflowRunStatus, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
 import type { ScenarioActors } from '../../services/scenario-actors-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
@@ -70,6 +70,19 @@ export declare class WorkflowRunFailedError extends PikkuError {
 export declare class WorkflowRunCancelledError extends PikkuError {
     constructor();
 }
+/**
+ * A decision arrived for an approval gate that has already resolved. The gate
+ * caches its outcome as the step result and never re-reads run state, so the
+ * decision could not take effect — it is rejected rather than accepted and
+ * dropped.
+ */
+export declare class WorkflowApprovalResolvedError extends PikkuError {
+    payload: {
+        reason: string;
+        outcome: ApprovalOutcome<unknown>['status'];
+    };
+    constructor(reason: string, outcome: ApprovalOutcome<unknown>['status']);
+}
 export declare class WorkflowServiceNotInitialized extends Error {
 }
 export declare class WorkflowStepNameNotString extends Error {
@@ -446,6 +459,43 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      */
     private getSuspendStepName;
     private suspendStep;
+    /**
+     * Wake a run later by enqueuing a delayed orchestrator pass. Deliberately NOT
+     * {@link scheduleSleep}: that resolves the step it is given, which for an
+     * approval would resolve the gate itself. This only nudges the run to replay
+     * and re-evaluate — the gate stays the sole judge of its own outcome.
+     *
+     * Best-effort by design. Expiry is decided from the recorded deadline on
+     * replay, so losing this wake costs liveness (the run sits until something
+     * else resumes it), never correctness.
+     */
+    private scheduleRunWake;
+    /**
+     * Durable step name for an approval gate. Namespaced separately from suspend
+     * so the two can't collide, and derived from `reason` for the same reason
+     * {@link getSuspendStepName} is: it must be stable across replays.
+     */
+    private getApprovalStepName;
+    /**
+     * Run-state key holding an approval gate's record. Hex-encoded because the
+     * Mongo backend restricts state keys to `/^[a-zA-Z0-9_]+$/` and a `reason` is
+     * arbitrary human text. One key per gate, so two gates resolving concurrently
+     * can't clobber each other through a read-modify-write.
+     */
+    private approvalStateKey;
+    /**
+     * Record a decision against an approval gate and wake the run. Called from
+     * outside the workflow (an HTTP route, an RPC), so the schema value is NOT in
+     * scope here — the payload is stored raw and validated on replay inside the
+     * workflow body, which is the only place the schema exists. An invalid payload
+     * therefore leaves the gate closed rather than failing the run.
+     *
+     * `reason` addresses the first reach of that gate. An approval reached more
+     * than once under the same reason (e.g. in a loop) gets `#N`-suffixed step
+     * rows that this cannot currently target.
+     */
+    approveStep(runId: string, reason: string, decision: unknown): Promise<void>;
+    private approvalStep;
     createWorkflowWire(name: string, runId: string, rpcService: any, addonNamespace?: string | null): PikkuScenarioWire;
     private verifyStepName;
     private getConfig;

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

@@ -142,6 +142,23 @@ addError(WorkflowRunCancelledError, {
     status: 409,
     message: 'Workflow was cancelled.',
 });
+/**
+ * A decision arrived for an approval gate that has already resolved. The gate
+ * caches its outcome as the step result and never re-reads run state, so the
+ * decision could not take effect — it is rejected rather than accepted and
+ * dropped.
+ */
+export class WorkflowApprovalResolvedError extends PikkuError {
+    payload;
+    constructor(reason, outcome) {
+        super(`Approval already ${outcome}: ${reason}`);
+        this.payload = { reason, outcome };
+    }
+}
+addError(WorkflowApprovalResolvedError, {
+    status: 409,
+    message: 'Approval has already been resolved.',
+});
 export class WorkflowServiceNotInitialized extends Error {
 }
 export class WorkflowStepNameNotString extends Error {
@@ -1381,6 +1398,156 @@ export class PikkuWorkflowService {
             throw new WorkflowSuspendedException(runId, reason);
         });
     }
+    /**
+     * Wake a run later by enqueuing a delayed orchestrator pass. Deliberately NOT
+     * {@link scheduleSleep}: that resolves the step it is given, which for an
+     * approval would resolve the gate itself. This only nudges the run to replay
+     * and re-evaluate — the gate stays the sole judge of its own outcome.
+     *
+     * Best-effort by design. Expiry is decided from the recorded deadline on
+     * replay, so losing this wake costs liveness (the run sits until something
+     * else resumes it), never correctness.
+     */
+    async scheduleRunWake(runId, delay) {
+        try {
+            const queueService = this.verifyQueueService();
+            const run = await this.getRun(runId);
+            if (!run?.workflow)
+                return;
+            await queueService.add(this.getOrchestratorQueueName(run.workflow), { runId }, { ...this.resolveStepJobOptions(), delay });
+        }
+        catch (error) {
+            this.logger?.warn(`Failed to schedule approval expiry wake for run ${runId}; expiry will still resolve on the next replay`, error);
+        }
+    }
+    /**
+     * Durable step name for an approval gate. Namespaced separately from suspend
+     * so the two can't collide, and derived from `reason` for the same reason
+     * {@link getSuspendStepName} is: it must be stable across replays.
+     */
+    getApprovalStepName(reason) {
+        return `__workflow_approval:${reason}`;
+    }
+    /**
+     * Run-state key holding an approval gate's record. Hex-encoded because the
+     * Mongo backend restricts state keys to `/^[a-zA-Z0-9_]+$/` and a `reason` is
+     * arbitrary human text. One key per gate, so two gates resolving concurrently
+     * can't clobber each other through a read-modify-write.
+     */
+    approvalStateKey(stepName) {
+        let hex = '';
+        for (const byte of new TextEncoder().encode(stepName)) {
+            hex += byte.toString(16).padStart(2, '0');
+        }
+        return `__approval_${hex}`;
+    }
+    /**
+     * Record a decision against an approval gate and wake the run. Called from
+     * outside the workflow (an HTTP route, an RPC), so the schema value is NOT in
+     * scope here — the payload is stored raw and validated on replay inside the
+     * workflow body, which is the only place the schema exists. An invalid payload
+     * therefore leaves the gate closed rather than failing the run.
+     *
+     * `reason` addresses the first reach of that gate. An approval reached more
+     * than once under the same reason (e.g. in a loop) gets `#N`-suffixed step
+     * rows that this cannot currently target.
+     */
+    async approveStep(runId, reason, decision) {
+        const stepName = this.getApprovalStepName(reason);
+        const stateKey = this.approvalStateKey(stepName);
+        // A resolved gate returns its cached step result and never re-reads state,
+        // so a decision recorded now would be silently discarded — most obviously
+        // when it loses the race with expiry. Reject instead, so the approver
+        // learns their decision did not land.
+        let resolved;
+        try {
+            resolved = await this.getStepState(runId, stepName);
+        }
+        catch {
+            // No step row yet: the run has not reached the gate. Recording a decision
+            // ahead of it is legitimate — the gate picks it up on arrival.
+        }
+        if (resolved?.stepId && resolved.status === 'succeeded') {
+            const outcome = resolved.result;
+            throw new WorkflowApprovalResolvedError(reason, outcome?.status ?? 'decided');
+        }
+        const state = await this.getRunState(runId);
+        const record = (state[stateKey] ?? {});
+        await this.updateRunState(runId, stateKey, {
+            ...record,
+            decision,
+            decidedAt: new Date().toISOString(),
+            error: undefined,
+        });
+        await this.resumeWorkflow(runId);
+    }
+    async approvalStep(runId, reason, options) {
+        const fromStepName = this.lastStepName(runId);
+        const approvalStepName = this.nextStepKey(runId, this.getApprovalStepName(reason));
+        return await this.withStepLock(runId, approvalStepName, async () => {
+            let stepState;
+            try {
+                stepState = await this.getStepState(runId, approvalStepName);
+            }
+            catch {
+                stepState = await this.insertStepState(runId, approvalStepName, 'pikkuWorkflowApproval', { reason, expiry: options.expiry }, undefined, fromStepName);
+            }
+            if (!stepState.stepId) {
+                stepState = await this.insertStepState(runId, approvalStepName, 'pikkuWorkflowApproval', { reason, expiry: options.expiry }, undefined, fromStepName);
+            }
+            // Unlike suspend, `succeeded` here means a decision (or expiry) was
+            // actually resolved, and the step result IS the return channel.
+            if (stepState.status === 'succeeded') {
+                return stepState.result;
+            }
+            const stateKey = this.approvalStateKey(approvalStepName);
+            let record = ((await this.getRunState(runId))[stateKey] ?? {});
+            if (stepState.status === 'pending') {
+                await this.setStepRunning(stepState.stepId);
+                // First reach: stamp the deadline and nudge the run awake when it
+                // passes. The deadline is what's authoritative — see below.
+                if (options.expiry !== undefined && !record.expiresAt) {
+                    const expiresAt = new Date(Date.now() + getDurationInMilliseconds(options.expiry)).toISOString();
+                    record = { ...record, expiresAt };
+                    await this.updateRunState(runId, stateKey, record);
+                    await this.scheduleRunWake(runId, getDurationInMilliseconds(options.expiry));
+                }
+            }
+            if (record.decision !== undefined) {
+                const validation = await options.schema['~standard'].validate(record.decision);
+                if (validation.issues) {
+                    // Drop the bad decision and re-close the gate, leaving the failure
+                    // legible to whoever tries next. Failing the run instead would let any
+                    // caller kill a workflow with a malformed payload.
+                    await this.updateRunState(runId, stateKey, {
+                        ...record,
+                        decision: undefined,
+                        decidedAt: undefined,
+                        error: validation.issues.map((issue) => ({
+                            message: issue.message,
+                            path: issue.path?.map((segment) => typeof segment === 'object' ? segment.key : segment),
+                        })),
+                    });
+                    throw new WorkflowSuspendedException(runId, reason);
+                }
+                const outcome = {
+                    status: 'decided',
+                    data: validation.value,
+                };
+                await this.setStepResult(stepState.stepId, outcome);
+                return outcome;
+            }
+            // Expiry is decided by comparing against the recorded deadline rather than
+            // by the timer having fired, so a duplicate, late, or dropped timer all
+            // produce the same answer.
+            if (record.expiresAt && Date.now() >= Date.parse(record.expiresAt)) {
+                const outcome = { status: 'expired' };
+                await this.setStepResult(stepState.stepId, outcome);
+                return outcome;
+            }
+            throw new WorkflowSuspendedException(runId, reason);
+        });
+    }
     createWorkflowWire(name, runId, rpcService, addonNamespace) {
         const workflowWire = {
             name,
@@ -1492,6 +1659,10 @@ export class PikkuWorkflowService {
                 this.verifyStepName(reason);
                 await this.suspendStep(runId, reason);
             },
+            approval: (async (reason, options) => {
+                this.verifyStepName(reason);
+                return await this.approvalStep(runId, reason, options);
+            }),
             runScheduledTask: async (taskName) => {
                 await runScheduledTask({ name: taskName });
             },

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

@@ -1,7 +1,7 @@
 import type { SerializedError, CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 export type { WorkflowService } from '../../services/workflow-service.js';
-export type { WorkflowStepOptions, WorkflowExpectEventuallyOptions, WorkflowExpectErrorOptions, WorkflowExpectServiceOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SuspendStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.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, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, PikkuScenarioWire, } from './dsl/workflow-dsl.types.js';
 import type { WorkflowStepMeta } from './dsl/workflow-dsl.types.js';
 export interface WorkflowRunWire {
     type: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.62",
+  "version": "0.12.64",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -41,6 +41,7 @@
     "./cli/channel": "./dist/wirings/cli/channel/index.js",
     "./node": "./dist/wirings/node/index.js",
     "./credential": "./dist/wirings/credential/index.js",
+    "./scope": "./dist/wirings/scope/index.js",
     "./secret": "./dist/wirings/secret/index.js",
     "./variable": "./dist/wirings/variable/index.js",
     "./oauth2": "./dist/wirings/oauth2/index.js",
@@ -53,6 +54,7 @@
     "./services/temporary-file-service": "./dist/services/temporary-file-service.js",
     "./services/gopass-secrets": "./dist/services/gopass-secrets.js",
     "./crypto-utils": "./dist/crypto-utils.js",
+    "./hmac": "./dist/utils/hmac.js",
     "./internal": "./dist/internal.js",
     "./schema": "./dist/schema.js",
     "./testing": "./dist/testing/index.js",
@@ -67,7 +69,9 @@
     "picoquery": "^2.5.0"
   },
   "devDependencies": {
+    "@ag-ui/core": "0.0.57",
     "@types/node": "^24.11.0",
+    "esbuild": "~0.27.0",
     "tsx": "^4.21.0",
     "typescript": "^6.0.3"
   },

package/run-tests.sh

@@ -53,6 +53,7 @@ fi
 
 if [ "$coverage_mode" = true ]; then
   node_cmd+=(--test-coverage-include="src/**/*.{ts,js}" --test-coverage-exclude="**/dist/**" --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info)
+  export PIKKU_TEST_COVERAGE=1
 fi
 
 # Execute the node command with the expanded list of files

package/src/dev/hot-reload.ts

@@ -1,9 +1,6 @@
 import { watch, type FSWatcher } from 'node:fs'
-import { stat, readFile, copyFile, rm } from 'node:fs/promises'
-import { basename, dirname, join, resolve, relative } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-import { register } from 'tsx/esm/api'
+import { stat } from 'node:fs/promises'
+import { basename, join, resolve, relative } from 'node:path'
 
 import { pikkuState } from '../pikku-state.js'
 import { clearMiddlewareCache } from '../middleware-runner.js'
@@ -12,6 +9,7 @@ import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middlewa
 import { httpRouter } from '../wirings/http/routers/http-router.js'
 import type { Logger } from '../services/logger.js'
 import type { CorePikkuFunctionConfig } from '../function/functions.types.js'
+import { createModuleRunner } from './module-runner.js'
 
 export * from './reload-meta.js'
 
@@ -54,67 +52,19 @@ const findCompiledFile = async (
   return null
 }
 
-// Use data: URLs to import modules. This bypasses TypeScript loaders
-// (e.g. tsx) that intercept file:// imports and break dynamic ESM loading.
-// Each import gets unique content so there's no module cache to worry about.
-let tsxRegistered = false
-
-const ensureTsxRegistered = () => {
-  if (tsxRegistered) return
-  register()
-  tsxRegistered = true
-}
-
-let tempCounter = 0
-
-const reimportModule = async (
-  filePath: string,
-  useTsx = false
-): Promise<Record<string, unknown> | null> => {
-  try {
-    if (useTsx) {
-      // Import a uniquely-named sibling copy: a `?t=` query does NOT bust
-      // the cache on either runtime (Bun keys module identity on the bare
-      // path; tsx's transform cache keys on the file path too), so a fresh
-      // path is the only reliable re-import. Same directory → identical
-      // resolution for relative and package-`imports` (#…) specifiers. The
-      // dot-prefix keeps it out of the watcher.
-      if (!process.versions.bun) {
-        // Node needs tsx's loader to import raw .ts; Bun imports it natively.
-        ensureTsxRegistered()
-      }
-      const abs = resolve(filePath)
-      const tempPath = join(
-        dirname(abs),
-        `.pikku-hot-${++tempCounter}-${basename(abs)}`
-      )
-      await copyFile(abs, tempPath)
-      try {
-        return await import(pathToFileURL(tempPath).href)
-      } finally {
-        await rm(tempPath, { force: true }).catch(() => {
-          // Best-effort temp cleanup; a leftover dotfile is watcher-ignored.
-        })
-      }
-    }
-
-    const content = await readFile(resolve(filePath), 'utf-8')
-    const dataUrl =
-      'data:text/javascript;base64,' + Buffer.from(content).toString('base64')
-    return await import(dataUrl)
-  } catch {
-    return null
-  }
-}
-
+// Changed user files are re-run through an evictable module runner keyed by a
+// stable path (createModuleRunner), NOT re-imported under a fresh URL. A
+// fresh-URL import (a `data:` URL on Node, a uniquely-named temp sibling on
+// Bun) permanently leaks a record in the native ESM loader map on every
+// reload, OOMing long editing sessions; the runner overwrites a single slot so
+// the previous module is collected. See ./module-runner.ts.
 const isWatchedTsFile = (filename: string): boolean => {
   return (
     filename.endsWith('.ts') &&
     !filename.endsWith('.test.ts') &&
     !filename.endsWith('.d.ts') &&
     !filename.endsWith('.gen.ts') &&
-    // Hidden files: editor/sed atomic-write temps and our own hot-reload
-    // sibling copies must never trigger a reload of themselves.
+    // Hidden files: editor/sed atomic-write temps must never trigger a reload.
     !basename(filename).startsWith('.')
   )
 }
@@ -135,6 +85,7 @@ export async function pikkuDevReloader(
   const watchers: FSWatcher[] = []
 
   const functionsMap = pikkuState(null, 'function', 'functions')
+  const moduleRunner = createModuleRunner()
 
   const handleFileChange = async (changedTsFile: string) => {
     const start = Date.now()
@@ -150,15 +101,8 @@ export async function pikkuDevReloader(
       absPikkuDir
     )
     const importPath = compiledFile ?? changedTsFile
-    const usedTsxFallback = !compiledFile
-
-    if (usedTsxFallback) {
-      logger.debug(
-        `Hot-reload using tsx fallback for: ${relative(process.cwd(), changedTsFile)}`
-      )
-    }
 
-    const mod = await reimportModule(importPath, usedTsxFallback)
+    const mod = await moduleRunner.run(importPath)
     if (!mod) {
       logger.error(
         `Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`
@@ -260,6 +204,7 @@ export async function pikkuDevReloader(
       for (const watcher of watchers) {
         watcher.close()
       }
+      moduleRunner.clear()
     },
     // Drain the queue of recently re-imported files and import them again.
     // A dev-server watcher calls this AFTER its codegen pass has refreshed

package/src/dev/module-runner.test.ts

@@ -0,0 +1,169 @@
+import { describe, test, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+import v8 from 'node:v8'
+import vm from 'node:vm'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { tmpdir } from 'node:os'
+
+import { createModuleRunner } from './module-runner.js'
+
+// A forced-GC hook without launching the process with a flag: on Bun use the
+// native collector; on Node flip --expose-gc on just long enough to grab `gc`.
+const getGc = (): (() => void) => {
+  const bun = (globalThis as any).Bun
+  if (bun) return () => bun.gc(true)
+  v8.setFlagsFromString('--expose-gc')
+  const gc = vm.runInNewContext('gc') as () => void
+  v8.setFlagsFromString('--no-expose-gc')
+  return () => gc()
+}
+
+const heapUsedMb = () => process.memoryUsage().heapUsed / 1048576
+
+// V8's --experimental-test-coverage retains coverage data for every compiled
+// script for the life of the run, which pins the runner's per-reload compiled
+// functions (and would equally pin the old leaky mechanism), so a heap-growth
+// measurement can't discriminate a leak from a non-leak while it's on. run-tests.sh
+// exports this marker in --coverage mode (the flag itself is not visible to the
+// isolated test child). The single-slot registry guarantee below still runs
+// unconditionally.
+const UNDER_COVERAGE = process.env.PIKKU_TEST_COVERAGE === '1'
+
+describe('createModuleRunner', { concurrency: false }, () => {
+  let tmpDir: string
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'pikku-module-runner-'))
+    await writeFile(
+      join(tmpDir, 'package.json'),
+      JSON.stringify({ type: 'module' })
+    )
+  })
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true })
+  })
+
+  test('runs a TS module and returns its exports', async () => {
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'todo.ts')
+    await writeFile(
+      file,
+      `interface Todo { id: string }
+       export const createTodo = { func: async (_s: any, d: Todo) => ({ id: d.id }) }`
+    )
+
+    const mod = await runner.run(file)
+    assert.ok(mod)
+    const createTodo = mod!.createTodo as {
+      func: (...a: any[]) => Promise<any>
+    }
+    assert.equal(typeof createTodo.func, 'function')
+    assert.deepEqual(await createTodo.func({}, { id: 'abc' }), { id: 'abc' })
+  })
+
+  test('top-level import side effects hit the live singleton dependency', async () => {
+    // Delegated imports must resolve to the SAME module instance the rest of
+    // the process holds, so a user file's wire* side effect mutates live state.
+    await writeFile(
+      join(tmpDir, 'registry.js'),
+      `export const registry = new Map()
+       export const wire = (name, cfg) => registry.set(name, cfg)`
+    )
+
+    const runner = createModuleRunner()
+    const userFile = join(tmpDir, 'wired.ts')
+    await writeFile(
+      userFile,
+      `import { wire } from './registry.js'
+       export const createTodo = { func: async () => ({ ok: true }) }
+       wire('createTodo', createTodo)`
+    )
+
+    const mod = await runner.run(userFile)
+    assert.ok(mod)
+
+    // Read the dependency through the same resolver the runner uses, so we
+    // observe the exact instance the user module's `import` bound to (using a
+    // separate `import()` would resolve a distinct copy under the tsx test
+    // loader and prove nothing about live-singleton delegation).
+    const dep = createRequire(pathToFileURL(userFile))('./registry.js') as {
+      registry: Map<string, unknown>
+    }
+    assert.equal(dep.registry.has('createTodo'), true)
+    assert.strictEqual(dep.registry.get('createTodo'), mod!.createTodo)
+  })
+
+  test('re-running the same path overwrites a single registry slot', async () => {
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'value.ts')
+
+    await writeFile(file, `export const value = { func: async () => 'v1' }`)
+    const first = await runner.run(file)
+    assert.equal(await (first!.value as any).func(), 'v1')
+
+    await writeFile(file, `export const value = { func: async () => 'v2' }`)
+    const second = await runner.run(file)
+    assert.equal(await (second!.value as any).func(), 'v2')
+
+    // Stable key: many reloads of one path never grow the registry.
+    for (let i = 0; i < 20; i++) await runner.run(file)
+    assert.equal(runner.size, 1)
+  })
+
+  test('returns null on a bad edit so the caller keeps old code', async () => {
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'broken.ts')
+    await writeFile(
+      file,
+      `export const oops = { func: async () => ( } ] syntax`
+    )
+    const mod = await runner.run(file)
+    assert.equal(mod, null)
+  })
+
+  test('editing and reimporting a module 200x does not leak memory', async () => {
+    const gc = getGc()
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'big.ts')
+    // A sizeable module edited on every reload (the real dev pattern). The old
+    // fresh-URL reimport left one of these in the native ESM loader map per
+    // edit (~0.3-1.3 MB each) — ~84 MB (Node) / ~222 MB (Bun) over 200 edits —
+    // and OOMed. The evictable runner overwrites a single stable slot, so the
+    // previous module is collected and heap stays bounded.
+    const payload = JSON.stringify(
+      Array.from({ length: 2000 }, (_, i) => ({ i, s: 'field_' + i }))
+    )
+    const write = (marker: number) =>
+      writeFile(
+        file,
+        `export const data = ${payload}
+         export const handler = { func: async () => data.length }
+         // edit ${marker}`
+      )
+
+    // Warm up (first compile allocates esbuild + shared caches), then baseline.
+    await write(0)
+    await runner.run(file)
+    gc()
+    const baseline = heapUsedMb()
+
+    for (let i = 1; i <= 200; i++) {
+      await write(i)
+      const mod = await runner.run(file)
+      assert.ok(mod)
+    }
+    gc()
+    const growth = heapUsedMb() - baseline
+
+    assert.equal(runner.size, 1)
+    if (UNDER_COVERAGE) return
+    assert.ok(
+      growth < 15,
+      `heap grew ${growth.toFixed(1)} MB over 200 edits (expected < 15 MB)`
+    )
+  })
+})