@telorun/analyzer 0.68.0 → 0.69.0

package/src/call-graph.ts

@@ -56,7 +56,12 @@ import {
   type RefUseCases,
 } from "./ref-slot.js";
 import { isStepSlot } from "./step-slot.js";
-import { isRefEntry, resolveFieldEntries, type RefFieldEntry } from "./reference-field-map.js";
+import {
+  isInlineResource,
+  isRefEntry,
+  resolveFieldEntries,
+  type RefFieldEntry,
+} from "./reference-field-map.js";
 import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
 export interface ResourceGraphNode {
@@ -92,6 +97,42 @@ export interface StepGraphNode {
   index: number;
   /** The step value as written. */
   step: Record<string, unknown>;
+  /**
+   * Which branch of the step grammar this step IS — the branch's own title
+   * (`invoke`, `if/then/else`, `while/do`, `switch/cases/default`,
+   * `try/catch/finally`, `throw`, `value`).
+   *
+   * Matched on the branch's REQUIRED keys, and IS those keys — sorted and
+   * joined (`if+then`, `invoke`, `do+while`). A machine identity, so a consumer
+   * may branch on it; it was the branch's `title`, which is prose an author may
+   * reword at any time, and a view was splitting it on `/` to recover a keyword.
+   * Absent for a step matching no branch — one just added, and still empty.
+   */
+  variant?: string;
+  /** The branch's `title` as its author wrote it, for a view to render verbatim.
+   *  Never parsed: it is a label, and the moment anything reads its SHAPE it
+   *  becomes a vocabulary the author cannot change. */
+  variantLabel?: string;
+  /**
+   * The expression that decides whether or how this step runs, as written: an
+   * `if:`, a `while:`, a `switch:`, or the `when:` guard on a dispatch.
+   *
+   * Found through `x-telo-topology-role`, never by keyword, so a third-party
+   * composer annotating its own predicate is read the same way.
+   */
+  predicate?: string;
+  /**
+   * Every reference slot this step's grammar declares — filled, empty, or
+   * holding a declaration written at the site.
+   *
+   * Recorded here because this is the one place a step's item schema and its
+   * value are both in hand: a step array's items sit behind a local `$ref`, so
+   * the reference field map deliberately never reaches them, and a consumer
+   * asking "what may this step dispatch to, and where is that written" has
+   * nowhere else to look. An EMPTY slot is listed for exactly that reason — it
+   * is a site an editor can offer to fill, and an edge says nothing about one.
+   */
+  refSlots?: { key: string; path: string; kinds: string[]; inline?: boolean }[];
 }
 
 export type CallGraphNode = ResourceGraphNode | StepGraphNode;
@@ -154,7 +195,15 @@ export interface CallGraph {
   /** Edges arriving at a resource node. */
   edgesTo(id: string): CallGraphEdge[];
   resource(kind: string, name: string): ResourceGraphNode | undefined;
-  resourceByName(name: string): ResourceGraphNode | undefined;
+  /**
+   * The resource a bare name addresses, read from `fromModule`'s scope.
+   *
+   * A name is module-scoped, so the module is how two declarations of one name
+   * are told apart — see {@link resolveScopedName}. Omitting it answers for a
+   * name declared once and, where several modules declare it, declines rather
+   * than taking whichever came first.
+   */
+  resourceByName(name: string, fromModule?: string): ResourceGraphNode | undefined;
   /** Step nodes declared by a resource, in lexical order. */
   steps(resourceId: string): StepGraphNode[];
   /** Every edge whose `use` includes at least one control transfer, plus every
@@ -164,6 +213,55 @@ export interface CallGraph {
 
 export const resourceId = (kind: string, name: string): string => `${kind}\0${name}`;
 
+/**
+ * The id a manifest's node is keyed by.
+ *
+ * **A resource name is MODULE-SCOPED**, so `(kind, name)` is unique inside one
+ * module and not across a flattened set: two libraries each exporting an
+ * `Http.Api` named `routes` are two declarations, and keying both as
+ * `http.Api\0routes` silently made them one — the second overwrote the first,
+ * taking its edges and its steps with it. The module is part of the identity
+ * wherever the loader stamped one; a manifest with no stamp keeps the bare form,
+ * so nothing that never crossed a module boundary moves.
+ */
+export function nodeIdFor(manifest: ResourceManifest): string {
+  const kind = manifest.kind as string;
+  const name = manifest.metadata?.name as string;
+  const module = (manifest.metadata as { module?: string } | undefined)?.module;
+  return module ? `${module}\0${resourceId(kind, name)}` : resourceId(kind, name);
+}
+
+/** The module a manifest was declared in, when the loader stamped one. */
+const declaringModule = (manifest: ResourceManifest): string | undefined =>
+  (manifest.metadata as { module?: string } | undefined)?.module;
+
+/**
+ * A bare `<name>` read from a resource declared in `fromModule`.
+ *
+ * **Same module first**, because that is what a bare name MEANS: it is resolved
+ * in the scope it was written in, and a cross-module reference is written with
+ * an alias. A name declared in exactly one module resolves to it whatever the
+ * reader's scope — which is what keeps an unstamped manifest set (every
+ * fixture, every single-module load) behaving as it did. A name declared in
+ * SEVERAL other modules and none of the reader's resolves to NOTHING: guessing
+ * between them attributes a reference to a resource the author never named, and
+ * some other pass reports the dangling name honestly.
+ *
+ * Exported because more than one pass resolves a bare name — the call graph's
+ * own sites, and the projection's inline declarations and CEL state reads. Two
+ * spellings of this rule is how a fix in one leaves a first-wins lookup in the
+ * other, which is exactly the collision it exists to prevent.
+ */
+export function resolveScopedName<T>(
+  candidates: readonly T[] | undefined,
+  moduleOf: (item: T) => string | undefined,
+  fromModule: string | undefined,
+): T | undefined {
+  if (!candidates || candidates.length === 0) return undefined;
+  if (candidates.length === 1) return candidates[0];
+  return candidates.find((candidate) => moduleOf(candidate) === fromModule);
+}
+
 /**
  * Does control reach this edge's target?
  *
@@ -323,6 +421,65 @@ interface StepWalkContext {
   stepEdgesByPath: Map<string, CallGraphEdge>;
 }
 
+/**
+ * What a step IS, and what decides whether it runs.
+ *
+ * Both come off the schema rather than off a keyword list: the variant is the
+ * `oneOf` branch whose REQUIRED keys the step carries, and the predicate is the
+ * field annotated as one. A composer that declares a step body of its own is
+ * therefore described in its own words, and nothing here knows that `while`
+ * exists.
+ *
+ * A step matching several branches takes the FIRST — the grammar is a `oneOf`,
+ * so more than one match is a manifest the checker rejects, and guessing among
+ * them would be a second opinion on a question the checker already answers.
+ */
+function classifyStep(
+  step: Record<string, unknown>,
+  itemSchema: Record<string, any> | undefined,
+  rootSchema: Record<string, any>,
+): { variant?: string; variantLabel?: string; predicate?: string } {
+  if (!itemSchema) return {};
+  const branches = Array.isArray(itemSchema.oneOf) ? itemSchema.oneOf : [];
+  let variant: string | undefined;
+  let variantLabel: string | undefined;
+  for (const raw of branches) {
+    const branch = resolveLocalRef(raw, rootSchema);
+    const required = Array.isArray(branch?.required) ? (branch.required as string[]) : [];
+    if (required.length === 0 || !required.every((key) => step[key] !== undefined)) continue;
+    // The keys are what the branch IS; the title is what it is called.
+    variant = [...required].sort().join("+");
+    if (typeof branch?.title === "string") variantLabel = branch.title;
+    break;
+  }
+
+  let predicate: string | undefined;
+  for (const [key, propSchema] of propertySchemas(itemSchema)) {
+    const role = propSchema?.["x-telo-topology-role"];
+    if (role !== "predicate" && role !== "discriminator") continue;
+    const written = expressionSource(step[key]);
+    if (written !== undefined) {
+      predicate = written;
+      break;
+    }
+  }
+  return {
+    ...(variant ? { variant } : {}),
+    ...(variantLabel ? { variantLabel } : {}),
+    ...(predicate ? { predicate } : {}),
+  };
+}
+
+/** A predicate as the author wrote it. A CEL value reaches here as a tagged
+ *  sentinel or as an already-compiled node, and the SOURCE is the only part of
+ *  either worth showing. */
+function expressionSource(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (value === null || typeof value !== "object") return undefined;
+  const record = value as { source?: unknown; __compiled?: unknown };
+  return typeof record.source === "string" ? record.source : undefined;
+}
+
 /**
  * Emit the edges a single step's own ref slots declare.
  *
@@ -338,7 +495,21 @@ function emitStepEdges(node: StepGraphNode, ctx: StepWalkContext): void {
   for (const [key, propSchema] of propertySchemas(ctx.itemSchema)) {
     const slot = readRefSlot(propSchema);
     if (!slot || slot.kinds.length === 0) continue;
-    const targetName = refTargetName(node.step[key]);
+    const written = node.step[key];
+    const inline =
+      written !== null &&
+      typeof written === "object" &&
+      !Array.isArray(written) &&
+      isInlineResource(written as Record<string, unknown>);
+    // Every declared slot is recorded, whatever is in it: an empty one is a
+    // site an editor can fill, and a declaration written at the site is a real
+    // dispatch that emits no edge — which is what made an inline step read
+    // exactly like one that dispatches nothing.
+    node.refSlots = [
+      ...(node.refSlots ?? []),
+      { key, path: `${node.path}.${key}`, kinds: slot.kinds, ...(inline ? { inline: true } : {}) },
+    ];
+    const targetName = refTargetName(written);
     if (targetName === undefined) continue;
     const entry: RefFieldEntry = {
       refs: slot.kinds,
@@ -441,6 +612,10 @@ function walkSteps(
       step: value,
     };
     if (typeof value.name === "string") node.name = value.name;
+    const { variant, variantLabel, predicate } = classifyStep(value, ctx.itemSchema, ctx.rootSchema);
+    if (variant) node.variant = variant;
+    if (variantLabel) node.variantLabel = variantLabel;
+    if (predicate) node.predicate = predicate;
     if (parent) node.parent = parent;
     ctx.nodes.set(id, node);
     ctx.order.push(node);
@@ -498,7 +673,9 @@ export function buildCallGraph(
 ): CallGraph {
   const nodes = new Map<string, CallGraphNode>();
   const edges: CallGraphEdge[] = [];
-  const byName = new Map<string, ResourceGraphNode>();
+  /** Every declaration of a bare name, in declaration order — a name may be
+   *  declared once per module, so this is a list rather than one node. */
+  const byName = new Map<string, ResourceGraphNode[]>();
   const stepsByOwner = new Map<string, StepGraphNode[]>();
   const stepEdgesByPath = new Map<string, CallGraphEdge>();
 
@@ -527,15 +704,22 @@ export function buildCallGraph(
     if (!name || !manifest.kind || SYSTEM_KINDS.has(manifest.kind)) continue;
     const node: ResourceGraphNode = {
       type: "resource",
-      id: resourceId(manifest.kind, name as string),
+      id: nodeIdFor(manifest),
       kind: manifest.kind,
       name: name as string,
       manifest,
     };
+    if (nodes.has(node.id)) continue;
     nodes.set(node.id, node);
-    byName.set(node.name, node);
+    byName.set(node.name, [...(byName.get(node.name) ?? []), node]);
   }
 
+  const resolveByName = (
+    name: string,
+    fromModule: string | undefined,
+  ): ResourceGraphNode | undefined =>
+    resolveScopedName(byName.get(name), (node) => declaringModule(node.manifest), fromModule);
+
   // --- step nodes ---
   const collectStepsFor = (
     node: ResourceGraphNode,
@@ -565,7 +749,7 @@ export function buildCallGraph(
   };
 
   for (const node of [...nodes.values()] as ResourceGraphNode[]) {
-    collectStepsFor(node, (name) => byName.get(name));
+    collectStepsFor(node, (name) => resolveByName(name, declaringModule(node.manifest)));
   }
 
   // --- edges ---
@@ -593,7 +777,7 @@ export function buildCallGraph(
         scopeLocal = new Map();
         const ownerName = event.source.metadata?.name as string | undefined;
         if (!ownerName || !event.source.kind) return;
-        const ownerId = resourceId(event.source.kind, ownerName);
+        const ownerId = nodeIdFor(event.source);
 
         // Inline declarations inside `x-telo-scope` arrays become nodes of
         // their own, keyed by their scope site — the declaration-site identity
@@ -620,8 +804,9 @@ export function buildCallGraph(
         }
         if (scopeLocal.size === 0) return;
 
+        const ownerModule = declaringModule(event.source);
         const resolveScoped = (name: string): ResourceGraphNode | undefined =>
-          scopeLocal.get(name) ?? byName.get(name);
+          scopeLocal.get(name) ?? resolveByName(name, ownerModule);
 
         // The owner's own step edges were emitted before this scope was seen
         // (step collection precedes the visit), so their names resolved
@@ -680,7 +865,7 @@ export function buildCallGraph(
       onRef: (event) => {
         const sourceName = event.source.metadata?.name as string | undefined;
         if (!sourceName || !event.source.kind) return;
-        const sourceId = resourceId(event.source.kind, sourceName);
+        const sourceId = nodeIdFor(event.source);
         if (!nodes.has(sourceId)) return;
 
         // A site inside a step was already emitted by the step walk, which
@@ -719,9 +904,10 @@ export function buildCallGraph(
           path: event.concretePath,
           use,
         };
+        const sourceModule = declaringModule(event.source);
         const target = scopedNames.has(targetName)
-          ? (scopeLocal.get(targetName) ?? byName.get(targetName))
-          : byName.get(targetName);
+          ? (scopeLocal.get(targetName) ?? resolveByName(targetName, sourceModule))
+          : resolveByName(targetName, sourceModule);
         if (target) edge.to = target.id;
         if (unresolved) edge.unresolved = unresolved;
         if (unresolvedReason) edge.unresolvedReason = unresolvedReason;
@@ -758,8 +944,15 @@ export function buildCallGraph(
     edges,
     edgesFrom: (id) => fromIndex.get(id) ?? [],
     edgesTo: (id) => toIndex.get(id) ?? [],
-    resource: (kind, name) => nodes.get(resourceId(kind, name)) as ResourceGraphNode | undefined,
-    resourceByName: (name) => byName.get(name),
+    // Both accessors take a name with no module, so both answer for the one
+    // declaration that name has — and, where a flattened set has several, the
+    // first in declaration order. A caller that must tell two apart holds a
+    // node id, which carries the module.
+    resource: (kind, name) =>
+      (nodes.get(resourceId(kind, name)) as ResourceGraphNode | undefined) ??
+      byName.get(name)?.find((n) => n.kind === kind),
+    resourceByName: (name, fromModule) =>
+      resolveScopedName(byName.get(name), (node) => declaringModule(node.manifest), fromModule),
     steps: (ownerId) => stepsByOwner.get(ownerId) ?? [],
     controlEdges: () => edges.filter(reachesTarget),
   };

package/src/import-resolution-diagnostics.ts

@@ -1,18 +1,16 @@
 import type { GraphLoadError, LoadedGraph } from "./loaded-types.js";
 import { isLocalPathSource } from "./sources/local-path-ref.js";
-import { isRegistryRef } from "./sources/module-ref.js";
 import { isOciRef } from "./sources/oci-ref.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
 
-/** True when `source` is a shape some transport claims — a registry ref, an OCI
- *  ref, an HTTP(S) URL, or a relative/absolute path. A source matching none of
- *  these is malformed (no transport can ever resolve it), which we report
- *  differently from a well-formed ref that simply failed to fetch. */
+/** True when `source` is a shape some transport claims — an OCI ref, an HTTP(S)
+ *  URL, or a relative/absolute path. A source matching none of these is
+ *  malformed (no transport can ever resolve it), which we report differently
+ *  from a well-formed ref that simply failed to fetch. */
 function isRecognizedSourceShape(source: string): boolean {
   return (
-    isRegistryRef(source) ||
     isOciRef(source) ||
     source.startsWith("http://") ||
     source.startsWith("https://") ||
@@ -27,13 +25,32 @@ function classify(e: GraphLoadError): "INVALID_IMPORT_TARGET" | "INVALID_IMPORT_
   return isRecognizedSourceShape(e.source ?? e.url) ? "IMPORT_UNRESOLVED" : "INVALID_IMPORT_SOURCE";
 }
 
+/** The removed bare `<namespace>/<name>@<version>` ref: no scheme, not a path,
+ *  carrying both a `/` and an `@`. Recognised only to explain itself — no
+ *  migration can rewrite it, because the OCI host it moved to is not derivable
+ *  from the ref, and the failing line is frequently inside a dependency the
+ *  consumer cannot edit. The message is the whole remedy available to them. */
+function isRemovedBareRef(source: string): boolean {
+  return (
+    !source.includes("://") &&
+    !source.startsWith("/") &&
+    !source.startsWith(".") &&
+    source.includes("@") &&
+    source.includes("/")
+  );
+}
+
 function messageFor(e: GraphLoadError, code: ReturnType<typeof classify>): string {
   const authored = e.source ?? e.url;
   const via = e.alias ? `import '${e.alias}' → '${authored}'` : `'${authored}'`;
   if (code === "INVALID_IMPORT_SOURCE") {
+    const removedForm = isRemovedBareRef(authored)
+      ? ` The bare '<namespace>/<name>@<version>' form was removed — rewrite it to the ` +
+        `module's 'oci://' ref (\`telo search <name>\` reports it).`
+      : "";
     return (
       `Cannot resolve ${via}: not a recognized module reference. Expected ` +
-      `'namespace/name@version', 'oci://host/repo@tag', 'https://…', or a relative path.`
+      `'oci://host/repo@tag', 'https://…', or a relative path.${removedForm}`
     );
   }
   // The target WAS obtained, so "cannot resolve" would name the wrong problem —

package/src/index.ts

@@ -112,7 +112,13 @@ export {
   RedactionPathError,
 } from "./redaction-path.js";
 export type { RedactionSegment } from "./redaction-path.js";
-export { buildCallGraph, projectToPairs, resourceId } from "./call-graph.js";
+export {
+  buildCallGraph,
+  nodeIdFor,
+  projectToPairs,
+  resolveScopedName,
+  resourceId,
+} from "./call-graph.js";
 export type {
   BuildCallGraphOptions,
   CallGraph,
@@ -121,6 +127,31 @@ export type {
   ResourceGraphNode,
   StepGraphNode,
 } from "./call-graph.js";
+export {
+  AMBIENT_CAPABILITIES,
+  buildModuleGraph,
+  contentKey,
+  edgeClassOf,
+  isAmbientCapability,
+  isAmbientHold,
+  isOrderedRow,
+  isUnwired,
+} from "./module-graph.js";
+export type {
+  BuildModuleGraphOptions,
+  EdgeClass,
+  GraphEdge,
+  GraphKind,
+  GraphNode,
+  GraphPort,
+  GraphRegion,
+  GraphRow,
+  ModuleGraph,
+  ModuleGraphDeps,
+  NodeOwnership,
+  PortSlot,
+  RowKind,
+} from "./module-graph.js";
 export {
   buildReferenceFieldMap,
   isRefEntry,
@@ -304,7 +335,12 @@ export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validat
 export type { RefSlotIssue } from "./validate-ref-slots.js";
 export { validateValueTypeSlots } from "./validate-value-type-slots.js";
 export type { ValueTypeSlotIssue } from "./validate-value-type-slots.js";
-export { checkSchemaCompatibility, resolveRefIn, selectUnionBranch } from "./schema-compat.js";
+export {
+  checkSchemaCompatibility,
+  collectProperties,
+  resolveRefIn,
+  selectUnionBranch,
+} from "./schema-compat.js";
 export type { CompatibilityResult, ExternalSchemaResolver } from "./schema-compat.js";
 export {
   ajvErrorToPath,
@@ -362,7 +398,6 @@ export {
 } from "./position-metadata.js";
 export type { DocumentPosition } from "./position-metadata.js";
 export { HttpSource } from "./sources/http-source.js";
-export { RegistrySource } from "./sources/registry-source.js";
 export { defaultSources } from "./sources/default-sources.js";
 export {
   splitIntegrity,
@@ -373,8 +408,6 @@ export {
   sha256Base64Url,
   IntegrityError,
 } from "./sources/integrity.js";
-export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
-export type { ParsedModuleRef } from "./sources/module-ref.js";
 export { OCI_SCHEME, isOciRef, parseOciRef } from "./sources/oci-ref.js";
 export type { ParsedOciRef } from "./sources/oci-ref.js";
 export { parseVersionedRef, withRefVersion } from "./sources/versioned-ref.js";

package/src/loaded-types.ts

@@ -12,9 +12,9 @@ import type { AstDocument } from "./yaml-ast.js";
  *  cache uses `source` — the URL the source adapter's `read()` returned. */
 export interface LoadedFile {
   /** Canonical identity. The URL the source adapter's `read()` returned —
-   *  HTTPS for http/registry, an absolute path for local. */
+   *  HTTPS for a remote module, an absolute path for local. */
   source: string;
-  /** The URL the caller supplied (e.g. registry ref `std/javascript@0.3.0`).
+  /** The URL the caller supplied (e.g. `oci://ghcr.io/telorun/javascript@0.3.0`).
    *  Differs from `source` only for adapter-resolved URLs. */
   requestedUrl: string;
   /** Raw text exactly as `read()` returned it. */
@@ -65,8 +65,8 @@ export interface LoadedModule {
 export interface ImportEdge {
   /** Canonical resolved URL of the target — a key into `modules`. */
   targetSource: string;
-  /** The import's `source` exactly as authored — a registry ref, an `oci://`
-   *  or `https://` ref, or a relative path. Version reconciliation keys on
+  /** The import's `source` exactly as authored — an `oci://` or `https://`
+   *  ref, or a relative path. Version reconciliation keys on
    *  this (minus its version), since it names the module's location
    *  independently of what the module declares about itself. */
   targetRef: string;

package/src/manifest-analysis.ts

@@ -27,7 +27,14 @@ import { CelScopeQuery, type CelScopeQueryContext } from "./cel-scope-query.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import type { ContractDirection } from "./extends-resolution.js";
 import { analyzerContractScope, resolveContract } from "./invocation-contract.js";
+import { buildCallGraph, type CallGraph } from "./call-graph.js";
 import { findManifest } from "./find-manifest.js";
+import {
+  buildModuleGraph,
+  type BuildModuleGraphOptions,
+  type ModuleGraph,
+  type ModuleGraphDeps,
+} from "./module-graph.js";
 import { isModuleKind } from "./module-kinds.js";
 
 /**
@@ -43,6 +50,8 @@ export interface ManifestRef {
 export class ManifestAnalysis {
   private readonly scopes: ModuleScopes;
   private celScopeQuery: CelScopeQuery | undefined;
+  private callGraphMemo: CallGraph | undefined;
+  private moduleGraphMemo: ModuleGraph | undefined;
 
   constructor(
     readonly manifests: ResourceManifest[],
@@ -62,6 +71,36 @@ export class ManifestAnalysis {
     return (this.celScopeQuery ??= new CelScopeQuery(this.manifests, this.ctx));
   }
 
+  /** What calls what. Built on first use and kept, so the projection and any
+   *  other consumer over this set share one. */
+  private get callGraph(): CallGraph {
+    return (this.callGraphMemo ??= buildCallGraph(this.manifests, this.ctx.defs, {
+      aliases: this.ctx.aliases,
+      aliasesByModule: this.ctx.aliasesByModule,
+    }));
+  }
+
+  /**
+   * The module graph: boxes, ordered rows and classed edges — the projection an
+   * editor draws.
+   *
+   * Here rather than on the registry because it is the registry AND a manifest
+   * set, which is the pairing this class exists to name; a fifth
+   * `registry.x(manifests, …)` factory is the accretion naming it stopped. It
+   * shares this analysis's call graph rather than building one of its own.
+   *
+   * `deps` is supplied by the registry, which owns capability resolution — this
+   * class holds the manifests, not the rules for reading a kind.
+   */
+  moduleGraph(deps: ModuleGraphDeps, options: BuildModuleGraphOptions = {}): ModuleGraph {
+    return (this.moduleGraphMemo ??= buildModuleGraph(
+      this.manifests,
+      this.callGraph,
+      deps,
+      options,
+    ));
+  }
+
   /** The manifest a `(kind, name)` pair addresses. */
   resourceFor(kind: string | undefined, name: string | undefined): ResourceManifest | undefined {
     return findManifest(this.manifests, kind, name);

package/src/manifest-loader.ts

@@ -146,7 +146,7 @@ export class Loader {
    *  when a URL it has already canonicalised is requested again — kernel
    *  load → boot and the import-controller each ask the loader for the same
    *  modules. Without this fast path every duplicate request re-runs the
-   *  source's `read()` (a `fetch` for `RegistrySource`, a disk read for
+   *  source's `read()` (a `fetch` for `HttpSource`, a disk read for
    *  `LocalFileSource`). */
   private readonly urlToSource = new Map<string, string>();
 
@@ -157,8 +157,7 @@ export class Loader {
   /** Sources are resolved in order — the first whose `supports(url)` matches
    *  wins. The caller (composition root) decides which concrete sources exist
    *  and supplies them; `defaultSources()` bundles the browser-safe built-ins
-   *  (HTTP + registry) for the common case. `register()` prepends a source at
-   *  runtime. */
+   *  (HTTP) for the common case. `register()` prepends a source at runtime. */
   constructor(sources: ManifestSource[] = [], options: LoaderInitOptions = {}) {
     this.sources = [...sources];
     this.celEnv = buildCelEnvironment(options.celHandlers);
@@ -181,7 +180,7 @@ export class Loader {
     // entry are populated in `urlToSource` + `fileCache` in one read.
     // Callers (kernel.load) immediately call `loadGraph(entryUrl)`
     // afterwards — without this priming, the entry file would be read
-    // twice (twice over the network for `RegistrySource`).
+    // twice (twice over the network for `HttpSource`).
     const file = await this.loadFile(url);
     return file.source;
   }
@@ -469,7 +468,7 @@ export class Loader {
 
   /** Resolve an `import` URL against the file it appears in. Relative /
    *  absolute-path forms run through the owning `ManifestSource`'s
-   *  `resolveRelative`; registry refs and full URLs pass through
+   *  `resolveRelative`; scheme-qualified refs and full URLs pass through
    *  unchanged. Exposed so the import-controller (and any other
    *  caller-side resolver) lands on the *exact same* canonical URL the
    *  loader used when walking the entry graph — divergent resolution

package/src/manifest-schemas.ts

@@ -241,6 +241,10 @@ export const InvokeStepSchema = {
     when: {
       title: "When",
       description: "CEL guard — the dispatch is skipped when it evaluates false.",
+      // The same role `if:` and `while:` carry: it is the expression that
+      // decides whether the statement runs, and a surface showing what a step
+      // is conditional on should not have to know which keyword spelled it.
+      "x-telo-topology-role": "predicate",
       type: "string",
     },
     retry: {