@telorun/kernel 0.4.0 → 0.5.0

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

@@ -0,0 +1,285 @@
+import { ControllerInstance } 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";
+
+export class NpmControllerLoader {
+  /**
+   * 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>`.
+   */
+  async load(purl: string, baseUri: string): Promise<ControllerInstance> {
+    const [, namespace, name, versionSpec, qualifiers, entry] = PackageURL.parseString(purl);
+
+    const localPath = (qualifiers as any)?.get("local_path");
+    const cacheKey = createHash("sha256").update(purl).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}`);
+        }
+      }
+    } 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 "${purl}": 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,
+    );
+    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);
+    }
+    if (!path.extname(directPath)) {
+      const withJs = `${directPath}.js`;
+      if (await this.pathExists(withJs)) {
+        return withJs;
+      }
+    }
+
+    throw new Error(`Controller entry "${entryValue}" could not be resolved in ${packageRoot}`);
+  }
+
+  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);
+  }
+
+  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;
+        }
+      }
+      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;
+          }
+        }
+      }
+    }
+    return null;
+  }
+
+  private async resolveForRuntime(resolvedPath: string, packageRoot: string): Promise<string> {
+    if (isBun || !resolvedPath.endsWith(".ts")) {
+      return resolvedPath;
+    }
+    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 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;
+    }
+  }
+}

package/src/controller-registry.ts

@@ -1,74 +1,76 @@
-import { ControllerInstance, ResourceDefinition, RuntimeResource } from "@telorun/sdk";
-import * as path from "path";
+import { ControllerInstance, ResourceDefinition, RuntimeError } from "@telorun/sdk";
+
+const DEFAULT_FINGERPRINT = "default";
 
 /**
  * ControllerRegistry: Manages controller loading and dispatch
- * Maps fully-qualified resource kinds to their controller implementations
+ * Maps fully-qualified resource kinds to their controller implementations.
+ *
+ * Controllers are keyed by `(kind, runtimeFingerprint)` so that two
+ * `Telo.Import`s of the same library with different `runtime:` selections
+ * each get their own cached controller instance — the first winner does not
+ * lock out the second. Definitions remain kind-only; only the loaded
+ * controller instance is policy-scoped.
  */
 export class ControllerRegistry {
-  private controllersByKind: Map<string, ControllerInstance> = new Map();
+  private controllersByKind: Map<string, Map<string, ControllerInstance>> = new Map();
   private definitionsByKind: Map<string, ResourceDefinition> = new Map();
-  private controllerLoaders: Map<string, () => Promise<ControllerInstance>> = new Map();
+
   /**
    * Register a controller definition
    */
-  registerDefinition(
-    definition: ResourceDefinition,
-    // baseDir?: string,
-    // namespace?: string | null,
-  ): void {
-    // Construct fully qualified kind: Namespace.Name
-    // Only add namespace if name is not already qualified (doesn't contain a dot)
+  registerDefinition(definition: ResourceDefinition): void {
     const namespace = definition.metadata.module;
-    const baseDir = null;
     const name = definition.metadata.name;
     const kind = namespace && !name.includes(".") ? `${namespace}.${name}` : name;
-
     this.definitionsByKind.set(kind, definition);
-
-    // If definition has controllers, register loader for them
-    if (definition.controllers && definition.controllers.length > 0 && baseDir) {
-      this.registerControllerLoader(kind, definition, baseDir);
-    }
   }
 
   /**
-   * Get a controller instance for a kind
-   * Lazy-loads controller code on first access
-   * Throws if controller not found
+   * Get a controller instance for a (kind, fingerprint) pair. Lookup order:
+   *  1. Exact match for the requested fingerprint (the common path).
+   *  2. The "default" fingerprint — kernel built-ins register here once and
+   *     should be reachable from any module's fingerprinted lookup.
+   *  3. The first registered entry for this kind, regardless of fingerprint
+   *     — handles the case of a root-context resource referencing a kind
+   *     that an import loaded under its own runtime selection.
+   *
+   * Throws `ERR_CONTROLLER_NOT_LOADED` on full miss.
    */
-  getController(kind: string): ControllerInstance {
-    // Return cached instance if available
-    if (this.controllersByKind.has(kind)) {
-      return this.controllersByKind.get(kind)!;
+  getController(kind: string, fingerprint: string = DEFAULT_FINGERPRINT): ControllerInstance {
+    const cached = this.lookup(kind, fingerprint);
+    if (cached) {
+      return cached;
     }
-
-    // Load controller if loader is registered
-    // const loader = this.controllerLoaders.get(kind);
-    // if (loader) {
-    //   const controller = await loader();
-    //   this.controllersByKind.set(kind, controller);
-    //   return controller;
-    // }
-    return {
-      schema: { type: "object", additionalProperties: false },
-    };
-    // throw new Error(`No controller registered for kind: ${kind}`);
+    throw new RuntimeError(
+      "ERR_CONTROLLER_NOT_LOADED",
+      `No controller loaded for kind "${kind}" (runtime fingerprint "${fingerprint}"). The kind's Telo.Definition must init before its controller is consulted.`,
+    );
   }
 
   /**
-   * Safe get - returns undefined if controller not found
+   * Safe get - returns undefined if controller not found. Same fallback
+   * order as `getController`.
    */
-  getControllerOrUndefined(kind: string): ControllerInstance | undefined {
-    // Return cached instance if available
-    if (this.controllersByKind.has(kind)) {
-      return this.controllersByKind.get(kind);
-    }
-    return undefined;
+  getControllerOrUndefined(
+    kind: string,
+    fingerprint: string = DEFAULT_FINGERPRINT,
+  ): ControllerInstance | undefined {
+    return this.lookup(kind, fingerprint);
+  }
+
+  private lookup(kind: string, fingerprint: string): ControllerInstance | undefined {
+    const byFp = this.controllersByKind.get(kind);
+    if (!byFp) return undefined;
+    return (
+      byFp.get(fingerprint) ??
+      byFp.get(DEFAULT_FINGERPRINT) ??
+      byFp.values().next().value
+    );
   }
 
   /**
-   * Check if a controller exists for this kind (definition or directly registered)
+   * Check if any controller exists for this kind (any fingerprint, or just a definition).
    */
   hasController(kind: string): boolean {
     return this.controllersByKind.has(kind) || this.definitionsByKind.has(kind);
@@ -88,29 +90,27 @@ export class ControllerRegistry {
     return Array.from(this.definitionsByKind.keys());
   }
 
-  getControllerKinds(): string[] {
-    return Array.from(this.controllersByKind.keys());
-  }
-
   /**
-   * Create a resource instance using its controller
+   * Distinct kinds with at least one registered controller. Used by the boot
+   * register-hook loop, which fires once per kind regardless of fingerprint.
    */
-  async create(kind: string, resource: RuntimeResource, ctx: any): Promise<any | null> {
-    const controller = this.getController(kind);
-    if (!controller || !controller.create) {
-      return null;
-    }
-    return controller.create(resource, ctx);
+  getControllerKinds(): string[] {
+    return Array.from(this.controllersByKind.keys());
   }
 
   /**
-   * Register a controller for a kind
+   * Register a controller for a (kind, fingerprint). Multiple registrations
+   * for the same kind with different fingerprints coexist; same fingerprint
+   * overwrites the prior entry.
    */
-  registerController(kind: string, controller: ControllerInstance): void {
+  registerController(
+    kind: string,
+    controller: ControllerInstance,
+    fingerprint: string = DEFAULT_FINGERPRINT,
+  ): void {
     if (!this.definitionsByKind.has(kind)) {
       throw new Error(`Cannot register controller for kind ${kind} without definition`);
     }
-    // Ensure controller has schema from definition
     const definition = this.definitionsByKind.get(kind);
     const wrappedController: ControllerInstance = {
       ...controller,
@@ -118,74 +118,11 @@ export class ControllerRegistry {
       inputType: controller.inputType,
       outputType: controller.outputType,
     };
-    this.controllersByKind.set(kind, wrappedController);
-  }
-
-  /**
-   * Private: Register controller loader
-   */
-  private registerControllerLoader(
-    kind: string,
-    definition: ResourceDefinition,
-    moduleDir: string,
-  ): void {
-    const controllerDef = definition.controllers?.[0]; // Use first matching controller for now
-    if (!controllerDef) return;
-
-    this.controllerLoaders.set(kind, async () => {
-      const modulePath = path.resolve(moduleDir, controllerDef.entry);
-      const moduleRuntime = await import(modulePath);
-      const exported = moduleRuntime.default || moduleRuntime.Module || moduleRuntime;
-
-      const registerFn =
-        typeof moduleRuntime.register === "function"
-          ? moduleRuntime.register
-          : typeof exported === "function" && !this.isModuleClass(exported)
-            ? exported
-            : null;
-
-      const createFn =
-        typeof moduleRuntime.create === "function"
-          ? moduleRuntime.create
-          : typeof exported?.create === "function"
-            ? exported.create
-            : null;
-
-      const executeFn =
-        typeof moduleRuntime.execute === "function"
-          ? moduleRuntime.execute
-          : typeof exported?.execute === "function"
-            ? exported.execute
-            : null;
-
-      const compileFn =
-        typeof moduleRuntime.compile === "function"
-          ? moduleRuntime.compile
-          : typeof exported?.compile === "function"
-            ? exported.compile
-            : null;
-
-      if (!registerFn && !executeFn && !createFn && !compileFn) {
-        throw new Error(`Controller for "${kind}" exports no usable handlers`);
-      }
-
-      if (!definition.schema) {
-        throw new Error(`Definition for "${kind}" does not have schema`);
-      }
-
-      return {
-        register: registerFn ?? undefined,
-        create: createFn ?? undefined,
-        execute: executeFn ?? undefined,
-        compile: compileFn ?? undefined,
-        schema: definition.schema,
-      };
-    });
-  }
-
-  private isModuleClass(obj: any): boolean {
-    return (
-      typeof obj === "function" && (obj.name === "Controller" || obj.toString().includes("class"))
-    );
+    let byFp = this.controllersByKind.get(kind);
+    if (!byFp) {
+      byFp = new Map();
+      this.controllersByKind.set(kind, byFp);
+    }
+    byFp.set(fingerprint, wrappedController);
   }
 }

package/src/controllers/module/import-controller.ts

@@ -2,6 +2,7 @@ import { DiagnosticSeverity, StaticAnalyzer } from "@telorun/analyzer";
 import type { ResourceContext, ResourceInstance } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 import { ModuleContext } from "../../module-context.js";
+import { isDefaultPolicy, normalizeRuntime } from "../../runtime-registry.js";
 
 const importAnalysisCache = new Map<
   string,
@@ -24,10 +25,18 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
 
   const moduleSource: string = resource.module ?? resource.source;
 
+  // Resolve relative source paths against the manifest's OWN file URL (stamped onto
+  // `metadata.source` by the loader), not the parent module context's source. When a
+  // Telo.Library imports another library via a relative path, that path is written
+  // relative to the declaring library's file — not relative to whatever root manifest
+  // happens to have imported the chain. Falling back to ctx.moduleContext.source for
+  // manifests that somehow lack a stamped source keeps the old behaviour for edge cases.
+  const base = (resource.metadata?.source as string | undefined) ?? ctx.moduleContext.source;
+
   // Validate the imported module and all its transitive imports before loading for runtime.
   // loadManifests() follows Telo.Import chains so definitions from sub-imports are present,
   // preventing false UNDEFINED_KIND errors for kinds that come from the module's own imports.
-  const resolvedUrl = resolveImportSource(moduleSource, ctx.moduleContext.source);
+  const resolvedUrl = resolveImportSource(moduleSource, base);
   const analysisManifests = await ctx.loadManifests(resolvedUrl);
   const signature = JSON.stringify(analysisManifests);
   const cached = importAnalysisCache.get(resolvedUrl);
@@ -88,6 +97,20 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
     ),
   );
 
+  // Stamp the resolved controller policy on the child only when the import
+  // specifies a `runtime:` field that resolves to something other than the
+  // canonical default. Omitted, `auto`, and any list that normalizes to the
+  // default shape (e.g. `[nodejs, any]` on the Node.js kernel) all leave the
+  // child policy unstamped — they are equivalent forms of "no preference"
+  // and stamping would make them observably distinct from the omitted form
+  // for no behavioral gain.
+  if (resource.runtime !== undefined) {
+    const policy = normalizeRuntime(resource.runtime as string | string[]);
+    if (!isDefaultPolicy(policy)) {
+      (child as ModuleContext).setControllerPolicy(policy);
+    }
+  }
+
   for (const manifest of manifests) {
     child.registerManifest(manifest);
   }
@@ -153,6 +176,12 @@ export const schema = {
     source: { type: "string" },
     variables: { type: "object" },
     secrets: { type: "object" },
+    runtime: {
+      oneOf: [
+        { type: "string" },
+        { type: "array", items: { type: "string" } },
+      ],
+    },
   },
   required: ["metadata", "source"],
   additionalProperties: false,

package/src/controllers/resource-definition/abstract-controller.ts

@@ -0,0 +1,56 @@
+import type {
+  ControllerContext,
+  ResourceContext,
+  ResourceInstance,
+  RuntimeResource,
+} from "@telorun/sdk";
+import { formatAjvErrors, validateResourceAbstract } from "../../manifest-schemas.js";
+
+type ResourceAbstractResource = RuntimeResource & {
+  kind: "Telo.Abstract";
+  metadata: {
+    [key: string]: any;
+    name: string;
+    module?: string;
+  };
+  schema?: Record<string, any>;
+  capability?: string;
+};
+
+/**
+ * Telo.Abstract meta-controller.
+ *
+ * An abstract declares a contract that other definitions may implement via `extends`
+ * (or the legacy `capability: <AbstractKind>` overload). It has no runtime instance
+ * of its own and no controller to load — the `init()` just registers the definition
+ * with the kernel's ControllerRegistry so `getDefinition(<abstractKind>)` returns it
+ * during capability-chain resolution and so `snapshot()` calls from the abstract's
+ * extendedBy children can resolve its schema for runtime validation.
+ */
+class ResourceAbstract implements ResourceInstance {
+  readonly kind: "ResourceAbstract" = "ResourceAbstract";
+
+  constructor(readonly resource: ResourceAbstractResource) {}
+
+  async init(ctx: ResourceContext) {
+    ctx.registerDefinition(this.resource);
+  }
+}
+
+export function register(_ctx: ControllerContext): void {
+  // Abstract is passive — no registration side-effects.
+}
+
+export async function create(resource: any, _ctx: ResourceContext): Promise<ResourceAbstract> {
+  if (!validateResourceAbstract(resource)) {
+    throw new Error(
+      `Invalid Telo.Abstract "${resource.metadata?.name}": ${formatAjvErrors(validateResourceAbstract.errors)}`,
+    );
+  }
+  return new ResourceAbstract(resource as unknown as ResourceAbstractResource);
+}
+
+export const schema = {
+  type: "object",
+  additionalProperties: true,
+};

package/src/controllers/resource-definition/resource-definition-controller.ts

@@ -48,6 +48,7 @@ class ResourceDefinition implements ResourceInstance {
       const controllerInstance = await this.controllerLoader.load(
         this.resource.controllers,
         this.resource.metadata.source,
+        ctx.getControllerPolicy(),
       );
       ctx.emit("ControllerLoaded", { schema: controllerInstance.schema });
       ctx.registerDefinition(this.resource);