@telorun/kernel 0.60.0 → 0.61.0

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

@@ -66,33 +66,89 @@ function resolveRefSlot(value: unknown, ctx: ResourceContext): ResourceInstance
   return instance ?? undefined;
 }
 
-/** Expand a `base:` node against `self`. Self-only CEL resolves to literals now;
- *  a pure `self.<path>` access is navigated directly so live instances pass
- *  through. */
-function expandBaseNode(value: unknown, self: Record<string, unknown>, ctx: EvaluationContext): unknown {
+/** Expand a mapping node against a CEL scope. `self`-only CEL resolves to
+ *  literals now; a pure `self.<path>` access is navigated directly so live
+ *  instances pass through (CEL's output type checker rejects them). Shared by
+ *  `base:` (construction, scope `{ self }`) and the dispatch mappings
+ *  `inputs:` / `result:` (scope `{ self, inputs }` / `{ self, result }`). */
+function expandMappingNode(
+  value: unknown,
+  scope: Record<string, unknown>,
+  ctx: EvaluationContext,
+): unknown {
   if (isCompiledValue(value)) {
     const src = typeof value.source === "string" ? value.source.trim() : "";
     const m = src.match(SELF_PATH);
     if (m) {
-      let cur: unknown = self;
+      let cur: unknown = scope.self;
       for (const key of m[1].split(".").slice(1)) {
         cur = (cur as Record<string, unknown> | undefined)?.[key];
       }
       return cur;
     }
-    return ctx.expandWith(value, { self });
+    return ctx.expandWith(value, scope);
   }
-  if (Array.isArray(value)) return value.map((v) => expandBaseNode(v, self, ctx));
+  if (Array.isArray(value)) return value.map((v) => expandMappingNode(v, scope, ctx));
   if (value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
     const out: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      out[k] = expandBaseNode(v, self, ctx);
+      out[k] = expandMappingNode(v, scope, ctx);
     }
     return out;
   }
   return value;
 }
 
+/**
+ * Bind the dispatch mappings of a child that REPLACED its inherited contract.
+ *
+ * A contract resolves to the nearest declaration along `extends` and never
+ * merges, so a child declaring `inputType` presents a signature the inherited
+ * controller has never heard of. `inputs:` is the adapter that turns the child's
+ * signature into the parent's call, and `result:` turns the parent's result back
+ * into the child's declared output — the same top-level-sibling factoring a
+ * template definition uses for `invoke:`.
+ *
+ * Bound onto the parent instance rather than wrapping it, so the child still IS
+ * a parent instance: `init`, `snapshot`, `teardown` and status plumbing are
+ * untouched, and nothing new appears in a declared ref slot. It composes with
+ * the kernel's contract binding by position — the parent's contract was bound
+ * when the parent instance was produced, this mapping goes on next, and the
+ * child's own contract is bound outermost by the caller. One dispatch therefore
+ * checks the child's inputs, maps, checks the parent's inputs, runs, checks the
+ * parent's result, maps back, and checks the child's result.
+ */
+function bindDispatchMapping(
+  instance: ResourceInstance,
+  definition: ResourceDefinition,
+  self: Record<string, unknown>,
+  ctx: EvaluationContext,
+): void {
+  const body = definition as unknown as { inputs?: unknown; result?: unknown };
+  const inputsMapping = body.inputs;
+  const resultMapping = body.result;
+  if (inputsMapping == null && resultMapping == null) return;
+  if (typeof instance.invoke !== "function") return;
+
+  // Every argument is forwarded — the mapping rewrites `inputs`, while the
+  // InvokeContext (cancellation, tracing) in later parameters belongs to the
+  // caller and must reach the inherited controller untouched.
+  const original = instance.invoke.bind(instance) as (
+    inputs: any,
+    ...rest: unknown[]
+  ) => Promise<unknown>;
+  instance.invoke = async (inputs: any, ...rest: unknown[]) => {
+    const mappedInputs =
+      inputsMapping != null
+        ? (expandMappingNode(inputsMapping, { self, inputs }, ctx) as Record<string, unknown>)
+        : inputs;
+    const result = await original(mappedInputs, ...rest);
+    return resultMapping != null
+      ? expandMappingNode(resultMapping, { self, result }, ctx)
+      : result;
+  };
+}
+
 /**
  * Controller for a definition that inherits its controller by delegation — it
  * `extends` a concrete kind, declares no own `controllers:` / template body, and
@@ -143,7 +199,7 @@ export function createInheritedController(
       // instances in `self`), minus the reserved keys.
       let parentConfig: Record<string, unknown>;
       if (base != null) {
-        parentConfig = expandBaseNode(base, self, definingContext) as Record<string, unknown>;
+        parentConfig = expandMappingNode(base, { self }, definingContext) as Record<string, unknown>;
       } else {
         const { kind: _kind, metadata: _metadata, name: _name, ...config } = self;
         parentConfig = config;
@@ -159,7 +215,10 @@ export function createInheritedController(
           `Telo.Definition '${definition.metadata.name}': inherited controller requires a ResourceContext host that implements createInheritedInstance().`,
         );
       }
-      return host.createInheritedInstance(definingContext, parentResource);
+      const instance = await host.createInheritedInstance(definingContext, parentResource);
+      if (!instance) return null;
+      bindDispatchMapping(instance, definition, self, definingContext);
+      return instance;
     },
   };
 }

package/src/controllers/type/json-schema-controller.ts

@@ -0,0 +1,114 @@
+import { evaluate } from "@marcbachmann/cel-js";
+import type {
+  ResourceContext,
+  ResourceInstance,
+  ResourceManifest,
+  TypeRule,
+} from "@telorun/sdk";
+import { canonicalTypeSchemaId, mergeTypeSchemas, RuntimeError } from "@telorun/sdk";
+
+/**
+ * `Telo.JsonSchema` — a named data shape.
+ *
+ * It lives in the kernel rather than in an installable module for the same
+ * reason the mandatory log sinks do: declaring a shape is not optional. Every
+ * kind that carries an invocation contract needs one, so requiring an import to
+ * write `inputType:` would tax the exact thing contracts want authors to do —
+ * and a library declaring its own contract would have to import a module purely
+ * to describe itself.
+ *
+ * `type.JsonSchema` is retained as a deprecated alias with the same behaviour, so
+ * published manifests keep resolving.
+ */
+class JsonSchemaType {
+  constructor(
+    private readonly qualifiedName: string,
+    private readonly rules: TypeRule[],
+    /** The fully-resolved (post-`extends`), self-contained JSON Schema. Read by
+     *  consumers that need the effective shape — e.g. a templated resource
+     *  threading `${{ self.model.schema }}` into a request validation schema. */
+    readonly schema: Record<string, unknown>,
+  ) {}
+
+  /**
+   * Validate data against this type's CEL rules — the invariant layer on top of
+   * the schema itself, which AJV enforces through the schema registry.
+   */
+  validateRules(data: unknown): void {
+    for (const rule of this.rules) {
+      let result: unknown;
+      try {
+        result = evaluate(rule.condition, { this: data });
+      } catch (err) {
+        throw new RuntimeError(
+          "ERR_TYPE_VALIDATION_FAILED",
+          `Type "${this.qualifiedName}" rule evaluation failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+      if (result !== true) {
+        throw new RuntimeError(
+          rule.code,
+          rule.message ??
+            `Type "${this.qualifiedName}" validation failed: rule "${rule.code}" not satisfied`,
+        );
+      }
+    }
+  }
+}
+
+/** A type resource is pure declaration: it registers a schema and holds the
+ *  resolved shape, implementing none of the lifecycle verbs. `ResourceInstance`
+ *  is entirely optional members, so a class with none of them satisfies it only
+ *  by assertion — the same shape the module-loaded controller had, where the
+ *  dynamic-import boundary erased the type instead of asserting it. */
+export async function create(
+  resource: ResourceManifest,
+  ctx: ResourceContext,
+): Promise<ResourceInstance | null> {
+  const qualifiedName = `${resource.metadata.module}.${resource.metadata.name}`;
+  const ownSchema = resource.schema as Record<string, unknown>;
+
+  let schema: Record<string, unknown> = ownSchema;
+
+  const extendsField = resource.extends as string | string[] | undefined;
+  if (extendsField) {
+    const parents = Array.isArray(extendsField) ? extendsField : [extendsField];
+
+    const parentSchemas: Record<string, unknown>[] = [];
+    for (const parent of parents) {
+      const parentSchema = ctx.lookupSchema(parent);
+      // Defer if any parent schema isn't registered yet (multi-pass resolution).
+      if (!parentSchema) return null;
+      parentSchemas.push(parentSchema as Record<string, unknown>);
+    }
+
+    // Each parent's registered schema is itself already resolved, so merging
+    // them makes inheritance transitive through grandparents with no `$ref`s
+    // left in the result.
+    schema = mergeTypeSchemas([...parentSchemas, ownSchema]);
+  }
+
+  const rules = (Array.isArray(resource.rules) ? resource.rules : []) as TypeRule[];
+
+  ctx.registerSchema(qualifiedName, schema);
+  ctx.registerTypeRules(qualifiedName, rules);
+
+  // Also register under the short name so types can be referenced without a
+  // module prefix.
+  const shortName = resource.metadata.name;
+  if (shortName !== qualifiedName) {
+    ctx.registerSchema(shortName, schema);
+    ctx.registerTypeRules(shortName, rules);
+  }
+
+  // Canonical module-scoped id — the target of `$ref: "telo://Self/<name>"` (and
+  // `telo://<Alias>/<name>` across imports) once the loader resolves the
+  // authority to this module. Authority-free, so a validator can actually
+  // resolve the reference; see `canonicalTypeSchemaId`.
+  const moduleName = resource.metadata.module as string | undefined;
+  if (moduleName) {
+    ctx.registerSchema(canonicalTypeSchemaId(moduleName, shortName), schema);
+  }
+
+  return new JsonSchemaType(qualifiedName, rules, schema) as unknown as ResourceInstance;
+}

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

@@ -47,6 +47,7 @@ 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 { 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");
+}