@telorun/analyzer 0.65.0 → 0.67.0

package/src/call-graph.ts

@@ -284,7 +284,13 @@ function resolveUseAtSite(
     const resolved = entry.useCases.cases[String(selector)];
     if (resolved) return { use: resolved };
   }
-  const slot = { kinds: entry.refs, uses: entry.uses, useCases: entry.useCases, inline: false };
+  const slot = {
+    kinds: entry.refs,
+    uses: entry.uses,
+    useCases: entry.useCases,
+    inline: false,
+    valueBranches: [],
+  };
   const unresolvedReason = isTaggedSentinel(selector)
     ? "dynamic"
     : selector === undefined

package/src/cel-environment.ts

@@ -47,24 +47,34 @@ export function buildTypedCelEnvironment(
       (env as any).registerType(brand, { fields: {} });
     }
 
-    // Build typed ObjectSchema from manifest.variables if it looks like a schema map
-    const vars = (manifest as Record<string, unknown>).variables;
-    if (vars !== null && typeof vars === "object" && !Array.isArray(vars)) {
-      const entries = Object.entries(vars as Record<string, unknown>).filter(
-        ([, v]) => v !== null && typeof v === "object" && !Array.isArray(v),
-      );
-      if (entries.length > 0) {
-        const schema: Record<string, string> = {};
-        for (const [k, v] of entries) {
-          schema[k] = jsonSchemaToCelType(v as Record<string, any>);
-        }
-        (env as any).registerVariable({ name: "variables", schema });
-      } else {
-        env.registerVariable("variables", "map");
-      }
-    } else {
-      env.registerVariable("variables", "map");
-    }
+    // `variables` / `secrets`: the DECLARING module's blocks, which is the
+    // contract the resource's CEL is evaluated against at runtime. Read the
+    // same three ways `ports` and `module` are, and for the same reason — a
+    // resource doc does not carry them, so typing from `manifest` alone left
+    // every ordinary resource with an open `variables` and no check at all,
+    // while `ports.<typo>` one line away was an error.
+    //
+    // Order matters: a module-identity doc analyzing itself carries its own
+    // block; a resource forwarded from an imported library carries its
+    // library's as `metadata.moduleGlobals`, which must win over the consuming
+    // application's; everything else is the entry module's own doc.
+    const moduleGlobals = (manifest.metadata as Record<string, any> | undefined)?.moduleGlobals as
+      | Record<string, unknown>
+      | undefined;
+    // A KIND document is the exception, and it is not a detail: the CEL inside
+    // a `Telo.Definition`'s `schema:` — an `examples:` entry, a `description`
+    // showing `${{ secrets.API_KEY }}` — illustrates what a CONSUMER writes, in
+    // the consumer's scope. Closing those over the declaring module's blocks
+    // reported an error against a name the module never meant to declare, and
+    // one nobody could fix without deleting the example.
+    const root = (
+      isKindDocument(manifest) ? undefined : (rootModuleManifest as Record<string, unknown>)
+    ) as Record<string, unknown> | undefined;
+    registerConfigNamespace(
+      env,
+      (manifest as Record<string, unknown>).variables ?? moduleGlobals?.variables ?? root?.variables,
+      "variables",
+    );
 
     // `ports` namespace: each entry types as the brand its `protocol` selects
     // (tcp → TcpPort, udp → UdpPort), so `${{ ports.http }}` carries a nominal
@@ -87,7 +97,11 @@ export function buildTypedCelEnvironment(
       env.registerVariable("ports", "map");
     }
 
-    env.registerVariable("secrets", "map");
+    registerConfigNamespace(
+      env,
+      (manifest as Record<string, unknown>).secrets ?? moduleGlobals?.secrets ?? root?.secrets,
+      "secrets",
+    );
     env.registerVariable("resources", "map");
 
     // `module` — the declaring module's own `metadata`, so a manifest reads its
@@ -132,6 +146,21 @@ export function buildTypedCelEnvironment(
   }
 }
 
+/**
+ * A kind document — whose CEL is written for whoever instantiates the kind, not
+ * evaluated in the declaring module's own scope.
+ *
+ * Its `examples:` show a consumer's route reading `request` and `result`, its
+ * `description`s show `${{ secrets.API_KEY }}`, and a rule condition reads the
+ * `self` / `referrer` its own evaluator binds. None of those names are in scope
+ * where they are WRITTEN, and all of them are correct where they are READ — so
+ * every check that asks "is this name in scope here" has to stand down on these
+ * documents, or it reports errors nobody can fix without deleting the example.
+ */
+export function isKindDocument(manifest: ResourceManifest): boolean {
+  return manifest.kind === "Telo.Definition" || manifest.kind === "Telo.Abstract";
+}
+
 /** Register a `variables`/`secrets` namespace typed from a module doc's schema map
  *  (`{ name: <schema>, … }`), falling back to dyn `map` when absent or untyped. */
 function registerConfigNamespace(

package/src/cel-scope.ts

@@ -42,6 +42,7 @@ import {
 } from "./kernel-globals.js";
 import { gatherPropertySchemas, resolveLocalRef, walkStepArray } from "./schema-walk.js";
 import { readStepSlot } from "./step-slot.js";
+import { bodyForPath, templateBodies } from "./template-body.js";
 import {
   getManifestItem,
   resolveContextAnnotations,
@@ -415,6 +416,20 @@ export class CelScopeResolver {
   private stepContext: Record<string, any> | undefined;
   private invocationContext: Record<string, any> | undefined;
   private errorScopes: Map<string, Record<string, any>> = new Map();
+  /** The same two facts per `resources:` entry of a `Telo.Definition` — a
+   *  template body is a declaration of ANOTHER kind, so its step body and its
+   *  error branches are that kind's, not the enclosing definition's. */
+  private bodyScopes: Array<{
+    prefix: string;
+    scopePrefix: string;
+    manifest: Record<string, any>;
+    stepContext: Record<string, any> | undefined;
+    errorScopes: Map<string, Record<string, any>>;
+  }> = [];
+  /** The enclosing definition's `self` schema, resolved once per resource. A
+   *  template body's contexts resolve against the BODY, so `self` — the one
+   *  binding anchored on the definition — is substituted before they do. */
+  private selfSchema: Record<string, any> | undefined;
 
   constructor(private readonly inputs: CelScopeInputs) {}
 
@@ -445,19 +460,44 @@ export class CelScopeResolver {
     this.invocationContext = (m.metadata as any)?.xTeloInvocationContext as
       | Record<string, any>
       | undefined;
-    this.stepContext = definition?.schema
+    // The INHERITANCE-RESOLVED schema at both sites, for the reason the CEL
+    // context regions use it: an `extends` child is authored against
+    // merge(parent, own), so a step body or a `catch:` region the parent
+    // declares is in force on the child. All three consumers share one memo so
+    // they cannot come to disagree about which schema a kind means.
+    const authorSchema = defs.effectiveSchemaOf(definition) as Record<string, any> | undefined;
+    this.stepContext = authorSchema
       ? buildStepContextSchema(
           m as Record<string, any>,
-          definition.schema as Record<string, any>,
+          authorSchema,
           allManifests as Record<string, any>[],
           defs,
           aliases,
           scopes,
         )
       : undefined;
-    this.errorScopes = collectErrorContextScopes(
-      definition?.schema as Record<string, any> | undefined,
-    );
+    this.errorScopes = collectErrorContextScopes(authorSchema);
+    this.selfSchema =
+      m.kind === "Telo.Definition" ? buildSelfSchema(m as Record<string, any>, defs, aliases) : undefined;
+    this.bodyScopes = templateBodies(m, defs, aliases, scopes).map((body) => {
+      const bodySchema = defs.effectiveSchemaOf(body.definition) as Record<string, any> | undefined;
+      return {
+        prefix: body.prefix,
+        scopePrefix: body.scopePrefix,
+        manifest: body.manifest as Record<string, any>,
+        stepContext: bodySchema
+          ? buildStepContextSchema(
+              body.manifest as Record<string, any>,
+              bodySchema,
+              allManifests as Record<string, any>[],
+              defs,
+              aliases,
+              scopes,
+            )
+          : undefined,
+        errorScopes: collectErrorContextScopes(bodySchema),
+      };
+    });
   }
 
   /**
@@ -514,18 +554,39 @@ export class CelScopeResolver {
     const m = site.source;
     let matched: Record<string, any> | undefined = site.contextSchema ?? this.invocationContext;
 
-    if (this.stepContext) {
+    // Inside a template body the step and error regions are the NESTED kind's.
+    // Its `steps` accumulator and its `catch:` branches are declared there, and
+    // the enclosing definition's (there are none) would say nothing about them.
+    const inBody = this.bodyScopes.length > 0 ? bodyForPath(this.bodyScopes, path) : undefined;
+    const stepContext = inBody ? inBody.stepContext : this.stepContext;
+    const errorScopes = inBody ? inBody.errorScopes : this.errorScopes;
+
+    if (stepContext) {
       const base = matched ?? { type: "object", properties: {}, additionalProperties: true };
       matched = {
         ...base,
-        properties: { ...(base.properties ?? {}), steps: this.stepContext },
+        properties: {
+          // `inputs` is in scope beside `steps` wherever a step body runs — the
+          // step engine evaluates a step against the enclosing kind's own
+          // arguments, which is what `steps[0].inputs.x` reads. Modelled here
+          // because it was modelled NOWHERE: the step context is open, so a
+          // chain through it was never checked and the name's absence went
+          // unnoticed until something asked whether the root existed.
+          //
+          // OPEN, not typed from the kind's `inputType`: closing it would newly
+          // reject every read of an argument the contract does not spell out,
+          // which is a separate decision from knowing the name is legal.
+          inputs: { type: "object", additionalProperties: true },
+          ...(base.properties ?? {}),
+          steps: stepContext,
+        },
       };
     }
 
     // `error` is only in scope inside an error-bearing branch (e.g. a
     // `catch:` / `finally:`), so it's merged per-path, not resource-wide.
     const errorSchema =
-      this.errorScopes.size > 0 ? errorContextForPath(path, this.errorScopes) : undefined;
+      errorScopes.size > 0 ? errorContextForPath(path, errorScopes) : undefined;
     if (errorSchema) {
       const base = matched ?? { type: "object", properties: {}, additionalProperties: true };
       matched = {
@@ -543,16 +604,49 @@ export class CelScopeResolver {
     }
 
     const { defs, aliases, scopes, allManifests, kernelGlobals } = this.inputs;
-    const manifestItem = site.matchedScope
-      ? getManifestItem(path, site.matchedScope, m as Record<string, any>)
-      : (m as Record<string, any>);
-    const rootForResolver = manifestRootForResolver(
-      m as Record<string, any>,
-      defs,
-      aliases,
-      allManifests as Record<string, any>[],
-      scopes,
-    );
+
+    // A template body's context annotations are the NESTED kind's, and every one
+    // that anchors at a root — `x-telo-context-element-from`,
+    // `-collection-from`, `-from-root`, `x-telo-bindings-from` — means the root
+    // of the DECLARATION they were written for. Resolving them against the
+    // enclosing `Telo.Definition` looked `collection:` up on a document that has
+    // no such field, so `item` typed open and a typo below it went unreported —
+    // the one place a nested declaration did not answer as the same declaration
+    // written at the top level.
+    //
+    // So the path and the scope are rebased into the body and the body becomes
+    // the resolution root. `self` is the single binding that genuinely belongs to
+    // the enclosing definition, and it is substituted below rather than left as
+    // an annotation the rebased root would misread.
+    const body = inBody;
+    const localPath = body ? path.slice(body.prefix.length + 1) : path;
+    const localScope =
+      body && site.matchedScope?.startsWith(`${body.scopePrefix}.`)
+        ? `$.${site.matchedScope.slice(body.scopePrefix.length + 1)}`
+        : body
+          ? undefined
+          : site.matchedScope;
+    const rootManifest = body ? body.manifest : (m as Record<string, any>);
+
+    if (body && this.selfSchema && matched.properties?.self) {
+      matched = {
+        ...matched,
+        properties: { ...matched.properties, self: this.selfSchema },
+      };
+    }
+
+    const manifestItem = localScope
+      ? getManifestItem(localPath, localScope, rootManifest)
+      : rootManifest;
+    const rootForResolver = body
+      ? rootManifest
+      : manifestRootForResolver(
+          m as Record<string, any>,
+          defs,
+          aliases,
+          allManifests as Record<string, any>[],
+          scopes,
+        );
     const resolved = resolveContextAnnotations(matched, manifestItem, {
       manifestRoot: rootForResolver,
       defs,
@@ -560,7 +654,7 @@ export class CelScopeResolver {
       allManifests: allManifests as Record<string, any>[],
     });
     return mergeKernelGlobalsIntoContext(
-      withBindingNames(resolved, m as Record<string, any>),
+      withBindingNames(resolved, rootManifest),
       // Typed in the module that DECLARED this resource — for a manifest
       // forwarded from an imported library, that is its `moduleGlobals` stamp,
       // not the consuming application's block.

package/src/definition-registry.ts

@@ -41,6 +41,9 @@ export class DefinitionRegistry {
   private readonly fieldMaps = new Map<string, ReferenceFieldMap>();
   /** Reverse inheritance index: parent kind → direct child kinds. */
   private readonly extendedBy = new Map<string, string[]>();
+  /** Memoized inheritance-resolved schemas. `null` records "resolved to
+   *  nothing", so a kind with no schema is not re-walked on every resource. */
+  private readonly effectiveSchemas = new Map<string, Record<string, unknown> | null>();
   /** DEPRECATED module identity table: identity string → canonical module name
    *  ("std/pipeline" → "pipeline"). Serves only the legacy
    *  `<namespace>/<module>#<Kind>` form of `x-telo-ref`, kept resolvable for
@@ -57,6 +60,7 @@ export class DefinitionRegistry {
     // so any already-computed map recomputes against the now-larger def set; the
     // maps rebuild lazily on first `getFieldMap` (after all defs are registered).
     this.fieldMaps.clear();
+    this.effectiveSchemas.clear();
     // `capability` populates extendedBy for backward-compat with the legacy pattern where
     // a concrete definition overloaded `capability: <AbstractKind>` to mean "implements
     // this abstract." The canonical pattern is `extends` (below). Both populate the index,
@@ -285,6 +289,44 @@ export class DefinitionRegistry {
     return this.defs.get(kind);
   }
 
+  /**
+   * The kind's AUTHOR-FACING schema — its own merged with everything it
+   * inherits along `extends` — memoized per kind.
+   *
+   * This is what every consumer reading a kind's schema to interpret an
+   * INSTANCE must use, because that is the schema the instance was authored
+   * against and the one the kernel stamps at definition registration. Reading
+   * `resolve(kind).schema` instead sees only what the leaf declared, so an
+   * annotation on a parent — a CEL context region, a step body, an error
+   * context — is invisible on every child, silently and per consumer. Sharing
+   * one memo is what keeps those consumers from drifting apart.
+   *
+   * Lazy for the same reason `getFieldMap` is: a child registered before its
+   * parent still sees the inherited half once both are present.
+   */
+  effectiveSchema(kind: string): Record<string, unknown> | undefined {
+    const cached = this.effectiveSchemas.get(kind);
+    if (cached !== undefined) return cached ?? undefined;
+    const def = this.defs.get(kind);
+    if (!def) return undefined;
+    const schema = effectiveAuthorSchema(def, (k) => this.resolve(k)) as
+      | Record<string, unknown>
+      | undefined;
+    this.effectiveSchemas.set(kind, schema ?? null);
+    return schema;
+  }
+
+  /** The effective schema for a definition, by the kind it is registered under.
+   *  Falls back to the definition's own schema when it is not in this registry
+   *  (a synthesized or not-yet-registered kind), which is the pre-inheritance
+   *  behaviour and the safe direction: it types less, never wrongly. */
+  effectiveSchemaOf(definition: ResourceDefinition | undefined): Record<string, unknown> | undefined {
+    if (!definition) return undefined;
+    const { name, module: mod } = definition.metadata;
+    const resolved = this.effectiveSchema(mod ? `${mod}.${name}` : name);
+    return resolved ?? (definition.schema as Record<string, unknown> | undefined);
+  }
+
   /** Returns the reference field map for the given kind, computed lazily from the
    *  kind's AUTHOR-FACING (inheritance-resolved) schema and memoized. Lazy so a
    *  child registered before its parent still sees the parent's inherited ref
@@ -407,6 +449,42 @@ export class DefinitionRegistry {
     return buildFieldMapAtPath(subSchema, fieldPath);
   }
 
+  /** The kinds a definition descends from DIRECTLY — the same two edges
+   *  `register` feeds into `extendedBy`, read the other way.
+   *
+   *  Both spellings, because either can carry the edge that satisfies a slot:
+   *  `capability:` is the legacy implements-this form, `extends:` the canonical
+   *  one. A consumer walking these by hand would be a second reading of what an
+   *  inheritance edge IS, and the downward index and the upward walk have to
+   *  agree about that forever. */
+  parentsOf(kind: string): string[] {
+    const def = this.defs.get(kind);
+    if (!def) return [];
+    return [def.capability, def.extends].filter(
+      (parent): parent is string => typeof parent === "string" && parent.length > 0,
+    );
+  }
+
+  /** Whether every kind this one descends from is registered.
+   *
+   *  When it is, what the kind implements is FULLY KNOWN: a target it does not
+   *  reach is one it genuinely does not implement, so a mismatch is a verdict.
+   *  When a hop is missing — an unimported abstract, an alias the declaring file
+   *  could not resolve — a mismatch cannot be told from a missing dependency,
+   *  which is the partial context every reference check stays lenient in. */
+  ancestryResolved(kind: string): boolean {
+    const queue = [kind];
+    const seen = new Set<string>();
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (seen.has(current)) continue;
+      seen.add(current);
+      if (!this.defs.has(current)) return false;
+      queue.push(...this.parentsOf(current));
+    }
+    return true;
+  }
+
   /** Returns all definitions that transitively extend the given abstract kind.
    *  Follows the capability chain to any depth (equivalent to instanceof in OOP).
    *  Definitions are included regardless of registration order. */

package/src/dependency-graph.ts

@@ -2,6 +2,7 @@ import type { ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import { buildCallGraph, projectToPairs, type ResourceGraphNode } from "./call-graph.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { readSuppliedResources } from "./resource-input.js";
 
 export interface ResourceNode {
   kind: string;
@@ -67,6 +68,8 @@ export function buildDependencyGraph(
   }
   for (const key of nodes.keys()) if (!deps.has(key)) deps.set(key, new Set());
 
+  addResourceInputEdges(resources, nodes, deps);
+
   // --- Kahn's topological sort ---
   // in-degree[X] = number of X's dependencies (size of deps[X])
   // reverse[dep] = set of nodes that depend on dep (for degree decrement)
@@ -164,3 +167,66 @@ function findCycle(
 
   return [];
 }
+
+/**
+ * Boot-order edges for the one thing a `Telo.Import` does hold: the instances it
+ * hands DOWN to its target library's declared `resources:` inputs.
+ *
+ * An import is otherwise module wiring rather than a runtime node — it is in
+ * `DEPENDENCY_GRAPH_SKIP_KINDS` and the call graph gives it no node at all — but
+ * a borrowed instance must exist before the import initializes, and a cycle
+ * through one is a cycle like any other. The edges are added here rather than
+ * read off the reference field map because the accepted KIND at this slot is
+ * declared by the TARGET library, not by the `Telo.Import` schema, so there is
+ * no `x-telo-ref` for the map to read; the constraint itself is checked by
+ * `validate-resource-inputs`.
+ */
+function addResourceInputEdges(
+  resources: ResourceManifest[],
+  nodes: Map<string, ResourceNode>,
+  deps: Map<string, Set<string>>,
+): void {
+  // Every import that supplies inputs becomes a node FIRST, so a cross-module
+  // reference below can resolve to the import that exports its target.
+  const imports: Array<{ key: string; supplied: Record<string, unknown> }> = [];
+  for (const m of resources) {
+    if (m.kind !== "Telo.Import") continue;
+    const alias = m.metadata?.name as string | undefined;
+    const supplied = readSuppliedResources(m);
+    if (!alias || Object.keys(supplied).length === 0) continue;
+    const key = nodeKey(m.kind, alias);
+    nodes.set(key, { kind: m.kind, name: alias });
+    if (!deps.has(key)) deps.set(key, new Set<string>());
+    imports.push({ key, supplied });
+  }
+  if (imports.length === 0) return;
+
+  const byName = new Map<string, string>();
+  for (const [key, node] of nodes) byName.set(node.name, key);
+  // An import is keyed by its alias, and that is also how a cross-module
+  // reference names it — index those so one resolves.
+  for (const m of resources) {
+    if (m.kind !== "Telo.Import") continue;
+    const alias = m.metadata?.name as string | undefined;
+    const key = alias ? nodeKey(m.kind, alias) : undefined;
+    if (alias && key && nodes.has(key)) byName.set(alias, key);
+  }
+
+  for (const { key, supplied } of imports) {
+    const set = deps.get(key)!;
+    for (const value of Object.values(supplied)) {
+      const ref = value as { name?: unknown; alias?: unknown } | undefined;
+      // A CROSS-MODULE reference (`!ref Other.db`) names an instance exported by
+      // another import, never a local resource. Looking it up in the local name
+      // map would find an unrelated resource of the same name — a wrong edge,
+      // and possibly a phantom cycle — or nothing at all. What it depends on is
+      // the IMPORT that exports it, which is the projection
+      // `localDependencyNames` already makes at runtime.
+      const alias = typeof ref?.alias === "string" ? ref.alias : undefined;
+      const targetName =
+        alias && alias !== "Self" ? alias : typeof ref?.name === "string" ? ref.name : undefined;
+      const target = targetName ? byName.get(targetName) : undefined;
+      if (target && target !== key) set.add(target);
+    }
+  }
+}

package/src/eval-paths.ts

@@ -1,3 +1,27 @@
+/**
+ * WHERE IS CEL EVALUATED — the one reader, and the one decision built on it.
+ *
+ * Two independent ways a value is evaluated, and every consumer needs both:
+ * `x-telo-eval` names a field directly, while a REGION annotation
+ * (`x-telo-context` / `x-telo-step-context` / `x-telo-error-context`, or a step
+ * body) covers everything beneath it — which is how `Run.Choice`'s rows and an
+ * `Http.Api` route's `returns:` entries hold expressions while declaring no
+ * annotation of their own.
+ *
+ * The consumers are on both sides of the runtime: `telo check` decides whether a
+ * `!cel` here is live (`CEL_IN_NON_EVAL_FIELD`) or resolved at startup
+ * (`OBSERVED_STATE_IN_STARTUP_FIELD`), the kernel decides what to expand, and
+ * the editor decides whether to offer an expression at all. The editor's answer
+ * is a CLAIM that `telo check` will accept what it writes, so a second
+ * implementation there is a promise nothing keeps — it read `x-telo-eval` alone
+ * and left every predicate inside a region as a bare checkbox, with no way to
+ * write the expression the field exists to hold.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+
+import { isStepSlot } from "./step-slot.js";
+
 /**
  * The single containment rule for `x-telo-eval` paths, shared by every matcher so
  * the analyzer's coverage decision and the kernel's expansion/exclusion can't
@@ -66,3 +90,131 @@ function collectEvalPathsNode(
     }
   }
 }
+
+/** Schema keys that declare a CEL-bearing region: a field carrying any of these
+ *  is evaluated at runtime, so a `!cel` inside it (or a descendant) is live. A
+ *  STEP BODY is one too, and says so through the grammar its items point at
+ *  rather than through a key — {@link isStepSlot} reads either spelling. */
+const CEL_REGION_KEYS = [
+  "x-telo-context",
+  "x-telo-step-context",
+  "x-telo-error-context",
+] as const;
+
+/** True when this schema node declares a CEL-bearing region. Node-level, so a
+ *  consumer holding one schema (an editor rendering one field) asks it directly
+ *  rather than deriving scopes it would then have to match against. */
+export function declaresCelRegion(schema: unknown): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  const node = schema as Record<string, unknown>;
+  return CEL_REGION_KEYS.some((key) => node[key] !== undefined) || isStepSlot(node);
+}
+
+/**
+ * Walk a JSON Schema tree and collect the JSONPath scopes of every field that
+ * declares a CEL-bearing region (`x-telo-context` / `x-telo-step-context` /
+ * `x-telo-error-context`). Used — alongside `x-telo-eval` paths — to decide
+ * whether a `!cel` expression sits in a slot the runtime actually evaluates.
+ * Scopes use the same `$.a.b[*]` form as `extractContextsFromSchema`, matched
+ * against expression paths with `pathMatchesScope`.
+ */
+export function extractCelRegionScopes(schema: Record<string, any>, path = "$"): string[] {
+  if (!schema || typeof schema !== "object") return [];
+  const out: string[] = [];
+
+  if (declaresCelRegion(schema)) out.push(path);
+
+  if (schema.properties) {
+    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
+      out.push(...extractCelRegionScopes(value, `${path}.${key}`));
+    }
+  }
+  if (schema.items && typeof schema.items === "object") {
+    out.push(...extractCelRegionScopes(schema.items, `${path}[*]`));
+  }
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    if (Array.isArray(schema[key])) {
+      for (const subschema of schema[key]) out.push(...extractCelRegionScopes(subschema, path));
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
+ * falls within the scope of a context (e.g. "$.routes[*].inputs").
+ *
+ * The scope is matched directly (no sibling sharing): a context at "$.routes[*].inputs" only
+ * applies to expressions whose path starts with "routes[N].inputs", not to other sibling fields.
+ */
+export function pathMatchesScope(exprPath: string, scope: string): boolean {
+  const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
+  if (!stripped) return false;
+
+  // Split on wildcard array segments; each [*] must match a concrete [N] in exprPath
+  const parts = stripped.split("[*]");
+  let remaining = exprPath;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!;
+    if (!remaining.startsWith(part)) return false;
+    remaining = remaining.slice(part.length);
+    if (i < parts.length - 1) {
+      // Expect a concrete array index like [0], [12], ...
+      const m = remaining.match(/^\[\d+\]/);
+      if (!m) return false;
+      remaining = remaining.slice(m[0].length);
+    }
+  }
+  // Expression must end here or continue into a child path
+  return remaining === "" || remaining[0] === "." || remaining[0] === "[";
+}
+
+/** Every place a schema says its values are evaluated: the `x-telo-eval` paths,
+ *  by mode, plus the scopes of the regions that cover their contents. */
+export interface CelEvalSites {
+  compile: readonly string[];
+  runtime: readonly string[];
+  regions: readonly string[];
+}
+
+export const NO_CEL_EVAL_SITES: CelEvalSites = { compile: [], runtime: [], regions: [] };
+
+export function celEvalSites(schema: Record<string, any> | undefined): CelEvalSites {
+  if (!schema) return NO_CEL_EVAL_SITES;
+  const { compile, runtime } = buildEvalPaths(schema);
+  return { compile, runtime, regions: extractCelRegionScopes(schema) };
+}
+
+/** The union of several schemas' sites — a kind's own and its capability
+ *  abstract's, which is how a `Telo.Provider`'s implicit compile-eval reaches
+ *  fields the provider never annotated. */
+export function mergeCelEvalSites(...sites: CelEvalSites[]): CelEvalSites {
+  return {
+    compile: sites.flatMap((s) => s.compile),
+    runtime: sites.flatMap((s) => s.runtime),
+    regions: sites.flatMap((s) => s.regions),
+  };
+}
+
+/**
+ * Whether the value at `path` is evaluated, and when — null for a field whose
+ * value is read as a literal.
+ *
+ * `compile` wins over `runtime`, and both win over a region: a field's own
+ * annotation is more specific than the region it sits in, which is the same
+ * precedence a nested annotation has over an enclosing one. A region resolves to
+ * `runtime` because that is what a region IS — a per-invocation scope naming
+ * what its expressions can read.
+ *
+ * `path` is the `walkCelExpressions` spelling (`routes[0].returns[1].when`).
+ */
+export function celEvalModeAt(
+  sites: CelEvalSites,
+  path: string,
+): "compile" | "runtime" | null {
+  if (evalPathsCover(sites.compile, path)) return "compile";
+  if (evalPathsCover(sites.runtime, path)) return "runtime";
+  if (sites.regions.some((scope) => pathMatchesScope(path, scope))) return "runtime";
+  return null;
+}