@telorun/analyzer 0.26.0 → 0.28.0

package/dist/sources/default-sources.js

@@ -0,0 +1,10 @@
+import { HttpSource } from "./http-source.js";
+import { RegistrySource } from "./registry-source.js";
+/** The browser-safe built-in sources, in resolution order: HTTP fetch then
+ *  registry. Node-specific sources (local filesystem) are supplied by the
+ *  consuming package and passed alongside these into the `Loader` constructor.
+ *  Callers that only want a subset (e.g. the editor, which brings its own
+ *  registry adapters) construct the individual sources directly. */
+export function defaultSources(registryUrl) {
+    return [new HttpSource(), new RegistrySource(registryUrl)];
+}

package/dist/types.d.ts

@@ -68,14 +68,6 @@ export interface LoadOptions {
     desugarImports?: boolean;
 }
 export interface LoaderInitOptions {
-    /** Sources inserted with highest priority before built-ins. */
-    extraSources?: ManifestSource[];
-    /** Include built-in HttpSource. Defaults to true. */
-    includeHttpSource?: boolean;
-    /** Include built-in RegistrySource. Defaults to true. */
-    includeRegistrySource?: boolean;
-    /** Base URL used by built-in RegistrySource when enabled. */
-    registryUrl?: string;
     /** Handlers for CEL stdlib functions (e.g. `sha256`). Analyzer-only callers may
      *  omit this and get throwing stubs; runtime callers (kernel) must supply real impls. */
     celHandlers?: import("./cel-environment.js").CelHandlers;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAExD;;qEAEiE;IACjE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjE;;qEAEiE;IACjE,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;mEAO+D;IAC/D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,qDAAqD;IACrD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;6FACyF;IACzF,WAAW,CAAC,EAAE,OAAO,sBAAsB,EAAE,WAAW,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;sDAUkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;IACpE;;;;+EAI2E;IAC3E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC,CAAC;CAC5E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;qHACqH;AACrH,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AACX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE9F,gFAAgF;AAChF,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,MAAM,WAAW,QAAQ;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,QAAQ,CAAC;CACf;AAED;;oDAEoD;AACpD,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/C;6EAC6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2BAA2B;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAExD;;qEAEiE;IACjE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEjE;;qEAEiE;IACjE,cAAc,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,WAAW;IAC1B;;;+EAG2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;mEAO+D;IAC/D,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC;6FACyF;IACzF,WAAW,CAAC,EAAE,OAAO,sBAAsB,EAAE,WAAW,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;sDAUkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;gEAKgE;AAChE,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC;IACtD,WAAW,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;IACpE;;;;+EAI2E;IAC3E,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,qBAAqB,EAAE,aAAa,CAAC,CAAC;CAC5E"}

package/dist/validate-provider-coherence.d.ts

@@ -18,6 +18,14 @@ import { type AnalysisDiagnostic } from "./types.js";
  *    kind is registered but not a `Telo.Invocable`.
  *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
  *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
+ *  - MOUNT_ON_NON_MOUNT: `mount:` declared on a definition whose `capability` is
+ *    not `Telo.Mount`.
+ *  - MOUNT_DISPATCHER_CONFLICT: `mount:` co-exists with another dispatch
+ *    entry-point (`invoke:` / `run:` / `provide:`).
+ *  - MOUNT_TARGET_UNKNOWN: `mount.name` does not resolve to an entry in
+ *    `resources:`.
+ *  - MOUNT_TARGET_NOT_MOUNTABLE: `mount.name` resolves to a resource whose kind
+ *    is registered but not a `Telo.Mount`.
  */
 export declare function validateProviderCoherence(manifests: ResourceManifest[], registry: DefinitionRegistry, aliases: AliasResolver): AnalysisDiagnostic[];
 //# sourceMappingURL=validate-provider-coherence.d.ts.map

package/dist/validate-provider-coherence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-provider-coherence.d.ts","sourceRoot":"","sources":["../src/validate-provider-coherence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CAyItB"}
+{"version":3,"file":"validate-provider-coherence.d.ts","sourceRoot":"","sources":["../src/validate-provider-coherence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CAsNtB"}

package/dist/validate-provider-coherence.js

@@ -16,6 +16,14 @@ const SOURCE = "telo-analyzer";
  *    kind is registered but not a `Telo.Invocable`.
  *  - PROVIDER_MISSING_IMPLEMENTATION: definition with `capability: Telo.Provider`
  *    declares neither `controllers:` (TS-backed) nor `provide:` (template-backed).
+ *  - MOUNT_ON_NON_MOUNT: `mount:` declared on a definition whose `capability` is
+ *    not `Telo.Mount`.
+ *  - MOUNT_DISPATCHER_CONFLICT: `mount:` co-exists with another dispatch
+ *    entry-point (`invoke:` / `run:` / `provide:`).
+ *  - MOUNT_TARGET_UNKNOWN: `mount.name` does not resolve to an entry in
+ *    `resources:`.
+ *  - MOUNT_TARGET_NOT_MOUNTABLE: `mount.name` resolves to a resource whose kind
+ *    is registered but not a `Telo.Mount`.
  */
 export function validateProviderCoherence(manifests, registry, aliases) {
     const diagnostics = [];
@@ -45,11 +53,13 @@ export function validateProviderCoherence(manifests, registry, aliases) {
         const provide = md.provide;
         const invoke = md.invoke;
         const run = md.run;
+        const mount = md.mount;
         const controllers = md.controllers;
         const resources = md.resources;
         const hasProvide = provide !== undefined && provide !== null;
         const hasInvoke = invoke !== undefined && invoke !== null;
         const hasRun = run !== undefined && run !== null;
+        const hasMount = mount !== undefined && mount !== null;
         const hasControllers = Array.isArray(controllers) && controllers.length > 0;
         if (hasProvide && capability !== "Telo.Provider") {
             diagnostics.push({
@@ -133,6 +143,77 @@ export function validateProviderCoherence(manifests, registry, aliases) {
                 }
             }
         }
+        if (hasMount && capability !== "Telo.Mount") {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "MOUNT_ON_NON_MOUNT",
+                source: SOURCE,
+                message: `${label}: 'mount:' is only valid on definitions with 'capability: Telo.Mount' ` +
+                    `(found '${capability ?? "<unset>"}'). Use 'invoke:' / 'run:' / 'provide:' for other capabilities.`,
+                data: { resource, filePath, path: "mount" },
+            });
+        }
+        if (hasMount && (hasInvoke || hasRun || hasProvide)) {
+            const conflict = hasInvoke ? "invoke" : hasRun ? "run" : "provide";
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "MOUNT_DISPATCHER_CONFLICT",
+                source: SOURCE,
+                message: `${label}: 'mount:' cannot co-exist with '${conflict}:'. ` +
+                    `A definition declares exactly one dispatch entry-point.`,
+                data: { resource, filePath, path: "mount" },
+            });
+        }
+        if (hasMount) {
+            // Resolve the target's name from either form: the bare string (the
+            // primary, documented form — `mount: api`) or the object's `name`. A CEL
+            // target (`${{ … }}`) can only be checked at runtime, so skip those.
+            let mountedName;
+            if (typeof mount === "string") {
+                if (!mount.includes("${{"))
+                    mountedName = mount;
+            }
+            else if (typeof mount === "object" && !Array.isArray(mount)) {
+                const mountObj = mount;
+                if (typeof mountObj.name === "string" && !mountObj.name.includes("${{")) {
+                    mountedName = mountObj.name;
+                }
+            }
+            const mountPath = typeof mount === "string" ? "mount" : "mount.name";
+            if (mountedName && Array.isArray(resources)) {
+                const match = resources.find((r) => {
+                    const meta = r?.metadata;
+                    return typeof meta?.name === "string" && meta.name === mountedName;
+                });
+                if (!match) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "MOUNT_TARGET_UNKNOWN",
+                        source: SOURCE,
+                        message: `${label}: '${mountPath}: ${mountedName}' does not match any entry's ` +
+                            `metadata.name in 'resources:'.`,
+                        data: { resource, filePath, path: mountPath },
+                    });
+                }
+                else if (typeof match.kind === "string") {
+                    const resolvedKind = aliases.resolveKind(match.kind) ?? match.kind;
+                    const targetDef = registry.resolve(resolvedKind) ?? registry.resolve(match.kind);
+                    if (targetDef && targetDef.kind === "Telo.Definition") {
+                        const targetCap = targetDef.capability;
+                        if (typeof targetCap === "string" && targetCap !== "Telo.Mount") {
+                            diagnostics.push({
+                                severity: DiagnosticSeverity.Error,
+                                code: "MOUNT_TARGET_NOT_MOUNTABLE",
+                                source: SOURCE,
+                                message: `${label}: '${mountPath}: ${mountedName}' resolves to a ${match.kind} ` +
+                                    `(capability '${targetCap}'); 'mount:' requires a Telo.Mount target.`,
+                                data: { resource, filePath, path: mountPath },
+                            });
+                        }
+                    }
+                }
+            }
+        }
         if (capability === "Telo.Provider" && !hasControllers && !hasProvide) {
             diagnostics.push({
                 severity: DiagnosticSeverity.Error,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -48,7 +48,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.34.0"
+    "@telorun/sdk": "0.36.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/builtins.ts

@@ -61,12 +61,28 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           items: {
             type: "object",
             additionalProperties: true,
+            // Resource bodies are `self`-only for config: per-call `inputs` is
+            // NOT in scope here. Each entry is a persistent child created once at
+            // init() and reused, so its config cannot depend on call-time data —
+            // that flows through the top-level `inputs:` sibling into the dispatch
+            // target's invoke().
+            //
+            // The exception is CEL the child's OWN controller evaluates later
+            // against a runtime context it owns (e.g. an Http.Api evaluating route
+            // CEL per request). Those `request` / `result` / `steps` / `error`
+            // variables are deferred — the template controller preserves them
+            // untouched (see resource-template-controller.ts) — so they are
+            // exposed here permissively. Their deep shape is the child kind's
+            // concern, not the template's, so they type as open values.
             "x-telo-context": {
               type: "object",
               additionalProperties: false,
               properties: {
                 self: { "x-telo-context-from-root": "schema" },
-                inputs: { "x-telo-context-from-root": "inputType" },
+                request: {},
+                result: {},
+                steps: {},
+                error: {},
               },
             },
           },
@@ -129,6 +145,41 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             },
           },
         },
+        // Mount dispatch: names the `resources:` entry (a Telo.Mount, e.g. an
+        // Http.Api) whose `register()` this definition delegates to. Same
+        // string / { kind, name } grammar as `invoke:`. The named child stays
+        // persistent so the produced mount's routes can `!ref` its siblings.
+        mount: {
+          oneOf: [
+            {
+              type: "string",
+              "x-telo-context": {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  self: { "x-telo-context-from-root": "schema" },
+                },
+              },
+            },
+            {
+              type: "object",
+              additionalProperties: true,
+              properties: {
+                kind: { type: "string" },
+                name: {
+                  type: "string",
+                  "x-telo-context": {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                      self: { "x-telo-context-from-root": "schema" },
+                    },
+                  },
+                },
+              },
+            },
+          ],
+        },
         inputs: {
           type: "object",
           additionalProperties: true,

package/src/index.ts

@@ -39,6 +39,8 @@ export { parseLoadedFile } from "./parse-loaded-file.js";
 export type { ParseOptions } from "./parse-loaded-file.js";
 export { desugarLoadedFile, inlineImportManifests } from "./inline-imports.js";
 export type { SyntheticImport } from "./inline-imports.js";
+export { reconcileModuleVersions } from "./reconcile-module-versions.js";
+export type { VersionReconciliation } from "./reconcile-module-versions.js";
 export { residualEntrySchema, residualEntrySchemaMap } from "./residual-schema.js";
 export {
     buildDocumentPositions,
@@ -49,6 +51,7 @@ export {
 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 { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type {

package/src/loaded-types.ts

@@ -1,7 +1,7 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import type { Document } from "yaml";
 import type { DocumentPosition } from "./position-metadata.js";
-import type { Range } from "./types.js";
+import type { AnalysisDiagnostic, Range } from "./types.js";
 
 /** One physical file's parsed result. Returned for the owner manifest, for
  *  each `include:` partial, and for each external import target.
@@ -70,8 +70,21 @@ export interface LoadedGraph {
    *  its partials. */
   modules: Map<string, LoadedModule>;
   /** Per-Telo.Import resolution. Keyed by the resolved URL of the file the
-   *  Telo.Import was declared in, then by the import's PascalCase alias. */
+   *  Telo.Import was declared in, then by the import's PascalCase alias.
+   *  Version reconciliation repoints losing edges at their winner here, so a
+   *  consumer walking these edges (`flattenForAnalyzer`) sees one version per
+   *  module identity. */
   importEdges: Map<string, Map<string, ImportEdge>>;
+  /** Version-reconciliation redirects: a losing module's canonical source URL →
+   *  the winning version's canonical source URL. The runtime consults this when
+   *  it independently re-resolves an import (the analyzer already sees repointed
+   *  `importEdges`). Empty when no module identity appeared at two sources. */
+  overrides: Map<string, string>;
+  /** Diagnostics produced while reconciling module versions — one per import
+   *  edge redirected to a different version (warning for a same-major hoist,
+   *  error for a major mismatch). Surfaced alongside `analyze()` diagnostics by
+   *  every consumer (CLI, editor, VS Code). */
+  versionDiagnostics: AnalysisDiagnostic[];
   /** Surface-level errors that did not abort the graph load (e.g. an import
    *  whose target failed to fetch). */
   errors: GraphLoadError[];

package/src/manifest-loader.ts

@@ -1,7 +1,5 @@
 import type { Environment } from "@marcbachmann/cel-js";
 import type { ResourceManifest } from "@telorun/sdk";
-import { HttpSource } from "./sources/http-source.js";
-import { RegistrySource } from "./sources/registry-source.js";
 import { buildCelEnvironment } from "./cel-environment.js";
 import type {
   GraphLoadError,
@@ -13,6 +11,7 @@ import type {
 import { desugarLoadedFile } from "./inline-imports.js";
 import { isModuleKind } from "./module-kinds.js";
 import { parseLoadedFile } from "./parse-loaded-file.js";
+import { reconcileModuleVersions } from "./reconcile-module-versions.js";
 import {
   DEFAULT_MANIFEST_FILENAME,
   type LoadOptions,
@@ -53,22 +52,13 @@ export class Loader {
   protected sources: ManifestSource[];
   private readonly celEnv: Environment;
 
-  constructor(extraSourcesOrOptions: ManifestSource[] | LoaderInitOptions = []) {
-    const options: LoaderInitOptions = Array.isArray(extraSourcesOrOptions)
-      ? { extraSources: extraSourcesOrOptions }
-      : extraSourcesOrOptions;
-
-    const includeHttpSource = options.includeHttpSource ?? true;
-    const includeRegistrySource = options.includeRegistrySource ?? true;
-
-    this.sources = [];
-    if (includeHttpSource) this.sources.push(new HttpSource());
-    if (includeRegistrySource) this.sources.push(new RegistrySource(options.registryUrl));
-
-    if (options.extraSources?.length) {
-      this.sources.unshift(...options.extraSources);
-    }
-
+  /** 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. */
+  constructor(sources: ManifestSource[] = [], options: LoaderInitOptions = {}) {
+    this.sources = [...sources];
     this.celEnv = buildCelEnvironment(options.celHandlers);
   }
 
@@ -307,7 +297,20 @@ export class Loader {
       }
     }
 
-    return { rootSource, entry, modules, importEdges, errors };
+    // Collapse multiple versions of the same module identity onto one version
+    // before any consumer walks the edges: repoints losing `importEdges` in
+    // place and yields the runtime override map + hoist/conflict diagnostics.
+    const { overrides, diagnostics } = reconcileModuleVersions(modules, importEdges);
+
+    return {
+      rootSource,
+      entry,
+      modules,
+      importEdges,
+      overrides,
+      versionDiagnostics: diagnostics,
+      errors,
+    };
   }
 
   /** Resolve an `import` URL against the file it appears in. Relative /

package/src/reconcile-module-versions.ts

@@ -0,0 +1,253 @@
+import type { ImportEdge, LoadedModule } from "./loaded-types.js";
+import { isModuleKind } from "./module-kinds.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/** Outcome of reconciling a module name that appears at more than one resolved
+ *  source in a single import graph. The `overrides` map redirects each losing
+ *  canonical URL to the winner's canonical URL — consulted by the runtime when
+ *  it independently re-resolves an import (the analyzer side is handled by
+ *  repointing `importEdges` in place). */
+export interface VersionReconciliation {
+  /** Loser canonical source URL → winner canonical source URL. */
+  overrides: Map<string, string>;
+  /** One diagnostic per import edge that pointed at a non-winner: a warning for
+   *  a same-major hoist, an error for an incompatible major mismatch. */
+  diagnostics: AnalysisDiagnostic[];
+}
+
+interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  /** Dot-separated prerelease identifiers, or `null` for a release version. */
+  pre: string[] | null;
+}
+
+interface ModuleIdentity {
+  source: string;
+  identity: string;
+  version: string;
+  parsed: ParsedVersion | null;
+  text: string;
+}
+
+/** Parse `X.Y.Z`, `vX.Y.Z`, or `X.Y.Z-pre.1`. Returns `null` for anything that
+ *  isn't a plain three-part numeric core — an unparseable version forces the
+ *  group onto the conflict path (we never silently hoist across a version we
+ *  can't reason about). Pure: no dependency on the `semver` package, so the
+ *  analyzer stays browser-safe and dependency-free. */
+function parseVersion(raw: string | undefined): ParsedVersion | null {
+  if (typeof raw !== "string") return null;
+  const v = raw.startsWith("v") ? raw.slice(1) : raw;
+  const [core, ...preParts] = v.split("-");
+  const pre = preParts.length > 0 ? preParts.join("-") : null;
+  const segments = core.split(".");
+  if (segments.length !== 3) return null;
+  const [major, minor, patch] = segments.map((s) => {
+    if (!/^\d+$/.test(s)) return NaN;
+    return Number(s);
+  });
+  if ([major, minor, patch].some((n) => Number.isNaN(n))) return null;
+  return { major, minor, patch, pre: pre === null ? null : pre.split(".") };
+}
+
+/** SemVer precedence: numeric core, then a release outranks a prerelease, then
+ *  prerelease identifiers compared field-by-field (numeric < non-numeric per
+ *  spec, shorter set loses when all shared fields are equal). */
+function compareVersions(a: ParsedVersion, b: ParsedVersion): number {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  if (a.patch !== b.patch) return a.patch - b.patch;
+  if (a.pre === null && b.pre === null) return 0;
+  if (a.pre === null) return 1;
+  if (b.pre === null) return -1;
+  const len = Math.max(a.pre.length, b.pre.length);
+  for (let i = 0; i < len; i++) {
+    const ai = a.pre[i];
+    const bi = b.pre[i];
+    if (ai === undefined) return -1;
+    if (bi === undefined) return 1;
+    const an = /^\d+$/.test(ai);
+    const bn = /^\d+$/.test(bi);
+    if (an && bn) {
+      const d = Number(ai) - Number(bi);
+      if (d !== 0) return d;
+    } else if (an !== bn) {
+      return an ? -1 : 1;
+    } else if (ai !== bi) {
+      return ai < bi ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/** Read a loaded module's `namespace/name` identity, version, and raw owner
+ *  text. Returns `null` for modules without a namespace: only a registry
+ *  identity (`<namespace>/<name>`) is a stable cross-import key. Two namespace-
+ *  less local libraries that merely share a `metadata.name` are distinct modules
+ *  reached via distinct source URLs — reconciling them would drop one and break
+ *  its kinds; the same local file reached via two paths is already collapsed by
+ *  canonical-source dedup, so there is nothing left to reconcile here. */
+function moduleIdentityOf(mod: LoadedModule): ModuleIdentity | null {
+  const doc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind));
+  if (!doc) return null;
+  const meta = doc.metadata as { name?: string; namespace?: string | null; version?: string };
+  const name = meta?.name;
+  if (typeof name !== "string" || name.length === 0) return null;
+  if (typeof meta.namespace !== "string" || meta.namespace.length === 0) return null;
+  const version = typeof meta.version === "string" ? meta.version : "";
+  return {
+    source: mod.owner.source,
+    identity: `${meta.namespace}/${name}`,
+    version,
+    parsed: parseVersion(version),
+    text: mod.owner.text,
+  };
+}
+
+interface GroupResolution {
+  winner: ModuleIdentity;
+  /** True when members disagree on major version (or a version is unparseable). */
+  conflict: boolean;
+}
+
+/** Pick the winning member of a same-identity group and classify it. The winner
+ *  is the highest version (deterministic tiebreak on source URL for equal
+ *  versions / same-version-different-source). A major disagreement — or any
+ *  unparseable version — marks the group a conflict; we still pick a winner so
+ *  the rest of analysis proceeds against a single version instead of cascading
+ *  duplicate-kind errors. */
+function resolveGroup(members: ModuleIdentity[]): GroupResolution {
+  const majors = new Set<number | null>();
+  for (const m of members) majors.add(m.parsed ? m.parsed.major : null);
+  const conflict = majors.has(null) || majors.size > 1;
+
+  const winner = members.reduce((best, cur) => {
+    if (!cur.parsed) return best;
+    if (!best.parsed) return cur;
+    const cmp = compareVersions(cur.parsed, best.parsed);
+    if (cmp > 0) return cur;
+    if (cmp === 0 && cur.source < best.source) return cur;
+    return best;
+  }, members[0]);
+
+  return { winner, conflict };
+}
+
+/** The diagnostic for a redirected edge, or `null` when the redirect is a
+ *  silent dedupe (the same version resolved from two sources with identical
+ *  content — no decision was made, so nothing to report). */
+function hoistDiagnostic(
+  identity: string,
+  importerSource: string,
+  alias: string,
+  loser: ModuleIdentity,
+  winner: ModuleIdentity,
+  conflict: boolean,
+): AnalysisDiagnostic | null {
+  const data = { filePath: importerSource, path: `imports.${alias}` };
+  if (conflict) {
+    return {
+      severity: DiagnosticSeverity.Error,
+      code: "MODULE_VERSION_CONFLICT",
+      source: SOURCE,
+      message:
+        `Module '${identity}' is imported at incompatible major versions: ` +
+        `${loser.version || "<unknown>"} here and ${winner.version} elsewhere in the same graph. ` +
+        `Major versions can carry breaking changes and cannot be reconciled automatically — ` +
+        `align every importer on one major.`,
+      data,
+    };
+  }
+  if (loser.version === winner.version) {
+    // Same version, two sources. Identical content is a no-op dedupe; differing
+    // content means one is masquerading as the other (e.g. a local checkout vs
+    // the published version) — worth surfacing.
+    if (loser.text === winner.text) return null;
+    return {
+      severity: DiagnosticSeverity.Warning,
+      code: "MODULE_VERSION_HOISTED",
+      source: SOURCE,
+      message:
+        `Module '${identity}@${winner.version}' is imported from two sources whose contents ` +
+        `differ ('${loser.source}' and '${winner.source}'). Using '${winner.source}' for every ` +
+        `importer — pin a single source to remove the ambiguity.`,
+      data,
+    };
+  }
+  return {
+    severity: DiagnosticSeverity.Warning,
+    code: "MODULE_VERSION_HOISTED",
+    source: SOURCE,
+    message:
+      `Module '${identity}@${loser.version || "<unknown>"}' was hoisted to '${winner.version}' ` +
+      `because the same module is imported at the higher version elsewhere in the graph. ` +
+      `Pre-1.0 versions are additive, so the higher version is used for every importer.`,
+    data,
+  };
+}
+
+/**
+ * Reconcile a loaded import graph so each module identity (`namespace/name`)
+ * resolves to a single version. Within a shared major the highest version wins
+ * (a non-lossy hoist, given Telo's additive-only pre-1.0 policy); a major
+ * mismatch is a hard conflict. Mutates `importEdges` in place — every edge that
+ * pointed at a losing source is repointed at the winner — so `flattenForAnalyzer`
+ * walks a deduplicated graph and the runtime collision (two definitions of the
+ * same kind) cannot occur. Pure and browser-safe: no I/O, no Node built-ins.
+ */
+export function reconcileModuleVersions(
+  modules: Map<string, LoadedModule>,
+  importEdges: Map<string, Map<string, ImportEdge>>,
+): VersionReconciliation {
+  const overrides = new Map<string, string>();
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  const groups = new Map<string, ModuleIdentity[]>();
+  const infoBySource = new Map<string, ModuleIdentity>();
+  for (const mod of modules.values()) {
+    const info = moduleIdentityOf(mod);
+    if (!info) continue;
+    infoBySource.set(info.source, info);
+    const list = groups.get(info.identity);
+    if (list) list.push(info);
+    else groups.set(info.identity, [info]);
+  }
+
+  const conflictByIdentity = new Map<string, boolean>();
+  for (const [identity, members] of groups) {
+    if (members.length < 2) continue;
+    const { winner, conflict } = resolveGroup(members);
+    conflictByIdentity.set(identity, conflict);
+    for (const member of members) {
+      if (member.source !== winner.source) overrides.set(member.source, winner.source);
+    }
+  }
+
+  if (overrides.size === 0) return { overrides, diagnostics };
+
+  for (const [importerSource, aliasMap] of importEdges) {
+    for (const [alias, edge] of aliasMap) {
+      const winnerSource = overrides.get(edge.targetSource);
+      if (!winnerSource) continue;
+      const loser = infoBySource.get(edge.targetSource);
+      const winner = infoBySource.get(winnerSource);
+      if (loser && winner) {
+        const diag = hoistDiagnostic(
+          loser.identity,
+          importerSource,
+          alias,
+          loser,
+          winner,
+          conflictByIdentity.get(loser.identity) ?? false,
+        );
+        if (diag) diagnostics.push(diag);
+      }
+      edge.targetSource = winnerSource;
+    }
+  }
+
+  return { overrides, diagnostics };
+}

package/src/sources/default-sources.ts

@@ -0,0 +1,12 @@
+import type { ManifestSource } from "../types.js";
+import { HttpSource } from "./http-source.js";
+import { RegistrySource } from "./registry-source.js";
+
+/** The browser-safe built-in sources, in resolution order: HTTP fetch then
+ *  registry. Node-specific sources (local filesystem) are supplied by the
+ *  consuming package and passed alongside these into the `Loader` constructor.
+ *  Callers that only want a subset (e.g. the editor, which brings its own
+ *  registry adapters) construct the individual sources directly. */
+export function defaultSources(registryUrl?: string): ManifestSource[] {
+  return [new HttpSource(), new RegistrySource(registryUrl)];
+}

package/src/types.ts

@@ -75,14 +75,6 @@ export interface LoadOptions {
 }
 
 export interface LoaderInitOptions {
-  /** Sources inserted with highest priority before built-ins. */
-  extraSources?: ManifestSource[];
-  /** Include built-in HttpSource. Defaults to true. */
-  includeHttpSource?: boolean;
-  /** Include built-in RegistrySource. Defaults to true. */
-  includeRegistrySource?: boolean;
-  /** Base URL used by built-in RegistrySource when enabled. */
-  registryUrl?: string;
   /** Handlers for CEL stdlib functions (e.g. `sha256`). Analyzer-only callers may
    *  omit this and get throwing stubs; runtime callers (kernel) must supply real impls. */
   celHandlers?: import("./cel-environment.js").CelHandlers;