@telorun/kernel 0.14.0 → 0.16.0

package/src/kernel.ts

@@ -19,6 +19,7 @@ import {
   ResourceManifest,
   RuntimeError,
   RuntimeEvent,
+  type BootTarget,
   type EvaluationContext as IEvaluationContext,
   type ModuleContext as IModuleContext,
   type LoadOptions,
@@ -380,7 +381,14 @@ export class Kernel implements IKernel {
     // 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);
+    // Pass the analyzer-flattened set (entry + forwarded library exports) as cross-module
+    // resolution targets so `!ref Alias.name` in the entry-only runtime manifests resolves
+    // to imported libraries' exported instances.
+    const normalizedManifests = this.analyzer.normalize(
+      allManifests,
+      this.registry,
+      staticManifests,
+    );
     this.staticManifests = normalizedManifests;
 
     let rootApplicationManifest: ResourceManifest | undefined;
@@ -392,25 +400,32 @@ export class Kernel implements IKernel {
         // `process.env` after the manifest loop so imports can read
         // `${{ variables.X }}` during their own init.
         //
-        // Targets normalize down to bare names regardless of source surface.
-        // The analyzer's `resolveRefSentinels` pass already substituted any
-        // `!ref <name>` to `{kind, name}`; bare-string forms pass through.
-        // Anything else (e.g. an unresolved sentinel because the analyzer
-        // couldn't see it, or a malformed manifest) is a hard error —
-        // silently dropping the entry would leave the user staring at a
-        // "no targets ran" outcome with no signal where it went wrong.
+        // Targets are preserved as their full shape so the boot runner can
+        // evaluate `when` guards and inline invoke steps. The analyzer's
+        // `resolveRefSentinels` pass already substituted any `!ref <name>` to
+        // `{kind, name}` (including inside an inline target's `invoke`).
+        // Recognized shapes: bare string ref, resolved `{kind, name}`, gated
+        // `{ ref, when? }`, and inline `{ name?, invoke, inputs?, when?, retry? }`.
+        // Anything else (e.g. an unresolved sentinel, or a malformed manifest)
+        // is a hard error — silently dropping the entry would leave the user
+        // staring at a "no targets ran" outcome with no signal.
         const rawTargets = (manifest.targets ?? []) as unknown[];
-        const targetNames = rawTargets.map((t, index) => {
-          if (typeof t === "string") return t;
-          if (t && typeof t === "object" && typeof (t as { name?: unknown }).name === "string") {
-            return (t as { name: string }).name;
+        rawTargets.forEach((t, index) => {
+          const ok =
+            typeof t === "string" ||
+            (!!t &&
+              typeof t === "object" &&
+              (typeof (t as { name?: unknown }).name === "string" ||
+                (t as { ref?: unknown }).ref != null ||
+                (t as { invoke?: unknown }).invoke !== undefined));
+          if (!ok) {
+            throw new RuntimeError(
+              "ERR_INVALID_VALUE",
+              `Telo.Application '${(manifest.metadata as { name?: string } | undefined)?.name ?? "(unnamed)"}' targets[${index}] is not a recognized target shape. Got: ${JSON.stringify(t)}`,
+            );
           }
-          throw new RuntimeError(
-            "ERR_INVALID_VALUE",
-            `Telo.Application '${(manifest.metadata as { name?: string } | undefined)?.name ?? "(unnamed)"}' targets[${index}] could not be normalized to a resource name. Got: ${JSON.stringify(t)}`,
-          );
         });
-        this.rootContext.setTargets(targetNames);
+        this.rootContext.setTargets(rawTargets as BootTarget[]);
         if (manifest.kind === "Telo.Application") {
           rootApplicationManifest = manifest;
         }
@@ -847,7 +862,7 @@ export class Kernel implements IKernel {
    */
   private _injectDependencies(
     resource: ResourceManifest,
-    getInstance: (name: string) => ResourceInstance | undefined,
+    getInstance: (name: string, alias?: string) => ResourceInstance | undefined,
   ): void {
     this.registry.iterateFieldEntries(
       resource,
@@ -1031,10 +1046,28 @@ function collectEvalPathsNode(
 function injectAtPath(
   resource: ResourceManifest,
   fieldPath: string,
-  getInstance: (name: string) => ResourceInstance | undefined,
+  getInstance: (name: string, alias?: string) => ResourceInstance | undefined,
 ): void {
   const parts = fieldPath.split(".");
 
+  // Resolve a {kind, name, alias?} reference to its live instance. A non-`Self` alias is a
+  // cross-module reference into an import's published exports; if that import hasn't
+  // finished init() yet the instance is absent, so we throw to defer this resource to a
+  // later pass of the multi-pass init loop (which catches and retries) rather than leaving
+  // the ref unresolved. Local refs (no alias) that miss are left for topo ordering / later
+  // diagnostics, matching prior behaviour.
+  function resolveInto(ref: Record<string, unknown>): ResourceInstance | undefined {
+    const alias = typeof ref.alias === "string" ? ref.alias : undefined;
+    const instance = getInstance(ref.name as string, alias);
+    if (!instance && alias && alias !== "Self") {
+      throw new RuntimeError(
+        "ERR_CROSS_MODULE_REF_PENDING",
+        `Cross-module reference '${alias}.${String(ref.name)}' is not available yet (import not initialized)`,
+      );
+    }
+    return instance;
+  }
+
   function traverse(obj: unknown, partsLeft: string[]): void {
     if (!obj || typeof obj !== "object" || partsLeft.length === 0) return;
     const [head, ...rest] = partsLeft;
@@ -1049,7 +1082,7 @@ function injectAtPath(
         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);
+            const instance = resolveInto(ref);
             if (instance) container[mapKey] = instance;
           }
         } else {
@@ -1073,7 +1106,7 @@ function injectAtPath(
         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);
+            const instance = resolveInto(ref);
             if (instance) val[i] = instance;
           }
         } else {
@@ -1085,7 +1118,7 @@ function injectAtPath(
         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);
+            const instance = resolveInto(ref);
             if (instance) container[key] = instance;
           }
         }

package/src/module-context.ts

@@ -1,7 +1,12 @@
+import { executeInvokeStep } from "@telorun/sdk";
 import type {
+  BootTarget,
   ControllerPolicy,
   Invocable,
+  InvokeStep,
+  InvokeStepContext,
   ModuleContext as IModuleContext,
+  ResourceInstance,
 } from "@telorun/sdk";
 import type { EmitEvent, InstanceFactory } from "@telorun/sdk";
 import { EvaluationContext } from "./evaluation-context.js";
@@ -68,6 +73,18 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   /** Maps import alias → allowed kind names. Absent entry = unrestricted (e.g. Kernel). */
   private readonly importedKinds = new Map<string, Set<string>>();
 
+  /** Maps import alias → its child context's exported instances. Registered by the
+   *  Telo.Import controller; read when resolving a cross-module `!ref Alias.name`
+   *  reference (Phase 5 injection and boot targets). `names` is the import's
+   *  `exports.resources` gate — only listed instances are reachable. */
+  private readonly importedScopes = new Map<
+    string,
+    {
+      names: Set<string>;
+      get: (name: string) => { kind: string; instance: ResourceInstance } | undefined;
+    }
+  >();
+
   /**
    * Resolved controller-selection policy for this module's `Telo.Definition`s.
    * Stamped by the parent `Telo.Import` controller from the import's `runtime:`
@@ -82,7 +99,7 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     variables: Record<string, unknown> = {},
     secrets: Record<string, unknown> = {},
     resources: Record<string, unknown> = {},
-    private targets: string[] = [],
+    private targets: BootTarget[] = [],
     createInstance: InstanceFactory = async () => null,
     emit: EmitEvent,
     private readonly _hostEnv?: Record<string, string | undefined>,
@@ -120,7 +137,7 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     this._rebuildContext();
   }
 
-  setTargets(vars: string[]): void {
+  setTargets(vars: BootTarget[]): void {
     this.targets = vars;
   }
 
@@ -157,6 +174,37 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
     }
   }
 
+  /** Register an import alias's exported instances for cross-module reference resolution.
+   *  `names` is the gate (the import's `exports.resources`); `get` reads the child context's
+   *  live instance + its canonical kind lazily — they exist only after the import's `init()`
+   *  runs. */
+  registerImportedScope(
+    alias: string,
+    names: string[],
+    get: (name: string) => { kind: string; instance: ResourceInstance } | undefined,
+  ): void {
+    this.importedScopes.set(alias, { names: new Set(names), get });
+  }
+
+  /** Resolve `Alias.name` to a live exported instance, gated by `exports.resources`.
+   *  Returns undefined when the alias is unknown, the name isn't exported, or the import
+   *  hasn't initialized its instances yet (the injection path defers and retries). */
+  override resolveImportedInstance(alias: string, name: string): ResourceInstance | undefined {
+    const scope = this.importedScopes.get(alias);
+    if (!scope || !scope.names.has(name)) return undefined;
+    return scope.get(name)?.instance;
+  }
+
+  /** Like `resolveImportedInstance`, but returns the `{kind, name}` ref (canonical kind)
+   *  for controllers that resolve step/handler invokes to refs rather than live instances
+   *  (e.g. Run.Sequence via `resolveChildren`). The alias is reattached by the caller. */
+  resolveImportedRef(alias: string, name: string): { kind: string; name: string } | undefined {
+    const scope = this.importedScopes.get(alias);
+    if (!scope || !scope.names.has(name)) return undefined;
+    const entry = scope.get(name);
+    return entry ? { kind: entry.kind, name } : undefined;
+  }
+
   hasImport(alias: string): boolean {
     return this.importAliases.has(alias);
   }
@@ -256,8 +304,57 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
   }
 
   async runTargets() {
-    for (const target of this.targets) {
-      await this.run(target);
+    const steps: Record<string, unknown> = {};
+    const stepCtx: InvokeStepContext = {
+      expandValue: (value, context) => this.expandWith(value, context),
+      invoke: (kind, name, inputs) => this.invoke(kind, name, inputs),
+      invokeResolved: (kind, name, instance, inputs) =>
+        this.invokeResolved(kind, name, instance, inputs),
+      resolveImportedInstance: (alias, name) => this.resolveImportedInstance(alias, name),
+    };
+    for (let i = 0; i < this.targets.length; i++) {
+      const target = this.targets[i]!;
+      if (typeof target === "string") {
+        await this.run(target);
+        continue;
+      }
+      if ("invoke" in target && target.invoke !== undefined) {
+        const step: InvokeStep = {
+          name: target.name ?? `Target${i}`,
+          when: target.when,
+          // A cross-module `!ref Alias.name` stays a `{kind, name, alias}` ref; the leaf's
+          // alias branch resolves it via `resolveImportedInstance` and dispatches through
+          // `invokeResolved` so invocation events and error wrapping still fire.
+          invoke: target.invoke,
+          inputs: target.inputs,
+        };
+        await executeInvokeStep(step, stepCtx, { steps });
+        continue;
+      }
+      if ("ref" in target && target.ref != null) {
+        if (target.when === undefined || this.expandWith(target.when, { steps })) {
+          const ref = target.ref as unknown;
+          const r =
+            ref && typeof ref === "object" ? (ref as { name: string; alias?: string }) : undefined;
+          if (r && typeof r.alias === "string" && r.alias !== "Self") {
+            const inst = this.resolveImportedInstance(r.alias, r.name);
+            if (!inst || typeof inst.run !== "function") {
+              throw new Error(
+                `Boot target '${r.alias}.${r.name}' is not a runnable exported instance`,
+              );
+            }
+            await inst.run();
+          } else {
+            await this.run(typeof ref === "string" ? ref : r!.name);
+          }
+        }
+        continue;
+      }
+      if ("name" in target && typeof target.name === "string") {
+        await this.run(target.name);
+        continue;
+      }
+      throw new Error(`Unrecognized target shape at index ${i}: ${JSON.stringify(target)}`);
     }
   }
 }

package/src/resource-context.ts

@@ -161,6 +161,10 @@ export class ResourceContextImpl implements ResourceContext {
     return this.moduleContext.invokeResolved(kind, name, instance, inputs);
   }
 
+  resolveImportedInstance(alias: string, name: string): ResourceInstance | undefined {
+    return this.moduleContext.resolveImportedInstance(alias, name);
+  }
+
   async run(name: string) {
     await this.moduleContext.run(name);
   }
@@ -195,7 +199,10 @@ export class ResourceContextImpl implements ResourceContext {
    * @returns Normalized {kind, name} reference
    * @throws RuntimeError if 'kind' is missing
    */
-  resolveChildren(resource: any, resourceName?: string): { kind: string; name: string } {
+  resolveChildren(
+    resource: any,
+    resourceName?: string,
+  ): { kind: string; name: string; alias?: string } {
     if (!resource || typeof resource !== "object") {
       throw new RuntimeError(
         "ERR_INVALID_VALUE",
@@ -217,7 +224,25 @@ export class ResourceContextImpl implements ResourceContext {
     // this rescue — schemas exercising those hidden slots must use the
     // legacy string or `{kind, name}` forms for now.
     if (isRefSentinel(resource)) {
-      const refName = resource.source;
+      const source = resource.source;
+      const dot = source.indexOf(".");
+      const alias = dot > 0 ? source.slice(0, dot) : undefined;
+      // Cross-module exported instance (`!ref Alias.name`) — resolve the {kind, name} ref
+      // from the import's exported scope and reattach the alias so downstream scope
+      // resolution (executeInvokeStep → ScopeContext.getInstance) routes into the import's
+      // child context rather than scope-local resources.
+      if (alias && alias !== "Self") {
+        const name = source.slice(dot + 1);
+        const ref = this.moduleContext.resolveImportedRef(alias, name);
+        if (!ref) {
+          throw new RuntimeError(
+            "ERR_RESOURCE_NOT_FOUND",
+            `[${this.metadata.name}] !ref '${source}' is not an exported instance of import '${alias}'.`,
+          );
+        }
+        return { kind: ref.kind, name: ref.name, alias };
+      }
+      const refName = alias === "Self" ? source.slice(dot + 1) : source;
       const entry = this.moduleContext.resourceInstances.get(refName);
       if (!entry) {
         throw new RuntimeError(