@telorun/analyzer 0.50.0 → 0.52.0

package/dist/index.js

@@ -3,6 +3,7 @@ export { StaticAnalyzer } from "./analyzer.js";
 export { importResolutionDiagnostics } from "./import-resolution-diagnostics.js";
 export { flattenForAnalyzer, flattenLoadedModule, forwardReExportManifests, parseExportEntry, reExportSpecsFromExports, resolveExportedKinds, selectModuleManifestsForAnalysis, stampExportedKinds, stampReExportedKinds, } from "./flatten-for-analyzer.js";
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
+export { BINDINGS_ANNOTATION, bindingContextProperties, bindingDependencies, findBindingSites, resolveBindingOrder, } from "./cel-bindings.js";
 export { applyObservedStateNode, buildObservedStateIndex, buildObservedStateResourcesSchema, collectRunReachableNames, observedStateRead, validateObservedStateDeclarations, OBSERVED_STATE_SCHEMA, } from "./validate-observed-state.js";
 export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolver.js";
 export { ancestorChain, contractDeclarer, controllerBearingAncestor, effectiveAuthorSchema, effectiveContractField, effectiveStatusSchema, hasOwnControllerOrTemplate, inheritedCapability, isInheritedDelegation, mappingFieldFor, needsContractMapping, resolveParent, } from "./extends-resolution.js";
@@ -21,7 +22,7 @@ export { buildDocumentPositions, buildLineOffsets, buildPositionIndex, documentL
 export { HttpSource } from "./sources/http-source.js";
 export { RegistrySource } from "./sources/registry-source.js";
 export { defaultSources } from "./sources/default-sources.js";
-export { splitIntegrity, foldIntegrity, verifyIntegrity, verifiedFetch, sha256Base64Url, IntegrityError, } from "./sources/integrity.js";
+export { splitIntegrity, foldIntegrity, isCanonicalIntegrity, verifyIntegrity, verifiedFetch, sha256Base64Url, IntegrityError, } from "./sources/integrity.js";
 export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
 export { OCI_SCHEME, isOciRef, parseOciRef } from "./sources/oci-ref.js";
 export { parseVersionedRef, withRefVersion } from "./sources/versioned-ref.js";
@@ -32,5 +33,5 @@ export { LayerIndexError, matchControllerLayers, parseLayerIndex, singletonLayer
 export { validateModuleArtifact } from "./validate-module-artifact.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { documentToAst, parseToAst } from "./yaml-ast.js";
-export { buildCelSegments, wrapCelAst } from "./cel-ast.js";
+export { CelParseError, buildCelSegments, wrapCelAst } from "./cel-ast.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";

package/dist/sources/integrity.d.ts

@@ -24,6 +24,16 @@ export declare function splitIntegrity(ref: string): {
  *  author-authored pin is never overwritten). Inverse of `splitIntegrity`;
  *  used to fold the object form's `integrity:` sibling into the source string. */
 export declare function foldIntegrity(source: string, integrity: unknown): string;
+/** True for a value safe to WRITE into a manifest as an integrity pin.
+ *
+ *  A pin arriving from outside the file — the hub's version index, a registry
+ *  response — is untrusted text before it is untrusted *content*: a value
+ *  carrying a quote, a `#`, or a newline corrupts the YAML it is spliced into,
+ *  which no later install-time verification can catch because the manifest no
+ *  longer parses. A wrong-but-well-formed hash is the case install *does*
+ *  catch; this is the case it cannot. Callers writing a pin they did not
+ *  compute check here first and fall back to writing none. */
+export declare function isCanonicalIntegrity(value: unknown): value is string;
 /** SHA-256 of `bytes` as unpadded base64url — the canonical inline-hash form. */
 export declare function sha256Base64Url(bytes: Uint8Array): Promise<string>;
 /** Hash `bytes` and compare against `integrity` (`<alg>-<digest>`). Throws a

package/dist/sources/integrity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../../src/sources/integrity.ts"],"names":[],"mappings":"AAAA;;;;;;6EAM6E;AAO7E;;;qDAGqD;AACrD,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAIhF;AAED;;;kFAGkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAIxE;AAcD,iFAAiF;AACjF,wBAAsB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAOxE;AAED;;gFAEgF;AAChF,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;sCAIsC;AACtC,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAU9C"}
+{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../../src/sources/integrity.ts"],"names":[],"mappings":"AAAA;;;;;;6EAM6E;AAc7E;;;qDAGqD;AACrD,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAIhF;AAED;;;kFAGkF;AAClF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAIxE;AAED;;;;;;;;8DAQ8D;AAC9D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEpE;AAcD,iFAAiF;AACjF,wBAAsB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAOxE;AAED;;gFAEgF;AAChF,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;sCAIsC;AACtC,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAU9C"}

package/dist/sources/integrity.js

@@ -9,6 +9,12 @@
  *  fragments (rare in module refs) pass through untouched. `sha256` is the
  *  only algorithm accepted today; the prefix leaves room to migrate. */
 const INTEGRITY_FRAGMENT = /#(sha256-[A-Za-z0-9_+/=-]+)$/;
+/** The canonical written form: SHA-256 as unpadded base64url, exactly what
+ *  {@link sha256Base64Url} emits and what the `layers[].integrity` schema
+ *  accepts. Stricter than {@link INTEGRITY_FRAGMENT}, which also tolerates the
+ *  padded / standard-base64 spellings {@link verifyIntegrity} normalizes on the
+ *  way in — reading is forgiving, writing is not. */
+const CANONICAL_INTEGRITY = /^sha256-[A-Za-z0-9_-]{43}$/;
 /** A failed integrity/tamper check — always terminal, never best-effort. A
  *  distinct type so a caller doing best-effort network handling (e.g. the
  *  bundle extractor warning-and-skipping on a fetch blip) can still let a
@@ -37,6 +43,18 @@ export function foldIntegrity(source, integrity) {
         ? `${source}#${integrity}`
         : source;
 }
+/** True for a value safe to WRITE into a manifest as an integrity pin.
+ *
+ *  A pin arriving from outside the file — the hub's version index, a registry
+ *  response — is untrusted text before it is untrusted *content*: a value
+ *  carrying a quote, a `#`, or a newline corrupts the YAML it is spliced into,
+ *  which no later install-time verification can catch because the manifest no
+ *  longer parses. A wrong-but-well-formed hash is the case install *does*
+ *  catch; this is the case it cannot. Callers writing a pin they did not
+ *  compute check here first and fall back to writing none. */
+export function isCanonicalIntegrity(value) {
+    return typeof value === "string" && CANONICAL_INTEGRITY.test(value);
+}
 function toBase64Url(bytes) {
     let binary = "";
     for (let i = 0; i < bytes.length; i++)

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAItF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AA4CD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAyCjC;AAuFD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA4IrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD;AAUD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,SAAM,GAAG,MAAM,EAAE,CAqBxF"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAItF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AA4CD,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAa,GACxC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAyCjC;AAuFD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiJrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD;AAUD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,SAAM,GAAG,MAAM,EAAE,CAqBxF"}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.50.0",
+  "version": "0.52.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.63.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,6 +63,16 @@ 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";
@@ -416,6 +430,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 +443,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 +459,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 +810,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[][] {
@@ -1695,6 +1763,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 +1819,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 +2029,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

package/src/cel-ast.ts

@@ -1,4 +1,30 @@
-import { parse, type ASTNode as CelJsNode } from "@marcbachmann/cel-js";
+import { ParseError, parse, type ASTNode as CelJsNode } from "@marcbachmann/cel-js";
+
+/** A CEL body that does not parse — an author's expression, mid-typing or
+ *  malformed. Owned here so a consumer can be lenient about author syntax
+ *  (navigation, completion) without also swallowing a defect in the wrapper
+ *  below, and so the third-party parser's error type stays internal, exactly as
+ *  its AST type does. */
+export class CelParseError extends Error {
+  constructor(
+    readonly source: string,
+    override readonly cause: unknown,
+  ) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.name = "CelParseError";
+  }
+}
+
+/** Parse a CEL body, translating the parser's own failure into `CelParseError`.
+ *  Anything else (a bug in `wrapCelAst`) propagates untouched. */
+function parseCel(source: string): CelJsNode {
+  try {
+    return parse(source).ast;
+  } catch (error) {
+    if (error instanceof ParseError) throw new CelParseError(source, error);
+    throw error;
+  }
+}
 
 /** Read-only CEL expression tree owned by the analyzer. The third-party
  *  `@marcbachmann/cel-js` `ASTNode` stays an internal detail — `wrapCelAst`
@@ -57,7 +83,9 @@ export interface CelSegment {
   source: string;
   /** True when a `${{` has no matching `}}` yet (the user is mid-typing). */
   open: boolean;
-  /** Lazily parse + wrap; ranges are already absolute. */
+  /** Lazily parse + wrap; ranges are already absolute. Throws `CelParseError`
+   *  when the body doesn't parse — an `open` segment recovers to its longest
+   *  parseable prefix instead, so only a closed one can throw. */
   ast(): CelNode;
 }
 
@@ -178,9 +206,11 @@ function parseLenient(source: string, segmentStart: number, range: [number, numb
     const trimmed = candidate.trim();
     if (!trimmed) break;
     try {
-      return wrapCelAst(parse(trimmed).ast, segmentStart);
-    } catch {
-      // try the next-shorter prefix
+      return wrapCelAst(parseCel(trimmed), segmentStart);
+    } catch (error) {
+      // Only a body that doesn't parse warrants the next-shorter prefix; a
+      // wrapper defect is not something a shorter prefix fixes.
+      if (!(error instanceof CelParseError)) throw error;
     }
   }
   return { kind: "ident", range, name: source.trim() };
@@ -211,7 +241,7 @@ export function buildCelSegments(
         range,
         source: taggedSource,
         open: false,
-        ast: () => wrapCelAst(parse(taggedSource).ast, bodyStart),
+        ast: () => wrapCelAst(parseCel(taggedSource), bodyStart),
       },
     ];
   }
@@ -230,7 +260,7 @@ export function buildCelSegments(
       range: [scalarStart + match.index, scalarStart + match.index + whole.length],
       source,
       open: false,
-      ast: () => wrapCelAst(parse(source).ast, bodyStart),
+      ast: () => wrapCelAst(parseCel(source), bodyStart),
     });
     lastClosedEnd = match.index + whole.length;
   }

package/src/cel-bindings.ts

@@ -0,0 +1,222 @@
+import { isCompiledValue } from "@telorun/sdk";
+import { buildCelEnvironment, extractAccessChains } from "@telorun/templating";
+import { extractContextsFromSchema } from "./validate-cel-context.js";
+
+/** Annotation on an `x-telo-context` node naming the resource field that holds
+ *  the kind's named CEL bindings. The field is read from the RESOURCE ROOT, not
+ *  the per-scope manifest item: a bindings map belongs to the resource, while the
+ *  contexts that see it may be anchored anywhere (a decision table annotates both
+ *  `choices` and `default`). */
+export const BINDINGS_ANNOTATION = "x-telo-bindings-from";
+
+export interface BindingSites {
+  /** Resource field holding the bindings map. */
+  field: string;
+  /** Every field named by an annotation on this kind. More than one is a
+   *  kind-authoring mistake: which of them holds the bindings would be decided
+   *  by schema walk order. */
+  fields: string[];
+  /** Variable names the annotated contexts declare — a binding may not shadow one. */
+  scopeNames: Set<string>;
+}
+
+/**
+ * CEL keywords. A binding named after one is unreachable — `true` lexes as a
+ * literal, `in` as an operator — so it is reserved alongside the scope names,
+ * which turns silence into a diagnostic.
+ */
+export const CEL_RESERVED_WORDS: readonly string[] = [
+  "as",
+  "break",
+  "const",
+  "continue",
+  "else",
+  "false",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "let",
+  "loop",
+  "namespace",
+  "null",
+  "package",
+  "return",
+  "true",
+  "var",
+  "void",
+  "while",
+];
+
+/** Locate a kind's bindings field and the scope names its annotated contexts
+ *  declare. Returns undefined for a kind that declares no bindings region. */
+export function findBindingSites(
+  definitionSchema: Record<string, any> | undefined,
+): BindingSites | undefined {
+  if (!definitionSchema) return undefined;
+  const fields: string[] = [];
+  const scopeNames = new Set<string>();
+  for (const { schema } of extractContextsFromSchema(definitionSchema)) {
+    const declared = schema?.[BINDINGS_ANNOTATION];
+    if (typeof declared !== "string" || declared.length === 0) continue;
+    if (!fields.includes(declared)) fields.push(declared);
+    for (const name of Object.keys(schema.properties ?? {})) scopeNames.add(name);
+  }
+  return fields.length > 0 ? { field: fields[0]!, fields, scopeNames } : undefined;
+}
+
+const TEMPLATE_RE = /\$\{\{\s*([^}]+?)\s*\}\}/g;
+const EXACT_TEMPLATE_RE = /^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/;
+
+/** Parser for expressions that reach here uncompiled. Built once; the base
+ *  environment is stateless and shared with the runtime's own. */
+let parseEnv: ReturnType<typeof buildCelEnvironment> | undefined;
+
+/**
+ * Root identifiers an expression source reads — the first element of every
+ * member-access chain, which is what a dependency edge is made of.
+ *
+ * Parsed, never lexed: `inputs.total` reads `inputs`, not `total`, and a name
+ * inside a string literal reads nothing. A token scan would make two bindings
+ * named after each other's *fields* look mutually recursive and reject a correct
+ * manifest — the worst outcome a static check has. An expression that does not
+ * parse contributes no edges; its syntax error is the engine pass's to report.
+ */
+function addRootIdentifiers(source: string, out: Set<string>): void {
+  try {
+    parseEnv ??= buildCelEnvironment();
+    for (const chain of extractAccessChains(parseEnv.parse(source).ast)) {
+      if (chain.length > 0) out.add(chain[0]!);
+    }
+  } catch {
+    // Unparseable — see above.
+  }
+}
+
+/** Root identifiers a binding's value reads. Walks the whole value so a
+ *  structured binding (a map with `!cel` leaves) is covered, and reads both a
+ *  compiled expression and a still-raw `${{ }}` string — the editor's
+ *  round-trip view never compiles. An untagged plain string is a literal, not
+ *  an expression, and contributes nothing. */
+function collectRefs(value: unknown, out: Set<string>): void {
+  if (isCompiledValue(value)) {
+    const refs = (value as { refs?: readonly string[] }).refs;
+    if (refs) for (const ref of refs) out.add(ref);
+    else addRootIdentifiers((value as { source?: string }).source ?? "", out);
+    return;
+  }
+  if (typeof value === "string") {
+    for (const match of value.matchAll(TEMPLATE_RE)) addRootIdentifiers(match[1]!, out);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) collectRefs(entry, out);
+    return;
+  }
+  if (value !== null && typeof value === "object") {
+    for (const entry of Object.values(value)) collectRefs(entry, out);
+  }
+}
+
+/** Each binding's dependencies, restricted to its siblings — an identifier that
+ *  names something else in scope (`inputs`, `item`) is not an edge. */
+export function bindingDependencies(
+  bindings: Record<string, unknown>,
+): Map<string, Set<string>> {
+  const names = new Set(Object.keys(bindings));
+  const deps = new Map<string, Set<string>>();
+  for (const [name, value] of Object.entries(bindings)) {
+    const refs = new Set<string>();
+    collectRefs(value, refs);
+    const own = new Set<string>();
+    for (const ref of refs) if (names.has(ref)) own.add(ref);
+    deps.set(name, own);
+  }
+  return deps;
+}
+
+/** Member-access chain for a binding whose value is one bare dotted identifier
+ *  expression (`inputs.user.name`). Null for anything else — a literal, a call,
+ *  a comprehension, a structured value — none of which reduces to a typed path. */
+export function bindingPathChain(value: unknown): string[] | null {
+  let source: string | undefined;
+  if (isCompiledValue(value)) source = (value as { source?: string }).source;
+  else if (typeof value === "string") source = value.match(EXACT_TEMPLATE_RE)?.[1];
+  if (source === undefined) return null;
+  const expr = source.trim();
+  if (!/^[A-Za-z_]\w*(\.[A-Za-z_]\w*)*$/.test(expr)) return null;
+  return expr.split(".");
+}
+
+/**
+ * The context properties a bindings map contributes: each name typed from its
+ * expression where that expression is a chain into an already-typed scope
+ * variable, and left open otherwise.
+ *
+ * Gradual by design — the same stance `x-telo-context-element-from` takes. An
+ * open schema costs a missed `CEL_UNKNOWN_FIELD` under that name; inventing a
+ * type would cost a false one.
+ */
+export function bindingContextProperties(
+  bindings: Record<string, unknown>,
+  contextSchema: Record<string, any>,
+): Record<string, any> {
+  const props: Record<string, any> = {};
+  for (const [name, value] of Object.entries(bindings)) {
+    props[name] = schemaAtChain(bindingPathChain(value), contextSchema) ?? {};
+  }
+  return props;
+}
+
+/** Walk a member-access chain through a schema's `properties`, returning the
+ *  terminal node or undefined once the path leaves typed schema. */
+export function schemaAtChain(
+  chain: string[] | null,
+  root: Record<string, any>,
+): Record<string, any> | undefined {
+  if (!chain) return undefined;
+  let current: Record<string, any> | undefined = root;
+  for (const key of chain) {
+    const props = current?.properties as Record<string, any> | undefined;
+    if (!props || !(key in props)) return undefined;
+    current = props[key] as Record<string, any>;
+  }
+  return current && typeof current === "object" ? current : undefined;
+}
+
+/**
+ * Evaluation order derived from the reference graph, plus any cycles found.
+ *
+ * Order is what the editor and diagnostics show; the runtime does not need it,
+ * since lazy evaluation reaches a binding's dependencies by construction. A
+ * cycle is reported as the path that closes it (`a → b → a`).
+ */
+export function resolveBindingOrder(bindings: Record<string, unknown>): {
+  order: string[];
+  cycles: string[][];
+} {
+  const deps = bindingDependencies(bindings);
+  const order: string[] = [];
+  const cycles: string[][] = [];
+  const state = new Map<string, "visiting" | "done">();
+  const path: string[] = [];
+
+  const visit = (name: string): void => {
+    const seen = state.get(name);
+    if (seen === "done") return;
+    if (seen === "visiting") {
+      cycles.push([...path.slice(path.indexOf(name)), name]);
+      return;
+    }
+    state.set(name, "visiting");
+    path.push(name);
+    for (const dep of deps.get(name) ?? []) visit(dep);
+    path.pop();
+    state.set(name, "done");
+    order.push(name);
+  };
+
+  for (const name of Object.keys(bindings)) visit(name);
+  return { order, cycles };
+}

package/src/index.ts

@@ -24,6 +24,14 @@ export {
     type ReExportSpec,
 } from "./flatten-for-analyzer.js";
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
+export {
+  BINDINGS_ANNOTATION,
+  bindingContextProperties,
+  bindingDependencies,
+  findBindingSites,
+  resolveBindingOrder,
+} from "./cel-bindings.js";
+export type { BindingSites } from "./cel-bindings.js";
 export {
   applyObservedStateNode,
   buildObservedStateIndex,
@@ -111,6 +119,7 @@ export { defaultSources } from "./sources/default-sources.js";
 export {
   splitIntegrity,
   foldIntegrity,
+  isCanonicalIntegrity,
   verifyIntegrity,
   verifiedFetch,
   sha256Base64Url,
@@ -161,7 +170,7 @@ export { validateModuleArtifact } from "./validate-module-artifact.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";
-export { buildCelSegments, wrapCelAst } from "./cel-ast.js";
+export { CelParseError, buildCelSegments, wrapCelAst } from "./cel-ast.js";
 export type { CelNode, CelSegment } from "./cel-ast.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";
 export type {