@telorun/analyzer 0.44.0 → 0.45.0

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";

package/dist/module-version-order.d.ts

@@ -0,0 +1,36 @@
+/** SemVer precedence for module versions — the single ordering rule shared by
+ *  version reconciliation and by any host deciding whether an import is behind.
+ *
+ *  Pure and dependency-free (no `semver` package), so the analyzer stays
+ *  browser-safe and the editor can reach the same rule the kernel-side analysis
+ *  uses. A caller that cannot parse a version must not guess: an OCI digest, a
+ *  moving tag like `latest`, and a malformed pin all come back `null` rather
+ *  than being ordered by some weaker fallback. */
+export interface ParsedModuleVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    /** Dot-separated prerelease identifiers, or `null` for a release version. */
+    pre: string[] | null;
+}
+/** Parse `X.Y.Z`, `vX.Y.Z`, or `X.Y.Z-pre.1`. Returns `null` for anything that
+ *  isn't a plain three-part numeric core — an unparseable version is never
+ *  silently ordered. */
+export declare function parseModuleVersion(raw: string | undefined): ParsedModuleVersion | null;
+/** SemVer precedence: numeric core, then a release outranks a prerelease, then
+ *  prerelease identifiers compared field-by-field (numeric < non-numeric per
+ *  spec, shorter set loses when all shared fields are equal). */
+export declare function compareParsedModuleVersions(a: ParsedModuleVersion, b: ParsedModuleVersion): number;
+/** Negative / zero / positive when both versions parse, `null` when either does
+ *  not. The string-in convenience over {@link compareParsedModuleVersions}. */
+export declare function compareModuleVersions(a: string, b: string): number | null;
+/** True when `candidate` is strictly newer than `current` — the test for
+ *  whether an import is behind. False when they are equal, when `current` is
+ *  ahead (a version index can lag the module's own origin, and "upgrading" to
+ *  what it knows would be a downgrade), or when either side is unparseable. */
+export declare function isNewerModuleVersion(candidate: string, current: string): boolean;
+/** True when two tags name the same version, tolerating a `v` prefix on either
+ *  side. Falls back to exact equality for unparseable tags, so a digest still
+ *  matches itself. */
+export declare function isSameModuleVersion(a: string, b: string): boolean;
+//# sourceMappingURL=module-version-order.d.ts.map

package/dist/module-version-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-version-order.d.ts","sourceRoot":"","sources":["../src/module-version-order.ts"],"names":[],"mappings":"AAAA;;;;;;;kDAOkD;AAElD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CACtB;AAED;;wBAEwB;AACxB,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,mBAAmB,GAAG,IAAI,CAatF;AAED;;iEAEiE;AACjE,wBAAgB,2BAA2B,CACzC,CAAC,EAAE,mBAAmB,EACtB,CAAC,EAAE,mBAAmB,GACrB,MAAM,CAyBR;AAED;+EAC+E;AAC/E,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKzE;AAED;;;+EAG+E;AAC/E,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEhF;AAED;;sBAEsB;AACtB,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/module-version-order.js

@@ -0,0 +1,91 @@
+/** SemVer precedence for module versions — the single ordering rule shared by
+ *  version reconciliation and by any host deciding whether an import is behind.
+ *
+ *  Pure and dependency-free (no `semver` package), so the analyzer stays
+ *  browser-safe and the editor can reach the same rule the kernel-side analysis
+ *  uses. A caller that cannot parse a version must not guess: an OCI digest, a
+ *  moving tag like `latest`, and a malformed pin all come back `null` rather
+ *  than being ordered by some weaker fallback. */
+/** Parse `X.Y.Z`, `vX.Y.Z`, or `X.Y.Z-pre.1`. Returns `null` for anything that
+ *  isn't a plain three-part numeric core — an unparseable version is never
+ *  silently ordered. */
+export function parseModuleVersion(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const v = raw.startsWith("v") ? raw.slice(1) : raw;
+    const [core, ...preParts] = v.split("-");
+    const pre = preParts.length > 0 ? preParts.join("-") : null;
+    const segments = core.split(".");
+    if (segments.length !== 3)
+        return null;
+    const [major, minor, patch] = segments.map((s) => {
+        if (!/^\d+$/.test(s))
+            return NaN;
+        return Number(s);
+    });
+    if ([major, minor, patch].some((n) => Number.isNaN(n)))
+        return null;
+    return { major, minor, patch, pre: pre === null ? null : pre.split(".") };
+}
+/** SemVer precedence: numeric core, then a release outranks a prerelease, then
+ *  prerelease identifiers compared field-by-field (numeric < non-numeric per
+ *  spec, shorter set loses when all shared fields are equal). */
+export function compareParsedModuleVersions(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    if (a.patch !== b.patch)
+        return a.patch - b.patch;
+    if (a.pre === null && b.pre === null)
+        return 0;
+    if (a.pre === null)
+        return 1;
+    if (b.pre === null)
+        return -1;
+    const len = Math.max(a.pre.length, b.pre.length);
+    for (let i = 0; i < len; i++) {
+        const ai = a.pre[i];
+        const bi = b.pre[i];
+        if (ai === undefined)
+            return -1;
+        if (bi === undefined)
+            return 1;
+        const an = /^\d+$/.test(ai);
+        const bn = /^\d+$/.test(bi);
+        if (an && bn) {
+            const d = Number(ai) - Number(bi);
+            if (d !== 0)
+                return d;
+        }
+        else if (an !== bn) {
+            return an ? -1 : 1;
+        }
+        else if (ai !== bi) {
+            return ai < bi ? -1 : 1;
+        }
+    }
+    return 0;
+}
+/** Negative / zero / positive when both versions parse, `null` when either does
+ *  not. The string-in convenience over {@link compareParsedModuleVersions}. */
+export function compareModuleVersions(a, b) {
+    const left = parseModuleVersion(a);
+    const right = parseModuleVersion(b);
+    if (!left || !right)
+        return null;
+    return compareParsedModuleVersions(left, right);
+}
+/** True when `candidate` is strictly newer than `current` — the test for
+ *  whether an import is behind. False when they are equal, when `current` is
+ *  ahead (a version index can lag the module's own origin, and "upgrading" to
+ *  what it knows would be a downgrade), or when either side is unparseable. */
+export function isNewerModuleVersion(candidate, current) {
+    return (compareModuleVersions(candidate, current) ?? 0) > 0;
+}
+/** True when two tags name the same version, tolerating a `v` prefix on either
+ *  side. Falls back to exact equality for unparseable tags, so a digest still
+ *  matches itself. */
+export function isSameModuleVersion(a, b) {
+    return a === b || compareModuleVersions(a, b) === 0;
+}

package/dist/reconcile-module-versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile-module-versions.d.ts","sourceRoot":"","sources":["../src/reconcile-module-versions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;0CAI0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;2EACuE;IACvE,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAuMD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAClC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAChD,qBAAqB,CAsEvB"}
+{"version":3,"file":"reconcile-module-versions.d.ts","sourceRoot":"","sources":["../src/reconcile-module-versions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAOlE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;0CAI0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;2EACuE;IACvE,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAgJD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAClC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAChD,qBAAqB,CAsEvB"}

package/dist/reconcile-module-versions.js

@@ -1,69 +1,7 @@
 import { isModuleKind } from "./module-kinds.js";
+import { compareParsedModuleVersions, parseModuleVersion, } from "./module-version-order.js";
 import { DiagnosticSeverity } from "./types.js";
 const SOURCE = "telo-analyzer";
-/** Parse `X.Y.Z`, `vX.Y.Z`, or `X.Y.Z-pre.1`. Returns `null` for anything that
- *  isn't a plain three-part numeric core — an unparseable version forces the
- *  group onto the conflict path (we never silently hoist across a version we
- *  can't reason about). Pure: no dependency on the `semver` package, so the
- *  analyzer stays browser-safe and dependency-free. */
-function parseVersion(raw) {
-    if (typeof raw !== "string")
-        return null;
-    const v = raw.startsWith("v") ? raw.slice(1) : raw;
-    const [core, ...preParts] = v.split("-");
-    const pre = preParts.length > 0 ? preParts.join("-") : null;
-    const segments = core.split(".");
-    if (segments.length !== 3)
-        return null;
-    const [major, minor, patch] = segments.map((s) => {
-        if (!/^\d+$/.test(s))
-            return NaN;
-        return Number(s);
-    });
-    if ([major, minor, patch].some((n) => Number.isNaN(n)))
-        return null;
-    return { major, minor, patch, pre: pre === null ? null : pre.split(".") };
-}
-/** SemVer precedence: numeric core, then a release outranks a prerelease, then
- *  prerelease identifiers compared field-by-field (numeric < non-numeric per
- *  spec, shorter set loses when all shared fields are equal). */
-function compareVersions(a, b) {
-    if (a.major !== b.major)
-        return a.major - b.major;
-    if (a.minor !== b.minor)
-        return a.minor - b.minor;
-    if (a.patch !== b.patch)
-        return a.patch - b.patch;
-    if (a.pre === null && b.pre === null)
-        return 0;
-    if (a.pre === null)
-        return 1;
-    if (b.pre === null)
-        return -1;
-    const len = Math.max(a.pre.length, b.pre.length);
-    for (let i = 0; i < len; i++) {
-        const ai = a.pre[i];
-        const bi = b.pre[i];
-        if (ai === undefined)
-            return -1;
-        if (bi === undefined)
-            return 1;
-        const an = /^\d+$/.test(ai);
-        const bn = /^\d+$/.test(bi);
-        if (an && bn) {
-            const d = Number(ai) - Number(bi);
-            if (d !== 0)
-                return d;
-        }
-        else if (an !== bn) {
-            return an ? -1 : 1;
-        }
-        else if (ai !== bi) {
-            return ai < bi ? -1 : 1;
-        }
-    }
-    return 0;
-}
 /** 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:
@@ -115,7 +53,7 @@ function moduleIdentityOf(mod, identity) {
         source: mod.owner.source,
         identity,
         version,
-        parsed: parseVersion(version),
+        parsed: parseModuleVersion(version),
         text: mod.owner.text,
     };
 }
@@ -135,7 +73,7 @@ function resolveGroup(members) {
             return best;
         if (!best.parsed)
             return cur;
-        const cmp = compareVersions(cur.parsed, best.parsed);
+        const cmp = compareParsedModuleVersions(cur.parsed, best.parsed);
         if (cmp > 0)
             return cur;
         if (cmp === 0 && cur.source < best.source)

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.44.0",
+  "version": "0.45.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",

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/module-version-order.ts

@@ -0,0 +1,91 @@
+/** SemVer precedence for module versions — the single ordering rule shared by
+ *  version reconciliation and by any host deciding whether an import is behind.
+ *
+ *  Pure and dependency-free (no `semver` package), so the analyzer stays
+ *  browser-safe and the editor can reach the same rule the kernel-side analysis
+ *  uses. A caller that cannot parse a version must not guess: an OCI digest, a
+ *  moving tag like `latest`, and a malformed pin all come back `null` rather
+ *  than being ordered by some weaker fallback. */
+
+export interface ParsedModuleVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  /** Dot-separated prerelease identifiers, or `null` for a release version. */
+  pre: string[] | null;
+}
+
+/** Parse `X.Y.Z`, `vX.Y.Z`, or `X.Y.Z-pre.1`. Returns `null` for anything that
+ *  isn't a plain three-part numeric core — an unparseable version is never
+ *  silently ordered. */
+export function parseModuleVersion(raw: string | undefined): ParsedModuleVersion | null {
+  if (typeof raw !== "string") return null;
+  const v = raw.startsWith("v") ? raw.slice(1) : raw;
+  const [core, ...preParts] = v.split("-");
+  const pre = preParts.length > 0 ? preParts.join("-") : null;
+  const segments = core.split(".");
+  if (segments.length !== 3) return null;
+  const [major, minor, patch] = segments.map((s) => {
+    if (!/^\d+$/.test(s)) return NaN;
+    return Number(s);
+  });
+  if ([major, minor, patch].some((n) => Number.isNaN(n))) return null;
+  return { major, minor, patch, pre: pre === null ? null : pre.split(".") };
+}
+
+/** SemVer precedence: numeric core, then a release outranks a prerelease, then
+ *  prerelease identifiers compared field-by-field (numeric < non-numeric per
+ *  spec, shorter set loses when all shared fields are equal). */
+export function compareParsedModuleVersions(
+  a: ParsedModuleVersion,
+  b: ParsedModuleVersion,
+): number {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  if (a.patch !== b.patch) return a.patch - b.patch;
+  if (a.pre === null && b.pre === null) return 0;
+  if (a.pre === null) return 1;
+  if (b.pre === null) return -1;
+  const len = Math.max(a.pre.length, b.pre.length);
+  for (let i = 0; i < len; i++) {
+    const ai = a.pre[i];
+    const bi = b.pre[i];
+    if (ai === undefined) return -1;
+    if (bi === undefined) return 1;
+    const an = /^\d+$/.test(ai);
+    const bn = /^\d+$/.test(bi);
+    if (an && bn) {
+      const d = Number(ai) - Number(bi);
+      if (d !== 0) return d;
+    } else if (an !== bn) {
+      return an ? -1 : 1;
+    } else if (ai !== bi) {
+      return ai < bi ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/** Negative / zero / positive when both versions parse, `null` when either does
+ *  not. The string-in convenience over {@link compareParsedModuleVersions}. */
+export function compareModuleVersions(a: string, b: string): number | null {
+  const left = parseModuleVersion(a);
+  const right = parseModuleVersion(b);
+  if (!left || !right) return null;
+  return compareParsedModuleVersions(left, right);
+}
+
+/** True when `candidate` is strictly newer than `current` — the test for
+ *  whether an import is behind. False when they are equal, when `current` is
+ *  ahead (a version index can lag the module's own origin, and "upgrading" to
+ *  what it knows would be a downgrade), or when either side is unparseable. */
+export function isNewerModuleVersion(candidate: string, current: string): boolean {
+  return (compareModuleVersions(candidate, current) ?? 0) > 0;
+}
+
+/** True when two tags name the same version, tolerating a `v` prefix on either
+ *  side. Falls back to exact equality for unparseable tags, so a digest still
+ *  matches itself. */
+export function isSameModuleVersion(a: string, b: string): boolean {
+  return a === b || compareModuleVersions(a, b) === 0;
+}

package/src/reconcile-module-versions.ts

@@ -1,5 +1,10 @@
 import type { ImportEdge, LoadedModule } from "./loaded-types.js";
 import { isModuleKind } from "./module-kinds.js";
+import {
+  compareParsedModuleVersions,
+  parseModuleVersion,
+  type ParsedModuleVersion,
+} from "./module-version-order.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -17,72 +22,17 @@ export interface VersionReconciliation {
   diagnostics: AnalysisDiagnostic[];
 }
 
-interface ParsedVersion {
-  major: number;
-  minor: number;
-  patch: number;
-  /** Dot-separated prerelease identifiers, or `null` for a release version. */
-  pre: string[] | null;
-}
-
 interface ModuleIdentity {
   source: string;
   identity: string;
   version: string;
-  parsed: ParsedVersion | null;
+  /** `null` for an unparseable version, which forces the group onto the
+   *  conflict path — we never silently hoist across a version we can't reason
+   *  about. */
+  parsed: ParsedModuleVersion | null;
   text: string;
 }
 
-/** Parse `X.Y.Z`, `vX.Y.Z`, or `X.Y.Z-pre.1`. Returns `null` for anything that
- *  isn't a plain three-part numeric core — an unparseable version forces the
- *  group onto the conflict path (we never silently hoist across a version we
- *  can't reason about). Pure: no dependency on the `semver` package, so the
- *  analyzer stays browser-safe and dependency-free. */
-function parseVersion(raw: string | undefined): ParsedVersion | null {
-  if (typeof raw !== "string") return null;
-  const v = raw.startsWith("v") ? raw.slice(1) : raw;
-  const [core, ...preParts] = v.split("-");
-  const pre = preParts.length > 0 ? preParts.join("-") : null;
-  const segments = core.split(".");
-  if (segments.length !== 3) return null;
-  const [major, minor, patch] = segments.map((s) => {
-    if (!/^\d+$/.test(s)) return NaN;
-    return Number(s);
-  });
-  if ([major, minor, patch].some((n) => Number.isNaN(n))) return null;
-  return { major, minor, patch, pre: pre === null ? null : pre.split(".") };
-}
-
-/** SemVer precedence: numeric core, then a release outranks a prerelease, then
- *  prerelease identifiers compared field-by-field (numeric < non-numeric per
- *  spec, shorter set loses when all shared fields are equal). */
-function compareVersions(a: ParsedVersion, b: ParsedVersion): number {
-  if (a.major !== b.major) return a.major - b.major;
-  if (a.minor !== b.minor) return a.minor - b.minor;
-  if (a.patch !== b.patch) return a.patch - b.patch;
-  if (a.pre === null && b.pre === null) return 0;
-  if (a.pre === null) return 1;
-  if (b.pre === null) return -1;
-  const len = Math.max(a.pre.length, b.pre.length);
-  for (let i = 0; i < len; i++) {
-    const ai = a.pre[i];
-    const bi = b.pre[i];
-    if (ai === undefined) return -1;
-    if (bi === undefined) return 1;
-    const an = /^\d+$/.test(ai);
-    const bn = /^\d+$/.test(bi);
-    if (an && bn) {
-      const d = Number(ai) - Number(bi);
-      if (d !== 0) return d;
-    } else if (an !== bn) {
-      return an ? -1 : 1;
-    } else if (ai !== bi) {
-      return ai < bi ? -1 : 1;
-    }
-  }
-  return 0;
-}
-
 /** 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:
@@ -133,7 +83,7 @@ function moduleIdentityOf(mod: LoadedModule, identity: string): ModuleIdentity |
     source: mod.owner.source,
     identity,
     version,
-    parsed: parseVersion(version),
+    parsed: parseModuleVersion(version),
     text: mod.owner.text,
   };
 }
@@ -158,7 +108,7 @@ function resolveGroup(members: ModuleIdentity[]): GroupResolution {
   const winner = members.reduce((best, cur) => {
     if (!cur.parsed) return best;
     if (!best.parsed) return cur;
-    const cmp = compareVersions(cur.parsed, best.parsed);
+    const cmp = compareParsedModuleVersions(cur.parsed, best.parsed);
     if (cmp > 0) return cur;
     if (cmp === 0 && cur.source < best.source) return cur;
     return best;

package/src/sources/versioned-ref.ts

@@ -0,0 +1,77 @@
+import { splitIntegrity } from "./integrity.js";
+import { isRegistryRef } from "./module-ref.js";
+import { OCI_SCHEME } from "./oci-ref.js";
+
+/** 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 function parseVersionedRef(ref: string): ParsedVersionedRef | null {
+  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: string, version: string): string {
+  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: string): "oci" | "registry" | null {
+  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: string): number | null {
+  if (refGrammar(base) === null) return null;
+  const at = base.lastIndexOf("@");
+  return at > (base.startsWith(OCI_SCHEME) ? OCI_SCHEME.length : 0) ? at : null;
+}