@telorun/kernel 0.4.0 → 0.5.0

package/src/controller-loader.ts

@@ -1,301 +1,105 @@
 import { ControllerInstance, RuntimeError } from "@telorun/sdk";
-import { execFile } from "child_process";
-import { createHash } from "crypto";
-import * as fs from "fs/promises";
-import * as os from "os";
-import { PackageURL } from "packageurl-js";
-import * as path from "path";
-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 as any).Bun !== "undefined";
-
+import { ControllerEnvMissingError, NapiControllerLoader } from "./controller-loaders/napi-loader.js";
+import { NpmControllerLoader } from "./controller-loaders/npm-loader.js";
+import { ControllerPolicy, DEFAULT_POLICY, POLICY_WILDCARD } from "./runtime-registry.js";
+
+export type { ControllerPolicy } from "./runtime-registry.js";
+
+/**
+ * Top-level controller-loader dispatcher. Picks a per-scheme sub-loader by
+ * PURL type and applies the resolved selection policy:
+ *
+ *   ControllerLoader.load(candidates, baseUri, policy)
+ *     └─ orderCandidates(candidates, policy)
+ *          ├─ pkg:npm   → NpmControllerLoader
+ *          └─ pkg:cargo → NapiControllerLoader
+ *
+ * Recovery: env-missing failures (`ControllerEnvMissingError`) advance to the
+ * next candidate. User-code failures (`RuntimeError("ERR_CONTROLLER_BUILD_FAILED" | "ERR_CONTROLLER_INVALID")`)
+ * fail hard regardless of remaining candidates.
+ */
 export class ControllerLoader {
-  /**
-   * Load controller instance from URI in format:
-   *
-   * <runtime>:<registry>:<path>@<version-spec>
-   */
-  async load(purlCandidates: string[], baseUri: string): Promise<ControllerInstance> {
+  private npmLoader = new NpmControllerLoader();
+  private napiLoader = new NapiControllerLoader();
+
+  async load(
+    purlCandidates: string[],
+    baseUri: string,
+    policy?: ControllerPolicy,
+  ): Promise<ControllerInstance> {
     if (!purlCandidates || purlCandidates.length === 0) {
       throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", "Missing controller PURL candidates");
     }
-    const purl = purlCandidates.find((p) => p.startsWith("pkg:npm"));
-    if (!purl) {
+    const effectivePolicy = policy ?? DEFAULT_POLICY;
+    const ordered = orderCandidates(purlCandidates, effectivePolicy);
+    if (ordered.length === 0) {
       throw new RuntimeError(
         "ERR_CONTROLLER_NOT_FOUND",
-        "Controller PURL candidates not applicable",
+        `No controllers match runtime selection [${effectivePolicy.load.join(", ")}]; declared: ${purlCandidates.join(", ")}`,
       );
     }
-    const [type, namespace, name, versionSpec, qualifiers, entry] = PackageURL.parseString(purl);
 
-    const localPath = (qualifiers as any)?.get("local_path");
-    const cacheKey = createHash("sha256").update(purlCandidates[0]).digest("hex").slice(0, 12);
-    const installDir = path.join(npmCacheRoot, cacheKey);
-
-    let packageRoot: string;
-    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;
-      } else {
-        const nodeModulesPath = await this.findInNodeModules(`${namespace}/${name}`);
-        if (nodeModulesPath) {
-          packageRoot = nodeModulesPath;
-        } else {
-          await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
-          packageRoot = this.getInstalledPackageRoot(installDir, `${namespace}/${name}`);
+    const errors: string[] = [];
+    for (const purl of ordered) {
+      try {
+        return await this.dispatchOne(purl, baseUri);
+      } catch (err) {
+        if (err instanceof ControllerEnvMissingError) {
+          errors.push(`${purl}: ${err.message}`);
+          continue;
         }
+        throw err;
       }
-    } else {
-      const nodeModulesPath = await this.findInNodeModules(`${namespace}/${name}`);
-      if (nodeModulesPath) {
-        packageRoot = nodeModulesPath;
-      } else {
-        await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
-        packageRoot = this.getInstalledPackageRoot(installDir, `${namespace}/${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 "${purlCandidates[0]}": missing create or register function`,
-      );
     }
-    return instance;
-  }
-
-  private async ensureNpmPackageInstalled(installDir: string, packageSpec: string): Promise<void> {
-    const packageName = this.getPackageName(
-      packageSpec.startsWith(".") || path.isAbsolute(packageSpec)
-        ? await this.getLocalPackageName(packageSpec)
-        : packageSpec,
+    throw new RuntimeError(
+      "ERR_CONTROLLER_NOT_FOUND",
+      `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`,
     );
-    const packageRoot = this.getInstalledPackageRoot(installDir, packageName);
-    const packageJsonPath = path.join(packageRoot, "package.json");
-    if (await this.pathExists(packageJsonPath)) {
-      return;
-    }
-
-    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 execFileAsync = promisify(execFile);
-    const args = [
-      "install",
-      "--no-audit",
-      "--no-fund",
-      "--silent",
-      "--prefix",
-      installDir,
-      packageSpec,
-    ];
-
-    await execFileAsync("npm", args);
-  }
-
-  private getPackageName(packageSpec: string): string {
-    if (packageSpec.startsWith("@")) {
-      const lastAt = packageSpec.lastIndexOf("@");
-      return lastAt > 0 ? packageSpec.slice(0, lastAt) : packageSpec;
-    }
-    const [name] = packageSpec.split("@");
-    return name;
-  }
-
-  private getInstalledPackageRoot(installDir: string, packageName: string): string {
-    const nameParts = packageName.split("/");
-    return path.join(installDir, "node_modules", ...nameParts);
-  }
-
-  private async getLocalPackageName(packagePath: string): Promise<string> {
-    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 parsed.name;
   }
 
-  private async resolvePackageEntry(
-    packageRoot: string,
-    entry: string,
-    packageName?: string,
-  ): Promise<string> {
-    const packageJsonPath = path.join(packageRoot, "package.json");
-    let resolvedPackageName = packageName;
-    let packageJson: any = 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;
-      }
-    } else if (await this.pathExists(packageJsonPath)) {
-      try {
-        packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
-      } catch {
-        packageJson = null;
-      }
-    }
-
-    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);
-      }
-      if (!path.extname(resolved)) {
-        const withJs = `${resolved}.js`;
-        if (await this.pathExists(withJs)) {
-          return withJs;
-        }
-      }
-    }
-    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);
+  private async dispatchOne(purl: string, baseUri: string): Promise<ControllerInstance> {
+    if (purl.startsWith("pkg:npm")) {
+      return this.npmLoader.load(purl, baseUri);
     }
-    if (!path.extname(directPath)) {
-      const withJs = `${directPath}.js`;
-      if (await this.pathExists(withJs)) {
-        return withJs;
-      }
+    if (purl.startsWith("pkg:cargo")) {
+      return this.napiLoader.load(purl, baseUri);
     }
-
-    throw new Error(`Controller entry "${entryValue}" could not be resolved in ${packageRoot}`);
+    throw new ControllerEnvMissingError(`Unsupported PURL scheme: ${purl}`);
   }
+}
 
-  private resolvePackageExportTarget(exportsField: any, entry: string): string | null {
-    if (!exportsField) {
-      return null;
-    }
-
-    const key = entry === "." || entry === "./" ? "." : entry;
-    const target = exportsField[key];
-    return this.resolveExportTargetValue(target);
-  }
+function getPurlType(purl: string): string {
+  const slashIdx = purl.indexOf("/", purl.indexOf(":") + 1);
+  return slashIdx === -1 ? purl : purl.slice(0, slashIdx);
+}
 
-  private resolveExportTargetValue(target: any): string | null {
-    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;
+function orderCandidates(
+  candidates: ReadonlyArray<string>,
+  policy: ControllerPolicy,
+): string[] {
+  const result: string[] = [];
+  const seen = new Set<string>();
+  const explicitTypes = new Set(policy.load.filter((t) => t !== POLICY_WILDCARD));
+
+  for (const entry of policy.load) {
+    if (entry === POLICY_WILDCARD) {
+      for (const candidate of candidates) {
+        if (seen.has(candidate)) continue;
+        const type = getPurlType(candidate);
+        if (!explicitTypes.has(type)) {
+          result.push(candidate);
+          seen.add(candidate);
         }
       }
-      return null;
-    }
-    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;
-          }
+    } else {
+      for (const candidate of candidates) {
+        if (seen.has(candidate)) continue;
+        if (getPurlType(candidate) === entry) {
+          result.push(candidate);
+          seen.add(candidate);
         }
       }
     }
-    return null;
-  }
-
-  /**
-   * For Node.js, resolve .ts paths to their compiled .js equivalents in dist/.
-   * Bun can load .ts directly, so it returns the path unchanged.
-   */
-  private async resolveForRuntime(resolvedPath: string, packageRoot: string): Promise<string> {
-    if (isBun || !resolvedPath.endsWith(".ts")) {
-      return resolvedPath;
-    }
-    // Try dist/ equivalent: src/foo.ts -> dist/foo.js
-    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;
-    }
-    // Fallback: same location but .js
-    const jsPath = resolvedPath.replace(/\.ts$/, ".js");
-    if (await this.pathExists(jsPath)) {
-      return jsPath;
-    }
-    return resolvedPath;
-  }
-
-  private async findInNodeModules(packageName: string): Promise<string | null> {
-    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;
-      }
-    }
-    return null;
-  }
-
-  private async pathExists(filePath: string): Promise<boolean> {
-    try {
-      await fs.access(filePath);
-      return true;
-    } catch {
-      return false;
-    }
   }
+  return result;
 }

package/src/controller-loaders/napi-loader.ts

@@ -0,0 +1,191 @@
+import { ControllerInstance, RuntimeError } from "@telorun/sdk";
+import { execFile } from "child_process";
+import * as fs from "fs/promises";
+import { createRequire } from "module";
+import { PackageURL } from "packageurl-js";
+import * as path from "path";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+const requireFromHere = createRequire(import.meta.url);
+
+/**
+ * Recoverable resolution failure — the loader could not find the artifact in the
+ * environment (missing rustc, missing local_path, missing prebuilt dylib in dist
+ * mode). The dispatcher may try the next candidate when wildcard fallback is
+ * enabled. Distinguished from `RuntimeError("ERR_CONTROLLER_BUILD_FAILED" | …)`
+ * which is non-recoverable: those mean user code is broken and must surface.
+ */
+export class ControllerEnvMissingError extends Error {
+  readonly _envMissing = true as const;
+  constructor(message: string) {
+    super(message);
+    this.name = "ControllerEnvMissingError";
+  }
+}
+
+/**
+ * Process-lifetime cache of resolved native modules keyed by the realpath of
+ * the crate directory. The first call for a given crate does the cargo build,
+ * dylib rename, and `require()` work; subsequent calls (e.g. a second kernel
+ * registering the same controller, or two manifests reaching the crate via
+ * different — possibly symlinked — paths) skip straight to the cached module.
+ *
+ * Beyond the obvious cost saving, this is load-bearing for Node compatibility:
+ * `fs.copyFile` overwriting a `.node` file that Node has already mmapped, plus
+ * the secondary `cargo metadata` / build invocations, can leave Node's native
+ * addon machinery in a state where finalize callbacks for class instances
+ * created in a previous kernel race and segfault. Keying on the canonical
+ * crate path (not on the caller's baseUri) ensures two distinct paths that
+ * point at the same crate share one cache entry.
+ */
+const _napiModuleCache = new Map<string, ControllerInstance>();
+
+export class NapiControllerLoader {
+  /**
+   * Resolve a `pkg:cargo/...` PURL to a controller module instance by building
+   * the crate and loading the resulting native addon.
+   *
+   * Dev mode (local_path qualifier present): probe rustc, run `cargo build
+   * --release`, locate the dylib via `cargo metadata`, copy to
+   * `<libname>.node`, load via createRequire. Cached on success.
+   *
+   * Distribution mode (no local_path): out of scope for the PoC; the hook is
+   * left in place so the dispatcher reports env-missing and falls through.
+   */
+  async load(purl: string, baseUri: string): Promise<ControllerInstance> {
+    const [, , name, , qualifiers] = PackageURL.parseString(purl);
+    const localPath = (qualifiers as any)?.get("local_path");
+
+    const isLocalManifest =
+      baseUri && !baseUri.startsWith("http://") && !baseUri.startsWith("https://");
+    if (!localPath || !isLocalManifest) {
+      throw new ControllerEnvMissingError(
+        `pkg:cargo distribution-mode resolution is not implemented for the PoC; supply ?local_path=...`,
+      );
+    }
+
+    const baseUriPath = baseUri.startsWith("file://") ? baseUri.slice("file://".length) : baseUri;
+    const manifestDir = path.dirname(baseUriPath);
+    const cratePath = path.resolve(manifestDir, localPath);
+
+    if (!(await pathExists(cratePath))) {
+      throw new ControllerEnvMissingError(`pkg:cargo local_path does not exist: ${cratePath}`);
+    }
+
+    // Key the cache on the canonical crate location (realpath) — two manifests
+    // that reach the same crate via different baseUris (e.g. through symlinked
+    // workspace paths) must share one cache entry. A miss here would re-run
+    // cargo build and `fs.copyFile` over an already-mmapped `.node`, which
+    // can leave napi finalize callbacks racing and crash Node.
+    const canonicalCratePath = await fs.realpath(cratePath);
+    const cacheKey = canonicalCratePath;
+    const cached = _napiModuleCache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      await execFileAsync("rustc", ["--version"]);
+    } catch {
+      throw new ControllerEnvMissingError("rustc not found on PATH");
+    }
+
+    try {
+      // Plain `cargo build --release` — no `--features` flag. The SDK's
+      // `default = ["napi"]` selects the napi backend transitively, so the
+      // controller crate's Cargo.toml stays free of any `[features]` block
+      // or napi-rs deps. A future Rust kernel passes
+      // `--no-default-features --features native` here instead.
+      await execFileAsync("cargo", ["build", "--release"], {
+        cwd: cratePath,
+        maxBuffer: 32 * 1024 * 1024,
+      });
+    } catch (err: any) {
+      const stderr = err?.stderr ? `\n${err.stderr}` : "";
+      throw new RuntimeError(
+        "ERR_CONTROLLER_BUILD_FAILED",
+        `cargo build failed for ${cratePath}:${stderr}`,
+      );
+    }
+
+    const { targetDir, libName } = await resolveCrateMetadata(cratePath, name ?? "");
+
+    const dylibPath = await findDylib(targetDir, libName);
+    if (!dylibPath) {
+      throw new RuntimeError(
+        "ERR_CONTROLLER_BUILD_FAILED",
+        `cargo build succeeded but no cdylib found for ${libName} under ${path.join(targetDir, "release")}/`,
+      );
+    }
+
+    const nodePath = path.join(path.dirname(dylibPath), `${libName}.node`);
+    await fs.copyFile(dylibPath, nodePath);
+
+    let module: any;
+    try {
+      module = requireFromHere(nodePath);
+    } catch (err: any) {
+      throw new RuntimeError(
+        "ERR_CONTROLLER_INVALID",
+        `Failed to load native addon ${nodePath}: ${err.message}`,
+      );
+    }
+
+    if (!module || (!module.create && !module.register)) {
+      throw new RuntimeError(
+        "ERR_CONTROLLER_INVALID",
+        `pkg:cargo controller at ${nodePath} exports neither create nor register`,
+      );
+    }
+    _napiModuleCache.set(cacheKey, module);
+    return module;
+  }
+}
+
+async function resolveCrateMetadata(
+  cratePath: string,
+  fallbackName: string,
+): Promise<{ targetDir: string; libName: string }> {
+  const result = await execFileAsync("cargo", [
+    "metadata",
+    "--format-version",
+    "1",
+    "--manifest-path",
+    path.join(cratePath, "Cargo.toml"),
+    "--no-deps",
+  ], { maxBuffer: 32 * 1024 * 1024 });
+  const metadata = JSON.parse(result.stdout);
+  const cratePackage = metadata.packages?.find(
+    (p: any) => p.manifest_path === path.join(cratePath, "Cargo.toml"),
+  );
+  const packageName = cratePackage?.name ?? fallbackName;
+  return {
+    targetDir: metadata.target_directory,
+    libName: packageName.replace(/-/g, "_"),
+  };
+}
+
+async function findDylib(targetDir: string, libName: string): Promise<string | null> {
+  const releaseDir = path.join(targetDir, "release");
+  const candidates = [
+    path.join(releaseDir, `lib${libName}.so`),
+    path.join(releaseDir, `lib${libName}.dylib`),
+    path.join(releaseDir, `${libName}.dll`),
+  ];
+  for (const candidate of candidates) {
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}