@telorun/ide-support 0.14.1 → 0.16.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":"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"}

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/dist/semantic-tokens/build-semantic-tokens.d.ts

@@ -1,12 +1,17 @@
-import { type AnalysisRegistry, type AstDocument } from "@telorun/analyzer";
+import { type AnalysisRegistry, type AstDocument, type ManifestAnalysis } from "@telorun/analyzer";
 import type { SemanticToken } from "../types.js";
 /** Registry-aware semantic tokens: a `kind:` value that resolves to a known
  *  definition is a `type`; a `capability:` value is an `interface`; a `!ref`
- *  target is a `variable`. Everything else (structure, CEL, tags) is left to the
- *  TextMate grammar. Ref targets are colored here rather than in the grammar
- *  because a `!ref` after a `key:` is tokenized by the bundled YAML grammar
- *  before a Telo pattern can claim it — the AST sees it unambiguously. An
- *  unresolved kind gets no token, so a typo stays uncolored — a quiet signal
- *  that pairs with the analyzer's `UNDEFINED_KIND` diagnostic. */
-export declare function buildSemanticTokens(text: string, registry: AnalysisRegistry | undefined, docs?: AstDocument[]): SemanticToken[];
+ *  target is a `variable`. Ref targets are colored here rather than in the
+ *  grammar because a `!ref` after a `key:` is tokenized by the bundled YAML
+ *  grammar before a Telo pattern can claim it — the AST sees it unambiguously.
+ *  An unresolved kind gets no token, so a typo stays uncolored — a quiet signal
+ *  that pairs with the analyzer's `UNDEFINED_KIND` diagnostic.
+ *
+ *  The inside of a `!cel` / `${{ }}` body is colored here too, and for the same
+ *  reason one level down: a grammar can only know the roots someone hardcoded
+ *  into it, while `scopeQuery` knows what is in scope at this exact site. With
+ *  no query the names are colored syntactically instead — a CEL body must never
+ *  read as a plain string, which is what the stock YAML grammar makes of it. */
+export declare function buildSemanticTokens(text: string, registry: AnalysisRegistry | undefined, docs?: AstDocument[], analysis?: ManifestAnalysis): SemanticToken[];
 //# sourceMappingURL=build-semantic-tokens.d.ts.map

package/dist/semantic-tokens/build-semantic-tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-semantic-tokens.d.ts","sourceRoot":"","sources":["../../src/semantic-tokens/build-semantic-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD;;;;;;;kEAOkE;AAClE,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,IAAI,CAAC,EAAE,WAAW,EAAE,GACnB,aAAa,EAAE,CAqCjB"}
+{"version":3,"file":"build-semantic-tokens.d.ts","sourceRoot":"","sources":["../../src/semantic-tokens/build-semantic-tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAIhB,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAajD;;;;;;;;;;;;gFAYgF;AAChF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,IAAI,CAAC,EAAE,WAAW,EAAE,EACpB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,aAAa,EAAE,CA2EjB"}