@telorun/analyzer 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -29,7 +29,8 @@
       "bun": "./src/index.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist/**",
@@ -41,14 +42,16 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/sdk": "0.11.1",
-    "@telorun/templating": "0.2.3"
+    "@telorun/templating": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8"
   },
+  "peerDependencies": {
+    "@telorun/sdk": "0.12.0"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",
     "test": "vitest run",

package/src/analysis-registry.ts

@@ -101,6 +101,43 @@ export class AnalysisRegistry {
     return computeSuggestKind(badKind, this.aliases, this.defs);
   }
 
+  /** Returns every user-facing (alias-form) kind that satisfies the given
+   *  `x-telo-ref` constraint string (e.g. `"telo#Invocable"`, `"std/sql#Connection"`).
+   *  Resolution mirrors `validateReferences.checkKind`: abstract targets expand to
+   *  the set of definitions extending them; concrete targets yield just themselves.
+   *  Returns `undefined` when the ref can't be resolved (e.g. unregistered identity),
+   *  so callers can fall back to the unfiltered kind list. */
+  userFacingKindsForRef(xTeloRef: string): string[] | undefined {
+    const targetKind = this.defs.resolveRef(xTeloRef);
+    if (!targetKind) return undefined;
+    const targetDef = this.defs.resolve(targetKind);
+    if (!targetDef) return undefined;
+
+    const canonicalKinds: string[] = [];
+    if (targetDef.kind === "Telo.Abstract") {
+      for (const def of this.defs.getByExtends(targetKind)) {
+        const module = (def.metadata as { module?: string } | undefined)?.module;
+        if (module && def.metadata?.name) {
+          canonicalKinds.push(`${module}.${def.metadata.name as string}`);
+        }
+      }
+    } else {
+      canonicalKinds.push(targetKind);
+    }
+
+    const out = new Set<string>();
+    for (const kind of canonicalKinds) {
+      const dot = kind.indexOf(".");
+      if (dot === -1) continue;
+      const moduleName = kind.slice(0, dot);
+      const typeName = kind.slice(dot + 1);
+      for (const alias of this.aliases.aliasesFor(moduleName)) {
+        out.add(`${alias}.${typeName}`);
+      }
+    }
+    return Array.from(out);
+  }
+
   /** @internal Bridge for StaticAnalyzer — do not use outside the analyzer package. */
   _context(): AnalysisContext {
     return { aliases: this.aliases, definitions: this.defs, aliasesByModule: this.aliasesByModule };

package/src/analyzer.ts

@@ -14,6 +14,9 @@ import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kerne
 import { computeSuggestKind } from "./kind-suggest.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
+import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
+import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
+import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import {
   celTypeSatisfiesJsonSchema,
   substituteCelFields,
@@ -28,11 +31,45 @@ import {
   resolveTypeFieldToSchema,
 } from "./validate-cel-context.js";
 import { validateExtends } from "./validate-extends.js";
+import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
 const SELF_PREFIX = "Self.";
 
+/**
+ * `StaticAnalyzer.analyze()` requires `metadata.source` (non-empty) and
+ * `metadata.sourceLine` (number) on every non-system manifest — see the
+ * JSDoc on `analyze()`. Production callers stamp these via the `Loader` /
+ * `flattenForAnalyzer` / `emitDocsFor` paths; programmatic callers (tests,
+ * scripts) should pre-process inputs with `withSyntheticPositions(...)`.
+ * Surfacing the violation here turns silent dedup misbehaviour into a
+ * loud, actionable error.
+ */
+function assertManifestPositions(manifests: ResourceManifest[]): void {
+  for (let i = 0; i < manifests.length; i++) {
+    const m = manifests[i];
+    if (REF_VALIDATION_SKIP_KINDS.has(m.kind)) continue;
+    const meta = m.metadata as { source?: string; sourceLine?: number } | undefined;
+    const okSource = typeof meta?.source === "string" && meta.source.length > 0;
+    const okLine = typeof meta?.sourceLine === "number";
+    if (okSource && okLine) continue;
+    const label = `${m.kind}/${m.metadata?.name ?? "(unnamed)"}`;
+    const missing = [
+      !okSource ? "metadata.source" : null,
+      !okLine ? "metadata.sourceLine" : null,
+    ]
+      .filter(Boolean)
+      .join(" and ");
+    throw new Error(
+      `StaticAnalyzer.analyze(): manifest #${i} (${label}) is missing ${missing}. ` +
+        `Real callers stamp positions automatically; programmatic callers ` +
+        `(tests, ad-hoc scripts) should pass inputs through ` +
+        `\`withSyntheticPositions(manifests)\` before calling analyze().`,
+    );
+  }
+}
+
 /** Resolve an alias-prefixed kind value (e.g. `Self.Encoder` or `Ai.Model`)
  *  to its canonical form. `Self.<Name>` resolves to `<ownModule>.<Name>` —
  *  the magic alias for "this library's own module" — and other prefixes
@@ -493,11 +530,27 @@ export class StaticAnalyzer {
     this.celEnv = buildCelEnvironment(options.celHandlers);
   }
 
+  /**
+   * Run static analysis over a flattened manifest list.
+   *
+   * **Contract**: every non-system manifest (anything outside `Telo.Definition`,
+   * `Telo.Abstract`) must carry `metadata.source` (non-empty string) and
+   * `metadata.sourceLine` (number). The dedup that backs
+   * `DUPLICATE_RESOURCE_NAME` reads those fields to tell a pipeline echo
+   * apart from a genuine collision, and downstream diagnostic positioning
+   * depends on them too. Real callers stamp positions already (the `Loader`,
+   * `flattenForAnalyzer`, the telo-editor's `emitDocsFor`, the VSCode
+   * extension). Programmatic callers — tests, ad-hoc scripts — should pass
+   * their inputs through `withSyntheticPositions(...)` before calling
+   * `analyze()`. A missing position throws a clear error rather than
+   * silently producing wrong diagnostics.
+   */
   analyze(
     manifests: ResourceManifest[],
     options?: AnalysisOptions,
     registry?: AnalysisRegistry,
   ): AnalysisDiagnostic[] {
+    assertManifestPositions(manifests);
     const diagnostics: AnalysisDiagnostic[] = [];
 
     // Use pre-seeded registries from the provided AnalysisRegistry, or create fresh ones.
@@ -621,6 +674,22 @@ export class StaticAnalyzer {
     // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
     const allManifests = normalizeInlineResources(manifests, defs, aliases, aliasesByModule);
 
+    // Phase 2.5: resolve `!ref <name>` sentinels at every ref slot to canonical
+    // {kind, name} objects so downstream phases (validation, dependency graph,
+    // kernel controllers) see a uniform shape. Runs after normalize so both
+    // original and inline-extracted manifests have their sentinels resolved.
+    resolveRefSentinels(allManifests, defs, aliases, aliasesByModule);
+
+    // Trusted-input fast path: when the caller has already attested that
+    // this exact manifest set passes analysis (e.g. via the kernel's
+    // hash-stamped `.validated.json` cache), skip the validation walk.
+    // Registration of identities / aliases / definitions and inline-resource
+    // normalisation have already run above; that's all downstream
+    // consumers (prepare, init loop) require.
+    if (options?.skipValidation) {
+      return diagnostics;
+    }
+
     // Build a name→manifest map for looking up referenced resources
     const byName = new Map<string, ResourceManifest>();
     for (const m of allManifests) {
@@ -629,6 +698,35 @@ export class StaticAnalyzer {
       }
     }
 
+    // Library env: rejection — `env:` on a Library `variables` / `secrets`
+    // entry is forbidden. The Library entry schema is otherwise open so that
+    // any JSON Schema property schema is valid; this targeted check produces
+    // a clear diagnostic instead of a generic "additional property" error.
+    for (const m of allManifests) {
+      if (m.kind !== "Telo.Library") continue;
+      const filePath = (m.metadata as { source?: string } | undefined)?.source;
+      const moduleName = m.metadata?.name as string | undefined;
+      const resource = moduleName ? { kind: m.kind, name: moduleName } : undefined;
+      for (const block of ["variables", "secrets"] as const) {
+        const entries = (m as Record<string, any>)[block];
+        if (!entries || typeof entries !== "object" || Array.isArray(entries)) continue;
+        for (const [entryName, entry] of Object.entries(entries)) {
+          if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+          if ("env" in (entry as Record<string, unknown>)) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "LIBRARY_ENV_KEY_REJECTED",
+              source: SOURCE,
+              message:
+                `Telo.Library ${block}/${entryName}: 'env:' is only permitted on Telo.Application entries. ` +
+                `Libraries must receive values from importers via the parent manifest's variables / secrets block.`,
+              data: { resource, filePath, path: `${block}.${entryName}.env` },
+            });
+          }
+        }
+      }
+    }
+
     // Build typed kernel globals schema so x-telo-context chain validation
     // recognises variables, secrets, resources, env automatically
     const kernelGlobals = buildKernelGlobalsSchema(allManifests);
@@ -776,17 +874,15 @@ export class StaticAnalyzer {
         }
       }
 
-      // Top-level `result:` (a sibling, only meaningful with `provide:`) is a
-      // post-call mapping that must satisfy the abstract this definition
-      // `extends` (`outputType`). The target's outputType lives on `provide.kind`
+      // Top-level `result:` is a post-call mapping that must satisfy the abstract
+      // this definition `extends` (`outputType`). It's a sibling of whichever
+      // dispatch entry-point declared a kind-typed target (`provide:` or
+      // `invoke:`). The target's outputType lives on the dispatcher's `kind`
       // and is what `result` is typed against *inside* CEL — separate role.
-      if (
-        provide &&
-        typeof provide === "object" &&
-        !Array.isArray(provide) &&
-        md.result &&
-        typeof md.result === "object"
-      ) {
+      const hasDispatchObject =
+        (provide && typeof provide === "object" && !Array.isArray(provide)) ||
+        (invoke && typeof invoke === "object" && !Array.isArray(invoke));
+      if (hasDispatchObject && md.result && typeof md.result === "object") {
         const extendsValue = md.extends as string | undefined;
         if (typeof extendsValue === "string" && extendsValue.length > 0) {
           const abstractSchema = lookupDefinitionTypeField(
@@ -920,10 +1016,15 @@ export class StaticAnalyzer {
     // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
     diagnostics.push(...validateExtends(allManifests, defs, aliases));
 
+    // Validate provider coherence rules for `provide:` template-target definitions.
+    diagnostics.push(...validateProviderCoherence(allManifests, defs, aliases));
+
     // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
     diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv));
 
-    return diagnostics;
+    // Reroute diagnostics on synthetic (inline-extracted) resources back to
+    // the chain root so position-index lookups land on the parent doc.
+    return rewriteSyntheticOrigins(diagnostics, allManifests);
   }
 
   analyzeErrors(
@@ -938,12 +1039,17 @@ export class StaticAnalyzer {
 
   normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[] {
     const ctx = registry._context();
-    return normalizeInlineResources(
+    const normalized = normalizeInlineResources(
       manifests,
       ctx.definitions!,
       ctx.aliases,
       ctx.aliasesByModule,
     );
+    // Resolve !ref sentinels after normalize so both the original and
+    // inline-extracted manifests get their refs canonicalized to
+    // {kind, name} for the kernel that consumes this output.
+    resolveRefSentinels(normalized, ctx.definitions!, ctx.aliases, ctx.aliasesByModule);
+    return normalized;
   }
 
   prepare(

package/src/builtins.ts

@@ -149,7 +149,12 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             additionalProperties: false,
             properties: {
               self: { "x-telo-context-from-root": "schema" },
-              result: { "x-telo-context-from-ref-kind": "provide/kind#outputType" },
+              result: {
+                "x-telo-context-from-ref-kind": [
+                  "provide/kind#outputType",
+                  "invoke/kind#outputType",
+                ],
+              },
             },
           },
         },
@@ -215,6 +220,20 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             anyOf: [
               { type: "string", "x-telo-ref": "telo#Runnable" },
               { type: "string", "x-telo-ref": "telo#Service" },
+              // Post-resolution shape that `resolveRefSentinels`
+              // substitutes a `!ref <name>` sentinel into. The
+              // adjacent `x-telo-ref` constraints govern the kind
+              // check; this branch only admits the structural form so
+              // AJV doesn't reject a resolved ref.
+              {
+                type: "object",
+                required: ["kind", "name"],
+                properties: {
+                  kind: { type: "string" },
+                  name: { type: "string" },
+                },
+                additionalProperties: true,
+              },
             ],
           },
         },
@@ -222,6 +241,44 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
+        // Application-level environment contract. Each entry layers `env:`
+        // (required, names the source env var) and `default:` (optional, used
+        // when the env var is unset) on top of an open JSON Schema property
+        // schema. `type:` constrains the coercion rule applied to the raw env
+        // string (scalars per-type; `object` / `array` via JSON.parse with the
+        // matching top-level type). All other JSON Schema keywords are passed
+        // through unchanged and applied to the coerced value via the standard
+        // schema validator. See kernel/nodejs/src/application-env.ts.
+        variables: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            required: ["env", "type"],
+            properties: {
+              env: { type: "string" },
+              type: {
+                type: "string",
+                enum: ["string", "integer", "number", "boolean", "object", "array"],
+              },
+              default: {},
+            },
+          },
+        },
+        secrets: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            required: ["env", "type"],
+            properties: {
+              env: { type: "string" },
+              type: {
+                type: "string",
+                enum: ["string", "integer", "number", "boolean", "object", "array"],
+              },
+              default: {},
+            },
+          },
+        },
       },
       required: ["metadata"],
       additionalProperties: false,

package/src/definition-registry.ts

@@ -80,6 +80,21 @@ export class DefinitionRegistry {
    *  @param namespace  The module's metadata.namespace (e.g. "std"), or null for telo built-ins.
    *  @param moduleName The module's metadata.name (e.g. "pipeline", "http-server"). */
   registerModuleIdentity(namespace: string | null, moduleName: string): void {
+    // The "telo" identity is reserved for the Telo built-in module and gets
+    // populated automatically when a Telo.Abstract definition registers (see
+    // `register` below). A user app / library without a namespace must NOT
+    // claim it — silently overwriting the built-in entry breaks every
+    // x-telo-ref that resolves through "telo#…". Concretely, the
+    // `Http.Api.routes[].handler` slot in the http-server schema carries
+    // `x-telo-ref: "telo#Invocable"`. If the entry application is, say,
+    // `Telo.Application/HelloApi` (no namespace), this method previously
+    // overwrote `"telo" → "Telo"` with `"telo" → "HelloApi"`. The handler's
+    // ref then resolved to a nonexistent `HelloApi.Invocable`, the
+    // kind-mismatch check inside `validate-references.ts` short-circuited
+    // on partial context, and the analyzer reported zero issues for a
+    // manifest that explodes at runtime. Skip non-Telo no-namespace modules;
+    // they have no x-telo-ref identity to declare anyway.
+    if (!namespace && moduleName !== "Telo") return;
     const identity = namespace ? `${namespace}/${moduleName}` : "telo";
     this.identityMap.set(identity, moduleName);
     this.reverseIdentityMap.set(moduleName, identity);

package/src/dependency-graph.ts

@@ -1,7 +1,9 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { isRefEntry, isScopeEntry, resolveFieldValues } from "./reference-field-map.js";
+import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
 export interface ResourceNode {
   kind: string;
@@ -17,16 +19,6 @@ export interface DependencyGraph {
   cycle?: ReadonlyArray<ResourceNode>;
 }
 
-/** System resource kinds that are not runtime nodes in the dependency graph.
- *  Module-identity docs (Telo.Application, Telo.Library) are intentionally
- *  not in this set: an Application's `targets` use `x-telo-ref` to real
- *  Runnable/Service resources, so the Application legitimately depends on
- *  them in boot order — modeling that as a graph edge is correct. A Library
- *  has no `targets`, so it becomes a zero-edge node, which is harmless.
- *  If the graph is ever consumed as "things to init", skip these kinds at
- *  the consumer site; the controller already runs them separately. */
-const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Import"]);
-
 const nodeKey = (kind: string, name: string) => `${kind}\0${name}`;
 
 /**
@@ -47,12 +39,18 @@ export function buildDependencyGraph(
   aliases?: AliasResolver,
   aliasesByModule?: Map<string, AliasResolver>,
 ): DependencyGraph {
-  // --- Build node set ---
+  // --- Build node set + name index ---
   const nodes = new Map<string, ResourceNode>();
+  // Sentinel lookup (`!ref <name>`) needs to resolve a bare name to its
+  // declared kind. Names are unique within a manifest scope, so a flat
+  // map suffices and lets the sentinel branch below avoid a full
+  // O(N) scan of the node set on every reference.
+  const nodesByName = new Map<string, ResourceNode>();
   for (const r of resources) {
     if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
-    const key = nodeKey(r.kind, r.metadata.name as string);
-    nodes.set(key, { kind: r.kind, name: r.metadata.name as string });
+    const node = { kind: r.kind, name: r.metadata.name as string };
+    nodes.set(nodeKey(node.kind, node.name), node);
+    nodesByName.set(node.name, node);
   }
 
   // --- Build adjacency: from → deps (from depends on dep) ---
@@ -90,7 +88,22 @@ export function buildDependencyGraph(
       if (!isRefEntry(entry)) continue;
 
       for (const val of resolveFieldValues(r, fieldPath)) {
-        if (!val || typeof val !== "object") continue;
+        if (!val) continue;
+
+        // `!ref <name>` sentinel — look up the target's kind from the
+        // name (resources are unique by name) so the edge carries the
+        // concrete kind, matching the {kind, name} edge shape below.
+        if (isRefSentinel(val)) {
+          const refName = val.source;
+          if (scopedNames.has(refName)) continue;
+          const node = nodesByName.get(refName);
+          if (node) {
+            deps.get(sourceKey)!.add(nodeKey(node.kind, node.name));
+          }
+          continue;
+        }
+
+        if (typeof val !== "object") continue;
         const ref = val as Record<string, unknown>;
         if (!ref.kind || !ref.name) continue;
         // Edges to scoped resources are runtime deps, not boot-time deps — exclude from DAG

package/src/index.ts

@@ -14,6 +14,7 @@ export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export type { ModuleKind } from "./module-kinds.js";
 export { parseLoadedFile } from "./parse-loaded-file.js";
 export type { ParseOptions } from "./parse-loaded-file.js";
+export { residualEntrySchema, residualEntrySchemaMap } from "./residual-schema.js";
 export {
     buildDocumentPositions,
     buildLineOffsets,
@@ -23,6 +24,7 @@ export {
 export type { DocumentPosition } from "./position-metadata.js";
 export { HttpSource } from "./sources/http-source.js";
 export { RegistrySource } from "./sources/registry-source.js";
+export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type {
     AnalysisDiagnostic,

package/src/kernel-globals.ts

@@ -1,4 +1,5 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { residualEntrySchemaMap } from "./residual-schema.js";
 
 /**
  * Kernel global names available in every CEL evaluation context at runtime.
@@ -72,20 +73,17 @@ export function buildKernelGlobalsSchema(
 }
 
 /** Wrap a JSON Schema property map (like `Telo.Application.variables`) into a
- *  closed object schema suitable for chain-access validation. Falls back to
- *  an open map when the module declares no variables/secrets. */
+ *  closed object schema suitable for chain-access validation. For Application
+ *  entries the per-entry shape carries kernel-specific keys (`env`, `default`)
+ *  on top of an otherwise-standard JSON Schema property schema; those keys are
+ *  stripped via `residualEntrySchemaMap` so CEL sees the coerced shape, not
+ *  the env-binding wrapper. Library entries are pure JSON Schema property
+ *  schemas and pass through the same call unchanged. Falls back to an open map
+ *  when the module declares no variables/secrets. */
 function buildSchemaMapSchema(
   schemaMap: Record<string, any> | null | undefined,
 ): Record<string, any> {
-  if (!schemaMap || typeof schemaMap !== "object" || Array.isArray(schemaMap)) {
-    return { type: "object", additionalProperties: true };
-  }
-  const props: Record<string, any> = {};
-  for (const [key, value] of Object.entries(schemaMap)) {
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      props[key] = value;
-    }
-  }
+  const props = residualEntrySchemaMap(schemaMap);
   if (Object.keys(props).length === 0) {
     return { type: "object", additionalProperties: true };
   }

package/src/manifest-loader.ts

@@ -33,6 +33,14 @@ export class Loader {
    *  get distinct entries, so neither sees the wrong manifest tree. */
   private readonly fileCache = new Map<string, LoadedFile>();
 
+  /** requestUrl → canonical `source`. Lets `loadFile` skip the source read
+   *  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
+   *  `LocalFileSource`). */
+  private readonly urlToSource = new Map<string, string>();
+
   protected sources: ManifestSource[];
   private readonly celEnv: Environment;
 
@@ -67,8 +75,22 @@ export class Loader {
   }
 
   async resolveEntryPoint(url: string): Promise<string> {
-    const { source } = await this.pick(url).read(url);
-    return source;
+    // Route through `loadFile` so the resolved source URL and parsed
+    // 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`).
+    const file = await this.loadFile(url);
+    return file.source;
+  }
+
+  /** Returns the canonical source URL the loader has already mapped `url`
+   *  to during a prior `loadFile`/`loadModule`/`loadGraph` call, or
+   *  `undefined` when the URL has not been seen. Callers use it to test
+   *  set-membership against a previous graph walk's modules without
+   *  triggering an extra source read. */
+  canonicalize(url: string): string | undefined {
+    return this.urlToSource.get(url);
   }
 
   // --- New API: returns LoadedFile / LoadedModule / LoadedGraph ----------
@@ -78,8 +100,42 @@ export class Loader {
    *  private mutable copy must call `parseLoadedFile` directly with the
    *  LoadedFile's `text`. */
   async loadFile(url: string, options?: LoadOptions): Promise<LoadedFile> {
+    const compileKey = options?.compile ? "compiled" : "raw";
+    const knownSource = this.urlToSource.get(url);
+    if (knownSource) {
+      const cached = this.fileCache.get(`${compileKey}:${knownSource}`);
+      if (cached) return cached;
+      // The other compile-mode entry is cached — reparse from its text
+      // instead of re-reading the source.
+      //
+      // NOTE for watch-mode reactivation (cli/nodejs/src/commands/run.ts
+      // currently has `setupWatchMode` commented out): this branch
+      // assumes file contents don't change underneath a single Loader.
+      // Reviving watch mode will need a public `invalidate(url)` (or
+      // similar) that drops both `urlToSource[url]` and the cached
+      // entries for its canonical source before the loader serves the
+      // file again.
+      const altKey = `${compileKey === "compiled" ? "raw" : "compiled"}:${knownSource}`;
+      const alt = this.fileCache.get(altKey);
+      if (alt) {
+        const reparsed = parseLoadedFile(knownSource, url, alt.text, {
+          compile: options?.compile,
+          celEnv: this.celEnv,
+        });
+        this.fileCache.set(`${compileKey}:${knownSource}`, reparsed);
+        return reparsed;
+      }
+    }
+
     const { text, source } = await this.pick(url).read(url);
-    const cacheKey = `${options?.compile ? "compiled" : "raw"}:${source}`;
+    this.urlToSource.set(url, source);
+    // Also map the canonical source to itself so subsequent `loadFile`
+    // calls that already received a canonical URL — `kernel.load` passes
+    // the result of `resolveEntryPoint` to `loadGraph`, which then asks
+    // for that exact URL — hit the urlToSource fast path instead of
+    // falling through to a redundant `pick(url).read(url)`.
+    this.urlToSource.set(source, source);
+    const cacheKey = `${compileKey}:${source}`;
     const cached = this.fileCache.get(cacheKey);
     if (cached && cached.text === text) return cached;
 
@@ -224,7 +280,16 @@ export class Loader {
     return { rootSource, entry, modules, importEdges, errors };
   }
 
-  private resolveImportUrl(fromSource: string, importSource: string): string {
+  /** 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
+   *  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
+   *  would silently break optimizations like `canonicalize()`-keyed
+   *  cache hits whenever a non-trivial `ManifestSource.resolveRelative`
+   *  is in play. */
+  resolveImportUrl(fromSource: string, importSource: string): string {
     if (importSource.startsWith(".") || importSource.startsWith("/")) {
       return this.pick(fromSource).resolveRelative(fromSource, importSource);
     }