@telorun/kernel 0.5.0 → 0.6.1

package/src/controller-loader.ts

@@ -5,6 +5,48 @@ import { ControllerPolicy, DEFAULT_POLICY, POLICY_WILDCARD } from "./runtime-reg
 
 export type { ControllerPolicy } from "./runtime-registry.js";
 
+/**
+ * Which branch the per-scheme loader actually took. Cache/local hits resolve
+ * in milliseconds; `npm-install` and `cargo-build` are the only branches that
+ * do real (network or compile) work. The CLI uses this to decide whether a
+ * "downloading…" line was honest or should be erased.
+ */
+export type ControllerResolveSource =
+  | "local"
+  | "node_modules"
+  | "cache"
+  | "npm-install"
+  | "cargo-build";
+
+export type ControllerLoaderEvent =
+  | { name: "ControllerLoading"; payload: { purl: string } }
+  | {
+      name: "ControllerLoaded";
+      payload: { purl: string; source: ControllerResolveSource; durationMs: number };
+    }
+  | { name: "ControllerLoadFailed"; payload: { purl: string; error: string } }
+  /**
+   * The candidate at `purl` couldn't be tried in this environment (e.g.
+   * `pkg:cargo` with no `rustc` on PATH, or an unsupported scheme) and the
+   * dispatcher has moved on to the next candidate. Distinct from `Failed`,
+   * which is non-recoverable. Consumers that opened a UI element on the
+   * matching `ControllerLoading` should close it out here.
+   */
+  | { name: "ControllerLoadSkipped"; payload: { purl: string; reason: string } };
+
+/**
+ * The dispatcher awaits each emission, so the callback may be async without
+ * risking out-of-order delivery (concurrent definition loads emit in
+ * parallel; the await pins each pair of `Loading`/`Loaded` events to the
+ * same async chain). The kernel's `ctx.emit` is async, hence `Promise<void>`
+ * is allowed.
+ */
+export type ControllerLoaderEmit = (event: ControllerLoaderEvent) => void | Promise<void>;
+
+export interface ControllerLoaderOptions {
+  emit?: ControllerLoaderEmit;
+}
+
 /**
  * Top-level controller-loader dispatcher. Picks a per-scheme sub-loader by
  * PURL type and applies the resolved selection policy:
@@ -17,10 +59,19 @@ export type { ControllerPolicy } from "./runtime-registry.js";
  * Recovery: env-missing failures (`ControllerEnvMissingError`) advance to the
  * next candidate. User-code failures (`RuntimeError("ERR_CONTROLLER_BUILD_FAILED" | "ERR_CONTROLLER_INVALID")`)
  * fail hard regardless of remaining candidates.
+ *
+ * Lifecycle events are emitted per *attempt*, so a fallback chain produces one
+ * `ControllerLoading` per candidate tried plus a final `ControllerLoaded` (or
+ * `ControllerLoadFailed`) for the one that won.
  */
 export class ControllerLoader {
   private npmLoader = new NpmControllerLoader();
   private napiLoader = new NapiControllerLoader();
+  private emit?: ControllerLoaderEmit;
+
+  constructor(options: ControllerLoaderOptions = {}) {
+    this.emit = options.emit;
+  }
 
   async load(
     purlCandidates: string[],
@@ -41,23 +92,48 @@ export class ControllerLoader {
 
     const errors: string[] = [];
     for (const purl of ordered) {
+      await this.emit?.({ name: "ControllerLoading", payload: { purl } });
+      const startedAt = Date.now();
       try {
-        return await this.dispatchOne(purl, baseUri);
+        const { instance, source } = await this.dispatchOne(purl, baseUri);
+        await this.emit?.({
+          name: "ControllerLoaded",
+          payload: { purl, source, durationMs: Date.now() - startedAt },
+        });
+        return instance;
       } catch (err) {
         if (err instanceof ControllerEnvMissingError) {
           errors.push(`${purl}: ${err.message}`);
+          // Env-missing isn't a hard failure — the dispatcher will try the
+          // next candidate. We still emit a terminal event for *this* attempt
+          // so consumers (notably the CLI progress renderer) can close out
+          // the UI state opened by the matching ControllerLoading. Without
+          // this, every fallback attempt would leak a pending `⬇` line.
+          await this.emit?.({
+            name: "ControllerLoadSkipped",
+            payload: { purl, reason: err.message },
+          });
           continue;
         }
+        await this.emit?.({
+          name: "ControllerLoadFailed",
+          payload: { purl, error: err instanceof Error ? err.message : String(err) },
+        });
         throw err;
       }
     }
-    throw new RuntimeError(
-      "ERR_CONTROLLER_NOT_FOUND",
-      `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`,
-    );
+    const aggregated = `No controller resolved. Tried ${ordered.length} candidate(s):\n${errors.join("\n")}`;
+    await this.emit?.({
+      name: "ControllerLoadFailed",
+      payload: { purl: ordered[ordered.length - 1], error: aggregated },
+    });
+    throw new RuntimeError("ERR_CONTROLLER_NOT_FOUND", aggregated);
   }
 
-  private async dispatchOne(purl: string, baseUri: string): Promise<ControllerInstance> {
+  private async dispatchOne(
+    purl: string,
+    baseUri: string,
+  ): Promise<{ instance: ControllerInstance; source: ControllerResolveSource }> {
     if (purl.startsWith("pkg:npm")) {
       return this.npmLoader.load(purl, baseUri);
     }

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

@@ -39,7 +39,35 @@ export class ControllerEnvMissingError extends Error {
  * crate path (not on the caller's baseUri) ensures two distinct paths that
  * point at the same crate share one cache entry.
  */
-const _napiModuleCache = new Map<string, ControllerInstance>();
+/**
+ * Holds the *raw* `require()`'d module object — i.e. the flat export bag
+ * returned by the napi addon — keyed by canonical crate path. The PURL
+ * fragment (`#entry`) projects out a sub-export at call time; caching the
+ * raw module here means two PURLs that differ only by fragment share one
+ * cargo build / one mmap of the dylib, instead of paying for either twice.
+ */
+const _napiModuleCache = new Map<string, any>();
+
+/**
+ * Which branch of the resolver served this load.
+ *
+ * - `cache`      — process-lifetime in-memory hit on `_napiModuleCache`.
+ * - `local`      — `local_path` qualifier; cargo was invoked but the work
+ *                  is conceptually equivalent to "found source on disk and
+ *                  used it" (parallel to the npm `local_path` branch). The
+ *                  CLI silences these by default; the first cold build on
+ *                  a fresh checkout is silent for the same reason.
+ * - `cargo-build`— reserved for distribution-mode resolution (fetch from a
+ *                  registry + compile). Not produced today; the dispatcher
+ *                  errors with `ControllerEnvMissingError` for non-local
+ *                  PURLs (see [napi-loader.ts:62-66] in this file).
+ */
+export type NapiResolveSource = "cache" | "local" | "cargo-build";
+
+export interface NapiLoadResult {
+  instance: ControllerInstance;
+  source: NapiResolveSource;
+}
 
 export class NapiControllerLoader {
   /**
@@ -52,9 +80,19 @@ export class NapiControllerLoader {
    *
    * Distribution mode (no local_path): out of scope for the PoC; the hook is
    * left in place so the dispatcher reports env-missing and falls through.
+   *
+   * Fragment (`#entry`) is optional. When absent, the whole `require()`'d
+   * module is returned as the controller — the legacy single-export
+   * convention. When present, the fragment is treated as a property name on
+   * the loaded module: e.g. `pkg:cargo/foo?local_path=...#bar` returns
+   * `module.bar` as the controller. This mirrors the npm `#entry` semantics
+   * but indexes into the flat napi export bag instead of opening a different
+   * file. The convention is "one source file per controller, top-level
+   * export name matches the file" — files-as-controllers in spirit, even
+   * though all exports come from one linked dylib.
    */
-  async load(purl: string, baseUri: string): Promise<ControllerInstance> {
-    const [, , name, , qualifiers] = PackageURL.parseString(purl);
+  async load(purl: string, baseUri: string): Promise<NapiLoadResult> {
+    const [, , name, , qualifiers, entry] = PackageURL.parseString(purl);
     const localPath = (qualifiers as any)?.get("local_path");
 
     const isLocalManifest =
@@ -82,7 +120,7 @@ export class NapiControllerLoader {
     const cacheKey = canonicalCratePath;
     const cached = _napiModuleCache.get(cacheKey);
     if (cached) {
-      return cached;
+      return { instance: project(cached, entry, cratePath), source: "cache" };
     }
 
     try {
@@ -122,9 +160,9 @@ export class NapiControllerLoader {
     const nodePath = path.join(path.dirname(dylibPath), `${libName}.node`);
     await fs.copyFile(dylibPath, nodePath);
 
-    let module: any;
+    let rawModule: any;
     try {
-      module = requireFromHere(nodePath);
+      rawModule = requireFromHere(nodePath);
     } catch (err: any) {
       throw new RuntimeError(
         "ERR_CONTROLLER_INVALID",
@@ -132,15 +170,50 @@ export class NapiControllerLoader {
       );
     }
 
-    if (!module || (!module.create && !module.register)) {
+    _napiModuleCache.set(cacheKey, rawModule);
+    // `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" };
+  }
+}
+
+/**
+ * Pick the controller out of the raw napi module. With no fragment, the
+ * whole module *is* the controller (legacy single-export shape). With a
+ * fragment, look up `module[entry]` — convention: one source file per
+ * controller, top-level export name matches the file.
+ */
+function project(module: any, entry: string | undefined, where: string): ControllerInstance {
+  if (!module) {
+    throw new RuntimeError("ERR_CONTROLLER_INVALID", `napi module from ${where} is empty`);
+  }
+  if (!entry) {
+    if (!module.create && !module.register) {
       throw new RuntimeError(
         "ERR_CONTROLLER_INVALID",
-        `pkg:cargo controller at ${nodePath} exports neither create nor register`,
+        `pkg:cargo controller at ${where} exports neither create nor register`,
       );
     }
-    _napiModuleCache.set(cacheKey, module);
     return module;
   }
+  const sub = module[entry];
+  if (!sub) {
+    throw new RuntimeError(
+      "ERR_CONTROLLER_INVALID",
+      `pkg:cargo controller at ${where}#${entry}: module has no export named "${entry}"`,
+    );
+  }
+  if (!sub.create && !sub.register) {
+    throw new RuntimeError(
+      "ERR_CONTROLLER_INVALID",
+      `pkg:cargo controller at ${where}#${entry} exports neither create nor register`,
+    );
+  }
+  return sub;
 }
 
 async function resolveCrateMetadata(

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

@@ -14,13 +14,26 @@ const cacheRoot = process.env.TELO_CACHE_DIR
 const npmCacheRoot = path.join(cacheRoot, "npm");
 const isBun = typeof (globalThis as any).Bun !== "undefined";
 
+/**
+ * Tells the dispatcher (and any UI consumer downstream) which branch the
+ * resolver actually took. `npm-install` is the only one that hits the network;
+ * the rest are sub-second cache/local lookups, so the CLI uses this to decide
+ * whether a "downloading…" line was honest or should be silently dropped.
+ */
+export type NpmResolveSource = "local" | "node_modules" | "npm-install" | "cache";
+
+export interface NpmLoadResult {
+  instance: ControllerInstance;
+  source: NpmResolveSource;
+}
+
 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> {
+  async load(purl: string, baseUri: string): Promise<NpmLoadResult> {
     const [, namespace, name, versionSpec, qualifiers, entry] = PackageURL.parseString(purl);
 
     const localPath = (qualifiers as any)?.get("local_path");
@@ -28,6 +41,7 @@ export class NpmControllerLoader {
     const installDir = path.join(npmCacheRoot, cacheKey);
 
     let packageRoot: string;
+    let source: NpmResolveSource;
     const isLocalManifest =
       baseUri && !baseUri.startsWith("http://") && !baseUri.startsWith("https://");
     if (localPath && isLocalManifest) {
@@ -36,12 +50,14 @@ export class NpmControllerLoader {
       const resolvedLocalPath = path.resolve(manifestDir, localPath);
       if (await this.pathExists(resolvedLocalPath)) {
         packageRoot = resolvedLocalPath;
+        source = "local";
       } else {
         const nodeModulesPath = await this.findInNodeModules(`${namespace}/${name}`);
         if (nodeModulesPath) {
           packageRoot = nodeModulesPath;
+          source = "node_modules";
         } else {
-          await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
+          source = await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
           packageRoot = this.getInstalledPackageRoot(installDir, `${namespace}/${name}`);
         }
       }
@@ -49,8 +65,9 @@ export class NpmControllerLoader {
       const nodeModulesPath = await this.findInNodeModules(`${namespace}/${name}`);
       if (nodeModulesPath) {
         packageRoot = nodeModulesPath;
+        source = "node_modules";
       } else {
-        await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
+        source = await this.ensureNpmPackageInstalled(installDir, `${namespace}/${name}@${versionSpec}`);
         packageRoot = this.getInstalledPackageRoot(installDir, `${namespace}/${name}`);
       }
     }
@@ -62,10 +79,13 @@ export class NpmControllerLoader {
         `Invalid controller loaded from "${purl}": missing create or register function`,
       );
     }
-    return instance;
+    return { instance, source };
   }
 
-  private async ensureNpmPackageInstalled(installDir: string, packageSpec: string): Promise<void> {
+  private async ensureNpmPackageInstalled(
+    installDir: string,
+    packageSpec: string,
+  ): Promise<"cache" | "npm-install"> {
     const packageName = this.getPackageName(
       packageSpec.startsWith(".") || path.isAbsolute(packageSpec)
         ? await this.getLocalPackageName(packageSpec)
@@ -74,7 +94,7 @@ export class NpmControllerLoader {
     const packageRoot = this.getInstalledPackageRoot(installDir, packageName);
     const packageJsonPath = path.join(packageRoot, "package.json");
     if (await this.pathExists(packageJsonPath)) {
-      return;
+      return "cache";
     }
 
     await fs.mkdir(installDir, { recursive: true });
@@ -98,6 +118,7 @@ export class NpmControllerLoader {
     ];
 
     await execFileAsync("npm", args);
+    return "npm-install";
   }
 
   private getPackageName(packageSpec: string): string {

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

@@ -11,8 +11,8 @@ const importAnalysisCache = new Map<
 
 // Only resolve relative/absolute-path sources against the importer's URL. Registry refs
 // (std/foo@1.2.3) and absolute URLs (https://, file://) must pass through unchanged so the
-// loader's adapter chain can dispatch them — otherwise `new URL("std/foo@1", "file:///srv/telo.yaml")`
-// turns a registry ref into a bogus file path and LocalFileAdapter ENOENTs on it.
+// loader's source chain can dispatch them — otherwise `new URL("std/foo@1", "file:///srv/telo.yaml")`
+// turns a registry ref into a bogus file path and LocalFileSource ENOENTs on it.
 function resolveImportSource(source: string, baseSource: string): string {
   if (source.startsWith(".") || source.startsWith("/")) {
     return new URL(source, baseSource).toString();

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

@@ -27,10 +27,7 @@ type ResourceDefinitionResource = RuntimeResource & {
 class ResourceDefinition implements ResourceInstance {
   readonly kind: "ResourceDefinition" = "ResourceDefinition";
 
-  constructor(
-    readonly resource: ResourceDefinitionResource,
-    private controllerLoader: ControllerLoader,
-  ) {}
+  constructor(readonly resource: ResourceDefinitionResource) {}
 
   async init(ctx: ResourceContext) {
     if (!this.resource.controllers?.length) {
@@ -43,24 +40,25 @@ class ResourceDefinition implements ResourceInstance {
       );
       return;
     }
-    ctx.emit("ControllerLoading", { controllers: this.resource.controllers });
-    try {
-      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);
-      await ctx.registerController(
-        this.resource.metadata.module,
-        this.resource.metadata.name,
-        controllerInstance,
-      );
-    } catch (err) {
-      ctx.emit("ControllerLoadFailed", { error: (err as Error).message });
-      throw err;
-    }
+    // 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),
+    });
+    const controllerInstance = await loader.load(
+      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,
+    );
   }
 }
 
@@ -78,7 +76,7 @@ export async function create(resource: any, ctx: ResourceContext): Promise<Resou
 
   // Return a fully-formed ResourceDefinition instance
   const definition = resource as unknown as ResourceDefinitionResource;
-  return new ResourceDefinition(definition, new ControllerLoader());
+  return new ResourceDefinition(definition);
 }
 
 export const schema = {

package/src/evaluation-context.ts

@@ -18,6 +18,52 @@ import { RuntimeError } from "@telorun/sdk";
 
 export { resourceKey };
 
+type Walker = (ctx: Record<string, unknown>) => unknown;
+
+/** Compile a manifest subtree into a tightly-bound walker closure. The returned
+ *  function takes an activation object and rebuilds a fresh container of the
+ *  same shape with all `${{ }}` CompiledValues evaluated against the activation.
+ *  Per-call overhead is one closure invocation per node — no isCompiledValue /
+ *  Array.isArray / typeof / Object.entries checks at runtime. */
+function compileWalker(value: unknown): Walker {
+  if (isCompiledValue(value)) {
+    const compiled = value;
+    return (ctx) => {
+      try {
+        return compiled.call(ctx);
+      } catch (error) {
+        const expr = compiled.source ? `\${{ ${compiled.source} }}` : "unknown expression";
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new Error(`Expression ${expr} failed: ${msg}`);
+      }
+    };
+  }
+  if (Array.isArray(value)) {
+    const childWalkers = value.map(compileWalker);
+    const n = childWalkers.length;
+    return (ctx) => {
+      const out = new Array(n);
+      for (let i = 0; i < n; i++) out[i] = childWalkers[i]!(ctx);
+      return out;
+    };
+  }
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>).map(
+      ([k, v]) => [k, compileWalker(v)] as const,
+    );
+    const n = entries.length;
+    return (ctx) => {
+      const out: Record<string, unknown> = {};
+      for (let i = 0; i < n; i++) {
+        const [k, fn] = entries[i]!;
+        out[k] = fn(ctx);
+      }
+      return out;
+    };
+  }
+  return () => value;
+}
+
 /**
  * Base class for all evaluation contexts. Owns template
  * expansion, secrets redaction, and the generic resource lifecycle tree.
@@ -215,7 +261,7 @@ export class EvaluationContext implements IEvaluationContext {
           }
           if (instance.init) await instance.init(ctx);
           if (instance.snapshot) {
-            const snap = await Promise.resolve(instance.snapshot()).catch(() => ({}));
+            const snap = await Promise.resolve(instance.snapshot());
             this.onResourceSnapshotted(name, (snap as Record<string, unknown>) ?? {});
           }
           this.resourceInstances.set(name, { resource, instance });
@@ -453,7 +499,9 @@ export class EvaluationContext implements IEvaluationContext {
         if (declaredCodes && !declaredCodes.has(err.code)) {
           await this.emit(`${kind}.${name}.InvokeRejected.Undeclared`, payload);
         }
-      } else if (err instanceof Error) {
+        throw err;
+      }
+      if (err instanceof Error) {
         await this.emit(`${kind}.${name}.InvokeFailed`, {
           name: err.name,
           message: err.message,
@@ -464,7 +512,22 @@ export class EvaluationContext implements IEvaluationContext {
           message: String(err),
         });
       }
-      throw err;
+      // Already enriched at an inner invoke: keep the innermost (most
+      // specific) resource as the failure location.
+      if (err instanceof RuntimeError && err.diagnostics?.length) throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      const code = err instanceof Error ? err.name : undefined;
+      // Keep `message` raw so callers (Run.Sequence catch blocks, assertions)
+      // see the original error text unchanged. Resource context lives only on
+      // the attached diagnostic, which the CLI's formatter renders as the
+      // location prefix. Attach the original error as `cause` so
+      // formatErrorForDiagnostic walks the chain and surfaces the underlying
+      // stack and well-known error fields (AWS, pg, Node system errors).
+      const wrapped = new RuntimeError("ERR_EXECUTION_FAILED", message, [
+        { kind, resource: name, message, code },
+      ]);
+      (wrapped as { cause?: unknown }).cause = err;
+      throw wrapped;
     }
   }
 
@@ -497,48 +560,62 @@ export class EvaluationContext implements IEvaluationContext {
 
   /**
    * Expand a value that may contain precompiled ${{ }} templates.
-   * Works recursively over CompiledValues, arrays, and objects.
+   *
+   * Hot path: each unique manifest subtree is compiled once into a tightly-bound
+   * walker closure (no per-call `isCompiledValue` / `Array.isArray` / `typeof` /
+   * `Object.entries` overhead, no recursive method dispatch). The walker tree is
+   * cached by the input value's identity in `walkerCache`, so subsequent calls
+   * with the same manifest data reuse it. The walker reads from `this._context`
+   * — which `expandWith` mutates in place — and emits a fresh container per call
+   * to preserve the original recursive `expand`'s semantics.
    */
   expand(value: unknown): unknown {
-    if (isCompiledValue(value)) {
-      try {
-        return value.call(this._context);
-      } catch (error) {
-        const expr = value.source ? `\${{ ${value.source} }}` : "unknown expression";
-        const msg = error instanceof Error ? error.message : String(error);
-        throw new Error(`Expression ${expr} failed: ${msg}`);
-      }
-    }
-    if (Array.isArray(value)) {
-      return value.map((entry) => this.expand(entry));
-    }
-    if (value !== null && typeof value === "object") {
-      const resolved: Record<string, unknown> = {};
-      for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
-        resolved[key] = this.expand(entry);
-      }
-      return resolved;
-    }
-    return value;
+    if (value === null || typeof value !== "object") return value;
+    const cached = this.walkerCache.get(value as object);
+    if (cached) return cached(this._context);
+    const walker = compileWalker(value);
+    this.walkerCache.set(value as object, walker);
+    return walker(this._context);
   }
 
   /**
    * Expand a value using this context merged with additional properties.
-   * Equivalent to merge(extraContext).expand(value) without allocating a context object.
+   *
+   * Hot path optimisation: rather than allocate a fresh prototype-less object
+   * per call (one allocation + N property copies for N keys in the saved
+   * context), we mutate `_context` in place — adding or overwriting only the
+   * `extraContext` keys — and restore the previous values on exit. Safe because
+   * `expand` is synchronous; cel-vm closures only read from the activation.
    */
   expandWith(value: unknown, extraContext: Record<string, unknown>): unknown {
-    const saved = this._context;
-    this._context = Object.assign(Object.create(null), saved, extraContext) as Record<
-      string,
-      unknown
-    >;
+    const ctx = this._context as Record<string, unknown>;
+    const keys = Object.keys(extraContext);
+    const savedValues: unknown[] = new Array(keys.length);
+    const hadKey: boolean[] = new Array(keys.length);
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i]!;
+      hadKey[i] = k in ctx;
+      if (hadKey[i]) savedValues[i] = ctx[k];
+      ctx[k] = extraContext[k];
+    }
     try {
       return this.expand(value);
     } finally {
-      this._context = saved;
+      for (let i = 0; i < keys.length; i++) {
+        const k = keys[i]!;
+        if (hadKey[i]) ctx[k] = savedValues[i];
+        else delete ctx[k];
+      }
     }
   }
 
+  /** Cache of compiled walker closures keyed on the manifest subtree they walk.
+   *  WeakMap so entries are GC'd if the manifest is reloaded. */
+  private readonly walkerCache = new WeakMap<
+    object,
+    (ctx: Record<string, unknown>) => unknown
+  >();
+
 /**
    * Expand specific dot-paths within an object. '**' expands the entire object.
    * Paths listed in excludePaths are left untouched (runtime takes precedence).

package/src/index.ts

@@ -1,7 +1,8 @@
 export { ControllerLoader } from "./controller-loader.js";
 export { ControllerRegistry } from "./controller-registry.js";
 export { EvaluationContext } from "./evaluation-context.js";
-export { LocalFileAdapter } from "./manifest-adapters/local-file-adapter.js";
+export { LocalFileSource } from "./manifest-sources/local-file-source.js";
+export { MemorySource } from "./manifest-sources/memory-source.js";
 export { EventStream } from "./event-stream.js";
 export { ExecutionContext } from "./execution-context.js";
 export { Kernel, type KernelOptions } from "./kernel.js";