@telorun/kernel 0.9.2 → 0.11.0

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

@@ -47,6 +47,7 @@ class ResourceDefinition implements ResourceInstance {
     // here at the call site.
     const loader = new ControllerLoader({
       emit: (e) => ctx.emit(e.name, e.payload),
+      entryUrl: ctx.getEntryUrl(),
     });
     const controllerInstance = await loader.load(
       this.resource.controllers,

package/src/index.ts

@@ -2,6 +2,12 @@ export { ControllerLoader } from "./controller-loader.js";
 export { ControllerRegistry } from "./controller-registry.js";
 export { EvaluationContext } from "./evaluation-context.js";
 export { LocalFileSource } from "./manifest-sources/local-file-source.js";
+export {
+  LocalManifestCacheSource,
+  cachePathForCanonical,
+  resolveEntryDir,
+  writeManifestCache,
+} from "./manifest-sources/local-manifest-cache-source.js";
 export { MemorySource } from "./manifest-sources/memory-source.js";
 export { EventStream } from "./event-stream.js";
 export { ExecutionContext } from "./execution-context.js";

package/src/kernel.ts

@@ -1,5 +1,7 @@
 import {
   AnalysisRegistry,
+  flattenForAnalyzer,
+  flattenLoadedModule,
   isModuleKind,
   Loader,
   StaticAnalyzer,
@@ -48,6 +50,24 @@ function findEnclosingPolicy(ctx: IEvaluationContext): ControllerPolicy | undefi
   return findEnclosingModule(ctx)?.getControllerPolicy();
 }
 
+function throwInvalidState(operation: string, reason: string): never {
+  throw new RuntimeError(
+    "ERR_KERNEL_STATE_INVALID",
+    `Cannot ${operation}(): ${reason}`,
+  );
+}
+
+function parseRef(ref: string): { kind: string; name: string } {
+  const lastDot = ref.lastIndexOf(".");
+  if (lastDot <= 0 || lastDot === ref.length - 1) {
+    throw new RuntimeError(
+      "ERR_INVALID_VALUE",
+      `Invalid resource reference '${ref}': expected '<Kind>.<Name>' (e.g. 'Http.Server.Main') or pass { kind, name } directly.`,
+    );
+  }
+  return { kind: ref.slice(0, lastDot), name: ref.slice(lastDot + 1) };
+}
+
 export interface KernelOptions {
   stdin?: NodeJS.ReadableStream;
   stdout?: NodeJS.WritableStream;
@@ -96,6 +116,13 @@ export class Kernel implements IKernel {
   private readonly sharedSchemaValidator = new SchemaValidator();
   private rootContext!: ModuleContext;
   private staticManifests: ResourceManifest[] = [];
+  private _entryUrl?: string;
+  // Lifecycle state — guards boot/runTargets/teardown/invoke transitions.
+  // teardown() is the only idempotent method; everything else throws on misuse.
+  private _bootCalled = false;
+  private _isBooted = false;
+  private _targetsRan = false;
+  private _isTornDown = false;
 
   readonly stdin: NodeJS.ReadableStream;
   readonly stdout: NodeJS.WritableStream;
@@ -140,12 +167,15 @@ export class Kernel implements IKernel {
     this.registry.registerDefinition(definition);
   }
 
-  loadModule(url: string, options?: LoadOptions): Promise<ResourceManifest[]> {
-    return this.loader.loadModule(url, options);
+  async loadModule(url: string, options?: LoadOptions): Promise<ResourceManifest[]> {
+    const lm = await this.loader.loadModule(url, options);
+    return flattenLoadedModule(lm);
   }
 
-  loadManifests(url: string): Promise<ResourceManifest[]> {
-    return this.loader.loadManifests(url);
+  async loadManifests(url: string): Promise<ResourceManifest[]> {
+    const graph = await this.loader.loadGraph(url);
+    if (graph.errors.length > 0) throw graph.errors[0].error;
+    return flattenForAnalyzer(graph);
   }
 
   /** Returns the live analysis registry backed by this kernel's known definitions and aliases.
@@ -194,6 +224,7 @@ export class Kernel implements IKernel {
    */
   async load(url: string): Promise<void> {
     const sourceUrl = await this.loader.resolveEntryPoint(url);
+    this._entryUrl = sourceUrl;
     this.rootContext = new ModuleContext(
       sourceUrl,
       {},
@@ -218,7 +249,11 @@ export class Kernel implements IKernel {
 
     // Static analysis pre-flight: validates schemas and invocation context compatibility.
     // All errors are fatal — kernel does not start if analysis fails.
-    const staticManifests = await this.loader.loadManifests(sourceUrl);
+    const analysisGraph = await this.loader.loadGraph(sourceUrl);
+    if (analysisGraph.errors.length > 0) {
+      throw analysisGraph.errors[0].error;
+    }
+    const staticManifests = flattenForAnalyzer(analysisGraph);
     this.staticManifests = staticManifests;
 
     // Register module identities for x-telo-ref resolution (Phase 3 prerequisite).
@@ -256,8 +291,11 @@ export class Kernel implements IKernel {
       );
     }
 
-    // Load runtime configuration — root module gets access to host env
-    const allManifests = await this.loader.loadModule(sourceUrl, { compile: true });
+    // Load runtime configuration — root module gets access to host env.
+    // Imports are loaded separately via the import-controller; this load is
+    // entry-only with compile-time CEL.
+    const lm = await this.loader.loadModule(sourceUrl, { compile: true });
+    const allManifests = flattenLoadedModule(lm);
 
     // Phase 2: normalize inline resources — extract inline values from x-telo-ref slots
     // into first-class named manifests and replace them in-place with {kind, name} references.
@@ -278,9 +316,25 @@ export class Kernel implements IKernel {
   }
 
   /**
-   * Phase 2: Start - Initialize resources
+   * 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
+   * `invoke()` calls.
+   *
+   * Throws ERR_KERNEL_STATE_INVALID if `load()` was not called first, on
+   * second call, or after teardown.
    */
-  async start(): Promise<void> {
+  async boot(): Promise<void> {
+    if (this._isTornDown) {
+      throwInvalidState("boot", "kernel has been torn down");
+    }
+    if (this._bootCalled) {
+      throwInvalidState("boot", "boot() already called");
+    }
+    if (this._entryUrl === undefined) {
+      throwInvalidState("boot", "load() has not been called");
+    }
+    this._bootCalled = true;
+
     // Call register hooks for controllers actually loaded at this point (built-ins).
     // User-module kinds load their controllers during Phase 3 (Telo.Definition.init),
     // and registerController() fires their register hook there.
@@ -321,25 +375,103 @@ export class Kernel implements IKernel {
       this.rootContext.setInitOrder(order);
     }
 
-    // Initialize resources
+    await this.rootContext.initializeResources();
+    await this.eventBus.emit("Kernel.Initialized", {});
+
+    this._isBooted = true;
+  }
+
+  /**
+   * Run the manifest's `targets` (Telo.Service / Telo.Runnable instances).
+   * Emits Kernel.Starting before, Kernel.Started after.
+   *
+   * Throws ERR_KERNEL_STATE_INVALID if called before `boot()` completes, after
+   * teardown, or a second time.
+   */
+  async runTargets(): Promise<void> {
+    if (this._isTornDown) {
+      throwInvalidState("runTargets", "kernel has been torn down");
+    }
+    if (!this._isBooted) {
+      throwInvalidState("runTargets", "boot() has not completed");
+    }
+    if (this._targetsRan) {
+      throwInvalidState("runTargets", "runTargets() already called");
+    }
+    this._targetsRan = true;
+
+    await this.eventBus.emit("Kernel.Starting", {});
+    await this.rootContext.runTargets();
+    await this.eventBus.emit("Kernel.Started", {});
+  }
+
+  /**
+   * Tear down every initialized resource. Emits Kernel.Stopping before,
+   * Kernel.Stopped after. Idempotent — second call is a no-op (does not
+   * re-emit). Tolerates partial state — a boot() that threw mid-init still
+   * cleans up whichever resources had initialized.
+   */
+  async teardown(): Promise<void> {
+    if (this._isTornDown) return;
+    this._isTornDown = true;
+
+    await this.eventBus.emit("Kernel.Stopping", {});
+    if (this.rootContext) {
+      await this.rootContext.teardownResources();
+    }
+    await this.eventBus.emit("Kernel.Stopped", { exitCode: this._exitCode });
+  }
+
+  /**
+   * Convenience: boot → runTargets → waitForIdle → teardown. The try wraps
+   * boot() and runTargets() too — init-time failures still drive teardown and
+   * still emit Kernel.Stopping / Kernel.Stopped, matching pre-split semantics.
+   */
+  async start(): Promise<void> {
     try {
-      await this.rootContext.initializeResources();
-      await this.eventBus.emit("Kernel.Initialized", {});
-      await this.eventBus.emit("Kernel.Starting", {});
-      await this.rootContext.runTargets();
-      await this.eventBus.emit("Kernel.Started", {});
+      await this.boot();
+      await this.runTargets();
       await this.waitForIdle();
     } finally {
-      await this.eventBus.emit("Kernel.Stopping", {});
-      await this.rootContext.teardownResources();
-      await this.eventBus.emit("Kernel.Stopped", { exitCode: this._exitCode });
+      await this.teardown();
     }
   }
 
+  /**
+   * Invoke a Telo.Invocable resource by `<kind>.<name>` (dot-form) or
+   * `{ kind, name }`. Resolves through the root module context, so the same
+   * dispatch, error path, and event emission that controller-to-controller
+   * invokes use apply here too.
+   */
+  async invoke<TInputs = any, TOutput = any>(
+    ref: string | { kind: string; name: string },
+    inputs: TInputs,
+  ): Promise<TOutput> {
+    if (this._isTornDown) {
+      throwInvalidState("invoke", "kernel has been torn down");
+    }
+    if (!this._isBooted) {
+      throwInvalidState("invoke", "boot() has not completed");
+    }
+    const parsed = typeof ref === "string" ? parseRef(ref) : ref;
+    return (await this.rootContext.invoke(parsed.kind, parsed.name, inputs)) as TOutput;
+  }
+
   async emitRuntimeEvent(event: string, payload?: any): Promise<void> {
     await this.eventBus.emit(event, payload);
   }
 
+  /**
+   * URL of the entry manifest passed to `load()`, or `undefined` before
+   * `load()` has been called. Used by controllers and the controller-loader
+   * to anchor per-manifest install roots so every resource in the process
+   * shares a single `node_modules` tree (and therefore one realpath for
+   * `@telorun/sdk`).
+   */
+  getEntryUrl(): string | undefined {
+    return this._entryUrl;
+  }
+
   get exitCode(): number {
     return this._exitCode;
   }
@@ -383,11 +515,14 @@ export class Kernel implements IKernel {
   }
 
   /**
-   * Force-resolve waitForIdle() regardless of active holds.
-   * Used for graceful shutdown when external signals (e.g. SIGINT) should
-   * bypass resource holds and proceed directly to teardown.
+   * Force-resolve any pending `waitForIdle()` even when holds are still active.
+   * Used by external signal handlers (SIGINT/SIGTERM) to unblock graceful exit
+   * so `start()`'s waitForIdle returns and its finally clause runs `teardown()`.
+   *
+   * Does not tear down on its own — call `teardown()` directly if you're not
+   * inside `start()`.
    */
-  shutdown(): void {
+  forceIdle(): void {
     const resolvers = this.idleResolvers.splice(0);
     for (const resolve of resolvers) resolve();
   }

package/src/manifest-sources/local-manifest-cache-source.ts

@@ -0,0 +1,256 @@
+import type { LoadedGraph, ManifestSource } from "@telorun/analyzer";
+import { createHash } from "crypto";
+import { statSync } from "fs";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+
+const CACHE_SUBDIR = ".telo/manifests";
+const HTTP_NAMESPACE = "__http";
+const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
+const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
+const QUERY_HASH_LENGTH = 12;
+
+/** Verify that `candidate` resolves to a path under `root`. Returns the
+ *  candidate path on success, `null` when any segment escapes the root.
+ *  Guards against `..` segments inside module refs or HTTP pathnames. */
+function joinUnder(root: string, ...segments: string[]): string | null {
+  if (segments.some((s) => s === "")) return null;
+  const candidate = path.join(root, ...segments);
+  const resolved = path.resolve(candidate);
+  const resolvedRoot = path.resolve(root);
+  if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
+    return null;
+  }
+  return candidate;
+}
+
+/** Mirror `HttpSource.read`'s `fetchUrl` derivation: when the URL does not
+ *  already point at a YAML file, append `/telo.yaml`. Used by both the
+ *  reader and writer so a raw import URL and the canonical source it
+ *  resolves to map to the same cache path. */
+function normalizePathname(url: string, parsed: URL): string {
+  let pathname = parsed.pathname;
+  if (!url.includes(".yaml")) {
+    pathname = pathname.endsWith("/")
+      ? `${pathname}${DEFAULT_MANIFEST_FILENAME}`
+      : `${pathname}/${DEFAULT_MANIFEST_FILENAME}`;
+  }
+  return pathname;
+}
+
+/** Compute a short hash of `search + hash` so two URLs that differ only in
+ *  query / fragment do not collide at the same cache path. Inserted before
+ *  the final extension so the filename stays readable. */
+function disambiguatePath(pathname: string, search: string, hash: string): string {
+  if (!search && !hash) return pathname;
+  const digest = createHash("sha256")
+    .update(search + hash)
+    .digest("hex")
+    .slice(0, QUERY_HASH_LENGTH);
+  const ext = path.extname(pathname);
+  const base = pathname.slice(0, pathname.length - ext.length);
+  return `${base}.${digest}${ext}`;
+}
+
+/** Single source of truth for URL → cache path. Used identically by the
+ *  reader (cache lookup) and writer (install-time persistence). For any
+ *  given import URL — registry ref, direct registry URL, or arbitrary
+ *  HTTP — both sides land on the same file.
+ *
+ *  Returns `null` for unsupported URLs (file://, memory://, relative paths)
+ *  or for path-traversal attempts that would escape `cacheRoot`. */
+function cachePathForUrl(
+  url: string,
+  cacheRoot: string,
+  registryUrl: string,
+): string | null {
+  const trimmedRegistry = registryUrl.replace(/\/+$/, "");
+
+  // 1. Registry ref form: namespace/name@version
+  if (
+    !url.startsWith("http://") &&
+    !url.startsWith("https://") &&
+    !url.startsWith("/") &&
+    !url.startsWith(".") &&
+    !url.startsWith("file://") &&
+    !url.startsWith("memory://") &&
+    url.includes("@") &&
+    url.includes("/")
+  ) {
+    const atIdx = url.lastIndexOf("@");
+    if (atIdx <= 0 || atIdx === url.length - 1) return null;
+    const modulePath = url.slice(0, atIdx);
+    if (!modulePath.includes("/")) return null;
+    const version = url.slice(atIdx + 1).replace(/^v/, "");
+    if (!version) return null;
+    return joinUnder(cacheRoot, modulePath, version, DEFAULT_MANIFEST_FILENAME);
+  }
+
+  // 2. HTTP(S) URL — could be a direct registry URL or arbitrary external.
+  if (url.startsWith("http://") || url.startsWith("https://")) {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return null;
+    }
+    const pathname = normalizePathname(url, parsed);
+
+    // 2a. URL is on the configured registry, with no query/fragment:
+    //     fold into the registry layout so the writer that received a
+    //     registry-ref canonical and the reader that sees a direct URL
+    //     both resolve to the same file.
+    const normalizedUrl = `${parsed.protocol}//${parsed.host}${pathname}`;
+    if (
+      !parsed.search &&
+      !parsed.hash &&
+      (normalizedUrl === trimmedRegistry || normalizedUrl.startsWith(`${trimmedRegistry}/`))
+    ) {
+      const rel = normalizedUrl.slice(trimmedRegistry.length + 1);
+      if (!rel) return null;
+      return joinUnder(cacheRoot, ...rel.split("/"));
+    }
+
+    // 2b. Arbitrary HTTP(S) URL → __http subtree, with a short query-hash
+    //     suffix when query / fragment are present to prevent collisions.
+    const cleanPath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+    const disambiguated = disambiguatePath(cleanPath, parsed.search, parsed.hash);
+    return joinUnder(cacheRoot, HTTP_NAMESPACE, parsed.host, ...disambiguated.split("/"));
+  }
+
+  return null;
+}
+
+/**
+ * Reads previously-cached manifest YAMLs from `<entry-dir>/.telo/manifests/`.
+ * Sits ahead of `RegistrySource` / `HttpSource` in the source chain — a hit
+ * makes boot hermetic, a miss falls through to the network source unchanged.
+ *
+ * Populated by `writeManifestCache` at install time.
+ */
+export class LocalManifestCacheSource implements ManifestSource {
+  private readonly cacheRoot: string;
+  private readonly registryUrl: string;
+
+  constructor(entryDir: string, registryUrl: string = DEFAULT_REGISTRY_URL) {
+    this.cacheRoot = path.join(entryDir, CACHE_SUBDIR);
+    this.registryUrl = registryUrl;
+  }
+
+  supports(url: string): boolean {
+    return this.tryMap(url) !== null;
+  }
+
+  async read(url: string): Promise<{ text: string; source: string }> {
+    const mapped = this.tryMap(url);
+    if (!mapped) {
+      throw new Error(
+        `LocalManifestCacheSource does not support '${url}' (cache miss or unsupported scheme)`,
+      );
+    }
+    const text = await fs.readFile(mapped, "utf-8");
+    return { text, source: pathToFileURL(mapped).href };
+  }
+
+  resolveRelative(base: string, relative: string): string {
+    // Once `read()` serves a file the canonical `source` is a file:// URL, so
+    // any further include: / sibling resolution flows through LocalFileSource.
+    // This method exists only for completeness; if the loader ever invokes it
+    // with a cache-mapped base, fall back to file-URL semantics.
+    const baseDir = base.endsWith("/") ? base : base.slice(0, base.lastIndexOf("/") + 1);
+    return new URL(relative, baseDir).href;
+  }
+
+  private tryMap(url: string): string | null {
+    const candidate = cachePathForUrl(url, this.cacheRoot, this.registryUrl);
+    if (!candidate) return null;
+    // Require a regular file. A directory, dangling symlink, or stat failure
+    // (ENOENT, EACCES, EISDIR-on-component) all fall through as a cache miss
+    // so the next source in the chain still gets a chance to serve the URL.
+    try {
+      return statSync(candidate).isFile() ? candidate : null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Map a graph's canonical `source` URL to the on-disk cache file path it
+ * should be written to (writer side). Returns `null` for sources that do
+ * not need caching — file:// (already on disk), memory:// (transient), or
+ * any path that would escape the cache root.
+ *
+ * Uses the same mapping function as `LocalManifestCacheSource`, so the
+ * writer and reader always agree on where every URL lives.
+ */
+export function cachePathForCanonical(
+  canonicalSource: string,
+  entryDir: string,
+  registryUrl: string,
+): string | null {
+  const cacheRoot = path.join(entryDir, CACHE_SUBDIR);
+  return cachePathForUrl(canonicalSource, cacheRoot, registryUrl);
+}
+
+/**
+ * Persist every manifest file reachable from `graph` (owners + partials) to
+ * `<entryDir>/.telo/manifests/`, except the entry manifest itself and any
+ * file:// or memory:// sources (already on disk or transient).
+ *
+ * Idempotent: rewrites any existing file with the freshly fetched bytes so
+ * a partial re-install converges. Never deletes entries — stale versions
+ * stay until `.telo/manifests/` is removed by hand, matching the
+ * `.telo/npm/` convention.
+ *
+ * Returns the list of paths written, for diagnostics.
+ */
+export async function writeManifestCache(
+  graph: LoadedGraph,
+  entryDir: string,
+  registryUrl: string = DEFAULT_REGISTRY_URL,
+): Promise<string[]> {
+  const written: string[] = [];
+  const seen = new Set<string>();
+
+  for (const [, module] of graph.modules) {
+    for (const file of [module.owner, ...module.partials]) {
+      if (file.source === graph.rootSource) continue;
+      if (seen.has(file.source)) continue;
+      seen.add(file.source);
+
+      const target = cachePathForCanonical(file.source, entryDir, registryUrl);
+      if (!target) continue;
+
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, file.text, "utf-8");
+      written.push(target);
+    }
+  }
+
+  return written;
+}
+
+/** Resolve the entry-anchor directory for the manifest cache.
+ *
+ * For a file path or `file://` URL: returns the containing directory.
+ * For a directory path: returns the directory itself.
+ * For an HTTP(S) URL: returns `null` (no local anchor; cache writes skipped). */
+export function resolveEntryDir(entryPath: string): string | null {
+  if (entryPath.startsWith("http://") || entryPath.startsWith("https://")) {
+    return null;
+  }
+  let absolute: string;
+  if (entryPath.startsWith("file://")) {
+    absolute = fileURLToPath(entryPath);
+  } else {
+    absolute = path.resolve(entryPath);
+  }
+  try {
+    const stat = statSync(absolute);
+    return stat.isDirectory() ? absolute : path.dirname(absolute);
+  } catch {
+    return path.dirname(absolute);
+  }
+}

package/src/resource-context.ts

@@ -262,6 +262,10 @@ export class ResourceContextImpl implements ResourceContext {
     return this.moduleContext.getControllerPolicy();
   }
 
+  getEntryUrl(): string | undefined {
+    return this.kernel.getEntryUrl();
+  }
+
   on(event: string, handler: (payload?: any) => void | Promise<void>): void {
     this.kernel.on(event, handler);
   }