@telorun/analyzer 0.43.0 → 0.45.0

package/dist/sources/manifest-cache.js

@@ -10,15 +10,24 @@ function invalidSegment(segment) {
     return segment === "" || segment === "." || segment === ".." || segment.includes("\\");
 }
 /** Deterministic cache key for one module version:
- *  `<transport>/<host>/<path…>/<version>/telo.yaml`. Returns `null` when any
- *  coordinate is empty or would traverse out of the key space. */
+ *  `<transport>/<host>/<path…>/<version>/<file>`, where `version` is omitted
+ *  when the coordinates carry none and `file` defaults to the module manifest.
+ *  Returns `null` when any coordinate is empty or would traverse out of the key
+ *  space. */
 export function manifestCacheKey(coords) {
-    const { transport, host, path, version } = coords;
-    const segments = [transport, host, ...path.split("/"), version];
-    if (segments.some(invalidSegment) || transport.includes("/") || host.includes("/") || version.includes("/")) {
+    const { transport, host, path, version, file } = coords;
+    const segments = [transport, host, ...(path ? path.split("/") : [])];
+    if (version !== undefined)
+        segments.push(version);
+    segments.push(file ?? DEFAULT_MANIFEST_FILENAME);
+    if (segments.some(invalidSegment) ||
+        transport.includes("/") ||
+        host.includes("/") ||
+        (version !== undefined && version.includes("/")) ||
+        (file !== undefined && file.includes("/"))) {
         return null;
     }
-    return `${segments.join("/")}/${DEFAULT_MANIFEST_FILENAME}`;
+    return segments.join("/");
 }
 /** Cache coordinates for an `oci://host/repo@tag` ref. Returns `null` when the
  *  ref carries no explicit tag (a defaulted `latest` or a `sha256:` digest is

package/dist/sources/versioned-ref.d.ts

@@ -0,0 +1,34 @@
+/** A module ref split into the parts an upgrade needs: the version-independent
+ *  ref, the version segment it currently names, and any inline pin. */
+export interface ParsedVersionedRef {
+    /** The ref with its `@version` segment and integrity fragment removed —
+     *  `std/run`, `oci://ghcr.io/telorun/timer`. This is the identity a version
+     *  list is keyed by (the hub registers modules under exactly this form). */
+    baseRef: string;
+    /** The version segment, raw — a registry `@version`, an OCI tag, or an OCI
+     *  digest reference (`sha256:…`). The caller applies its own SemVer check. */
+    version: string;
+    /** Telo's inline `sha256-<base64url>` pin, when the ref carried one. */
+    integrity?: string;
+}
+/** Split a versioned module ref. Returns `null` when the ref names no
+ *  upgradeable version — a local path, a bare `https://` URL, or an OCI ref
+ *  with no explicit reference (an implicit `latest` is not a pin).
+ *
+ *  Browser-safe and transport-neutral: this is the *grammar* half of an
+ *  upgrade, shared by the kernel transports (whose `refVersion` / `withVersion`
+ *  delegate here) and the editor, which cannot use a transport at all — the
+ *  *network* half (enumerating versions) is scheme-specific and stays behind
+ *  `Transport.listVersions` on Node and the hub's `/module/versions` in the
+ *  browser. */
+export declare function parseVersionedRef(ref: string): ParsedVersionedRef | null;
+/** `ref` rewritten to name `version`, dropping any integrity fragment (the
+ *  caller re-pins the result). Appends the version when the ref carries none —
+ *  an untagged `oci://host/repo` is still a versionable address.
+ *
+ *  Throws when the ref's grammar has no version segment at all — a relative
+ *  path, a bare `https://` URL. Producing `../lib@0.4.0` for those would write
+ *  a ref nothing can resolve, so this fails where the transport-specific
+ *  parsers it replaced (`parseOciRef` / `parseModuleRef`) also failed. */
+export declare function withRefVersion(ref: string, version: string): string;
+//# sourceMappingURL=versioned-ref.d.ts.map

package/dist/sources/versioned-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-ref.d.ts","sourceRoot":"","sources":["../../src/sources/versioned-ref.ts"],"names":[],"mappings":"AAIA;uEACuE;AACvE,MAAM,WAAW,kBAAkB;IACjC;;gFAE4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB;kFAC8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;eASe;AACf,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAOxE;AAED;;;;;;;0EAO0E;AAC1E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAUnE"}

package/dist/sources/versioned-ref.js

@@ -0,0 +1,60 @@
+import { splitIntegrity } from "./integrity.js";
+import { isRegistryRef } from "./module-ref.js";
+import { OCI_SCHEME } from "./oci-ref.js";
+/** Split a versioned module ref. Returns `null` when the ref names no
+ *  upgradeable version — a local path, a bare `https://` URL, or an OCI ref
+ *  with no explicit reference (an implicit `latest` is not a pin).
+ *
+ *  Browser-safe and transport-neutral: this is the *grammar* half of an
+ *  upgrade, shared by the kernel transports (whose `refVersion` / `withVersion`
+ *  delegate here) and the editor, which cannot use a transport at all — the
+ *  *network* half (enumerating versions) is scheme-specific and stays behind
+ *  `Transport.listVersions` on Node and the hub's `/module/versions` in the
+ *  browser. */
+export function parseVersionedRef(ref) {
+    const { base, integrity } = splitIntegrity(ref);
+    const at = versionSeparator(base);
+    if (at === null)
+        return null;
+    const version = base.slice(at + 1);
+    if (!version)
+        return null;
+    return { baseRef: base.slice(0, at), version, integrity };
+}
+/** `ref` rewritten to name `version`, dropping any integrity fragment (the
+ *  caller re-pins the result). Appends the version when the ref carries none —
+ *  an untagged `oci://host/repo` is still a versionable address.
+ *
+ *  Throws when the ref's grammar has no version segment at all — a relative
+ *  path, a bare `https://` URL. Producing `../lib@0.4.0` for those would write
+ *  a ref nothing can resolve, so this fails where the transport-specific
+ *  parsers it replaced (`parseOciRef` / `parseModuleRef`) also failed. */
+export function withRefVersion(ref, version) {
+    const { base } = splitIntegrity(ref);
+    if (refGrammar(base) === null) {
+        throw new Error(`Cannot set a version on '${ref}' — only registry (namespace/name@version) ` +
+            `and oci:// refs carry a version segment.`);
+    }
+    const at = versionSeparator(base);
+    return `${at === null ? base : base.slice(0, at)}@${version}`;
+}
+/** Which versionable ref grammar `base` is written in, or `null` when it is
+ *  neither — a relative/absolute path, a `file:`/`https://` URL. */
+function refGrammar(base) {
+    if (base.startsWith(OCI_SCHEME)) {
+        // A host alone is not addressable; the repo path is what carries a version.
+        return base.indexOf("/", OCI_SCHEME.length) > OCI_SCHEME.length ? "oci" : null;
+    }
+    // `isRegistryRef` requires the `@`, so a version-less `std/console` is not a
+    // registry ref by this test — matching `parseModuleRef`, which throws on it.
+    return isRegistryRef(base) ? "registry" : null;
+}
+/** Index of the `@` that separates the version, or `null` when the ref names
+ *  none. Split on the LAST `@` so a digest reference (`repo@sha256:…`) keeps
+ *  everything before it as the ref. */
+function versionSeparator(base) {
+    if (refGrammar(base) === null)
+        return null;
+    const at = base.lastIndexOf("@");
+    return at > (base.startsWith(OCI_SCHEME) ? OCI_SCHEME.length : 0) ? at : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.43.0",
+  "version": "0.45.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.54.0"
+    "@telorun/sdk": "0.56.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

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";
@@ -1035,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;
@@ -1043,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;
@@ -1063,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));
     }
 
@@ -1089,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(

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/index.ts

@@ -60,6 +60,14 @@ 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 {
+  compareModuleVersions,
+  compareParsedModuleVersions,
+  isNewerModuleVersion,
+  isSameModuleVersion,
+  parseModuleVersion,
+} from "./module-version-order.js";
+export type { ParsedModuleVersion } from "./module-version-order.js";
 export { reconcileModuleVersions } from "./reconcile-module-versions.js";
 export type { VersionReconciliation } from "./reconcile-module-versions.js";
 export { residualEntrySchema, residualEntrySchemaMap } from "./residual-schema.js";
@@ -86,6 +94,8 @@ export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
 export type { ParsedModuleRef } from "./sources/module-ref.js";
 export { OCI_SCHEME, isOciRef, parseOciRef } from "./sources/oci-ref.js";
 export type { ParsedOciRef } from "./sources/oci-ref.js";
+export { parseVersionedRef, withRefVersion } from "./sources/versioned-ref.js";
+export type { ParsedVersionedRef } from "./sources/versioned-ref.js";
 export { isLocalPathSource } from "./sources/local-path-ref.js";
 export {
   MANIFEST_CACHE_BASE_URL,

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,
           });