@telorun/ide-support 0.15.0 → 0.16.1

package/src/completions/detect-context.ts

@@ -1,4 +1,10 @@
-import { parseToAst, readRefSlot, refSlotAnnotation, type AstDocument } from "@telorun/analyzer";
+import {
+  parseToAst,
+  readRefSlot,
+  refSlotAnnotation,
+  type AstDocument,
+  type CelSegment,
+} from "@telorun/analyzer";
 import type { ReplaceRange } from "../types.js";
 import { resolveNodeAtPosition } from "./resolve-node.js";
 
@@ -19,7 +25,17 @@ export type CompletionCtx =
       replaceRange: ReplaceRange;
     }
   | { type: "capability" }
-  | { type: "prop-key"; docKind: string; yamlPath: string[]; existingKeys: Set<string> }
+  | {
+      type: "prop-key";
+      docKind: string;
+      yamlPath: string[];
+      /** The same location with sequence indices kept, so a caller can find the
+       *  manifest node this slot sits in — what resolving an enclosing call's
+       *  reference needs. */
+      concretePath: string;
+      docIndex: number;
+      existingKeys: Set<string>;
+    }
   | {
       /** Cursor sits on the value of an object-form ref's `name:` field
        *  (e.g. `connection: { kind: Sql.Connection, name: |}`). Editor hosts
@@ -43,6 +59,35 @@ export type CompletionCtx =
       prefix: string;
       /** Full source range of the value being completed. */
       replaceRange: ReplaceRange;
+    }
+  | {
+      /** Cursor sits on an ordinary field VALUE whose schema declares the values
+       *  it may take — `enum` (closed) or `examples` (open). Untargeted on
+       *  purpose: every value slot resolves here and the ones declaring neither
+       *  simply offer nothing. */
+      type: "value-suggestions";
+      docKind: string;
+      /** Path from the document root to the field, so its schema can be found. */
+      yamlPath: string[];
+      replaceRange: ReplaceRange;
+    }
+  | {
+      /** Cursor sits inside a CEL body — closed or still open (`!cel "req.|`).
+       *  What completes is decided by the scope the analyzer resolves for this
+       *  site, so the host must supply a `CelScopeQuery`; without one the
+       *  candidate list would be a guess rather than a claim about what
+       *  `telo check` accepts, and nothing is offered. */
+      type: "cel";
+      docKind?: string;
+      /** Which `---` document the cursor is in, so the host can name the
+       *  resource this expression belongs to. */
+      docIndex: number;
+      /** The site's address with sequence indices kept — what the scope is
+       *  resolved at. */
+      concretePath: string;
+      segment: CelSegment;
+      /** Cursor as a document offset. */
+      offset: number;
     };
 
 /** Returns every schema branch reachable from `node` after peeling `anyOf` /
@@ -116,19 +161,52 @@ function resolveLocalRef(
   return current;
 }
 
+/**
+ * Resolves an `x-telo-schema-from` annotation to the schema it derives. Supplied
+ * by the caller because the anchor is alias-qualified and only the registry can
+ * resolve it in the declaring kind's module scope.
+ */
+export type SchemaFromResolver = (schemaFrom: string) => Record<string, any> | undefined;
+
+/**
+ * Expand a node whose shape comes from a sibling kind's schema.
+ *
+ * A slot annotated `x-telo-schema-from` declares NO `properties` of its own — an
+ * `Http.Api` route's `request:` is exactly this — so every walk that reads
+ * `properties` finds an empty node and silently offers nothing. The derived
+ * schema is merged UNDER whatever the slot itself declared, so a slot that adds
+ * a title or narrows a field keeps winning.
+ */
+function resolveSchemaFrom(
+  node: Record<string, any> | undefined,
+  resolve: SchemaFromResolver | undefined,
+): Record<string, any> | undefined {
+  const from = node?.["x-telo-schema-from"];
+  if (!node || !resolve || typeof from !== "string") return node;
+  const derived = resolve(from);
+  if (!derived) return node;
+  return {
+    ...derived,
+    ...node,
+    properties: { ...(derived.properties ?? {}), ...(node.properties ?? {}) },
+  };
+}
+
 /** Navigate a JSON Schema hierarchy following `path`, auto-descending into
- *  array items, peeling `anyOf` / `oneOf` branches and following document-local
- *  `$ref`s. When multiple peeled branches define `properties`, returns a
- *  synthetic node whose `properties` is the union (first-wins on key collision)
- *  and whose `required` is the intersection — enough for propKeyCompletions to
- *  surface every key a value at this slot can legally carry. */
+ *  array items, peeling `anyOf` / `oneOf` branches, following document-local
+ *  `$ref`s and expanding `x-telo-schema-from` slots. When multiple peeled
+ *  branches define `properties`, returns a synthetic node whose `properties` is
+ *  the union (first-wins on key collision) and whose `required` is the
+ *  intersection — enough for propKeyCompletions to surface every key a value at
+ *  this slot can legally carry. */
 export function navigateSchema(
   schema: Record<string, any>,
   path: string[],
+  schemaFrom?: SchemaFromResolver,
 ): Record<string, any> | undefined {
   let current: Record<string, any> | undefined = schema;
   for (const segment of path) {
-    current = resolveLocalRef(current, schema);
+    current = resolveSchemaFrom(resolveLocalRef(current, schema), schemaFrom);
     if (!current) return undefined;
     const candidates = peelCombinators(current).flatMap((node) => {
       const expanded: Record<string, any>[] = [];
@@ -161,7 +239,7 @@ export function navigateSchema(
     if (!next) return undefined;
     current = next;
   }
-  current = resolveLocalRef(current, schema);
+  current = resolveSchemaFrom(resolveLocalRef(current, schema), schemaFrom);
   if (!current) return undefined;
   // Auto-descend through a trailing array at the leaf (e.g. cursor inside `mounts:` items)
   while (current.type === "array" && current.items) {
@@ -227,8 +305,9 @@ function unionLeaves(
 export function lookupRefConstraints(
   definitionSchema: Record<string, any>,
   yamlPath: string[],
+  schemaFrom?: SchemaFromResolver,
 ): string[] {
-  const node = navigateSchema(definitionSchema, yamlPath);
+  const node = navigateSchema(definitionSchema, yamlPath, schemaFrom);
   if (!node) return [];
   return readRefSlot(node)?.kinds ?? [];
 }
@@ -249,9 +328,18 @@ export function detectContext(
   const { docKind } = resolved;
 
   if (resolved.slot === "value") {
-    // Inside a CEL body — structural completion does not apply (a future
-    // CEL-completion feature consumes `resolved.cel`).
-    if (resolved.cel) return undefined;
+    // Inside a CEL body — structural completion does not apply; what completes
+    // are the names the expression may use.
+    if (resolved.cel) {
+      return {
+        type: "cel",
+        docKind,
+        docIndex: resolved.docIndex,
+        concretePath: resolved.concretePath ?? "",
+        segment: resolved.cel.segment,
+        offset: resolved.cel.offset,
+      };
+    }
     const replaceRange = resolved.replaceRange;
     if (!replaceRange) return undefined;
     const key = resolved.path[resolved.path.length - 1];
@@ -297,6 +385,10 @@ export function detectContext(
       }
     }
 
+    if (docKind) {
+      return { type: "value-suggestions", docKind, yamlPath: resolved.path, replaceRange };
+    }
+
     return undefined;
   }
 
@@ -311,6 +403,8 @@ export function detectContext(
     type: "prop-key",
     docKind: scopeKind,
     yamlPath: resolved.path.slice(resolved.resourceDepth ?? 0),
+    concretePath: resolved.concretePath ?? "",
+    docIndex: resolved.docIndex,
     existingKeys: resolved.existingKeys ?? new Set<string>(),
   };
 }

package/src/completions/prop-keys.ts

@@ -25,7 +25,18 @@ export function propKeyCompletions(
   yamlPath: string[],
   existingKeys: Set<string>,
   registry: AnalysisRegistry | undefined,
+  /** The arguments the enclosing call declares, when this path IS that call's
+   *  argument slot. Resolved by the caller, which is the side holding the
+   *  manifest the reference names. */
+  callInputs?: Record<string, any>,
 ): CompletionResult[] {
+  if (callInputs?.properties) {
+    return buildItems(
+      callInputs.properties as Record<string, any>,
+      existingKeys,
+      new Set<string>(Array.isArray(callInputs.required) ? callInputs.required : []),
+    );
+  }
   if (!registry) return [];
 
   const definition = registry.resolveDefinition(kind);
@@ -41,9 +52,20 @@ export function propKeyCompletions(
 
   const targetSchema = yamlPath.length === 0
     ? (definition.schema as Record<string, any>)
-    : navigateSchema(definition.schema as Record<string, any>, yamlPath);
+    : navigateSchema(definition.schema as Record<string, any>, yamlPath, (from) =>
+        registry.resolveSchemaFrom(from, kind),
+      );
+
+  // A NAME-KEYED map declares its keys nowhere in `properties` — they are the
+  // author's own (a media type, a header name). `propertyNames` is JSON
+  // Schema's own vocabulary for what they may be, and it carries the open/closed
+  // distinction already: `enum` constrains, `examples` only suggests. So an open
+  // list of known values needs no annotation and no analyzer-side knowledge of
+  // any domain.
+  const keySuggestions = propertyNameSuggestions(targetSchema, existingKeys);
 
   if (!targetSchema?.properties) {
+    if (keySuggestions.length > 0) return keySuggestions;
     if (yamlPath.length === 0) {
       return buildItems(ROOT_IMPLICIT_PROPS, existingKeys, new Set<string>());
     }
@@ -58,7 +80,42 @@ export function propKeyCompletions(
       ? { ...ROOT_IMPLICIT_PROPS, ...(targetSchema.properties as Record<string, any>) }
       : { ...(targetSchema.properties as Record<string, any>), ...annotationKeys(targetSchema) };
 
-  return buildItems(properties, existingKeys, required);
+  return [...keySuggestions, ...buildItems(properties, existingKeys, required)];
+}
+
+/**
+ * Key candidates a map-valued node declares through `propertyNames`.
+ *
+ * `enum` is a closed set and `examples` an open one — suggestions with no
+ * validation effect, which is exactly "these are the known values, others are
+ * allowed". Both are stock JSON Schema, so nothing here knows what a media type
+ * is and any name-keyed field gains the same behaviour by declaring it.
+ */
+function propertyNameSuggestions(
+  schema: Record<string, any> | undefined,
+  existingKeys: Set<string>,
+): CompletionResult[] {
+  const names = schema?.propertyNames as Record<string, any> | undefined;
+  if (!names || typeof names !== "object") return [];
+  const closed = Array.isArray(names.enum) ? (names.enum as unknown[]) : undefined;
+  const open = Array.isArray(names.examples) ? (names.examples as unknown[]) : [];
+  const values = closed ?? open;
+
+  const out: CompletionResult[] = [];
+  for (const value of values) {
+    if (typeof value !== "string" || existingKeys.has(value)) continue;
+    out.push({
+      label: value,
+      kind: "enumMember",
+      insertText: `${value}: $0`,
+      snippet: true,
+      detail: closed ? names.title ?? "allowed key" : names.title ?? "known key",
+      // Ahead of any structural key at the same level: at a name-keyed slot the
+      // author is choosing one of these, not adding a sibling field.
+      sortText: `0_${value}`,
+    });
+  }
+  return out;
 }
 
 /**

package/src/completions/resolve-node.ts

@@ -48,8 +48,15 @@ export interface ResolvedCursor {
   /** Key slot: number of `path` segments that reach `resourceKind`'s map, so
    *  the schema-relative path is `path.slice(resourceDepth)`. */
   resourceDepth?: number;
-  /** Set when the cursor sits inside a CEL body (closed or open). Populated for
-   *  a future CEL-completion feature; this refactor does not consume it. */
+  /** The path with sequence INDICES kept (`routes[0].handler.url`),
+   *  as distinct from `path`, through which arrays are transparent. This is the
+   *  address the analyzer speaks — an `x-telo-context` scope, an error-bearing
+   *  region and a step's identity are all resolved per item — so it is what a
+   *  CEL site is looked up by. */
+  concretePath?: string;
+  /** Set when the cursor sits inside a CEL body (closed or open). The CEL
+   *  segment plus the cursor's document offset — what completion and hover
+   *  hit-test the expression's chain against. */
   cel?: { segment: CelSegment; offset: number };
 }
 
@@ -109,6 +116,7 @@ type Descent =
       type: "key";
       container: AstMap;
       path: string[];
+      concretePath: string;
       keyNode: AstScalar;
       keyName?: string;
       scope: ResourceScope;
@@ -119,15 +127,22 @@ type Descent =
        *  (which has no keyed siblings). */
       container: AstMap | undefined;
       path: string[];
+      concretePath: string;
       keyName?: string;
       keyEnd: number;
       valueNode: AstNode;
     }
   | { type: "empty" };
 
+/** Append one key segment to a concrete path (`routes[0]` + `handler`). */
+function joinKey(concrete: string, key: string): string {
+  return concrete ? `${concrete}.${key}` : key;
+}
+
 function descend(
   node: AstNode,
   ancestors: string[],
+  concrete: string,
   offset: number,
   scope: ResourceScope,
 ): Descent | undefined {
@@ -140,6 +155,7 @@ function descend(
           type: "key",
           container: node,
           path: ancestors,
+          concretePath: concrete,
           keyNode: pair.key as AstScalar,
           keyName,
           scope: mapScope,
@@ -147,13 +163,15 @@ function descend(
       }
       if (pair.value && within(pair.value.range, offset)) {
         const childAncestors = keyName != null ? [...ancestors, keyName] : ancestors;
+        const childConcrete = keyName != null ? joinKey(concrete, keyName) : concrete;
         if (pair.value.kind === "map" || pair.value.kind === "seq") {
-          return descend(pair.value, childAncestors, offset, mapScope) ?? { type: "empty" };
+          return descend(pair.value, childAncestors, childConcrete, offset, mapScope) ?? { type: "empty" };
         }
         return {
           type: "value",
           container: node,
           path: ancestors,
+          concretePath: childConcrete,
           keyName,
           keyEnd: pair.key.range[1],
           valueNode: pair.value,
@@ -164,16 +182,26 @@ function descend(
   }
   if (node.kind === "seq") {
     // Sequence items are transparent to the key path (mirrors the schema
-    // walker, which auto-descends arrays).
-    for (const item of node.items) {
+    // walker, which auto-descends arrays) but NOT to the concrete path: an
+    // `x-telo-context` scope, an error-bearing region and a step's identity are
+    // all addressed per item, so a CEL site is unreachable without the index.
+    for (const [index, item] of node.items.entries()) {
       if (within(item.range, offset)) {
+        const itemConcrete = `${concrete}[${index}]`;
         if (item.kind === "map" || item.kind === "seq") {
-          return descend(item, ancestors, offset, scope) ?? { type: "empty" };
+          return descend(item, ancestors, itemConcrete, offset, scope) ?? { type: "empty" };
         }
         // A bare scalar list item (`targets:\n  - One`) has no enclosing map of
         // keyed siblings — leave `container` undefined rather than treating the
         // seq as a map.
-        return { type: "value", container: undefined, path: ancestors, keyEnd: item.range[0], valueNode: item };
+        return {
+          type: "value",
+          container: undefined,
+          path: ancestors,
+          concretePath: itemConcrete,
+          keyEnd: item.range[0],
+          valueNode: item,
+        };
       }
     }
     return undefined;
@@ -187,6 +215,9 @@ function descend(
 
 interface MapScope {
   path: string[];
+  /** The same location with sequence indices kept — what addresses a manifest
+   *  node, as distinct from `path`, which addresses a schema node. */
+  concrete: string;
   childColumn: number;
   keys: Set<string>;
   rangeStart: number;
@@ -195,6 +226,7 @@ interface MapScope {
 
 interface PairScope {
   path: string[]; // full key path to this pair
+  concrete: string;
   keyColumn: number;
   keyOffset: number;
   childKeys: Set<string>;
@@ -204,6 +236,7 @@ interface PairScope {
 function collectScopes(
   node: AstNode,
   ancestors: string[],
+  concrete: string,
   scope: ResourceScope,
   lineOffsets: number[],
   maps: MapScope[],
@@ -219,11 +252,19 @@ function collectScopes(
       if (childColumn < 0) childColumn = offsetToPosition(pair.key.range[0], lineOffsets).character;
     }
     if (childColumn >= 0) {
-      maps.push({ path: ancestors, childColumn, keys, rangeStart: node.range[0], scope: mapScope });
+      maps.push({
+        path: ancestors,
+        concrete,
+        childColumn,
+        keys,
+        rangeStart: node.range[0],
+        scope: mapScope,
+      });
     }
     for (const pair of node.entries) {
       const keyName = scalarString(pair.key);
       const fullPath = keyName != null ? [...ancestors, keyName] : ancestors;
+      const fullConcrete = keyName != null ? joinKey(concrete, keyName) : concrete;
       const childKeys = new Set<string>();
       if (pair.value?.kind === "map") {
         for (const p of pair.value.entries) {
@@ -233,20 +274,26 @@ function collectScopes(
       }
       pairs.push({
         path: fullPath,
+        concrete: fullConcrete,
         keyColumn: offsetToPosition(pair.key.range[0], lineOffsets).character,
         keyOffset: pair.key.range[0],
         childKeys,
         scope: mapScope,
       });
-      if (pair.value) collectScopes(pair.value, fullPath, mapScope, lineOffsets, maps, pairs);
+      if (pair.value) {
+        collectScopes(pair.value, fullPath, fullConcrete, mapScope, lineOffsets, maps, pairs);
+      }
     }
   } else if (node.kind === "seq") {
-    for (const item of node.items) collectScopes(item, ancestors, scope, lineOffsets, maps, pairs);
+    node.items.forEach((item, index) =>
+      collectScopes(item, ancestors, `${concrete}[${index}]`, scope, lineOffsets, maps, pairs),
+    );
   }
 }
 
 interface KeyResolution {
   path: string[];
+  concrete: string;
   existingKeys: Set<string>;
   scope: ResourceScope;
 }
@@ -262,7 +309,7 @@ function columnSearch(
 ): KeyResolution {
   const maps: MapScope[] = [];
   const pairs: PairScope[] = [];
-  collectScopes(root, [], { depth: 0 }, lineOffsets, maps, pairs);
+  collectScopes(root, [], "", { depth: 0 }, lineOffsets, maps, pairs);
 
   // Sibling level: a map whose children already sit at the cursor's column.
   let sibling: MapScope | undefined;
@@ -271,7 +318,14 @@ function columnSearch(
       if (!sibling || m.rangeStart > sibling.rangeStart) sibling = m;
     }
   }
-  if (sibling) return { path: sibling.path, existingKeys: sibling.keys, scope: sibling.scope };
+  if (sibling) {
+    return {
+      path: sibling.path,
+      concrete: sibling.concrete,
+      existingKeys: sibling.keys,
+      scope: sibling.scope,
+    };
+  }
 
   // Nest under the nearest-preceding key shallower than the cursor.
   let nest: PairScope | undefined;
@@ -286,9 +340,16 @@ function columnSearch(
       }
     }
   }
-  if (nest) return { path: nest.path, existingKeys: nest.childKeys, scope: nest.scope };
+  if (nest) {
+    return {
+      path: nest.path,
+      concrete: nest.concrete,
+      existingKeys: nest.childKeys,
+      scope: nest.scope,
+    };
+  }
 
-  return { path: [], existingKeys: new Set(), scope: { depth: 0 } };
+  return { path: [], concrete: "", existingKeys: new Set(), scope: { depth: 0 } };
 }
 
 // ---------------------------------------------------------------------------
@@ -326,7 +387,7 @@ export function resolveNodeAtPosition(
   const doc = docs[docIndex];
   const docKind = docKindOf(doc);
 
-  const found = doc.root ? descend(doc.root, [], offset, { depth: 0 }) : undefined;
+  const found = doc.root ? descend(doc.root, [], "", offset, { depth: 0 }) : undefined;
 
   // Cursor sits on an existing map key → key/prop-key position.
   if (found?.type === "key") {
@@ -341,6 +402,7 @@ export function resolveNodeAtPosition(
       docKind,
       slot: "key",
       path: found.path,
+      concretePath: found.concretePath,
       node: found.keyNode,
       replaceRange: { start: toPos(found.keyNode.range[0]), end: toPos(found.keyNode.range[1]) },
       container: found.container,
@@ -365,13 +427,14 @@ export function resolveNodeAtPosition(
       toPos(value.range[0]).line !== toPos(found.keyEnd).line;
     if (isPartialKey && doc.root) {
       const col = toPos(value.range[0]).character;
-      const { path, existingKeys, scope } = columnSearch(doc.root, col, offset, lineOffsets);
+      const { path, concrete, existingKeys, scope } = columnSearch(doc.root, col, offset, lineOffsets);
       return {
         docIndex,
         offset,
         docKind,
         slot: "key",
         path,
+        concretePath: concrete,
         container: found.container,
         existingKeys,
         resourceKind: scope.kind,
@@ -386,6 +449,7 @@ export function resolveNodeAtPosition(
       docKind,
       slot: "value",
       path: found.keyName != null ? [...found.path, found.keyName] : found.path,
+      concretePath: found.concretePath,
       node: value,
       container: found.container,
       prefix: text.slice(value.range[0], clampedEnd),
@@ -400,13 +464,14 @@ export function resolveNodeAtPosition(
   // resolved by cursor column.
   const resolution: KeyResolution = doc.root
     ? columnSearch(doc.root, character, offset, lineOffsets)
-    : { path: [], existingKeys: new Set<string>(), scope: { depth: 0 } };
+    : { path: [], concrete: "", existingKeys: new Set<string>(), scope: { depth: 0 } };
   return {
     docIndex,
     offset,
     docKind,
     slot: "key",
     path: resolution.path,
+    concretePath: resolution.concrete,
     existingKeys: resolution.existingKeys,
     resourceKind: resolution.scope.kind,
     resourceDepth: resolution.scope.depth,

package/src/completions/valid-capabilities.ts

@@ -10,7 +10,7 @@ export const CAPABILITY_VALUES = [
 /** One-line role summary per capability, surfaced on hover. Kept in sync with
  *  the capability list in `CLAUDE.md` / the kernel builtins. */
 export const CAPABILITY_DOCS: Record<string, string> = {
-  "Telo.Service": "Long-lived resource: `init()` + optional `teardown()` (servers, pools).",
+  "Telo.Service": "Long-lived resource: `init()` + `run()`, returning what undoes them (servers, pools).",
   "Telo.Runnable": "One-shot task: `run()` (pipelines, boot steps).",
   "Telo.Invocable": "Request handler: `invoke(inputs)` (scripts, endpoints).",
   "Telo.Provider": "Value-flow source: `init()` + optional `provide()` (config, secrets).",

package/src/definition/build-definition.ts

@@ -1,7 +1,15 @@
-import { parseToAst, type AstDocument, type AstScalar, type LoadedGraph } from "@telorun/analyzer";
+import {
+  parseToAst,
+  type AstDocument,
+  type AstScalar,
+  type ManifestAnalysis,
+  type LoadedGraph,
+} from "@telorun/analyzer";
 import type { DefinitionResult } from "../types.js";
 import { resolveNodeAtPosition } from "../completions/resolve-node.js";
 import { splitAliasQualified } from "./alias-qualified-value.js";
+import { locateContextBinding } from "./locate-context-binding.js";
+import { locateStepDeclaration } from "./locate-step.js";
 import { moduleForFile } from "./manifest-navigation.js";
 import { resolveCelTarget } from "./resolve-cel-target.js";
 import { isKindSlot, resolveKindTarget } from "./resolve-kind-target.js";
@@ -30,6 +38,10 @@ export function buildDefinition(
   graph: LoadedGraph,
   currentFilePath: string,
   docs?: AstDocument[],
+  /** Lets a `steps.<name>` read navigate to the step that produced it, and a
+   *  context binding to its declaration — both need the declaring kind's own
+   *  annotations, which only the analysis can read. */
+  analysis?: ManifestAnalysis,
 ): DefinitionResult | undefined {
   const astDocs = docs ?? parseToAst(text);
   const resolved = resolveNodeAtPosition(text, astDocs, line, character);
@@ -38,7 +50,23 @@ export function buildDefinition(
   const currentModule = moduleForFile(graph, currentFilePath) ?? graph.entry;
 
   if (resolved.cel) {
-    return resolveCelTarget(graph, currentModule, resolved.cel.segment, resolved.cel.offset);
+    return resolveCelTarget(graph, currentModule, resolved.cel.segment, resolved.cel.offset, {
+      // A step is resolved in the CURRENT document — `steps.<name>.result` is
+      // readable only inside the resource that declares it, which is one
+      // document. Supplied as a closure so the chain resolver stays free of the
+      // AST and the scope query alike.
+      locateStep: (stepName) =>
+        locateStepDeclaration(graph, currentFilePath, astDocs, resolved.docIndex, stepName, analysis?.celScope),
+      locateContextBinding: (parts) =>
+        locateContextBinding(
+          graph,
+          astDocs,
+          resolved.docIndex,
+          resolved.concretePath ?? "",
+          parts,
+          analysis?.celScope,
+        ),
+    });
   }
 
   const node = resolved.node;

package/src/definition/locate-context-binding.ts

@@ -0,0 +1,53 @@
+/**
+ * Where a CEL context binding was declared.
+ *
+ * `request.query` is written in the route's own `request.schema`, `self.<field>`
+ * in the definition's `schema`, `result.<field>` in the INVOKED resource's
+ * `outputType` — each derived by an `x-telo-context-*` annotation rather than
+ * reached through a reference slot, so none of them is navigable by the graph
+ * walk the other CEL roots use. The scope query resolves the annotation to a
+ * manifest identity plus a path; locating that path in the loaded files is what
+ * this adds.
+ */
+import type { AstDocument, CelScopeQuery, LoadedFile, LoadedGraph } from "@telorun/analyzer";
+import type { DefinitionResult } from "../types.js";
+import { docIdentity } from "../doc-identity.js";
+
+/** Every file of every module in the graph — a binding's declaration may sit in
+ *  another module (an invoked handler's `outputType`), so the search is not
+ *  confined to the current file. */
+function allFiles(graph: LoadedGraph): LoadedFile[] {
+  const out: LoadedFile[] = [];
+  for (const mod of graph.modules.values()) out.push(mod.owner, ...mod.partials);
+  return out;
+}
+
+export function locateContextBinding(
+  graph: LoadedGraph,
+  docs: AstDocument[],
+  docIndex: number,
+  sitePath: string,
+  parts: string[],
+  scopeQuery: CelScopeQuery | undefined,
+): DefinitionResult | undefined {
+  if (!scopeQuery) return undefined;
+  const identity = docIdentity(docs[docIndex]);
+  const resource = scopeQuery.resourceFor(identity.kind, identity.name);
+  if (!resource) return undefined;
+
+  const site = scopeQuery.contextDeclarationSite(resource, sitePath, parts);
+  if (!site) return undefined;
+
+  for (const file of allFiles(graph)) {
+    for (let i = 0; i < file.manifests.length; i++) {
+      const manifest = file.manifests[i] as { kind?: string; metadata?: { name?: string } } | null;
+      if (manifest?.kind !== site.kind || manifest.metadata?.name !== site.name) continue;
+      const index = file.positions[i]?.positionIndex;
+      // The KEY span, so the jump underlines `query:` rather than the block that
+      // follows it — a declaration, not a selection.
+      const range = index?.get(`@key:${site.path}`) ?? index?.get(site.path);
+      if (range) return { uri: file.source, range };
+    }
+  }
+  return undefined;
+}