@telorun/analyzer 0.43.0 → 0.45.0

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

package/src/reference-field-map.ts

@@ -1,6 +1,7 @@
 /** An entry for a field that carries one or more x-telo-ref constraints. */
 export interface RefFieldEntry {
-  /** One or more canonical ref strings ("namespace/module#TypeName" or "telo#TypeName").
+  /** One or more canonical kind keys ("<module>.<Kind>"), or the deprecated
+   *  identity form ("<namespace>/<module>#<Kind>") for a legacy published module.
    *  Multiple entries arise from anyOf branches. */
   refs: string[];
   /** True when the field path traversed through at least one array (path contains "[]"). */

package/src/resolve-schema-ref-kinds.ts

@@ -0,0 +1,118 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+
+const REF_ANNOTATION = "x-telo-ref";
+
+/** Why an `x-telo-ref` constraint did not canonicalize.
+ *
+ *  - `legacy`  — the deprecated `<namespace>/<module>#<Kind>` identity form,
+ *                still resolved through the identity table.
+ *  - `unknown` — the prefix is not an alias in the declaring module's scope: a
+ *                typo, a missing `imports:` entry — or a value that was already
+ *                canonical, which the caller separates by asking the registry.
+ *  - `gated`   — the alias is known and the target owns the kind, but its
+ *                `exports.kinds` does not list it. */
+export type RefConstraintReason = "legacy" | "unknown" | "gated";
+
+/** An `x-telo-ref` constraint that did not canonicalize. */
+export interface RefConstraintIssue {
+  /** The constraint string exactly as authored. */
+  ref: string;
+  /** Dotted path to the annotated schema node within the doc, e.g.
+   *  `schema.properties.store`. Points the author at the slot, not just the doc. */
+  path: string;
+  /** The `Telo.Definition` / `Telo.Abstract` doc that declares the slot. */
+  manifest: ResourceManifest;
+  reason: RefConstraintReason;
+  /** For `gated`: the target module and the kinds it does export. */
+  gate?: { module: string; exported: string[] };
+  /** Aliases the declaring scope does know — the "did you mean" material for
+   *  an `unknown` prefix. */
+  knownAliases?: string[];
+}
+
+/** True for the legacy identity form, which is split on `#` by the identity table. */
+export function isLegacyRefIdentity(ref: string): boolean {
+  return ref.includes("#");
+}
+
+/**
+ * Rewrites the `x-telo-ref` constraints on one definition doc from the alias
+ * form (`KvStore.Store`, `Self.Store`, `Telo.Invocable`) to the canonical
+ * `<module>.<Kind>` key the definition registry is keyed by.
+ *
+ * `resolver` must be the scope of the module that DECLARES the definition, not
+ * the consumer's: an imported library names its dependencies by its own aliases.
+ * This mirrors how `extends:` and `capability:` are pre-resolved before
+ * registration, so the registry never needs module context to answer a ref query.
+ *
+ * Every constraint that does not canonicalize is returned, tagged with why. That
+ * matters more than it looks: an unresolved constraint leaves a string naming no
+ * registered kind, and the reference check treats an unknown target as partial
+ * context and skips it — so an unreported one would silently let the slot accept
+ * anything. The authored value is left in place either way, so a diagnostic
+ * quotes what the author actually wrote.
+ *
+ * An `unknown` result also covers an already-canonical value (`kv-store.Store`
+ * names a module, not an alias), which is what keeps the rewrite idempotent —
+ * the caller drops those by checking the definition registry once every kind is
+ * registered.
+ *
+ * The walk covers the whole doc rather than a fixed field list: a constraint can
+ * sit in `schema`, `inputType`, `outputType`, or a `$defs` entry nested in any of
+ * them, and rewriting one that appears in a template body's inline schema is
+ * correct too.
+ */
+export function resolveSchemaRefKinds(
+  definition: ResourceManifest,
+  resolver: Pick<AliasResolver, "resolveKindResult" | "knownAliases">,
+): RefConstraintIssue[] {
+  const issues: RefConstraintIssue[] = [];
+
+  const record = (ref: string, path: string): void => {
+    if (isLegacyRefIdentity(ref)) {
+      issues.push({ ref, path, manifest: definition, reason: "legacy" });
+      return;
+    }
+    const result = resolver.resolveKindResult(ref);
+    if (result.status === "ok") return;
+    issues.push(
+      result.status === "gated"
+        ? {
+            ref,
+            path,
+            manifest: definition,
+            reason: "gated",
+            gate: { module: result.module, exported: result.exported },
+          }
+        : {
+            ref,
+            path,
+            manifest: definition,
+            reason: "unknown",
+            knownAliases: resolver.knownAliases(),
+          },
+    );
+  };
+
+  const walk = (value: unknown, path: string): void => {
+    if (value === null || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach((item, i) => walk(item, `${path}[${i}]`));
+      return;
+    }
+    const obj = value as Record<string, unknown>;
+    const ref = obj[REF_ANNOTATION];
+    if (typeof ref === "string" && ref) {
+      const result = isLegacyRefIdentity(ref) ? null : resolver.resolveKindResult(ref);
+      if (result?.status === "ok") obj[REF_ANNOTATION] = result.kind;
+      else record(ref, path);
+    }
+    for (const key of Object.keys(obj)) {
+      walk(obj[key], path ? `${path}.${key}` : key);
+    }
+  };
+
+  walk(definition, "");
+  return issues;
+}

package/src/sources/manifest-cache.ts

@@ -12,12 +12,20 @@ export const MANIFEST_CACHE_BASE_URL = "https://manifests.telo.sh";
  *  stores per version — `{ transport, host, path, version }` — so the tracker's
  *  write key and the editor's read key come from the same function and never
  *  drift. `path` is the slash-separated repo/module path (multi-segment OCI
- *  repos nest as prefixes). */
+ *  repos nest as prefixes), empty for a module addressed at a host's root. */
 export interface ManifestCacheCoords {
   transport: string;
   host: string;
   path: string;
-  version: string;
+  /** Omit only when the ref carries no version to key by — a direct `https://`
+   *  URL addresses exactly one file, so its path alone is already unambiguous.
+   *  Every ref whose grammar has a version segment must supply it, or two
+   *  versions of one module would collide on a single key. */
+  version?: string;
+  /** File within the version directory. Defaults to the module manifest, which
+   *  is the only file the hub's bucket stores; the local install cache also
+   *  holds each `include:` partial, which is named here. */
+  file?: string;
 }
 
 /** True for a segment that would corrupt or escape the cache key space. */
@@ -26,15 +34,25 @@ function invalidSegment(segment: string): boolean {
 }
 
 /** 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: ManifestCacheCoords): string | null {
-  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

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;
+}