@telorun/kernel 0.9.1 → 0.10.0

package/dist/controller-loaders/npm-loader.js

@@ -1,261 +1,809 @@
 import { execFile } from "child_process";
-import { createHash } from "crypto";
+import * as crypto from "crypto";
 import * as fs from "fs/promises";
+import { createRequire } from "module";
 import * as os from "os";
 import { PackageURL } from "packageurl-js";
 import * as path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
 import { promisify } from "util";
-const homedir = os.homedir();
-const cacheRoot = process.env.TELO_CACHE_DIR
-    ? path.resolve(process.env.TELO_CACHE_DIR)
-    : path.join(homedir, ".cache", "telo");
-const npmCacheRoot = path.join(cacheRoot, "npm");
-const isBun = typeof globalThis.Bun !== "undefined";
+import { ControllerEnvMissingError } from "./napi-loader.js";
+const execFileAsync = promisify(execFile);
+const requireFromHere = createRequire(import.meta.url);
+/**
+ * Package-manager binary used for `<root>/.telo/npm/` installs. Captured once
+ * at module load so a mid-process env mutation can't change which binary
+ * runs for half an install batch — the kernel's controller installs are
+ * sequenced, but predictability beats late-binding here. Override via
+ * `TELO_PKG_MANAGER` (e.g. `pnpm`, `bun`).
+ */
+const PACKAGE_MANAGER = process.env.TELO_PKG_MANAGER ?? "npm";
+/**
+ * Maximum age before a held lock is considered abandoned. `npm install` on a
+ * cold cache for a tree with one or two controllers is comfortably under a
+ * minute on modern hardware; tuning higher would let zombie locks persist.
+ */
+const LOCK_STALE_MS = 60000;
+/**
+ * Total wall-clock cap for waiting on the install lock — enough for a slow
+ * first install on a peer process to finish, short enough that a deadlocked
+ * CI job fails loudly rather than hanging for hours. The retry interval
+ * trades wakeup latency vs. wasted polls; 500ms is well below the lock
+ * holder's typical hold time.
+ */
+const LOCK_WAIT_MAX_MS = 5 * 60000;
+const LOCK_RETRY_MS = 500;
+/**
+ * The npm-loader maintains a single install root per kernel process at
+ * `<entry-manifest-dir>/.telo/npm/`. Every controller — registry tag or
+ * `local_path` — is installed via `npm install <spec>` into this root, then
+ * imported from `<root>/node_modules/<pkg>`. This collapses two parallel
+ * module realms (kernel-side @telorun/sdk vs. controller-side @telorun/sdk)
+ * into one: the kernel's own SDK is wired in as a `file:` dep, npm/pnpm
+ * symlink it, and Node's ESM resolver follows the symlink to the same
+ * realpath as the kernel — so `Stream` (and any other class-identity-sensitive
+ * type) has a single constructor across the process.
+ *
+ * Per-kernel state lives on each `NpmControllerLoader` instance (one is
+ * constructed per `ControllerLoader`, which is itself constructed per
+ * `Telo.Definition.init`). The instance caches the install-root materialization
+ * promise (`rootReady`), the set of installed specs (`installedSpecs`), an
+ * in-flight install map for single-flight dedupe (`inFlight`), and a snapshot
+ * of the install root's `dependencies` map (`rootDeps`) so per-controller
+ * fast paths can hit without re-reading `package.json`. Cross-kernel and
+ * cross-process safety is provided by a filesystem lock on `<root>/.lock`.
+ */
 export class NpmControllerLoader {
+    constructor(options = {}) {
+        /**
+         * Per-process cache of "this controller's package + version is already
+         * installed in the root and matches our spec" so concurrent loads of the
+         * same definition skip the lock + re-check round-trip after the first
+         * caller wins. Keyed by absolute spec (e.g. `@telorun/sdk@file:/abs/path`
+         * or `@scope/pkg@^1.2.3`).
+         */
+        this.installedSpecs = new Set();
+        /**
+         * In-flight installs keyed by canonical spec. Two callers racing for the
+         * same spec share one `npm install <spec>` invocation rather than each
+         * acquiring the fs-lock and reinstalling.
+         */
+        this.inFlight = new Map();
+        /**
+         * Snapshot of the install root's `dependencies` map at the time of last
+         * read. Set during `materializeInstallRoot()` and refreshed when an
+         * install adds a new spec. Lets the per-controller fast path decide on
+         * "already installed?" without re-reading and re-parsing `package.json`
+         * for every load — a single test typically touches 5–10 controllers,
+         * and a test suite spawns one Kernel per fixture, so the multiplier is
+         * `tests * controllers` file reads otherwise.
+         */
+        this.rootDeps = {};
+        this.entryUrl = options.entryUrl;
+    }
+    async load(purl, baseUri) {
+        const parsed = PackageURL.fromString(purl);
+        if (!parsed.name) {
+            throw new Error(`Invalid PURL '${purl}': missing package name`);
+        }
+        const packageName = parsed.namespace ? `${parsed.namespace}/${parsed.name}` : parsed.name;
+        const installRoot = await this.ensureInstallRoot();
+        const resolved = await resolveInstallSpec(parsed, packageName, baseUri);
+        const source = await this.installPackage(installRoot, packageName, resolved.spec, resolved.kind);
+        const instance = await loadFromInstall(installRoot, packageName, parsed.subpath ?? null, purl);
+        return { instance, source };
+    }
     /**
-     * Resolve a `pkg:npm/...` PURL to a controller module instance. Tries, in order:
-     * a relative `local_path` qualifier, the workspace's `node_modules`, and finally
-     * an isolated install under `~/.cache/telo/npm/<hash>`.
+     * Compute the install root from the entry URL, write a baseline package.json
+     * pinning the kernel's own runtime deps as `file:` references, run a single
+     * `npm install` once, and return the absolute root path. Memoized for the
+     * lifetime of this loader instance.
      */
-    async load(purl, baseUri) {
-        const [, namespace, name, versionSpec, qualifiers, entry] = PackageURL.parseString(purl);
-        const localPath = qualifiers?.get("local_path");
-        const cacheKey = createHash("sha256").update(purl).digest("hex").slice(0, 12);
-        const installDir = path.join(npmCacheRoot, cacheKey);
-        let packageRoot;
-        let source;
-        const isLocalManifest = baseUri && !baseUri.startsWith("http://") && !baseUri.startsWith("https://");
-        if (localPath && isLocalManifest) {
-            const baseUriPath = baseUri.startsWith("file://") ? baseUri.slice("file://".length) : baseUri;
-            const manifestDir = path.dirname(baseUriPath);
-            const resolvedLocalPath = path.resolve(manifestDir, localPath);
-            if (await this.pathExists(resolvedLocalPath)) {
-                packageRoot = resolvedLocalPath;
-                source = "local";
-            }
-            else {
-                const nodeModulesPath = await this.findInNodeModules(`${namespace}/${name}`);
-                if (nodeModulesPath) {
-                    packageRoot = nodeModulesPath;
-                    source = "node_modules";
-                }
-                else {
-                    source = await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
-                    packageRoot = this.getInstalledPackageRoot(installDir, `${namespace}/${name}`);
-                }
-            }
+    ensureInstallRoot() {
+        if (this.rootReady)
+            return this.rootReady;
+        this.rootReady = this.materializeInstallRoot().catch((err) => {
+            // Reset on failure so a follow-up call retries rather than caches the rejection.
+            this.rootReady = undefined;
+            throw err;
+        });
+        return this.rootReady;
+    }
+    async materializeInstallRoot() {
+        if (!this.entryUrl) {
+            // Throw the env-missing variant so a mixed candidate list (e.g.
+            // `pkg:npm/... + pkg:cargo/...`) still falls back to the next
+            // candidate. A plain Error would abort the whole resolve chain;
+            // callers that intentionally drive the napi loader without supplying
+            // an entry URL would otherwise see a hard failure.
+            throw new ControllerEnvMissingError("NpmControllerLoader requires an entryUrl. Pass one to the constructor (kernel: " +
+                "Kernel.load() records this; CLI: pass the manifest path).");
         }
-        else {
-            const nodeModulesPath = await this.findInNodeModules(`${namespace}/${name}`);
-            if (nodeModulesPath) {
-                packageRoot = nodeModulesPath;
-                source = "node_modules";
-            }
-            else {
-                source = await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
-                packageRoot = this.getInstalledPackageRoot(installDir, `${namespace}/${name}`);
+        const entryUrlStr = this.entryUrl;
+        // The install root is anchored next to the entry manifest on disk. For an
+        // http(s):// entry URL there is no such anchor — `path.resolve` would
+        // silently turn `http://host/x.yaml` into something like
+        // `<cwd>/http:/host/x.yaml`, materializing a `.telo/npm` tree in an
+        // unrelated directory. Reject the case loudly until we ship an explicit
+        // strategy (e.g. a hash-keyed cache under `~/.cache/telo`) for HTTP-sourced
+        // manifests; today nothing in the workspace exercises this path.
+        const entryPath = parseFileUrlOrThrow(entryUrlStr);
+        const entryDir = path.dirname(path.resolve(entryPath));
+        const installRoot = path.join(entryDir, ".telo", "npm");
+        // Build the install-root package.json: kernel-runtime deps as `file:` refs,
+        // `overrides` + `pnpm.overrides` pinning every name to `$<name>`. This is
+        // the realm-collapse mechanism — npm's `file:` symlinks the kernel's own
+        // package locations, the resolver follows symlinks to the realpath, and
+        // every controller transitively resolving these names lands on the
+        // identical module instance the kernel itself is using.
+        const runtimeDeps = await loadRuntimeDeps();
+        const dependencies = {};
+        const overrides = {};
+        for (const name of runtimeDeps) {
+            const resolvedPkgRoot = await resolveKernelPackageRoot(name);
+            if (!resolvedPkgRoot) {
+                // A kernel runtime dep that can't be resolved at boot is unusual but
+                // not fatal — the realm-collapse story degrades to "rely on registry
+                // resolution + overrides" for that name. Don't crash the loader.
+                continue;
             }
+            dependencies[name] = `file:${resolvedPkgRoot}`;
+            overrides[name] = `$${name}`;
         }
-        const entryFile = await this.resolvePackageEntry(packageRoot, entry ? `./${entry}` : ".");
-        const instance = await import(entryFile);
-        if (!instance || (!instance.create && !instance.register)) {
-            throw new Error(`Invalid controller loaded from "${purl}": missing create or register function`);
+        const packageJson = {
+            name: "telo-runtime-install",
+            private: true,
+            version: "0.0.0",
+            dependencies,
+            overrides,
+            pnpm: { overrides },
+        };
+        const packageJsonPath = path.join(installRoot, "package.json");
+        const stateFile = path.join(installRoot, ".telo-state.json");
+        const newHash = sha256(JSON.stringify(packageJson));
+        await fs.mkdir(installRoot, { recursive: true });
+        // Lock-free fast path: if the on-disk state matches what we'd write,
+        // there's nothing to install and nothing to serialize. Every fresh
+        // Kernel re-enters this code path (e.g. test suites that spawn one
+        // Kernel per test), so paying even an `fs.open(.lock, 'wx')` here per
+        // test is measurable. Reads-only checks are safe without the lock —
+        // the writer side updates package.json + .telo-state.json + node_modules
+        // under a held lock, so any read that observes a matching hash plus
+        // an existing node_modules has observed a fully materialized tree.
+        if ((await readJsonField(stateFile, "rootHash")) === newHash &&
+            (await pathExists(path.join(installRoot, "node_modules")))) {
+            // Lock-free fast path: nothing to do beyond seeding the in-process caches.
+            await this.seedDepCaches(installRoot, dependencies);
+            return installRoot;
         }
-        return { instance, source };
+        await withInstallLock(installRoot, async () => {
+            // Re-check inside the lock: a peer may have completed the install
+            // between the fast-path miss and our acquisition.
+            const existingHash = await readJsonField(stateFile, "rootHash");
+            if (existingHash === newHash && (await pathExists(path.join(installRoot, "node_modules")))) {
+                return;
+            }
+            await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+            await runPackageManager(installRoot, ["install", "--no-audit", "--no-fund", "--silent"]);
+            await fs.writeFile(stateFile, JSON.stringify({ rootHash: newHash }, null, 2) + "\n");
+        });
+        await this.seedDepCaches(installRoot, dependencies);
+        return installRoot;
     }
-    async ensureNpmPackageInstalled(installDir, packageSpec) {
-        const packageName = this.getPackageName(packageSpec.startsWith(".") || path.isAbsolute(packageSpec)
-            ? await this.getLocalPackageName(packageSpec)
-            : packageSpec);
-        const packageRoot = this.getInstalledPackageRoot(installDir, packageName);
-        const packageJsonPath = path.join(packageRoot, "package.json");
-        if (await this.pathExists(packageJsonPath)) {
+    /**
+     * Populate the in-process caches that drive the per-controller fast path:
+     * `installedSpecs` (so duplicate calls from the same Kernel return immediately)
+     * and `rootDeps` (so the fast path doesn't re-read `package.json` per load).
+     * `dependencies` is the freshly-built map we know is on disk; it's used as a
+     * fallback when the actual file-read fails (e.g. immediately after a hot
+     * reload where the writer is still racing).
+     */
+    async seedDepCaches(installRoot, dependencies) {
+        for (const [name, spec] of Object.entries(dependencies)) {
+            this.installedSpecs.add(`${name}@${spec}`);
+        }
+        this.rootDeps = (await readPackageDeps(installRoot)) ?? { ...dependencies };
+    }
+    /**
+     * Install one controller spec into the existing root. Single-flight per
+     * spec within the process; cross-process safety is the fs-lock around the
+     * `npm install` call. If the spec is already present in the manifest's
+     * package.json (under `dependencies`), skip — reusing the previous install.
+     *
+     * `kind` distinguishes a `local_path` source (loader synthesized `file:`
+     * spec) from a registry tag. The CLI silences progress for both `cache`
+     * and `local`; `npm-install` is the only event surfaced. Folding this
+     * decision in here means the caller no longer needs to override the
+     * returned source after the fact.
+     */
+    async installPackage(installRoot, packageName, spec, kind) {
+        const cacheKey = `${packageName}@${spec}`;
+        if (this.installedSpecs.has(cacheKey))
+            return "cache";
+        const inFlight = this.inFlight.get(cacheKey);
+        if (inFlight) {
+            await inFlight;
+            return "cache";
+        }
+        // Lock-free fast path: consult the in-process snapshot of the install
+        // root's `dependencies` map (seeded by `materializeInstallRoot`). If the
+        // spec matches what's already wired in and the package directory exists,
+        // there's nothing to do — no lock, no fork, no per-load file read. This
+        // is the dominant case for warm test suites: every Kernel touches the
+        // same controllers and a fresh-on-disk read per (Kernel × controller)
+        // dominates wall time even when the actual installs are already done.
+        //
+        // Normalize specs before comparing because npm rewrites absolute `file:`
+        // deps to relative paths inside the install root's `package.json`. The
+        // loader passes absolute paths (resolved against the declaring library's
+        // baseUri); the on-disk record is `file:../../foo`. Without normalization
+        // every fast-path read is a string-mismatch and the loader would fall
+        // through to a real `npm install` per controller per Kernel — turning a
+        // 1ms hit into a 150–200ms one.
+        const targetPath = path.join(installRoot, "node_modules", ...packageName.split("/"));
+        const cachedSpec = this.rootDeps[packageName];
+        if (cachedSpec !== undefined &&
+            normalizeFileSpec(cachedSpec, installRoot) === normalizeFileSpec(spec, installRoot) &&
+            (await pathExists(targetPath))) {
+            this.installedSpecs.add(cacheKey);
             return "cache";
         }
-        await fs.mkdir(installDir, { recursive: true });
-        const rootPackageJson = path.join(installDir, "package.json");
-        if (!(await this.pathExists(rootPackageJson))) {
-            await fs.writeFile(rootPackageJson, JSON.stringify({ name: "telo-cache", private: true }, null, 2));
+        const work = (async () => {
+            await withInstallLock(installRoot, async () => {
+                // Re-check inside the lock: a peer process may have installed the
+                // spec between the fast-path miss and our acquisition. Normalize
+                // the on-disk record to absolute form before comparing — npm
+                // rewrites `file:` deps to be relative to the install root.
+                const lockedSpec = await readDepSpec(installRoot, packageName);
+                if (lockedSpec !== undefined &&
+                    normalizeFileSpec(lockedSpec, installRoot) === normalizeFileSpec(spec, installRoot) &&
+                    (await pathExists(targetPath))) {
+                    this.rootDeps[packageName] = lockedSpec;
+                    return;
+                }
+                await runPackageManager(installRoot, [
+                    "install",
+                    "--no-audit",
+                    "--no-fund",
+                    "--silent",
+                    "--save",
+                    spec,
+                ]);
+                // Re-read what npm actually wrote (it normalizes `file:` paths to
+                // be relative to the install root). Caching the spec in its on-disk
+                // form keeps subsequent fast-path comparisons stable.
+                const written = await readDepSpec(installRoot, packageName);
+                if (written !== undefined)
+                    this.rootDeps[packageName] = written;
+                else
+                    this.rootDeps[packageName] = spec;
+            });
+        })();
+        this.inFlight.set(cacheKey, work);
+        try {
+            await work;
         }
-        const execFileAsync = promisify(execFile);
-        const args = [
-            "install",
-            "--no-audit",
-            "--no-fund",
-            "--silent",
-            "--prefix",
-            installDir,
-            packageSpec,
-        ];
-        await execFileAsync("npm", args);
-        return "npm-install";
-    }
-    getPackageName(packageSpec) {
-        if (packageSpec.startsWith("@")) {
-            const lastAt = packageSpec.lastIndexOf("@");
-            return lastAt > 0 ? packageSpec.slice(0, lastAt) : packageSpec;
+        finally {
+            this.inFlight.delete(cacheKey);
         }
-        const [name] = packageSpec.split("@");
-        return name;
+        this.installedSpecs.add(cacheKey);
+        // First-touch local installs report `local` (silenced in CLI progress);
+        // fresh registry installs report `npm-install` (the only branch a
+        // user-facing "downloading…" line should ever surface for).
+        return kind === "local" ? "local" : "npm-install";
     }
-    getInstalledPackageRoot(installDir, packageName) {
-        const nameParts = packageName.split("/");
-        return path.join(installDir, "node_modules", ...nameParts);
+}
+/**
+ * Read the realm-collapse name list shipped with the kernel under
+ * `dist/generated/runtime-deps.json`. The list is small and stable (today:
+ * `@telorun/sdk`); see `scripts/generate-runtime-deps.mjs` for the rationale
+ * about which packages belong here. Returns an empty array if the file is
+ * unreadable — the npm-loader then degrades to "no realm collapse," which is
+ * still a working install path; only `Stream`-flavoured class-identity bugs
+ * resurface.
+ */
+async function loadRuntimeDeps() {
+    const here = fileURLToPath(import.meta.url);
+    // Walk up from this file's location to the kernel-package root (the dir
+    // that contains package.json). In dev: `kernel/nodejs/`. In published:
+    // the installed package root inside `node_modules/@telorun/kernel/`.
+    // Walk-until-root rather than a fixed depth — the directory tree depth
+    // depends on whether we're in a workspace or installed tree.
+    const pkgDir = await walkUpToPackageRoot(path.dirname(here));
+    if (!pkgDir)
+        return [];
+    const generated = path.join(pkgDir, "dist", "generated", "runtime-deps.json");
+    if (!(await pathExists(generated)))
+        return [];
+    // The file is generated by `scripts/generate-runtime-deps.mjs`; if it
+    // exists but is malformed, that's a kernel-build bug. Don't swallow —
+    // surface so the cause is debuggable. Realm collapse is the whole point
+    // of this code path; quietly degrading to "no realm collapse" would
+    // silently re-introduce the very bug the file fixes.
+    const data = JSON.parse(await fs.readFile(generated, "utf8"));
+    if (!Array.isArray(data?.names)) {
+        throw new Error(`[telo] ${generated} is malformed: expected { names: string[] } at top level. ` +
+            `Re-run \`node scripts/generate-runtime-deps.mjs <pkg-dir>\` to regenerate.`);
     }
-    async getLocalPackageName(packagePath) {
-        const packageJsonPath = path.join(packagePath, "package.json");
-        if (!(await this.pathExists(packageJsonPath))) {
-            throw new Error(`Local package missing package.json: ${packagePath}`);
-        }
-        const content = await fs.readFile(packageJsonPath, "utf8");
-        const parsed = JSON.parse(content);
-        if (!parsed?.name) {
-            throw new Error(`Local package missing name in package.json: ${packagePath}`);
+    return data.names;
+}
+/**
+ * Walk up from `from` until the directory contains a `package.json`.
+ * Returns null at filesystem root if none found.
+ */
+async function walkUpToPackageRoot(from) {
+    let dir = from;
+    while (true) {
+        if (await pathExists(path.join(dir, "package.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Resolve a kernel-runtime dep name to the realpath of its package directory.
+ * Anchored on this module so resolution mirrors the kernel's own.
+ *
+ * Uses two strategies because well-encapsulated packages (e.g. `@telorun/sdk`)
+ * declare a strict `exports` map that doesn't expose `./package.json`:
+ *   1. Try `require.resolve("<name>/package.json")` directly — works for
+ *      packages without an exports map or with a permissive one.
+ *   2. Fall back to resolving the package's main entry and walking up to
+ *      the nearest `package.json` whose `name` field matches.
+ *
+ * Returns null when neither strategy locates the package — `require.resolve`
+ * itself throws `MODULE_NOT_FOUND` if the package isn't installed at all,
+ * which we treat as "no realm-collapse for this name." Other errors (e.g. a
+ * corrupt package.json) propagate so the caller can surface the real cause.
+ */
+async function resolveKernelPackageRoot(name) {
+    try {
+        const pkgJsonPath = requireFromHere.resolve(`${name}/package.json`);
+        return path.dirname(pkgJsonPath);
+    }
+    catch (err) {
+        if (err?.code !== "MODULE_NOT_FOUND" && err?.code !== "ERR_PACKAGE_PATH_NOT_EXPORTED") {
+            throw err;
         }
-        return parsed.name;
-    }
-    async resolvePackageEntry(packageRoot, entry, packageName) {
-        const packageJsonPath = path.join(packageRoot, "package.json");
-        let resolvedPackageName = packageName;
-        let packageJson = null;
-        if (!resolvedPackageName && (await this.pathExists(packageJsonPath))) {
-            const content = await fs.readFile(packageJsonPath, "utf8");
-            try {
-                packageJson = JSON.parse(content);
-                resolvedPackageName = packageJson?.name;
-            }
-            catch {
-                resolvedPackageName = packageName;
-            }
+        // exports map withholds package.json — fall through to mainEntry strategy.
+    }
+    let mainEntry;
+    try {
+        mainEntry = requireFromHere.resolve(name);
+    }
+    catch (err) {
+        if (err?.code === "MODULE_NOT_FOUND")
+            return null;
+        throw err;
+    }
+    let dir = path.dirname(mainEntry);
+    while (true) {
+        const pkgJsonPath = path.join(dir, "package.json");
+        if (await pathExists(pkgJsonPath)) {
+            // Confirm the package.json's `name` field matches — we may have walked
+            // past the target into a parent's package.json. A malformed package.json
+            // here is a real bug (a corrupted node_modules) so let it propagate.
+            const pkg = JSON.parse(await fs.readFile(pkgJsonPath, "utf8"));
+            if (pkg?.name === name)
+                return dir;
         }
-        else if (await this.pathExists(packageJsonPath)) {
-            try {
-                packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
-            }
-            catch {
-                packageJson = null;
-            }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Acquire a process-portable lock on `<root>/.lock` and execute fn while
+ * holding it. Implementation: `fs.open(path, 'wx')` is atomic on POSIX and
+ * Windows; concurrent processes serialize naturally. PID + start time live
+ * inside the lock file so a crashed-holder lock can be detected and reclaimed.
+ *
+ * The lock guards the install-root manifest write, the package-manager
+ * invocation, and any state-file writes. It does NOT serialize *reads* of
+ * already-installed controllers — those run lock-free against a stable tree.
+ */
+async function withInstallLock(installRoot, fn) {
+    const lockPath = path.join(installRoot, ".lock");
+    await fs.mkdir(installRoot, { recursive: true });
+    const lockBody = JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: Date.now() });
+    let handle = null;
+    const waitedSince = Date.now();
+    while (true) {
+        try {
+            handle = await fs.open(lockPath, "wx");
+            await handle.writeFile(lockBody);
+            break;
         }
-        const entryValue = entry.trim();
-        const exportTarget = this.resolvePackageExportTarget(packageJson?.exports, entryValue);
-        if (exportTarget) {
-            const resolved = path.resolve(packageRoot, exportTarget);
-            if (await this.pathExists(resolved)) {
-                return this.resolveForRuntime(resolved, packageRoot);
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+            // Lock exists. Inspect its mtime + PID. If older than LOCK_STALE_MS and
+            // the holding PID isn't alive (or is on another host), reclaim.
+            if (await isLockStale(lockPath)) {
+                await fs.rm(lockPath, { force: true });
+                continue;
             }
-            if (!path.extname(resolved)) {
-                const withJs = `${resolved}.js`;
-                if (await this.pathExists(withJs)) {
-                    return withJs;
-                }
+            if (Date.now() - waitedSince > LOCK_WAIT_MAX_MS) {
+                throw new Error(`[telo] timed out waiting for install lock at ${lockPath} ` +
+                    `(held >${LOCK_WAIT_MAX_MS / 60000} min). ` +
+                    `Inspect the lock file or remove it manually if no other Telo process is running.`);
             }
+            await sleep(LOCK_RETRY_MS);
         }
-        if ((entryValue === "." || entryValue === "./") && packageJson) {
-            const mainFields = ["module", "main"];
-            for (const field of mainFields) {
-                const target = packageJson[field];
-                if (typeof target === "string") {
-                    const resolved = path.resolve(packageRoot, target);
-                    if (await this.pathExists(resolved)) {
-                        return this.resolveForRuntime(resolved, packageRoot);
-                    }
-                    if (!path.extname(resolved)) {
-                        const withJs = `${resolved}.js`;
-                        if (await this.pathExists(withJs)) {
-                            return withJs;
-                        }
-                    }
-                }
-            }
-        }
-        const directPath = path.resolve(packageRoot, entryValue);
-        if (await this.pathExists(directPath)) {
-            return this.resolveForRuntime(directPath, packageRoot);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        // The fd close races nothing important: if it fails, the FD is reaped on
+        // process exit. The unlink is the dangerous one — a non-ENOENT failure
+        // (permissions, read-only mount) means every subsequent kernel waits
+        // LOCK_STALE_MS before reclaiming. Surface it so the cause is visible
+        // rather than hiding behind a silent five-minute hang.
+        await handle.close().catch(() => { });
+        try {
+            await fs.rm(lockPath, { force: true });
         }
-        if (!path.extname(directPath)) {
-            const withJs = `${directPath}.js`;
-            if (await this.pathExists(withJs)) {
-                return withJs;
+        catch (err) {
+            if (err?.code !== "ENOENT") {
+                process.stderr.write(`[telo] failed to release install lock at ${lockPath}: ${err?.message ?? err}\n`);
             }
         }
-        throw new Error(`Controller entry "${entryValue}" could not be resolved in ${packageRoot}`);
     }
-    resolvePackageExportTarget(exportsField, entry) {
-        if (!exportsField) {
-            return null;
-        }
-        const key = entry === "." || entry === "./" ? "." : entry;
-        const target = exportsField[key];
-        return this.resolveExportTargetValue(target);
+}
+async function isLockStale(lockPath) {
+    let stat;
+    try {
+        stat = await fs.stat(lockPath);
     }
-    resolveExportTargetValue(target) {
-        if (!target) {
-            return null;
-        }
-        if (typeof target === "string") {
-            return target;
-        }
-        if (Array.isArray(target)) {
-            for (const item of target) {
-                const resolved = this.resolveExportTargetValue(item);
-                if (resolved) {
-                    return resolved;
-                }
-            }
-            return null;
+    catch (err) {
+        // Race: lock vanished while we inspected it. The next open() will succeed.
+        if (err?.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    const age = Date.now() - stat.mtimeMs;
+    if (age < LOCK_STALE_MS)
+        return false;
+    let body;
+    try {
+        body = await fs.readFile(lockPath, "utf8");
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return false;
+        throw err;
+    }
+    // A zero-byte or unparseable lock file is interpreted as stale: a previous
+    // holder crashed mid-write (empty body) or got partially flushed (truncated
+    // JSON). Treating either as held would deadlock; throwing here would block
+    // every controller load behind a broken file the operator may not even
+    // notice exists.
+    if (!body)
+        return true;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return true;
+    }
+    if (!parsed?.pid)
+        return true;
+    if (parsed.host && parsed.host !== os.hostname())
+        return false; // different host: assume held
+    try {
+        // signal 0 throws if the PID isn't alive (or is owned by a different user)
+        process.kill(parsed.pid, 0);
+        return false;
+    }
+    catch (err) {
+        // ESRCH = no such process. EPERM = exists but we can't signal it; treat as alive.
+        return err?.code === "ESRCH";
+    }
+}
+async function runPackageManager(cwd, args) {
+    try {
+        await execFileAsync(PACKAGE_MANAGER, args, { cwd, maxBuffer: 32 * 1024 * 1024 });
+    }
+    catch (err) {
+        const isMissing = err?.code === "ENOENT" ||
+            /not found|command not recognized/i.test(err?.message ?? "");
+        if (isMissing) {
+            throw new Error(`[telo] '${PACKAGE_MANAGER}' not found on PATH. Telo's controller installer requires a ` +
+                `JavaScript package manager (npm or pnpm). Install Node.js (which bundles npm) or set ` +
+                `TELO_PKG_MANAGER to a different binary name.`);
         }
-        if (typeof target === "object") {
-            const preferredKeys = isBun
-                ? ["bun", "import", "default", "require"]
-                : ["import", "default", "require"];
-            for (const key of preferredKeys) {
-                if (target[key]) {
-                    const resolved = this.resolveExportTargetValue(target[key]);
-                    if (resolved) {
-                        return resolved;
-                    }
-                }
-            }
+        const stderr = err?.stderr ? `\n${err.stderr}` : "";
+        throw new Error(`[telo] '${PACKAGE_MANAGER} ${args.join(" ")}' failed in ${cwd}:${stderr}`);
+    }
+}
+async function readJsonField(filePath, field) {
+    try {
+        const text = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(text);
+        return parsed?.[field];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read the install root's `dependencies[<packageName>]` value, or undefined
+ * if package.json is missing/unreadable or the dep isn't listed. Used by the
+ * lock-free fast path to decide whether a controller is already wired in.
+ */
+async function readDepSpec(installRoot, packageName) {
+    try {
+        const text = await fs.readFile(path.join(installRoot, "package.json"), "utf8");
+        const pkg = JSON.parse(text);
+        const value = pkg?.dependencies?.[packageName];
+        return typeof value === "string" ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Convert an entry-manifest URL to its on-disk path, throwing a descriptive
+ * error for any URL scheme that doesn't map to a local filesystem location.
+ * The install-root anchoring story requires a real directory next to the
+ * manifest; non-file schemes (e.g. `http://`, `https://`) have no such
+ * anchor and would otherwise silently produce a junk path via
+ * `path.resolve("http://host/x")`.
+ *
+ * Bare paths without a scheme are accepted as-is — callers that hand the
+ * loader an absolute filesystem path are common and there's no ambiguity
+ * to surface.
+ */
+function parseFileUrlOrThrow(entryUrl) {
+    if (entryUrl.startsWith("file://"))
+        return fileURLToPath(entryUrl);
+    // A scheme is anything before the first `://` — distinguish a URL from a
+    // bare filesystem path (which has no `://`).
+    const schemeMatch = entryUrl.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):\/\//);
+    if (schemeMatch) {
+        // Env-missing rather than a hard error: the dispatcher should advance
+        // to the next candidate when an HTTP-sourced manifest is paired with a
+        // `pkg:cargo` (or other non-npm) fallback. Hard-failing would lock the
+        // whole resolve chain to this branch.
+        throw new ControllerEnvMissingError(`[telo] entry URL scheme '${schemeMatch[1]}' is not supported by the npm controller ` +
+            `loader. The install root must live next to a local manifest; HTTP-sourced manifests ` +
+            `have no such anchor. Resolve the manifest to disk first, or use file:// directly. ` +
+            `(entryUrl: ${entryUrl})`);
+    }
+    return entryUrl;
+}
+/**
+ * Normalize a `file:` spec to an absolute path so two specs that point at the
+ * same source — one absolute (what the loader synthesizes from `local_path`)
+ * and one relative (what npm rewrites into the install root's package.json) —
+ * compare equal. Specs that aren't `file:` deps pass through unchanged, since
+ * registry tags compare exactly.
+ */
+function normalizeFileSpec(spec, installRoot) {
+    if (!spec.startsWith("file:"))
+        return spec;
+    const filePath = spec.slice("file:".length);
+    if (path.isAbsolute(filePath))
+        return `file:${path.resolve(filePath)}`;
+    return `file:${path.resolve(installRoot, filePath)}`;
+}
+/**
+ * Snapshot the install root's full `dependencies` map so the per-controller
+ * fast path can lookup specs without re-reading package.json on every load.
+ * Returns null when the file is missing or unreadable; callers decide whether
+ * to seed from a synthesized map instead.
+ */
+async function readPackageDeps(installRoot) {
+    try {
+        const text = await fs.readFile(path.join(installRoot, "package.json"), "utf8");
+        const pkg = JSON.parse(text);
+        const deps = pkg?.dependencies;
+        if (!deps || typeof deps !== "object")
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(deps)) {
+            if (typeof v === "string")
+                out[k] = v;
         }
+        return out;
+    }
+    catch {
         return null;
     }
-    async resolveForRuntime(resolvedPath, packageRoot) {
-        if (isBun || !resolvedPath.endsWith(".ts")) {
-            return resolvedPath;
+}
+function sha256(s) {
+    return crypto.createHash("sha256").update(s).digest("hex");
+}
+async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Decide what `npm install <spec>` should look like for this PURL. Returns
+ * a discriminated union so the caller and the installer agree on the kind
+ * of install without re-deriving it from the spec string. `local_path`
+ * resolves relative to the *declaring library's* baseUri (each
+ * Telo.Definition's manifest URL); the loader installs the absolute path
+ * via `npm install file:<abs>` so realm-collapse still applies even for
+ * source already on disk.
+ */
+async function resolveInstallSpec(parsed, packageName, baseUri) {
+    const localPath = parsed.qualifiers?.local_path;
+    const isLocalManifest = !!baseUri && !baseUri.startsWith("http://") && !baseUri.startsWith("https://");
+    if (localPath && isLocalManifest) {
+        const baseUriPath = baseUri.startsWith("file://") ? fileURLToPath(baseUri) : baseUri;
+        const absolutePath = path.resolve(path.dirname(baseUriPath), localPath);
+        if (await pathExists(absolutePath)) {
+            return { kind: "local", spec: `file:${absolutePath}`, absolutePath };
         }
-        const relative = path.relative(packageRoot, resolvedPath);
-        const distEquivalent = path.resolve(packageRoot, relative.replace(/^src\//, "dist/").replace(/\.ts$/, ".js"));
-        if (await this.pathExists(distEquivalent)) {
-            return distEquivalent;
+    }
+    const spec = parsed.version ? `${packageName}@${parsed.version}` : packageName;
+    return { kind: "registry", spec };
+}
+/**
+ * Import the controller module out of the install root and validate its
+ * shape. Splits cleanly from the install logic so each phase has one job:
+ * `installPackage` decides whether work is needed, this function is pure
+ * resolve-and-import once the tree is in place.
+ */
+async function loadFromInstall(installRoot, packageName, subpath, purl) {
+    const packageRoot = path.join(installRoot, "node_modules", ...packageName.split("/"));
+    const entry = subpath ? `./${subpath}` : ".";
+    const entryFile = await resolvePackageEntry(packageRoot, entry);
+    // ESM dynamic `import()` accepts either a relative specifier or a `file://`
+    // URL — but NOT a bare absolute filesystem path. On POSIX the `/abs/path`
+    // form works by happy accident; on Windows `C:\path\to\file.js` is rejected
+    // outright. Convert through `pathToFileURL` so the loader behaves the same
+    // on both platforms.
+    //
+    // Dynamic `import()` always resolves to a module namespace object on
+    // success; it never returns null/undefined. The only meaningful contract
+    // check is whether the module exports at least one of the controller hooks.
+    const instance = await import(pathToFileURL(entryFile).href);
+    if (!instance.create && !instance.register) {
+        throw new Error(`Invalid controller loaded from "${purl}": exports neither create() nor register()`);
+    }
+    return instance;
+}
+/**
+ * Default ESM resolver conditions, in priority order. The `bun` condition
+ * comes first when running under Bun so dev workspaces resolve to `src/*.ts`
+ * directly without a build step. The remaining conditions are the standard
+ * Node.js ESM keys; the loader doesn't honour `node` because we always
+ * fall back to `import`/`default` for Node anyway.
+ */
+const DEFAULT_RESOLVER_CONDITIONS = typeof globalThis.Bun !== "undefined"
+    ? ["bun", "import", "default", "require"]
+    : ["import", "default", "require"];
+/**
+ * Cap on `exports` map traversal depth. A pathological consumer-authored
+ * package.json with cycles through array/object trees would otherwise loop
+ * forever (the data is third-party — `package.json` files we read out of an
+ * arbitrary npm install). 16 levels is far past any plausible legitimate map.
+ */
+const EXPORTS_MAX_DEPTH = 16;
+/**
+ * Resolve a package's entry file using its package.json `exports` map first,
+ * then the `module`/`main` fields, then a direct path lookup. The conditions
+ * list is supplied by the caller so the resolver stays generic — today the
+ * only branch is Bun-vs-Node, but worker/browser/electron/deno selections
+ * compose the same way.
+ */
+async function resolvePackageEntry(packageRoot, entry, conditions = DEFAULT_RESOLVER_CONDITIONS) {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    let packageJson = null;
+    if (await pathExists(packageJsonPath)) {
+        // A package.json that exists but won't parse is a real on-disk problem
+        // (corrupted install, half-written file from an interrupted `npm install`,
+        // hand-edited typo). Surface it — silently falling through to the
+        // direct-path branch produces an opaque "missing create or register"
+        // error instead of "your package.json is broken."
+        const raw = await fs.readFile(packageJsonPath, "utf8");
+        try {
+            packageJson = JSON.parse(raw);
         }
-        const jsPath = resolvedPath.replace(/\.ts$/, ".js");
-        if (await this.pathExists(jsPath)) {
-            return jsPath;
+        catch (err) {
+            throw new Error(`[telo] failed to parse ${packageJsonPath}: ` +
+                (err instanceof Error ? err.message : String(err)));
         }
-        return resolvedPath;
-    }
-    async findInNodeModules(packageName) {
-        const nameParts = packageName.split("/");
-        const candidates = [
-            path.join(process.cwd(), "node_modules", ...nameParts),
-            path.join(process.cwd(), "node_modules", ".pnpm", "node_modules", ...nameParts),
-        ];
-        for (const candidate of candidates) {
-            const packageJsonPath = path.join(candidate, "package.json");
-            if (await this.pathExists(packageJsonPath)) {
-                return candidate;
-            }
+    }
+    const entryValue = entry.trim();
+    const exportTarget = resolvePackageExportTarget(packageJson?.exports, entryValue, conditions);
+    if (exportTarget) {
+        const hit = await tryResolveFile(path.resolve(packageRoot, exportTarget));
+        if (hit)
+            return hit;
+    }
+    if ((entryValue === "." || entryValue === "./") && packageJson) {
+        for (const field of ["module", "main"]) {
+            const target = packageJson[field];
+            if (typeof target !== "string")
+                continue;
+            const hit = await tryResolveFile(path.resolve(packageRoot, target));
+            if (hit)
+                return hit;
         }
-        return null;
     }
-    async pathExists(filePath) {
-        try {
-            await fs.access(filePath);
-            return true;
+    const direct = await tryResolveFile(path.resolve(packageRoot, entryValue));
+    if (direct)
+        return direct;
+    throw new Error(`Controller entry "${entryValue}" could not be resolved in ${packageRoot}`);
+}
+/**
+ * Try a path verbatim, then with `.js` appended if it has no extension.
+ * Returns the first path that exists, or null if neither does. Centralizes
+ * the extension-fallback rule so it's not repeated at every call site.
+ */
+async function tryResolveFile(absPath) {
+    if (await pathExists(absPath))
+        return absPath;
+    if (!path.extname(absPath)) {
+        const withJs = `${absPath}.js`;
+        if (await pathExists(withJs))
+            return withJs;
+    }
+    return null;
+}
+function resolvePackageExportTarget(exportsField, entry, conditions) {
+    if (!exportsField)
+        return null;
+    const key = entry === "." || entry === "./" ? "." : entry;
+    return resolveExportTargetValue(exportsField[key], conditions, 0);
+}
+function resolveExportTargetValue(target, conditions, depth) {
+    if (depth > EXPORTS_MAX_DEPTH)
+        return null;
+    if (!target)
+        return null;
+    if (typeof target === "string")
+        return target;
+    if (Array.isArray(target)) {
+        for (const item of target) {
+            const resolved = resolveExportTargetValue(item, conditions, depth + 1);
+            if (resolved)
+                return resolved;
         }
-        catch {
-            return false;
+        return null;
+    }
+    if (typeof target === "object") {
+        for (const key of conditions) {
+            if (target[key] !== undefined) {
+                const resolved = resolveExportTargetValue(target[key], conditions, depth + 1);
+                if (resolved)
+                    return resolved;
+            }
         }
     }
+    return null;
 }
+/**
+ * Pure helpers exported under a stable namespace for unit tests. The class
+ * itself isn't useful in isolation (it requires a package manager binary, a
+ * filesystem, and a network for non-local specs); these are the deterministic
+ * parts that benefit from cheap unit coverage and have no side effects.
+ *
+ * Not part of the kernel's public API — consumers should not import these.
+ */
+export const __testing__ = {
+    normalizeFileSpec,
+    resolvePackageExportTarget,
+    resolveExportTargetValue,
+    tryResolveFile,
+    walkUpToPackageRoot,
+    EXPORTS_MAX_DEPTH,
+    DEFAULT_RESOLVER_CONDITIONS,
+};
 //# sourceMappingURL=npm-loader.js.map