@telorun/analyzer 0.64.0 → 0.66.0

package/dist/analyzer.d.ts

@@ -33,7 +33,7 @@ export declare 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

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAiBzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AA8B9B,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAWvF,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAoDjE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA2F/F;0CAC0C;AAC1C,eAAO,MAAM,eAAe,GAAI,OAAO;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAG,OACT,CAAC;AAErD;8EAC8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAqUD,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACtC;AA6DD,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAkFD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB,EAAE;IAiwDvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAyBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAiBzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AA8B9B,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAWvF,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAwDjE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA+F/F;0CAC0C;AAC1C,eAAO,MAAM,eAAe,GAAI,OAAO;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAG,OACT,CAAC;AAErD;8EAC8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAqUD,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACtC;AA6DD,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAkFD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB,EAAE;IAu4DvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,eAAe,CAAC,EAAE,eAAe,GAChC,kBAAkB,EAAE;IAMvB,SAAS,CACP,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,EAI1B,kBAAkB,CAAC,EAAE,gBAAgB,EAAE,GACtC,gBAAgB,EAAE;IAyBrB,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -1,7 +1,7 @@
 import { canonicalTypeSchemaId, OBSERVED_STATE_KEY } from "@telorun/sdk";
 import { defaultRegistry, isRefSentinel, isTaggedSentinel, plainChainOf, } from "@telorun/templating";
 import { AliasResolver, scopeResolverForModule, } from "./alias-resolver.js";
-import { buildCelEnvironment, } from "./cel-environment.js";
+import { buildCelEnvironment, isKindDocument, } from "./cel-environment.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import { effectiveAuthorSchema } from "./extends-resolution.js";
 import { analyzerContractScope, resolveContract, } from "./invocation-contract.js";
@@ -30,10 +30,11 @@ export { analyzerContractScope } from "./invocation-contract.js";
 import { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
 import { validateSchemaProjection, } from "./validate-schema-projection.js";
 import { evaluateResourceRules, reportResourceRules, reportUnexercisedRule, ruleExercised, validateResourceRuleDeclarations, } from "./validate-resource-rules.js";
-import { readResourceRules } from "./resource-rule.js";
+import { pointerToPath, readResourceRules } from "./resource-rule.js";
 import { readReferrerRules } from "./referrer-rule.js";
 import { evaluateReferrerRules, referrerRuleExercised, reportReferrerRules, reportUnexercisedReferrerRule, validateReferrerRuleDeclarations, } from "./validate-referrer-rules.js";
-import { describeProjectionFailure, } from "./schema-projection.js";
+import { analyzerPeerBinder, analyzerPeersTarget } from "./peer-binding.js";
+import { describeProjectionFailure, manifestListScope, resolveSchemaProjections, } from "./schema-projection.js";
 import { validateDynamicSelectors, validateRefSlotDeclarations, } from "./validate-ref-slots.js";
 import { validateValueTypeSlots, } from "./validate-value-type-slots.js";
 import { resolveSchemaTypeRefs } from "./resolve-schema-type-refs.js";
@@ -42,8 +43,8 @@ import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import { celTypeSatisfiesJsonSchema, checkSchemaCompatibility, navigateSchemaToExprPath, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { collectValueSchemaIssues } from "./validate-value-schema.js";
 import { DiagnosticSeverity } from "./types.js";
-import { extractAccessChains, extractCelRegionScopes, pathMatchesScope, } from "./validate-cel-context.js";
-import { buildEvalPaths, evalPathsCover } from "./eval-paths.js";
+import { extractAccessChains, } from "./validate-cel-context.js";
+import { celEvalModeAt, celEvalSites, mergeCelEvalSites, NO_CEL_EVAL_SITES, } from "./eval-paths.js";
 import { BINDINGS_ANNOTATION, findBindingSites, resolveBindingOrder, } from "./cel-bindings.js";
 import { CEL_RESERVED_WORDS, checkName } from "./identifier-name.js";
 import { validateIdentifierNames } from "./validate-identifier-names.js";
@@ -554,7 +555,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
@@ -776,6 +777,11 @@ export class StaticAnalyzer {
         const projectionIssues = [];
         const resourceRuleIssues = [];
         const referrerRuleIssues = [];
+        /** 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 = [];
         // 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
@@ -822,7 +828,10 @@ export class StaticAnalyzer {
                 // inherited field resolves — which is what lets a rule shared by every
                 // backend be declared once on the abstract they extend.
                 resourceRuleIssues.push(...validateResourceRuleDeclarations(m, effectiveAuthorSchema(m, (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k))));
-                referrerRuleIssues.push(...validateReferrerRuleDeclarations(m));
+                // 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);
                 for (const rule of readReferrerRules(m.schema)) {
                     referrerRuleExercise.set(`${m.metadata?.module}.${m.metadata?.name}#${rule.code}`, {
                         manifest: m,
@@ -873,6 +882,23 @@ export class StaticAnalyzer {
                 : def;
             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
@@ -1257,6 +1283,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
         // hash-stamped `.validated.json` cache), skip the validation walk.
@@ -1266,13 +1303,12 @@ export class StaticAnalyzer {
         if (options?.skipValidation) {
             return suppressUnreadableModuleDiagnostics(diagnostics, unreadableFiles);
         }
-        // Build a name→manifest map for looking up referenced resources
-        const byName = new Map();
-        for (const m of allManifests) {
-            if (m.metadata?.name) {
-                byName.set(m.metadata.name, 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 = {
+            peerBinder: analyzerPeerBinder(defs, aliases, allManifests),
+        };
         // Fail loud on definition schemas AJV cannot compile. `validateAgainstSchema`
         // and `validateWithRefs` swallow compile failures (returning no issues),
         // which would silently skip schema validation for every resource of that
@@ -1409,6 +1445,44 @@ export class StaticAnalyzer {
             moduleManifest,
             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();
+        const validationSchemaFor = (def) => {
+            const cached = authorSchemaCache.get(def);
+            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, 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, (kind) => (defs.resolve(kind) ?? defs.resolve(aliases.resolveKind(kind) ?? kind)));
         // Validate each non-definition, non-system resource
         for (const m of allManifests) {
             const filePath = m.metadata?.source;
@@ -1499,32 +1573,47 @@ export class StaticAnalyzer {
                 continue;
             }
             // 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 = [];
+                const projected = resolveSchemaProjections(schema, m, resourceProjectionScope, projectionFailures);
+                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
@@ -1550,10 +1639,10 @@ export class StaticAnalyzer {
             // `validate-resource-rules.ts`, the shape every neighbouring pass uses:
             // issues out, one emit here.
             const ruleDeclarer = definition.metadata?.module;
-            for (const report of reportResourceRules(m, definition, evaluateResourceRules(m, authorSchema), !ruleDeclarer || rootModules.has(ruleDeclarer))) {
+            for (const report of reportResourceRules(m, definition, evaluateResourceRules(m, 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)
@@ -1568,10 +1657,10 @@ 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, getCallGraph());
-                for (const report of reportReferrerRules(m, definition, evaluateReferrerRules(m, authorSchema, referrers, kindMatches), !ruleDeclarer || rootModules.has(ruleDeclarer))) {
+                for (const report of reportReferrerRules(m, definition, evaluateReferrerRules(m, schema, referrers, kindMatches, referrerRuleContext), !ruleDeclarer || rootModules.has(ruleDeclarer))) {
                     // A VIOLATION is the referrer's data, so it is reported only when that
                     // manifest is the entry's own — the same direction a resource-rule
                     // violation takes, one hop further out.
@@ -1580,6 +1669,15 @@ 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}`;
@@ -1587,8 +1685,9 @@ export class StaticAnalyzer {
                     if (!tracked)
                         continue;
                     tracked.seen = true;
-                    if (referrerRuleExercised(rule, referrers, kindMatches))
+                    if (referrerRuleExercised(rule, referrers, kindMatches, referrerRuleContext)) {
                         tracked.exercised = true;
+                    }
                 }
             }
             // Validate inline resources nested inside this resource's body (e.g. a
@@ -1615,7 +1714,10 @@ export class StaticAnalyzer {
                     }
                     const viaRoot = aliases.resolveKind(kind);
                     return viaRoot ? defs.resolve(viaRoot) : undefined;
-                }, allManifests));
+                }, allManifests, {
+                    validate: (data, target) => defs.validateResourceConfig(data, target),
+                    external: (ref) => defs.schemaForId(ref),
+                }));
             }
             // (Invocation context compatibility check is handled via x-telo-context in the CEL pass below)
         }
@@ -1753,18 +1855,15 @@ export class StaticAnalyzer {
         // same schema an expression is typed against.
         let celStepContextSchema;
         let celErrorScopes = 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 = [];
+        // 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 = 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;
-        // The compile half alone: a field that resolves at startup, where observed
-        // state cannot exist yet.
-        let celCompilePaths = [];
-        let celRegionScopes = [];
         let celRuleApplies = false;
         visitManifest(allManifests, defs, {
             onResourceEnter: (e) => {
@@ -1896,23 +1995,23 @@ export class StaticAnalyzer {
                 celRuleApplies =
                     !!e.definition?.schema && capability !== undefined && capability !== "Telo.Template";
                 if (celRuleApplies) {
-                    const ownSchema = e.definition.schema;
-                    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, (k) => defs.resolve(aliases.resolveKind(k) ?? k) ?? defs.resolve(k));
                     const capabilityDef = capability ? defs.resolve(capability) : undefined;
-                    const parent = capabilityDef?.schema
-                        ? buildEvalPaths(capabilityDef.schema)
-                        : { 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));
                 }
                 else {
-                    celEvalPaths = [];
-                    celCompilePaths = [];
-                    celRegionScopes = [];
+                    celSites = NO_CEL_EVAL_SITES;
                 }
             },
             onCel: (e) => {
@@ -1928,8 +2027,7 @@ export class StaticAnalyzer {
                 if (celRuleApplies &&
                     engineName === "cel" &&
                     celScope.invocationContextSchema === undefined &&
-                    !evalPathsCover(celEvalPaths, path) &&
-                    !celRegionScopes.some((scope) => pathMatchesScope(path, scope)) &&
+                    celEvalModeAt(celSites, path) === null &&
                     !pathCrossesNestedResource(m, path)) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
@@ -1953,7 +2051,7 @@ export class StaticAnalyzer {
                         // the two-level shape it publishes under, so a cross-module read
                         // is checked exactly like a local one.
                         const reported = observedState.get(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",
@@ -1997,7 +2095,19 @@ export class StaticAnalyzer {
                     contextSchema: e.contextSchema,
                     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);
                     if (!byPath)
@@ -2033,7 +2143,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/dist/call-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"call-graph.d.ts","sourceRoot":"","sources":["../src/call-graph.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"call-graph.d.ts","sourceRoot":"","sources":["../src/call-graph.ts"],"names":[],"mappings":"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"}

package/dist/call-graph.js

@@ -119,7 +119,13 @@ function resolveUseAtSite(entry, root, concretePath, schemaDefault) {
         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/dist/cel-environment.d.ts

@@ -13,6 +13,18 @@ export type { CelHandlers } from "@telorun/templating";
  *  NOTE: The set of kernel globals registered here must match `KERNEL_GLOBAL_NAMES`
  *  in kernel-globals.ts, which is used for chain-access validation. */
 export declare function buildTypedCelEnvironment(baseEnv: Environment, manifest: ResourceManifest, extraContextSchema?: Record<string, any> | null, rootModuleManifest?: ResourceManifest): Environment;
+/**
+ * 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 declare function isKindDocument(manifest: ResourceManifest): boolean;
 /** CEL environment for the `variables:`/`secrets:` expressions on a `Telo.Import`.
  *
  *  Import inputs are a config-only contract: their expressions are evaluated

package/dist/cel-environment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cel-environment.d.ts","sourceRoot":"","sources":["../src/cel-environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAcrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;uEASuE;AACvE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAI/C,kBAAkB,CAAC,EAAE,gBAAgB,GACpC,WAAW,CAgGb;AAuBD;;;;;;8DAM8D;AAC9D,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,WAAW,EACpB,cAAc,EAAE,gBAAgB,GAAG,SAAS,GAC3C,WAAW,CAkCb"}
+{"version":3,"file":"cel-environment.d.ts","sourceRoot":"","sources":["../src/cel-environment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAcrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;uEASuE;AACvE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,gBAAgB,EAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,EAI/C,kBAAkB,CAAC,EAAE,gBAAgB,GACpC,WAAW,CA8Gb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAElE;AAuBD;;;;;;8DAM8D;AAC9D,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,WAAW,EACpB,cAAc,EAAE,gBAAgB,GAAG,SAAS,GAC3C,WAAW,CAkCb"}

package/dist/cel-environment.js

@@ -35,24 +35,26 @@ rootModuleManifest) {
         for (const brand of Object.keys(VALUE_BRAND_BASE)) {
             env.registerType(brand, { fields: {} });
         }
-        // Build typed ObjectSchema from manifest.variables if it looks like a schema map
-        const vars = manifest.variables;
-        if (vars !== null && typeof vars === "object" && !Array.isArray(vars)) {
-            const entries = Object.entries(vars).filter(([, v]) => v !== null && typeof v === "object" && !Array.isArray(v));
-            if (entries.length > 0) {
-                const schema = {};
-                for (const [k, v] of entries) {
-                    schema[k] = jsonSchemaToCelType(v);
-                }
-                env.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?.moduleGlobals;
+        // 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);
+        registerConfigNamespace(env, manifest.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
         // type that consuming fields can check against.
@@ -73,7 +75,7 @@ rootModuleManifest) {
         else {
             env.registerVariable("ports", "map");
         }
-        env.registerVariable("secrets", "map");
+        registerConfigNamespace(env, manifest.secrets ?? moduleGlobals?.secrets ?? root?.secrets, "secrets");
         env.registerVariable("resources", "map");
         // `module` — the declaring module's own `metadata`, so a manifest reads its
         // version instead of restating it. A resource forwarded from an imported
@@ -110,6 +112,20 @@ rootModuleManifest) {
         return baseEnv.clone();
     }
 }
+/**
+ * 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) {
+    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(env, block, name) {

package/dist/cel-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cel-scope.d.ts","sourceRoot":"","sources":["../src/cel-scope.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cel-scope.d.ts","sourceRoot":"","sources":["../src/cel-scope.ts"],"names":[],"mappings":"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"}