@telorun/ide-support 0.14.1 → 0.16.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);
+}

package/src/semantic-tokens/build-semantic-tokens.ts

@@ -5,60 +5,114 @@ import {
   type AnalysisRegistry,
   type AstDocument,
   type AstNode,
+  type AstScalar,
+  type CelScope,
+  type ManifestAnalysis,
 } from "@telorun/analyzer";
 import type { SemanticToken } from "../types.js";
+import { celSegmentTokens } from "../cel/tokens.js";
+import { docIdentity } from "../doc-identity.js";
 import { scalarString } from "../completions/resolve-node.js";
 import { CAPABILITY_VALUES } from "../completions/valid-capabilities.js";
 
 const CAPABILITIES = new Set<string>(CAPABILITY_VALUES);
 
+/** Append one key segment to a concrete path (`routes[0]` + `handler`). */
+function joinKey(concrete: string, key: string): string {
+  return concrete ? `${concrete}.${key}` : key;
+}
+
 /** 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. */
+ *  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 function buildSemanticTokens(
   text: string,
   registry: AnalysisRegistry | undefined,
   docs?: AstDocument[],
+  analysis?: ManifestAnalysis,
 ): SemanticToken[] {
   const astDocs = docs ?? parseToAst(text);
   const lineOffsets = buildLineOffsets(text);
 
   const tokens: SemanticToken[] = [];
-  const emit = (node: AstNode | undefined, type: SemanticToken["type"]): void => {
-    if (!node) return;
-    const start = offsetToPosition(node.range[0], lineOffsets);
-    const end = offsetToPosition(node.range[1], lineOffsets);
-    // Kind / capability values never span lines; a clamped single-line token.
+  const emitRange = (range: [number, number], type: SemanticToken["type"]): void => {
+    const start = offsetToPosition(range[0], lineOffsets);
+    const end = offsetToPosition(range[1], lineOffsets);
+    // Kind / capability values and CEL identifiers never span lines; a clamped
+    // single-line token.
     if (start.line !== end.line) return;
-    tokens.push({ line: start.line, character: start.character, length: end.character - start.character, type });
+    tokens.push({
+      line: start.line,
+      character: start.character,
+      length: end.character - start.character,
+      type,
+    });
+  };
+  const emit = (node: AstNode | undefined, type: SemanticToken["type"]): void => {
+    if (node) emitRange(node.range, type);
   };
 
-  const walk = (node: AstNode): void => {
-    if (node.kind === "map") {
-      for (const pair of node.entries) {
-        const key = scalarString(pair.key);
-        const value = scalarString(pair.value);
-        if (key === "kind" && value && registry?.resolveDefinition(value)) {
-          emit(pair.value, "type");
-        } else if (key === "capability" && value && CAPABILITIES.has(value)) {
-          emit(pair.value, "interface");
+  for (const doc of astDocs) {
+    if (!doc.root) continue;
+
+    // The scope is resolved per SITE. `scopeAt` caches per (resource, path) for
+    // the analysis's lifetime, which is what keeps a whole-file colourizer off
+    // the per-keystroke cost of rebuilding a context-matched environment.
+    const identity = docIdentity(doc);
+    const scopeQuery = analysis?.celScope;
+    const resource = scopeQuery?.resourceFor(identity.kind, identity.name);
+    const scopeAt = (path: string): CelScope | undefined =>
+      scopeQuery && resource ? scopeQuery.scopeAt(resource, path) : undefined;
+
+    const celTokens = (node: AstScalar, path: string): void => {
+      const segments = node.celSegments();
+      if (segments.length === 0) return;
+      const scope = scopeAt(path);
+      for (const segment of segments) {
+        for (const span of celSegmentTokens(text, segment, scope)) emitRange(span.range, span.type);
+      }
+    };
+
+    const walk = (node: AstNode, concrete: string): void => {
+      if (node.kind === "map") {
+        for (const pair of node.entries) {
+          const key = scalarString(pair.key);
+          const value = scalarString(pair.value);
+          if (key === "kind" && value && registry?.resolveDefinition(value)) {
+            emit(pair.value, "type");
+          } else if (key === "capability" && value && CAPABILITIES.has(value)) {
+            emit(pair.value, "interface");
+          }
+          if (pair.value) walk(pair.value, key != null ? joinKey(concrete, key) : concrete);
         }
-        if (pair.value) walk(pair.value);
+        return;
       }
-    } else if (node.kind === "seq") {
-      for (const item of node.items) walk(item);
-    } else if (node.kind === "scalar" && node.tag === "!ref") {
-      emit(node, "variable");
-    }
-  };
+      if (node.kind === "seq") {
+        // Indices are kept: a CEL site's scope is addressed per item, so an
+        // index-erased path resolves the wrong context or none.
+        node.items.forEach((item, index) => walk(item, `${concrete}[${index}]`));
+        return;
+      }
+      if (node.kind === "scalar") {
+        if (node.tag === "!ref") {
+          emit(node, "variable");
+          return;
+        }
+        celTokens(node, concrete);
+      }
+    };
 
-  for (const doc of astDocs) {
-    if (doc.root) walk(doc.root);
+    walk(doc.root, "");
   }
   return tokens;
 }