@telorun/analyzer 0.67.0 → 0.69.0

package/dist/validate-sensitive-slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-sensitive-slots.d.ts","sourceRoot":"","sources":["../src/validate-sensitive-slots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gCAAgC,GAAG,8BAA8B,CAAC;IACxE,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,EAAE,CAqDvF"}

package/dist/validate-sensitive-slots.js

@@ -0,0 +1,75 @@
+import { SCHEMA_REGION_KEYS } from "./schema-region.js";
+const ANNOTATION = "x-telo-sensitive";
+/** The only regions the kernel reads the annotation from. */
+const CONTRACT_KEYS = new Set(["inputType", "outputType"]);
+export function validateSensitiveSlots(manifest) {
+    const issues = [];
+    const walk = (node, path, seen) => {
+        if (!node || typeof node !== "object")
+            return;
+        if (seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            node.forEach((child, i) => walk(child, [...path, i], seen));
+            return;
+        }
+        const record = node;
+        if (Object.hasOwn(record, ANNOTATION)) {
+            const dotted = path.join(".");
+            if (record[ANNOTATION] !== true) {
+                issues.push({
+                    code: "SENSITIVE_ANNOTATION_INVALID",
+                    manifest,
+                    path: dotted,
+                    message: `'${ANNOTATION}' must be \`true\`; got ${JSON.stringify(record[ANNOTATION])}. ` +
+                        `It is a marker, not a level — a value other than \`true\` reads as "not sensitive".`,
+                });
+            }
+            else {
+                const region = enclosingSchemaRegion(path);
+                if (region === undefined || !CONTRACT_KEYS.has(region)) {
+                    issues.push({
+                        code: "SENSITIVE_ANNOTATION_MISPLACED",
+                        manifest,
+                        path: dotted,
+                        message: `'${ANNOTATION}' is only read from a resource's declared contract ` +
+                            `(\`inputType\` / \`outputType\`), and this node is ` +
+                            (region === undefined
+                                ? "not inside a schema at all"
+                                : `inside \`${region}\``) +
+                            `. The kernel will not redact it, so the value would still reach trace ` +
+                            `payloads and the debug wire. Move the mark onto the contract property ` +
+                            `that carries the value.`,
+                    });
+                }
+            }
+        }
+        for (const [key, child] of Object.entries(record)) {
+            walk(child, [...path, key], seen);
+        }
+    };
+    walk(manifest, [], new Set());
+    return issues;
+}
+/**
+ * The OUTERMOST segment naming a schema-valued key, or `undefined` when the node
+ * is not inside a schema.
+ *
+ * Outermost, not nearest, because a contract is routinely written in the inline
+ * `{kind: Telo.JsonSchema, schema: …}` form — so the path to a marked property is
+ * `outputType.schema.properties.headers`, and the nearest region key is that
+ * wrapper's own `schema`. Reading it as a kind's configuration would report every
+ * correctly-marked contract as misplaced, which is how this check first behaved.
+ *
+ * It is the same reasoning `expandManifestFragments` uses when it keys on the
+ * top-level slot: the object a contract resolver is handed is the one under
+ * `inputType` / `outputType`, whatever nesting the authoring form adds beneath.
+ */
+function enclosingSchemaRegion(path) {
+    for (const segment of path) {
+        if (typeof segment === "string" && SCHEMA_REGION_KEYS.includes(segment))
+            return segment;
+    }
+    return undefined;
+}

package/dist/value-type-keyword.d.ts

@@ -28,7 +28,7 @@ import type { KeywordDefinition } from "ajv";
  *
  * `x-telo-type` is deliberately absent — it is the one that emits code.
  */
-export declare const ANNOTATION_KEYWORDS: readonly ["x-telo-bindings-from", "x-telo-catches-for", "x-telo-context", "x-telo-context-collection-from", "x-telo-context-element-from", "x-telo-context-from", "x-telo-context-from-ref-kind", "x-telo-context-from-root", "x-telo-context-ref-from", "x-telo-error-context", "x-telo-eval", "x-telo-inline", "x-telo-outcome-list", "x-telo-provides-zone", "x-telo-ref", "x-telo-requires-zone", "x-telo-resource-rules", "x-telo-schema-from", "x-telo-schema-map", "x-telo-schema-projection", "x-telo-schema-projection-from", "x-telo-scope", "x-telo-step-context", "x-telo-topology-role", "x-telo-value-schema-from", "x-telo-widget"];
+export declare const ANNOTATION_KEYWORDS: readonly ["x-telo-bindings-from", "x-telo-catches-for", "x-telo-context", "x-telo-context-collection-from", "x-telo-context-element-from", "x-telo-context-from", "x-telo-context-from-ref-kind", "x-telo-context-from-root", "x-telo-context-ref-from", "x-telo-error-context", "x-telo-eval", "x-telo-inline", "x-telo-outcome-list", "x-telo-provides-zone", "x-telo-ref", "x-telo-requires-zone", "x-telo-resource-rules", "x-telo-schema-from", "x-telo-schema-map", "x-telo-schema-projection", "x-telo-schema-projection-from", "x-telo-scope", "x-telo-sensitive", "x-telo-step-context", "x-telo-topology-role", "x-telo-value-schema-from", "x-telo-widget"];
 /**
  * The `x-telo-type` keyword.
  *

package/dist/value-type-keyword.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-type-keyword.d.ts","sourceRoot":"","sources":["../src/value-type-keyword.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;+EAqB+E;AAG/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,KAAK,CAAC;AAiB7C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,onBA2BtB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CA+BpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IACxC,UAAU,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;CACzD,GAAG,IAAI,CAGP"}
+{"version":3,"file":"value-type-keyword.d.ts","sourceRoot":"","sources":["../src/value-type-keyword.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;+EAqB+E;AAG/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,KAAK,CAAC;AAiB7C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,woBA4BtB,CAAC;AAEX;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CA+BpD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE;IACxC,UAAU,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,UAAU,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;CACzD,GAAG,IAAI,CAGP"}

package/dist/value-type-keyword.js

@@ -54,6 +54,7 @@ export const ANNOTATION_KEYWORDS = [
     "x-telo-schema-projection",
     "x-telo-schema-projection-from",
     "x-telo-scope",
+    "x-telo-sensitive",
     "x-telo-step-context",
     "x-telo-topology-role",
     "x-telo-value-schema-from",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.67.0",
+  "version": "0.69.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",

package/src/analysis-registry.ts

@@ -1,12 +1,14 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { AliasResolver } from "./alias-resolver.js";
 import { KERNEL_BUILTINS } from "./builtins.js";
+import type { BuildModuleGraphOptions, ModuleGraphDeps } from "./module-graph.js";
 import { ManifestAnalysis } from "./manifest-analysis.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import { computeSuggestKind, computeValidUserFacingKinds } from "./kind-suggest.js";
 import { visitManifest as runVisitManifest, type ManifestVisitor } from "./manifest-visitor.js";
 import type { ContractDirection, DefResolver } from "./extends-resolution.js";
 import { resolveContract } from "./invocation-contract.js";
+import { createResolveCtx, resolveThrowsUnion } from "./resolve-throws-union.js";
 import { isRefEntry, isScopeEntry } from "./reference-field-map.js";
 import { resolveSchemaTypeRefs as resolveSchemaTypeRefsIn } from "./resolve-schema-type-refs.js";
 import type { AnalysisContext } from "./types.js";
@@ -279,6 +281,41 @@ export class AnalysisRegistry {
     });
   }
 
+  /**
+   * What the projection needs that only this registry knows: how a kind
+   * resolves, what its reference slots are, which capabilities they target, and
+   * what a resource can raise.
+   *
+   * The GRAPH itself is built by `ManifestAnalysis.moduleGraph`, which is the
+   * pairing of a registry with a manifest set — a fifth
+   * `registry.x(manifests, …)` factory is the accretion naming that class
+   * stopped. This is the half the registry owns.
+   */
+  moduleGraphDeps(
+    manifests: ResourceManifest[],
+    options: BuildModuleGraphOptions = {},
+  ): ModuleGraphDeps {
+    // The error contract is resolved through the SAME resolver `telo check`
+    // uses, memoized across the whole graph — so what a box says it can raise
+    // is what a route's `catches:` is validated against.
+    const throwsCtx = createResolveCtx(
+      manifests,
+      this.defs,
+      this.aliases,
+      this.aliasesByModule,
+      new Set(options.entryModule ? [options.entryModule] : []),
+    );
+    return {
+      refFields: (resource) => this.refFieldsForResource(resource),
+      definition: (kind, module) => this.resolveDefinitionIn(kind, module),
+      aliasesForModule: (module) => this.aliases.aliasesFor(module),
+      throwsOf: (resource) => {
+        const union = resolveThrowsUnion(resource, throwsCtx);
+        return { codes: [...union.codes.keys()], unbounded: union.unbounded };
+      },
+    };
+  }
+
   /**
    * Returns the built-in kernel definitions. The underlying DefinitionRegistry already
    * seeds these on construction; this method exposes them so callers (e.g. the kernel's

package/src/analyzer.ts

@@ -108,6 +108,10 @@ import {
   validateValueTypeSlots,
   type ValueTypeSlotIssue,
 } from "./validate-value-type-slots.js";
+import {
+  validateSensitiveSlots,
+  type SensitiveSlotIssue,
+} from "./validate-sensitive-slots.js";
 import { resolveSchemaTypeRefs } from "./resolve-schema-type-refs.js";
 import { validateSchemaTypeRefs } from "./validate-schema-type-refs.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
@@ -979,10 +983,16 @@ export class StaticAnalyzer {
     // definition's `schema:` does. Same scoping as every other schema issue —
     // the entry's own modules, since a dependency is not the consumer's to fix.
     const valueTypeSlotIssues: ValueTypeSlotIssue[] = [];
+    // `x-telo-sensitive` rides the same walk and the same scoping. It is read by
+    // ONE consumer — the kernel, off a bound contract — so an occurrence outside
+    // `inputType` / `outputType` is inert; for a security control, inert-and-
+    // silent is the failure worth reporting.
+    const sensitiveSlotIssues: SensitiveSlotIssue[] = [];
     for (const m of manifests) {
       const declaringModule = (m.metadata as { module?: string } | undefined)?.module;
       if (!declaringModule || rootModules.has(declaringModule)) {
         valueTypeSlotIssues.push(...validateValueTypeSlots(m as unknown as ResourceManifest));
+        sensitiveSlotIssues.push(...validateSensitiveSlots(m as unknown as ResourceManifest));
       }
     }
     for (const m of manifests) {
@@ -1212,6 +1222,22 @@ export class StaticAnalyzer {
           },
         });
       }
+      for (const issue of sensitiveSlotIssues) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: issue.code,
+          source: SOURCE,
+          message: issue.message,
+          data: {
+            resource: {
+              kind: issue.manifest.kind,
+              name: issue.manifest.metadata?.name as string,
+            },
+            filePath: (issue.manifest.metadata as { source?: string } | undefined)?.source,
+            path: issue.path,
+          },
+        });
+      }
       // Same split for the two zone annotations. Unreadable ones fail in
       // OPPOSITE directions — a dropped requirement is silently unenforced, a
       // dropped provision invents failures — so neither can be left to

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/extends-resolution.ts

@@ -137,6 +137,39 @@ export function effectiveAuthorSchema(
   return mergeTypeSchemas([parentSchema, own]) as Record<string, any>;
 }
 
+/**
+ * The fields a merge-form inheriting child publishes over its parent's reading.
+ *
+ * A child that inherits its controller by delegation and declares no `base:` IS
+ * the parent instance, so `resources.<child>` is the parent's `snapshot()` — and
+ * a field the parent has never heard of would be readable from nowhere. These
+ * are exactly those fields: the ones the effective (merged) schema declares that
+ * the controller-bearing ancestor's does not.
+ *
+ * A REDECLARED name is deliberately excluded. Narrowing an inherited field (a
+ * description, a pattern, a widget hint) is ordinary in an additive extension and
+ * says nothing about publication, while the parent's `snapshot()` is the sole
+ * authority on what a parent instance publishes — its normalizations, its
+ * deliberate omissions, and its redactions. Republishing such a field from raw
+ * config would silently undo a provider's decision to keep it out.
+ *
+ * Empty for the `base:` form, whose fields are construction inputs consumed by
+ * the mapping, and for a child with its own controller, which publishes itself.
+ */
+export function publishedOwnFields(
+  def: ResourceDefinition | undefined,
+  resolve: DefResolver,
+): string[] {
+  if (body(def).base || !isInheritedDelegation(def, resolve)) return [];
+  const ancestor = controllerBearingAncestor(def, resolve);
+  if (!ancestor) return [];
+  const inherited = new Set(
+    Object.keys((effectiveAuthorSchema(ancestor, resolve).properties ?? {}) as object),
+  );
+  const own = (effectiveAuthorSchema(def, resolve).properties ?? {}) as Record<string, unknown>;
+  return Object.keys(own).filter((name) => !inherited.has(name));
+}
+
 /** The two directions of a kind's invocation contract. `inputType` is what a
  *  caller sends to `invoke()`; `outputType` is what `invoke()` / `provide()`
  *  returns. */

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 —