@telorun/analyzer 0.43.0 → 0.45.0

package/dist/analysis-registry.d.ts

@@ -10,7 +10,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
@@ -55,9 +55,9 @@ export declare class AnalysisRegistry {
     refFieldsForResource(resource: ResourceManifest): RefFieldInfo[];
     /** 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;
@@ -137,7 +137,7 @@ export declare class AnalysisRegistry {
      *  resolved (e.g. unregistered identity). */
     acceptedKindsForRef(xTeloRef: string): Set<string> | undefined;
     /** 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/dist/analysis-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAqC,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEhG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD;;wDAEwD;AACxD,MAAM,WAAW,YAAY;IAC3B;0CACsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,OAAO,EAAE,OAAO,CAAC;IACjB,sFAAsF;IACtF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;8EAG0E;IAC1E,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAIjD,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpE;;+EAE2E;IAC3E,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAI9E,wFAAwF;IACxF,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAIzD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;OAOG;IACH,mBAAmB,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAkBP;;;;;;OAMG;IACH,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,YAAY,EAAE;IAoBhE;;;;;;wBAMoB;IACpB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQtD;;;;;;sFAMkF;IAClF,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAenE;;;;;qDAKiD;IACjD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAepE,OAAO,CAAC,mBAAmB;IAS3B;;;;;;OAMG;IACH,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,EACxB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,GACzF,IAAI;IAQP;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAM/D;;;;;;;;yCAQqC;IACrC,qBAAqB,CAAC,GAAG,EAAE;QACzB,QAAQ,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAChC,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,kBAAkB,GAAG,SAAS;IASpD;;qFAEiF;IACjF,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAUzC,QAAQ,IAAI,MAAM,EAAE;IAIpB;mEAC+D;IAC/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC;;;gCAG4B;IAC5B,oBAAoB,IAAI,MAAM,EAAE;IAIhC;wEACoE;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD;;;;;;;;iDAQ6C;IAC7C,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,SAAS;IAqB9D;;;;;gEAK4D;IAC5D,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAiB7D,qFAAqF;IACrF,QAAQ,IAAI,eAAe;CAG5B"}

package/dist/analysis-registry.js

@@ -81,9 +81,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) {
@@ -260,7 +260,7 @@ export class AnalysisRegistry {
         return out;
     }
     /** 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/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAqB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA8xB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAw2BvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAmBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAsB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA8xB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA07BvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAmBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -12,6 +12,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 } 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";
@@ -865,6 +866,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 = [];
         for (const m of manifests) {
             if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract")
                 continue;
@@ -873,6 +875,16 @@ export class StaticAnalyzer {
             const scopeResolver = 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;
@@ -891,6 +903,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,
+                };
+                const filePath = issue.manifest.metadata?.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));
         }
         // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
@@ -914,7 +977,27 @@ export class StaticAnalyzer {
             const canonicalKind = scopeResolver.resolveKind(m.kind) ?? m.kind;
             if (defs.resolve(canonicalKind)?.capability !== "Telo.Type")
                 continue;
-            defs.registerNamedTypeSchema(canonicalTypeSchemaId(ownModule, m.metadata.name), m.schema);
+            const typeName = m.metadata.name;
+            const registered = defs.registerNamedTypeSchema(canonicalTypeSchemaId(ownModule, typeName), m.schema);
+            // 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?.source,
+                        path: "metadata.name",
+                    },
+                });
+            }
         }
         if (!options?.skipValidation) {
             diagnostics.push(...validateSchemaTypeRefs(allManifests, defs, aliases, aliasesByModule, rootModules));

package/dist/builtins.js

@@ -89,7 +89,7 @@ const ROOT_LOGGING_SCHEMA = {
             type: "array",
             items: {
                 type: "object",
-                "x-telo-ref": "telo#LogSink",
+                "x-telo-ref": "Telo.LogSink",
                 "x-telo-inline": true,
             },
         },
@@ -435,8 +435,8 @@ export const KERNEL_BUILTINS = [
                     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
@@ -460,8 +460,8 @@ export const KERNEL_BUILTINS = [
                                 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"],
@@ -501,8 +501,8 @@ export const KERNEL_BUILTINS = [
                                         },
                                         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/dist/definition-registry.d.ts

@@ -9,36 +9,52 @@ export declare class DefinitionRegistry {
      *  across analyze() calls and no unbounded growth across the process lifetime. */
     private readonly ajv;
     private readonly registeredSchemaIds;
+    /** 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;
     private readonly defs;
     private readonly fieldMaps;
     /** Reverse inheritance index: parent kind → direct child kinds. */
     private readonly extendedBy;
-    /** 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;
-    /** 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;
     register(definition: ResourceDefinition): void;
     private addExtendedBy;
-    /** 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;
     /** 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;
+     *  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;
     /** True when a schema is registered under `id` (a canonical `telo://` type id
      *  or a definition `$id`). Used to flag schema `$ref`s that resolve to nothing. */
     hasSchemaId(id: string): boolean;
-    /** 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;
     /** 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
@@ -53,16 +69,27 @@ export declare class DefinitionRegistry {
      *  `validateWithRefs` would swallow the failure and silently skip every
      *  resource of that kind. */
     schemaCompileError(schema: Record<string, any>): string | undefined;
+    /** 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;
-    /** 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;
     resolve(kind: string): ResourceDefinition | undefined;
     /** Returns the reference field map for the given kind, computed lazily from the

package/dist/definition-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition-registry.d.ts","sourceRoot":"","sources":["../src/definition-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAIlC,+EAA+E;AAC/E,qBAAa,kBAAkB;;IAK7B;;sFAEkF;IAClF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D;6DACyD;IACzD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD;;0EAEsE;IACtE,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA6B;IAEhE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAqC9C,OAAO,CAAC,aAAa;IASrB;;;yFAGqF;IACrF,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IA+B1E;;;;iFAI6E;IAC7E,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAMtE;uFACmF;IACnF,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIhC;4EACwE;IACxE,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMnE;;;;oFAIgF;IAChF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAWtE;;;;;;iCAM6B;IAC7B,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,SAAS;IASnE,OAAO,CAAC,iBAAiB;IAczB;;;;;;;;4FAQwF;IACxF,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUhD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIrD;;;uCAGmC;IACnC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAWxD,gGAAgG;IAChG,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS;IAOhC;;;;;;;;qFAQiF;IACjF,2BAA2B,CACzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC1C,iBAAiB,GAAG,SAAS;IAkChC,OAAO,CAAC,uBAAuB;IA+B/B;;qEAEiE;IACjE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAgBxD,KAAK,IAAI,MAAM,EAAE;CAGlB"}
+{"version":3,"file":"definition-registry.d.ts","sourceRoot":"","sources":["../src/definition-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAIlC,+EAA+E;AAC/E,qBAAa,kBAAkB;;IAK7B;;sFAEkF;IAClF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD;;mFAE+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D;;;;wEAIoE;IACpE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAoC9C,OAAO,CAAC,aAAa;IASrB;;;;;;;;;;;;;2FAauF;IACvF,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAK1E;;;;;;;;;;gFAU4E;IAC5E,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO;IAQzE;uFACmF;IACnF,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIhC;;;;oFAIgF;IAChF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAWtE;;;;;;iCAM6B;IAC7B,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,SAAS;IASnE;;;;4EAIwE;IACxE,OAAO,CAAC,iBAAiB;IAkBzB;;;;;;;;;;;;;;4BAcwB;IACxB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAShD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIrD;;;uCAGmC;IACnC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAWxD,gGAAgG;IAChG,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS;IAOhC;;;;;;;;qFAQiF;IACjF,2BAA2B,CACzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC1C,iBAAiB,GAAG,SAAS;IAkChC,OAAO,CAAC,uBAAuB;IA+B/B;;qEAEiE;IACjE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAgBxD,KAAK,IAAI,MAAM,EAAE;CAGlB"}

package/dist/definition-registry.js

@@ -1,3 +1,4 @@
+import { canonicalTypeSchemaId } from "@telorun/sdk";
 import { KERNEL_BUILTINS } from "./builtins.js";
 import { buildFieldMapAtPath, buildReferenceFieldMap, isSchemaFromEntry, } from "./reference-field-map.js";
 import { createAjv, formatSingleError, navigateJsonPointer } from "./schema-compat.js";
@@ -13,17 +14,20 @@ export class DefinitionRegistry {
      *  across analyze() calls and no unbounded growth across the process lifetime. */
     ajv = createAjv();
     registeredSchemaIds = new Set();
+    /** 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. */
+    definitionSchemaIds = new Set();
     defs = new Map();
     fieldMaps = new Map();
     /** Reverse inheritance index: parent kind → direct child kinds. */
     extendedBy = new Map();
-    /** 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. */
     identityMap = new Map();
-    /** 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. */
-    reverseIdentityMap = new Map();
     register(definition) {
         const { name, module: mod } = definition.metadata;
         const key = mod ? `${mod}.${name}` : name;
@@ -50,12 +54,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, definition.schema);
         }
@@ -70,61 +73,50 @@ export class DefinitionRegistry {
             this.extendedBy.set(parent, [child]);
         }
     }
-    /** 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, moduleName) {
-        // 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")
+        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, def.schema);
-            }
-        }
+        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(...))`. */
+     *  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, schema) {
+        if (this.definitionSchemaIds.has(id))
+            return false;
         if (this.registeredSchemaIds.has(id) || this.ajv.getSchema(id))
-            return;
+            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
      *  or a definition `$id`). Used to flag schema `$ref`s that resolve to nothing. */
     hasSchemaId(id) {
         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, typeName) {
-        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
@@ -158,35 +150,49 @@ export class DefinitionRegistry {
             return err instanceof Error ? err.message : String(err);
         }
     }
+    /** 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. */
     tryRegisterSchema(moduleName, typeName, schema) {
-        const id = this.computeId(moduleName, typeName);
-        if (!id || this.registeredSchemaIds.has(id))
+        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) {
         const hash = xTeloRef.indexOf("#");
-        if (hash === -1 || hash === xTeloRef.length - 1)
+        if (hash === -1)
+            return xTeloRef;
+        if (hash === xTeloRef.length - 1)
             return undefined;
-        const identity = xTeloRef.slice(0, hash);
-        const typeName = xTeloRef.slice(hash + 1);
-        const moduleName = this.identityMap.get(identity);
+        const moduleName = this.identityMap.get(xTeloRef.slice(0, hash));
         if (!moduleName)
             return undefined;
-        return `${moduleName}.${typeName}`;
+        return `${moduleName}.${xTeloRef.slice(hash + 1)}`;
     }
     resolve(kind) {
         return this.defs.get(kind);

package/dist/index.d.ts

@@ -20,6 +20,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 { 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";
@@ -33,6 +35,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, ManifestCacheSource, isHttpsModuleRef, manifestCacheKey, manifestCacheUrl, ociManifestCacheCoords, urlManifestCacheCoords, } from "./sources/manifest-cache.js";
 export type { ManifestCacheCoords } from "./sources/manifest-cache.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -11,6 +11,7 @@ export { Loader } from "./manifest-loader.js";
 export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export { parseLoadedFile } from "./parse-loaded-file.js";
 export { desugarLoadedFile, inlineImportManifests } from "./inline-imports.js";
+export { compareModuleVersions, compareParsedModuleVersions, isNewerModuleVersion, isSameModuleVersion, parseModuleVersion, } from "./module-version-order.js";
 export { reconcileModuleVersions } from "./reconcile-module-versions.js";
 export { residualEntrySchema, residualEntrySchemaMap } from "./residual-schema.js";
 export { buildDocumentPositions, buildLineOffsets, buildPositionIndex, documentLineOffsets, offsetToPosition, } from "./position-metadata.js";
@@ -20,6 +21,7 @@ export { defaultSources } from "./sources/default-sources.js";
 export { splitIntegrity, foldIntegrity, verifyIntegrity, verifiedFetch, sha256Base64Url, IntegrityError, } from "./sources/integrity.js";
 export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
 export { OCI_SCHEME, isOciRef, parseOciRef } from "./sources/oci-ref.js";
+export { parseVersionedRef, withRefVersion } from "./sources/versioned-ref.js";
 export { isLocalPathSource } from "./sources/local-path-ref.js";
 export { MANIFEST_CACHE_BASE_URL, ManifestCacheSource, isHttpsModuleRef, manifestCacheKey, manifestCacheUrl, ociManifestCacheCoords, urlManifestCacheCoords, } from "./sources/manifest-cache.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";