knitting 0.1.56 → 0.1.61

package/src/api.js

@@ -1,14 +1,16 @@
-import { getCallerFilePath, getCallerHref } from "./common/task-source.js";
+import { getCallerFilePath, getCallerHref, setModuleUrl, } from "./common/task-source.js";
 import { DEBUG_ENABLED, resolveDebugNamespaces } from "./debug/gate.js";
 import { genTaskID } from "./common/task-source.js";
 import { toModuleUrl } from "./common/module-url.js";
 import { endpointSymbol } from "./common/task-symbol.js";
-import { spawnWorkerContext } from "./runtime/pool.js";
-import { ChannelHandler } from "./runtime/dispatcher.js";
-import { RUNTIME } from "./common/runtime.js";
+import { createStealPoolBuffers, MAX_STEAL_CONSUMERS, spawnWorkerContext, } from "./runtime/pool.js";
+import { ChannelHandler, hostDispatcherLoop } from "./runtime/dispatcher.js";
+import { createSharedArrayBuffer, RUNTIME } from "./common/runtime.js";
 import { RUNTIME_IS_MAIN_THREAD, RUNTIME_POOL_DEPTH, RUNTIME_WORKER_DATA, } from "./common/worker-runtime.js";
-import { resolvePermissionProtocol, toRuntimePermissionFlags, } from "./permission/index.js";
+import { classifyProcessPermissionCompatibility, enforceProcessPermissionCompatibility, resolvePermissionProtocol, toRuntimePermissionFlags, } from "./permission/index.js";
 import { getNodeProcess } from "./common/node-compat.js";
+import { readProcessWorkerNodeMajor, readProcessWorkerRuntime, } from "./runtime/process-worker.js";
+import { inspectCompiledWorkerArtifact } from "./runtime/compiled-artifact.js";
 import { managerMethod } from "./runtime/balancer.js";
 import { createInlineExecutor } from "./runtime/inline-executor.js";
 const hasDebugNamespace = (namespaces, namespace) => namespaces.has("*") || namespaces.has(namespace);
@@ -50,6 +52,21 @@ const MAX_FUNCTION_COUNT = MAX_FUNCTION_ID + 1;
 const DEFAULT_IMPORT_EXPORT_NAME = "default";
 export const isMain = RUNTIME_IS_MAIN_THREAD;
 export { endpointSymbol as endpointSymbol };
+/**
+ * Declare the task module's URL for runtimes without stack traces (e.g.
+ * Andromeda) that can't auto-discover the caller. Call once at module top
+ * level, before defining tasks:
+ *
+ * ```ts
+ * import { setModuleUrl, task } from "knitting";
+ * setModuleUrl(import.meta.url);
+ * export const add = task({ f: ([a, b]: [number, number]) => a + b });
+ * ```
+ *
+ * Runs in both host and worker (same module re-imported), so both agree on the
+ * path. No-op-safe on Node/Deno/Bun, where stack discovery already works.
+ */
+export { setModuleUrl as setModuleUrl };
 /**
  * Reconstructs stable task order from top-level exports before names are bound.
  */
@@ -80,25 +97,112 @@ const resolveImportHref = (href, callerHref) => {
         return toModuleUrl(href);
     }
 };
-const resolveWorkerBootstrapSettings = (worker, callerHref) => {
-    const bootstrap = worker?.bootstrap;
-    if (bootstrap === undefined)
-        return worker;
-    const name = bootstrap.name ?? DEFAULT_IMPORT_EXPORT_NAME;
-    if (typeof bootstrap.href !== "string" || bootstrap.href.length === 0) {
-        throw new TypeError("worker.bootstrap.href must be a non-empty string");
+const resolveWorkerSettings = (worker, callerHref) => {
+    if (worker === undefined)
+        return undefined;
+    const usingPorffor = worker.processRuntime === "porffor";
+    if (usingPorffor && worker.runtime !== undefined &&
+        worker.runtime !== "compiled") {
+        throw new Error('worker.processRuntime "porffor" requires worker.runtime to be compiled or omitted');
     }
-    if (typeof name !== "string" || name.length === 0) {
-        throw new TypeError("worker.bootstrap.name must be a non-empty string");
+    const forcePorfforBuild = usingPorffor && worker.runtime === undefined;
+    let resolved = usingPorffor
+        ? {
+            ...worker,
+            runtime: "compiled",
+            processRuntime: undefined,
+            compiled: forcePorfforBuild
+                ? { ...worker.compiled, build: "always" }
+                : worker.compiled,
+        }
+        : worker;
+    const bootstrap = resolved.bootstrap;
+    if (bootstrap !== undefined) {
+        const name = bootstrap.name ?? DEFAULT_IMPORT_EXPORT_NAME;
+        if (typeof bootstrap.href !== "string" || bootstrap.href.length === 0) {
+            throw new TypeError("worker.bootstrap.href must be a non-empty string");
+        }
+        if (typeof name !== "string" || name.length === 0) {
+            throw new TypeError("worker.bootstrap.name must be a non-empty string");
+        }
+        resolved = {
+            ...resolved,
+            bootstrap: {
+                ...bootstrap,
+                href: resolveImportHref(bootstrap.href, callerHref),
+                name,
+            },
+        };
     }
-    return {
-        ...worker,
-        bootstrap: {
-            ...bootstrap,
-            href: resolveImportHref(bootstrap.href, callerHref),
-            name,
-        },
+    const compiled = resolved.compiled;
+    if (compiled !== undefined) {
+        if (compiled.build !== undefined && typeof compiled.build !== "boolean" &&
+            compiled.build !== "always") {
+            throw new TypeError('worker.compiled.build must be a boolean or "always"');
+        }
+        for (const [name, value] of Object.entries({
+            artifact: compiled.artifact,
+            manifest: compiled.manifest,
+            compiler: compiled.compiler,
+        })) {
+            if (value !== undefined &&
+                (typeof value !== "string" || value.length === 0)) {
+                throw new TypeError("worker.compiled." + name + " must be a non-empty string");
+            }
+        }
+        resolved = {
+            ...resolved,
+            compiled: {
+                build: compiled.build,
+                compiler: compiled.compiler === undefined
+                    ? undefined
+                    : compiled.compiler.startsWith(".") ||
+                        compiled.compiler.startsWith("/") ||
+                        compiled.compiler.startsWith("file:") ||
+                        /^[A-Za-z]:[\\/]/.test(compiled.compiler)
+                        ? resolveImportHref(compiled.compiler, callerHref)
+                        : compiled.compiler,
+                artifact: compiled.artifact === undefined
+                    ? undefined
+                    : resolveImportHref(compiled.artifact, callerHref),
+                manifest: compiled.manifest === undefined
+                    ? undefined
+                    : resolveImportHref(compiled.manifest, callerHref),
+            },
+        };
+    }
+    return resolved;
+};
+/**
+ * Check whether a task module has a compatible prebuilt native worker.
+ *
+ * By default tasks.ts resolves to tasks.knt plus tasks.knt.json.
+ * This only inspects the artifact; it never executes it.
+ */
+export const checkCompiledWorker = (source, options) => {
+    const moduleSource = typeof source === "string" || source instanceof URL
+        ? source
+        : source?.importedFrom;
+    if (typeof moduleSource !== "string" && !(moduleSource instanceof URL)) {
+        throw new TypeError("checkCompiledWorker expects a task definition, module path, or URL");
+    }
+    const callerHref = getCallerHref(2);
+    const resolvedOptions = options === undefined ? undefined : {
+        build: options.build,
+        compiler: options.compiler,
+        artifact: options.artifact === undefined
+            ? undefined
+            : resolveImportHref(options.artifact, callerHref),
+        manifest: options.manifest === undefined
+            ? undefined
+            : resolveImportHref(options.manifest, callerHref),
     };
+    const inspection = inspectCompiledWorkerArtifact({
+        source: moduleSource,
+        options: resolvedOptions,
+    });
+    const { artifactHref: _artifactHref, manifestHref: _manifestHref, taskEntries: _taskEntries, ...result } = inspection;
+    return result;
 };
 const isTaskDefinition = (value) => value != null &&
     typeof value === "object" &&
@@ -206,7 +310,9 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             key === "--allow-fs-write" ||
             key === "--allow-worker" ||
             key === "--allow-child-process" ||
+            key === "--allow-net" ||
             key === "--allow-addons" ||
+            key === "--allow-ffi" ||
             key === "--allow-wasi";
     };
     const stripNodePermissionFlags = (flags) => flags?.filter((flag) => !isNodePermissionFlag(flag));
@@ -256,7 +362,72 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     hostDebug?.log(`modules=${formatDebugList(list)}`);
     hostDebug?.log(`permission=${permissionProtocol?.mode ?? "off"} execArgv=${formatDebugList(execArgv)}`);
     const usesAbortSignal = listOfFunctions.some((fn) => fn.abortSignal !== undefined);
-    const resolvedWorker = resolveWorkerBootstrapSettings(worker, callerHref);
+    const resolvedWorker = resolveWorkerSettings(worker, callerHref);
+    const dispatcherEnv = nodeProcess?.env?.KNITTING_DISPATCHER;
+    const stealEnvRaw = nodeProcess?.env?.KNITTING_STEAL?.trim().toLowerCase();
+    const stealEnv = stealEnvRaw === "1" || stealEnvRaw === "true"
+        ? true
+        : stealEnvRaw === "0" || stealEnvRaw === "false"
+            ? false
+            : undefined;
+    // Shared-submit stealing is the default for compatible multi-worker thread
+    // pools. An explicit option wins over the environment; process/compiled/
+    // inline transports retain their existing topology unless the caller
+    // explicitly requests an unsupported combination.
+    const dispatcherExplicitlySelected = host?.dispatcher !== undefined ||
+        dispatcherEnv === "serial-channel" || dispatcherEnv === "per-thread";
+    const stealDefaultCompatible = balancer === undefined &&
+        !dispatcherExplicitlySelected && (threads ?? 1) <= MAX_STEAL_CONSUMERS;
+    const stealRequested = host?.steal ?? stealEnv ?? stealDefaultCompatible;
+    const stealExplicitlyEnabled = host?.steal === true ||
+        (host?.steal === undefined && stealEnv === true);
+    const usingCompiledWorker = resolvedWorker?.runtime === "compiled";
+    if (resolvedWorker?.compiled !== undefined && !usingCompiledWorker) {
+        throw new Error("worker.compiled requires worker.runtime to be compiled");
+    }
+    if (usingCompiledWorker) {
+        const unsupported = [];
+        if (usingInliner)
+            unsupported.push("inliner");
+        if (payload !== undefined)
+            unsupported.push("payload");
+        if (unsafe !== undefined)
+            unsupported.push("unsafe");
+        if (source !== undefined)
+            unsupported.push("source");
+        if (workerExecArgv !== undefined)
+            unsupported.push("workerExecArgv");
+        if (permission !== undefined)
+            unsupported.push("permission");
+        if (host !== undefined)
+            unsupported.push("host");
+        if (resolvedWorker.bootstrap !== undefined) {
+            unsupported.push("worker.bootstrap");
+        }
+        if (resolvedWorker.timers !== undefined)
+            unsupported.push("worker.timers");
+        if (resolvedWorker.processRuntime !== undefined) {
+            unsupported.push("worker.processRuntime");
+        }
+        if (resolvedWorker.processCommandPrefix !== undefined) {
+            unsupported.push("worker.processCommandPrefix");
+        }
+        if (resolvedWorker.processSharedMemory !== undefined) {
+            unsupported.push("worker.processSharedMemory");
+        }
+        if (resolvedWorker.resolveAfterFinishingAll !== undefined) {
+            unsupported.push("worker.resolveAfterFinishingAll");
+        }
+        if (listOfFunctions.some((fn) => fn.timeout !== undefined)) {
+            unsupported.push("task timeout");
+        }
+        if (listOfFunctions.some((fn) => fn.imported === true)) {
+            unsupported.push("importTask");
+        }
+        if (unsupported.length > 0) {
+            throw new Error("Compiled workers do not support: " + unsupported.join(", "));
+        }
+    }
     if (resolvedWorker?.bootstrap !== undefined) {
         hostDebug?.log(`bootstrap href=${resolvedWorker.bootstrap.href}` +
             ` name=${resolvedWorker.bootstrap.name}`);
@@ -264,6 +435,22 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
     if (usingInliner && resolvedWorker?.bootstrap !== undefined) {
         throw new Error("worker.bootstrap cannot be used with the inliner");
     }
+    if (stealExplicitlyEnabled && resolvedWorker?.runtime === "process") {
+        throw new Error("host.steal does not support process workers; use worker threads or disable stealing");
+    }
+    if (resolvedWorker?.runtime === "process") {
+        const processRuntime = readProcessWorkerRuntime(resolvedWorker);
+        enforceProcessPermissionCompatibility(classifyProcessPermissionCompatibility({
+            permission,
+            resolved: permissionProtocol,
+            target: {
+                runtime: processRuntime,
+                nodeMajor: processRuntime === "node"
+                    ? readProcessWorkerNodeMajor(resolvedWorker)
+                    : undefined,
+            },
+        }));
+    }
     const hardTimeoutMs = Number.isFinite(resolvedWorker?.hardTimeoutMs)
         ? Math.max(1, Math.floor(resolvedWorker?.hardTimeoutMs))
         : undefined;
@@ -276,7 +463,6 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             `(import { isMain } from "knitting") so only the main program starts ` +
             `the pool.`);
     }
-    const dispatcherEnv = nodeProcess?.env?.KNITTING_DISPATCHER;
     const explicitDispatcher = host?.dispatcher ??
         (dispatcherEnv === "serial-channel" || dispatcherEnv === "per-thread"
             ? dispatcherEnv
@@ -292,7 +478,26 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         return "serial-channel";
     })();
     const dispatcher = explicitDispatcher ?? autoDispatcher;
-    const serialChannel = dispatcher === "serial-channel";
+    // Work stealing: one shared submit region, private return lanes, one
+    // pool-global pending registry. It is the compatible multi-thread default;
+    // an explicit balancer/dispatcher keeps the private-lane topology unless
+    // stealing itself was explicitly requested.
+    const useSteal = stealRequested &&
+        !usingCompiledWorker &&
+        resolvedWorker?.runtime !== "process" &&
+        (threads ?? 1) > 1 &&
+        !usingInliner;
+    const stealBuffers = useSteal
+        ? createStealPoolBuffers({
+            threads: threads ?? 1,
+            payload,
+            regionLanes: host?.stealRegionLanes,
+            abortSignalCapacity,
+            usesAbortSignal,
+        })
+        : undefined;
+    const serialChannel = !usingCompiledWorker && !useSteal &&
+        dispatcher === "serial-channel";
     const serialDispatcherChannel = serialChannel
         ? new ChannelHandler()
         : undefined;
@@ -317,14 +522,83 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         usesAbortSignal,
         permission: permissionProtocol,
         sharedChannelHandler: serialDispatcherChannel,
+        stealPool: stealBuffers === undefined ? undefined : {
+            submitBuffers: stealBuffers.submitBuffers,
+            returnBuffers: stealBuffers.returnBuffers[thread],
+            hostSubmitLock: stealBuffers.hostSubmitLock,
+            hostReturnLock: stealBuffers.hostReturnLocks[thread],
+            sharedQueue: stealBuffers.sharedQueue,
+            consumers: threads ?? 1,
+            consumerId: thread,
+            regionLanes: stealBuffers.regionLanes,
+            abortSignalSAB: stealBuffers.abortSignalSAB,
+            abortSignalMax: stealBuffers.abortSignalMax,
+        },
     }));
+    const stealChannel = useSteal ? new ChannelHandler() : undefined;
+    if (useSteal) {
+        const channel = stealChannel;
+        const queue = stealBuffers.sharedQueue;
+        // Wake exactly one worker per drain, round-robin. Stealing decouples the
+        // wake target from the assignment: if the woken worker is busy, any other
+        // idle endpoint claims the region instead. So this costs one notify per
+        // publish regardless of pool size, rather than one per lane.
+        let wakeCursor = 0;
+        const wakeOne = () => {
+            const lanes = workers.length;
+            if (lanes === 0)
+                return;
+            const lane = wakeCursor;
+            wakeCursor = wakeCursor + 1 < lanes ? wakeCursor + 1 : 0;
+            workers[lane].laneWake?.();
+        };
+        // The shared dispatcher drives one queue, so it needs signal words of its
+        // own rather than any single lane's; waking is delegated to `wakeOne`.
+        const signalWords = new Int32Array(createSharedArrayBuffer(3 * Int32Array.BYTES_PER_ELEMENT));
+        const { check } = hostDispatcherLoop({
+            signalBox: {
+                opView: signalWords.subarray(0, 1),
+                txStatus: signalWords.subarray(1, 2),
+                rxStatus: signalWords.subarray(2, 3),
+            },
+            queue,
+            channelHandler: channel,
+            dispatcherOptions: host,
+            notifySignal: wakeOne,
+        });
+        channel.open(check);
+        workers.forEach((context) => {
+            context.bindSend(() => {
+                if (check.isRunning !== true) {
+                    check.isRunning = true;
+                    Promise.resolve().then(check);
+                }
+                wakeOne();
+            });
+        });
+        hostDebug?.log(`dispatcher=steal lanes=${workers.length} g=${stealBuffers.regionLanes}`);
+    }
     const sharedDispatcherChannel = serialDispatcherChannel;
     if (serialChannel) {
         const channel = serialDispatcherChannel;
         const checks = workers.map((context) => context.dispatcherCheck);
+        const laneIdle = workers.map((context) => context.txIdle);
         let serialScheduled = false;
         let serialInFlight = false;
         let serialRerun = false;
+        // Busy-lane set: a tick walks only the lanes that have work, not all of
+        // them. `active` is a dense list of lane indices; `isActive` keeps the
+        // membership test O(1). A lane joins on send() and leaves once its queue
+        // reports idle, so an N-worker pool with one busy lane costs one check per
+        // tick instead of N.
+        const active = [];
+        const isActive = new Uint8Array(checks.length);
+        const markActive = (lane) => {
+            if (isActive[lane] === 1)
+                return;
+            isActive[lane] = 1;
+            active.push(lane);
+        };
         const runSerialChecks = () => {
             if (serialInFlight) {
                 serialRerun = true;
@@ -334,11 +608,19 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             do {
                 serialRerun = false;
                 serialScheduled = false;
-                for (let index = 0; index < checks.length; index++) {
-                    const check = checks[index];
+                // Walk backwards so dropping an idle lane is a swap-with-last pop.
+                for (let index = active.length - 1; index >= 0; index--) {
+                    const lane = active[index];
+                    const check = checks[lane];
                     if (check.isRunning !== true)
                         check.isRunning = true;
                     check();
+                    if (laneIdle[lane]()) {
+                        isActive[lane] = 0;
+                        const last = active.pop();
+                        if (index < active.length)
+                            active[index] = last;
+                    }
                 }
             } while (serialRerun);
             serialInFlight = false;
@@ -354,9 +636,10 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
             Promise.resolve().then(runSerialChecks);
         };
         channel.open(runSerialChecks);
-        workers.forEach((context) => {
+        workers.forEach((context, lane) => {
             const wake = context.laneWake;
             context.bindSend(() => {
+                markActive(lane);
                 scheduleSerialCheck();
                 wake();
             });
@@ -401,6 +684,7 @@ export const createPool = ({ threads, debug, inliner, balancer, payload, unsafe,
         closePromise = Promise.allSettled(workers.map((context) => context.kills()))
             .then(() => {
             sharedDispatcherChannel?.close();
+            stealChannel?.close();
         });
         return closePromise;
     };

package/src/common/module-url.d.ts

@@ -1 +1,2 @@
 export declare const toModuleUrl: (specifier: string) => string;
+export declare const toImportSpecifier: (moduleUrl: string) => string;

package/src/common/module-url.js

@@ -1,9 +1,18 @@
-import { pathToFileURL } from "node:url";
+import { getNodeBuiltinModule } from "./node-compat.js";
+import { IS_ANDROMEDA } from "./runtime.js";
 const WINDOWS_DRIVE_PATH = /^[A-Za-z]:[\\/]/;
 const WINDOWS_UNC_PATH = /^\\\\[^\\/?]+\\[^\\/?]+/;
 const encodeFilePath = (path) => encodeURI(path)
     .replace(/\?/g, "%3F")
     .replace(/#/g, "%23");
+// `node:url` resolved lazily (absent on Andromeda); fall back to a pure
+// path->file-URL conversion when it is missing.
+const nodePathToFileURL = () => getNodeBuiltinModule("node:url")
+    ?.pathToFileURL;
+const pathToFileUrlFallback = (specifier) => {
+    const absolute = specifier.startsWith("/") ? specifier : `/${specifier}`;
+    return `file://${encodeFilePath(absolute)}`;
+};
 export const toModuleUrl = (specifier) => {
     if (WINDOWS_DRIVE_PATH.test(specifier)) {
         const normalized = specifier.replace(/\\/g, "/");
@@ -19,6 +28,25 @@ export const toModuleUrl = (specifier) => {
         return new URL(specifier).href;
     }
     catch {
-        return pathToFileURL(specifier).href;
+        const pathToFileURL = nodePathToFileURL();
+        return pathToFileURL
+            ? pathToFileURL(specifier).href
+            : pathToFileUrlFallback(specifier);
+    }
+};
+// Andromeda's loader treats `file://` import specifiers as relative paths;
+// convert back to a plain filesystem path there. No-op elsewhere.
+export const toImportSpecifier = (moduleUrl) => {
+    if (!IS_ANDROMEDA || !moduleUrl.startsWith("file://"))
+        return moduleUrl;
+    const withoutScheme = moduleUrl.slice("file://".length);
+    const path = withoutScheme.startsWith("/")
+        ? withoutScheme
+        : `/${withoutScheme}`;
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return path;
     }
 };

package/src/common/node-compat.d.ts

@@ -1,8 +1,10 @@
 export type NodeProcessLike = {
     getBuiltinModule?: (id: string) => unknown;
     versions?: {
+        modules?: string;
         node?: string;
     };
+    pid?: number;
     platform?: string;
     allowedNodeEnvironmentFlags?: ReadonlySet<string>;
     execArgv?: string[];

package/src/common/path-canonical.js

@@ -1,9 +1,23 @@
-import { existsSync, realpathSync, } from "node:fs";
-import { basename as pathBasename, dirname as pathDirname, join as pathJoin, resolve as pathResolve, } from "node:path";
-export const toCanonicalPath = (candidate, fsApi = {
-    existsSync,
-    realpathSync: realpathSync.native ?? realpathSync,
-}) => {
+import { getNodeBuiltinModule } from "./node-compat.js";
+const nodeFs = () => getNodeBuiltinModule("node:fs");
+const nodePath = () => {
+    const module = getNodeBuiltinModule("node:path");
+    if (module === undefined) {
+        throw new Error("node:path is not available in this runtime");
+    }
+    return module;
+};
+const defaultFsApi = () => {
+    const fs = nodeFs();
+    if (fs === undefined)
+        return {};
+    return {
+        existsSync: fs.existsSync,
+        realpathSync: fs.realpathSync.native ?? fs.realpathSync,
+    };
+};
+export const toCanonicalPath = (candidate, fsApi = defaultFsApi()) => {
+    const { basename: pathBasename, dirname: pathDirname, join: pathJoin, resolve: pathResolve, } = nodePath();
     const absolute = pathResolve(candidate);
     const { existsSync, realpathSync } = fsApi;
     if (typeof realpathSync === "function") {

package/src/common/runtime.d.ts

@@ -1,7 +1,9 @@
-type RuntimeName = "deno" | "bun" | "node" | "unknown";
+type RuntimeName = "deno" | "bun" | "node" | "andromeda" | "browser" | "unknown";
 export declare const IS_DENO: boolean;
 export declare const IS_BUN: boolean;
 export declare const IS_NODE: boolean;
+export declare const IS_ANDROMEDA: boolean;
+export declare const IS_BROWSER: boolean;
 export declare const RUNTIME: RuntimeName;
 export declare const SET_IMMEDIATE: typeof setImmediate & ((cb: () => void) => void);
 export declare const HAS_SHARED_WASM_MEMORY: boolean;

package/src/common/runtime.js

@@ -4,16 +4,37 @@ const nodeProcess = getNodeProcess();
 export const IS_DENO = typeof globals.Deno?.version?.deno === "string";
 export const IS_BUN = typeof globals.Bun?.version === "string";
 export const IS_NODE = typeof nodeProcess?.versions?.node === "string";
-export const RUNTIME = (IS_DENO ? "deno" : IS_BUN ? "bun" : IS_NODE ? "node" : "unknown");
+// Andromeda (Nova engine): no `node:` builtins or `WebAssembly`; detect via
+// its private bootstrap global.
+export const IS_ANDROMEDA = typeof globals.__andromeda__ !== "undefined";
+// A page or a web worker: no `node:` builtins, but `Worker`, `MessageChannel`,
+// and a cross-origin isolated `SharedArrayBuffer` are all the pool needs.
+export const IS_BROWSER = !IS_DENO && !IS_BUN && !IS_NODE && !IS_ANDROMEDA &&
+    (typeof globals.document !== "undefined" ||
+        typeof globals.WorkerGlobalScope === "function");
+export const RUNTIME = (IS_DENO
+    ? "deno"
+    : IS_BUN
+        ? "bun"
+        : IS_NODE
+            ? "node"
+            : IS_ANDROMEDA
+                ? "andromeda"
+                : IS_BROWSER
+                    ? "browser"
+                    : "unknown");
+// `WebAssembly` may be undeclared (not just undefined) on Andromeda, where a
+// bare reference throws; capture it through `globalThis` so access is safe.
+const WebAssemblyRef = globals.WebAssembly;
 export const SET_IMMEDIATE = typeof globals.setImmediate === "function" ? globals.setImmediate : undefined;
 const WASM_MEMORY_PAGE_BYTES = 64 * 1024;
 const wasmSharedBufferMemory = new WeakMap();
 const wasmSharedBufferMaxByteLength = new WeakMap();
 const hasSharedWasmMemory = (() => {
-    if (typeof WebAssembly?.Memory !== "function")
+    if (typeof WebAssemblyRef?.Memory !== "function")
         return false;
     try {
-        void new WebAssembly.Memory({ initial: 0, maximum: 1, shared: true });
+        void new WebAssemblyRef.Memory({ initial: 0, maximum: 1, shared: true });
         return true;
     }
     catch {
@@ -23,7 +44,7 @@ const hasSharedWasmMemory = (() => {
 export const HAS_SHARED_WASM_MEMORY = hasSharedWasmMemory;
 const roundupWasmPages = (byteLength) => Math.ceil(Math.max(0, byteLength) / WASM_MEMORY_PAGE_BYTES);
 const createSharedWasmBuffer = (byteLength, maxByteLength) => {
-    const memory = new WebAssembly.Memory({
+    const memory = new WebAssemblyRef.Memory({
         initial: roundupWasmPages(byteLength),
         maximum: Math.max(roundupWasmPages(byteLength), roundupWasmPages(maxByteLength)),
         shared: true,

package/src/common/task-source.d.ts

@@ -1,3 +1,5 @@
 export declare const genTaskID: () => number;
+export declare const setModuleUrl: (url: string | undefined) => void;
+export declare const getModuleUrlOverride: () => string | undefined;
 export declare const getCallerHref: (offset?: number) => string;
 export declare const getCallerFilePath: (offset?: number) => [string, number];

package/src/common/task-source.js

@@ -61,7 +61,21 @@ const collectStackFrames = () => {
 const isInternalFrame = (frame) => isRuntimeInternalFrame(frame.file) ||
     isInternalCallerFrame(frame.file) ||
     isInternalCallerFunction(frame.functionName, frame.methodName);
+// Module-URL override for runtimes without stack traces (e.g. Andromeda, where
+// `new Error().stack` is undefined). When set, caller discovery skips stack
+// inspection and attributes every task here. Set via
+// `setModuleUrl(import.meta.url)`, which runs in both host and worker copies so
+// both agree on the path.
+let moduleUrlOverride;
+export const setModuleUrl = (url) => {
+    moduleUrlOverride = typeof url === "string" && url.length > 0
+        ? toModuleUrl(url)
+        : undefined;
+};
+export const getModuleUrlOverride = () => moduleUrlOverride;
 const resolveCallerHref = (offset) => {
+    if (moduleUrlOverride !== undefined)
+        return moduleUrlOverride;
     const frames = collectStackFrames();
     const direct = frames[offset];
     const caller = (direct && !isInternalFrame(direct)
@@ -70,7 +84,9 @@ const resolveCallerHref = (offset) => {
         frames.find((frame) => !isInternalFrame(frame))?.file ??
         frames.find((frame) => !isRuntimeInternalFrame(frame.file))?.file;
     if (!caller) {
-        throw new Error("Unable to determine caller file.");
+        throw new Error("Unable to determine caller file. This runtime exposes no stack traces " +
+            "(e.g. Andromeda); call setModuleUrl(import.meta.url) at the top of " +
+            "the module that defines your tasks before creating a pool.");
     }
     return toModuleUrl(caller);
 };