@telorun/kernel 0.60.0 → 0.62.0

package/src/evaluation-context.ts

@@ -26,6 +26,12 @@ import {
 } from "@telorun/sdk";
 import { RuntimeError } from "@telorun/sdk";
 import { evalPathCovers } from "@telorun/analyzer";
+import {
+  classifyInitFailures,
+  renderInitFailureText,
+  summarizeInitFailures,
+  type FailedResource,
+} from "./init-failure-diagnostics.js";
 import {
   acceptReportedStatus,
   buildPublishedProps,
@@ -93,6 +99,16 @@ function collectResourceRefs(resource: ResourceManifest): ResourceRef[] {
   return [...found.values()];
 }
 
+/**
+ * Project resource refs onto the names they depend on IN THIS CONTEXT. A local
+ * ref is its own name; a cross-module `Alias.name` ref depends on the local
+ * `Telo.Import` resource named by the alias, since that is the resource whose
+ * failure would strand it. Used to attribute an init failure to its cause.
+ */
+function localDependencyNames(refs: ResourceRef[]): string[] {
+  return refs.map((r) => (r.alias && r.alias !== "Self" ? r.alias : r.name));
+}
+
 /**
  * Build a resource's resolved properties for the debug stream — its config "after
  * templating", with `${{ }}` / `!cel` reduced to concrete values. The manifest is
@@ -343,6 +359,12 @@ export class EvaluationContext implements IEvaluationContext {
   /** Resources queued for initialization on this context node. */
   private pendingResources: ResourceManifest[] = [];
 
+  /** Per-resource dependency names, captured at create() time — BEFORE Phase-5
+   *  injection swaps refs for live instances, so the walk sees plain objects and
+   *  cannot wander into a controller's (possibly cyclic) object graph. Read only
+   *  when init fails, to attribute each failure to its cause. */
+  private readonly resourceDependencies = new Map<string, string[]>();
+
   /**
    * Optional hook called between create() and init() for each resource.
    * Set by the kernel to inject live instances into reference fields.
@@ -616,7 +638,10 @@ export class EvaluationContext implements IEvaluationContext {
    */
   async initializeResources(): Promise<void> {
     const MAX_PASSES = 10;
-    const errors = new Map<string, { message: string; code?: string; details?: string }>();
+    const errors = new Map<
+      string,
+      { message: string; code?: string; details?: string; children?: RuntimeDiagnostic[] }
+    >();
 
     let pass = 1;
     do {
@@ -641,6 +666,8 @@ export class EvaluationContext implements IEvaluationContext {
             errors.delete(name);
             progress = true;
             const createdRes = created.resource;
+            const refs = collectResourceRefs(createdRes);
+            this.resourceDependencies.set(name, localDependencyNames(refs));
             const payload: Record<string, unknown> = {
               resource: {
                 kind: createdRes.kind,
@@ -649,7 +676,7 @@ export class EvaluationContext implements IEvaluationContext {
                 id: this.resourceId(createdRes.kind, createdRes.metadata.name),
               },
               ...(this.owner ? { owner: this.owner } : {}),
-              dependencies: this.qualifyDeps(collectResourceRefs(createdRes)),
+              dependencies: this.qualifyDeps(refs),
             };
             // `properties` (the resolved config) is a second full config walk plus
             // a secret scrub. Build it lazily: the EventBus short-circuits when
@@ -682,6 +709,7 @@ export class EvaluationContext implements IEvaluationContext {
                   ? this.resolveImportedInstance(alias, n)
                   : this.resourceInstances.get(n)?.instance,
               (n) => this.hasManifest(n) && !this.resourceInstances.has(n),
+              this,
             );
           }
           if (instance.init) await instance.init(ctx);
@@ -694,6 +722,9 @@ export class EvaluationContext implements IEvaluationContext {
           await this.publishSnapshot(name);
           this.resourceInstances.set(name, { resource, instance });
           this.createdInstances.delete(name);
+          // Read only on failure, and this one succeeded — drop it rather than
+          // holding a dep-name array per resource for the context's lifetime.
+          this.resourceDependencies.delete(name);
           errors.delete(name);
           progress = true;
           await this.emit(`${resource.kind}.${resource.metadata.name}.Initialized`, {
@@ -715,38 +746,33 @@ export class EvaluationContext implements IEvaluationContext {
     } while (pass <= MAX_PASSES);
 
     if (this.pendingResources.length > 0 || this.createdInstances.size > 0) {
-      const diagnostics: RuntimeDiagnostic[] = [
-        ...this.pendingResources.map((r) => {
-          const info = errors.get(r.metadata.name) ?? { message: "Unknown error" };
-          return {
-            resource: r.metadata.name,
-            kind: r.kind,
-            message: info.message,
-            details: info.details,
-            code: info.code,
-          };
-        }),
-        ...[...this.createdInstances].map(([name, { resource }]) => {
-          const info = errors.get(name) ?? { message: "Unknown error" };
-          return {
-            resource: name,
-            kind: resource.kind,
-            message: info.message,
-            details: info.details,
-            code: info.code,
-          };
-        }),
+      const toFailure = (name: string, kind: string, deps: string[]): FailedResource => {
+        const info = errors.get(name) ?? { message: "Unknown error" };
+        return {
+          resource: name,
+          kind,
+          message: info.message,
+          details: info.details,
+          code: info.code,
+          children: info.children,
+          deps,
+        };
+      };
+      const failures: FailedResource[] = [
+        // A resource that never got created was never injected either, so its
+        // manifest still carries plain `{kind, name}` refs — walk it here rather
+        // than relying on the create-time capture it never reached.
+        ...this.pendingResources.map((r) =>
+          toFailure(r.metadata.name, r.kind, localDependencyNames(collectResourceRefs(r))),
+        ),
+        ...[...this.createdInstances].map(([name, { resource }]) =>
+          toFailure(name, resource.kind, this.resourceDependencies.get(name) ?? []),
+        ),
       ];
-      const textDetails = diagnostics
-        .map((d) => {
-          const head = `  ${d.kind ? `${d.kind} ` : ""}${d.resource}: ${d.message}${d.code ? ` [${d.code}]` : ""}`;
-          const extra = d.details ? "\n" + d.details.split("\n").map((l) => `    ${l}`).join("\n") : "";
-          return head + extra;
-        })
-        .join("\n");
+      const diagnostics = classifyInitFailures(failures);
       throw new RuntimeError(
         "ERR_RESOURCE_INITIALIZATION_FAILED",
-        `Unable to process resources:\n${textDetails}`,
+        `${summarizeInitFailures(diagnostics)}:\n${renderInitFailureText(diagnostics)}`,
         diagnostics,
       );
     }
@@ -815,7 +841,7 @@ export class EvaluationContext implements IEvaluationContext {
         // Propagate injection hook: extend getInstance to also resolve parent singleton instances.
         if (parent.preInitHook) {
           const parentHook = parent.preInitHook;
-          child.preInitHook = (resource, childGetInstance, childIsPending) => {
+          child.preInitHook = (resource, childGetInstance, childIsPending, owner) => {
             parentHook(
               resource,
               (name, alias) => {
@@ -836,6 +862,9 @@ export class EvaluationContext implements IEvaluationContext {
               // Only a scope-local dependency can still be pending — an outer resource
               // is live by the time a scope opens — so the child's own predicate suffices.
               childIsPending,
+              // Forwarded, not replaced by `child`: a `with:` nested inside a scoped
+              // resource must still resolve kinds against the scope it opened in.
+              owner,
             );
           };
         }
@@ -1761,11 +1790,31 @@ function formatErrorForDiagnostic(err: unknown): {
   message: string;
   code?: string;
   details?: string;
+  children?: RuntimeDiagnostic[];
 } {
   if (!(err instanceof Error)) {
     return { message: String(err) };
   }
 
+  // A nested context's aggregate (an import initializing its library's
+  // resources) already carries a classified diagnostic list. Keep it structured
+  // instead of letting the cause-chain walk flatten it into this entry's
+  // message: the child's root causes stay distinguishable from the child's own
+  // cascade, and the error count sees the real leaves rather than one import.
+  // The headline is re-derived from the diagnostics, never recovered by parsing
+  // the message the child already rendered from them.
+  if (
+    err instanceof RuntimeError &&
+    err.code === "ERR_RESOURCE_INITIALIZATION_FAILED" &&
+    err.diagnostics?.length
+  ) {
+    return {
+      message: summarizeInitFailures(err.diagnostics),
+      code: err.code,
+      children: err.diagnostics,
+    };
+  }
+
   const detailLines: string[] = [];
   const seen = new Set<unknown>();
   let current: unknown = err;

package/src/index.ts

@@ -32,6 +32,7 @@ export {
   moduleDirectoryFor,
   hostPlatformTarget,
   type MaterializedLayer,
+  type ResolvedControllerLayer,
 } from "./bundle/module-artifact.js";
 export { readOwnerManifest, type OwnerManifest } from "./bundle/module-manifest.js";
 export type {
@@ -46,7 +47,8 @@ export { nodeCelHandlers } from "./cel-handlers.js";
 export { ModuleContext } from "./module-context.js";
 export { ManifestRegistry as Registry } from "./registry.js";
 export { ResourceURI } from "./resource-uri.js";
-export type { RuntimeDiagnostic } from "@telorun/sdk";
+export type { DiagnosticOrigin, RuntimeDiagnostic } from "@telorun/sdk";
+export { describeBlockedGroup, groupBlockedResources } from "./init-failure-diagnostics.js";
 
 // Structured logging — the runtime half of kernel/specs/logging.md. The record
 // model, severity scale, and `Logger` surface live in `@telorun/sdk`; these are

package/src/init-failure-diagnostics.ts

@@ -0,0 +1,169 @@
+import type { RuntimeDiagnostic } from "@telorun/sdk";
+
+/**
+ * Codes that mean "this resource never got its turn": the multi-pass init loop
+ * deferred it because a dependency had not initialized, so it never produced a
+ * failure of its own. This is the ONLY signal that an entry may be collapsed —
+ * see {@link classifyInitFailures}.
+ */
+const DEPENDENCY_PENDING_CODES = new Set([
+  "ERR_LOCAL_REF_PENDING",
+  "ERR_CROSS_MODULE_REF_PENDING",
+]);
+
+/** One resource that did not reach the `Initialized` state, with the outbound
+ *  edges (names of resources in the SAME context) captured for it. */
+export interface FailedResource {
+  resource: string;
+  kind?: string;
+  message: string;
+  details?: string;
+  code?: string;
+  children?: RuntimeDiagnostic[];
+  deps: string[];
+}
+
+/**
+ * Split a failed-resource set into the ones that failed on their own (root
+ * causes) and the ones that only failed because something else in the set did.
+ *
+ * A dependency chain of any length produces one real error and N shadows of it,
+ * and the shadows outnumber the cause — reporting them flat buries the only
+ * line a reader can act on.
+ *
+ * **What makes an entry derived is its CODE, never its edges.** Only a
+ * {@link DEPENDENCY_PENDING_CODES} deferral says "this resource never ran, so
+ * it has nothing of its own to report". A reference edge into the failure set
+ * proves an edge exists, not that this entry's failure came from it: a resource
+ * can reference a failed dependency AND fail its own schema validation, and
+ * collapsing it there would swallow a real, independent error the author has to
+ * fix — the second half of a two-error session they would only discover on the
+ * next run. (Nor is the edge trustworthy on its own terms: `collectResourceRefs`
+ * walks `with:`-scoped inline declarations, whose names resolve scope-locally,
+ * so a scoped `!ref Db` can collide with a failed module-level `Db`.)
+ *
+ * Edges are used for ATTRIBUTION only — they name which failure a deferred
+ * entry is waiting on. `blockedBy` is the ROOT of the chain, not the immediate
+ * blocker, since that is the name a reader has to go fix; the walk stops at the
+ * first entry that is not itself derived. A deferral with no visible edge (a
+ * `${{ resources.X }}` read the ref walk cannot see) is still derived, just
+ * unattributed.
+ *
+ * Classification never hides everything: if no entry survives as a root (every
+ * failure is a deferral), the whole set is reported unclassified.
+ *
+ * Returns diagnostics ordered root causes first, then the derived entries.
+ */
+export function classifyInitFailures(failures: FailedResource[]): RuntimeDiagnostic[] {
+  const failed = new Set(failures.map((f) => f.resource));
+
+  const derived = new Set(
+    failures.filter((f) => f.code && DEPENDENCY_PENDING_CODES.has(f.code)).map((f) => f.resource),
+  );
+  // Attribution edges are collected for EVERY entry, derived or not: a chain
+  // walk has to pass through an entry to reach the root beyond it.
+  const edgeBlocker = new Map<string, string>();
+  for (const f of failures) {
+    const dep = f.deps.find((n) => n !== f.resource && failed.has(n));
+    if (dep !== undefined) edgeBlocker.set(f.resource, dep);
+  }
+
+  const rootCauseOf = (name: string): string | undefined => {
+    const seen = new Set<string>([name]);
+    let current = edgeBlocker.get(name);
+    while (current !== undefined && !seen.has(current)) {
+      if (!derived.has(current)) return current;
+      seen.add(current);
+      current = edgeBlocker.get(current);
+    }
+    return undefined;
+  };
+
+  const toDiagnostic = (f: FailedResource, isDerived: boolean): RuntimeDiagnostic => {
+    const blockedBy = isDerived ? rootCauseOf(f.resource) : undefined;
+    return {
+      resource: f.resource,
+      kind: f.kind,
+      message: f.message,
+      details: f.details,
+      code: f.code,
+      ...(f.children?.length ? { children: f.children } : {}),
+      ...(isDerived ? { derived: true, ...(blockedBy ? { blockedBy } : {}) } : {}),
+    };
+  };
+
+  const roots = failures.filter((f) => !derived.has(f.resource));
+  if (roots.length === 0) return failures.map((f) => toDiagnostic(f, false));
+
+  return [
+    ...roots.map((f) => toDiagnostic(f, false)),
+    ...failures.filter((f) => derived.has(f.resource)).map((f) => toDiagnostic(f, true)),
+  ];
+}
+
+/** Group the derived entries by the root cause they hang off, so a renderer can
+ *  collapse each chain to a single line instead of repeating one failure N
+ *  times. Entries whose blocker could not be named group under `undefined`. */
+export function groupBlockedResources(
+  diagnostics: RuntimeDiagnostic[],
+): Map<string | undefined, string[]> {
+  const groups = new Map<string | undefined, string[]>();
+  for (const d of diagnostics) {
+    if (!d.derived) continue;
+    const key = d.blockedBy;
+    const names = groups.get(key) ?? [];
+    names.push(d.resource ?? "(unnamed)");
+    groups.set(key, names);
+  }
+  return groups;
+}
+
+/** One collapsed line per blocked chain, e.g.
+ *  `9 resources blocked by GrantDb: GrantStore, GoogleTokens, ...`. */
+export function describeBlockedGroup(blockedBy: string | undefined, names: string[]): string {
+  const subject = `${names.length} resource${names.length !== 1 ? "s" : ""}`;
+  const blocker = blockedBy ?? "an uninitialized dependency";
+  return `${subject} blocked by ${blocker}: ${names.join(", ")}`;
+}
+
+/** The headline for a classified failure set. Shared by the aggregate error's
+ *  own message and by the entry an importing context builds for it, so the two
+ *  are never recovered by re-parsing each other's rendered text. */
+export function summarizeInitFailures(diagnostics: RuntimeDiagnostic[]): string {
+  const total = diagnostics.length;
+  const roots = diagnostics.filter((d) => !d.derived).length;
+  const blocked = total - roots;
+  return (
+    `${total} resource${total !== 1 ? "s" : ""} failed to initialize` +
+    (blocked > 0 ? ` (${roots} root cause${roots !== 1 ? "s" : ""}, rest blocked)` : "")
+  );
+}
+
+/** Render a classified failure set as the text body of the aggregate error
+ *  message — root causes in full, each blocked chain collapsed to one line.
+ *  Nested children recurse through this same function so a child list is
+ *  traversed exactly once, groups included. */
+export function renderInitFailureText(diagnostics: RuntimeDiagnostic[]): string {
+  const lines: string[] = [];
+  for (const d of diagnostics) {
+    if (!d.derived) {
+      lines.push(
+        `  ${d.kind ? `${d.kind} ` : ""}${d.resource}: ${d.message}${d.code ? ` [${d.code}]` : ""}`,
+      );
+      if (d.details) lines.push(...d.details.split("\n").map((l) => `    ${l}`));
+    }
+    // A derived entry contributes no line of its own, but a nested context's
+    // root causes are not shadows of THIS context's failure — they still report.
+    if (d.children?.length) {
+      lines.push(
+        ...renderInitFailureText(d.children)
+          .split("\n")
+          .map((l) => `  ${l}`),
+      );
+    }
+  }
+  for (const [blockedBy, names] of groupBlockedResources(diagnostics)) {
+    lines.push(`  ${describeBlockedGroup(blockedBy, names)}`);
+  }
+  return lines.join("\n");
+}