@pikku/core 0.12.94 → 0.12.96

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

@@ -11,7 +11,7 @@ import { buildRunTimeline, reconstructStateAt, } from './run-timeline.js';
 import { DEFAULT_STEP_RETRIES, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, isRunSettled, } from './workflow-constants.js';
 import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepNameNotString, WorkflowSuspendedException, } from './workflow-errors.js';
 import { resolveWorkflowMeta } from './workflow-meta-resolver.js';
-import { jobGroupFor, orchestratorQueueName, resolveWorkflowConfig, stepJobOptions, stepWorkerQueueName, } from './workflow-queue-routing.js';
+import { jobGroupFor, orchestratorQueueName, resolveWorkflowConfig, stepDispatchTarget, stepJobOptions, stepWorkerQueueName, } from './workflow-queue-routing.js';
 import { wireWorkflowQueueWorkers } from './workflow-queue-wiring.js';
 import { approvalStepNameFor, evaluateApprovalStep, recordApprovalDecision, } from './workflow-approval.js';
 import { auditApprovalDecision } from './workflow-approval-audit.js';
@@ -323,16 +323,10 @@ export class PikkuWorkflowService {
         });
     }
     async dispatchStep(runId, stepName, rpcName, data, stepOptions, fromStepName) {
-        const functionsMeta = pikkuState(null, 'function', 'meta');
-        const rpcFuncId = pikkuState(null, 'rpc', 'meta')[rpcName];
-        const rpcMeta = typeof rpcFuncId === 'string' ? functionsMeta[rpcFuncId] : undefined;
-        const forceQueue = rpcMeta?.workflowQueued === true;
-        if (!forceQueue) {
+        const target = await stepDispatchTarget(rpcName, stepName, () => this.isInline(runId));
+        if (target === 'inline') {
             return false;
         }
-        if (!getSingletonServices()?.queueService) {
-            throw new Error(`Workflow step '${stepName}' (function '${rpcName}') is marked 'workflowQueued: true' but no queue service is configured.`);
-        }
         try {
             await getSingletonServices().queueService.add(this.getStepWorkerQueueName(rpcName), { runId, stepName, rpcName, data, fromStepName }, {
                 ...this.resolveStepJobOptions(stepOptions),

package/dist/wirings/workflow/scenario-prose.d.ts

@@ -1,10 +1,32 @@
 import type { ScenarioStepPhase } from './scenario-step.types.js';
 export declare const renderStepTemplate: (template: string, input: unknown) => string;
-export declare const composeStepProse: ({ phase, description, template, input, actor, keywordWidth, }: {
+export declare const composeStepProse: ({ phase, description, template, input, actor, actorRole, continuesPhase, continuesActor, keywordWidth, }: {
     phase: ScenarioStepPhase;
     description: string;
     template?: string;
     input?: unknown;
     actor?: string;
+    /**
+     * What this actor is, rendered as an apposition after their key — "yasser
+     * (the founder)". Only pass it where the actor has not been named yet: an
+     * ordinary run repeats one actor for a dozen steps, and repeating the role
+     * with them turns the one piece of context into the noise around it.
+     */
+    actorRole?: string;
+    /**
+     * This step repeats the phase of the one before it, so it reads as `And`
+     * rather than saying `Given` three times — the same thing Gherkin does.
+     */
+    continuesPhase?: boolean;
+    /**
+     * The step before this one had the same actor. Combined with `continuesPhase`
+     * the subject is dropped, because English drops a repeated subject in a
+     * compound predicate: "yasser opens the dashboard / and sees the audit log".
+     *
+     * It takes both. Dropping the subject across a phase change gives "When opens
+     * the dashboard", and a pronoun instead of a name would give "they sees",
+     * since step templates are authored in the third person singular.
+     */
+    continuesActor?: boolean;
     keywordWidth?: number;
 }) => string;

package/dist/wirings/workflow/scenario-prose.js

@@ -14,9 +14,13 @@ const formatValue = (value) => {
     }
     return String(value);
 };
-export const composeStepProse = ({ phase, description, template, input, actor, keywordWidth, }) => {
-    const keyword = capitalise(phase);
-    const subject = actor ? `the ${actor}` : '';
+export const composeStepProse = ({ phase, description, template, input, actor, actorRole, continuesPhase, continuesActor, keywordWidth, }) => {
+    const keyword = capitalise(continuesPhase ? 'and' : phase);
+    // The actor key is the subject verbatim, with no article in front of it.
+    // "the ${actor}" only reads as English when the key happens to be a role
+    // noun — it turns a persona named after a person into "the nadia", which
+    // is the reporter quietly imposing a naming convention on the author.
+    const subject = continuesPhase && continuesActor ? '' : composeSubject(actor, actorRole);
     const rendered = template ? renderStepTemplate(template, input) : description;
     const sentence = [subject, rendered].filter(Boolean).join(' ');
     if (keywordWidth === undefined) {
@@ -24,4 +28,9 @@ export const composeStepProse = ({ phase, description, template, input, actor, k
     }
     return `${keyword.padEnd(keywordWidth)} ${sentence}`;
 };
+const composeSubject = (actor, actorRole) => {
+    if (!actor)
+        return '';
+    return actorRole ? `${actor} (the ${actorRole})` : actor;
+};
 const capitalise = (value) => value.charAt(0).toUpperCase() + value.slice(1);

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

@@ -35,6 +35,13 @@ export interface ScenarioArtifact {
 /** One step of a run, already joined to the prose that declared it. */
 export interface ScenarioStepRow {
     sentence: string;
+    /**
+     * The same sentence with the actor's role in it — "yasser (the founder)
+     * signs in". Set only on the step that first names each actor, and only
+     * when a persona declares a job title or a role, so a reader who wants the
+     * context picks this and one who wants the bare run picks `sentence`.
+     */
+    sentenceWithRole?: string;
     status: string;
     durationMs?: number;
     error?: string;

package/dist/wirings/workflow/workflow-queue-routing.d.ts

@@ -4,5 +4,23 @@ export type WorkflowQueueStrategy = 'per-workflow' | 'shared-groups';
 export declare const resolveWorkflowConfig: () => WorkflowServiceConfig;
 export declare const orchestratorQueueName: (strategy: WorkflowQueueStrategy, workflowName?: string) => string;
 export declare const stepWorkerQueueName: (strategy: WorkflowQueueStrategy, rpcName?: string) => string;
+/**
+ * How a step reaches its worker: on the queue, or here in the orchestrator.
+ *
+ * A step naming a workflow queues whenever a queue exists, even unmarked. Run
+ * here, it holds the parent's run lock — and its lock connection — until the
+ * child ends, and marks the child inline so the child's own `sleep` degrades
+ * from a suspension into a real in-process wait. Workflows cannot opt in
+ * through `workflowQueued`: that flag is read off `rpc` meta, and `addWorkflow`
+ * never registers there.
+ *
+ * Throws only for a step that asked for the queue by name and has none, which
+ * is a deployment missing a service rather than a routing choice.
+ *
+ * `parentIsInline` is a thunk because resolving it can read the run store, and
+ * every step dispatch would pay for that — only a step that names a workflow
+ * and has a queue to reach ever asks.
+ */
+export declare const stepDispatchTarget: (rpcName: string, stepName: string, parentIsInline: () => Promise<boolean>) => Promise<"queue" | "inline">;
 export declare const jobGroupFor: (strategy: WorkflowQueueStrategy, id?: string) => JobGroup | undefined;
 export declare const stepJobOptions: (stepOptions?: WorkflowStepOptions) => JobOptions;

package/dist/wirings/workflow/workflow-queue-routing.js

@@ -25,6 +25,41 @@ const dedicatedQueueName = (prefix, name, strategy, fallback) => {
 };
 export const orchestratorQueueName = (strategy, workflowName) => dedicatedQueueName('wf-orchestrator-', workflowName, strategy, resolveWorkflowConfig().orchestratorQueueName);
 export const stepWorkerQueueName = (strategy, rpcName) => dedicatedQueueName('wf-step-', rpcName, strategy, resolveWorkflowConfig().stepWorkerQueueName);
+/**
+ * How a step reaches its worker: on the queue, or here in the orchestrator.
+ *
+ * A step naming a workflow queues whenever a queue exists, even unmarked. Run
+ * here, it holds the parent's run lock — and its lock connection — until the
+ * child ends, and marks the child inline so the child's own `sleep` degrades
+ * from a suspension into a real in-process wait. Workflows cannot opt in
+ * through `workflowQueued`: that flag is read off `rpc` meta, and `addWorkflow`
+ * never registers there.
+ *
+ * Throws only for a step that asked for the queue by name and has none, which
+ * is a deployment missing a service rather than a routing choice.
+ *
+ * `parentIsInline` is a thunk because resolving it can read the run store, and
+ * every step dispatch would pay for that — only a step that names a workflow
+ * and has a queue to reach ever asks.
+ */
+export const stepDispatchTarget = async (rpcName, stepName, parentIsInline) => {
+    const rpcFuncId = pikkuState(null, 'rpc', 'meta')[rpcName];
+    const rpcMeta = typeof rpcFuncId === 'string'
+        ? pikkuState(null, 'function', 'meta')[rpcFuncId]
+        : undefined;
+    const hasQueue = getSingletonServices()?.queueService !== undefined;
+    if (rpcMeta?.workflowQueued === true) {
+        if (!hasQueue) {
+            throw new Error(`Workflow step '${stepName}' (function '${rpcName}') is marked 'workflowQueued: true' but no queue service is configured.`);
+        }
+        return 'queue';
+    }
+    const isWorkflow = pikkuState(null, 'workflows', 'meta')[rpcName] !== undefined;
+    if (!isWorkflow || !hasQueue) {
+        return 'inline';
+    }
+    return (await parentIsInline()) ? 'inline' : 'queue';
+};
 export const jobGroupFor = (strategy, id) => id && strategy === 'shared-groups' ? { id, tier: id } : undefined;
 export const stepJobOptions = (stepOptions) => {
     const retries = stepOptions?.retries ?? DEFAULT_STEP_RETRIES;

package/dist/wirings/workflow/workflow-status-stream.d.ts

@@ -0,0 +1,28 @@
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { PikkuChannel } from '../channel/channel.types.js';
+import type { WorkflowRunService } from './workflow.types.js';
+export interface WorkflowStatusStreamParams {
+    workflowRunService: WorkflowRunService;
+    runId: string;
+    channel: Pick<PikkuChannel<unknown, any>, 'send' | 'close'>;
+    session: CoreUserSession | undefined;
+    /**
+     * Whether to include what the run produced. Off for the user-facing route:
+     * a workflow's output and its error messages are internal detail, and a step
+     * that spawned a child run says so only to tooling that can follow it.
+     */
+    detailed?: boolean;
+    pollIntervalMs?: number;
+}
+/**
+ * Streams one run's progress until it reaches a terminal state.
+ *
+ * Polled rather than subscribed because a run's steps are written by whichever
+ * worker picked them up, in whichever process — there is no in-memory event to
+ * listen for that every deployment shape would deliver.
+ *
+ * Each poll sends only when something changed, compared by a hash of exactly
+ * what this stream reports. A run that sits on a slow step for a minute costs
+ * one message, not a hundred and twenty.
+ */
+export declare const streamWorkflowRunStatus: ({ workflowRunService, runId, channel, session, detailed, pollIntervalMs, }: WorkflowStatusStreamParams) => Promise<void>;

package/dist/wirings/workflow/workflow-status-stream.js

@@ -0,0 +1,105 @@
+import { assertWorkflowRunOwner } from './workflow-run-ownership.js';
+/**
+ * The status stream behind the scaffolded workflow SSE routes.
+ *
+ * Two routes share it, and they differ by one thing: whether the caller is
+ * trusted with what the run produced. A user-facing frontend gets step names
+ * and statuses; an admin console also gets the output, the error and the child
+ * run ids. That is a parameter, not a second copy of the loop.
+ */
+const TERMINAL = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+]);
+const DEFAULT_POLL_INTERVAL_MS = 500;
+/**
+ * Streams one run's progress until it reaches a terminal state.
+ *
+ * Polled rather than subscribed because a run's steps are written by whichever
+ * worker picked them up, in whichever process — there is no in-memory event to
+ * listen for that every deployment shape would deliver.
+ *
+ * Each poll sends only when something changed, compared by a hash of exactly
+ * what this stream reports. A run that sits on a slow step for a minute costs
+ * one message, not a hundred and twenty.
+ */
+export const streamWorkflowRunStatus = async ({ workflowRunService, runId, channel, session, detailed = false, pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, }) => {
+    let lastHash = '';
+    let initSent = false;
+    const poll = async () => {
+        const run = await workflowRunService.getRun(runId);
+        if (!run) {
+            await channel.close();
+            return false;
+        }
+        // Checked on every poll, not just the first: ownership is read from the run
+        // itself, and a stream that outlives a session should stop rather than keep
+        // reporting.
+        assertWorkflowRunOwner(run.wire, session);
+        const steps = await workflowRunService.getRunSteps(runId);
+        // A deterministic run knows its whole shape up front, so the client can
+        // draw every step — including the ones not started — before anything runs.
+        // A dynamic run has nothing to send here, and gets no init frame.
+        if (!initSent && run.deterministic) {
+            const statusByStep = new Map(steps.map((step) => [step.stepName, step.status]));
+            await channel.send({
+                type: 'init',
+                deterministic: true,
+                steps: (run.plannedSteps ?? []).map((step) => ({
+                    stepName: step.stepName,
+                    status: statusByStep.get(step.stepName) ?? 'pending',
+                })),
+            });
+            initSent = true;
+        }
+        const hash = JSON.stringify({
+            s: run.status,
+            ...(detailed ? { o: run.output } : {}),
+            steps: steps.map((step) => [step.stepName, step.status]),
+        });
+        if (hash !== lastHash) {
+            lastHash = hash;
+            await channel.send({
+                type: 'update',
+                status: run.status,
+                ...(detailed ? { output: run.output, error: run.error } : {}),
+                steps: steps.map((step) => ({
+                    stepName: step.stepName,
+                    status: step.status,
+                    ...(detailed && step.childRunId
+                        ? { childRunId: step.childRunId }
+                        : {}),
+                })),
+            });
+        }
+        if (TERMINAL.has(run.status)) {
+            await channel.send({ type: 'done' });
+            await channel.close();
+            return false;
+        }
+        return true;
+    };
+    // Every exit from here closes the channel, including the ones a throw takes:
+    // `assertWorkflowRunOwner` rejecting a session that lost access is exactly
+    // the case where the stream should end rather than be left hanging open.
+    try {
+        // A run that is already finished is answered without ever starting a timer.
+        if (!(await poll())) {
+            return;
+        }
+        // The next poll is scheduled when the previous one resolves rather than on
+        // a fixed interval. A timer that fires regardless would let two polls
+        // overlap on a slow store — both seeing `initSent` unset and sending the
+        // init frame twice, and racing `lastHash` into out-of-order updates.
+        while (await new Promise((resolve, reject) => {
+            setTimeout(() => void poll().then(resolve, reject), pollIntervalMs);
+        })) {
+            // The condition is the whole loop: poll until it says to stop.
+        }
+    }
+    catch (error) {
+        await channel.close();
+        throw error;
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.94",
+  "version": "0.12.96",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/dev/hot-reload.test.ts

@@ -215,6 +215,48 @@ describe('pikkuDevReloader', { concurrency: false }, () => {
     assert.deepEqual(await func.func({} as any, {}, {} as any), {
       working: true,
     })
+
+    // Serving the old code is only safe if the developer is told why; without
+    // the reason the sole symptom is a function that ignores the file on disk.
+    const failureLog = mockLogger
+      .getLogs()
+      .find((l) => l.message.includes('Failed to import'))
+    assert.ok(failureLog, 'Should log the failed import')
+    assert.ok(
+      failureLog!.message.includes('keeping old code'),
+      'Should say the old code is still being served'
+    )
+    assert.match(failureLog!.message, /badFunc\.js/)
+  })
+
+  test('should name the top-level await limitation when a reload hits it', async (t) => {
+    if (!(await ensureRecursiveWatchAvailable(t, tmpDir))) return
+
+    await writeFile(join(tmpDir, 'tlaFunc.ts'), '// initial')
+
+    reloader = await pikkuDevReloader({
+      srcDirectories: [tmpDir],
+      logger: mockLogger,
+      pikkuDir: tmpDir,
+    })
+
+    await writeFile(
+      join(tmpDir, 'tlaFunc.ts'),
+      `const config = await Promise.resolve({ ok: true })
+       export const tlaFunc = { func: async () => config }
+       // trigger ${Date.now()}`
+    )
+
+    await wait(300)
+
+    const failureLog = mockLogger
+      .getLogs()
+      .find((l) => l.message.includes('Failed to import'))
+    assert.ok(failureLog, 'Should log the failed import')
+    // The file is valid TypeScript; pointing at pikku's own `cjs` emit is the
+    // difference between a two-minute fix and an afternoon.
+    assert.match(failureLog!.message, /top-level `?await`?/i)
+    assert.match(failureLog!.message, /pikku limitation/i)
   })
 
   test('should ignore non-ts files, test files, and gen files', async (t) => {

package/src/dev/hot-reload.ts

@@ -9,7 +9,10 @@ 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'
+import {
+  createModuleRunner,
+  isTopLevelAwaitLimitation,
+} from './module-runner.js'
 
 export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js'
 
@@ -63,6 +66,23 @@ const isWatchedTsFile = (filename: string): boolean => {
   )
 }
 
+/** Not every reload failure is a mistake in the file: pikku's reloader emits
+ *  `cjs`, which has no way to express top-level `await`, so a perfectly valid
+ *  module can fail here forever. Saying so outright saves the reader from
+ *  hunting a bug that is not in their code. The stack is dropped in that case
+ *  because it points into esbuild rather than at anything actionable. */
+const reloadFailureReason = (error: Error): string => {
+  if (isTopLevelAwaitLimitation(error)) {
+    return (
+      `  ${error.message}\n` +
+      '  This is a pikku limitation, not a mistake in your file: the hot-reloader compiles to `cjs`, ' +
+      'which cannot express top-level `await`. Move the awaited work into a function, or restart the ' +
+      'dev server to pick the file up.'
+    )
+  }
+  return `  ${error.stack ?? error.message}`
+}
+
 export interface PikkuDevReloaderHandle {
   close: () => void
   /** Re-import every file changed since the last drain (post-codegen, once
@@ -96,13 +116,19 @@ export async function pikkuDevReloader(
     )
     const importPath = compiledFile ?? changedTsFile
 
-    const mod = await moduleRunner.run(importPath)
-    if (!mod) {
+    const result = await moduleRunner.run(importPath)
+    if (!result.ok) {
+      // Keeping the old code leaves the process disagreeing with the file on
+      // disk, and the only symptom is stale output from a function that looks
+      // correct in the editor — so the reason has to be printed here, where it
+      // is still known, rather than left for the developer to reconstruct.
       logger.error(
-        `Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)`
+        `Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
+          reloadFailureReason(result.error)
       )
       return
     }
+    const mod = result.exports
 
     // knowledge: decisions/internals/hot-reload-writes-into-the-function-map-captured-at-startup.md
     for (const [exportName, exportValue] of Object.entries(mod)) {

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

@@ -8,7 +8,10 @@ import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { tmpdir } from 'node:os'
 
-import { createModuleRunner } from './module-runner.js'
+import {
+  createModuleRunner,
+  isTopLevelAwaitLimitation,
+} 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`.
@@ -56,9 +59,10 @@ describe('createModuleRunner', { concurrency: false }, () => {
        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 {
+    const result = await runner.run(file)
+    assert.equal(result.ok, true)
+    const createTodo = (result as { exports: Record<string, unknown> }).exports
+      .createTodo as {
       func: (...a: any[]) => Promise<any>
     }
     assert.equal(typeof createTodo.func, 'function')
@@ -83,8 +87,9 @@ describe('createModuleRunner', { concurrency: false }, () => {
        wire('createTodo', createTodo)`
     )
 
-    const mod = await runner.run(userFile)
-    assert.ok(mod)
+    const result = await runner.run(userFile)
+    assert.equal(result.ok, true)
+    const mod = (result as { exports: Record<string, unknown> }).exports
 
     // 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
@@ -103,26 +108,64 @@ describe('createModuleRunner', { concurrency: false }, () => {
 
     await writeFile(file, `export const value = { func: async () => 'v1' }`)
     const first = await runner.run(file)
-    assert.equal(await (first!.value as any).func(), 'v1')
+    assert.equal(first.ok, true)
+    assert.equal(await ((first as any).exports.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')
+    assert.equal(second.ok, true)
+    assert.equal(await ((second as any).exports.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 () => {
+  test('reports a bad edit with its reason so the caller can say why', 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)
+    const result = await runner.run(file)
+    assert.equal(result.ok, false)
+    // The caller keeps serving the old code, so this error is the only thing
+    // standing between the developer and an unexplained stale response.
+    const { error } = result as { error: Error }
+    assert.ok(error instanceof Error)
+    assert.match(error.message, /broken\.ts/)
+    assert.equal(isTopLevelAwaitLimitation(error), false)
+  })
+
+  test('names the top-level await limitation as such', async () => {
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'tla.ts')
+    await writeFile(
+      file,
+      `const config = await Promise.resolve({ ok: true })
+       export const load = { func: async () => config }`
+    )
+    const result = await runner.run(file)
+    assert.equal(result.ok, false)
+    // Nothing is wrong with this file — the `cjs` emit is what cannot take it,
+    // and the caller has to be able to tell the developer that.
+    assert.equal(
+      isTopLevelAwaitLimitation((result as { error: Error }).error),
+      true
+    )
+  })
+
+  test('a thrown non-Error still arrives as an Error carrying its value', async () => {
+    const runner = createModuleRunner()
+    const file = join(tmpDir, 'throws-a-string.ts')
+    await writeFile(file, `throw 'boom'`)
+    const result = await runner.run(file)
+    assert.equal(result.ok, false)
+    const { error } = result as { error: Error }
+    assert.ok(error instanceof Error)
+    assert.equal(error.message, 'boom')
+    assert.equal((error as { cause?: unknown }).cause, 'boom')
   })
 
   test('editing and reimporting a module 200x does not leak memory', async () => {
@@ -153,8 +196,8 @@ describe('createModuleRunner', { concurrency: false }, () => {
 
     for (let i = 1; i <= 200; i++) {
       await write(i)
-      const mod = await runner.run(file)
-      assert.ok(mod)
+      const result = await runner.run(file)
+      assert.equal(result.ok, true)
     }
     gc()
     const growth = heapUsedMb() - baseline

package/src/dev/module-runner.ts

@@ -18,22 +18,35 @@ const loadTransform = async (): Promise<EsbuildTransform> => {
   return transformSync
 }
 
+/** The outcome of one run. A failure carries its error rather than collapsing
+ *  to `null`: the caller keeps serving the previously-loaded code, so unless the
+ *  reason travels with the failure the running process silently disagrees with
+ *  the file on disk and nothing anywhere says why. */
+export type PikkuModuleRunResult =
+  { ok: true; exports: Record<string, unknown> } | { ok: false; error: Error }
+
 export interface PikkuModuleRunner {
   /** Run a user module by absolute path. Repeated runs of one path overwrite a
-   *  single registry slot. Returns `null` on failure so the caller can keep the
-   *  previously-loaded code. */
-  run: (absPath: string) => Promise<Record<string, unknown> | null>
+   *  single registry slot. Failure is returned, not thrown, so the caller can
+   *  keep the previously-loaded code — and the discriminant makes that case
+   *  impossible to read past by accident. */
+  run: (absPath: string) => Promise<PikkuModuleRunResult>
   evict: (absPath: string) => void
   clear: () => void
   readonly size: number
 }
 
+/** esbuild states pikku's one documented reload limitation only in the text of
+ *  its transform error. Matching it is worth the fragility: the developer's file
+ *  is correct, and no amount of re-reading it will reveal that the reloader —
+ *  not the file — is what cannot cope. */
+export const isTopLevelAwaitLimitation = (error: Error): boolean =>
+  /top-level await/i.test(error.message)
+
 export const createModuleRunner = (): PikkuModuleRunner => {
   const registry = new Map<string, Record<string, unknown>>()
 
-  const run = async (
-    filePath: string
-  ): Promise<Record<string, unknown> | null> => {
+  const run = async (filePath: string): Promise<PikkuModuleRunResult> => {
     const absPath = resolve(filePath)
     try {
       const transform = await loadTransform()
@@ -55,11 +68,20 @@ export const createModuleRunner = (): PikkuModuleRunner => {
       fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath))
 
       registry.set(absPath, moduleObj.exports)
-      return moduleObj.exports
-    } catch {
+      return { ok: true, exports: moduleObj.exports }
+    } catch (thrown) {
       // A bad edit, or the one known limitation: a file using top-level
-      // `await`, which cannot be emitted in `cjs` form.
-      return null
+      // `await`, which cannot be emitted in `cjs` form. Normalised to an
+      // `Error` so the caller always has a message and a stack to print
+      // without re-deriving them; a non-`Error` throw keeps its original value
+      // as the `cause`.
+      return {
+        ok: false,
+        error:
+          thrown instanceof Error
+            ? thrown
+            : new Error(String(thrown), { cause: thrown }),
+      }
     }
   }