@webjsdev/server 0.8.58 → 0.8.59

package/src/dev.js

@@ -15,7 +15,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { buildRouteTable, matchPage, matchApi } from './router.js';
 import { generateRouteTypes } from './route-types.js';
 import { ssrPage, ssrNotFound, setClientRouterEnabled } from './ssr.js';
-import { loadPageAction, runPageAction } from './page-action.js';
+import { runFormAction } from './form-dispatch.js';
 import { handleApi } from './api.js';
 import {
   buildActionIndex,
@@ -26,7 +26,7 @@ import {
   hasUseServerDirective,
   hashFile,
 } from './actions.js';
-import { registerSeedHooks } from './action-seed.js';
+import { registerActionHooks } from './action-seed.js';
 import { readRegenerateRules, maybeRegenerate, isRegenerateOutputPath } from './dev-regenerate.js';
 import { stripTypeScript, ensureStripper } from './ts-strip.js';
 import { defaultLogger } from './logger.js';
@@ -93,7 +93,8 @@ import { setVendorEntries, setCoreInstall, publishBuildId, setAppSourceId, setBa
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { propagateTrustedRemoteIp } from './rate-limit.js';
 import { readAllowedOrigins } from './csrf.js';
-import { setAssetUrlProvider } from '@webjsdev/core';
+import { setAssetUrlProvider, setFormActionResolver } from '@webjsdev/core';
+import { resolveActionIdentity } from './form-action-identity.js';
 import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports, resolveAssetUrl } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
@@ -640,13 +641,17 @@ export async function createRequestHandler(opts) {
   // never touched the disk.
   setAssetUrlProvider((p) => resolveAssetUrl(p, basePath()));
 
-  // SSR action-result seeding (#472). Install the process-global module load
-  // hook NOW, at boot, before any `'use server'` action module is imported (ESM
-  // caches by URL, so a module loaded before the hook would never be faceted).
-  // Read once (not per-rebuild): the hook is global and cannot be cleanly
-  // un-installed, so toggling needs a restart. Disabled -> no hook, no ambient
-  // collector wrap in ssr.js, and module loading stays byte-identical.
-  if (await readSeedEnabled(appDir)) await registerSeedHooks();
+  // The `'use server'` load hook. Install it NOW, at boot, before any action
+  // module is imported (ESM caches by URL, so a module loaded before the hook
+  // would never be wrapped). Read once (not per-rebuild): the hook is global
+  // and cannot be cleanly un-installed, so toggling needs a restart.
+  //
+  // It installs UNCONDITIONALLY, and only seed collection (#472) follows the
+  // `webjs.seed` switch. Action identity (#1155) rides the same hook, and it is
+  // what a bound `<form action=${action}>` resolves through, so gating the hook
+  // on seeding would mean `webjs.seed: false` silently broke every no-JS form.
+  await registerActionHooks({ seed: await readSeedEnabled(appDir) });
+
 
   // When an app commits a vendor pin (.webjs/vendor/importmap.json) it carries a
   // deterministic vendor map that is cheap to read (one file, no analysis, no
@@ -757,7 +762,7 @@ export async function createRequestHandler(opts) {
   // package.json `webjs.maxBodyBytes` / `webjs.maxMultipartBytes` plus the env
   // overrides. The secure defaults (1 MiB JSON/RPC, 10 MiB form) apply when
   // unconfigured. Stamped on every request via `setBodyLimits` so `readBody`
-  // (used inside route handlers) enforces the same cap the RPC and page-action
+  // (used inside route handlers) enforces the same cap the RPC and form-dispatch
   // paths do.
   const bodyLimits = await readBodyLimitsFromApp(appDir);
 
@@ -797,14 +802,27 @@ export async function createRequestHandler(opts) {
     regenerateRules: dev ? await readRegenerateRules(appDir) : [],
   };
 
+  // Teach the renderers how to turn a real server-action function into the
+  // `<hash>/<fn>` identity a form submits (#1155). The hook path is
+  // process-global and needs no index; `state.actionIndex` is consulted only as
+  // a hash memo, and by the scan fallback for a runtime with no hook. In a
+  // process running several handlers the fallback therefore resolves against
+  // the most recently booted one, which is the same scope the asset-url
+  // provider already has.
+  setFormActionResolver((fn) => (state.actionIndex ? resolveActionIdentity(state.actionIndex, fn) : null));
+
   /**
    * Report a dev error (#264): build a frame and push it to the open tab via
    * the SSE overlay channel. DEV-ONLY and best-effort, so it can never affect a
    * response or crash the server (a frame-build failure is swallowed). No file
    * path or source is ever built in prod (the early return), so nothing leaks.
    *
+   * `info.url` stamps a `render` frame with the URL that produced it (#1047), so
+   * the browser overlay can refuse a frame for a page the tab is not viewing.
+   * A `ts-strip` / `rebuild` frame passes none and stays unscoped.
+   *
    * @param {unknown} error
-   * @param {{ kind?: 'render'|'ts-strip'|'rebuild', file?: string, line?: number, column?: number, hint?: string }} [info]
+   * @param {{ kind?: 'render'|'ts-strip'|'rebuild', file?: string, line?: number, column?: number, hint?: string, url?: string }} [info]
    */
   function reportDevError(error, info = {}) {
     if (!dev) return;
@@ -1181,7 +1199,7 @@ export async function createRequestHandler(opts) {
 
       // Make the resolved body-size limits (issue #237) readable from the
       // request scope, so `readBody` inside a route handler enforces the same
-      // cap the framework's own RPC / page-action body reads do.
+      // cap the framework's own RPC / form-dispatch body reads do.
       setBodyLimits(state.bodyLimits);
 
       let pathname = '/';
@@ -1349,7 +1367,7 @@ export async function createRequestHandler(opts) {
             // to the inbound `x-webjs-remote-ip` header that the copied
             // `req.headers` still carries, which a client can spoof. So strip
             // that header on the rebuild and propagate the framework-trusted IP
-            // across the new object, the same pattern page-action.js uses.
+            // across the new object, the same pattern form-dispatch.js uses.
             const headers = new Headers(req.headers);
             headers.delete('x-webjs-remote-ip');
             const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
@@ -1839,7 +1857,7 @@ function startNodeListener(ctx) {
   // Catch-all process handlers: log, but don't tear the process down on a
   // single mishandled promise. Uncaught exceptions are different: state may be
   // corrupted, so log + start an orderly shutdown rather than continuing.
-  installProcessHandlers(logger, () => shutdown('uncaughtException'));
+  installProcessHandlers(logger, () => shutdown('uncaughtException', { fatal: true }));
 
   return {
     server,
@@ -2179,14 +2197,30 @@ async function handleCore(req, ctx) {
   }
 
   // Page route. GET/HEAD render the page. A NON-GET/HEAD method (POST/PUT/…)
-  // is only routed here when the page module exports an `action` (#244); the
-  // action runs inside the page's segment middleware, then either PRG-redirects
-  // (303) on success, re-renders the same page (422) with field errors on
-  // failure, or honors a thrown redirect()/notFound(). Without an `action`
-  // export, a non-GET/HEAD request falls through to the 404 below, unchanged.
+  // is a form submission (#1155): the `__webjs_action` hidden field names the
+  // server action to run, it runs inside the page's segment middleware, and the
+  // result either PRG-redirects (303), re-renders the same page (422) with
+  // field errors, or honors a thrown redirect()/notFound(). A non-GET carrying
+  // no action identity is a 405 on a path that exists but only renders.
   {
     const page = matchPage(state.routeTable, path);
     if (page) {
+      // The URL this render is FOR, in the form the browser sees it (#1047), so
+      // the overlay's scope gate can compare it against `location.pathname +
+      // location.search`. Two details are load-bearing: the RAW `url.pathname`
+      // (not the decoded `path`) is used, because `location.pathname` is
+      // percent-encoded too; and the base path is put back, because the ingress
+      // strip already removed it from `url` while the browser's location still
+      // carries it, so without this the gate would suppress every overlay on a
+      // sub-path deploy.
+      const devErrorUrl = withBasePath(url.pathname, basePath()) + url.search;
+      // A speculative link prefetch must never raise an overlay (#1047): the
+      // user is only hovering a link to a page that throws, and the page they
+      // are actually looking at is fine. Dropping the hook also keeps the throw
+      // out of `state.lastDevError`, so the SSE replay cannot hand it to a
+      // freshly-connected tab either. The APM `onError` sink below still fires,
+      // because the render really did throw.
+      const isPrefetch = req.headers.get('x-webjs-prefetch') === '1';
       const ssrOpts = {
         dev, appDir, moduleGraph: state.moduleGraph,
         serverFiles: state.actionIndex.fileToHash,
@@ -2213,17 +2247,43 @@ async function handleCore(req, ctx) {
         // Dev error overlay (#264): a render crash pushes a frame to the open
         // tab. Dev-only (reportDevError early-returns in prod), so no source
         // leaks. Distinct from onError (the APM sink), which always fires.
-        onDevError: dev ? (e) => reportDevError(e, { kind: 'render' }) : undefined,
+        onDevError: dev && !isPrefetch
+          ? (e) => reportDevError(e, { kind: 'render', url: devErrorUrl })
+          : undefined,
       };
       if (method === 'GET' || method === 'HEAD') {
-        const handler = () => ssrPage(page.route, page.params, url, { ...ssrOpts, req });
-        return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
-      }
-      const loaded = await loadPageAction(page.route.file, dev);
-      if (loaded) {
-        const handler = () => runPageAction(page.route, page.params, url, loaded, req, ssrOpts);
+        // A successful render of URL U supersedes a RETAINED render error for
+        // that same URL (#1047), so a reconnecting tab is not handed a frame the
+        // page has since recovered from. Keyed on BOTH frame identity and url:
+        // identity so a frame this very render just reported is never wiped, url
+        // so a good render of an unrelated page cannot erase an error that is
+        // still current for the page the user is looking at (the #893 gap the
+        // retention exists to close). Dev-only, and skipped for a prefetch,
+        // which is not the user's view of anything.
+        const handler = dev && !isPrefetch
+          ? async () => {
+            const before = state.lastDevError;
+            const resp = await ssrPage(page.route, page.params, url, { ...ssrOpts, req });
+            if (
+              before && state.lastDevError === before
+              && before.kind === 'render' && before.url === devErrorUrl
+            ) state.lastDevError = null;
+            return resp;
+          }
+          : () => ssrPage(page.route, page.params, url, { ...ssrOpts, req });
         return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
       }
+      // Every non-GET/HEAD to a page runs the page's segment middleware, and
+      // the dispatcher always answers with a Response (a 405 when there is no
+      // action to run), so a middleware that post-processes `await next()`
+      // never has to handle an absent one.
+      const deps = {
+        actionIndex: state.actionIndex,
+        allowedOrigins,
+        onError: reportError ? (e) => reportError(e, req, 'action') : undefined,
+      };
+      const handler = () => runFormAction(page.route, page.params, url, req, ssrOpts, deps);
+      return runWithSegmentMiddleware(req, page.route.middlewares, handler, dev);
     }
   }
 
@@ -2845,6 +2905,11 @@ function __webjsApplyError(data) {
   let f; try { f = JSON.parse(data); } catch (_) { return; }
   renderDevOverlay(f);
 }
+// Keep the overlay tracking the page actually on screen (#1047): a render frame
+// is scoped to the URL that produced it, so navigating away takes it down, and a
+// frame that arrived before the URL advanced goes up once it does. The gate
+// itself lives inside renderDevOverlay, so __webjsApplyError needs no change.
+installDevOverlayNavSync();
 // Never reload INTO a server that is still restarting (Node's node --watch
 // briefly kills the process on an edit), which would paint a style-less,
 // half-rendered page (#893). Probe the lightweight /__webjs/version endpoint

package/src/form-action-identity.js

@@ -0,0 +1,290 @@
+/**
+ * Resolving a bound `<form action=${action}>` back to `<hash>/<fn>` (#1155).
+ *
+ * The renderer holds a function and needs the identity the browser will submit.
+ * On the client that is trivial (the RPC stub stamps its own identity on
+ * itself), but at SSR the value is the REAL server function, so something has
+ * to have watched it load. The `'use server'` load hook did, which is why it
+ * installs unconditionally rather than only when seeding is on.
+ *
+ * The naming is the RPC endpoint's, deliberately: the same `hashFile(file)`
+ * over the absolute path, the same `<hash>/<fnName>` shape. One identity
+ * scheme means the form dispatcher and the RPC endpoint resolve the same
+ * string to the same function, so the two transports can never disagree about
+ * what an action IS.
+ */
+
+import { actionIdentitiesOf, identityHookInstalled } from './action-seed.js';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * Resolved identities for functions the hook never registered. Only ever
+ * populated by the scan fallback below, so on a supported runtime it stays
+ * empty.
+ * @type {WeakMap<Function, string>}
+ */
+const _scanned = new WeakMap();
+
+/** Emit the scan-fallback warning once per process rather than per render. */
+let _warnedScan = false;
+
+/**
+ * The `<hash>/<fn>` identity of an action function, or null.
+ *
+ * @param {import('./actions.js').ActionIndex} idx
+ * @param {Function} fn
+ * @returns {Promise<string | null>}
+ */
+export async function resolveActionIdentity(idx, fn) {
+  const known = actionIdentitiesOf(fn);
+  if (known.length) {
+    // The FIRST registration the index knows. Order is defining-module-first,
+    // so a function re-exported through a barrel resolves to the module that
+    // also carries its `validate` / `middleware` / `method` / `invalidates`
+    // config exports; the barrel is used only when the defining module is not
+    // in the index at all (an action from a linked workspace package, or one
+    // reached under a path the app-tree walk never produced, such as through a
+    // symlink).
+    for (const entry of known) {
+      const hash = idx.fileToHash.get(entry.file);
+      if (!hash) continue;
+      // Falling back past the defining module can COST something, so say so.
+      // The dispatcher loads whatever module the identity names and reads
+      // `validate` / `middleware` / `method` / `invalidates` off THAT namespace
+      // BY NAME, which cuts both ways: config declared beside the action does
+      // not travel with a `export { fn } from '...'` re-export, and config the
+      // re-exporting module declares for its own exports applies to this action
+      // instead. Neither direction is knowable without loading the module,
+      // which is why the warning states the condition rather than the
+      // consequence (see `warnConfigExportsBypassed`). It warns
+      // rather than refuses because the RPC endpoint resolves the same barrel
+      // hash the same way: both transports agree, and refusing would break a
+      // page that works while leaving the RPC path open anyway.
+      if (entry !== known[0]) warnConfigExportsBypassed(known[0], entry);
+      return `${hash}/${entry.fnName}`;
+    }
+    // Registered, but under no name the index knows. Minting a hash from the
+    // path (which `actionFileHash` will happily do for any string) would
+    // produce an identity the dispatcher cannot resolve, and an unresolvable
+    // hash reads as a deploy skew: every submission would answer 422 "please
+    // submit again", forever, with nothing logged. Refusing at render is the
+    // better failure, but the renderer's message can only say "not a server
+    // action", which is wrong here and would send the author looking in the
+    // wrong place. So name the real cause once, on the server.
+    warnUnindexedAction(known[0]);
+    return null;
+  }
+  return await scanForIdentity(idx, fn);
+}
+
+/** Files already warned about, so a re-render does not repeat the line. */
+const _warnedUnindexed = new Set();
+
+/**
+ * No name the action index knows.
+ *
+ * The message names the SYMPTOM and lists the causes rather than asserting one.
+ * Two produce this, and they need opposite fixes: the module genuinely lives
+ * outside the app tree, or it lives inside but under a different path than the
+ * one that was walked (an `appDir` reached through a symlink, since the index
+ * stores the walked path while the ESM loader realpaths the module). Asserting
+ * the first would confidently misdiagnose the second, whose author would then
+ * go looking for a package that does not exist.
+ *
+ * The remedy has to say NAMED, too: `export * from` cannot be enumerated, so
+ * the facade never wraps it and nothing registers, which leaves the page
+ * failing in exactly the same way it already was.
+ *
+ * @param {{ file: string, fnName: string }} entry
+ */
+function warnUnindexedAction(entry) {
+  if (_warnedUnindexed.has(entry.file)) return;
+  _warnedUnindexed.add(entry.file);
+  console.warn(
+    `[webjs] cannot bind ${entry.fnName} to a <form>: it is a 'use server' export, but the `
+    + `action index has no entry for ${entry.file}, so the identity the browser submits `
+    + 'could never be resolved back. Common causes: the module is outside the app '
+    + 'directory, or the app directory was reached through a symlink so the walked path '
+    + `and the loaded path differ. Fix the path, or add a NAMED re-export ("export { ${entry.fnName} } `
+    + `from ...") in a 'use server' module inside the app; a star re-export cannot be `
+    + 'enumerated and will not register it.',
+  );
+}
+
+/** Defining modules already warned about for a bypassed-config fallback. */
+const _warnedBypass = new Set();
+
+/**
+ * Warn that the dispatched module is not the defining one.
+ *
+ * Deliberately CONDITIONAL about the consequence. What is known here is cheap
+ * and certain: the identity names a re-exporting module, so the dispatcher will
+ * read config off that namespace. What that costs is not knowable without
+ * loading the module, which this path refuses to do (it is a render-time
+ * resolve, and eager-loading every action module is exactly the cost
+ * `scanForIdentity` exists to avoid).
+ *
+ * Config is matched BY NAME off the dispatched namespace
+ * (`actionConfigFn(mod, 'validate')`), with no association back to a particular
+ * function, and that cuts BOTH ways. Three wordings have now been wrong by
+ * describing only one direction:
+ *
+ *   - config declared beside the action does NOT travel with a plain
+ *     `export { fn } from` re-export, so it stops applying
+ *   - config the DISPATCHING module declares DOES apply to this action, even
+ *     though it was written for one of that module's own exports
+ *
+ * The second is why "an action that declares no config loses nothing" was
+ * false: a config-less action re-exported through a module that has a
+ * `validate` for its own sibling inherits that validator, and its submissions
+ * start failing with a message about a different action.
+ *
+ * It follows that re-exporting the config into a SHARED barrel is bad advice
+ * (it attaches one action's validator to every sibling), while re-exporting it
+ * into a module holding only this action is safe and is the only option when
+ * the action lives in a workspace package several apps share, which is exactly
+ * the case that produces this warning. The remedy has to offer both, and the
+ * second needs its CONDITION stated: among indexed re-exporters the identity
+ * goes to the first one LOADED (registration order, and module load is lazy per
+ * route), so a stray second re-exporter can silently win over the remedy module
+ * depending on which page a visitor hits first.
+ *
+ * The second remedy also cannot silence this line. The defining module stays
+ * outside the index, so the fallback still runs and this check cannot see
+ * inside the dispatched module to know the config now travels with it. Round 4
+ * of this PR's review found a diagnostic that persisted in the state its own
+ * remedy produced while still describing it as broken; the honest fix is the
+ * message saying so itself.
+ *
+ * `webjs check` catches none of it: `one-action-per-configured-file` counts
+ * callables from `export function` / `export const … =>`, so a re-exported
+ * action is invisible to it (a pure barrel reads as zero callables).
+ *
+ * @param {{ file: string, fnName: string }} defining
+ * @param {{ file: string, fnName: string }} used
+ */
+function warnConfigExportsBypassed(defining, used) {
+  if (_warnedBypass.has(defining.file)) return;
+  _warnedBypass.add(defining.file);
+  console.warn(
+    `[webjs] ${defining.fnName} is bound to a <form>, but its module ${defining.file} is `
+    + `not in the action index, so the submission is dispatched through ${used.file} `
+    + 'instead. Config is matched by NAME off that module, so it flows both ways: a '
+    + '`validate` / `middleware` / `method` / `invalidates` declared beside the action does '
+    + 'not travel with a plain `export { fn } from` re-export, and any that module declares '
+    + 'of its own applies to this action. Move the action inside the app directory. Or '
+    + 're-export it from a module holding only this one action, put its config there, and '
+    + 'make sure NO other in-app module re-exports it: among re-exporters the first one '
+    + 'loaded wins the identity, so a shared barrel can silently override the dedicated '
+    + 'module. Adding config to a re-export module that carries several actions applies it '
+    + 'to all of them, and `webjs check` cannot see that. This notice keeps printing after '
+    + 'the dedicated-module fix, because the check cannot see inside the dispatched module; '
+    + 'if that module carries the config, it is working as intended. (The RPC endpoint '
+    + 'resolves the same way, so this is not specific to forms.)',
+  );
+}
+
+/**
+ * Cold-path fallback: find the function by loading the indexed action modules
+ * and comparing exports.
+ *
+ * Reached in exactly one situation: a runtime with neither
+ * `module.registerHooks` nor `Bun.plugin`, which never installs the hook at all.
+ * A module imported BEFORE the hook installed is also unwrapped, but the gate
+ * below rules it out, and the server installs the hook at boot ahead of any app
+ * module, so that shape only exists in a unit test that imports one by hand.
+ *
+ * It is gated on the hook being ABSENT rather than merely on a registry miss.
+ * The scan imports every `'use server'` module in the app, which is exactly the
+ * eager loading (DB driver init, connection pools) that `buildActionIndex`
+ * avoids by only hashing paths. Paying that during a render because one lookup
+ * missed would turn a fast miss into a slow one on every page; with the hook
+ * installed, a miss means the function genuinely is not an action, and the
+ * renderer should say so immediately.
+ *
+ * @param {import('./actions.js').ActionIndex} idx
+ * @param {Function} fn
+ * @returns {Promise<string | null>}
+ */
+export async function scanForIdentity(idx, fn) {
+  if (identityHookInstalled()) return null;
+  const cached = _scanned.get(fn);
+  if (cached) return cached;
+  if (!_warnedScan) {
+    _warnedScan = true;
+    console.warn(
+      '[webjs] resolving a bound form action by scanning the action index, because '
+      + "the 'use server' load hook is not installed on this runtime. Every action "
+      + 'module is imported to do it. Node 24+ and Bun both install the hook.',
+    );
+  }
+  for (const [hash, file] of idx.hashToFile) {
+    let mod;
+    try {
+      // Deliberately NOT cache-busted, unlike every other dev-time import here.
+      // The match is function-object identity against the instance the page
+      // already holds, and a busted specifier is a fresh module whose exports
+      // are new objects, so `value === fn` could never be true. In dev that
+      // made this fallback import every action module and always return null.
+      mod = await import(pathToFileURL(file).toString());
+    } catch {
+      continue;
+    }
+    for (const [name, value] of Object.entries(mod)) {
+      if (value !== fn) continue;
+      const id = `${hash}/${name}`;
+      _scanned.set(fn, id);
+      return id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve an identity string back to the function it names, for the form
+ * dispatcher.
+ *
+ * Returns a `reason` rather than a bare null on failure, because the failures
+ * need different responses. An unknown HASH is a deploy skew (a form rendered
+ * by an older build, submitted against a newer one), which re-renders the page
+ * with a resubmit message.
+ *
+ * An unknown FUNCTION inside a known file is NOT decided here: this resolves
+ * the file and hands back its module namespace, and the caller decides whether
+ * the named export is a callable action (it also has to reject a reserved
+ * config export, which only it knows about). That is why there is no
+ * `unknown-fn` reason.
+ *
+ * A module that THROWS at import is a third case, and folding it into skew was
+ * a real defect. The hash resolves (the index only hashes paths, it never
+ * imports), so a `.server.ts` whose module scope throws (a DB connection built
+ * at load with a missing env var) would answer every submission with "please
+ * submit again" forever, with the actual error discarded: no log line, no
+ * `onError`, nothing. The same broken module surfaces a logged 500 through a
+ * page render and through the RPC endpoint, which lets `loadModule` throw on
+ * purpose, so the form path was the one place it went silent. The error is
+ * carried out instead and the caller turns it into a sanitized, digest-logged
+ * 500 like any other action throw.
+ *
+ * @param {import('./actions.js').ActionIndex} idx
+ * @param {string} id the submitted `<hash>/<fn>` value
+ * @returns {Promise<{ ok: true, file: string, fnName: string, module: Record<string, unknown> }
+ *   | { ok: false, reason: 'malformed' | 'skew' }
+ *   | { ok: false, reason: 'load-failed', error: unknown }>}
+ */
+export async function lookupActionIdentity(idx, id) {
+  const raw = typeof id === 'string' ? id : '';
+  const slash = raw.indexOf('/');
+  if (slash <= 0 || slash === raw.length - 1) return { ok: false, reason: 'malformed' };
+  const hash = raw.slice(0, slash);
+  const fnName = raw.slice(slash + 1);
+  const file = idx.hashToFile.get(hash);
+  if (!file) return { ok: false, reason: 'skew' };
+  let module;
+  try {
+    module = await import(pathToFileURL(file).toString() + (idx.dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : ''));
+  } catch (error) {
+    return { ok: false, reason: 'load-failed', error };
+  }
+  return { ok: true, file, fnName, module };
+}