@telorun/kernel 0.12.0 → 0.13.0

package/dist/snapshot-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-serializer.js","sourceRoot":"","sources":["../src/snapshot-serializer.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+import type { ControllerContext, ResourceContext, ResourceInstance, ResourceManifest, RuntimeErrorCode, RuntimeResource } from "@telorun/sdk";
+import type { ModuleContext } from "./module-context.js";
+export type { ControllerContext, ResourceContext, ResourceInstance, ResourceManifest } from "@telorun/sdk";
+export interface KernelContext {
+    kernel: Kernel;
+}
+export interface ExecContext {
+    execute(urn: string, input: any): Promise<any>;
+    [key: string]: any;
+}
+export type ResourceCapability = string;
+export interface ResourceDefinition {
+    kind: string;
+    metadata: {
+        name: string;
+        module: string;
+    };
+    schema: Record<string, any>;
+    capabilities: ResourceCapability[];
+    events?: string[];
+    controllers?: Array<{
+        runtime: string;
+        entry: string;
+    }>;
+}
+/**
+ * Controller definition for a resource kind.
+ * Maps a fully-qualified resource kind to its controller implementation for a specific runtime.
+ */
+export interface ControllerDefinition {
+    kind: string;
+    runtime: string;
+    entry: string;
+    controller?: any;
+}
+/**
+ * Controller instance - runtime representation of a controller that handles resource instances.
+ */
+export interface ControllerInstance {
+    execute?(name: string, inputs: any, ctx: ExecContext): Promise<any>;
+    compile?(resource: ResourceManifest, ctx: ResourceContext): RuntimeResource | Promise<RuntimeResource>;
+    register?(ctx: ControllerContext): void | Promise<void>;
+    create?(resource: ResourceManifest, ctx: ResourceContext): ResourceInstance | null | Promise<ResourceInstance | null>;
+    schema: any;
+}
+export interface Kernel {
+    loadFromConfig(runtimeYamlPath: string): Promise<void>;
+    start(): Promise<void>;
+    acquireHold(reason?: string): () => void;
+    waitForIdle(): Promise<void>;
+    requestExit(code: number): void;
+    readonly exitCode: number;
+    teardownResource(module: string, kind: string, name: string): Promise<void>;
+    registerChildManifest(parentKey: string, resource: ResourceManifest): void;
+    getSourceFiles(): string[];
+    reloadSource(sourcePath: string): Promise<void>;
+    shutdown(): void;
+    registerModuleContext(moduleName: string, variables: Record<string, unknown>, secrets: Record<string, unknown>): void;
+    getModuleContext(moduleName: string): ModuleContext;
+}
+export declare class RuntimeError extends Error {
+    code: RuntimeErrorCode;
+    constructor(code: RuntimeErrorCode, message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+export class RuntimeError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "RuntimeError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA0FA,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YACS,IAAsB,EAC7B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,SAAI,GAAJ,IAAI,CAAkB;QAI7B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF"}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
-    "digly",
+    "telo",
     "runtime",
     "execution",
     "manifest"
@@ -47,8 +47,8 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.5.3",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.11.0",
-    "@telorun/sdk": "0.11.1",
+    "@telorun/analyzer": "0.12.0",
+    "@telorun/templating": "0.3.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "minimatch": "^10.2.5",
@@ -60,11 +60,14 @@
     "typescript": "^5.0.0",
     "vitest": "^2.1.8"
   },
+  "peerDependencies": {
+    "@telorun/sdk": "0.12.0"
+  },
   "overrides": {
     "@marcbachmann/cel-js": "$@marcbachmann/cel-js",
     "@sinclair/typebox": "$@sinclair/typebox",
     "@telorun/analyzer": "$@telorun/analyzer",
-    "@telorun/sdk": "$@telorun/sdk",
+    "@telorun/templating": "$@telorun/templating",
     "ajv": "$ajv",
     "ajv-formats": "$ajv-formats",
     "minimatch": "$minimatch",
@@ -72,7 +75,7 @@
     "yaml": "$yaml"
   },
   "scripts": {
-    "build": "tsc && node ../../scripts/generate-runtime-deps.mjs .",
+    "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest"

package/src/application-env.ts

@@ -0,0 +1,216 @@
+import { residualEntrySchema } from "@telorun/analyzer";
+import { RuntimeError } from "@telorun/sdk";
+import { SchemaValidator } from "./schema-validator.js";
+
+type EntryType = "string" | "integer" | "number" | "boolean" | "object" | "array";
+
+interface EnvEntry {
+  env: string;
+  type: EntryType;
+  default?: unknown;
+  [key: string]: unknown;
+}
+
+export interface EnvResolutionResult {
+  variables: Record<string, unknown>;
+  secrets: Record<string, unknown>;
+}
+
+/**
+ * Populate the root Application's `variables` / `secrets` namespaces from
+ * host environment variables, per the per-field `env:` mapping declared on
+ * each entry.
+ *
+ * Implements the polyglot env-resolution spec from
+ * kernel/nodejs/plans/application-env-variables.md: read the env var, coerce
+ * per `entry.type`, validate the coerced value (or the declared default, when
+ * the env var is unset) against the entry's residual schema, and aggregate
+ * every failure into a single `ERR_MANIFEST_VALIDATION_FAILED` error so all
+ * problems surface before any controller initializes.
+ *
+ * This must run BEFORE any Telo.Import controller initializes — imports may
+ * pass `${{ variables.X }}` as their `variables:` inputs, so the root scope
+ * has to be populated by the time the import controller evaluates those
+ * expressions.
+ */
+export function resolveApplicationEnv(
+  manifest: Record<string, any>,
+  env: Record<string, string | undefined>,
+  validator: SchemaValidator,
+): EnvResolutionResult {
+  const errors: string[] = [];
+  const variables = resolveBlock(
+    manifest.variables ?? {},
+    env,
+    validator,
+    errors,
+    false,
+  );
+  const secrets = resolveBlock(
+    manifest.secrets ?? {},
+    env,
+    validator,
+    errors,
+    true,
+  );
+  if (errors.length > 0) {
+    throw new RuntimeError(
+      "ERR_MANIFEST_VALIDATION_FAILED",
+      `Application environment validation failed:\n` +
+        errors.map((e) => `  - ${e}`).join("\n"),
+    );
+  }
+  return { variables, secrets };
+}
+
+function resolveBlock(
+  block: Record<string, EnvEntry> | unknown,
+  env: Record<string, string | undefined>,
+  validator: SchemaValidator,
+  errors: string[],
+  isSecret: boolean,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    return out;
+  }
+  for (const [name, entry] of Object.entries(block as Record<string, EnvEntry>)) {
+    if (!entry || typeof entry !== "object") continue;
+    const envKey = entry.env;
+    const raw = env[envKey];
+    const residual = residualEntrySchema(entry as Record<string, unknown>);
+
+    if (raw === undefined || raw === null) {
+      if (entry.default !== undefined) {
+        const validation = validateResidual(entry.default, residual, validator);
+        if (validation) {
+          errors.push(`${name}: ${validation}`);
+        } else {
+          out[name] = entry.default;
+        }
+        continue;
+      }
+      errors.push(`${name}: environment variable ${envKey} is not set (no default)`);
+      continue;
+    }
+
+    let coerced: unknown;
+    try {
+      coerced = coerce(raw, entry.type, envKey, isSecret);
+    } catch (e) {
+      errors.push(`${name}: ${(e as Error).message}`);
+      continue;
+    }
+
+    const validation = validateResidual(coerced, residual, validator);
+    if (validation) {
+      errors.push(`${name}: ${validation}`);
+      continue;
+    }
+
+    out[name] = coerced;
+  }
+  return out;
+}
+
+/** Render a raw env value for inclusion in an error message. Secret values
+ *  are masked so coercion / schema diagnostics don't leak secret material
+ *  into logs (the env-var name and the failure reason still surface). */
+function renderRawForError(raw: string, isSecret: boolean): string {
+  return isSecret ? "<redacted>" : `"${raw}"`;
+}
+
+function coerce(
+  raw: string,
+  type: EntryType,
+  envKey: string,
+  isSecret: boolean,
+): unknown {
+  switch (type) {
+    case "string":
+      return raw;
+    case "integer": {
+      const trimmed = raw.trim();
+      if (!/^-?\d+$/.test(trimmed)) {
+        throw new Error(
+          `environment variable ${envKey}: value ${renderRawForError(raw, isSecret)} is not a valid integer`,
+        );
+      }
+      return parseInt(trimmed, 10);
+    }
+    case "number": {
+      const n = parseFloat(raw);
+      if (Number.isNaN(n)) {
+        throw new Error(
+          `environment variable ${envKey}: value ${renderRawForError(raw, isSecret)} is not a valid number`,
+        );
+      }
+      return n;
+    }
+    case "boolean":
+      if (raw === "true") return true;
+      if (raw === "false") return false;
+      throw new Error(
+        `environment variable ${envKey}: value ${renderRawForError(raw, isSecret)} is not a valid boolean (expected "true" or "false")`,
+      );
+    case "object": {
+      const parsed = parseJson(raw, envKey, isSecret);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(
+          `environment variable ${envKey}: expected JSON object, got ${describeJsonType(parsed)}`,
+        );
+      }
+      return parsed;
+    }
+    case "array": {
+      const parsed = parseJson(raw, envKey, isSecret);
+      if (!Array.isArray(parsed)) {
+        throw new Error(
+          `environment variable ${envKey}: expected JSON array, got ${describeJsonType(parsed)}`,
+        );
+      }
+      return parsed;
+    }
+  }
+}
+
+function parseJson(raw: string, envKey: string, isSecret: boolean): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    // Node's JSON.parse error embeds the offending character / position; for
+    // secrets, swallow the parser detail and surface only the env var name.
+    const detail = isSecret ? "value is not valid JSON" : (e as Error).message;
+    throw new Error(`environment variable ${envKey}: ${isSecret ? detail : `value is not valid JSON: ${detail}`}`);
+  }
+}
+
+function describeJsonType(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function validateResidual(
+  value: unknown,
+  residual: Record<string, unknown>,
+  validator: SchemaValidator,
+): string | null {
+  try {
+    validator.compile(residual as any).validate(value);
+    return null;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    // Strip SchemaValidator's "Invalid value passed: <JSON>. Error: " prefix
+    // so the JSON-stringified value (which can be secret material for entries
+    // under `secrets:`) never reaches the caller. The split is anchored on
+    // the literal ". Error: " delimiter — a `[^.]*` regex would have leaked
+    // any value containing a dot (URLs, versions, paths).
+    const sentinel = ". Error: ";
+    const idx = msg.indexOf(sentinel);
+    if (msg.startsWith("Invalid value passed:") && idx !== -1) {
+      return msg.slice(idx + sentinel.length);
+    }
+    return msg;
+  }
+}

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

@@ -81,10 +81,13 @@ export interface NpmControllerLoaderOptions {
 }
 
 /**
- * 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
+ * The npm-loader maintains a single install root per kernel process. For a
+ * local entry manifest (`file://` URL or bare path) the root lives at
+ * `<entry-manifest-dir>/.telo/npm/`; for an HTTP(S) entry URL it lives in a
+ * user-level cache keyed by `sha256(entryUrl)` (see `computeInstallRoot`).
+ * 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
@@ -190,36 +193,24 @@ export class NpmControllerLoader {
       );
     }
     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 installRoot = computeInstallRoot(entryUrlStr);
+
+    // Build the install-root package.json: kernel-runtime deps as `file:` refs
+    // pointing at the kernel-side realpath. Modules declare these names as
+    // `peerDependencies`, so npm/pnpm resolve each controller's `import` to the
+    // single copy provided here — the realm-collapse mechanism that gives
+    // class-identity-sensitive types (today: `Stream`) one constructor across
+    // the kernel/controller boundary.
     const dependencies: Record<string, string> = {};
-    const overrides: Record<string, string> = {};
-    for (const name of runtimeDeps) {
+    for (const name of REALM_COLLAPSE_NAMES) {
       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.
+        // not fatal — the realm-collapse story degrades to "rely on whatever
+        // the package manager picks" for that name. Don't crash the loader.
         continue;
       }
       dependencies[name] = `file:${resolvedPkgRoot}`;
-      overrides[name] = `$${name}`;
     }
 
     const packageJson = {
@@ -227,8 +218,6 @@ export class NpmControllerLoader {
       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");
@@ -405,54 +394,18 @@ export class NpmControllerLoader {
 }
 
 /**
- * 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.
+ * Names of packages whose realpath must be shared between the kernel and every
+ * loaded controller. Each name here becomes a `file:` dep in the install-root
+ * `package.json`, pinned at the kernel's own resolution; controllers declare
+ * these names as `peerDependencies` so npm/pnpm resolves them to that single
+ * copy instead of nesting their own.
+ *
+ * Add a name here if you ship another shared runtime symbol whose `instanceof`
+ * or constructor identity matters across module boundaries. Today the only
+ * such name is `@telorun/sdk` (carries the `Stream` class registered with
+ * `@marcbachmann/cel-js`).
  */
-async function loadRuntimeDeps(): Promise<string[]> {
-  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.`,
-    );
-  }
-  return data.names as string[];
-}
-
-/**
- * Walk up from `from` until the directory contains a `package.json`.
- * Returns null at filesystem root if none found.
- */
-async function walkUpToPackageRoot(from: string): Promise<string | null> {
-  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;
-  }
-}
+const REALM_COLLAPSE_NAMES: ReadonlyArray<string> = ["@telorun/sdk"];
 
 /**
  * Resolve a kernel-runtime dep name to the realpath of its package directory.
@@ -675,35 +628,56 @@ async function readDepSpec(installRoot: string, packageName: string): Promise<st
 }
 
 /**
- * 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")`.
+ * Decide where the per-kernel install root lives for a given entry URL.
+ *
+ * - `file://` URL or bare filesystem path: anchored next to the manifest at
+ *   `<entry-dir>/.telo/npm/`. Same as before — keeps the "install lives with
+ *   the project" story for local development and Docker builds where the
+ *   tree is `COPY`-d into the image.
+ * - `http(s)://` URL: there is no on-disk anchor next to the manifest, so
+ *   the install root lives in a user-level cache keyed by the SHA-256 of
+ *   the entry URL: `<cacheDir>/<hash>/npm/`. Repeat runs of the same URL
+ *   hit the same cache; distinct URLs get isolated trees so two unrelated
+ *   remote apps don't share `node_modules` (different controller versions,
+ *   different realm-collapse pins).
  *
- * 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.
+ *   Cache location, in priority order:
+ *     1. `$TELO_NPM_CACHE_DIR` (explicit override — tests use this to avoid
+ *        polluting the developer's `~/.cache`).
+ *     2. `$XDG_CACHE_HOME/telo/remote` (standard XDG path on Linux).
+ *     3. `<os.homedir()>/.cache/telo/remote` (POSIX fallback / macOS).
+ *
+ * Unrecognised schemes (anything that isn't `file://`, `http://`, or
+ * `https://`) still throw `ControllerEnvMissingError` so the dispatcher can
+ * advance to a non-npm candidate.
  */
-function parseFileUrlOrThrow(entryUrl: string): string {
-  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})`,
-    );
+function computeInstallRoot(entryUrl: string): string {
+  if (entryUrl.startsWith("file://")) {
+    const entryPath = fileURLToPath(entryUrl);
+    return path.join(path.dirname(path.resolve(entryPath)), ".telo", "npm");
   }
-  return entryUrl;
+  const schemeMatch = entryUrl.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):\/\//);
+  if (!schemeMatch) {
+    // Bare filesystem path: same anchor as `file://`.
+    return path.join(path.dirname(path.resolve(entryUrl)), ".telo", "npm");
+  }
+  const scheme = schemeMatch[1].toLowerCase();
+  if (scheme === "http" || scheme === "https") {
+    const cacheBase =
+      process.env.TELO_NPM_CACHE_DIR ||
+      (process.env.XDG_CACHE_HOME
+        ? path.join(process.env.XDG_CACHE_HOME, "telo", "remote")
+        : path.join(os.homedir(), ".cache", "telo", "remote"));
+    return path.join(cacheBase, sha256(entryUrl), "npm");
+  }
+  // Env-missing rather than a hard error: the dispatcher should advance to
+  // the next candidate when a non-npm scheme is paired with a `pkg:cargo`
+  // (or other) fallback.
+  throw new ControllerEnvMissingError(
+    `[telo] entry URL scheme '${schemeMatch[1]}' is not supported by the npm controller ` +
+      `loader. Supported schemes: file://, http://, https://, or a bare filesystem path. ` +
+      `(entryUrl: ${entryUrl})`,
+  );
 }
 
 /**
@@ -954,7 +928,8 @@ export const __testing__ = {
   resolvePackageExportTarget,
   resolveExportTargetValue,
   tryResolveFile,
-  walkUpToPackageRoot,
+  computeInstallRoot,
   EXPORTS_MAX_DEPTH,
   DEFAULT_RESOLVER_CONDITIONS,
+  REALM_COLLAPSE_NAMES,
 };