@telorun/kernel 0.2.5 → 0.2.7

package/src/kernel.ts

@@ -1,6 +1,6 @@
+import { AnalysisRegistry, Loader, StaticAnalyzer } from "@telorun/analyzer";
 import {
   ControllerContext,
-  EvaluationContext,
   Kernel as IKernel,
   ModuleContext,
   ResourceContext,
@@ -9,58 +9,61 @@ import {
   ResourceManifest,
   RuntimeError,
   RuntimeEvent,
+  isCompiledValue,
+  type ParsedArgs,
 } from "@telorun/sdk";
 import * as path from "path";
+import { parseArgs } from "util";
 import { ControllerRegistry } from "./controller-registry.js";
 import { EventStream } from "./event-stream.js";
 import { EventBus } from "./events.js";
-import { Loader } from "./loader.js";
+import { LocalFileAdapter } from "./manifest-adapters/local-file-adapter.js";
 import { ResourceContextImpl } from "./resource-context.js";
 import { SchemaValidator } from "./schema-valiator.js";
 
+export interface KernelOptions {
+  stdin?: NodeJS.ReadableStream;
+  stdout?: NodeJS.WritableStream;
+  stderr?: NodeJS.WritableStream;
+  env?: Record<string, string | undefined>;
+  argv?: string[];
+}
+
 /**
  * Kernel: Central orchestrator managing lifecycle and message bus
  * Handles resource loading, initialization, and execution through controllers
  */
 export class Kernel implements IKernel {
-  private loader: Loader = new Loader();
-  // private manifests: ManifestRegistry = new ManifestRegistry();
+  private readonly loader = new Loader();
+  private readonly analyzer = new StaticAnalyzer();
+  private readonly registry = new AnalysisRegistry();
   private controllers: ControllerRegistry = new ControllerRegistry();
   private eventBus: EventBus = new EventBus();
   private eventStream: EventStream = new EventStream();
-  // private snapshotSerializer: SnapshotSerializer = new SnapshotSerializer();
-  // private runtimeManifests: ResourceManifest[] | null = null;
-  // private resourceInstances: Map<
-  //   string,
-  //   { resource: ResourceManifest; instance: ResourceInstance }
-  // > = new Map();
-  private resourceEventBuses: Map<string, EventBus> = new Map();
+
   private holdCount = 0;
   private idleResolvers: Array<() => void> = [];
   private _exitCode = 0;
-  // private bootContextRegistry = new BootContextRegistry();
   private readonly sharedSchemaValidator = new SchemaValidator();
   private rootContext!: ModuleContext;
-
-  constructor() {
+  private staticManifests: ResourceManifest[] = [];
+
+  readonly stdin: NodeJS.ReadableStream;
+  readonly stdout: NodeJS.WritableStream;
+  readonly stderr: NodeJS.WritableStream;
+  readonly env: Record<string, string | undefined>;
+  readonly argv: string[];
+
+  constructor(options: KernelOptions = {}) {
+    this.stdin = options.stdin ?? process.stdin;
+    this.stdout = options.stdout ?? process.stdout;
+    this.stderr = options.stderr ?? process.stderr;
+    this.env = options.env ?? process.env;
+    this.argv = options.argv ?? [];
+    this.loader.register(new LocalFileAdapter());
     this.setupEventStreaming();
   }
 
-  // async teardownResource(module: string, kind: string, name: string): Promise<void> {
-  //   const key = this.getResourceKey(module, kind, name);
-  //   const entry = this.resourceInstances.get(key);
-  //   if (!entry) return;
-  //   const { resource, instance } = entry;
-  //   if (instance.teardown) {
-  //     await instance.teardown();
-  //   }
-  //   await this.eventBus.emit(`${resource.kind}.${resource.metadata.name}.Teardown`, {
-  //     resource: { kind: resource.kind, name: resource.metadata.name },
-  //   });
-  //   // this.resourceInstances.delete(key);
-  //   this.resourceEventBuses.delete(key);
-  // }
-
   async registerController(
     moduleName: string,
     kindName: string,
@@ -73,16 +76,9 @@ export class Kernel implements IKernel {
   /**
    * Register a resource definition with the controller registry
    */
-  registerResourceDefinition(
-    definition: ResourceDefinition,
-    // basePath?: string,
-    // namespace?: string | null,
-  ): void {
+  registerResourceDefinition(definition: ResourceDefinition): void {
     this.controllers.registerDefinition(definition);
-  }
-
-  registerCapability(name: string, schema?: Record<string, any>): void {
-    this.controllers.registerCapability(name, schema);
+    this.registry.registerDefinition(definition);
   }
 
   getModuleContext(_moduleName: string): ModuleContext {
@@ -100,14 +96,14 @@ export class Kernel implements IKernel {
     kinds: string[],
   ): void {
     this.rootContext.registerImport(alias, targetModule, kinds);
+    this.registry.registerImport(alias, targetModule, kinds);
   }
 
-  isCapabilityRegistered(name: string): boolean {
-    return this.controllers.isCapabilityRegistered(name);
-  }
-
-  getCapabilitySchema(name: string): Record<string, any> | null | undefined {
-    return this.controllers.getCapabilitySchema(name);
+  /** Returns the live analysis registry backed by this kernel's known definitions and aliases.
+   *  Pass to StaticAnalyzer.analyze() for incremental validation of new manifests against
+   *  already-registered types (e.g. front-end editor validating a manifest before submitting). */
+  getAnalysisRegistry(): AnalysisRegistry {
+    return this.registry;
   }
 
   /**
@@ -120,81 +116,92 @@ export class Kernel implements IKernel {
     // Declare built-in module namespaces upfront so getContext() can distinguish
     // "not yet populated" from a completely unknown module name.
     this.rootContext.registerImport("Kernel", "Kernel", []); // built-ins, unrestricted
-    // this.moduleContextRegistry.declareModule("default"); // user resources with no module field
 
-    this.controllers.registerDefinition({
-      kind: "Kernel.Definition",
-      metadata: { name: "Definition", module: "Kernel" },
-      capabilities: ["template"],
-      schema: { type: "object" },
-    });
+    // Register built-in definitions with the controller registry.
+    // AnalysisRegistry's underlying DefinitionRegistry already seeds KERNEL_BUILTINS on construction.
+    for (const def of this.registry.builtinDefinitions()) this.controllers.registerDefinition(def);
+
     this.controllers.registerController(
       "Kernel.Definition",
       await import("./controllers/resource-definition/resource-definition-controller.js"),
     );
-    this.controllers.registerDefinition({
-      kind: "Kernel.Definition",
-      metadata: { name: "Module", module: "Kernel" },
-      capabilities: ["template"],
-      schema: { type: "object" },
-    });
     this.controllers.registerController(
       "Kernel.Module",
       await import("./controllers/module/module-controller.js"),
     );
-    this.controllers.registerDefinition({
-      kind: "Kernel.Definition",
-      metadata: { name: "Import", module: "Kernel" },
-      capabilities: ["template"],
-      schema: { type: "object" },
-    });
     this.controllers.registerController(
       "Kernel.Import",
       await import("./controllers/module/import-controller.js"),
     );
-    this.controllers.registerDefinition({
-      kind: "Kernel.Definition",
-      metadata: { name: "Capability", module: "Kernel" },
-      capabilities: ["template"],
-      schema: { type: "object" },
-    });
-    this.controllers.registerController(
-      "Kernel.Capability",
-      await import("./controllers/capability/capability-controller.js"),
-    );
   }
 
   /**
    * Load from runtime configuration file
    */
   async loadFromConfig(runtimeYamlPath: string): Promise<void> {
+    const resolvedUrl = new URL(runtimeYamlPath, `file://${process.cwd()}/`).href;
+    const sourceUrl = await this.loader.resolveEntryPoint(resolvedUrl);
     this.rootContext = new ModuleContext(
-      this.loader.resolvePath(`file://${process.cwd()}/`, runtimeYamlPath),
+      sourceUrl,
       {},
       {},
       {},
       [],
       this._createInstance.bind(this),
       (event, payload) => this.eventBus.emit(event, payload),
+      this.env,
     );
     // Initialize built-in Runtime definitions first
     await this.loadBuiltinDefinitions();
 
-    // Load built-in capability manifests before user configuration so that
-    // capability resources are available in the first initialization pass
-    const { fileURLToPath } = await import("url");
-    const capabilitiesDir = fileURLToPath(new URL("./capabilities/", import.meta.url));
-    const capabilityManifests = await this.loader.loadDirectory(capabilitiesDir);
+    // Phase 5: attach injection hook — fires between create() and init() for every resource
+    this.rootContext.preInitHook = (resource, getInstance) =>
+      this._injectDependencies(resource, getInstance);
+
+    // 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);
+    this.staticManifests = staticManifests;
+
+    // Register module identities for x-telo-ref resolution (Phase 3 prerequisite).
+    // Kernel built-ins ("kernel" → "Kernel") are auto-registered when Kernel.Abstract
+    // definitions are registered in loadBuiltinDefinitions() above.
+    for (const m of staticManifests) {
+      if (m.kind === "Kernel.Module" && m.metadata?.name && m.metadata?.namespace) {
+        this.registry.registerModuleIdentity(
+          m.metadata.namespace as string,
+          m.metadata.name as string,
+        );
+      }
+    }
+
+    const errors = this.analyzer.analyzeErrors(staticManifests, {}, this.registry);
+    if (errors.length > 0) {
+      throw new RuntimeError(
+        "ERR_MANIFEST_VALIDATION_FAILED",
+        "Manifest validation failed",
+        errors.map((d) => ({
+          severity: "error" as const,
+          message: d.message,
+          code: d.code !== undefined ? String(d.code) : undefined,
+          resource: (d.data as any)?.resource
+            ? `${(d.data as any).resource.kind}.${(d.data as any).resource.name}`
+            : undefined,
+        })),
+      );
+    }
 
     // Load runtime configuration — root module gets access to host env
-    const userManifests = await this.loader.loadManifest(
-      runtimeYamlPath,
-      `file://${process.cwd()}/`,
-      { env: process.env },
-    );
-    const allManifests = [...capabilityManifests, ...userManifests];
+    const allManifests = await this.loader.loadModule(sourceUrl, { compile: true });
+
+    // 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.
+    // Update staticManifests so Phase 3 (validateReferences) and Phase 4 (DAG) see
+    // the same normalized structure.
+    const normalizedManifests = this.analyzer.normalize(allManifests, this.registry);
+    this.staticManifests = normalizedManifests;
 
-    for (const manifest of allManifests) {
+    for (const manifest of normalizedManifests) {
       if (manifest.kind === "Kernel.Module") {
         this.rootContext.setSecrets(manifest.secrets ?? {});
         this.rootContext.setVariables(manifest.variables ?? {});
@@ -226,6 +233,36 @@ export class Kernel implements IKernel {
       }
     }
 
+    // Phase 3+4: reference validation, cycle detection, and topo sort
+    const {
+      diagnostics: refErrors,
+      order,
+      cycleError,
+    } = this.analyzer.prepare(this.staticManifests, this.registry);
+    if (refErrors.length > 0) {
+      throw new RuntimeError(
+        "ERR_MANIFEST_VALIDATION_FAILED",
+        "Manifest validation failed",
+        refErrors.map((d) => ({
+          severity: "error" as const,
+          message: d.message,
+          code: d.code !== undefined ? String(d.code) : undefined,
+          resource: (d.data as any)?.resource
+            ? `${(d.data as any).resource.kind}.${(d.data as any).resource.name}`
+            : undefined,
+        })),
+      );
+    }
+    if (cycleError) {
+      throw new RuntimeError("ERR_CIRCULAR_DEPENDENCY", cycleError);
+    }
+
+    // Phase 5: sort pending resources into topo order so injection always finds
+    // initialized dependencies, then run the init loop.
+    if (order) {
+      this.rootContext.setInitOrder(order);
+    }
+
     // Initialize resources
     try {
       await this.rootContext.initializeResources();
@@ -241,14 +278,6 @@ export class Kernel implements IKernel {
     }
   }
 
-  // async runInstances(): Promise<void> {
-  //   for (const { instance } of this.resourceInstances.values()) {
-  //     if (instance.run) {
-  //       await instance.run();
-  //     }
-  //   }
-  // }
-
   async emitRuntimeEvent(event: string, payload?: any): Promise<void> {
     await this.eventBus.emit(event, payload);
   }
@@ -327,7 +356,7 @@ export class Kernel implements IKernel {
       },
       acquireHold: (reason?: string) => this.acquireHold(reason),
       expandValue: (value: any, context: Record<string, any>) =>
-        this.rootContext.merge(context).expand(value),
+        this.rootContext.expandWith(value, context),
       requestExit: (code: number) => this.requestExit(code),
     };
   }
@@ -335,25 +364,62 @@ export class Kernel implements IKernel {
   private createResourceContext(
     moduleContext: ModuleContext,
     resource: ResourceManifest,
+    args?: ParsedArgs,
   ): ResourceContext {
     return new ResourceContextImpl(
       this,
       moduleContext,
       resource.metadata,
       this.sharedSchemaValidator,
+      this.stdin,
+      this.stdout,
+      this.stderr,
+      args,
     );
   }
 
   /**
-   * Create a resource instance: resolves the controller, validates the schema,
-   * calls create/init, registers context providers, stores the snapshot, and
-   * mirrors the instance into the Kernel-level and module-level registries.
-   * Returns null when the controller is not yet registered (retry signal).
+   * Parse kernel.argv using a controller's args spec (if present).
+   * If the controller exports no args spec, does a generic parse.
+   */
+  private parseArgsForController(controller: any): ParsedArgs {
+    if (this.argv.length === 0) return { _: [] };
+
+    const argSpec = controller.args;
+    if (argSpec) {
+      const options: Record<string, { type: "string" | "boolean"; short?: string }> = {};
+      for (const [name, def] of Object.entries(argSpec) as [string, any][]) {
+        options[name] = { type: def.type ?? "string" };
+        if (def.alias) options[name].short = def.alias;
+      }
+      const { values, positionals } = parseArgs({
+        args: this.argv,
+        options,
+        allowPositionals: true,
+        strict: false,
+      });
+      return { ...values, _: positionals } as ParsedArgs;
+    }
+
+    // Generic parse: no spec, best-effort
+    const { values, positionals } = parseArgs({
+      args: this.argv,
+      allowPositionals: true,
+      strict: false,
+    });
+    return { ...values, _: positionals } as ParsedArgs;
+  }
+
+  /**
+   * Create phase only: resolves the controller, validates the schema, and calls
+   * controller.create(). Returns { instance, ctx } so initializeResources can
+   * run init() separately in its second phase. Returns null when the controller
+   * is not yet registered (retry signal).
    */
   private async _createInstance(
     evalContext: ModuleContext,
     resource: ResourceManifest,
-  ): Promise<ResourceInstance | null> {
+  ): Promise<{ instance: ResourceInstance; ctx: ResourceContext } | null> {
     const kind = resource.kind;
 
     // Resolve the alias-prefixed kind to its real fully-qualified kind.
@@ -379,8 +445,27 @@ export class Kernel implements IKernel {
       throw new Error(`No schema defined for ${kind} controller`);
     }
 
+    // Resolve eval paths from x-telo-eval annotations in the parent and own schema
+    const definition = this.controllers.getDefinition(resolvedKind);
+    const parentDef = definition?.capability
+      ? this.controllers.getDefinition(definition.capability)
+      : undefined;
+    const parentEval = parentDef?.schema
+      ? buildEvalPaths(parentDef.schema)
+      : { compile: [], runtime: [] };
+    const ownEval = definition?.schema
+      ? buildEvalPaths(definition.schema)
+      : { compile: [], runtime: [] };
+    const compile = [...parentEval.compile, ...ownEval.compile];
+    const runtime = [...parentEval.runtime, ...ownEval.runtime];
+
+    // Schema validation runs before CEL evaluation so it sees the original manifest
+    // shape. CompiledValue wrappers (from load-time precompilation) are stripped,
+    // restoring the pre-CEL string view that the schema expects.
     try {
-      this.sharedSchemaValidator.compile(controller.schema).validate(resource);
+      this.sharedSchemaValidator
+        .compile(controller.schema)
+        .validate(stripCompiledValues(resource, controller.schema as Record<string, unknown>));
     } catch (error) {
       throw new RuntimeError(
         "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED",
@@ -388,138 +473,56 @@ export class Kernel implements IKernel {
       );
     }
 
-    const ctx = this.createResourceContext(evalContext, resource);
-    const instance = await controller.create(resource, ctx);
+    // Expand compile-time CEL fields before passing to the controller.
+    const processedResource = compile.length
+      ? (evalContext.expandPaths(
+          resource as Record<string, unknown>,
+          compile,
+          runtime,
+        ) as ResourceManifest)
+      : resource;
+
+    const parsedArgs = this.parseArgsForController(controller);
+    const ctx = this.createResourceContext(evalContext, processedResource, parsedArgs);
+    const instance = await controller.create(processedResource, ctx);
     if (!instance) return null;
 
-    if (instance.init) await instance.init(ctx);
-
-    // if (isContextProvider(instance)) {
-    //   this.bootContextRegistry.register(
-    //     resource.kind,
-    //     resource.metadata.name,
-    //     resource.metadata.module,
-    //     resource.grants as string[] | undefined,
-    //     instance.provideContext(),
-    //   );
-    // }
-
-    if (instance.snapshot) {
-      const snap = await Promise.resolve(instance.snapshot()).catch(() => ({}));
-      if (evalContext instanceof ModuleContext) {
-        evalContext.setResource(resource.metadata.name, (snap as Record<string, unknown>) ?? {});
-      }
-    }
-
-    return instance;
-  }
+    if (!runtime.length) return { instance, ctx };
 
-  /**
-   * Tear down all resource instances owned by a dynamically-spawned context,
-   * cascading depth-first through its children. Removes entries from both
-   * ctx.resourceInstances and the Kernel-level resourceInstances map, and
-   * emits Teardown events (matching the behaviour of teardownResource()).
-   */
-  async teardownContext(ctx: EvaluationContext): Promise<void> {
-    for (const child of [...ctx.children].reverse()) {
-      await this.teardownContext(child);
-    }
-    const entries = [...ctx.resourceInstances.entries()].reverse();
-    for (const [key, { resource, instance }] of entries) {
-      if (instance.teardown) await instance.teardown();
-      await this.eventBus.emit(`${resource.kind}.${resource.metadata.name}.Teardown`, {
-        resource: { kind: resource.kind, name: resource.metadata.name },
-      });
-      // this.resourceInstances.delete(key);
-      ctx.resourceInstances.delete(key);
-      this.resourceEventBuses.delete(key);
-    }
+    const wrapped: ResourceInstance = {
+      ...instance,
+      invoke: async (inputs: any) => {
+        const expanded = evalContext.expandPaths(inputs as Record<string, unknown>, runtime);
+        return instance.invoke!(expanded);
+      },
+    };
+    return { instance: wrapped, ctx };
   }
 
-  // getResourcesByKind(kind: string): RuntimeResource[] {
-  //   const resources: RuntimeResource[] = [];
-  //   for (const entry of this.resourceInstances.values()) {
-  //     if (entry.resource.kind === kind) {
-  //       resources.push(entry.instance as any);
-  //     }
-  //   }
-  //   return resources;
-  // }
-
-  // getResourceByName(declaringModule: string, alias: string, name: string): RuntimeResource | null {
-  //   const realModule = this.moduleContextRegistry.resolveAlias(declaringModule, alias) ?? alias;
-  //   for (const { resource, instance } of this.resourceInstances.values()) {
-  //     if (resource.metadata.module === realModule && resource.metadata.name === name) {
-  //       return instance as RuntimeResource;
-  //     }
-  //   }
-  //   return null;
-  // }
-
-  /**
-   * Returns the unique set of local file paths from which resources were loaded.
-   * HTTP/HTTPS sources are excluded — they cannot be watched on disk.
-   */
-  // getSourceFiles(): string[] {
-  //   const seen = new Set<string>();
-  //   for (const { resource } of this.resourceInstances.values()) {
-  //     const src = resource.metadata.source;
-  //     if (src && !src.startsWith("http://") && !src.startsWith("https://")) {
-  //       seen.add(src);
-  //     }
-  //   }
-  //   return Array.from(seen);
-  // }
-
   /**
-   * Reload all resources that were loaded from the given source file.
-   * Safe order: parse first → if parse succeeds, tear down old → init new → run new only.
+   * Phase 5 — Inject live instances into reference fields of a resource config.
+   *
+   * Called between create() and init() for every resource. Walks the definition's
+   * field map and replaces each {kind, name} reference value (outside scope visibility
+   * paths) with the live ResourceInstance returned by getInstance(name). Fields within
+   * scope paths are left as {kind, name} — the controller resolves them at runtime.
    */
-  // async reloadSource(sourcePath: string): Promise<void> {
-  //   // Parse first — bail before touching running resources if the file is invalid
-  //   const newManifests = await this.loader.loadManifest(sourcePath, `file://${process.cwd()}/`, {
-  //     env: process.env,
-  //   });
-
-  //   // Collect keys of resources loaded from this source (in insertion order)
-  //   const keysFromSource: string[] = [];
-  //   for (const [key, { resource }] of this.resourceInstances.entries()) {
-  //     if (resource.metadata.source === sourcePath) {
-  //       keysFromSource.push(key);
-  //     }
-  //   }
-  //   // Tear down in reverse order (children first via cascade)
-  //   for (const key of [...keysFromSource].reverse()) {
-  //     const entry = this.resourceInstances.get(key);
-  //     if (!entry) continue; // already removed by a cascade
-  //     await this.teardownResource(
-  //       entry.resource.metadata.module,
-  //       entry.resource.kind,
-  //       entry.resource.metadata.name,
-  //     );
-  //   }
-
-  //   for (const manifest of newManifests) {
-  //     this.rootContext.registerManifest(manifest);
-  //   }
-  //   const keysBefore = new Set(this.resourceInstances.keys());
-  //   await this.initializeResources();
-
-  //   // Run only newly created instances (not all instances — avoids double-run)
-  //   const newKeys = Array.from(this.resourceInstances.keys()).filter((k) => !keysBefore.has(k));
-  //   for (const key of newKeys) {
-  //     const entry = this.resourceInstances.get(key);
-  //     if (entry?.instance.run) {
-  //       await entry.instance.run();
-  //     }
-  //   }
-  // }
-
-  private getResourceKey(module: string, kind: string, name: string): string {
-    if (!kind.includes(".")) {
-      throw new Error(`Resource kind must include module prefix: ${kind}`);
-    }
-    return `${module}.${kind}.${name}`;
+  private _injectDependencies(
+    resource: ResourceManifest,
+    getInstance: (name: string) => ResourceInstance | undefined,
+  ): void {
+    this.registry.iterateFieldEntries(
+      resource,
+      (fieldPath) => injectAtPath(resource, fieldPath, getInstance),
+      (fieldPath) => {
+        const val = (resource as Record<string, unknown>)[fieldPath];
+        if (Array.isArray(val)) {
+          (resource as Record<string, unknown>)[fieldPath] = this.rootContext.createScopeHandle(
+            val as ResourceManifest[],
+          );
+        }
+      },
+    );
   }
 
   /**
@@ -556,3 +559,138 @@ export class Kernel implements IKernel {
     };
   }
 }
+
+/** Returns a schema-appropriate placeholder value for a CompiledValue field. */
+function placeholderForSchema(schema: Record<string, unknown>): unknown {
+  if (schema.default !== undefined) return schema.default;
+  switch (schema.type) {
+    case "integer":
+    case "number":
+      return (schema.minimum as number | undefined) ?? 0;
+    case "boolean":
+      return false;
+    case "array":
+      return [];
+    case "object":
+      return {};
+    default:
+      return "";
+  }
+}
+
+/** Replaces CompiledValue wrappers with schema-appropriate placeholders for schema validation.
+ *  Template strings were compiled from YAML at load time; this restores a shape
+ *  that AJV can validate without evaluating expressions. */
+function stripCompiledValues(v: unknown, schema: Record<string, unknown> = {}): unknown {
+  if (isCompiledValue(v)) return placeholderForSchema(schema);
+  if (Array.isArray(v)) {
+    const itemSchema = (schema.items ?? {}) as Record<string, unknown>;
+    return v.map((item) => stripCompiledValues(item, itemSchema));
+  }
+  if (v !== null && typeof v === "object") {
+    const props = (schema.properties ?? {}) as Record<string, Record<string, unknown>>;
+    const out: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+      out[k] = stripCompiledValues(val, props[k] ?? {});
+    }
+    return out;
+  }
+  return v;
+}
+
+/**
+ * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal).
+ * For each leaf value that looks like a {kind, name} reference, calls getInstance(name)
+ * and replaces the value in-place with the returned live ResourceInstance.
+ * Values where getInstance returns undefined are left unchanged.
+ */
+/**
+ * Traverses a definition schema and collects all paths annotated with `x-telo-eval`.
+ * Root-level `x-telo-eval` produces the `"**"` wildcard (expand all fields).
+ * Property-level annotations produce the dot-notation path to that property.
+ */
+function buildEvalPaths(schema: Record<string, any>): { compile: string[]; runtime: string[] } {
+  const compile: string[] = [];
+  const runtime: string[] = [];
+
+  if (schema["x-telo-eval"] === "compile") compile.push("**");
+  else if (schema["x-telo-eval"] === "runtime") runtime.push("**");
+
+  if (schema.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties as Record<string, any>)) {
+      collectEvalPathsNode(propSchema, key, compile, runtime);
+    }
+  }
+
+  return { compile, runtime };
+}
+
+function collectEvalPathsNode(
+  node: Record<string, any>,
+  path: string,
+  compile: string[],
+  runtime: string[],
+): void {
+  if (node["x-telo-eval"] === "compile") {
+    compile.push(path);
+    return;
+  }
+  if (node["x-telo-eval"] === "runtime") {
+    runtime.push(path);
+    return;
+  }
+  if (node.properties) {
+    for (const [key, propSchema] of Object.entries(node.properties as Record<string, any>)) {
+      collectEvalPathsNode(propSchema, `${path}.${key}`, compile, runtime);
+    }
+  }
+}
+
+function injectAtPath(
+  resource: ResourceManifest,
+  fieldPath: string,
+  getInstance: (name: string) => ResourceInstance | undefined,
+): void {
+  const parts = fieldPath.split(".");
+
+  function traverse(obj: unknown, partsLeft: string[]): void {
+    if (!obj || typeof obj !== "object" || partsLeft.length === 0) return;
+    const [head, ...rest] = partsLeft;
+    const isArr = head.endsWith("[]");
+    const key = isArr ? head.slice(0, -2) : head;
+    const container = obj as Record<string, unknown>;
+    const val = container[key];
+    if (val == null) return;
+
+    if (isArr) {
+      if (!Array.isArray(val)) return;
+      for (let i = 0; i < val.length; i++) {
+        const elem = val[i];
+        if (!elem || typeof elem !== "object") continue;
+        if (rest.length === 0) {
+          const ref = elem as Record<string, unknown>;
+          if (typeof ref.kind === "string" && typeof ref.name === "string") {
+            const instance = getInstance(ref.name);
+            if (instance) val[i] = instance;
+          }
+        } else {
+          traverse(elem, rest);
+        }
+      }
+    } else {
+      if (rest.length === 0) {
+        if (val && typeof val === "object" && !Array.isArray(val)) {
+          const ref = val as Record<string, unknown>;
+          if (typeof ref.kind === "string" && typeof ref.name === "string") {
+            const instance = getInstance(ref.name);
+            if (instance) container[key] = instance;
+          }
+        }
+      } else {
+        traverse(val, rest);
+      }
+    }
+  }
+
+  traverse(resource, parts);
+}