@telorun/analyzer 0.64.0 → 0.66.0

package/src/analyzer.ts

@@ -20,6 +20,7 @@ import {
   buildCelEnvironment,
   buildImportInputCelEnvironment,
   buildTypedCelEnvironment,
+  isKindDocument,
   type CelHandlers,
 } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
@@ -78,7 +79,7 @@ import {
   type ResourceRuleDiagnostic,
   type ResourceRuleIssue,
 } from "./validate-resource-rules.js";
-import { readResourceRules, type ResourceRule } from "./resource-rule.js";
+import { pointerToPath, readResourceRules, type ResourceRule } from "./resource-rule.js";
 import { readReferrerRules, type ReferrerRule } from "./referrer-rule.js";
 import {
   evaluateReferrerRules,
@@ -87,11 +88,15 @@ import {
   reportUnexercisedReferrerRule,
   validateReferrerRuleDeclarations,
   type Referrer,
+  type ReferrerRuleContext,
   type ReferrerRuleDiagnostic,
   type ReferrerRuleIssue,
 } from "./validate-referrer-rules.js";
+import { analyzerPeerBinder, analyzerPeersTarget } from "./peer-binding.js";
 import {
   describeProjectionFailure,
+  manifestListScope,
+  resolveSchemaProjections,
   type ProjectionFailure,
 } from "./schema-projection.js";
 import {
@@ -118,14 +123,18 @@ import { collectValueSchemaIssues } from "./validate-value-schema.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
   extractAccessChains,
-  extractCelRegionScopes,
   extractContextsFromSchema,
   getManifestItem,
-  pathMatchesScope,
   resolveContextAnnotations,
   resolveTypeFieldToSchema,
 } from "./validate-cel-context.js";
-import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
+import {
+  celEvalModeAt,
+  celEvalSites,
+  mergeCelEvalSites,
+  NO_CEL_EVAL_SITES,
+  type CelEvalSites,
+} from "./eval-paths.js";
 import {
   BINDINGS_ANNOTATION,
   bindingContextProperties,
@@ -706,7 +715,7 @@ export class StaticAnalyzer {
    * `DUPLICATE_RESOURCE_NAME` reads those fields to tell a pipeline echo
    * apart from a genuine collision, and downstream diagnostic positioning
    * depends on them too. Real callers stamp positions already (the `Loader`,
-   * `flattenForAnalyzer`, the telo-editor's `emitDocsFor`, the VSCode
+   * `flattenForAnalyzer`, telo studio's `emitDocsFor`, the VSCode
    * extension). Programmatic callers — tests, ad-hoc scripts — should pass
    * their inputs through `withSyntheticPositions(...)` before calling
    * `analyze()`. A missing position throws a clear error rather than
@@ -941,6 +950,11 @@ export class StaticAnalyzer {
     const projectionIssues: SchemaProjectionIssue[] = [];
     const resourceRuleIssues: ResourceRuleIssue[] = [];
     const referrerRuleIssues: ReferrerRuleIssue[] = [];
+    /** Definition docs of the entry's own modules that may declare rules. Their
+     *  referrer-rule declarations are checked after every kind is registered,
+     *  because a `peers:` pointer is checked against the REFERRER kind's schema
+     *  and that kind may be declared later in the same file. */
+    const ownRuleDeclarers: ResourceManifest[] = [];
     // A rule that never had anything to iterate is never proven — the second way
     // coverage varies invisibly, beside the dynamic-leaf skip. Tracked across the
     // whole run and reported once, since "empty on every resource" is not a fact
@@ -998,9 +1012,10 @@ export class StaticAnalyzer {
             effectiveAuthorSchema(m as any, (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k)),
           ),
         );
-        referrerRuleIssues.push(
-          ...validateReferrerRuleDeclarations(m as unknown as ResourceManifest),
-        );
+        // Deferred to after the registration loop: the `peers:` half is checked
+        // against the REFERRER kind's schema, and a rule may name a kind
+        // declared later in the same file.
+        ownRuleDeclarers.push(m as unknown as ResourceManifest);
         for (const rule of readReferrerRules((m as Record<string, unknown>).schema)) {
           referrerRuleExercise.set(`${m.metadata?.module}.${m.metadata?.name}#${rule.code}`, {
             manifest: m as unknown as ResourceManifest,
@@ -1056,6 +1071,25 @@ export class StaticAnalyzer {
       defs.register(normalized);
     }
 
+    /**
+     * What a peer rule's `peers:` pointer names in the kind its `referrer:`
+     * filters to.
+     *
+     * Liskov in BOTH directions, which is what the check has to be: the filter
+     * is usually an abstract (`Sql.Schema`, so one rule serves every backend)
+     * while the collection is declared by the backends that implement it, so a
+     * pointer resolving on any candidate resolves the rule. Reported only when
+     * NO candidate declares it, or when every candidate that does holds plain
+     * data — the two shapes where the rule would see no declaration at all.
+     */
+    const peersTarget = analyzerPeersTarget(defs);
+
+    if (!options?.skipValidation) {
+      for (const declarer of ownRuleDeclarers) {
+        referrerRuleIssues.push(...validateReferrerRuleDeclarations(declarer, { peersTarget }));
+      }
+    }
+
     // Reference-form validation — enforce `!ref` as the only reference shape.
     // Runs on the RAW manifests, BEFORE inline extraction and sentinel
     // resolution, while an author-written `{kind, name}` is still
@@ -1476,6 +1510,17 @@ export class StaticAnalyzer {
       diagnostics.push(...validateIncludePlacement(allManifests));
     }
     resolveSchemaTypeRefs(allManifests, aliases, aliasesByModule);
+    // ...and over the manifests the DEFINITION REGISTRY holds, which are not
+    // these. `normalizeInlineResources` deep-clones — that clone is the
+    // analyzer's immutability boundary — while `defs.register` ran before it, on
+    // the originals. So a kind whose `schema:` references a named shape kept the
+    // authored `telo://Self/<Type>` spelling everywhere the registry is read,
+    // which is where a resource's configuration is validated: the schema failed
+    // to compile, the failure was swallowed, and `telo check` reported nothing
+    // about a resource the kernel then rejected at boot. The pass is idempotent
+    // — a canonical id parses as no authority and is left alone — so running it
+    // over both is the whole repair.
+    resolveSchemaTypeRefs(manifests, aliases, aliasesByModule);
 
     // Trusted-input fast path: when the caller has already attested that
     // this exact manifest set passes analysis (e.g. via the kernel's
@@ -1487,13 +1532,12 @@ export class StaticAnalyzer {
       return suppressUnreadableModuleDiagnostics(diagnostics, unreadableFiles);
     }
 
-    // Build a name→manifest map for looking up referenced resources
-    const byName = new Map<string, ResourceManifest>();
-    for (const m of allManifests) {
-      if (m.metadata?.name) {
-        byName.set(m.metadata.name as string, m);
-      }
-    }
+    // ONE binder for the whole run, built beside the binding it serves: it caches
+    // each referrer's resolved collection, which is what keeps a rule over an
+    // n-entry collection from re-resolving that collection once per entry.
+    const referrerRuleContext: ReferrerRuleContext = {
+      peerBinder: analyzerPeerBinder(defs, aliases, allManifests as ResourceManifest[]),
+    };
 
     // Fail loud on definition schemas AJV cannot compile. `validateAgainstSchema`
     // and `validateWithRefs` swallow compile failures (returning no issues),
@@ -1640,6 +1684,54 @@ export class StaticAnalyzer {
       observedStateContext,
     });
 
+    /**
+     * The schema a resource of this kind is validated against, per DEFINITION.
+     *
+     * Both halves derive a fresh object — `effectiveAuthorSchema` merges along
+     * `extends`, and the closed-schema branch spreads `kind` / `metadata` in —
+     * so asking per resource handed `validateResourceConfig` a schema object it
+     * had never seen. That registry memoizes its compiled AJV validator by
+     * object IDENTITY, precisely because every resource of a kind is checked
+     * against the same one at keystroke time, so a fresh object per resource
+     * recompiled the whole kind schema per resource. Keyed on the definition,
+     * which is stable for the run.
+     */
+    const authorSchemaCache = new WeakMap<object, Record<string, any>>();
+    const validationSchemaFor = (def: ResourceDefinition): Record<string, any> => {
+      const cached = authorSchemaCache.get(def as unknown as object);
+      if (cached) return cached;
+      const authorSchema = effectiveAuthorSchema(def, (k) =>
+        defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k),
+      );
+      // `kind` and `metadata` are implicit on every resource — inject them so
+      // module authors don't have to repeat them under `additionalProperties:
+      // false`.
+      const schema =
+        authorSchema.additionalProperties === false
+          ? {
+              ...authorSchema,
+              properties: {
+                kind: { type: "string" },
+                metadata: { type: "object" },
+                ...authorSchema.properties,
+              },
+            }
+          : authorSchema;
+      authorSchemaCache.set(def as unknown as object, schema);
+      return schema;
+    };
+
+    // One scope for the whole run: it closes over the manifest list and the
+    // registry, neither of which changes per resource, and it is asked once per
+    // schema-valued slot that carries a projection.
+    const resourceProjectionScope = manifestListScope(
+      allManifests as Record<string, any>[],
+      (kind) =>
+        (defs.resolve(kind) ?? defs.resolve(aliases.resolveKind(kind) ?? kind)) as
+          | Record<string, any>
+          | undefined,
+    );
+
     // Validate each non-definition, non-system resource
     for (const m of allManifests) {
       const filePath = (m.metadata as { source?: string } | undefined)?.source;
@@ -1738,35 +1830,55 @@ export class StaticAnalyzer {
       }
 
       // Validate resource config against the definition's AUTHOR-FACING schema —
-      // inheritance-resolved: with `base:` the child's own schema (parent config
-      // is internal), else `merge(parent, own)` so a `base:`-less `extends` child
-      // is validated against the inherited fields it may set. For a definition
-      // that neither extends nor uses `base:` this is exactly its own schema.
-      // `kind` and `metadata` are implicit on every resource — inject them so module
-      // authors don't have to repeat them when using additionalProperties: false.
-      const authorSchema = effectiveAuthorSchema(definition, (k) =>
-        defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k),
-      );
-      if (authorSchema && Object.keys(authorSchema).length > 0) {
-        const schema =
-          authorSchema.additionalProperties === false
-            ? {
-                ...authorSchema,
-                properties: {
-                  kind: { type: "string" },
-                  metadata: { type: "object" },
-                  ...authorSchema.properties,
-                },
-              }
-            : authorSchema;
+      // inheritance-resolved, with `kind` / `metadata` injected. See
+      // `validationSchemaFor`, which is where both derivations and the reason
+      // they are memoized per definition live.
+      const schema = validationSchemaFor(definition);
+      if (Object.keys(schema).length > 0) {
         // Phase 1: collect the pure-CEL leaves and the schema of the slot each
         // flows into. The expression's own type is resolved later, by the
         // engine walk that owns type-checking; this half only knows the target.
         for (const slot of collectCelValueSlots(m, schema, "")) {
           celReturnSlots.push({ manifest: m, resource, filePath, ...slot });
         }
-        // Phase 2+3: AJV on substituted data — CEL fields replaced with typed placeholders
-        const ajvIssues = validateAgainstSchema(substituteCelFields(m, schema), schema);
+        // A kind's own schema may point a slot at a PROJECTION — of a resource it
+        // references, or (the empty pointer) of this very declaration, which is
+        // what types a table's seed rows against its own `columns:`. Resolved
+        // PER RESOURCE, because a projection is declaration-derived: the same
+        // kind schema yields a different row shape for every table.
+        //
+        // A failure here is REPORTED, never dropped. An entry that could not be
+        // read vanishes from the projected shape, so the slot typed from it then
+        // rejects a field the author did declare ("'status' is not allowed") with
+        // nothing saying why — the projection's own failure mode, blaming the
+        // wrong line. Entry-module-scoped, like every other schema issue.
+        const projectionFailures: ProjectionFailure[] = [];
+        const projected = resolveSchemaProjections(
+          schema,
+          m as Record<string, any>,
+          resourceProjectionScope,
+          projectionFailures,
+        ) as Record<string, any>;
+        if (!ownModule || rootModules.has(ownModule)) {
+          for (const failure of projectionFailures) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "SCHEMA_PROJECTION_FROM_UNRESOLVED",
+              source: SOURCE,
+              message: `${m.kind}/${resource.name}: ${describeProjectionFailure(failure)}`,
+              data: { resource, filePath, path: pointerToPath(failure.pointer) },
+            });
+          }
+        }
+        // Phase 2+3: AJV on substituted data — CEL fields replaced with typed
+        // placeholders. Through the REGISTRY, so a kind whose schema references
+        // a shape declared elsewhere is checked on the instance that holds it.
+        const ajvIssues = defs.validateResourceConfig(
+          substituteCelFields(m, projected, undefined, {
+            external: (ref) => defs.schemaForId(ref),
+          }),
+          projected,
+        );
         // Phase 4: value slots that must satisfy a type declared elsewhere on
         // the resource (`x-telo-value-schema-from`) — e.g. every row of a
         // decision table against its declared `outputType`, so a mistyped branch
@@ -1800,12 +1912,12 @@ export class StaticAnalyzer {
       for (const report of reportResourceRules(
         m as unknown as ResourceManifest,
         definition as unknown as ResourceManifest,
-        evaluateResourceRules(m as unknown as ResourceManifest, authorSchema),
+        evaluateResourceRules(m as unknown as ResourceManifest, schema),
         !ruleDeclarer || rootModules.has(ruleDeclarer),
       )) {
         diagnostics.push(resourceRuleDiagnostic(report));
       }
-      for (const rule of readResourceRules(authorSchema)) {
+      for (const rule of readResourceRules(schema)) {
         const key = `${definition.metadata?.module}.${definition.metadata?.name}#${rule.code}`;
         const tracked = ruleExercise.get(key);
         if (!tracked) continue;
@@ -1819,7 +1931,7 @@ export class StaticAnalyzer {
       // literal appears on the referring side, where the spelling would be the
       // consumer's import alias rather than anything the rule's author controls.
       // A consumer of the shared call graph, never a second traversal.
-      const referrerRules = readReferrerRules(authorSchema);
+      const referrerRules = readReferrerRules(schema);
       if (referrerRules.length > 0) {
         const referrers = referrersOf(m as unknown as ResourceManifest, getCallGraph());
         for (const report of reportReferrerRules(
@@ -1827,9 +1939,10 @@ export class StaticAnalyzer {
           definition as unknown as ResourceManifest,
           evaluateReferrerRules(
             m as unknown as ResourceManifest,
-            authorSchema,
+            schema,
             referrers,
             kindMatches,
+            referrerRuleContext,
           ),
           !ruleDeclarer || rootModules.has(ruleDeclarer),
         )) {
@@ -1841,13 +1954,25 @@ export class StaticAnalyzer {
             continue;
           }
           diagnostics.push(referrerRuleDiagnostic(report));
+          // A rule that VIOLATED plainly ran, whatever its peer set held. The
+          // unexercised report exists to catch silence — a `peers:` naming
+          // nothing makes every `!peers.exists(…)` pass vacuously — so a finding
+          // is exactly the evidence it asks for.
+          if (report.code === "REFERRER_RULE_VIOLATED") {
+            const violated = referrerRuleExercise.get(
+              `${definition.metadata?.module}.${definition.metadata?.name}#${report.rule}`,
+            );
+            if (violated) violated.exercised = true;
+          }
         }
         for (const rule of referrerRules) {
           const key = `${definition.metadata?.module}.${definition.metadata?.name}#${rule.code}`;
           const tracked = referrerRuleExercise.get(key);
           if (!tracked) continue;
           tracked.seen = true;
-          if (referrerRuleExercised(rule, referrers, kindMatches)) tracked.exercised = true;
+          if (referrerRuleExercised(rule, referrers, kindMatches, referrerRuleContext)) {
+            tracked.exercised = true;
+          }
         }
       }
 
@@ -1879,6 +2004,10 @@ export class StaticAnalyzer {
               return viaRoot ? defs.resolve(viaRoot) : undefined;
             },
             allManifests as Record<string, any>[],
+            {
+              validate: (data, target) => defs.validateResourceConfig(data, target),
+              external: (ref) => defs.schemaForId(ref),
+            },
           ),
         );
       }
@@ -2045,18 +2174,15 @@ export class StaticAnalyzer {
     // same schema an expression is typed against.
     let celStepContextSchema: Record<string, any> | undefined;
     let celErrorScopes: ReadonlyMap<string, Record<string, any>> = new Map();
-    // Region coverage for the "CEL in a non-eval field" check: the union of
-    // `x-telo-eval` paths (own + capability) and `x-telo-context` /
-    // `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[] = [];
+    // Where this kind says its values are evaluated — `x-telo-eval` paths (own +
+    // capability) and the regions covering their contents. A `!cel` outside every
+    // one of them is read as a literal, and one under a compile path resolves at
+    // startup, where observed state cannot exist yet. Both questions are
+    // `celEvalModeAt`, which the editor asks of the same sites.
+    let celSites: CelEvalSites = NO_CEL_EVAL_SITES;
     // 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[] = [];
-    let celRegionScopes: string[] = [];
     let celRuleApplies = false;
 
     visitManifest(
@@ -2211,22 +2337,28 @@ export class StaticAnalyzer {
           celRuleApplies =
             !!e.definition?.schema && capability !== undefined && capability !== "Telo.Template";
           if (celRuleApplies) {
-            const ownSchema = e.definition!.schema as Record<string, any>;
-            const own = buildEvalPaths(ownSchema);
+            // The INHERITANCE-RESOLVED schema, not the kind's own: without
+            // `base:`, an `extends` child is authored against merge(parent, own),
+            // so a CEL-bearing field the parent declares is a legal field on the
+            // child and the kernel expands it — it stamps the merged schema at
+            // definition registration and builds eval paths from that. Reading
+            // the own schema here reported `CEL_IN_NON_EVAL_FIELD` for an
+            // expression the runtime evaluates correctly, which is the two halves
+            // disagreeing about what the manifest means.
+            const ownSchema = effectiveAuthorSchema(
+              e.definition as unknown as ResourceDefinition,
+              (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k),
+            ) as Record<string, any>;
             const capabilityDef = capability ? defs.resolve(capability) : undefined;
-            const parent = capabilityDef?.schema
-              ? buildEvalPaths(capabilityDef.schema as Record<string, any>)
-              : { compile: [], runtime: [] };
-            celEvalPaths = [...own.compile, ...own.runtime, ...parent.compile, ...parent.runtime];
             // A `Telo.Provider`'s fields are implicitly compile-eval — the
             // capability abstract carries the root annotation — so its reads are
             // covered here without the provider restating anything.
-            celCompilePaths = [...own.compile, ...parent.compile];
-            celRegionScopes = extractCelRegionScopes(ownSchema);
+            celSites = mergeCelEvalSites(
+              celEvalSites(ownSchema),
+              celEvalSites(capabilityDef?.schema as Record<string, any> | undefined),
+            );
           } else {
-            celEvalPaths = [];
-            celCompilePaths = [];
-            celRegionScopes = [];
+            celSites = NO_CEL_EVAL_SITES;
           }
         },
         onCel: (e) => {
@@ -2244,8 +2376,7 @@ export class StaticAnalyzer {
             celRuleApplies &&
             engineName === "cel" &&
             celScope.invocationContextSchema === undefined &&
-            !evalPathsCover(celEvalPaths, path) &&
-            !celRegionScopes.some((scope) => pathMatchesScope(path, scope)) &&
+            celEvalModeAt(celSites, path) === null &&
             !pathCrossesNestedResource(m, path)
           ) {
             diagnostics.push({
@@ -2273,7 +2404,7 @@ export class StaticAnalyzer {
                 read.alias ? `${read.alias}.${read.name}` : read.name,
               );
 
-              if (celRuleApplies && evalPathsCover(celCompilePaths, path)) {
+              if (celRuleApplies && celEvalModeAt(celSites, path) === "compile") {
                 diagnostics.push({
                   severity: DiagnosticSeverity.Error,
                   code: "OBSERVED_STATE_IN_STARTUP_FIELD",
@@ -2320,7 +2451,19 @@ export class StaticAnalyzer {
             matchedScope,
           });
 
-          const result = engine.analyze(expr, { celEnv: typedEnv, contextSchema: effectiveContext });
+          const result = engine.analyze(expr, {
+            celEnv: typedEnv,
+            contextSchema: effectiveContext,
+            // `scopeFor` registers every kernel global and every name the site's
+            // context declares, so a root this environment does not know is one
+            // nothing puts in scope. Two places where the CEL belongs to another
+            // scope, both already recognised by the non-eval-field check: a kind
+            // document, whose CEL is written for whoever instantiates the kind,
+            // and anything below a nested inline `{ kind }`, whose CEL the
+            // nested kind evaluates — and which is analyzed again, in its own
+            // scope, as the resource it was extracted into.
+            rootsDeclared: !isKindDocument(m) && !pathCrossesNestedResource(m, path),
+          });
 
           if (result.type !== undefined) {
             let byPath = celTypeByPath.get(m);
@@ -2357,7 +2500,7 @@ export class StaticAnalyzer {
           // intent (a boot timestamp, a run id), so it warns rather than
           // blocking. The engine reports which calls re-evaluate; the eval mode
           // is manifest policy and stays here.
-          if (celRuleApplies && evalPathsCover(celCompilePaths, path)) {
+          if (celRuleApplies && celEvalModeAt(celSites, path) === "compile") {
             const volatile = [
               ...new Set(result.calls.filter((c) => c.deterministic === false).map((c) => c.name)),
             ].sort();

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

@@ -445,19 +445,23 @@ 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);
   }
 
   /**
@@ -518,7 +522,21 @@ export class CelScopeResolver {
       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: this.stepContext,
+        },
       };
     }