@xdelivered/emberflow 0.2.0 → 0.5.0

package/server/runRegistry.ts

@@ -5,11 +5,13 @@ import type {
 import { InMemoryTraceSink, startRun, type FlowRun, type NodeRegistry } from '../src/engine';
 import { createDefaultRegistry } from '../src/nodes';
 import { redactSecrets } from './redact';
-import { makeSubflowRunner } from './subflowRunner';
+import { makeSubflowRunner, type DrillEntry, type DrillState } from './subflowRunner';
 
 /** SSE-shaped events, mirroring ExecutorEvents 1:1. */
 export type RunEvent =
-  | { type: 'nodeState'; nodeId: string; state: NodeRunState }
+  /** `workflowId` is the flow the node belongs to: the root flow for the
+   *  run's own nodes, the CHILD flow's id for a stepped subflow's nodes. */
+  | { type: 'nodeState'; workflowId: string; nodeId: string; state: NodeRunState }
   | { type: 'log'; line: LogLine }
   | {
       type: 'finished';
@@ -27,6 +29,25 @@ interface LiveRun {
   listeners: Set<Listener>;
   finished: boolean;
   cleanupTimer?: ReturnType<typeof setTimeout>;
+  /** Serializes step() calls per run: a second concurrent step() would
+   *  re-arm `state.onChildStarted` (last writer wins) and double-drive the
+   *  executor, hanging the first caller. */
+  stepChain?: Promise<unknown>;
+  /** Present only for stepped runs: subflow drill-in state (see step()). */
+  drill?: {
+    state: DrillState;
+    /** The ROOT executor's step() promise left pending while a child runs. */
+    rootPendingStep?: Promise<boolean>;
+  };
+}
+
+/** Result of one composite step on a stepped run (see RunRegistry.step). */
+export interface StepResult {
+  done: boolean;
+  /** Set when this step drove execution INTO a subflow child. */
+  entered?: { workflowId: string; nodeId: string };
+  /** Set when this step completed the deepest child and popped back out. */
+  exited?: true;
 }
 
 const RETAIN_FINISHED_MS = 10 * 60 * 1000; // 10 minutes
@@ -93,6 +114,10 @@ export class RunRegistry {
        *  error-handler run — stamped onto this run's `finished` event as
        *  `errorHandler: { firedBy }`. Only meaningful alongside isErrorHandler. */
       errorHandlerFiredBy?: string;
+      /** When true (a step-mode run), Subflow children become step-drivable:
+       *  entering one pauses inside it instead of running it to completion in
+       *  a single opaque step. Drive the run via `step(runId)`. */
+      stepped?: boolean;
     },
   ): { runId: string; handle: FlowRun } {
     this.evictIfNeeded();
@@ -116,6 +141,11 @@ export class RunRegistry {
     // the child via loadFlow, runs it to completion on the same registry
     // sharing the parent's environment, and forwards its (prefixed) logs into
     // this run's SSE stream via `onLog`.
+    // Stepped runs share ONE drill state across the root's runner and every
+    // nested child's runner (makeSubflowRunner threads `opts` through), so a
+    // grandchild pushes onto the same stack and nesting works.
+    const drillState: DrillState | undefined = opts.stepped ? { stack: [] } : undefined;
+
     const subflowRunner = makeSubflowRunner(
       {
         loadFlow: (id) => this.loadFlow?.(id),
@@ -127,6 +157,18 @@ export class RunRegistry {
         mockRun: opts.mockRun,
         trace: this.sink,
         onLog: (line) => emit({ type: 'log', line }),
+        drill: drillState,
+        // Stepped children stream node states into this run's SSE stream,
+        // tagged with the CHILD flow's id so the client can route them.
+        // After a drill-aware cancel the rejected parent executions unwind in
+        // the background (recording their Subflow nodes as failed) — child
+        // states from that unwinding must not reach subscribers post-finish.
+        onNodeState: drillState
+          ? (workflowId, nodeId, state) => {
+              if (drillState.cancelled) return;
+              emit({ type: 'nodeState', workflowId, nodeId, state });
+            }
+          : undefined,
       },
       [flow.id],
     );
@@ -145,9 +187,14 @@ export class RunRegistry {
       trace: this.sink,
       subflowRunner,
       events: {
-        onNodeStateChange: (nodeId, state) => emit({ type: 'nodeState', nodeId, state }),
+        onNodeStateChange: (nodeId, state) =>
+          emit({ type: 'nodeState', workflowId: flow.id, nodeId, state }),
         onLog: (line) => emit({ type: 'log', line }),
         onRunFinished: (run) => {
+          // Idempotent: after a drill-aware cancel the root executor's pending
+          // Subflow execution can fail in the background and re-finish the run
+          // — subscribers already saw the cancelled `finished` event.
+          if (entry.finished) return;
           emit({
             type: 'finished',
             run,
@@ -163,10 +210,160 @@ export class RunRegistry {
     });
 
     entry.handle = handle;
+    if (drillState) entry.drill = { state: drillState };
     this.runs.set(handle.run.id, entry);
     return { runId: handle.run.id, handle };
   }
 
+  /**
+   * One composite step of a run, drill-aware. For stepped runs a Subflow node
+   * is no longer one opaque step: entering it pauses inside the child
+   * (`entered`), subsequent steps drive the child's nodes, and completing the
+   * child pops back out (`exited`). Non-stepped runs (no drill state) fall
+   * back to a plain executor step. Unknown run → undefined.
+   */
+  async step(runId: string): Promise<StepResult | undefined> {
+    const entry = this.runs.get(runId);
+    if (!entry) return undefined;
+    // Serialize per run: concurrent step() calls would each arm
+    // `state.onChildStarted` (last writer wins) and double-drive the
+    // executor, so the second caller waits for the first to settle.
+    const result = (entry.stepChain ?? Promise.resolve()).then(() => this.stepLevels(entry));
+    entry.stepChain = result.catch(() => undefined);
+    return result;
+  }
+
+  /**
+   * One composite step, drill-aware. Structured as a loop over levels: each
+   * pass drives the current deepest level (a pending stashed step, or a fresh
+   * executor step) while racing "a new child started". Popping a finished
+   * child continues the loop on its parent's stashed step WITH the race still
+   * armed — the parent's still-pending Subflow node execution may call
+   * runSubflow again (retry, or a custom node making sequential calls), and
+   * that re-entry must surface as `entered`, not deadlock the fold.
+   */
+  private async stepLevels(entry: LiveRun): Promise<StepResult> {
+    const drill = entry.drill;
+    if (!drill) {
+      const more = await entry.handle.step();
+      return { done: !more };
+    }
+
+    const { state } = drill;
+    // Cancelled mid-drill: the stack was already unwound by cancel(); report
+    // done without driving anything.
+    if (state.cancelled) return { done: true };
+
+    // Set once this step pops a child; carried onto whatever this step
+    // ultimately reports (including an `entered` for a re-run child).
+    let exited = false;
+    const withExit = (r: StepResult): StepResult => (exited ? { ...r, exited: true } : r);
+
+    for (;;) {
+      // The level being stepped: the deepest drilled-in child, or the root run.
+      const level = state.stack.length > 0 ? state.stack[state.stack.length - 1] : undefined;
+      const handle = level ? level.handle : entry.handle;
+      const pendingStep = level ? level.pendingStep : drill.rootPendingStep;
+      const setPending = (p: Promise<boolean> | undefined): void => {
+        if (level) level.pendingStep = p;
+        else drill.rootPendingStep = p;
+      };
+
+      // A Subflow node's execution blocks inside runSubflow until its child
+      // completes, so the step promise alone can never report "entered a
+      // child" — arm the child-started signal BEFORE awaiting and race them.
+      const childStarted = new Promise<DrillEntry>((res) => {
+        state.onChildStarted = res;
+      });
+      const stepPromise = pendingStep ?? handle.step();
+      setPending(undefined);
+
+      type Raced = { kind: 'stepped'; more: boolean } | { kind: 'entered'; child: DrillEntry };
+      let raced: Raced;
+      try {
+        raced = await Promise.race([
+          stepPromise.then((more): Raced => ({ kind: 'stepped', more })),
+          childStarted.then((child): Raced => ({ kind: 'entered', child })),
+        ]);
+      } catch (err) {
+        state.onChildStarted = undefined;
+        if (!level) throw err;
+        // A child level's step threw outright (not a recorded node failure —
+        // the executor catches those). Reject the parent's blocked runSubflow,
+        // which surfaces it as the Subflow node's error, then fold the parent
+        // (next loop pass, race re-armed).
+        state.stack.pop();
+        level.reject(err);
+        exited = true;
+        continue;
+      }
+      state.onChildStarted = undefined;
+
+      if (raced.kind === 'entered') {
+        // The level's step stays pending for the whole child run — stash it;
+        // the step that later pops this child folds its boolean back in.
+        setPending(stepPromise);
+        return withExit({
+          done: false,
+          entered: { workflowId: raced.child.workflowId, nodeId: raced.child.viaNodeId },
+        });
+      }
+
+      if (raced.more) return withExit({ done: false });
+
+      // This level has no more nodes: its run is complete.
+      if (!level) return withExit({ done: true });
+
+      // Pop the finished child and hand its completed run (succeeded OR failed)
+      // to the parent's blocked runSubflow — the success/failure semantics live
+      // in subflowRunner, byte-identical to the non-stepped path. The parent's
+      // stashed step is folded in by the next loop pass, with the child-started
+      // race re-armed so a retrying Subflow node re-entering its child yields
+      // `exited` + `entered` instead of hanging.
+      state.stack.pop();
+      level.resolve(level.handle.run);
+      exited = true;
+    }
+  }
+
+  /**
+   * Cancel a run, drill-aware. For a stepped run drilled into subflows this
+   * cancels every stacked child deepest-first and rejects the promise each
+   * parent's Subflow node execution is blocked on — those pending executions
+   * then unwind in the background exactly like an in-flight node after a
+   * plain root cancel today (recorded, but the run is already finished).
+   * step() after cancel reports { done: true } without executing anything.
+   * Returns false for an unknown run.
+   */
+  /** Cancels every live (non-finished) run — the server's shutdown path, so
+   *  in-flight executions (and their drilled subflow children) don't keep
+   *  running headless after the process is asked to die. */
+  shutdown(): void {
+    for (const [id, run] of this.runs) {
+      if (!run.finished) this.cancel(id);
+    }
+  }
+
+  cancel(runId: string): boolean {
+    const entry = this.runs.get(runId);
+    if (!entry) return false;
+    const drill = entry.drill;
+    if (drill) {
+      const { state } = drill;
+      state.cancelled = true;
+      state.onChildStarted = undefined;
+      while (state.stack.length > 0) {
+        const child = state.stack.pop()!;
+        child.pendingStep = undefined;
+        child.handle.cancel();
+        child.reject(new Error('run cancelled'));
+      }
+      drill.rootPendingStep = undefined;
+    }
+    entry.handle.cancel();
+    return true;
+  }
+
   /**
    * Best-effort: fires `errorOperation` (resolved via the same `loadFlow`
    * callback Subflow nodes use) as a new run when `failedRun` finished with

package/server/setupStatus.test.ts

@@ -78,6 +78,9 @@ describe('GET /setup-status', () => {
     const body = await res.json();
 
     expect(Array.isArray(body.agents)).toBe(true);
+    // The temp project dir isn't inside a git repo — reported as such so the
+    // checklist can gate the agent features on it.
+    expect(body.git).toEqual({ repo: false });
     // A fresh project has no environments file → the synthesized fallback is
     // reported as unconfigured with zero real environments.
     expect(body.environments).toMatchObject({

package/server/sourceNav.test.ts

@@ -0,0 +1,382 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { getSourceFile, resetSourceNavCaches, type SourceFilePayload } from './sourceNav';
+import { buildRegistries } from './projectMode';
+import { nodesPayload } from './nodesPayload';
+import type { NodeRegistry } from '../src/engine';
+
+let root: string;
+
+function write(rel: string, lines: string[]): void {
+  const p = join(root, rel);
+  mkdirSync(join(p, '..'), { recursive: true });
+  writeFileSync(p, lines.join('\n') + '\n');
+}
+
+async function payloadOf(rel: string): Promise<SourceFilePayload> {
+  const result = await getSourceFile(root, rel);
+  if (!result.ok) throw new Error(`expected ok for ${rel}, got ${result.status}: ${result.error}`);
+  return result.payload;
+}
+
+beforeAll(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), 'sourcenav-')));
+  resetSourceNavCaches();
+
+  write('nodes.mjs', [
+    "import { deriveTrackingActual } from './shipment-logic.mjs';", // 1
+    "import { createHash } from 'node:crypto';", // 2
+    "import express from 'express';", // 3
+    "import { helper } from '@scope/pkg/utils';", // 4
+    '', // 5
+    'const TAX_RATE = 0.2;', // 6
+    '', // 7
+    'export function handler(input) {', // 8
+    "  void createHash('sha256');", // 9
+    '  void express;', // 10
+    '  void helper;', // 11
+    '  return deriveTrackingActual(input) * TAX_RATE;', // 12
+    '}', // 13
+    '', // 14
+    'export async function loadPlugin(name) {', // 15
+    '  return await import(name);', // 16
+    '}', // 17
+  ]);
+
+  write('shipment-logic.mjs', [
+    'function nestedHelper(shipment) {', // 1
+    '  return shipment.weight * 2;', // 2
+    '}', // 3
+    '', // 4
+    'export function deriveTrackingActual(shipment) {', // 5
+    '  return nestedHelper(shipment);', // 6
+    '}', // 7
+  ]);
+
+  write('index.mjs', [
+    "export { deriveTrackingActual } from './shipment-logic.mjs';", // 1
+    "export * from './extras.mjs';", // 2
+  ]);
+  write('extras.mjs', ['export const EXTRA = 1;']);
+
+  write('via-index.mjs', [
+    "import { deriveTrackingActual } from './index.mjs';", // 1
+    '', // 2
+    'export function viaIndex(x) {', // 3
+    '  return deriveTrackingActual(x);', // 4
+    '}', // 5
+  ]);
+
+  // Mutual value-import cycle.
+  write('circ-a.mjs', [
+    "import { b } from './circ-b.mjs';",
+    'export function a() {',
+    '  return b();',
+    '}',
+  ]);
+  write('circ-b.mjs', [
+    "import { a } from './circ-a.mjs';",
+    'export function b() {',
+    '  return a();',
+    '}',
+  ]);
+
+  // Re-export cycle: chasing the declaration must terminate.
+  write('reexp-a.mjs', ["export { spin } from './reexp-b.mjs';"]);
+  write('reexp-b.mjs', ["export { spin } from './reexp-a.mjs';"]);
+  write('spin-consumer.mjs', [
+    "import { spin } from './reexp-a.mjs';",
+    'export const useSpin = spin;',
+  ]);
+
+  // TS variant with type annotations + TS-style .js specifier for a .ts file.
+  write('ts/handler.ts', [
+    "import { deriveTs } from './logic.js';", // 1
+    '', // 2
+    'export function tsHandler(n: number): number {', // 3
+    '  return deriveTs(n);', // 4
+    '}', // 5
+  ]);
+  write('ts/logic.ts', [
+    'export function deriveTs(n: number): number {', // 1
+    '  return n * 2;', // 2
+    '}', // 3
+  ]);
+
+  // tsconfig paths alias (JSONC — comments must parse leniently).
+  write('tsconfig.json', [
+    '{',
+    '  // single-star paths alias, exercised by aliased.ts',
+    '  "compilerOptions": {',
+    '    "paths": { "@lib/*": ["lib/*"] }',
+    '  }',
+    '}',
+  ]);
+  write('lib/util.ts', ['export function util(): number {', '  return 1;', '}']);
+  write('aliased.ts', ["import { util } from '@lib/util';", '', 'export const z = util();']);
+
+  // Secrets / denied files that must never be served.
+  write('.env', ['SECRET=shh']);
+  mkdirSync(join(root, 'sub'), { recursive: true });
+  write('sub/.env.local', ['SECRET=shh']);
+  write('server.key', ['---KEY---']);
+  write('cert.pem', ['---PEM---']);
+  write('emberflow.secrets.json', ['{}']);
+  mkdirSync(join(root, 'node_modules', 'somepkg'), { recursive: true });
+  write('node_modules/somepkg/index.js', ['module.exports = 1;']);
+});
+
+afterAll(() => {
+  if (root) rmSync(root, { recursive: true, force: true });
+});
+
+describe('getSourceFile: parse + declarations', () => {
+  it('serves the whole file with language and repo-relative path', async () => {
+    const p = await payloadOf('nodes.mjs');
+    expect(p.path).toBe('nodes.mjs');
+    expect(p.language).toBe('js');
+    expect(p.content).toContain('TAX_RATE');
+    expect(p.resolver).toBeUndefined();
+  });
+
+  it('extracts top-level declarations with kind, lines, and exported flag', async () => {
+    const p = await payloadOf('shipment-logic.mjs');
+    const decls = p.symbols.declarations;
+    const nested = decls.find((d) => d.name === 'nestedHelper');
+    expect(nested).toMatchObject({ kind: 'fn', line: 1, endLine: 3, exported: false });
+    const derive = decls.find((d) => d.name === 'deriveTrackingActual');
+    expect(derive).toMatchObject({ kind: 'fn', line: 5, endLine: 7, exported: true });
+  });
+
+  it('extracts a local const with an initializer', async () => {
+    const p = await payloadOf('nodes.mjs');
+    const tax = p.symbols.declarations.find((d) => d.name === 'TAX_RATE');
+    expect(tax).toMatchObject({ kind: 'const', line: 6, exported: false });
+  });
+});
+
+describe('getSourceFile: import resolution', () => {
+  it('resolves a relative sibling import to a project file with the declaration line', async () => {
+    const p = await payloadOf('nodes.mjs');
+    const imp = p.symbols.imports.find((i) => i.local === 'deriveTrackingActual');
+    expect(imp).toBeDefined();
+    expect(imp!.from).toBe('./shipment-logic.mjs');
+    expect(imp!.resolution).toEqual({ kind: 'project', path: 'shipment-logic.mjs', line: 5 });
+  });
+
+  it('classifies node:crypto as builtin', async () => {
+    const p = await payloadOf('nodes.mjs');
+    const imp = p.symbols.imports.find((i) => i.local === 'createHash');
+    expect(imp!.resolution).toEqual({ kind: 'builtin' });
+  });
+
+  it('classifies a bare specifier as external with the package name', async () => {
+    const p = await payloadOf('nodes.mjs');
+    const imp = p.symbols.imports.find((i) => i.local === 'express');
+    expect(imp!.name).toBe('default');
+    expect(imp!.resolution).toEqual({ kind: 'external', package: 'express' });
+  });
+
+  it('extracts the scoped package name from a deep specifier', async () => {
+    const p = await payloadOf('nodes.mjs');
+    const imp = p.symbols.imports.find((i) => i.local === 'helper');
+    expect(imp!.resolution).toEqual({ kind: 'external', package: '@scope/pkg' });
+  });
+
+  it('reports a computed dynamic import as unresolved with a reason', async () => {
+    const p = await payloadOf('nodes.mjs');
+    const dyn = p.symbols.imports.find((i) => i.resolution.kind === 'unresolved');
+    expect(dyn).toBeDefined();
+    expect((dyn!.resolution as { reason: string }).reason).toMatch(/dynamic/i);
+  });
+
+  it('follows a re-export chain through an index module to the declaring file', async () => {
+    const p = await payloadOf('via-index.mjs');
+    const imp = p.symbols.imports.find((i) => i.local === 'deriveTrackingActual');
+    expect(imp!.from).toBe('./index.mjs');
+    expect(imp!.resolution).toEqual({ kind: 'project', path: 'shipment-logic.mjs', line: 5 });
+  });
+
+  it('handles a circular import pair without looping', async () => {
+    const p = await payloadOf('circ-a.mjs');
+    const imp = p.symbols.imports.find((i) => i.local === 'b');
+    expect(imp!.resolution).toMatchObject({ kind: 'project', path: 'circ-b.mjs' });
+  });
+
+  it('terminates on a re-export cycle (depth cap + cycle set)', async () => {
+    const p = await payloadOf('spin-consumer.mjs');
+    const imp = p.symbols.imports.find((i) => i.local === 'spin');
+    expect(imp!.resolution.kind).toBe('project');
+  });
+
+  it('maps a TS-style .js specifier to the .ts source (extension ladder)', async () => {
+    const p = await payloadOf('ts/handler.ts');
+    expect(p.language).toBe('ts');
+    const imp = p.symbols.imports.find((i) => i.local === 'deriveTs');
+    expect(imp!.resolution).toEqual({ kind: 'project', path: 'ts/logic.ts', line: 1 });
+  });
+
+  it('honors single-star tsconfig paths (parsed leniently as JSONC)', async () => {
+    const p = await payloadOf('aliased.ts');
+    const imp = p.symbols.imports.find((i) => i.local === 'util');
+    expect(imp!.resolution).toEqual({ kind: 'project', path: 'lib/util.ts', line: 1 });
+  });
+});
+
+describe('getSourceFile: re-exports of the served file', () => {
+  it('lists named and star re-exports with resolutions', async () => {
+    const p = await payloadOf('index.mjs');
+    const named = p.symbols.reexports.find((r) => r.name === 'deriveTrackingActual');
+    expect(named!.from).toBe('./shipment-logic.mjs');
+    expect(named!.resolution).toEqual({ kind: 'project', path: 'shipment-logic.mjs', line: 5 });
+    const star = p.symbols.reexports.find((r) => r.name === '*');
+    expect(star!.from).toBe('./extras.mjs');
+    expect(star!.resolution).toMatchObject({ kind: 'project', path: 'extras.mjs' });
+  });
+});
+
+describe('getSourceFile: path guards', () => {
+  const denied = [
+    '../../etc/passwd',
+    '/etc/passwd',
+    'node_modules/somepkg/index.js',
+    '.env',
+    'sub/.env.local',
+    'server.key',
+    'cert.pem',
+    'emberflow.secrets.json',
+  ];
+  for (const rel of denied) {
+    it(`denies ${rel} with a generic 400`, async () => {
+      const result = await getSourceFile(root, rel);
+      expect(result.ok).toBe(false);
+      if (result.ok) return;
+      expect(result.status).toBe(400);
+      // Generic message: never echo the requested path back.
+      expect(result.error).not.toContain(rel);
+    });
+  }
+
+  it('404s for a missing file inside the root', async () => {
+    const result = await getSourceFile(root, 'does-not-exist.mjs');
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.status).toBe(404);
+  });
+});
+
+describe('getSourceFile: caching', () => {
+  it('invalidates the parse cache when the file mtime changes', async () => {
+    write('mut.mjs', ['export const FIRST = 1;']);
+    utimesSync(join(root, 'mut.mjs'), 1_000, 1_000);
+    const before = await payloadOf('mut.mjs');
+    expect(before.content).toContain('FIRST');
+    expect(before.symbols.declarations.map((d) => d.name)).toContain('FIRST');
+
+    write('mut.mjs', ['export const SECOND = 2;']);
+    utimesSync(join(root, 'mut.mjs'), 2_000, 2_000);
+    const after = await payloadOf('mut.mjs');
+    expect(after.content).toContain('SECOND');
+    expect(after.symbols.declarations.map((d) => d.name)).toContain('SECOND');
+    expect(after.content).not.toContain('FIRST');
+  });
+});
+
+describe('getSourceFile: typescript unavailable', () => {
+  it('returns resolver: unavailable with content but empty symbols when the ts import fails', async () => {
+    const result = await getSourceFile(root, 'nodes.mjs', {
+      tsLoader: async () => {
+        throw new Error('typescript not installed');
+      },
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.payload.resolver).toBe('unavailable');
+    expect(result.payload.content).toContain('TAX_RATE');
+    expect(result.payload.symbols.declarations).toEqual([]);
+    expect(result.payload.symbols.imports).toEqual([]);
+  });
+});
+
+describe('regression: DeriveShipmentActuals → deriveTrackingActual (thin-adapter consumer shape)', () => {
+  let regRoot: string;
+
+  beforeAll(async () => {
+    regRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sourcenav-regression-')));
+    const w = (rel: string, lines: string[]): void =>
+      writeFileSync(join(regRoot, rel), lines.join('\n') + '\n');
+    w('shipment-logic.mjs', [
+      'function nestedHelper(shipment) {', // 1
+      '  return (shipment.weight ?? 0) * 2;', // 2
+      '}', // 3
+      '', // 4
+      'export function deriveTrackingActual(shipment) {', // 5
+      '  return nestedHelper(shipment);', // 6
+      '}', // 7
+    ]);
+    w('nodes.mjs', [
+      "import { deriveTrackingActual } from './shipment-logic.mjs';", // 1
+      '', // 2
+      'export function registerNodes(registry) {', // 3
+      '  registry.register(', // 4
+      "    { type: 'DeriveShipmentActuals', label: 'Derive Shipment Actuals' },", // 5
+      '    async (ctx) => ({ actual: deriveTrackingActual(ctx.input) }),', // 6
+      '  );', // 7
+      '}', // 8
+    ]);
+  });
+
+  afterAll(() => {
+    if (regRoot) rmSync(regRoot, { recursive: true, force: true });
+  });
+
+  it('nodesPayload carries the node sourceRef, and /source-file navigates to the helper', async () => {
+    const mod = (await import(pathToFileURL(join(regRoot, 'nodes.mjs')).href)) as {
+      registerNodes: (r: NodeRegistry) => void;
+    };
+    const { validation } = buildRegistries({
+      root: regRoot,
+      flowsDir: join(regRoot, 'emberflow', 'flows'),
+      language: 'javascript',
+      registerNodes: mod.registerNodes,
+    });
+
+    // 1. The registration was captured and lands in the payload repo-relative.
+    // (Exact line accuracy under the production loader is asserted by
+    // registry.sourceRef.test.ts and sourceNavRoute.test.ts — vitest's
+    // vite-node transform shifts lines of in-process dynamic imports.)
+    const payload = nodesPayload(validation, regRoot);
+    const node = payload.nodes.find((n) => n.type === 'DeriveShipmentActuals');
+    expect(node).toBeDefined();
+    expect(node!.sourceRef!.file).toBe('nodes.mjs');
+    expect(typeof node!.sourceRef!.line).toBe('number');
+    expect(node!.builtin).toBeUndefined();
+
+    // Built-ins registered from the Emberflow package are outside regRoot.
+    const builtinNode = payload.nodes.find((n) => n.type === 'ValidateCredentials');
+    expect(builtinNode).toBeDefined();
+    expect(builtinNode!.builtin).toBe(true);
+    expect(builtinNode!.sourceRef).toBeUndefined();
+
+    // 2. /source-file on the handler module resolves the imported helper.
+    const handlerFile = await getSourceFile(regRoot, 'nodes.mjs');
+    expect(handlerFile.ok).toBe(true);
+    if (!handlerFile.ok) return;
+    const imp = handlerFile.payload.symbols.imports.find((i) => i.local === 'deriveTrackingActual');
+    expect(imp!.resolution).toEqual({ kind: 'project', path: 'shipment-logic.mjs', line: 5 });
+
+    // 3. /source-file on the helper module exposes its declaration lines.
+    const logicFile = await getSourceFile(regRoot, 'shipment-logic.mjs');
+    expect(logicFile.ok).toBe(true);
+    if (!logicFile.ok) return;
+    const derive = logicFile.payload.symbols.declarations.find(
+      (d) => d.name === 'deriveTrackingActual',
+    );
+    expect(derive).toMatchObject({ kind: 'fn', line: 5, endLine: 7, exported: true });
+    const nested = logicFile.payload.symbols.declarations.find((d) => d.name === 'nestedHelper');
+    expect(nested).toMatchObject({ kind: 'fn', line: 1, exported: false });
+  });
+});