@telorun/kernel 0.27.0 → 0.29.0

package/src/controller-loader.ts

@@ -20,6 +20,19 @@ export type ControllerResolveSource =
   | "cargo-build"
   | "bundle";
 
+/**
+ * A controller candidate that has been *resolved* (verified hostable: package
+ * installed / bundle present / crate located) but not yet imported/evaluated.
+ * `importInstance` performs the deferred — and expensive — module load; lazy
+ * controller loading calls it on the kind's first instantiation. `purl`/`source`
+ * are known at resolve time and carried for the load-time events.
+ */
+export interface ResolvedController {
+  purl: string;
+  source: ControllerResolveSource;
+  importInstance: () => Promise<ControllerInstance>;
+}
+
 export type ControllerLoaderEvent =
   | { name: "ControllerLoading"; payload: { purl: string } }
   | {
@@ -151,18 +164,74 @@ export class ControllerLoader {
     throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", aggregated);
   }
 
+  /**
+   * Resolve a controller without importing it: pick the first candidate this
+   * environment can host (same ordering + env-missing fallback as {@link load}),
+   * verify it's present, and return a {@link ResolvedController} whose
+   * `importInstance` defers the actual import/eval. Used by lazy controller
+   * loading so a `Telo.Definition` fails fast at boot when its controller can't
+   * load at all, while the expensive import is paid only on first instantiation.
+   *
+   * Silent by design — no lifecycle events here; the caller emits
+   * ControllerLoading/Loaded around `importInstance` so the events fire when the
+   * load actually happens. A total resolution failure throws (the boot-time
+   * fail-fast), mirroring {@link load}'s aggregated error.
+   */
+  async resolve(
+    purlCandidates: string[],
+    baseUri: string,
+    policy?: ControllerPolicy,
+  ): Promise<ResolvedController> {
+    if (!purlCandidates || purlCandidates.length === 0) {
+      throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", "Missing controller PURL candidates");
+    }
+    const effectivePolicy = policy ?? DEFAULT_POLICY;
+    const ordered = orderCandidates(purlCandidates, effectivePolicy);
+    if (ordered.length === 0) {
+      throw new RuntimeError(
+        "ERR_CONTROLLER_NOT_FOUND",
+        `No controllers match runtime selection [${effectivePolicy.load.join(", ")}]; declared: ${purlCandidates.join(", ")}`,
+      );
+    }
+    const errors: string[] = [];
+    for (const purl of ordered) {
+      try {
+        const { source, importInstance } = await this.dispatchResolveOne(purl, baseUri);
+        return { purl, source, importInstance };
+      } catch (err) {
+        if (err instanceof ControllerEnvMissingError) {
+          errors.push(`${purl}: ${err.message}`);
+          continue;
+        }
+        throw err;
+      }
+    }
+    throw new RuntimeError(
+      "ERR_CONTROLLER_NOT_FOUND",
+      `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`,
+    );
+  }
+
   private async dispatchOne(
     purl: string,
     baseUri: string,
   ): Promise<{ instance: ControllerInstance; source: ControllerResolveSource }> {
+    const { source, importInstance } = await this.dispatchResolveOne(purl, baseUri);
+    return { instance: await importInstance(), source };
+  }
+
+  private async dispatchResolveOne(
+    purl: string,
+    baseUri: string,
+  ): Promise<{ source: ControllerResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     if (purl.startsWith("pkg:npm")) {
-      return this.npmLoader.load(purl, baseUri);
+      return this.npmLoader.resolve(purl, baseUri);
     }
     if (purl.startsWith("pkg:cargo")) {
-      return this.napiLoader.load(purl, baseUri);
+      return this.napiLoader.resolve(purl, baseUri);
     }
     if (purl.startsWith("pkg:telo")) {
-      return this.bundleLoader.load(purl, baseUri);
+      return this.bundleLoader.resolve(purl, baseUri);
     }
     throw new ControllerEnvMissingError(`Unsupported PURL scheme: ${purl}`);
   }

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

@@ -141,6 +141,20 @@ export class BundleControllerLoader {
     purl: string,
     baseUri: string,
   ): Promise<{ instance: ControllerInstance; source: ControllerResolveSource }> {
+    const { source, importInstance } = await this.resolve(purl, baseUri);
+    return { instance: await importInstance(), source };
+  }
+
+  /**
+   * Resolve without importing: parse + validate the PURL, confirm the bundle
+   * file exists and its format is hostable, and ensure the realm symlinks — all
+   * cheap, fail-fast checks — but defer the bundle `import()` (the eval cost)
+   * into the returned `importInstance` thunk. Used by lazy controller loading.
+   */
+  async resolve(
+    purl: string,
+    baseUri: string,
+  ): Promise<{ source: ControllerResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     let parsed: PackageURL;
     try {
       parsed = PackageURL.fromString(purl);
@@ -196,26 +210,31 @@ export class BundleControllerLoader {
     // importing the bundle, so authors write normal imports.
     await ensureRealmSymlinks(path.dirname(absFile));
 
-    // A broken bundle (syntax / failed import) is a real user-code failure —
-    // let it propagate rather than masking it as env-missing.
-    const mod = (await import(pathToFileURL(absFile).href)) as Record<string, ControllerInstance>;
     const fragment = parsed.subpath;
-    // Distinguish "no such export" from "export isn't a controller" so the error
-    // points at the actual problem (mirrors the napi loader's project()).
-    if (fragment && !(fragment in mod)) {
-      throw new RuntimeError(
-        "ERR_CONTROLLER_INVALID",
-        `Bundled controller "${purl}": module "${absFile}" has no export named "${fragment}"`,
-      );
-    }
-    const instance = fragment ? mod[fragment] : (mod as unknown as ControllerInstance);
-    if (!instance || (!instance.create && !instance.register)) {
-      throw new RuntimeError(
-        "ERR_CONTROLLER_INVALID",
-        `Bundled controller "${purl}" exports neither create() nor register()` +
-          (fragment ? ` at fragment "#${fragment}"` : ""),
-      );
-    }
-    return { instance, source: "bundle" };
+    return {
+      source: "bundle",
+      importInstance: async () => {
+        // A broken bundle (syntax / failed import) is a real user-code failure —
+        // let it propagate rather than masking it as env-missing.
+        const mod = (await import(pathToFileURL(absFile).href)) as Record<string, ControllerInstance>;
+        // Distinguish "no such export" from "export isn't a controller" so the
+        // error points at the actual problem (mirrors the napi loader's project()).
+        if (fragment && !(fragment in mod)) {
+          throw new RuntimeError(
+            "ERR_CONTROLLER_INVALID",
+            `Bundled controller "${purl}": module "${absFile}" has no export named "${fragment}"`,
+          );
+        }
+        const instance = fragment ? mod[fragment] : (mod as unknown as ControllerInstance);
+        if (!instance || (!instance.create && !instance.register)) {
+          throw new RuntimeError(
+            "ERR_CONTROLLER_INVALID",
+            `Bundled controller "${purl}" exports neither create() nor register()` +
+              (fragment ? ` at fragment "#${fragment}"` : ""),
+          );
+        }
+        return instance;
+      },
+    };
   }
 }

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

@@ -123,6 +123,21 @@ export class NapiControllerLoader {
    * though all exports come from one linked dylib.
    */
   async load(purl: string, baseUri: string): Promise<NapiLoadResult> {
+    const { source, importInstance } = await this.resolve(purl, baseUri);
+    return { instance: await importInstance(), source };
+  }
+
+  /**
+   * Resolve without building: validate the PURL and confirm the crate's
+   * `local_path` exists (the fail-fast checks), then defer the cargo build +
+   * dylib load — the expensive part — into the returned `importInstance` thunk.
+   * A cache hit resolves instantly. Used by lazy controller loading so the build
+   * is paid on the kind's first instantiation, not at boot.
+   */
+  async resolve(
+    purl: string,
+    baseUri: string,
+  ): Promise<{ source: NapiResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     const [, , name, , qualifiers, entry] = PackageURL.parseString(purl);
     const localPath = (qualifiers as any)?.get("local_path");
 
@@ -149,38 +164,44 @@ export class NapiControllerLoader {
     // 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 { instance: project(cached, entry, cratePath), source: "cache" };
+    if (_napiModuleCache.has(cacheKey)) {
+      return {
+        source: "cache",
+        importInstance: async () => project(_napiModuleCache.get(cacheKey), entry, cratePath),
+      };
     }
 
-    // Concurrent callers for the same crate await one shared build. They
-    // report `local` (not `cache`): they paid the same wall-clock cost as
-    // the originator, just by sharing one cargo invocation rather than
-    // running their own. Reporting `cache` here would mislead metrics/event
-    // consumers into thinking it was a sub-ms hit.
-    const existingInFlight = _napiInFlight.get(cacheKey);
-    if (existingInFlight) {
-      const { rawModule } = await existingInFlight;
-      return { instance: project(rawModule, entry, cratePath), source: "local" };
-    }
-
-    const buildPromise = this.buildAndLoad(cratePath, name ?? "", cacheKey);
-    _napiInFlight.set(cacheKey, buildPromise);
-    let rawModule: any;
-    let nodePath: string;
-    try {
-      ({ rawModule, nodePath } = await buildPromise);
-    } finally {
-      _napiInFlight.delete(cacheKey);
-    }
-    // `local` rather than `cargo-build` because the only mode currently
-    // wired up is `local_path` dev-mode — cargo's incremental cache means
-    // every run after the first is ~50ms of cargo-startup with no real
-    // compilation, conceptually the same as the npm `local_path` branch
-    // that just imports source already on disk. Distribution mode (when
-    // implemented) will return `cargo-build` from its own branch.
-    return { instance: project(rawModule, entry, nodePath), source: "local" };
+    // `local` rather than `cargo-build` because the only mode currently wired up
+    // is `local_path` dev-mode — see the original note below. The thunk re-checks
+    // the module cache and the in-flight gate because resolve() and the deferred
+    // import can be separated in time (another instantiation may have built the
+    // crate in between).
+    const crateName = name ?? "";
+    const build = this.buildAndLoad.bind(this);
+    return {
+      source: "local",
+      importInstance: async () => {
+        const cached = _napiModuleCache.get(cacheKey);
+        if (cached) return project(cached, entry, cratePath);
+        // Concurrent callers for the same crate await one shared build, sharing
+        // one cargo invocation rather than each running their own.
+        const existingInFlight = _napiInFlight.get(cacheKey);
+        if (existingInFlight) {
+          const { rawModule } = await existingInFlight;
+          return project(rawModule, entry, cratePath);
+        }
+        const buildPromise = build(cratePath, crateName, cacheKey);
+        _napiInFlight.set(cacheKey, buildPromise);
+        let rawModule: any;
+        let nodePath: string;
+        try {
+          ({ rawModule, nodePath } = await buildPromise);
+        } finally {
+          _napiInFlight.delete(cacheKey);
+        }
+        return project(rawModule, entry, nodePath);
+      },
+    };
   }
 
   private async buildAndLoad(

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

@@ -178,6 +178,20 @@ export class NpmControllerLoader {
   }
 
   async load(purl: string, baseUri: string): Promise<NpmLoadResult> {
+    const { source, importInstance } = await this.resolve(purl, baseUri);
+    return { instance: await importInstance(), source };
+  }
+
+  /**
+   * Resolve without importing: materialize the install root and install/verify
+   * the package (the cheap, cache-hit-fast part that fails fast if the package
+   * is absent), but defer `loadFromInstall` — the actual `import()`/eval, which
+   * is the expensive cold-start cost — into the returned `importInstance` thunk.
+   */
+  async resolve(
+    purl: string,
+    baseUri: string,
+  ): Promise<{ source: NpmResolveSource; importInstance: () => Promise<ControllerInstance> }> {
     const parsed = PackageURL.fromString(purl);
     if (!parsed.name) {
       throw new Error(`Invalid PURL '${purl}': missing package name`);
@@ -197,8 +211,11 @@ export class NpmControllerLoader {
       resolved.kind,
       version,
     );
-    const instance = await loadFromInstall(installRoot, alias, parsed.subpath ?? null, purl);
-    return { instance, source };
+    const subpath = parsed.subpath ?? null;
+    return {
+      source,
+      importInstance: () => loadFromInstall(installRoot, alias, subpath, purl),
+    };
   }
 
   /**

package/src/controller-registry.ts

@@ -12,9 +12,21 @@ const DEFAULT_FINGERPRINT = "default";
  * lock out the second. Definitions remain kind-only; only the loaded
  * controller instance is policy-scoped.
  */
+/**
+ * A controller whose definition has been resolved but whose module is not yet
+ * imported. `load()` performs the import + `registerController` (firing the
+ * controller's `register()` hook); `loading` single-flights concurrent
+ * instantiations of the same kind through one import.
+ */
+interface LazyControllerEntry {
+  load: () => Promise<void>;
+  loading?: Promise<void>;
+}
+
 export class ControllerRegistry {
   private controllersByKind: Map<string, Map<string, ControllerInstance>> = new Map();
   private definitionsByKind: Map<string, ResourceDefinition> = new Map();
+  private lazyByKind: Map<string, Map<string, LazyControllerEntry>> = new Map();
 
   /**
    * Register a controller definition
@@ -143,4 +155,55 @@ export class ControllerRegistry {
     }
     byFp.set(fingerprint, wrappedController);
   }
+
+  /**
+   * Register a deferred controller for a (kind, fingerprint). The definition's
+   * metadata is already registered (so analysis/refs work); the controller
+   * module itself is imported lazily by {@link takeLazyController} on the kind's
+   * first instantiation. Mirrors `registerController`'s fingerprint keying.
+   */
+  registerLazyController(
+    kind: string,
+    fingerprint: string,
+    load: () => Promise<void>,
+  ): void {
+    if (!this.definitionsByKind.has(kind)) {
+      throw new Error(`Cannot register lazy controller for kind ${kind} without definition`);
+    }
+    let byFp = this.lazyByKind.get(kind);
+    if (!byFp) {
+      byFp = new Map();
+      this.lazyByKind.set(kind, byFp);
+    }
+    byFp.set(fingerprint, { load });
+  }
+
+  /**
+   * Drive the deferred import for a (kind, fingerprint) if one is registered,
+   * single-flighting concurrent callers through the same import. Returns true
+   * when a lazy entry existed (after its `load()` has completed and the
+   * controller is registered), false when there is none — letting the caller
+   * fall through to its existing "no controller" handling. Same fingerprint
+   * fallback order as `getControllerOrUndefined`.
+   */
+  async takeLazyController(
+    kind: string,
+    fingerprint: string = DEFAULT_FINGERPRINT,
+  ): Promise<boolean> {
+    const byFp = this.lazyByKind.get(kind);
+    if (!byFp) return false;
+    const entry =
+      byFp.get(fingerprint) ?? byFp.get(DEFAULT_FINGERPRINT) ?? byFp.values().next().value;
+    if (!entry) return false;
+    if (!entry.loading) {
+      // Reset on failure so a later instantiation re-attempts and re-surfaces
+      // the error rather than awaiting a cached rejection forever.
+      entry.loading = entry.load().catch((err) => {
+        entry.loading = undefined;
+        throw err;
+      });
+    }
+    await entry.loading;
+    return true;
+  }
 }

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

@@ -46,30 +46,63 @@ class ResourceDefinition implements ResourceInstance {
       );
       return;
     }
-    // The loader owns ControllerLoading / ControllerLoaded / ControllerLoadFailed
-    // emission so it can fire one event per attempted candidate (env-missing
-    // fallback chains), and so the payload can include the actually-picked PURL,
-    // which branch resolved it (`source`), and timing — none of which are known
-    // here at the call site.
     const loader = new ControllerLoader({
-      emit: (e) => ctx.emit(e.name, e.payload),
       entryUrl: ctx.getEntryUrl(),
       installRoot: ctx.getInstallRoot(),
     });
-    const controllerInstance = await loader.load(
+    // Eager resolve — verify the controller is hostable now (so a broken
+    // `controllers:` candidate fails fast at boot), but defer the expensive
+    // import/eval and the controller's `register()` to the kind's first
+    // instantiation. Definitions whose kind is never instantiated never import.
+    const resolved = await loader.resolve(
       this.resource.controllers,
       this.resource.metadata.source,
       ctx.getControllerPolicy(),
     );
     ctx.registerDefinition(this.resource);
-    await ctx.registerController(
-      this.resource.metadata.module,
-      this.resource.metadata.name,
-      controllerInstance,
+
+    const moduleName = this.resource.metadata.module;
+    const kindName = this.resource.metadata.name;
+    // Emitted here (not in the loader) so ControllerLoading / ControllerLoaded /
+    // ControllerLoadFailed — and the import duration — surface when the load
+    // actually happens (first instantiation), with the resolved PURL + source.
+    (ctx as unknown as LazyControllerHost).registerLazyController(
+      moduleName,
+      kindName,
+      async () => {
+        await ctx.emit("ControllerLoading", { purl: resolved.purl });
+        const startedAt = Date.now();
+        const instance = await resolved.importInstance().catch(async (err) => {
+          await ctx.emit("ControllerLoadFailed", {
+            purl: resolved.purl,
+            error: err instanceof Error ? err.message : String(err),
+          });
+          throw err;
+        });
+        await ctx.registerController(moduleName, kindName, instance);
+        await ctx.emit("ControllerLoaded", {
+          purl: resolved.purl,
+          source: resolved.source,
+          durationMs: Date.now() - startedAt,
+        });
+      },
     );
   }
 }
 
+/**
+ * Kernel-internal hook the concrete `ResourceContextImpl` exposes for lazy
+ * controller loading — deliberately off the public SDK `ResourceContext`
+ * surface, since only this controller uses it.
+ */
+interface LazyControllerHost {
+  registerLazyController(
+    moduleName: string,
+    kindName: string,
+    load: () => Promise<void>,
+  ): void;
+}
+
 export function register(ctx: ControllerContext): void {
   // ResourceDefinition is a passive resource - no registration needed
 }

package/src/kernel.ts

@@ -112,6 +112,10 @@ export class Kernel implements IKernel {
   private rootContext!: ModuleContext;
   private staticManifests: ResourceManifest[] = [];
   private _entryUrl?: string;
+  /** Root Application `ports:` resolved in `load()` — integer + declared protocol
+   *  per name. Surfaced via {@link getResolvedPorts} so a host can advertise where
+   *  the running app is reachable. */
+  private _resolvedPorts: Array<{ name: string; port: number; protocol: "tcp" | "udp" }> = [];
   /** The `.telo` cache root for this load, resolved once in `load()` and
    *  threaded to the validator, analysis stamp, and npm install root. */
   private _cacheRoot?: string | null;
@@ -161,6 +165,21 @@ export class Kernel implements IKernel {
     await controllerInstance.register?.(this.createControllerContext(`${moduleName}.${kindName}`));
   }
 
+  /**
+   * Register a deferred controller. The definition is already registered; the
+   * controller module is imported (and `register()` fired, via the `load` thunk
+   * calling back into `registerController`) only on the kind's first
+   * instantiation — see `_createInstance` / `ControllerRegistry.takeLazyController`.
+   */
+  registerLazyController(
+    moduleName: string,
+    kindName: string,
+    fingerprint: string,
+    load: () => Promise<void>,
+  ): void {
+    this.controllers.registerLazyController(`${moduleName}.${kindName}`, fingerprint, load);
+  }
+
   /**
    * Register a resource definition with the controller registry
    */
@@ -509,9 +528,27 @@ export class Kernel implements IKernel {
       if (Object.keys(ports).length > 0) {
         this.rootContext.setPorts(ports);
       }
+      const portDecls = (rootApplicationManifest as { ports?: Record<string, { protocol?: string }> })
+        .ports ?? {};
+      this._resolvedPorts = Object.entries(ports).map(([name, port]) => ({
+        name,
+        port,
+        protocol: portDecls[name]?.protocol === "udp" ? "udp" : "tcp",
+      }));
     }
   }
 
+  /**
+   * Resolved inbound ports from the root Application's `ports:` block, available
+   * after {@link load}. Each carries the resolved integer and its declared
+   * protocol; empty when the root declares no ports (or isn't an Application).
+   * Surfaced so a host (e.g. the CLI inspection endpoint) can tell the debug UI
+   * where the running app is reachable.
+   */
+  getResolvedPorts(): ReadonlyArray<{ name: string; port: number; protocol: "tcp" | "udp" }> {
+    return this._resolvedPorts;
+  }
+
   /**
    * Initialize every resource declared in the manifest. Does not run targets
    * and does not wait — returns as soon as the kernel is ready to accept
@@ -880,7 +917,16 @@ export class Kernel implements IKernel {
     const resolvedKind = (findEnclosingModule(evalContext) ?? this.rootContext).resolveKind(kind);
 
     const fingerprint = policyFingerprint(findEnclosingPolicy(evalContext));
-    const controller = this.controllers.getControllerOrUndefined(resolvedKind, fingerprint);
+    let controller = this.controllers.getControllerOrUndefined(resolvedKind, fingerprint);
+    if (!controller) {
+      // Lazy controller loading: the kind's Telo.Definition registered a deferred
+      // controller (resolved but not imported). Import + register it now, on this
+      // first instantiation, then re-resolve. A kind with no lazy entry (abstract,
+      // or genuinely unknown) falls through to the error below unchanged.
+      if (await this.controllers.takeLazyController(resolvedKind, fingerprint)) {
+        controller = this.controllers.getControllerOrUndefined(resolvedKind, fingerprint);
+      }
+    }
     if (!controller) {
       const kindInfo =
         resolvedKind !== kind ? `'${kind}' (resolved to '${resolvedKind}')` : `'${kind}'`;

package/src/resource-context.ts

@@ -332,6 +332,21 @@ export class ResourceContextImpl implements ResourceContext {
     await this.kernel.registerController(moduleName, kindName, controllerInstance, fingerprint);
   }
 
+  /**
+   * Register a deferred controller under the declaring module's policy
+   * fingerprint (same keying as `registerController`). Internal to the kernel's
+   * lazy controller loading — not part of the public SDK `ResourceContext`
+   * surface; the only caller is the `Telo.Definition` controller.
+   */
+  registerLazyController(
+    moduleName: string,
+    kindName: string,
+    load: () => Promise<void>,
+  ): void {
+    const fingerprint = policyFingerprint(this.moduleContext.getControllerPolicy());
+    this.kernel.registerLazyController(moduleName, kindName, fingerprint, load);
+  }
+
   registerDefinition(def: any) {
     this.kernel.registerResourceDefinition(def);
   }