@telorun/analyzer 0.42.0 → 0.44.0

package/src/analysis-registry.ts

@@ -17,7 +17,7 @@ export interface RefFieldInfo {
   path: string;
   /** True when the path traverses at least one array. */
   isArray: boolean;
-  /** Accepted `x-telo-ref` constraint strings (e.g. `telo#Runnable`). */
+  /** Accepted `x-telo-ref` constraint strings, canonicalized (e.g. `Telo.Runnable`). */
   refs: string[];
   /** Distinct capabilities the slot may target (`Telo.Runnable`,
    *  `Telo.Service`, `Telo.Provider`, …) — one per resolvable constraint. The
@@ -119,9 +119,9 @@ export class AnalysisRegistry {
 
   /** Base capability an `x-telo-ref` constraint targets. A definition's declared
    *  `capability` is always one of the base capabilities, so it wins — this
-   *  resolves user-defined abstracts (e.g. `std/ai#Model`, declared
+   *  resolves user-defined abstracts (e.g. `ai.Model`, declared
    *  `capability: Telo.Invocable`) to the capability instances satisfy, not the
-   *  abstract kind. Builtin abstracts (`telo#Runnable`) carry no `capability`
+   *  abstract kind. Builtin abstracts (`Telo.Runnable`) carry no `capability`
    *  field — there the kind itself *is* the capability. Undefined when
    *  unresolvable. */
   capabilityForRef(xTeloRef: string): string | undefined {
@@ -306,7 +306,7 @@ export class AnalysisRegistry {
   }
 
   /** Returns every user-facing (alias-form) kind that satisfies the given
-   *  `x-telo-ref` constraint string (e.g. `"telo#Invocable"`, `"std/sql#Connection"`).
+   *  `x-telo-ref` constraint string, canonicalized (e.g. `"Telo.Invocable"`, `"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),

package/src/analyzer.ts

@@ -20,6 +20,7 @@ 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 { resolveSchemaRefKinds, type RefConstraintIssue } from "./resolve-schema-ref-kinds.js";
 import { resolveSchemaTypeRefs } from "./resolve-schema-type-refs.js";
 import { validateSchemaTypeRefs } from "./validate-schema-type-refs.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
@@ -29,6 +30,7 @@ import {
   validateAgainstSchema,
   type SchemaIssue,
 } from "./schema-compat.js";
+import { collectValueSchemaIssues } from "./validate-value-schema.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
   extractCelRegionScopes,
@@ -1034,6 +1036,7 @@ export class StaticAnalyzer {
     // declaring scope's resolver, so `extendedBy` is keyed by canonical kind regardless
     // of alias choices. `capability` covers the legacy implements-this-abstract overload;
     // `extends` is the canonical first-class form.
+    const refConstraintIssues: RefConstraintIssue[] = [];
     for (const m of manifests) {
       if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract") continue;
       const def = m as unknown as ResourceDefinition;
@@ -1042,6 +1045,15 @@ export class StaticAnalyzer {
         ownModule && !rootModules.has(ownModule)
           ? (aliasesByModule.get(ownModule) ?? new AliasResolver())
           : aliases;
+      // Canonicalize alias-form `x-telo-ref` constraints in the DECLARING module's
+      // scope, before the schema reaches `register()` and the lazily-built field
+      // maps. Same pre-resolution `capability` / `extends` get below.
+      const issues = resolveSchemaRefKinds(m, scopeResolver);
+      // Report only for definitions the author can edit. A published dependency
+      // still on the deprecated form — or with a constraint that no longer
+      // resolves — is not the consumer's to fix, and every import would
+      // otherwise flood `telo check` with unactionable noise.
+      if (!ownModule || rootModules.has(ownModule)) refConstraintIssues.push(...issues);
       const resolvedCapability = def.capability
         ? (scopeResolver.resolveKind(def.capability) ?? def.capability)
         : def.capability;
@@ -1062,6 +1074,57 @@ export class StaticAnalyzer {
     // distinguishable from the resolver's own substitution (after Phase 2/2.5
     // they are the same object).
     if (!options?.skipValidation) {
+      for (const issue of refConstraintIssues) {
+        // An `unknown` prefix is also what an ALREADY-CANONICAL value looks like
+        // (`kv-store.Store` names a module, not an alias). Now that every kind is
+        // registered, the registry separates the two — anything it resolves was
+        // canonical, anything it doesn't names nothing at all.
+        if (issue.reason === "unknown" && defs.resolve(issue.ref)) continue;
+        const resource = {
+          kind: issue.manifest.kind,
+          name: issue.manifest.metadata?.name as string,
+        };
+        const filePath = (issue.manifest.metadata as { source?: string } | undefined)?.source;
+        const data = { resource, filePath, path: issue.path };
+        if (issue.reason === "legacy") {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Warning,
+            code: "X_TELO_REF_LEGACY_IDENTITY",
+            source: SOURCE,
+            message:
+              `x-telo-ref '${issue.ref}' at '${issue.path}' uses the deprecated ` +
+              `'<namespace>/<module>#<Kind>' form. Write the target as an alias-qualified kind ` +
+              `instead — '<Alias>.<Kind>' for a module declared in this file's 'imports:' map, ` +
+              `'Self.<Kind>' for a kind in this library, or 'Telo.<Kind>' for a built-in capability.`,
+            data,
+          });
+        } else if (issue.reason === "gated") {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "KIND_NOT_EXPORTED",
+            source: SOURCE,
+            message:
+              `x-telo-ref '${issue.ref}' at '${issue.path}' targets a kind module ` +
+              `'${issue.gate?.module}' does not export. Add ` +
+              `'${issue.ref.slice(issue.ref.indexOf(".") + 1)}' to that module's exports.kinds. ` +
+              `Exported kinds: ${issue.gate?.exported.join(", ") || "(none)"}.`,
+            data,
+          });
+        } else {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "X_TELO_REF_UNRESOLVED",
+            source: SOURCE,
+            message:
+              `x-telo-ref '${issue.ref}' at '${issue.path}' names no kind. The prefix must be an ` +
+              `import alias declared in this file's 'imports:' map, 'Self' for a kind in this ` +
+              `library, or 'Telo' for a built-in capability. An unresolvable constraint would ` +
+              `leave the slot accepting any resource. Known aliases: ` +
+              `${issue.knownAliases?.join(", ") || "(none)"}.`,
+            data,
+          });
+        }
+      }
       diagnostics.push(...validateReferenceForms(manifests, defs, aliases, aliasesByModule));
     }
 
@@ -1088,10 +1151,31 @@ export class StaticAnalyzer {
         rootModules.has(ownModule) ? aliases : (aliasesByModule.get(ownModule) ?? new AliasResolver());
       const canonicalKind = scopeResolver.resolveKind(m.kind as string) ?? (m.kind as string);
       if (defs.resolve(canonicalKind)?.capability !== "Telo.Type") continue;
-      defs.registerNamedTypeSchema(
-        canonicalTypeSchemaId(ownModule, m.metadata.name as string),
+      const typeName = m.metadata.name as string;
+      const registered = defs.registerNamedTypeSchema(
+        canonicalTypeSchemaId(ownModule, typeName),
         m.schema as Record<string, any>,
       );
+      // Kinds and named types share one `telo://<module>/<Name>` id space. A
+      // collision would leave every `$ref` to that id resolving to the kind's
+      // schema — validating the wrong shape, silently — so it is an error, not
+      // a last-writer-wins.
+      if (!registered && !options?.skipValidation) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "DUPLICATE_SCHEMA_ID",
+          source: SOURCE,
+          message:
+            `Type '${typeName}' collides with the kind '${ownModule}.${typeName}': both claim the ` +
+            `schema id '${canonicalTypeSchemaId(ownModule, typeName)}'. A '$ref' to it would ` +
+            `resolve to the kind's schema. Rename one of them.`,
+          data: {
+            resource: { kind: m.kind, name: typeName },
+            filePath: (m.metadata as { source?: string } | undefined)?.source,
+            path: "metadata.name",
+          },
+        });
+      }
     }
     if (!options?.skipValidation) {
       diagnostics.push(
@@ -1351,7 +1435,16 @@ export class StaticAnalyzer {
         );
         // Phase 2+3: AJV on substituted data — CEL fields replaced with typed placeholders
         const ajvIssues = validateAgainstSchema(substituteCelFields(m, schema), schema);
-        const issues = [...celIssues, ...ajvIssues];
+        // Phase 4: value slots that must satisfy a type declared elsewhere on
+        // the resource (`x-telo-value-schema-from`) — e.g. every row of a
+        // decision table against its declared `outputType`, so a mistyped branch
+        // is caught here rather than on the one input that selects it.
+        const valueSchemaIssues = collectValueSchemaIssues(
+          m as Record<string, any>,
+          schema,
+          allManifests as Record<string, any>[],
+        );
+        const issues = [...celIssues, ...ajvIssues, ...valueSchemaIssues];
         for (const issue of issues) {
           diagnostics.push({
             severity: DiagnosticSeverity.Error,
@@ -1390,6 +1483,7 @@ export class StaticAnalyzer {
               const viaRoot = aliases.resolveKind(kind);
               return viaRoot ? defs.resolve(viaRoot) : undefined;
             },
+            allManifests as Record<string, any>[],
           ),
         );
       }

package/src/builtins.ts

@@ -97,7 +97,7 @@ const ROOT_LOGGING_SCHEMA = {
       type: "array",
       items: {
         type: "object",
-        "x-telo-ref": "telo#LogSink",
+        "x-telo-ref": "Telo.LogSink",
         "x-telo-inline": true,
       },
     },
@@ -444,8 +444,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: {
             anyOf: [
-              { type: "string", "x-telo-ref": "telo#Runnable" },
-              { type: "string", "x-telo-ref": "telo#Service" },
+              { 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
@@ -469,8 +469,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                 properties: {
                   ref: {
                     anyOf: [
-                      { type: "string", "x-telo-ref": "telo#Runnable" },
-                      { type: "string", "x-telo-ref": "telo#Service" },
+                      { type: "string", "x-telo-ref": "Telo.Runnable" },
+                      { type: "string", "x-telo-ref": "Telo.Service" },
                       {
                         type: "object",
                         required: ["kind", "name"],
@@ -510,8 +510,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                     },
                     additionalProperties: true,
                     anyOf: [
-                      { "x-telo-ref": "telo#Invocable" },
-                      { "x-telo-ref": "telo#Runnable" },
+                      { "x-telo-ref": "Telo.Invocable" },
+                      { "x-telo-ref": "Telo.Runnable" },
                     ],
                   },
                   inputs: { type: "object", additionalProperties: true },

package/src/definition-registry.ts

@@ -1,4 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { canonicalTypeSchemaId } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import { KERNEL_BUILTINS } from "./builtins.js";
 import {
@@ -21,18 +22,21 @@ export class DefinitionRegistry {
    *  across analyze() calls and no unbounded growth across the process lifetime. */
   private readonly ajv = createAjv();
   private readonly registeredSchemaIds = new Set<string>();
+  /** The subset of `registeredSchemaIds` claimed by a kind's schema. Kinds and
+   *  named `Telo.Type`s share one `telo://<module>/<Name>` id space, so this is
+   *  what lets a colliding type name be reported instead of silently dropped. */
+  private readonly definitionSchemaIds = new Set<string>();
 
   private readonly defs = new Map<string, ResourceDefinition>();
   private readonly fieldMaps = new Map<string, ReferenceFieldMap>();
   /** Reverse inheritance index: parent kind → direct child kinds. */
   private readonly extendedBy = new Map<string, string[]>();
-  /** Module identity table: identity string → canonical module name.
-   *  "telo" → "Telo", "std/pipeline" → "pipeline", etc. */
+  /** DEPRECATED module identity table: identity string → canonical module name
+   *  ("std/pipeline" → "pipeline"). Serves only the legacy
+   *  `<namespace>/<module>#<Kind>` form of `x-telo-ref`, kept resolvable for
+   *  module versions published before constraints named their target by import
+   *  alias. Fed by `metadata.namespace`, which nothing else reads. */
   private readonly identityMap = new Map<string, string>();
-  /** Reverse identity table: canonical module name → full identity string.
-   *  "Telo" → "telo", "pipeline" → "std/pipeline", etc.
-   *  Used to compute definition $id values for the AJV schema store. */
-  private readonly reverseIdentityMap = new Map<string, string>();
 
   register(definition: ResourceDefinition): void {
     const { name, module: mod } = definition.metadata;
@@ -60,12 +64,11 @@ export class DefinitionRegistry {
     if (definition.extends) {
       this.addExtendedBy(definition.extends, key);
     }
-    // Auto-register the telo identity when any Telo built-in is registered.
+    // Auto-register the legacy telo identity when any Telo built-in is registered,
+    // so an already-published `x-telo-ref: "telo#Invocable"` still resolves.
     if (definition.kind === "Telo.Abstract" && mod === "Telo") {
       this.identityMap.set("telo", "Telo");
-      this.reverseIdentityMap.set("Telo", "telo");
     }
-    // If identity is already known, register the schema in AJV immediately.
     if (mod && definition.schema) {
       this.tryRegisterSchema(mod, name as string, definition.schema as Record<string, any>);
     }
@@ -80,50 +83,42 @@ export class DefinitionRegistry {
     }
   }
 
-  /** Register a module identity for x-telo-ref resolution.
-   *  Call once per module doc (Telo.Application or Telo.Library) when the manifest is loaded.
-   *  @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"). */
+  /** DEPRECATED. Register a module identity so the legacy
+   *  `<namespace>/<module>#<Kind>` form of `x-telo-ref` still resolves for module
+   *  versions published before constraints named their target by import alias.
+   *  New manifests declare no namespace and need no identity — their constraints
+   *  are canonicalized to `<module>.<Kind>` before registration.
+   *
+   *  The "telo" identity is reserved for the built-in module and is populated
+   *  automatically when a `Telo.Abstract` registers. A namespace-less module must
+   *  not claim it: overwriting the entry would repoint every legacy `telo#…`
+   *  constraint at a module that declares no such kind, and the resulting
+   *  unresolvable ref reads as partial context rather than an error.
+   *
+   *  @param namespace  The module's `metadata.namespace`, or null when it declares none.
+   *  @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);
-    // Retroactively register AJV schemas for definitions of this module already in the registry.
-    for (const def of this.defs.values()) {
-      if (def.metadata.module === moduleName && def.schema) {
-        this.tryRegisterSchema(
-          moduleName,
-          def.metadata.name as string,
-          def.schema as Record<string, any>,
-        );
-      }
-    }
+    if (!namespace || moduleName === "Telo") return;
+    this.identityMap.set(`${namespace}/${moduleName}`, moduleName);
   }
 
   /** Registers a named `Telo.Type` resource's schema under its canonical
    *  module-scoped URI `$id` (`telo://<module>/<name>`), so a sibling schema's
    *  `$ref: "telo://Self/<name>"` (rewritten to the canonical form by
    *  `resolveSchemaTypeRefs`) resolves during AJV compilation. Mirrors the
-   *  kernel type controller's `registerSchema(canonicalTypeSchemaId(...))`. */
-  registerNamedTypeSchema(id: string, schema: Record<string, any>): void {
-    if (this.registeredSchemaIds.has(id) || this.ajv.getSchema(id)) return;
+   *  kernel type controller's `registerSchema(canonicalTypeSchemaId(...))`.
+   *
+   *  Returns `false` when a kind schema in the same module already owns the id —
+   *  a name collision between a kind and a named type. Definitions register
+   *  first, so the type is the one that would be dropped, and every
+   *  `$ref: "telo://<module>/<Name>"` would then silently validate against the
+   *  kind's schema instead. The caller reports it; nothing is overwritten. */
+  registerNamedTypeSchema(id: string, schema: Record<string, any>): boolean {
+    if (this.definitionSchemaIds.has(id)) return false;
+    if (this.registeredSchemaIds.has(id) || this.ajv.getSchema(id)) return true;
     this.ajv.addSchema(schema, id);
     this.registeredSchemaIds.add(id);
+    return true;
   }
 
   /** True when a schema is registered under `id` (a canonical `telo://` type id
@@ -132,14 +127,6 @@ export class DefinitionRegistry {
     return this.registeredSchemaIds.has(id) || this.ajv.getSchema(id) !== undefined;
   }
 
-  /** Computes the $id for a definition schema: "<identity>/<TypeName>".
-   *  Returns undefined when the module identity is not yet registered. */
-  computeId(moduleName: string, typeName: string): string | undefined {
-    const identity = this.reverseIdentityMap.get(moduleName);
-    if (!identity) return undefined;
-    return `${identity}/${typeName}`;
-  }
-
   /** Validates data against a schema using this registry's AJV instance, which has all
    *  registered definition schemas loaded — enabling cross-module $ref resolution.
    *  A compile failure returns `[]` here; it is surfaced loudly (once, on the
@@ -172,37 +159,51 @@ export class DefinitionRegistry {
     }
   }
 
+  /** Registers a definition schema under the same module-scoped `telo://` id a
+   *  named `Telo.Type` uses, so a kind schema and a type schema are addressable
+   *  the same way and a `$ref` between them resolves at AJV compile time. One id
+   *  space per module: a kind and a named type may not share a name, which
+   *  `registerNamedTypeSchema` reports rather than resolving silently. */
   private tryRegisterSchema(
     moduleName: string,
     typeName: string,
     schema: Record<string, any>,
   ): void {
-    const id = this.computeId(moduleName, typeName);
-    if (!id || this.registeredSchemaIds.has(id)) return;
+    const id = canonicalTypeSchemaId(moduleName, typeName);
+    if (this.registeredSchemaIds.has(id)) {
+      this.definitionSchemaIds.add(id);
+      return;
+    }
     if (this.ajv.getSchema(id)) {
       throw new Error(`Duplicate definition schema $id: "${id}" is already registered`);
     }
     this.ajv.addSchema(schema, id);
     this.registeredSchemaIds.add(id);
+    this.definitionSchemaIds.add(id);
   }
 
-  /** Resolves an x-telo-ref string to a canonical registry kind key.
-   *  Splits on "#", looks up the left side in the identity table, and returns
-   *  "<canonicalModule>.<TypeName>".
+  /** Resolves an `x-telo-ref` constraint to a canonical registry kind key.
+   *
+   *  The constraint is already canonical `<module>.<Kind>`: alias-form values
+   *  (`KvStore.Store`, `Self.Store`, `Telo.Invocable`) are rewritten in the
+   *  declaring module's scope by `resolveSchemaRefKinds` before registration, so
+   *  no module context is needed here.
+   *
+   *  The legacy `<namespace>/<module>#<Kind>` form still resolves through the
+   *  identity table for module versions published before the alias form existed:
    *
-   *  "telo#Invocable"         → "Telo.Invocable"
-   *  "std/pipeline#Job"       → "pipeline.Job"
-   *  "std/http-server#Server" → "http-server.Server"
+   *    "telo#Invocable"         → "Telo.Invocable"
+   *    "std/http-server#Server" → "http-server.Server"
    *
-   *  Returns undefined when the string is malformed or the identity is not registered. */
+   *  Returns undefined when a legacy string is malformed or its identity was
+   *  never registered. */
   resolveRef(xTeloRef: string): string | undefined {
     const hash = xTeloRef.indexOf("#");
-    if (hash === -1 || hash === xTeloRef.length - 1) return undefined;
-    const identity = xTeloRef.slice(0, hash);
-    const typeName = xTeloRef.slice(hash + 1);
-    const moduleName = this.identityMap.get(identity);
+    if (hash === -1) return xTeloRef;
+    if (hash === xTeloRef.length - 1) return undefined;
+    const moduleName = this.identityMap.get(xTeloRef.slice(0, hash));
     if (!moduleName) return undefined;
-    return `${moduleName}.${typeName}`;
+    return `${moduleName}.${xTeloRef.slice(hash + 1)}`;
   }
 
   resolve(kind: string): ResourceDefinition | undefined {

package/src/loaded-types.ts

@@ -50,18 +50,25 @@ export interface LoadedModule {
 }
 
 /** Resolved Telo.Import edge: where the import points and what library
- *  identity it resolves to. Carrying name/namespace on the edge means
- *  `flattenForAnalyzer` can stamp `metadata.resolvedModuleName` /
- *  `resolvedNamespace` from this single source rather than re-deriving
- *  the target from manifest metadata, which would silently miss whenever
- *  a future projection forgets to stamp `metadata.source` consistently. */
+ *  identity it resolves to. Carrying the name on the edge means
+ *  `flattenForAnalyzer` can stamp `metadata.resolvedModuleName` from this
+ *  single source rather than re-deriving the target from manifest metadata,
+ *  which would silently miss whenever a future projection forgets to stamp
+ *  `metadata.source` consistently. */
 export interface ImportEdge {
   /** Canonical resolved URL of the target — a key into `modules`. */
   targetSource: string;
+  /** The import's `source` exactly as authored — a registry ref, an `oci://`
+   *  or `https://` ref, or a relative path. Version reconciliation keys on
+   *  this (minus its version), since it names the module's location
+   *  independently of what the module declares about itself. */
+  targetRef: string;
   /** Target library's `metadata.name`, or `null` when the target had no
    *  Telo.Library doc (an error case captured in `LoadedGraph.errors`). */
   targetModuleName: string | null;
-  /** Target library's `metadata.namespace` (or `null` when unset). */
+  /** DEPRECATED. Target library's `metadata.namespace`, or `null` when it
+   *  declares none. Feeds only the legacy `<namespace>/<module>#<Kind>` form
+   *  of `x-telo-ref`; nothing else reads it. */
   targetNamespace: string | null;
 }
 

package/src/manifest-loader.ts

@@ -317,6 +317,7 @@ export class Loader {
 
           aliases.set(alias, {
             targetSource: targetCanonical,
+            targetRef: importSource,
             targetModuleName,
             targetNamespace,
           });

package/src/reconcile-module-versions.ts

@@ -83,24 +83,55 @@ function compareVersions(a: ParsedVersion, b: ParsedVersion): number {
   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 {
+/** The location identity of an import ref: the ref with its version stripped.
+ *  Two refs share an identity when they address the same module at different
+ *  versions, whatever transport owns them:
+ *
+ *    "std/kv-store@0.3.0"             → "std/kv-store"
+ *    "oci://ghcr.io/acme/s3@1.2.0"    → "oci://ghcr.io/acme/s3"
+ *    "https://x.com/lib/telo.yaml"    → itself (a URL carries no version)
+ *
+ *  Returns `null` for a relative path, which addresses one file on the
+ *  publisher's disk and is therefore not a cross-import key: two local libraries
+ *  that merely agree on `metadata.name` are distinct modules, and reconciling
+ *  them would drop one and break its kinds. The same local file reached via two
+ *  paths is already collapsed by canonical-source dedup.
+ *
+ *  **What this key cannot relate.** It compares ref *spellings*, so it groups by
+ *  origin exactly and nothing else. Two consequences, both accepted:
+ *
+ *  - A module imported once by a registry ref and once by a relative path is two
+ *    groups, so a version skew between them is not hoisted. Keying on what the
+ *    module declares about itself would catch that case, but only by trusting a
+ *    self-declared identity — which is what this change removes, and which
+ *    cannot tell two same-named modules from different origins apart.
+ *  - A bare `std/kv-store@0.4.0` and the equivalent direct
+ *    `https://<registry>/std/kv-store/0.4.0/telo.yaml` are two groups. Relating
+ *    them needs the configured registry base, which this pure, browser-safe
+ *    function does not have. */
+function refIdentity(ref: string): string | null {
+  const base = ref.split("#")[0];
+  if (!base || base.startsWith(".") || base.startsWith("/") || base.startsWith("file:")) {
+    return null;
+  }
+  const lastSlash = base.lastIndexOf("/");
+  const at = base.lastIndexOf("@");
+  return at > lastSlash && at > 0 ? base.slice(0, at) : base;
+}
+
+/** Read a loaded module's version and raw owner text under the location
+ *  identity the import edge reached it by. The identity comes from the ref, not
+ *  from anything the module declares about itself — a module's own metadata
+ *  cannot distinguish two same-named modules published to different origins. */
+function moduleIdentityOf(mod: LoadedModule, identity: string): 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 meta = doc.metadata as { name?: string; version?: string };
+  if (typeof meta?.name !== "string" || meta.name.length === 0) return null;
   const version = typeof meta.version === "string" ? meta.version : "";
   return {
     source: mod.owner.source,
-    identity: `${meta.namespace}/${name}`,
+    identity,
     version,
     parsed: parseVersion(version),
     text: mod.owner.text,
@@ -184,8 +215,8 @@ function hoistDiagnostic(
 }
 
 /**
- * Reconcile a loaded import graph so each module identity (`namespace/name`)
- * resolves to a single version. Within a shared major the highest version wins
+ * Reconcile a loaded import graph so each module location (an import ref minus
+ * its version) 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`
@@ -199,10 +230,31 @@ export function reconcileModuleVersions(
   const overrides = new Map<string, string>();
   const diagnostics: AnalysisDiagnostic[] = [];
 
+  // Location identity per resolved module, taken from the ref that reached it.
+  // Two refs at different versions resolve to different canonical sources, so a
+  // source normally maps to exactly one identity; the entry module has no
+  // inbound edge and needs none (it is never reconciled against itself).
+  //
+  // One source CAN be reached by two spellings of the same location (a bare
+  // registry ref and the direct URL it resolves to). Both name the same module
+  // at the same version, so either identity groups it correctly — but the choice
+  // must not depend on edge iteration order, or the same graph could reconcile
+  // differently across runs. First edge wins.
+  const identityBySource = new Map<string, string>();
+  for (const aliasMap of importEdges.values()) {
+    for (const edge of aliasMap.values()) {
+      if (identityBySource.has(edge.targetSource)) continue;
+      const identity = refIdentity(edge.targetRef);
+      if (identity) identityBySource.set(edge.targetSource, identity);
+    }
+  }
+
   const groups = new Map<string, ModuleIdentity[]>();
   const infoBySource = new Map<string, ModuleIdentity>();
-  for (const mod of modules.values()) {
-    const info = moduleIdentityOf(mod);
+  for (const [source, mod] of modules) {
+    const identity = identityBySource.get(source);
+    if (!identity) continue;
+    const info = moduleIdentityOf(mod, identity);
     if (!info) continue;
     infoBySource.set(info.source, info);
     const list = groups.get(info.identity);

package/src/reference-field-map.ts

@@ -1,6 +1,7 @@
 /** An entry for a field that carries one or more x-telo-ref constraints. */
 export interface RefFieldEntry {
-  /** One or more canonical ref strings ("namespace/module#TypeName" or "telo#TypeName").
+  /** One or more canonical kind keys ("<module>.<Kind>"), or the deprecated
+   *  identity form ("<namespace>/<module>#<Kind>") for a legacy published module.
    *  Multiple entries arise from anyOf branches. */
   refs: string[];
   /** True when the field path traversed through at least one array (path contains "[]"). */
@@ -210,7 +211,7 @@ function traverseNode(
   // the kernel's `runInvoke` emit-Invoked path. The walker fix and the
   // dispatcher fix need to land together — see the follow-up in
   // [kernel/nodejs/plans/reference-syntax-unification.md] and the
-  // stopgap in `resource-context.ts:resolveChildren`. `visitedRefs`
+  // stopgap in `resource-context.ts:ensureKindRef`. `visitedRefs`
   // stays as a parameter so the recursive calls below thread the right
   // signature; turning the descent back on is a single-branch change.
   if (typeof node?.$ref === "string") return;