@telorun/ide-support 0.14.1 → 0.15.0

package/dist/import-upgrades/build-import-upgrades.d.ts

@@ -1,4 +1,5 @@
 import { type AstDocument, type Range } from "@telorun/analyzer";
+import { type IncompatibilityReason, type VersionCompatibilityCheck } from "./version-compatibility.js";
 /** One version of a module, as the hub reports it.
  *
  *  `integrity` is the import pin for exactly this version (`sha256-<base64url>`
@@ -23,6 +24,22 @@ export interface ModuleVersion {
  *  `GET /module/versions` and passes the body through
  *  {@link parseModuleVersions}. */
 export type ModuleVersionLookup = (baseRef: string) => Promise<ModuleVersion[]>;
+/** Everything an upgrade needs from its host: what versions exist, and whether
+ *  this runtime can host one.
+ *
+ *  `isCompatible` is required rather than optional so no host can quietly skip
+ *  the check and walk an author onto a version their telo cannot load — the gap
+ *  this package existed with. A host that genuinely cannot fetch candidate
+ *  manifests passes {@link uncheckedVersionCompatibility}, which says so
+ *  instead of pretending. */
+export interface ImportUpgradeEnvironment {
+    listVersions: ModuleVersionLookup;
+    isCompatible: VersionCompatibilityCheck;
+    /** Offer prereleases as automatic upgrade targets. Off by default, matching
+     *  `telo upgrade`: an upgrade nobody asked for must not walk a caller onto an
+     *  `-rc` build. */
+    includePrerelease?: boolean;
+}
 /** A source edit a host applies verbatim to upgrade an import. Ranges never
  *  overlap, within an upgrade or across a batch, so a host may apply the whole
  *  set in one pass without ordering them. */
@@ -50,6 +67,14 @@ export interface ImportUpgrade {
      *  means no pin was available for the target version — a host should say so
      *  when `wasPinned`, since the rewrite silently drops a hash the author had. */
     repinned: boolean;
+    /** A newer version that exists but this runtime cannot host, when
+     *  `latestVersion` is not the newest published. Surfacing it is not optional:
+     *  an upgrade that quietly stops short of the newest version, with no reason
+     *  given, reads as a bug in the tooling. */
+    heldBack?: {
+        version: string;
+        reason: IncompatibilityReason;
+    };
     /** Span of the alias key — where a per-entry affordance anchors. */
     keyRange: Range;
     /** Apply all of these to upgrade this one import. */
@@ -79,8 +104,18 @@ export interface ImportUpgradeSkip {
     latestVersion: string;
     /** Span of the alias key — where a per-entry affordance anchors. */
     keyRange: Range;
-    /** Author-facing sentence: what was not done, and what to run instead. */
-    reason: string;
+    /** Which decision this was, for a host that styles or filters them.
+     *  `incompatible` — every newer version declares a telo this runtime is not;
+     *  `stale-inline-pin` — the rewrite could not carry or drop the author's pin. */
+    code: "incompatible" | "stale-inline-pin";
+    /** Which rejection produced an `incompatible` skip, so a host can phrase its
+     *  own affordance without re-deriving one. Carried BESIDE `code` because the
+     *  code says what was not done while this says why, and the remedies differ:
+     *  updating telo cannot fix a requirement the module failed to state. Absent
+     *  for `stale-inline-pin`, which is not a compatibility decision at all. */
+    reason?: IncompatibilityReason;
+    /** Author-facing sentence: what was not done, and what to do instead. */
+    message: string;
 }
 export interface ImportUpgradeSet {
     /** Span of the `imports:` key — where a summary affordance anchors. */
@@ -102,6 +137,13 @@ export interface ImportUpgradeSet {
  * re-point it — plus every entry already at the newest version that carries no
  * integrity pin, and the edits that pin it.
  *
+ * The target is the newest version this runtime can HOST, which is not always
+ * the newest one published: each candidate's declared `requires.telo` is checked
+ * newest-first, and a newer version that was held back is reported on the
+ * upgrade rather than dropped. An import whose every newer version needs a newer
+ * telo produces a `skipped` entry instead, since the alternative — offering it
+ * anyway — is a manifest that fails at the load gate.
+ *
  * Skips what carries no upgradeable version: local path imports, bare URLs,
  * untagged refs, and pins that are not SemVer (an OCI digest, a moving tag like
  * `latest`) — `parseVersionedRef` and `isNewerModuleVersion` both decline to
@@ -111,5 +153,17 @@ export interface ImportUpgradeSet {
  * API. Returns `undefined` when the file declares no module document or the
  * module declares no `imports:`.
  */
-export declare function buildImportUpgrades(text: string, listVersions: ModuleVersionLookup, docs?: AstDocument[]): Promise<ImportUpgradeSet | undefined>;
+export declare function buildImportUpgrades(text: string, env: ImportUpgradeEnvironment, docs?: AstDocument[]): Promise<ImportUpgradeSet | undefined>;
+/** How a held-back version reads in a sentence, with the version itself as the
+ *  implied subject. Names the cause the check actually established.
+ *
+ *  The parameter is REQUIRED, so a caller cannot reach a sentence for a cause
+ *  nothing established — defaulting an absent reason to "requires a newer telo"
+ *  is precisely the invented verdict the four-way split exists to prevent. */
+export declare function describeReason(reason: IncompatibilityReason): string;
+/** What the author can do about it. Split from {@link describeReason} because
+ *  the two rejections have DIFFERENT remedies: an unreadable requirement is not
+ *  a version skew, so telling the author to update telo would send them after a
+ *  fix that cannot work — only the module's own author can repair it. */
+export declare function describeRemedy(reason: IncompatibilityReason): string;
 //# sourceMappingURL=build-import-upgrades.d.ts.map

package/dist/import-upgrades/build-import-upgrades.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-import-upgrades.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/build-import-upgrades.ts"],"names":[],"mappings":"AAAA,OAAO,EAYL,KAAK,WAAW,EAChB,KAAK,KAAK,EACX,MAAM,mBAAmB,CAAC;AAG3B;;;;;oEAKoE;AACpE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;mCAYmC;AACnC,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;AAEhF;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;6EAKyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;IACnB;;oFAEgF;IAChF,QAAQ,EAAE,OAAO,CAAC;IAClB,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB,qDAAqD;IACrD,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED;;;kFAGkF;AAClF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED;;;yDAGyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,eAAe,EAAE,KAAK,CAAC;IACvB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B;;wDAEoD;IACpD,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,mBAAmB,EACjC,IAAI,CAAC,EAAE,WAAW,EAAE,GACnB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAmEvC"}
+{"version":3,"file":"build-import-upgrades.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/build-import-upgrades.ts"],"names":[],"mappings":"AAAA,OAAO,EAaL,KAAK,WAAW,EAChB,KAAK,KAAK,EACX,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC/B,MAAM,4BAA4B,CAAC;AAEpC;;;;;oEAKoE;AACpE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;mCAYmC;AACnC,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;AAEhF;;;;;;;6BAO6B;AAC7B,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,mBAAmB,CAAC;IAClC,YAAY,EAAE,yBAAyB,CAAC;IACxC;;uBAEmB;IACnB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;6CAE6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;6EAKyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;IACnB;;oFAEgF;IAChF,QAAQ,EAAE,OAAO,CAAC;IAClB;;;gDAG4C;IAC5C,QAAQ,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,qBAAqB,CAAA;KAAE,CAAC;IAC9D,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB,qDAAqD;IACrD,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED;;;kFAGkF;AAClF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED;;;yDAGyD;AACzD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,EAAE,KAAK,CAAC;IAChB;;qFAEiF;IACjF,IAAI,EAAE,cAAc,GAAG,kBAAkB,CAAC;IAC1C;;;;gFAI4E;IAC5E,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,eAAe,EAAE,KAAK,CAAC;IACvB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B;;wDAEoD;IACpD,QAAQ,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,wBAAwB,EAC7B,IAAI,CAAC,EAAE,WAAW,EAAE,GACnB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAwGvC;AAED;;;;;8EAK8E;AAC9E,wBAAgB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAIpE;AAED;;;yEAGyE;AACzE,wBAAgB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CAIpE"}

package/dist/import-upgrades/build-import-upgrades.js

@@ -1,11 +1,19 @@
-import { buildLineOffsets, foldIntegrity, isCanonicalIntegrity, isLocalPathSource, isNewerModuleVersion, isSameModuleVersion, newestModuleVersion, parseModuleVersion, parseToAst, parseVersionedRef, withRefVersion, } from "@telorun/analyzer";
+import { TELO_SURFACE_VERSION, buildLineOffsets, foldIntegrity, isCanonicalIntegrity, isLocalPathSource, isNewerModuleVersion, isSameModuleVersion, newestModuleVersion, parseModuleVersion, parseToAst, parseVersionedRef, withRefVersion, } from "@telorun/analyzer";
 import { findImportEntries } from "./find-import-entries.js";
+import { selectCompatibleVersion, } from "./version-compatibility.js";
 /**
  * Find every `imports:` entry of a module document that names a version older
  * than the newest one `listVersions` reports, and produce the source edits that
  * re-point it — plus every entry already at the newest version that carries no
  * integrity pin, and the edits that pin it.
  *
+ * The target is the newest version this runtime can HOST, which is not always
+ * the newest one published: each candidate's declared `requires.telo` is checked
+ * newest-first, and a newer version that was held back is reported on the
+ * upgrade rather than dropped. An import whose every newer version needs a newer
+ * telo produces a `skipped` entry instead, since the alternative — offering it
+ * anyway — is a manifest that fails at the load gate.
+ *
  * Skips what carries no upgradeable version: local path imports, bare URLs,
  * untagged refs, and pins that are not SemVer (an OCI digest, a moving tag like
  * `latest`) — `parseVersionedRef` and `isNewerModuleVersion` both decline to
@@ -15,7 +23,7 @@ import { findImportEntries } from "./find-import-entries.js";
  * API. Returns `undefined` when the file declares no module document or the
  * module declares no `imports:`.
  */
-export async function buildImportUpgrades(text, listVersions, docs) {
+export async function buildImportUpgrades(text, env, docs) {
     const lineOffsets = buildLineOffsets(text);
     const block = findImportEntries(text, docs ?? parseToAst(text), lineOffsets);
     if (!block)
@@ -27,7 +35,7 @@ export async function buildImportUpgrades(text, listVersions, docs) {
         return ref ? [{ entry, ref }] : [];
     });
     const failures = [];
-    const known = await resolveVersions([...new Set(candidates.map((c) => c.ref.baseRef))], listVersions, failures);
+    const known = await resolveVersions([...new Set(candidates.map((c) => c.ref.baseRef))], env.listVersions, failures);
     const upgrades = [];
     const pins = [];
     const skipped = [];
@@ -35,7 +43,9 @@ export async function buildImportUpgrades(text, listVersions, docs) {
         const versions = known.get(ref.baseRef);
         if (!versions)
             continue;
-        const newest = newestModuleVersion(versions.map((v) => v.version));
+        const newest = newestModuleVersion(versions.map((v) => v.version), {
+            includePrerelease: env.includePrerelease,
+        });
         if (!newest)
             continue;
         if (!isNewerModuleVersion(newest, ref.version)) {
@@ -44,7 +54,32 @@ export async function buildImportUpgrades(text, listVersions, docs) {
                 pins.push(pin);
             continue;
         }
-        const integrity = integrityFor(versions, newest);
+        // The target is the newest version this runtime can actually host, not
+        // simply the newest one published. An upgrade the author's telo cannot load
+        // is not an upgrade — it is a load failure they were walked into.
+        const { best, heldBack } = await selectCompatibleVersion(ref.baseRef, versions, ref.version, env.isCompatible, { includePrerelease: env.includePrerelease });
+        // `heldBack` is non-null whenever a candidate existed, which `newest` being
+        // newer than the current version already established. Narrowed rather than
+        // defaulted: a reason nothing established is exactly what the four-verdict
+        // split exists to keep out of a message.
+        if (!best) {
+            if (!heldBack)
+                continue;
+            skipped.push({
+                alias: entry.alias,
+                currentVersion: ref.version,
+                latestVersion: newest,
+                keyRange: entry.keyRange,
+                code: "incompatible",
+                reason: heldBack.reason,
+                message: `'${entry.alias}' has newer versions (up to ${newest}), but none runs on telo ` +
+                    `${TELO_SURFACE_VERSION} — ${describeReason(heldBack.reason)}. ` +
+                    describeRemedy(heldBack.reason),
+            });
+            continue;
+        }
+        const target = best.version;
+        const integrity = integrityFor(versions, target);
         // A stale pin that can be neither replaced nor removed is the one case left
         // that has to be declined: re-pointing the source while leaving a hash for
         // the version it replaced turns the next install into a tamper error.
@@ -52,29 +87,51 @@ export async function buildImportUpgrades(text, listVersions, docs) {
             skipped.push({
                 alias: entry.alias,
                 currentVersion: ref.version,
-                latestVersion: newest,
+                latestVersion: target,
                 keyRange: entry.keyRange,
-                reason: `'${entry.alias}' carries an inline 'integrity:' that shares a line with other ` +
-                    `fields, and no pin is published for ${newest}, so the stale one cannot be ` +
+                code: "stale-inline-pin",
+                message: `'${entry.alias}' carries an inline 'integrity:' that shares a line with other ` +
+                    `fields, and no pin is published for ${target}, so the stale one cannot be ` +
                     `removed by a line edit. Run \`telo upgrade\`.`,
             });
             continue;
         }
-        const newSource = withRefVersion(entry.source, newest);
+        const newSource = withRefVersion(entry.source, target);
         upgrades.push({
             alias: entry.alias,
             source: entry.source,
             currentVersion: ref.version,
-            latestVersion: newest,
+            latestVersion: target,
             newSource: foldIntegrity(newSource, integrity),
             wasPinned: ref.integrity != null,
             repinned: integrity != null,
             keyRange: entry.keyRange,
+            ...(heldBack ? { heldBack } : {}),
             edits: buildEdits(entry, newSource, integrity),
         });
     }
     return { importsKeyRange: block.keyRange, upgrades, pins, skipped, failures };
 }
+/** How a held-back version reads in a sentence, with the version itself as the
+ *  implied subject. Names the cause the check actually established.
+ *
+ *  The parameter is REQUIRED, so a caller cannot reach a sentence for a cause
+ *  nothing established — defaulting an absent reason to "requires a newer telo"
+ *  is precisely the invented verdict the four-way split exists to prevent. */
+export function describeReason(reason) {
+    return reason === "unreadable"
+        ? "its declared requirement cannot be read"
+        : "it requires a newer telo";
+}
+/** What the author can do about it. Split from {@link describeReason} because
+ *  the two rejections have DIFFERENT remedies: an unreadable requirement is not
+ *  a version skew, so telling the author to update telo would send them after a
+ *  fix that cannot work — only the module's own author can repair it. */
+export function describeRemedy(reason) {
+    return reason === "unreadable"
+        ? "Only the module's author can fix that."
+        : "Update telo to upgrade it.";
+}
 /** The edits that re-point an entry at `newSource` and settle its pin.
  *
  *  Where the pin is written follows the shape the author chose: an entry with an

package/dist/import-upgrades/index.d.ts

@@ -1,6 +1,9 @@
-export { buildImportUpgrades } from "./build-import-upgrades.js";
-export type { ImportPin, ImportUpgrade, ImportUpgradeEdit, ImportUpgradeSet, ImportUpgradeSkip, ModuleVersion, ModuleVersionLookup, } from "./build-import-upgrades.js";
+export { buildImportUpgrades, describeReason, describeRemedy, } from "./build-import-upgrades.js";
+export type { ImportPin, ImportUpgrade, ImportUpgradeEdit, ImportUpgradeEnvironment, ImportUpgradeSet, ImportUpgradeSkip, ModuleVersion, ModuleVersionLookup, } from "./build-import-upgrades.js";
+export { moduleManifestCacheUrl } from "./manifest-cache-url.js";
 export { parseModuleVersions } from "./parse-module-versions.js";
 export { findImportEntries } from "./find-import-entries.js";
 export type { ImportEntry, ImportEntryIntegrity, ImportsBlock, } from "./find-import-entries.js";
+export { createVersionCompatibility, markVersionCompatibility, noneRunnableReason, selectCompatibleVersion, uncheckedVersionCompatibility, } from "./version-compatibility.js";
+export type { IncompatibilityReason, MarkedVersion, ModuleCompatibility, ModuleManifestReader, VersionCompatibilityCheck, VersionSelection, } from "./version-compatibility.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/import-upgrades/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,YAAY,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,YAAY,GACb,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,cAAc,GACf,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,uBAAuB,EACvB,6BAA6B,GAC9B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,4BAA4B,CAAC"}

package/dist/import-upgrades/index.js

@@ -1,3 +1,5 @@
-export { buildImportUpgrades } from "./build-import-upgrades.js";
+export { buildImportUpgrades, describeReason, describeRemedy, } from "./build-import-upgrades.js";
+export { moduleManifestCacheUrl } from "./manifest-cache-url.js";
 export { parseModuleVersions } from "./parse-module-versions.js";
 export { findImportEntries } from "./find-import-entries.js";
+export { createVersionCompatibility, markVersionCompatibility, noneRunnableReason, selectCompatibleVersion, uncheckedVersionCompatibility, } from "./version-compatibility.js";

package/dist/import-upgrades/manifest-cache-url.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where one version of a module's `telo.yaml` can be read from the hub's static
+ * manifest cache, or `null` when this ref is not addressable there.
+ *
+ * This is the read path an upgrade check uses to ask a candidate version what
+ * runtime it requires: a plain CORS GET of a single small file, no transport
+ * protocol and no artifact payload, so it works identically from a browser and
+ * from an extension host. The `fetch` itself stays with the host — everything
+ * in this package leaves the network to its caller.
+ *
+ * A ref the cache cannot address (a registry ref, whose origin this side does
+ * not know; a URL with no version segment) returns `null`, which the caller
+ * reads as "not known" and never as "incompatible". Losing the check for those
+ * refs is the honest outcome: the manifest is still gated at load time.
+ */
+export declare function moduleManifestCacheUrl(baseRef: string, version: string, baseUrl?: string): string | null;
+//# sourceMappingURL=manifest-cache-url.d.ts.map

package/dist/import-upgrades/manifest-cache-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-cache-url.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/manifest-cache-url.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,MAAgC,GACxC,MAAM,GAAG,IAAI,CAYf"}

package/dist/import-upgrades/manifest-cache-url.js

@@ -0,0 +1,30 @@
+import { MANIFEST_CACHE_BASE_URL, isOciRef, manifestCacheUrl, urlManifestCacheCoords, withRefVersion, } from "@telorun/analyzer";
+/**
+ * Where one version of a module's `telo.yaml` can be read from the hub's static
+ * manifest cache, or `null` when this ref is not addressable there.
+ *
+ * This is the read path an upgrade check uses to ask a candidate version what
+ * runtime it requires: a plain CORS GET of a single small file, no transport
+ * protocol and no artifact payload, so it works identically from a browser and
+ * from an extension host. The `fetch` itself stays with the host — everything
+ * in this package leaves the network to its caller.
+ *
+ * A ref the cache cannot address (a registry ref, whose origin this side does
+ * not know; a URL with no version segment) returns `null`, which the caller
+ * reads as "not known" and never as "incompatible". Losing the check for those
+ * refs is the honest outcome: the manifest is still gated at load time.
+ */
+export function moduleManifestCacheUrl(baseRef, version, baseUrl = MANIFEST_CACHE_BASE_URL) {
+    if (isOciRef(baseRef)) {
+        let versioned;
+        try {
+            versioned = withRefVersion(baseRef, version);
+        }
+        catch {
+            return null;
+        }
+        return manifestCacheUrl(versioned, baseUrl);
+    }
+    const coords = urlManifestCacheCoords(baseRef, version);
+    return coords ? manifestCacheUrl(coords, baseUrl) : null;
+}

package/dist/import-upgrades/version-compatibility.d.ts

@@ -0,0 +1,92 @@
+import { type ModuleCompatibility } from "@telorun/analyzer";
+import type { ModuleVersion } from "./build-import-upgrades.js";
+export type { ModuleCompatibility };
+/**
+ * Host capability: the `telo.yaml` text of one version of a module, or `null`
+ * when this host cannot address it (a transport it does not speak, a ref with
+ * no version segment). Rejecting is equally fine — both read as "not known",
+ * never as "incompatible".
+ *
+ * Narrow on purpose, and separate from {@link ModuleVersionLookup}: enumerating
+ * versions and reading one manifest are different routes with different costs,
+ * and a host caches or throttles them differently.
+ */
+export type ModuleManifestReader = (baseRef: string, version: string) => Promise<string | null | undefined>;
+/** The question an upgrade asks of a candidate version. */
+export type VersionCompatibilityCheck = (baseRef: string, version: string) => Promise<ModuleCompatibility>;
+/**
+ * A compatibility check backed by `read`, memoized per module and version for
+ * the lifetime of the returned function.
+ *
+ * The cache is not an optimization detail — an IDE re-derives its upgrade
+ * affordances on every keystroke, and a published version's declared
+ * requirement is immutable, so refetching it would be pure waste against an
+ * answer that cannot have changed. In-flight promises are shared, so the
+ * concurrent lookups one file's imports produce collapse to one read each.
+ *
+ * The verdict is always the analyzer's {@link manifestCompatibility}: an IDE
+ * reports NO host versions, because it is not the machine that will run the
+ * manifest. Only the telo surface is checked here; a host requirement still
+ * surfaces at the load gate when the manifest is actually run.
+ */
+export declare function createVersionCompatibility(read: ModuleManifestReader, teloVersion?: string): VersionCompatibilityCheck;
+/** A check that answers `unknown` for everything — the honest reading for a
+ *  host with no way to fetch a candidate manifest. Never blocks an upgrade. */
+export declare const uncheckedVersionCompatibility: VersionCompatibilityCheck;
+/** Why a candidate was not offered. `unknown` never appears: a version that
+ *  could not be read is offered, since an unreachable source must not silently
+ *  freeze an author's imports. */
+export type IncompatibilityReason = Exclude<ModuleCompatibility, "yes" | "unknown">;
+export interface VersionSelection {
+    /** The newest version this runtime can host that is also newer than the
+     *  current one, or `null` when there is none. */
+    best: ModuleVersion | null;
+    /** The newest candidate overall, when it is NOT `best` — what was held back.
+     *  Reported rather than swallowed: without it an upgrade affordance says
+     *  "up to date" while newer versions exist, which is a silent ceiling and a
+     *  worse report than the load failure this whole check replaces. */
+    heldBack: {
+        version: string;
+        reason: IncompatibilityReason;
+    } | null;
+}
+/**
+ * The newest version whose declared requirement accepts this runtime, among
+ * those newer than `currentVersion`.
+ *
+ * Walks newest-first and stops at the first satisfied candidate, so the common
+ * case — the newest version is compatible — costs a single manifest read.
+ * Candidates older than the current version are never considered: an upgrade
+ * that walks backwards is a downgrade nobody asked for. Pass `null` for an
+ * import that does not exist yet, where every published version is a candidate
+ * and there is nothing to walk backwards from.
+ */
+export declare function selectCompatibleVersion(baseRef: string, versions: readonly ModuleVersion[], currentVersion: string | null, isCompatible: VersionCompatibilityCheck, options?: {
+    includePrerelease?: boolean;
+}): Promise<VersionSelection>;
+/** One version as a picker renders it: what it is, and what this runtime makes
+ *  of it. */
+export interface MarkedVersion extends ModuleVersion {
+    compatibility: ModuleCompatibility;
+}
+/**
+ * Every version, each carrying its own verdict — what a deliberate pick needs.
+ *
+ * Unlike {@link selectCompatibleVersion} this cannot short-circuit: a picker
+ * marks entries it is not going to choose, so every entry has to be asked. That
+ * is why the two are separate operations rather than one with a flag — the
+ * automatic path must stay one read, and the picker is an explicit action on a
+ * single import whose reads are cached from then on.
+ */
+export declare function markVersionCompatibility(baseRef: string, versions: readonly ModuleVersion[], isCompatible: VersionCompatibilityCheck): Promise<MarkedVersion[]>;
+/**
+ * Why nothing in a marked list can be offered, or `null` when something can.
+ *
+ * A picker has to state this outright: a list where every row is marked
+ * explains nothing on its own, and the reader is left thinking the tool is
+ * broken. A reason rather than a boolean because the two rejections have
+ * different remedies — see {@link describeRemedy}. `unknown` counts as
+ * offerable: a version this host could not check is not one it may refuse.
+ */
+export declare function noneRunnableReason(versions: readonly MarkedVersion[]): IncompatibilityReason | null;
+//# sourceMappingURL=version-compatibility.d.ts.map

package/dist/import-upgrades/version-compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-compatibility.d.ts","sourceRoot":"","sources":["../../src/import-upgrades/version-compatibility.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAExC,2DAA2D;AAC3D,MAAM,MAAM,yBAAyB,GAAG,CACtC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,oBAAoB,EAC1B,WAAW,GAAE,MAA6B,GACzC,yBAAyB,CAqB3B;AAED;+EAC+E;AAC/E,eAAO,MAAM,6BAA6B,EAAE,yBAAiD,CAAC;AAE9F;;kCAEkC;AAClC,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC;AAEpF,MAAM,WAAW,gBAAgB;IAC/B;qDACiD;IACjD,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC3B;;;wEAGoE;IACpE,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,qBAAqB,CAAA;KAAE,GAAG,IAAI,CAAC;CACrE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,cAAc,EAAE,MAAM,GAAG,IAAI,EAC7B,YAAY,EAAE,yBAAyB,EACvC,OAAO,GAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5C,OAAO,CAAC,gBAAgB,CAAC,CAgB3B;AAED;aACa;AACb,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,aAAa,EAAE,mBAAmB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,YAAY,EAAE,yBAAyB,GACtC,OAAO,CAAC,aAAa,EAAE,CAAC,CAO1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,aAAa,EAAE,GACjC,qBAAqB,GAAG,IAAI,CAQ9B"}

package/dist/import-upgrades/version-compatibility.js

@@ -0,0 +1,121 @@
+import { TELO_SURFACE_VERSION, compareModuleVersions, isNewerModuleVersion, manifestCompatibility, parseModuleVersion, } from "@telorun/analyzer";
+/**
+ * A compatibility check backed by `read`, memoized per module and version for
+ * the lifetime of the returned function.
+ *
+ * The cache is not an optimization detail — an IDE re-derives its upgrade
+ * affordances on every keystroke, and a published version's declared
+ * requirement is immutable, so refetching it would be pure waste against an
+ * answer that cannot have changed. In-flight promises are shared, so the
+ * concurrent lookups one file's imports produce collapse to one read each.
+ *
+ * The verdict is always the analyzer's {@link manifestCompatibility}: an IDE
+ * reports NO host versions, because it is not the machine that will run the
+ * manifest. Only the telo surface is checked here; a host requirement still
+ * surfaces at the load gate when the manifest is actually run.
+ */
+export function createVersionCompatibility(read, teloVersion = TELO_SURFACE_VERSION) {
+    const cache = new Map();
+    return (baseRef, version) => {
+        const key = `${baseRef}@${version}`;
+        const cached = cache.get(key);
+        if (cached)
+            return cached;
+        const pending = read(baseRef, version)
+            .then((text) => (text ? manifestCompatibility(text, teloVersion) : "unknown"))
+            .catch(() => "unknown");
+        cache.set(key, pending);
+        // Only a DECIDED verdict is kept. What is immutable is a published version's
+        // declared requirement, not the network: caching `unknown` would let one
+        // offline moment disable the check for the rest of the session, leaving the
+        // UI reading as though every version had been checked and cleared. Dropped
+        // after it settles rather than before, so concurrent asks still share the
+        // one in-flight read.
+        void pending.then((verdict) => {
+            if (verdict === "unknown" && cache.get(key) === pending)
+                cache.delete(key);
+        });
+        return pending;
+    };
+}
+/** A check that answers `unknown` for everything — the honest reading for a
+ *  host with no way to fetch a candidate manifest. Never blocks an upgrade. */
+export const uncheckedVersionCompatibility = async () => "unknown";
+/**
+ * The newest version whose declared requirement accepts this runtime, among
+ * those newer than `currentVersion`.
+ *
+ * Walks newest-first and stops at the first satisfied candidate, so the common
+ * case — the newest version is compatible — costs a single manifest read.
+ * Candidates older than the current version are never considered: an upgrade
+ * that walks backwards is a downgrade nobody asked for. Pass `null` for an
+ * import that does not exist yet, where every published version is a candidate
+ * and there is nothing to walk backwards from.
+ */
+export async function selectCompatibleVersion(baseRef, versions, currentVersion, isCompatible, options = {}) {
+    const candidates = upgradeCandidates(versions, currentVersion, options);
+    if (candidates.length === 0)
+        return { best: null, heldBack: null };
+    const newest = candidates[0];
+    let firstReason = null;
+    for (const candidate of candidates) {
+        const verdict = await isCompatible(baseRef, candidate.version);
+        if (verdict === "too-new" || verdict === "unreadable") {
+            firstReason ??= verdict;
+            continue;
+        }
+        const held = candidate === newest ? null : { version: newest.version, reason: firstReason };
+        return { best: candidate, heldBack: held };
+    }
+    return { best: null, heldBack: { version: newest.version, reason: firstReason } };
+}
+/**
+ * Every version, each carrying its own verdict — what a deliberate pick needs.
+ *
+ * Unlike {@link selectCompatibleVersion} this cannot short-circuit: a picker
+ * marks entries it is not going to choose, so every entry has to be asked. That
+ * is why the two are separate operations rather than one with a flag — the
+ * automatic path must stay one read, and the picker is an explicit action on a
+ * single import whose reads are cached from then on.
+ */
+export async function markVersionCompatibility(baseRef, versions, isCompatible) {
+    return Promise.all(versions.map(async (version) => ({
+        ...version,
+        compatibility: await isCompatible(baseRef, version.version),
+    })));
+}
+/**
+ * Why nothing in a marked list can be offered, or `null` when something can.
+ *
+ * A picker has to state this outright: a list where every row is marked
+ * explains nothing on its own, and the reader is left thinking the tool is
+ * broken. A reason rather than a boolean because the two rejections have
+ * different remedies — see {@link describeRemedy}. `unknown` counts as
+ * offerable: a version this host could not check is not one it may refuse.
+ */
+export function noneRunnableReason(versions) {
+    if (versions.length === 0)
+        return null;
+    if (versions.some((v) => v.compatibility === "yes" || v.compatibility === "unknown")) {
+        return null;
+    }
+    // The newest blocked version's reason, in the list's own (newest-first)
+    // order: it is the one the reader is asking about.
+    return versions[0].compatibility;
+}
+/** Candidates strictly newer than `currentVersion`, newest first.
+ *
+ *  Ordering and prerelease exclusion come from the analyzer's shared rule, so
+ *  "is this import behind" and "what would it move to" cannot disagree. */
+function upgradeCandidates(versions, currentVersion, options) {
+    return versions
+        .filter((v) => {
+        const parsed = parseModuleVersion(v.version);
+        if (parsed === null)
+            return false;
+        if (parsed.pre !== null && !options.includePrerelease)
+            return false;
+        return currentVersion === null || isNewerModuleVersion(v.version, currentVersion);
+    })
+        .sort((a, b) => compareModuleVersions(b.version, a.version) ?? 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/ide-support",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Editor-host-agnostic IDE support (completions, diagnostic normalization) for Telo manifests.",
   "keywords": [
     "telo",
@@ -36,7 +36,7 @@
     "src/**"
   ],
   "dependencies": {
-    "@telorun/analyzer": "0.62.1"
+    "@telorun/analyzer": "0.63.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/import-upgrades/build-import-upgrades.ts

@@ -1,4 +1,5 @@
 import {
+  TELO_SURFACE_VERSION,
   buildLineOffsets,
   foldIntegrity,
   isCanonicalIntegrity,
@@ -14,6 +15,11 @@ import {
   type Range,
 } from "@telorun/analyzer";
 import { findImportEntries, type ImportEntry } from "./find-import-entries.js";
+import {
+  selectCompatibleVersion,
+  type IncompatibilityReason,
+  type VersionCompatibilityCheck,
+} from "./version-compatibility.js";
 
 /** One version of a module, as the hub reports it.
  *
@@ -41,6 +47,23 @@ export interface ModuleVersion {
  *  {@link parseModuleVersions}. */
 export type ModuleVersionLookup = (baseRef: string) => Promise<ModuleVersion[]>;
 
+/** Everything an upgrade needs from its host: what versions exist, and whether
+ *  this runtime can host one.
+ *
+ *  `isCompatible` is required rather than optional so no host can quietly skip
+ *  the check and walk an author onto a version their telo cannot load — the gap
+ *  this package existed with. A host that genuinely cannot fetch candidate
+ *  manifests passes {@link uncheckedVersionCompatibility}, which says so
+ *  instead of pretending. */
+export interface ImportUpgradeEnvironment {
+  listVersions: ModuleVersionLookup;
+  isCompatible: VersionCompatibilityCheck;
+  /** Offer prereleases as automatic upgrade targets. Off by default, matching
+   *  `telo upgrade`: an upgrade nobody asked for must not walk a caller onto an
+   *  `-rc` build. */
+  includePrerelease?: boolean;
+}
+
 /** A source edit a host applies verbatim to upgrade an import. Ranges never
  *  overlap, within an upgrade or across a batch, so a host may apply the whole
  *  set in one pass without ordering them. */
@@ -69,6 +92,11 @@ export interface ImportUpgrade {
    *  means no pin was available for the target version — a host should say so
    *  when `wasPinned`, since the rewrite silently drops a hash the author had. */
   repinned: boolean;
+  /** A newer version that exists but this runtime cannot host, when
+   *  `latestVersion` is not the newest published. Surfacing it is not optional:
+   *  an upgrade that quietly stops short of the newest version, with no reason
+   *  given, reads as a bug in the tooling. */
+  heldBack?: { version: string; reason: IncompatibilityReason };
   /** Span of the alias key — where a per-entry affordance anchors. */
   keyRange: Range;
   /** Apply all of these to upgrade this one import. */
@@ -100,8 +128,18 @@ export interface ImportUpgradeSkip {
   latestVersion: string;
   /** Span of the alias key — where a per-entry affordance anchors. */
   keyRange: Range;
-  /** Author-facing sentence: what was not done, and what to run instead. */
-  reason: string;
+  /** Which decision this was, for a host that styles or filters them.
+   *  `incompatible` — every newer version declares a telo this runtime is not;
+   *  `stale-inline-pin` — the rewrite could not carry or drop the author's pin. */
+  code: "incompatible" | "stale-inline-pin";
+  /** Which rejection produced an `incompatible` skip, so a host can phrase its
+   *  own affordance without re-deriving one. Carried BESIDE `code` because the
+   *  code says what was not done while this says why, and the remedies differ:
+   *  updating telo cannot fix a requirement the module failed to state. Absent
+   *  for `stale-inline-pin`, which is not a compatibility decision at all. */
+  reason?: IncompatibilityReason;
+  /** Author-facing sentence: what was not done, and what to do instead. */
+  message: string;
 }
 
 export interface ImportUpgradeSet {
@@ -122,6 +160,13 @@ export interface ImportUpgradeSet {
  * re-point it — plus every entry already at the newest version that carries no
  * integrity pin, and the edits that pin it.
  *
+ * The target is the newest version this runtime can HOST, which is not always
+ * the newest one published: each candidate's declared `requires.telo` is checked
+ * newest-first, and a newer version that was held back is reported on the
+ * upgrade rather than dropped. An import whose every newer version needs a newer
+ * telo produces a `skipped` entry instead, since the alternative — offering it
+ * anyway — is a manifest that fails at the load gate.
+ *
  * Skips what carries no upgradeable version: local path imports, bare URLs,
  * untagged refs, and pins that are not SemVer (an OCI digest, a moving tag like
  * `latest`) — `parseVersionedRef` and `isNewerModuleVersion` both decline to
@@ -133,7 +178,7 @@ export interface ImportUpgradeSet {
  */
 export async function buildImportUpgrades(
   text: string,
-  listVersions: ModuleVersionLookup,
+  env: ImportUpgradeEnvironment,
   docs?: AstDocument[],
 ): Promise<ImportUpgradeSet | undefined> {
   const lineOffsets = buildLineOffsets(text);
@@ -149,7 +194,7 @@ export async function buildImportUpgrades(
   const failures: Array<{ baseRef: string; message: string }> = [];
   const known = await resolveVersions(
     [...new Set(candidates.map((c) => c.ref.baseRef))],
-    listVersions,
+    env.listVersions,
     failures,
   );
 
@@ -160,7 +205,9 @@ export async function buildImportUpgrades(
   for (const { entry, ref } of candidates) {
     const versions = known.get(ref.baseRef);
     if (!versions) continue;
-    const newest = newestModuleVersion(versions.map((v) => v.version));
+    const newest = newestModuleVersion(versions.map((v) => v.version), {
+      includePrerelease: env.includePrerelease,
+    });
     if (!newest) continue;
 
     if (!isNewerModuleVersion(newest, ref.version)) {
@@ -169,7 +216,40 @@ export async function buildImportUpgrades(
       continue;
     }
 
-    const integrity = integrityFor(versions, newest);
+    // The target is the newest version this runtime can actually host, not
+    // simply the newest one published. An upgrade the author's telo cannot load
+    // is not an upgrade — it is a load failure they were walked into.
+    const { best, heldBack } = await selectCompatibleVersion(
+      ref.baseRef,
+      versions,
+      ref.version,
+      env.isCompatible,
+      { includePrerelease: env.includePrerelease },
+    );
+
+    // `heldBack` is non-null whenever a candidate existed, which `newest` being
+    // newer than the current version already established. Narrowed rather than
+    // defaulted: a reason nothing established is exactly what the four-verdict
+    // split exists to keep out of a message.
+    if (!best) {
+      if (!heldBack) continue;
+      skipped.push({
+        alias: entry.alias,
+        currentVersion: ref.version,
+        latestVersion: newest,
+        keyRange: entry.keyRange,
+        code: "incompatible",
+        reason: heldBack.reason,
+        message:
+          `'${entry.alias}' has newer versions (up to ${newest}), but none runs on telo ` +
+          `${TELO_SURFACE_VERSION} — ${describeReason(heldBack.reason)}. ` +
+          describeRemedy(heldBack.reason),
+      });
+      continue;
+    }
+
+    const target = best.version;
+    const integrity = integrityFor(versions, target);
     // A stale pin that can be neither replaced nor removed is the one case left
     // that has to be declined: re-pointing the source while leaving a hash for
     // the version it replaced turns the next install into a tamper error.
@@ -177,26 +257,28 @@ export async function buildImportUpgrades(
       skipped.push({
         alias: entry.alias,
         currentVersion: ref.version,
-        latestVersion: newest,
+        latestVersion: target,
         keyRange: entry.keyRange,
-        reason:
+        code: "stale-inline-pin",
+        message:
           `'${entry.alias}' carries an inline 'integrity:' that shares a line with other ` +
-          `fields, and no pin is published for ${newest}, so the stale one cannot be ` +
+          `fields, and no pin is published for ${target}, so the stale one cannot be ` +
           `removed by a line edit. Run \`telo upgrade\`.`,
       });
       continue;
     }
 
-    const newSource = withRefVersion(entry.source, newest);
+    const newSource = withRefVersion(entry.source, target);
     upgrades.push({
       alias: entry.alias,
       source: entry.source,
       currentVersion: ref.version,
-      latestVersion: newest,
+      latestVersion: target,
       newSource: foldIntegrity(newSource, integrity),
       wasPinned: ref.integrity != null,
       repinned: integrity != null,
       keyRange: entry.keyRange,
+      ...(heldBack ? { heldBack } : {}),
       edits: buildEdits(entry, newSource, integrity),
     });
   }
@@ -204,6 +286,28 @@ export async function buildImportUpgrades(
   return { importsKeyRange: block.keyRange, upgrades, pins, skipped, failures };
 }
 
+/** How a held-back version reads in a sentence, with the version itself as the
+ *  implied subject. Names the cause the check actually established.
+ *
+ *  The parameter is REQUIRED, so a caller cannot reach a sentence for a cause
+ *  nothing established — defaulting an absent reason to "requires a newer telo"
+ *  is precisely the invented verdict the four-way split exists to prevent. */
+export function describeReason(reason: IncompatibilityReason): string {
+  return reason === "unreadable"
+    ? "its declared requirement cannot be read"
+    : "it requires a newer telo";
+}
+
+/** What the author can do about it. Split from {@link describeReason} because
+ *  the two rejections have DIFFERENT remedies: an unreadable requirement is not
+ *  a version skew, so telling the author to update telo would send them after a
+ *  fix that cannot work — only the module's own author can repair it. */
+export function describeRemedy(reason: IncompatibilityReason): string {
+  return reason === "unreadable"
+    ? "Only the module's author can fix that."
+    : "Update telo to upgrade it.";
+}
+
 /** The edits that re-point an entry at `newSource` and settle its pin.
  *
  *  Where the pin is written follows the shape the author chose: an entry with an

package/src/import-upgrades/index.ts

@@ -1,13 +1,19 @@
-export { buildImportUpgrades } from "./build-import-upgrades.js";
+export {
+  buildImportUpgrades,
+  describeReason,
+  describeRemedy,
+} from "./build-import-upgrades.js";
 export type {
   ImportPin,
   ImportUpgrade,
   ImportUpgradeEdit,
+  ImportUpgradeEnvironment,
   ImportUpgradeSet,
   ImportUpgradeSkip,
   ModuleVersion,
   ModuleVersionLookup,
 } from "./build-import-upgrades.js";
+export { moduleManifestCacheUrl } from "./manifest-cache-url.js";
 export { parseModuleVersions } from "./parse-module-versions.js";
 export { findImportEntries } from "./find-import-entries.js";
 export type {
@@ -15,3 +21,18 @@ export type {
   ImportEntryIntegrity,
   ImportsBlock,
 } from "./find-import-entries.js";
+export {
+  createVersionCompatibility,
+  markVersionCompatibility,
+  noneRunnableReason,
+  selectCompatibleVersion,
+  uncheckedVersionCompatibility,
+} from "./version-compatibility.js";
+export type {
+  IncompatibilityReason,
+  MarkedVersion,
+  ModuleCompatibility,
+  ModuleManifestReader,
+  VersionCompatibilityCheck,
+  VersionSelection,
+} from "./version-compatibility.js";

package/src/import-upgrades/manifest-cache-url.ts

@@ -0,0 +1,40 @@
+import {
+  MANIFEST_CACHE_BASE_URL,
+  isOciRef,
+  manifestCacheUrl,
+  urlManifestCacheCoords,
+  withRefVersion,
+} from "@telorun/analyzer";
+
+/**
+ * Where one version of a module's `telo.yaml` can be read from the hub's static
+ * manifest cache, or `null` when this ref is not addressable there.
+ *
+ * This is the read path an upgrade check uses to ask a candidate version what
+ * runtime it requires: a plain CORS GET of a single small file, no transport
+ * protocol and no artifact payload, so it works identically from a browser and
+ * from an extension host. The `fetch` itself stays with the host — everything
+ * in this package leaves the network to its caller.
+ *
+ * A ref the cache cannot address (a registry ref, whose origin this side does
+ * not know; a URL with no version segment) returns `null`, which the caller
+ * reads as "not known" and never as "incompatible". Losing the check for those
+ * refs is the honest outcome: the manifest is still gated at load time.
+ */
+export function moduleManifestCacheUrl(
+  baseRef: string,
+  version: string,
+  baseUrl: string = MANIFEST_CACHE_BASE_URL,
+): string | null {
+  if (isOciRef(baseRef)) {
+    let versioned: string;
+    try {
+      versioned = withRefVersion(baseRef, version);
+    } catch {
+      return null;
+    }
+    return manifestCacheUrl(versioned, baseUrl);
+  }
+  const coords = urlManifestCacheCoords(baseRef, version);
+  return coords ? manifestCacheUrl(coords, baseUrl) : null;
+}

package/src/import-upgrades/version-compatibility.ts

@@ -0,0 +1,196 @@
+import {
+  TELO_SURFACE_VERSION,
+  compareModuleVersions,
+  isNewerModuleVersion,
+  manifestCompatibility,
+  parseModuleVersion,
+  type ModuleCompatibility,
+} from "@telorun/analyzer";
+import type { ModuleVersion } from "./build-import-upgrades.js";
+
+export type { ModuleCompatibility };
+
+/**
+ * Host capability: the `telo.yaml` text of one version of a module, or `null`
+ * when this host cannot address it (a transport it does not speak, a ref with
+ * no version segment). Rejecting is equally fine — both read as "not known",
+ * never as "incompatible".
+ *
+ * Narrow on purpose, and separate from {@link ModuleVersionLookup}: enumerating
+ * versions and reading one manifest are different routes with different costs,
+ * and a host caches or throttles them differently.
+ */
+export type ModuleManifestReader = (
+  baseRef: string,
+  version: string,
+) => Promise<string | null | undefined>;
+
+/** The question an upgrade asks of a candidate version. */
+export type VersionCompatibilityCheck = (
+  baseRef: string,
+  version: string,
+) => Promise<ModuleCompatibility>;
+
+/**
+ * A compatibility check backed by `read`, memoized per module and version for
+ * the lifetime of the returned function.
+ *
+ * The cache is not an optimization detail — an IDE re-derives its upgrade
+ * affordances on every keystroke, and a published version's declared
+ * requirement is immutable, so refetching it would be pure waste against an
+ * answer that cannot have changed. In-flight promises are shared, so the
+ * concurrent lookups one file's imports produce collapse to one read each.
+ *
+ * The verdict is always the analyzer's {@link manifestCompatibility}: an IDE
+ * reports NO host versions, because it is not the machine that will run the
+ * manifest. Only the telo surface is checked here; a host requirement still
+ * surfaces at the load gate when the manifest is actually run.
+ */
+export function createVersionCompatibility(
+  read: ModuleManifestReader,
+  teloVersion: string = TELO_SURFACE_VERSION,
+): VersionCompatibilityCheck {
+  const cache = new Map<string, Promise<ModuleCompatibility>>();
+  return (baseRef, version) => {
+    const key = `${baseRef}@${version}`;
+    const cached = cache.get(key);
+    if (cached) return cached;
+    const pending = read(baseRef, version)
+      .then((text) => (text ? manifestCompatibility(text, teloVersion) : "unknown"))
+      .catch(() => "unknown" as const);
+    cache.set(key, pending);
+    // Only a DECIDED verdict is kept. What is immutable is a published version's
+    // declared requirement, not the network: caching `unknown` would let one
+    // offline moment disable the check for the rest of the session, leaving the
+    // UI reading as though every version had been checked and cleared. Dropped
+    // after it settles rather than before, so concurrent asks still share the
+    // one in-flight read.
+    void pending.then((verdict) => {
+      if (verdict === "unknown" && cache.get(key) === pending) cache.delete(key);
+    });
+    return pending;
+  };
+}
+
+/** A check that answers `unknown` for everything — the honest reading for a
+ *  host with no way to fetch a candidate manifest. Never blocks an upgrade. */
+export const uncheckedVersionCompatibility: VersionCompatibilityCheck = async () => "unknown";
+
+/** Why a candidate was not offered. `unknown` never appears: a version that
+ *  could not be read is offered, since an unreachable source must not silently
+ *  freeze an author's imports. */
+export type IncompatibilityReason = Exclude<ModuleCompatibility, "yes" | "unknown">;
+
+export interface VersionSelection {
+  /** The newest version this runtime can host that is also newer than the
+   *  current one, or `null` when there is none. */
+  best: ModuleVersion | null;
+  /** The newest candidate overall, when it is NOT `best` — what was held back.
+   *  Reported rather than swallowed: without it an upgrade affordance says
+   *  "up to date" while newer versions exist, which is a silent ceiling and a
+   *  worse report than the load failure this whole check replaces. */
+  heldBack: { version: string; reason: IncompatibilityReason } | null;
+}
+
+/**
+ * The newest version whose declared requirement accepts this runtime, among
+ * those newer than `currentVersion`.
+ *
+ * Walks newest-first and stops at the first satisfied candidate, so the common
+ * case — the newest version is compatible — costs a single manifest read.
+ * Candidates older than the current version are never considered: an upgrade
+ * that walks backwards is a downgrade nobody asked for. Pass `null` for an
+ * import that does not exist yet, where every published version is a candidate
+ * and there is nothing to walk backwards from.
+ */
+export async function selectCompatibleVersion(
+  baseRef: string,
+  versions: readonly ModuleVersion[],
+  currentVersion: string | null,
+  isCompatible: VersionCompatibilityCheck,
+  options: { includePrerelease?: boolean } = {},
+): Promise<VersionSelection> {
+  const candidates = upgradeCandidates(versions, currentVersion, options);
+  if (candidates.length === 0) return { best: null, heldBack: null };
+
+  const newest = candidates[0]!;
+  let firstReason: IncompatibilityReason | null = null;
+  for (const candidate of candidates) {
+    const verdict = await isCompatible(baseRef, candidate.version);
+    if (verdict === "too-new" || verdict === "unreadable") {
+      firstReason ??= verdict;
+      continue;
+    }
+    const held = candidate === newest ? null : { version: newest.version, reason: firstReason! };
+    return { best: candidate, heldBack: held };
+  }
+  return { best: null, heldBack: { version: newest.version, reason: firstReason! } };
+}
+
+/** One version as a picker renders it: what it is, and what this runtime makes
+ *  of it. */
+export interface MarkedVersion extends ModuleVersion {
+  compatibility: ModuleCompatibility;
+}
+
+/**
+ * Every version, each carrying its own verdict — what a deliberate pick needs.
+ *
+ * Unlike {@link selectCompatibleVersion} this cannot short-circuit: a picker
+ * marks entries it is not going to choose, so every entry has to be asked. That
+ * is why the two are separate operations rather than one with a flag — the
+ * automatic path must stay one read, and the picker is an explicit action on a
+ * single import whose reads are cached from then on.
+ */
+export async function markVersionCompatibility(
+  baseRef: string,
+  versions: readonly ModuleVersion[],
+  isCompatible: VersionCompatibilityCheck,
+): Promise<MarkedVersion[]> {
+  return Promise.all(
+    versions.map(async (version) => ({
+      ...version,
+      compatibility: await isCompatible(baseRef, version.version),
+    })),
+  );
+}
+
+/**
+ * Why nothing in a marked list can be offered, or `null` when something can.
+ *
+ * A picker has to state this outright: a list where every row is marked
+ * explains nothing on its own, and the reader is left thinking the tool is
+ * broken. A reason rather than a boolean because the two rejections have
+ * different remedies — see {@link describeRemedy}. `unknown` counts as
+ * offerable: a version this host could not check is not one it may refuse.
+ */
+export function noneRunnableReason(
+  versions: readonly MarkedVersion[],
+): IncompatibilityReason | null {
+  if (versions.length === 0) return null;
+  if (versions.some((v) => v.compatibility === "yes" || v.compatibility === "unknown")) {
+    return null;
+  }
+  // The newest blocked version's reason, in the list's own (newest-first)
+  // order: it is the one the reader is asking about.
+  return versions[0]!.compatibility as IncompatibilityReason;
+}
+
+/** Candidates strictly newer than `currentVersion`, newest first.
+ *
+ *  Ordering and prerelease exclusion come from the analyzer's shared rule, so
+ *  "is this import behind" and "what would it move to" cannot disagree. */
+function upgradeCandidates(
+  versions: readonly ModuleVersion[],
+  currentVersion: string | null,
+  options: { includePrerelease?: boolean },
+): ModuleVersion[] {
+  return versions
+    .filter((v) => {
+      const parsed = parseModuleVersion(v.version);
+      if (parsed === null) return false;
+      if (parsed.pre !== null && !options.includePrerelease) return false;
+      return currentVersion === null || isNewerModuleVersion(v.version, currentVersion);
+    })
+    .sort((a, b) => compareModuleVersions(b.version, a.version) ?? 0);
+}