@telorun/kernel 0.24.2 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.24.2",
+  "version": "0.26.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.6.1",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.22.0",
+    "@telorun/analyzer": "0.23.0",
     "@telorun/templating": "0.8.0",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
@@ -59,7 +59,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.23.0"
+    "@telorun/sdk": "0.26.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/application-env.ts

@@ -124,6 +124,43 @@ export function precompileApplicationEnvSchemas(
   }
 }
 
+/**
+ * Build-time cache warm for resource-config validators. The runtime
+ * `_createInstance` compiles `controller.schema` — which falls back to the
+ * declaring `Telo.Definition`'s own `schema` — to validate every resource's
+ * config, then validates inputs/outputs against `inputType` / `outputType`.
+ * The analyze-only warm pass stops before instantiation, so without this those
+ * validators are absent from the `__validators` cache and the runtime
+ * recompiles (and, on a read-only image, fails to persist) them on every boot.
+ *
+ * Compiling each definition's `schema` (plus any inline `inputType` /
+ * `outputType` object schemas) here writes them into the same content-addressed
+ * cache the runtime reads, keyed identically because the same schema object is
+ * fed to the same `validator.compile`. Definitions whose controller exports its
+ * own `schema` (rare) still recompile at runtime — that needs the controller
+ * loaded, which the warm pass does not do. Compile failures are swallowed; a
+ * genuinely broken schema surfaces through analysis / runtime, not here.
+ */
+export function precompileDefinitionSchemas(
+  manifests: Array<Record<string, any>>,
+  validator: SchemaValidator,
+): void {
+  const compile = (schema: unknown): void => {
+    if (!schema || typeof schema !== "object") return;
+    try {
+      validator.compile(schema as any);
+    } catch {
+      // Broken schemas are reported by analysis / runtime, not the warm pass.
+    }
+  };
+  for (const m of manifests) {
+    if (m?.kind !== "Telo.Definition") continue;
+    compile(m.schema);
+    compile(m.inputType);
+    compile(m.outputType);
+  }
+}
+
 /**
  * Populate the root Application's `ports` namespace from host environment
  * variables. Mirrors `resolveBlock` but fixes the value type to a port integer

package/src/controller-loader.ts

@@ -55,6 +55,10 @@ export interface ControllerLoaderOptions {
    * (cargo loader has its own per-crate cache and does not need this).
    */
   entryUrl?: string;
+  /** Explicit npm install root (`<cache-root>/npm`), threaded from the kernel's
+   *  single `resolveCacheRoot`. Overrides the entry-anchored default so a
+   *  relocated `TELO_CACHE_DIR` is honoured. */
+  installRoot?: string;
 }
 
 /**
@@ -82,7 +86,10 @@ export class ControllerLoader {
 
   constructor(options: ControllerLoaderOptions = {}) {
     this.emit = options.emit;
-    this.npmLoader = new NpmControllerLoader({ entryUrl: options.entryUrl });
+    this.npmLoader = new NpmControllerLoader({
+      entryUrl: options.entryUrl,
+      installRoot: options.installRoot,
+    });
     this.napiLoader = new NapiControllerLoader();
     this.bundleLoader = new BundleControllerLoader();
   }

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

@@ -97,6 +97,14 @@ export interface NpmControllerLoaderOptions {
    * `pkg-name` cli command resolves it from its argument.
    */
   entryUrl?: string;
+  /**
+   * Explicit install root, threaded from the kernel's single `resolveCacheRoot`
+   * (`<cache-root>/npm`). When set it overrides the entry-anchored
+   * `computeInstallRoot`, so a relocated `TELO_CACHE_DIR` (e.g. a prebuilt
+   * image baking deps at `/telo-cache`) is honoured without this loader reading
+   * the env itself.
+   */
+  installRoot?: string;
 }
 
 /**
@@ -104,14 +112,17 @@ export interface NpmControllerLoaderOptions {
  * 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
- * realpath as the kernel — so `Stream` (and any other class-identity-sensitive
- * type) has a single constructor across the process.
+ * Every controller — registry tag or `local_path` — is installed under a
+ * version-scoped npm alias (`npm install <alias>@<spec>`, see `installAlias`)
+ * into this root, then imported from `<root>/node_modules/<alias>`. The alias
+ * encodes `name@version`, so a graph that references one package at two
+ * versions keeps both in the single flat `node_modules` instead of the last
+ * `--save` clobbering the first. This still collapses two parallel module
+ * realms (kernel-side @telorun/sdk vs. controller-side @telorun/sdk) into one:
+ * `@telorun/sdk` is exempt from aliasing and wired in as a `file:` dep under
+ * its real name, npm/pnpm hoist a single copy, and Node's ESM resolver follows
+ * it to the same realpath as the kernel — so `Stream` (and any other
+ * class-identity-sensitive type) has a single constructor across the process.
  *
  * Per-kernel state lives on each `NpmControllerLoader` instance (one is
  * constructed per `ControllerLoader`, which is itself constructed per
@@ -124,6 +135,8 @@ export interface NpmControllerLoaderOptions {
  */
 export class NpmControllerLoader {
   private readonly entryUrl?: string;
+  /** Threaded install root (`<cache-root>/npm`); overrides `computeInstallRoot`. */
+  private readonly installRootOverride?: string;
 
   /**
    * Per-process cache of "this controller's package + version is already
@@ -161,6 +174,7 @@ export class NpmControllerLoader {
 
   constructor(options: NpmControllerLoaderOptions = {}) {
     this.entryUrl = options.entryUrl;
+    this.installRootOverride = options.installRoot;
   }
 
   async load(purl: string, baseUri: string): Promise<NpmLoadResult> {
@@ -169,17 +183,21 @@ export class NpmControllerLoader {
       throw new Error(`Invalid PURL '${purl}': missing package name`);
     }
     const packageName = parsed.namespace ? `${parsed.namespace}/${parsed.name}` : parsed.name;
+    const version = parsed.version ?? null;
+    // Version-scope the install under an alias so the same package at two
+    // versions can coexist in one flat node_modules (see installAlias).
+    const alias = installAlias(packageName, version);
 
     const installRoot = await this.ensureInstallRoot();
     const resolved = await resolveInstallSpec(parsed, packageName, baseUri);
     const source = await this.installPackage(
       installRoot,
-      packageName,
+      alias,
       resolved.spec,
       resolved.kind,
-      parsed.version ?? null,
+      version,
     );
-    const instance = await loadFromInstall(installRoot, packageName, parsed.subpath ?? null, purl);
+    const instance = await loadFromInstall(installRoot, alias, parsed.subpath ?? null, purl);
     return { instance, source };
   }
 
@@ -212,7 +230,7 @@ export class NpmControllerLoader {
       );
     }
     const entryUrlStr = this.entryUrl;
-    const installRoot = computeInstallRoot(entryUrlStr);
+    const installRoot = this.installRootOverride ?? 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
@@ -296,6 +314,11 @@ export class NpmControllerLoader {
     installRoot: string,
     dependencies: Record<string, string>,
   ): Promise<void> {
+    // `dependencies` is only the realm-collapse deps (`@telorun/sdk`), keyed by
+    // real `name@spec`. Controllers, by contrast, key `installedSpecs` by their
+    // version-scoped alias in `installPackage`. The two key spaces are
+    // intentionally disjoint — realm-collapse names are wired in here and never
+    // flow through `installPackage`, so an alias and a `name@spec` never clash.
     for (const [name, spec] of Object.entries(dependencies)) {
       this.installedSpecs.add(`${name}@${spec}`);
     }
@@ -303,11 +326,14 @@ export class NpmControllerLoader {
   }
 
   /**
-   * Install one controller spec into the existing root. Single-flight per
-   * spec within the process; cross-process safety is the fs-lock around the
-   * `npm install` call. If the spec is already present in the manifest's
-   * package.json (under `dependencies`), skip — reusing the previous install.
+   * Install one controller into the existing root under its version-scoped
+   * `alias` folder. Single-flight per alias within the process; cross-process
+   * safety is the fs-lock around the `npm install` call. If the alias is
+   * already installed (right version on disk, or a matching `file:` record),
+   * skip — reusing the previous install.
    *
+   * `spec` is the source half of the install (`npm:<name>@<version>` or
+   * `file:<abs>`); the package manager is invoked with `<alias>@<spec>`.
    * `kind` distinguishes a `local_path` source (loader synthesized `file:`
    * spec) from a registry tag. The CLI silences progress for both `cache`
    * and `local`; `npm-install` is the only event surfaced. Folding this
@@ -316,12 +342,12 @@ export class NpmControllerLoader {
    */
   private async installPackage(
     installRoot: string,
-    packageName: string,
+    alias: string,
     spec: string,
     kind: SpecKind,
     requestedVersion: string | null,
   ): Promise<NpmResolveSource> {
-    const cacheKey = `${packageName}@${spec}`;
+    const cacheKey = alias;
     if (this.installedSpecs.has(cacheKey)) return "cache";
 
     const inFlight = this.inFlight.get(cacheKey);
@@ -330,17 +356,20 @@ export class NpmControllerLoader {
       return "cache";
     }
 
-    const targetPath = path.join(installRoot, "node_modules", ...packageName.split("/"));
+    // The package is installed under its version-scoped alias, so its folder
+    // name in node_modules is the alias, not the bare package name.
+    const targetPath = path.join(installRoot, "node_modules", alias);
 
     // Registry fast path: compare against the installed package's own
-    // `package.json` version field. `rootDeps[packageName]` can't be used
-    // here because npm rewrites registry specs on `--save` — we pass
-    // `@scope/pkg@0.3.4`, npm writes `^0.3.4` — so a string comparison
-    // never matches and every fresh `NpmControllerLoader` (one per
-    // `Telo.Definition.init`) would fall through to a no-op but ~200ms
+    // `package.json` version field. The recorded dep spec can't be used here
+    // because npm rewrites registry specs on `--save` — we pass
+    // `<alias>@npm:@scope/pkg@0.3.4`, npm writes `npm:@scope/pkg@^0.3.4` — so a
+    // string comparison never matches and every fresh `NpmControllerLoader`
+    // (one per `Telo.Definition.init`) would fall through to a no-op but ~200ms
     // `npm install`. Reading the installed package.json sidesteps that
-    // entirely: if the requested PURL version equals what's on disk, we
-    // already have the right thing.
+    // entirely: if the requested PURL version equals what's on disk under this
+    // alias, we already have the right thing. Because the alias encodes the
+    // version, a present alias folder is always the requested version.
     //
     // Ranges (`^1.0.0`, `~2.3.0`) fall through to a real `npm install` —
     // they're rare in PURLs (which typically pin) and a proper range check
@@ -354,37 +383,47 @@ export class NpmControllerLoader {
         this.installedSpecs.add(cacheKey);
         return "cache";
       }
-    }
-
-    // Local (`file:`) spec fast path: consult the in-process snapshot of the
-    // install root's `dependencies` map (seeded by `materializeInstallRoot`).
-    // Normalize because npm rewrites absolute `file:` deps to relative paths
-    // inside the install root's `package.json` — the loader passes the
-    // absolute path, the on-disk record is `file:../../foo`.
-    const cachedSpec = this.rootDeps[packageName];
-    if (
-      cachedSpec !== undefined &&
-      normalizeFileSpec(cachedSpec, installRoot) === normalizeFileSpec(spec, installRoot) &&
-      (await pathExists(targetPath))
-    ) {
-      this.installedSpecs.add(cacheKey);
-      return "cache";
+    } else {
+      // Local (`file:`) spec fast path: consult the in-process snapshot of the
+      // install root's `dependencies` map (seeded by `materializeInstallRoot`).
+      // Normalize because npm rewrites absolute `file:` deps to relative paths
+      // inside the install root's `package.json` — the loader passes the
+      // absolute path, the on-disk record is `file:../../foo`.
+      const cachedSpec = this.rootDeps[alias];
+      if (
+        cachedSpec !== undefined &&
+        normalizeFileSpec(cachedSpec, installRoot) === normalizeFileSpec(spec, installRoot) &&
+        (await pathExists(targetPath))
+      ) {
+        this.installedSpecs.add(cacheKey);
+        return "cache";
+      }
     }
 
     const work = (async () => {
       await withInstallLock(installRoot, async () => {
         // Re-check inside the lock: a peer process may have installed the
-        // spec between the fast-path miss and our acquisition. Normalize
-        // the on-disk record to absolute form before comparing — npm
-        // rewrites `file:` deps to be relative to the install root.
-        const lockedSpec = await readDepSpec(installRoot, packageName);
-        if (
-          lockedSpec !== undefined &&
-          normalizeFileSpec(lockedSpec, installRoot) === normalizeFileSpec(spec, installRoot) &&
-          (await pathExists(targetPath))
-        ) {
-          this.rootDeps[packageName] = lockedSpec;
-          return;
+        // spec between the fast-path miss and our acquisition.
+        if (kind === "registry") {
+          const installedVersion = await readInstalledVersion(targetPath);
+          if (
+            installedVersion !== null &&
+            (requestedVersion === null || requestedVersion === installedVersion)
+          ) {
+            return;
+          }
+        } else {
+          // Normalize the on-disk record to absolute form before comparing —
+          // npm rewrites `file:` deps to be relative to the install root.
+          const lockedSpec = await readDepSpec(installRoot, alias);
+          if (
+            lockedSpec !== undefined &&
+            normalizeFileSpec(lockedSpec, installRoot) === normalizeFileSpec(spec, installRoot) &&
+            (await pathExists(targetPath))
+          ) {
+            this.rootDeps[alias] = lockedSpec;
+            return;
+          }
         }
 
         await runPackageManager(installRoot, [
@@ -394,14 +433,17 @@ export class NpmControllerLoader {
           "--silent",
           ...PEER_INSTALL_FLAGS,
           "--save",
-          spec,
+          // `<alias>@<source-spec>` installs the package under the alias folder
+          // (`npm:` for registry, `file:` for local) so multiple versions of
+          // one package name coexist in the single install root.
+          `${alias}@${spec}`,
         ]);
         // Re-read what npm actually wrote (it normalizes `file:` paths to
         // be relative to the install root). Caching the spec in its on-disk
         // form keeps subsequent fast-path comparisons stable.
-        const written = await readDepSpec(installRoot, packageName);
-        if (written !== undefined) this.rootDeps[packageName] = written;
-        else this.rootDeps[packageName] = spec;
+        const written = await readDepSpec(installRoot, alias);
+        if (written !== undefined) this.rootDeps[alias] = written;
+        else this.rootDeps[alias] = spec;
       });
     })();
 
@@ -693,6 +735,35 @@ function computeInstallRoot(entryUrl: string): string {
   );
 }
 
+/**
+ * Version-qualified install alias for a controller package. The kernel's single
+ * flat install root can hold only one folder per package name, but a manifest
+ * graph may legitimately reference the same package at multiple versions (e.g.
+ * a library pins `@telorun/mcp-client@0.3.1` while the app uses `0.4.0`).
+ * Installing each `name@version` under a distinct npm alias
+ * (`npm install <alias>@npm:<name>@<version>`) lets every version coexist in
+ * one `node_modules`, mirroring the per-(name, version) identity of a Telo
+ * module singleton. `@telorun/sdk` is intentionally NOT routed through here —
+ * it stays under its real name so realm-collapse hoists a single copy across
+ * the kernel/controller boundary (see REALM_COLLAPSE_NAMES).
+ *
+ * The result is a valid unscoped npm package name: the scope `@` is dropped,
+ * `/` becomes `__`, and any character outside npm's name grammar is replaced
+ * with `-`. Because that sanitization is lossy (e.g. build metadata `1.0.0+x`
+ * and prerelease `1.0.0-x` both fold to `1.0.0-x`, and a `__` already in a
+ * package name overlaps the scope separator), the alias ends with a short hash
+ * of the *exact* `name@version` — so two distinct pairs can never collide onto
+ * one folder regardless of how their readable prefixes sanitize. The readable
+ * prefix is kept purely so the install tree is greppable.
+ */
+function installAlias(packageName: string, version: string | null): string {
+  const prefix = `${packageName.replace(/^@/, "").replace(/\//g, "__")}__${version ?? "latest"}`
+    .replace(/[^a-zA-Z0-9._-]/g, "-")
+    .toLowerCase();
+  const digest = sha256(`${packageName}@${version ?? ""}`).slice(0, 8);
+  return `${prefix}__${digest}`;
+}
+
 /**
  * Normalize a `file:` spec to an absolute path so two specs that point at the
  * same source — one absolute (what the loader synthesizes from `local_path`)
@@ -770,7 +841,10 @@ async function resolveInstallSpec(
       return { kind: "local", spec: `file:${absolutePath}`, absolutePath };
     }
   }
-  const spec = parsed.version ? `${packageName}@${parsed.version}` : packageName;
+  // `npm:` source spec so the caller can install it under a version-scoped
+  // alias (`<alias>@npm:<name>@<version>`); both versions of one package name
+  // then coexist in the single flat install root.
+  const spec = parsed.version ? `npm:${packageName}@${parsed.version}` : `npm:${packageName}`;
   return { kind: "registry", spec };
 }
 
@@ -782,11 +856,13 @@ async function resolveInstallSpec(
  */
 async function loadFromInstall(
   installRoot: string,
-  packageName: string,
+  alias: string,
   subpath: string | null,
   purl: string,
 ): Promise<ControllerInstance> {
-  const packageRoot = path.join(installRoot, "node_modules", ...packageName.split("/"));
+  // The package lives under its version-scoped alias folder (see installAlias),
+  // not its bare scoped name.
+  const packageRoot = path.join(installRoot, "node_modules", alias);
   const entry = subpath ? `./${subpath}` : ".";
   const entryFile = await resolvePackageEntry(packageRoot, entry);
   // ESM dynamic `import()` accepts either a relative specifier or a `file://`
@@ -937,6 +1013,7 @@ function resolveExportTargetValue(
  * Not part of the kernel's public API — consumers should not import these.
  */
 export const __testing__ = {
+  installAlias,
   normalizeFileSpec,
   resolvePackageExportTarget,
   resolveExportTargetValue,

package/src/controller-registry.ts

@@ -98,6 +98,24 @@ export class ControllerRegistry {
     return Array.from(this.controllersByKind.keys());
   }
 
+  /**
+   * Distinct controller `schema` objects across all registered kinds (one per
+   * kind, default fingerprint preferred). Used by the build-time validator warm
+   * to pre-compile the framework/builtin controller schemas (`Telo.Import`,
+   * `Telo.Definition`, the module controller, …) the runtime validates
+   * resources against — module-defined kinds aren't registered here until
+   * instantiation, so those are warmed from the static manifests instead.
+   */
+  getControllerSchemas(): object[] {
+    const schemas: object[] = [];
+    for (const byFp of this.controllersByKind.values()) {
+      const controller = byFp.get(DEFAULT_FINGERPRINT) ?? byFp.values().next().value;
+      const schema = controller?.schema;
+      if (schema && typeof schema === "object") schemas.push(schema);
+    }
+    return schemas;
+  }
+
   /**
    * Register a controller for a (kind, fingerprint). Multiple registrations
    * for the same kind with different fingerprints coexist; same fingerprint

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

@@ -1,4 +1,4 @@
-import { AnalysisRegistry, DiagnosticSeverity, StaticAnalyzer } from "@telorun/analyzer";
+import { AnalysisRegistry, DiagnosticSeverity, parseExportEntry, StaticAnalyzer } from "@telorun/analyzer";
 import type { ResourceInstance } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 import type { BuiltinControllerContext } from "../../internal-context.js";
@@ -108,12 +108,27 @@ export async function create(
   validateRequiredInputs(moduleManifest.variables ?? {}, resource.variables ?? {}, "variables");
   validateRequiredInputs(moduleManifest.secrets ?? {}, resource.secrets ?? {}, "secrets");
 
-  // Create child context with the imported variables/secrets baked in, so that
-  // ${{ variables.x }} / ${{ secrets.y }} templates resolve correctly at runtime.
+  // Evaluate the import's variables/secrets ONCE against the IMPORTER's config
+  // scope, instead of baking the raw compiled-value objects verbatim. Resolution
+  // is eager and per-hop: each importer resolves its child's inputs from its own
+  // already-settled config, so config flows app -> lib -> lib at any nesting depth
+  // and a leaf reads `variables.X` as an O(1) concrete lookup with no chain-walk.
+  // The single concrete result seeds both the child scope and the snapshot value-
+  // flow surface, so they can never diverge.
+  //
+  // NOTE: `expandValue` evaluates against the importer's FULL context (variables /
+  // secrets, plus env/resources for a root app). The config-only import contract —
+  // no resources/env/ports in import inputs — is enforced by the analyzer, not here;
+  // a `${{ resources.X }}` slipping past analysis (skipValidation / programmatic
+  // load) would evaluate at runtime rather than being rejected.
+  const importVariables =
+    (ctx.expandValue(resource.variables, {}) as Record<string, unknown>) ?? {};
+  const importSecrets =
+    (ctx.expandValue(resource.secrets, {}) as Record<string, unknown>) ?? {};
   const childCtx = new ModuleContext(
     ctx.moduleContext.source,
-    (resource.variables as Record<string, unknown>) ?? {},
-    (resource.secrets as Record<string, unknown>) ?? {},
+    importVariables,
+    importSecrets,
     {},
     [],
     ctx.moduleContext.createInstance,
@@ -157,8 +172,26 @@ export async function create(
   // Throws if resources.X is not yet populated — the kernel retry loop catches this and retries.
   // const evaluatedExports: any = child.expand(moduleManifest.exports ?? {});
 
-  const exportedKinds: string[] = moduleManifest.exports?.kinds ?? [];
-  const exportedResourceNames: string[] = moduleManifest.exports?.resources ?? [];
+  // `exports.kinds` entries are a bare kind name (locally defined) or `Alias.Kind` (a re-export
+  // of an imported library's kind). `parseExportEntry` (shared with the analyzer) yields
+  // `{name, alias?}` — `name` is the exported kind suffix, `alias` (when set) names this
+  // library's own import it re-exports from.
+  const kindEntries = ((moduleManifest.exports?.kinds ?? []) as string[]).map(parseExportEntry);
+  const exportedKindSuffixes = kindEntries.map((k) => k.name);
+  // `exports.resources` entries are a bare name (`Db`, a locally-owned export) or a dotted
+  // `Alias.Name` (re-export of an imported instance, under name `Name`) — same grammar as
+  // `exports.kinds`.
+  const exportEntries = ((moduleManifest.exports?.resources ?? []) as unknown[]).map((e) => {
+    if (typeof e !== "string") {
+      throw new RuntimeError(
+        "ERR_INVALID_EXPORT",
+        `Library '${targetModule}' exports.resources entries must be plain names ('Name' or ` +
+          `'Alias.Name'); the '!ref' tag is not allowed in exports.resources.`,
+      );
+    }
+    return parseExportEntry(e);
+  });
+  const exportedResourceNames = exportEntries.map((e) => e.name);
   for (const name of exportedResourceNames) {
     if (name === "variables" || name === "secrets") {
       throw new RuntimeError(
@@ -167,30 +200,22 @@ export async function create(
       );
     }
   }
-  ctx.registerModuleImport(alias, targetModule, exportedKinds);
+  ctx.registerModuleImport(alias, targetModule, exportedKindSuffixes);
 
   // Publish the child's exported instances to the parent so cross-module `!ref Alias.name`
   // (Phase 5 injection / boot targets) and `${{ resources.Alias.name }}` (CEL value-flow)
-  // resolve. The gate is `exports.resources`; the lookup is lazy — instances exist after
-  // this import's init() has run child.initializeResources().
+  // resolve. The gate is `exports.resources`; the child's terminal getter is read lazily —
+  // it exists after this import's init() built the child's export table. Handing the parent
+  // the child's TERMINAL getter (not a wrapper) keeps resolution O(1) across re-export hops.
   (ctx.moduleContext as ModuleContext).registerImportedScope(
     alias,
     exportedResourceNames,
-    (name) => {
-      const entry = childCtx.resourceInstances.get(name);
-      if (!entry) return undefined;
-      // Canonicalize the authored kind to `<module>.<Kind>` so the cross-module ref shape and
-      // event naming are scope-independent. Exported instances are authored `Self.<Kind>` —
-      // the only case the std modules use, and the only one canonicalized here; it maps to the
-      // owning module directly, matching the analyzer's rule in resolve-ref-sentinels.ts. A
-      // re-exported foreign kind (authored via another import alias) is a future case with no
-      // current consumer and is left verbatim.
-      const rawKind = entry.resource.kind as string;
-      const kind = rawKind.startsWith("Self.")
-        ? `${targetModule}.${rawKind.slice("Self.".length)}`
-        : rawKind;
-      return { kind, instance: entry.instance };
-    },
+    (name) => childCtx.getTerminalExport(name),
+  );
+  // Same for kinds: `kind: Alias.Kind` resolves through the child's exported-kind table,
+  // covering both locally-defined and transitively re-exported kinds in O(1).
+  (ctx.moduleContext as ModuleContext).registerImportedKindScope(alias, (suffix) =>
+    childCtx.getExportedKind(suffix),
   );
 
   // Return a ResourceInstance whose snapshot() surfaces the exported values under
@@ -201,19 +226,24 @@ export async function create(
     snapshot: async () => {
       const exported: Record<string, unknown> = {};
       for (const name of exportedResourceNames) {
-        const inst = childCtx.resourceInstances.get(name)?.instance;
+        const inst = childCtx.getExported(name)?.instance;
         if (inst && typeof inst.snapshot === "function") {
           exported[name] = await Promise.resolve(inst.snapshot());
         }
       }
       return {
-        variables: ctx.expandValue(resource.variables, {}) ?? {},
-        secrets: ctx.expandValue(resource.secrets, {}) ?? {},
+        variables: importVariables,
+        secrets: importSecrets,
         ...exported,
       };
     },
     init: async () => {
       await child.initializeResources();
+      // Build this import's flattened export tables now that its own imports are
+      // registered (leaves-first), so a re-export (`!ref Alias.name` / `Alias.Kind`)
+      // copies the source import's terminal getter / canonical kind by reference —
+      // O(1) resolution at any depth.
+      childCtx.buildExportTable(exportEntries, kindEntries, targetModule);
     },
     teardown: async () => {
       await child.teardownResources();

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

@@ -54,6 +54,7 @@ class ResourceDefinition implements ResourceInstance {
     const loader = new ControllerLoader({
       emit: (e) => ctx.emit(e.name, e.payload),
       entryUrl: ctx.getEntryUrl(),
+      installRoot: ctx.getInstallRoot(),
     });
     const controllerInstance = await loader.load(
       this.resource.controllers,

package/src/evaluation-context.ts

@@ -501,10 +501,13 @@ export class EvaluationContext implements IEvaluationContext {
     // the resolved entry for event topics and error messages.
     const effectiveKind = kind || (entry.resource.kind as string);
 
-    if (typeof entry.instance.invoke !== "function") {
+    if (
+      typeof entry.instance.invoke !== "function" &&
+      typeof entry.instance.run !== "function"
+    ) {
       throw new RuntimeError(
         "ERR_RESOURCE_NOT_INVOKABLE",
-        `Resource ${effectiveKind}.${name} does not have an invoke method`,
+        `Resource ${effectiveKind}.${name} does not have an invoke or run method`,
       );
     }
 
@@ -524,10 +527,10 @@ export class EvaluationContext implements IEvaluationContext {
     inputs: TInputs,
     ctx?: InvokeContext,
   ): Promise<any> {
-    if (typeof instance.invoke !== "function") {
+    if (typeof instance.invoke !== "function" && typeof instance.run !== "function") {
       throw new RuntimeError(
         "ERR_RESOURCE_NOT_INVOKABLE",
-        `Resource ${kind}.${name} does not have an invoke method`,
+        `Resource ${kind}.${name} does not have an invoke or run method`,
       );
     }
     return this.runInvoke(kind, name, instance, inputs, ctx);
@@ -560,8 +563,15 @@ export class EvaluationContext implements IEvaluationContext {
     try {
       // Only (re)establish the ALS scope when the token differs from the ambient
       // one — nested invokes that inherited it skip the redundant `run`.
+      // A step / boot-target slot may reference a pure Runnable (the schema
+      // allows `telo#Runnable` alongside `telo#Invocable`); dispatch it via
+      // `run()` — side effects only, no outputs. Prefer `invoke()` when both
+      // exist so a dual-capability instance (e.g. Run.Sequence) keeps invoke
+      // semantics and returns its `steps`/`outputs`.
       const call = () =>
-        (instance.invoke as (i: any, c?: InvokeContext) => any)(inputs as any, invokeCtx);
+        typeof instance.invoke === "function"
+          ? (instance.invoke as (i: any, c?: InvokeContext) => any)(inputs as any, invokeCtx)
+          : (instance.run as (c?: InvokeContext) => any)(invokeCtx);
       const outputs = await (invokeCtx === ambient
         ? call()
         : cancellationStore.run(invokeCtx, call));