@telorun/kernel 0.23.0 → 0.24.1

package/src/module-context.ts

@@ -47,6 +47,32 @@ function collectSecretValues(secrets: Record<string, unknown>): Set<string> {
   return values;
 }
 
+/** A boot target whose ref slot Phase 5 injection already replaced with the
+ *  live instance (the documented "pre-resolved instance once Phase 5 ran"
+ *  shape from `BootTarget`). Distinguished from a structural `{kind, name}` ref
+ *  by carrying a `run()` method. */
+function isRunnableInstance(value: unknown): value is ResourceInstance {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    typeof (value as { run?: unknown }).run === "function"
+  );
+}
+
+/** Cycle-safe serialization for diagnostics. A boot target can be a live
+ *  instance whose object graph (e.g. a Kysely/Ajv schema) is cyclic, which
+ *  would make a plain JSON.stringify throw and mask the real error. */
+function safeStringify(value: unknown): string {
+  const seen = new WeakSet<object>();
+  return JSON.stringify(value, (_key, val) => {
+    if (val && typeof val === "object") {
+      if (seen.has(val)) return "[Circular]";
+      seen.add(val);
+    }
+    return val;
+  });
+}
+
 /**
  * Persistent, module-scoped context. Reserved CEL namespaces:
  * variables, secrets, resources, ports (Application-only).
@@ -319,6 +345,18 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
         this.invokeResolved(kind, name, instance, inputs, ctx),
       resolveImportedInstance: (alias, name) => this.resolveImportedInstance(alias, name),
     };
+    // Mirror the local-run gate: refuse a target reached after the boot run was
+    // cancelled, then run the pre-resolved instance directly.
+    const runResolvedInstance = async (inst: ResourceInstance, label: string) => {
+      const token = ctx?.cancellation;
+      if (token?.isCancelled) {
+        throw new RuntimeError(
+          "ERR_INVOKE_CANCELLED",
+          `Run ${label} was cancelled${token.reason ? `: ${token.reason}` : ""}`,
+        );
+      }
+      await inst.run!(ctx);
+    };
     for (let i = 0; i < this.targets.length; i++) {
       const target = this.targets[i]!;
       if (typeof target === "string") {
@@ -341,36 +379,54 @@ export class ModuleContext extends EvaluationContext implements IModuleContext {
       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`,
-              );
-            }
-            // Mirror the local-run gate: refuse a cross-module target reached
-            // after the boot run was cancelled.
-            const token = ctx?.cancellation;
-            if (token?.isCancelled) {
-              throw new RuntimeError(
-                "ERR_INVOKE_CANCELLED",
-                `Run ${r.alias}.${r.name} was cancelled${token.reason ? `: ${token.reason}` : ""}`,
-              );
-            }
-            await inst.run(ctx);
+          // Phase 5 injection may have replaced the ref slot with the live
+          // instance; run it directly.
+          if (isRunnableInstance(ref)) {
+            await runResolvedInstance(ref, `target[${i}]`);
           } else {
-            await this.run(typeof ref === "string" ? ref : r!.name, ctx);
+            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 runResolvedInstance(inst, `${r.alias}.${r.name}`);
+            } else {
+              await this.run(typeof ref === "string" ? ref : r!.name, ctx);
+            }
           }
         }
         continue;
       }
-      if ("name" in target && typeof target.name === "string") {
-        await this.run(target.name, ctx);
+      // Bare run target. Phase 5 injection resolves a `!ref name` /
+      // cross-module `!ref Alias.name` slot into the live instance before boot,
+      // so the common runtime shape here is a pre-resolved ResourceInstance;
+      // fall back to the structural ref forms when injection left them in place.
+      if (isRunnableInstance(target)) {
+        await runResolvedInstance(target, `target[${i}]`);
+        continue;
+      }
+      const bare = target as { name?: unknown; alias?: unknown };
+      if (typeof bare.alias === "string" && bare.alias !== "Self" && typeof bare.name === "string") {
+        const inst = this.resolveImportedInstance(bare.alias, bare.name);
+        if (!inst || typeof inst.run !== "function") {
+          throw new Error(
+            `Boot target '${bare.alias}.${bare.name}' is not a runnable exported instance`,
+          );
+        }
+        await runResolvedInstance(inst, `${bare.alias}.${bare.name}`);
+        continue;
+      }
+      if (typeof bare.name === "string") {
+        await this.run(bare.name, ctx);
         continue;
       }
-      throw new Error(`Unrecognized target shape at index ${i}: ${JSON.stringify(target)}`);
+      throw new Error(`Unrecognized target shape at index ${i}: ${safeStringify(target)}`);
     }
   }
 }

package/src/resource-context.ts

@@ -251,14 +251,19 @@ export class ResourceContextImpl implements ResourceContext {
         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(
-          "ERR_RESOURCE_NOT_FOUND",
-          `[${this.metadata.name}] !ref '${refName}' did not resolve to a registered resource.`,
-        );
-      }
-      return { kind: entry.resource.kind as string, name: refName };
+      // Mirror the legacy `{kind, name}` path: return a `{kind, name}` ref and let
+      // the downstream resolution (module-global `invoke`, or scope-local
+      // `executeInvokeStep → ScopeContext.getInstance`) find it by name at invoke
+      // time. The kind is carried for invocation-event naming. Prefer an
+      // already-initialized instance's kind, else the authored kind from the
+      // static manifest (init-order-independent — the target may not be
+      // initialized yet when this resolves, and scope-local resources never enter
+      // `resourceInstances`).
+      const kind =
+        (this.moduleContext.resourceInstances.get(refName)?.resource.kind as string | undefined) ??
+        this.kernel.resourceKindByName(refName) ??
+        "";
+      return { kind, name: refName };
     }
 
     if (!resource.kind) {
@@ -274,6 +279,12 @@ export class ResourceContextImpl implements ResourceContext {
       resource.metadata?.name ??
       resourceName ??
       `Unnamed${Math.random().toString(16).slice(2, 8)}`;
+    // `alias` marks a resolved cross-module reference (`{kind, name, alias}`)
+    // produced from a `!ref Alias.name`. It is always a reference into an
+    // imported library's exported instance — never an inline definition — so it
+    // is a reference key alongside kind/name/metadata (not inline config) and is
+    // carried through so downstream scope resolution routes into the import.
+    const alias = typeof resource.alias === "string" ? resource.alias : undefined;
 
     // Register an inline manifest when:
     //  - the ref carries definition properties (clearly an inline definition), or
@@ -287,7 +298,7 @@ export class ResourceContextImpl implements ResourceContext {
     // the contract here; previous silent-skip-on-duplicate hid real bugs
     // (e.g. inline auto-names colliding across sibling Run.Sequence steps).
     const hasInlineProperties = Object.keys(resource).some(
-      (k) => k !== "kind" && k !== "name" && k !== "metadata",
+      (k) => k !== "kind" && k !== "name" && k !== "metadata" && k !== "alias",
     );
     const hasExplicitName = resource.name !== undefined || resource.metadata?.name !== undefined;
     const shouldRegister =
@@ -304,7 +315,7 @@ export class ResourceContextImpl implements ResourceContext {
       });
     }
 
-    return { kind, name };
+    return alias ? { kind, name, alias } : { kind, name };
   }
 
   getResourcesByName(_kind: string, name: string): RuntimeResource | null {

package/src/schema-validator.ts

@@ -8,7 +8,7 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { formatAjvErrors } from "./manifest-schemas.js";
-import { ManifestRootSchema } from "@telorun/templating";
+import { ManifestRootSchema, normalizeRefSlots } from "@telorun/templating";
 
 const Ajv = AjvModule.default ?? AjvModule;
 // AJV's standalone subpath is CJS — the default export shows up as either
@@ -174,7 +174,7 @@ export class SchemaValidator {
           required: Object.keys(schema),
           additionalProperties: false,
         };
-    const injected =
+    const withImplicit =
       normalized.additionalProperties === false
         ? {
             ...normalized,
@@ -186,6 +186,13 @@ export class SchemaValidator {
           }
         : normalized;
 
+    // Drop the legacy scalar `type` an older published module may still pin on
+    // its `x-telo-ref` slots. Schema validation runs in create() before Phase 5
+    // injection, so a ref slot holds the resolved `{kind, name, alias?}` object
+    // (or an unresolved sentinel) — both objects the stale `type: "string"`
+    // would otherwise reject.
+    const injected = normalizeRefSlots(withImplicit) as typeof withImplicit;
+
     const hash = createHash("sha256")
       .update(JSON.stringify({ runtime: VALIDATOR_RUNTIME_TAG, schema: injected }))
       .digest("hex")