@telorun/analyzer 0.51.0 → 0.53.0

package/dist/validate-cel-context.js

@@ -283,9 +283,14 @@ export function resolveContextAnnotations(schema, manifestItem, opts) {
             : [fromRefKindRaw];
     if (fromRoot || fromRefKinds.length > 0) {
         if (fromRoot) {
-            const resolved = navigatePath(manifestRoot, fromRoot.split("/"));
-            if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
-                return resolved;
+            const navigated = navigatePath(manifestRoot, fromRoot.split("/"));
+            if (navigated && typeof navigated === "object" && !Array.isArray(navigated)) {
+                // A `telo#Type` slot resolves to the schema it names — the inline
+                // `{ kind, schema }` wrapper, a `!ref` to a named type, or a bare name —
+                // so the variable is typed by the CONTRACT rather than by the wrapper
+                // around it. A raw JSON Schema resolves to itself, and a plain property
+                // map (a transport scope) resolves to nothing and is used verbatim.
+                return resolveTypeFieldToSchema(navigated, allManifests ?? []) ?? navigated;
             }
         }
         if (defs) {

package/dist/validate-module-metadata.d.ts

@@ -0,0 +1,38 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * Static validation of the `metadata:` block on module docs (`Telo.Application` /
+ * `Telo.Library`) and of `metadata.deprecated` wherever it appears.
+ *
+ * These fields are descriptive — nothing in the kernel branches on them — but they
+ * are the module's public face: a hub indexes them, and a consumer reads them
+ * before deciding to import. That is exactly why they need checking. A field the
+ * runtime ignores has no failure mode that would ever surface it, so a mistyped
+ * `licence:` or `deprecatd:` is invisible forever, and the module ships claiming
+ * nothing while its author believes otherwise.
+ *
+ * The vocabulary stays **open** — `metadata` accepts any key, because a publisher
+ * may carry their own — so an unknown key is only reported when it is a near-miss
+ * of a known one. That catches the typo without closing the set.
+ *
+ * **Everything here is a WARNING, and fatal only at `telo publish`** (see
+ * {@link PUBLISH_BLOCKING_CODES}). Refusing to *run* a manifest over a field no
+ * runtime reads gets the cost backwards: `version: 1.0` is a YAML float rather
+ * than a string, which is a real mistake worth reporting, but stopping the app
+ * from starting over it is worse than the mistake. Publication is the moment
+ * these fields become consequential — they are projected onto the artifact's
+ * annotations and indexed by the hub — so that is where they block.
+ */
+/**
+ * Codes that must not block running a manifest but MUST block publishing one.
+ *
+ * Kept as a set rather than a severity because the two audiences differ: a
+ * developer running a manifest wants to know, a publisher must be stopped. If a
+ * later check earns the same treatment, add its code here rather than inventing
+ * a third severity level.
+ */
+export declare const PUBLISH_BLOCKING_CODES: ReadonlySet<string>;
+export declare function validateModuleMetadata(manifests: ResourceManifest[], registry: DefinitionRegistry, aliases: AliasResolver): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-module-metadata.d.ts.map

package/dist/validate-module-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-module-metadata.d.ts","sourceRoot":"","sources":["../src/validate-module-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAiDH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,aAAa,GACrB,kBAAkB,EAAE,CA8CtB"}

package/dist/validate-module-metadata.js

@@ -0,0 +1,256 @@
+import { distance } from "./levenshtein.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Static validation of the `metadata:` block on module docs (`Telo.Application` /
+ * `Telo.Library`) and of `metadata.deprecated` wherever it appears.
+ *
+ * These fields are descriptive — nothing in the kernel branches on them — but they
+ * are the module's public face: a hub indexes them, and a consumer reads them
+ * before deciding to import. That is exactly why they need checking. A field the
+ * runtime ignores has no failure mode that would ever surface it, so a mistyped
+ * `licence:` or `deprecatd:` is invisible forever, and the module ships claiming
+ * nothing while its author believes otherwise.
+ *
+ * The vocabulary stays **open** — `metadata` accepts any key, because a publisher
+ * may carry their own — so an unknown key is only reported when it is a near-miss
+ * of a known one. That catches the typo without closing the set.
+ *
+ * **Everything here is a WARNING, and fatal only at `telo publish`** (see
+ * {@link PUBLISH_BLOCKING_CODES}). Refusing to *run* a manifest over a field no
+ * runtime reads gets the cost backwards: `version: 1.0` is a YAML float rather
+ * than a string, which is a real mistake worth reporting, but stopping the app
+ * from starting over it is worse than the mistake. Publication is the moment
+ * these fields become consequential — they are projected onto the artifact's
+ * annotations and indexed by the hub — so that is where they block.
+ */
+/**
+ * Codes that must not block running a manifest but MUST block publishing one.
+ *
+ * Kept as a set rather than a severity because the two audiences differ: a
+ * developer running a manifest wants to know, a publisher must be stopped. If a
+ * later check earns the same treatment, add its code here rather than inventing
+ * a third severity level.
+ */
+export const PUBLISH_BLOCKING_CODES = new Set([
+    "METADATA_INVALID_TYPE",
+    "METADATA_UNKNOWN_FIELD",
+    "INVALID_DEPRECATION",
+    "DEPRECATION_REPLACEMENT_UNRESOLVED",
+]);
+/** Conventional module-doc metadata, and the type each carries. Descriptive only;
+ *  `name` is the sole field anything resolves against. */
+const MODULE_METADATA_TYPES = {
+    name: "string",
+    module: "string",
+    version: "string",
+    description: "string",
+    repository: "string",
+    homepage: "string",
+    documentation: "string",
+    license: "string",
+    namespace: "string",
+    categories: "string[]",
+    deprecated: "object",
+};
+/** What a kind doc's `metadata:` may carry.
+ *
+ *  Deliberately narrower than a module's: `version`, `license` and the rest
+ *  belong to the module, and a kind restating them means nothing. `categories`
+ *  is legal and *replaces* the module's for that kind; `description` is hub
+ *  search text. Both have exactly the failure mode this file exists for — a
+ *  `descriptoin:` on a kind doc is read by nothing and reported by nothing, so
+ *  it ships silently — which is why kind docs are checked rather than exempt. */
+const KIND_METADATA_TYPES = {
+    name: "string",
+    module: "string",
+    description: "string",
+    categories: "string[]",
+    deprecated: "object",
+};
+/** Alias-qualified kind — `Self.Migrations`, `Cache.Store`, `Telo.JsonSchema`. */
+const ALIAS_KIND_RE = /^[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*$/;
+/** The built-in namespace, resolvable without an import — mirrors `validate-extends`. */
+const TELO_BUILTIN_ALIAS = "Telo";
+function typeOf(value) {
+    if (typeof value === "string")
+        return "string";
+    if (Array.isArray(value))
+        return value.every((v) => typeof v === "string") ? "string[]" : "other";
+    if (value !== null && typeof value === "object")
+        return "object";
+    return "other";
+}
+export function validateModuleMetadata(manifests, registry, aliases) {
+    const out = [];
+    // Docs forwarded from imported libraries carry `metadata.module` set to that
+    // library's name. Their `replacedBy` aliases — `Self`, or any alias private to
+    // that library — belong to the library's OWN scope, which the consumer's
+    // resolver knows nothing about, so re-checking them here reports a false
+    // DEPRECATION_REPLACEMENT_UNRESOLVED against a manifest the consumer does not
+    // own. They are validated when that library is analyzed as a root, which is
+    // its author's concern. Same rule, and the same reason, as `validate-extends`.
+    const importedModules = new Set();
+    for (const m of manifests) {
+        if (m.kind !== "Telo.Import")
+            continue;
+        const resolved = m.metadata
+            ?.resolvedModuleName;
+        if (resolved)
+            importedModules.add(resolved);
+    }
+    for (const manifest of manifests) {
+        const isModuleDoc = manifest.kind === "Telo.Application" || manifest.kind === "Telo.Library";
+        const isKindDoc = manifest.kind === "Telo.Definition" || manifest.kind === "Telo.Abstract";
+        if (!isModuleDoc && !isKindDoc)
+            continue;
+        const metadata = manifest.metadata;
+        if (!metadata)
+            continue;
+        const ownModule = metadata.module;
+        if (ownModule && importedModules.has(ownModule))
+            continue;
+        const name = typeof metadata.name === "string" ? metadata.name : undefined;
+        const filePath = typeof metadata.source === "string" ? metadata.source : undefined;
+        const ctx = {
+            label: `${manifest.kind}/${name ?? "(unnamed)"}`,
+            resource: { kind: manifest.kind, name },
+            filePath,
+        };
+        validateFieldTypes(metadata, isModuleDoc ? MODULE_METADATA_TYPES : KIND_METADATA_TYPES, ctx, out);
+        validateDeprecation(metadata, isModuleDoc, ctx, registry, aliases, out);
+    }
+    return out;
+}
+/** How far a key may be from a known one and still be called a typo.
+ *
+ *  Scaled, not absolute: at a flat 2, `date:` (a perfectly ordinary key an
+ *  author might carry) is two edits from `name` and gets told it is a
+ *  misspelling of it. The vocabulary is open, so a false accusation on a short
+ *  key is worse than missing a typo on one. */
+function typoThreshold(key, known) {
+    return Math.max(1, Math.floor(Math.min(key.length, known.length) / 3));
+}
+function validateFieldTypes(metadata, allowed, ctx, out) {
+    const known = Object.keys(allowed);
+    for (const [key, value] of Object.entries(metadata)) {
+        // Stamped by the loader, not authored — never a typo to report on.
+        if (key === "source")
+            continue;
+        // Listed as known so a typo still gets suggested against it, but its shape
+        // belongs to `validateDeprecation`, which can say what is actually wrong.
+        // Type-checking it here too would report one mistake twice.
+        if (key === "deprecated")
+            continue;
+        const expected = allowed[key];
+        if (expected === undefined) {
+            const near = known.find((k) => distance(key, k) <= typoThreshold(key, k));
+            if (near) {
+                out.push({
+                    severity: DiagnosticSeverity.Warning,
+                    code: "METADATA_UNKNOWN_FIELD",
+                    source: SOURCE,
+                    message: `${ctx.label}: 'metadata.${key}' is not a known field — did you mean '${near}'? ` +
+                        `Nothing reads an unrecognized key, so this declares nothing.`,
+                    data: { resource: ctx.resource, filePath: ctx.filePath, path: `metadata.${key}` },
+                });
+            }
+            continue;
+        }
+        if (typeOf(value) !== expected) {
+            out.push({
+                severity: DiagnosticSeverity.Warning,
+                code: "METADATA_INVALID_TYPE",
+                source: SOURCE,
+                message: `${ctx.label}: 'metadata.${key}' must be ${describeType(expected)}.`,
+                data: { resource: ctx.resource, filePath: ctx.filePath, path: `metadata.${key}` },
+            });
+        }
+    }
+}
+function describeType(t) {
+    if (t === "string[]")
+        return "an array of strings";
+    if (t === "object")
+        return "an object";
+    return "a string";
+}
+/**
+ * `metadata.deprecated: { reason, replacedBy? }`.
+ *
+ * `replacedBy` is deliberately resolvable rather than free text, and its form
+ * follows the level: a module doc names another **module ref** (the `imports:`
+ * source grammar), a kind doc names an **alias-qualified kind** resolved through
+ * this file's own imports — the same grammar `kind:` / `extends:` use, so the
+ * replacement is a link a consumer can follow rather than a sentence they have to
+ * interpret.
+ *
+ * A kind whose replacement lives in a module this one does not import cannot be
+ * named; that case deprecates at module level with a module ref instead. Accepted
+ * over inventing a second grammar for it.
+ */
+function validateDeprecation(metadata, isModuleDoc, ctx, registry, aliases, out) {
+    const deprecated = metadata.deprecated;
+    if (deprecated === undefined)
+        return;
+    const at = "metadata.deprecated";
+    const push = (code, message, path = at, severity = DiagnosticSeverity.Warning) => {
+        out.push({
+            severity,
+            code,
+            source: SOURCE,
+            message: `${ctx.label}: ${message}`,
+            data: { resource: ctx.resource, filePath: ctx.filePath, path },
+        });
+    };
+    if (typeOf(deprecated) !== "object") {
+        push("INVALID_DEPRECATION", `'${at}' must be an object with a 'reason' (and an optional 'replacedBy'). ` +
+            `A bare 'true' says a thing is deprecated without saying what to do instead.`);
+        return;
+    }
+    const block = deprecated;
+    const allowed = new Set(["reason", "replacedBy"]);
+    for (const key of Object.keys(block)) {
+        if (!allowed.has(key)) {
+            push("INVALID_DEPRECATION", `'${at}.${key}' is not a recognized key (reason, replacedBy).`, `${at}.${key}`);
+        }
+    }
+    if (typeof block.reason !== "string" || block.reason.trim() === "") {
+        push("INVALID_DEPRECATION", `'${at}.reason' is required and must be a non-empty string — it is what a consumer reads to know what to do instead.`, `${at}.reason`);
+    }
+    const replacedBy = block.replacedBy;
+    if (replacedBy === undefined)
+        return;
+    const path = `${at}.replacedBy`;
+    if (typeof replacedBy !== "string" || replacedBy.trim() === "") {
+        push("INVALID_DEPRECATION", `'${path}' must be a non-empty string.`, path);
+        return;
+    }
+    if (isModuleDoc) {
+        // A module is replaced by another module, addressed the way an import is.
+        // Catching alias form here is worth a dedicated message: it is the natural
+        // mistake, and it would otherwise be stored as an unresolvable ref.
+        if (ALIAS_KIND_RE.test(replacedBy)) {
+            push("INVALID_DEPRECATION", `'${path}: ${replacedBy}' looks like a kind reference, but a module doc's replacement is a ` +
+                `module ref (e.g. 'oci://ghcr.io/acme/thing'). Deprecate the kind itself to point at another kind.`, path);
+        }
+        return;
+    }
+    // Kind level: resolve through this file's imports, exactly as `extends` does.
+    if (!ALIAS_KIND_RE.test(replacedBy)) {
+        push("INVALID_DEPRECATION", `'${path}: ${replacedBy}' must be an alias-qualified kind ("<Alias>.<Kind>", ` +
+            `e.g. 'Self.Migrations'), resolved via this file's imports.`, path);
+        return;
+    }
+    const prefix = replacedBy.slice(0, replacedBy.indexOf("."));
+    if (prefix !== TELO_BUILTIN_ALIAS && !aliases.hasAlias(prefix)) {
+        push("DEPRECATION_REPLACEMENT_UNRESOLVED", `'${path}: ${replacedBy}' — alias '${prefix}' is not an import in this file's scope. ` +
+            `Declare the import or correct the alias.`, path);
+        return;
+    }
+    const canonical = aliases.resolveKind(replacedBy);
+    if (!canonical || !registry.resolve(canonical)) {
+        push("DEPRECATION_REPLACEMENT_UNRESOLVED", `'${path}: ${replacedBy}' does not resolve to a known kind. A replacement a consumer ` +
+            `cannot follow is no better than none.`, path);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -48,7 +48,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.64.0"
+    "@telorun/sdk": "0.65.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analyzer.ts

@@ -23,7 +23,11 @@ import {
   resolveContract,
 } from "./invocation-contract.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
-import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kernel-globals.js";
+import {
+  buildKernelGlobalsSchema,
+  KERNEL_GLOBAL_NAMES,
+  mergeKernelGlobalsIntoContext,
+} from "./kernel-globals.js";
 import {
   buildObservedStateIndex,
   buildObservedStateResourcesSchema,
@@ -59,9 +63,20 @@ import {
   resolveTypeFieldToSchema,
 } from "./validate-cel-context.js";
 import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
+import {
+  BINDINGS_ANNOTATION,
+  bindingContextProperties,
+  bindingPathChain,
+  CEL_RESERVED_WORDS,
+  findBindingSites,
+  resolveBindingOrder,
+  schemaAtChain,
+  type BindingSites,
+} from "./cel-bindings.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateLogging } from "./validate-logging.js";
 import { validateModuleArtifact } from "./validate-module-artifact.js";
+import { validateModuleMetadata } from "./validate-module-metadata.js";
 import { validateBaseMapping } from "./validate-base-mapping.js";
 import { validateInvocationContract } from "./validate-invocation-contract.js";
 import { collectStepInputIssues } from "./validate-step-inputs.js";
@@ -416,6 +431,9 @@ function buildStepContextSchema(
 
     const invokeField = stepCtx.invoke;
     const outputTypeField = stepCtx.outputType;
+    // Optional: the field a step uses to produce a result without dispatching.
+    // Only a kind that declares one has pure steps at all.
+    const valueField = stepCtx.value;
     if (!invokeField || !outputTypeField) continue;
 
     const steps = manifest[fieldName];
@@ -426,6 +444,13 @@ function buildStepContextSchema(
       defSchema,
     );
 
+    // The instance's own input contract, for typing a pure step that just
+    // forwards one of its values.
+    const ownInputs = resolveTypeFieldToSchema(
+      (manifest as Record<string, any>).inputType,
+      allManifests,
+    );
+
     const stepProperties: Record<string, any> = {};
 
     walkStepArray(steps, stepItemSchema, defSchema, fieldName, (s) => {
@@ -435,7 +460,28 @@ function buildStepContextSchema(
       // wrappers (try/if/while/switch/throw) don't produce a result and must
       // not shadow real entries with a permissive `additionalProperties: true`,
       // or unknown step references slip through chain validation.
-      if (typeof name !== "string" || !invoke || typeof invoke !== "object") return;
+      if (typeof name !== "string") return;
+      if (!invoke || typeof invoke !== "object") {
+        // A pure step dispatches nothing, so there is no contract to resolve.
+        // Where its expression is a plain chain into something already typed —
+        // an earlier step's result, or the kind's own inputs — that type carries
+        // through; anything else (arithmetic, a call, a comprehension) stays
+        // permissive rather than guessed. Same rule as a named binding's.
+        if (valueField && valueField in s) {
+          const scopeRoot = {
+            properties: {
+              steps: { type: "object", properties: { ...stepProperties } },
+              ...(ownInputs ? { inputs: ownInputs } : {}),
+            },
+          };
+          const chained = schemaAtChain(bindingPathChain(s[valueField]), scopeRoot);
+          stepProperties[name] = {
+            type: "object",
+            properties: { result: chained ?? PERMISSIVE_CONTRACT },
+          };
+        }
+        return;
+      }
       const invokedKind = invoke.kind as string | undefined;
       const invokedName = invoke.name as string | undefined;
       // A named `!ref` carries the target's own manifest (which may narrow the
@@ -765,6 +811,29 @@ function errorContextForPath(
   return best?.schema;
 }
 
+/** Add a kind's named bindings to a resolved context, when the context declares
+ *  a bindings region. They go UNDER the context's own properties: a scope
+ *  variable wins over a same-named binding at runtime, so static typing has to
+ *  agree (the collision itself is `BINDING_NAME_RESERVED`). */
+function withBindingNames(
+  contextSchema: Record<string, any>,
+  resource: Record<string, any>,
+): Record<string, any> {
+  const field = contextSchema[BINDINGS_ANNOTATION];
+  if (typeof field !== "string") return contextSchema;
+  const bindings = resource[field];
+  if (bindings === null || typeof bindings !== "object" || Array.isArray(bindings)) {
+    return contextSchema;
+  }
+  return {
+    ...contextSchema,
+    properties: {
+      ...bindingContextProperties(bindings as Record<string, unknown>, contextSchema),
+      ...(contextSchema.properties ?? {}),
+    },
+  };
+}
+
 /** Member-access chains in a CEL expression, or none when it doesn't parse.
  *  Best-effort: a syntax error is reported by the engine pass, not here. */
 function celAccessChains(env: Environment, expr: string): string[][] {
@@ -1247,6 +1316,10 @@ export class StaticAnalyzer {
       // would otherwise fail on a consumer's machine — or, for a mistyped platform
       // axis, silently offer one platform's binary to every host.
       diagnostics.push(...validateModuleArtifact(allManifests));
+      // The descriptive `metadata:` surface. Nothing in the kernel branches on
+      // these fields, which is precisely why they need a check: a mistyped one
+      // has no runtime failure mode that would ever surface it.
+      diagnostics.push(...validateModuleMetadata(allManifests, defs, aliases));
     }
     resolveSchemaTypeRefs(allManifests, aliases, aliasesByModule);
 
@@ -1695,6 +1768,9 @@ export class StaticAnalyzer {
     // `x-telo-step-context` / `x-telo-error-context` scopes. A `!cel` outside
     // every region is read as a literal — the runtime never evaluates it.
     let celEvalPaths: string[] = [];
+    // The bindings field this kind declares (if any), read by the CEL sites that
+    // see the names it introduces.
+    let celBindingSites: BindingSites | undefined;
     // The compile half alone: a field that resolves at startup, where observed
     // state cannot exist yet.
     let celCompilePaths: string[] = [];
@@ -1748,6 +1824,75 @@ export class StaticAnalyzer {
             e.definition?.schema as Record<string, any> | undefined,
           );
 
+          celBindingSites = findBindingSites(e.definition?.schema as Record<string, any>);
+          if (celBindingSites) {
+            const declared = (m as Record<string, any>)[celBindingSites.field];
+            const bindingsName = (m.metadata as any)?.name as string | undefined;
+            const bindingsFile = (m.metadata as { source?: string } | undefined)?.source;
+            const resourceRef = { kind: m.kind, name: bindingsName ?? "" };
+
+            // Which field holds the bindings would otherwise be decided by
+            // schema walk order, silently.
+            if (celBindingSites.fields.length > 1) {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "BINDING_FIELD_AMBIGUOUS",
+                source: SOURCE,
+                message: `${m.kind}/${bindingsName}: the kind's schema points '${BINDINGS_ANNOTATION}' at more than one field (${celBindingSites.fields.join(", ")}). Every annotated context must name the same bindings field.`,
+                data: { resource: resourceRef, filePath: bindingsFile, path: celBindingSites.field },
+              });
+            }
+
+            if (declared !== null && typeof declared === "object" && !Array.isArray(declared)) {
+
+              for (const cycle of resolveBindingOrder(declared).cycles) {
+                diagnostics.push({
+                  severity: DiagnosticSeverity.Error,
+                  code: "BINDING_CYCLE",
+                  source: SOURCE,
+                  message: `${m.kind}/${bindingsName}: '${celBindingSites.field}' has a cycle — ${cycle.join(" → ")}. A binding is resolved from the ones it references, so it cannot reference itself, directly or through others.`,
+                  data: {
+                    resource: resourceRef,
+                    filePath: bindingsFile,
+                    path: `${celBindingSites.field}.${cycle[0]}`,
+                  },
+                });
+              }
+
+              // Every name the CEL environment already binds at this site: the
+              // kernel globals (registered straight onto the environment, not
+              // contributed by any annotation), the scope the annotated contexts
+              // declare, and the two the analyzer merges per site. Shadowing one
+              // would leave the binding silently unreachable there — as would
+              // naming it after a CEL keyword, which never lexes as a reference.
+              const inScope = new Set<string>([
+                ...KERNEL_GLOBAL_NAMES,
+                ...celBindingSites.scopeNames,
+              ]);
+              if (celStepContextSchema) inScope.add("steps");
+              if (celErrorScopes.size > 0) inScope.add("error");
+              const keywords = new Set<string>(CEL_RESERVED_WORDS);
+
+              for (const name of Object.keys(declared)) {
+                const shadows = inScope.has(name);
+                if (!shadows && !keywords.has(name)) continue;
+                diagnostics.push({
+                  severity: DiagnosticSeverity.Error,
+                  code: "BINDING_NAME_RESERVED",
+                  source: SOURCE,
+                  message: shadows
+                    ? `${m.kind}/${bindingsName}: binding '${name}' shadows a variable already in scope here (${[...inScope].sort().join(", ")}). Rename the binding — a scope variable always wins, so this one would never be read.`
+                    : `${m.kind}/${bindingsName}: binding '${name}' is a CEL keyword, so no expression can read it as a reference. Rename the binding.`,
+                  data: {
+                    resource: resourceRef,
+                    filePath: bindingsFile,
+                    path: `${celBindingSites.field}.${name}`,
+                  },
+                });
+              }
+            }
+          }
+
           // The non-eval-field check only applies to runtime resource instances:
           // structural / templating kinds (capability `Telo.Template`, or no
           // definition) carry CEL the kernel evaluates by other rules.
@@ -1889,7 +2034,10 @@ export class StaticAnalyzer {
               aliases,
               allManifests: allManifests as Record<string, any>[],
             });
-            effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
+            effectiveContext = mergeKernelGlobalsIntoContext(
+              withBindingNames(resolvedContext, m as Record<string, any>),
+              kernelGlobals,
+            );
           } else if (observedStateContext) {
             // No `x-telo-context` matched, so nothing was chain-validated here
             // before. Validate the observed-state segment alone rather than