@telorun/analyzer 0.56.0 → 0.57.0

package/dist/validate-throws-coverage.js

@@ -171,7 +171,7 @@ function checkCatchAllPlacement(entries, resource, channel, filePath, arrayPath)
  *  in coverage-proving `when:` clauses. Phase 2 accepts inherit/passthrough
  *  handler unions too — when the resolved union is unbounded, a catch-all is
  *  required (rule 4 extension). */
-function checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env) {
+function checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env, handler) {
     const diagnostics = [];
     const declaredCodes = new Set(union.codes.keys());
     const covered = new Set();
@@ -221,16 +221,19 @@ function checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env
         });
     }
     if (!hasCatchAll) {
-        for (const code of declaredCodes) {
-            if (!covered.has(code)) {
-                diagnostics.push({
-                    severity: DiagnosticSeverity.Error,
-                    code: "UNCOVERED_THROW_CODE",
-                    source: SOURCE,
-                    message: `Code '${code}' is declared by the handler but not covered by any catches: entry (no matching \`when:\` and no catch-all).`,
-                    data: { resource, filePath, path: arrayPath },
-                });
-            }
+        // One diagnostic per block, not per code: every uncovered code sits at the
+        // same `catches:` array, and one catch-all answers all of them at once. A
+        // diagnostic each repeated the same location and the same fix N times.
+        const uncovered = [...declaredCodes].filter((c) => !covered.has(c)).sort();
+        if (uncovered.length > 0) {
+            diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "UNCOVERED_THROW_CODE",
+                source: SOURCE,
+                message: `handler ${handler?.name ? `\`!ref ${handler.name}\`` : `\`${handler?.kind ?? "?"}\``} can throw ${uncovered.length} code${uncovered.length === 1 ? "" : "s"} that no catches: entry handles: ${uncovered.map((c) => `'${c}'`).join(", ")}. ` +
+                    `Give each a matching \`when:\` (e.g. \`when: !cel "error.code == '${uncovered[0]}'"\`), or add a catch-all entry — one with no \`when:\`, placed last.`,
+                data: { resource, filePath, path: arrayPath, uncovered },
+            });
         }
     }
     return diagnostics;
@@ -447,7 +450,7 @@ export function validateThrowsCoverage(manifests, defs, aliases, env, aliasesByM
             diagnostics.push(...checkCatchAllPlacement(entries, resource, "catches", filePath, arrayPath));
             const handlerRef = resolveHandlerRef(siblingData[catchesFor]);
             const union = handlerRefUnion(handlerRef, manifests, resolveCtx, scopeResolver);
-            diagnostics.push(...checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env));
+            diagnostics.push(...checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env, handlerRef));
             diagnostics.push(...checkTypedErrorData(entries, union, resource, filePath, arrayPath, env));
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -41,14 +41,15 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
+    "packageurl-js": "^2.0.1",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.12.0"
+    "@telorun/templating": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.68.0"
+    "@telorun/sdk": "0.72.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analyzer.ts

@@ -1,7 +1,13 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId, OBSERVED_STATE_KEY } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
-import { defaultRegistry, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
+import {
+  defaultRegistry,
+  isRefSentinel,
+  isTaggedSentinel,
+  type CelSurface,
+} from "@telorun/templating";
+import type { DiagnosticFix } from "./types.js";
 import {
   AliasResolver,
   moduleScopedDefResolver,
@@ -25,7 +31,7 @@ import {
 import { buildCallGraph } from "./call-graph.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
 import {
-  buildKernelGlobalsSchema,
+  buildKernelGlobalsIndex,
   KERNEL_GLOBAL_NAMES,
   mergeKernelGlobalsIntoContext,
 } from "./kernel-globals.js";
@@ -84,6 +90,7 @@ import {
 import { validateExtends } from "./validate-extends.js";
 import { validateLogging } from "./validate-logging.js";
 import { validateModuleArtifact } from "./validate-module-artifact.js";
+import { validateIncludePlacement } from "./validate-include-placement.js";
 import { validateModuleMetadata } from "./validate-module-metadata.js";
 import { validateBaseMapping } from "./validate-base-mapping.js";
 import { validateInvocationContract } from "./validate-invocation-contract.js";
@@ -906,89 +913,62 @@ function celAccessChains(env: Environment, expr: string): string[][] {
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 const CEL_EXPR_RE = /\$\{\{\s*([^}]+?)\s*\}\}/;
 
-/** Recursively walk `data`+`schema` together, type-checking every pure CEL template
- *  string via `env.check()`. Returns `SchemaIssue[]` for any type mismatches found. */
-function collectCelTypeIssues(
+/** Restore the delimiters an engine's fix was computed without, so the
+ *  replacement is the whole scalar rather than a bare expression that would be
+ *  read back as literal text. A tagged scalar carries no wrapper and passes
+ *  through untouched. */
+function rewrapFix(
+  fix: DiagnosticFix | undefined,
+  wrapper: CelSurface["wrapper"],
+): DiagnosticFix | undefined {
+  if (!fix || !wrapper) return fix;
+  return { replacement: wrapper.prefix + fix.replacement + wrapper.suffix };
+}
+
+/** A pure-CEL leaf and the schema of the field it sits in. */
+export interface CelValueSlot {
+  readonly path: string;
+  readonly schema: Record<string, any>;
+}
+
+/** Recursively walk `data`+`schema` together, collecting every pure CEL leaf
+ *  with the schema of the field holding it.
+ *
+ *  Type *checking* is deliberately not done here. It belongs to the templating
+ *  engine, which owns the expression's syntax and now runs it once against the
+ *  environment typed for that path; checking again here would mean two verdicts
+ *  from two environments about one expression — which is exactly how an opaque
+ *  "no matching overload" used to survive next to the diagnostic that explained
+ *  it. What this walk supplies is the half the engine cannot know: the declared
+ *  type of the slot the value flows into. The comparison happens once both are
+ *  in hand (`reportCelReturnMismatches`). */
+function collectCelValueSlots(
   data: unknown,
   schema: Record<string, any>,
   path: string,
-  definition: { schema?: Record<string, any> },
-  manifest: ResourceManifest,
-  baseTypedEnv: Environment,
-  rootEnv: Environment,
-  rootModuleManifest?: ResourceManifest,
-): SchemaIssue[] {
-  const issues: SchemaIssue[] = [];
-
-  // A pure CEL value type-checks the same regardless of surface form: a
-  // `${{ … }}` string and a `!cel`-tagged sentinel must behave identically.
+): CelValueSlot[] {
+  const slots: CelValueSlot[] = [];
+
+  // A pure CEL value behaves the same regardless of surface form: a
+  // `${{ … }}` string and a `!cel`-tagged sentinel are the same expression.
   let celExpr: string | undefined;
   if (isTaggedSentinel(data)) {
     // Non-CEL engines (e.g. `!literal`) are analyzed by their own engine pass.
-    if (data.engine !== "cel") return issues;
+    if (data.engine !== "cel") return slots;
     celExpr = data.source;
   } else if (typeof data === "string" && CEL_PURE_RE.test(data)) {
     celExpr = data.match(CEL_EXPR_RE)?.[1]?.trim();
   }
 
   if (celExpr !== undefined) {
-    {
-      const expr = celExpr;
-
-      // Merge x-telo-context variables for this path if applicable
-      let typedEnv = baseTypedEnv;
-      if (definition.schema) {
-        for (const ctx of extractContextsFromSchema(definition.schema)) {
-          if (!pathMatchesScope(path, ctx.scope)) continue;
-          typedEnv = buildTypedCelEnvironment(rootEnv, manifest, ctx.schema, rootModuleManifest);
-          break;
-        }
-      }
-
-      let checkResult: ReturnType<typeof typedEnv.check> | undefined;
-      try {
-        checkResult = typedEnv.check(expr);
-      } catch {
-        /* degrade gracefully */
-      }
-
-      if (checkResult?.valid === false && checkResult.error) {
-        // env.check() rejected the expression itself — e.g. wrong method, wrong
-        // argument types, wrong operator overload. Surface the first line of the
-        // error message; the tail is a source-code caret diagram we don't need.
-        const message = String((checkResult.error as { message?: string }).message ?? checkResult.error)
-          .split("\n")[0]
-          .trim();
-        issues.push({ message: `CEL type error: ${message}`, path });
-      } else if (checkResult?.valid && checkResult.type && schema) {
-        const celType = checkResult.type.split("<")[0]!;
-        if (!celTypeSatisfiesJsonSchema(celType, schema)) {
-          const expected = schema["x-telo-type"] ?? schema.type ?? "unknown";
-          issues.push({
-            message: `CEL returns '${checkResult.type}' but field expects '${expected}'`,
-            path,
-          });
-        }
-      }
-    }
-    return issues;
+    if (schema) slots.push({ path, schema });
+    return slots;
   }
 
   if (Array.isArray(data)) {
     const itemSchema = (schema.items ?? {}) as Record<string, any>;
     for (let i = 0; i < data.length; i++) {
-      issues.push(
-        ...collectCelTypeIssues(
-          data[i],
-          itemSchema,
-          `${path}[${i}]`,
-          definition,
-          manifest,
-          baseTypedEnv,
-          rootEnv,
-          rootModuleManifest,
-        ),
-      );
+      slots.push(...collectCelValueSlots(data[i], itemSchema, `${path}[${i}]`));
     }
   } else if (data !== null && typeof data === "object") {
     const props = (schema.properties ?? {}) as Record<string, any>;
@@ -997,22 +977,17 @@ function collectCelTypeIssues(
         ? (schema.additionalProperties as Record<string, any>)
         : {};
     for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
-      issues.push(
-        ...collectCelTypeIssues(
+      slots.push(
+        ...collectCelValueSlots(
           v,
           (props[k] ?? mapValueSchema) as Record<string, any>,
           path ? `${path}.${k}` : k,
-          definition,
-          manifest,
-          baseTypedEnv,
-          rootEnv,
-          rootModuleManifest,
         ),
       );
     }
   }
 
-  return issues;
+  return slots;
 }
 
 export interface StaticAnalyzerOptions {
@@ -1501,6 +1476,9 @@ export class StaticAnalyzer {
       // these fields, which is precisely why they need a check: a mistyped one
       // has no runtime failure mode that would ever surface it.
       diagnostics.push(...validateModuleMetadata(allManifests, defs, aliases));
+      // A file embed resolves at resource creation, so one written on a doc that
+      // is never instantiated is read by nothing and would ship silently.
+      diagnostics.push(...validateIncludePlacement(allManifests));
     }
     resolveSchemaTypeRefs(allManifests, aliases, aliasesByModule);
 
@@ -1613,7 +1591,7 @@ export class StaticAnalyzer {
 
     // Build typed kernel globals schema so x-telo-context chain validation
     // recognises variables, secrets, resources, env automatically
-    const kernelGlobals = buildKernelGlobalsSchema(allManifests, observedState);
+    const kernelGlobals = buildKernelGlobalsIndex(allManifests, observedState);
 
     // Fallback context for CEL in a slot with no `x-telo-context` annotation:
     // everything stays open except the typed `.status` nodes, so unknown-field
@@ -1632,11 +1610,25 @@ export class StaticAnalyzer {
 
     // The module doc (Application/Library) carries the Application-only `ports`
     // namespace; threaded into per-resource CEL typing so `${{ ports.X }}`
-    // resolves its nominal brand cross-doc.
+    // resolves its nominal brand cross-doc. A flattened set holds exactly one —
+    // the entry's; see `buildKernelGlobalsSchema`.
     const moduleManifest =
       allManifests.find((mm) => mm.kind === "Telo.Application") ??
       allManifests.find((mm) => mm.kind === "Telo.Library");
 
+    // Every pure-CEL leaf, with the slot it flows into. Compared against the
+    // type the engine walk resolves, once both halves exist — see
+    // `collectCelValueSlots`.
+    const celReturnSlots: (CelValueSlot & {
+      manifest: ResourceManifest;
+      resource: { kind: string; name: string };
+      filePath?: string;
+    })[] = [];
+    const celTypeByPath = new Map<ResourceManifest, Map<string, string>>();
+    // Context-free typed environments, one per manifest. Reused across every
+    // expression in it — see the build site for why a matched context opts out.
+    const typedEnvByManifest = new Map<ResourceManifest, Environment>();
+
     // Validate each non-definition, non-system resource
     for (const m of allManifests) {
       const filePath = (m.metadata as { source?: string } | undefined)?.source;
@@ -1721,7 +1713,15 @@ export class StaticAnalyzer {
           code: "UNDEFINED_KIND",
           source: SOURCE,
           message: `No Telo.Definition found for kind '${m.kind}'.${hint}`,
-          data: { resource, filePath, path: "kind", suggestedKind },
+          // `suggestedKind` is kept beside the generic `fix` because it names
+          // what the replacement IS; the fix is how to apply it.
+          data: {
+            resource,
+            filePath,
+            path: "kind",
+            suggestedKind,
+            ...(suggestedKind ? { fix: { replacement: suggestedKind } } : {}),
+          },
         });
         continue;
       }
@@ -1748,37 +1748,12 @@ export class StaticAnalyzer {
                 },
               }
             : authorSchema;
-        // Phase 1: CEL type checking — walk data+schema together, check env.check() return types.
-        // A Telo.Import's variables/secrets are a config-only contract evaluated against the
-        // IMPORTING module's scope, so type them from the owning module doc (matched by
-        // `metadata.module`) and drop `resources`/`env` so referencing them is an error. A
-        // library's own internal import is validated against that library in the library's
-        // standalone analysis; in this flattened app pass the library doc is absent, so the
-        // importer is undefined here and variables/secrets fall back to a permissive `map`
-        // (no false positives) while resources/env stay rejected.
-        const importerModule =
-          m.kind === "Telo.Import"
-            ? allManifests.find(
-                (mm) =>
-                  (mm.kind === "Telo.Application" || mm.kind === "Telo.Library") &&
-                  (mm.metadata as { name?: string } | undefined)?.name ===
-                    (m.metadata as { module?: string } | undefined)?.module,
-              )
-            : undefined;
-        const baseTypedEnv =
-          m.kind === "Telo.Import"
-            ? buildImportInputCelEnvironment(this.celEnv, importerModule)
-            : buildTypedCelEnvironment(this.celEnv, m, undefined, moduleManifest);
-        const celIssues = collectCelTypeIssues(
-          m,
-          schema,
-          "",
-          definition,
-          m,
-          baseTypedEnv,
-          this.celEnv,
-          moduleManifest,
-        );
+        // 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);
         // Phase 4: value slots that must satisfy a type declared elsewhere on
@@ -1790,7 +1765,7 @@ export class StaticAnalyzer {
           schema,
           allManifests as Record<string, any>[],
         );
-        const issues = [...celIssues, ...ajvIssues, ...valueSchemaIssues];
+        const issues = [...ajvIssues, ...valueSchemaIssues];
         for (const issue of issues) {
           diagnostics.push({
             severity: DiagnosticSeverity.Error,
@@ -2217,7 +2192,10 @@ export class StaticAnalyzer {
             });
             effectiveContext = mergeKernelGlobalsIntoContext(
               withBindingNames(resolvedContext, m as Record<string, any>),
-              kernelGlobals,
+              // Typed in the module that DECLARED this resource — for a manifest
+              // forwarded from an imported library, that is its `moduleGlobals`
+              // stamp, not the consuming application's block.
+              kernelGlobals.forResource(m),
             );
           } else if (observedStateContext) {
             // No `x-telo-context` matched, so nothing was chain-validated here
@@ -2240,42 +2218,104 @@ export class StaticAnalyzer {
             });
             return;
           }
-          const findings = engine.analyze(expr, { celEnv: this.celEnv, contextSchema: effectiveContext });
-          for (const f of findings) {
-            if (f.code === "CEL_SYNTAX_ERROR") {
+          // The engine type-checks, so it gets the environment typed for THIS
+          // path — not the bare base one. A `Telo.Import`'s variables/secrets
+          // are a config-only contract evaluated in the IMPORTING module's
+          // scope, so they type from the owning module doc and drop
+          // `resources`/`env`, making a reference to either an error.
+          //
+          // Cached per manifest when no `x-telo-context` applied, which is most
+          // expressions: the environment then depends only on the manifest, so
+          // rebuilding it per expression is pure waste — a clone plus a
+          // re-registration of every variable, on every keystroke in the IDE.
+          // A matched context makes the environment path-specific (its schema is
+          // resolved against the enclosing array item), so those still build
+          // fresh rather than risk one item's types leaking into another's.
+          const cached = effectiveContext === null ? typedEnvByManifest.get(m) : undefined;
+          const typedEnv =
+            cached ??
+            (m.kind === "Telo.Import"
+              ? buildImportInputCelEnvironment(
+                  this.celEnv,
+                  allManifests.find(
+                    (mm) =>
+                      (mm.kind === "Telo.Application" || mm.kind === "Telo.Library") &&
+                      (mm.metadata as { name?: string } | undefined)?.name ===
+                        (m.metadata as { module?: string } | undefined)?.module,
+                  ),
+                )
+              : buildTypedCelEnvironment(
+                  this.celEnv,
+                  m,
+                  effectiveContext ?? undefined,
+                  moduleManifest,
+                ));
+          if (effectiveContext === null && !cached) typedEnvByManifest.set(m, typedEnv);
+
+          const result = engine.analyze(expr, { celEnv: typedEnv, contextSchema: effectiveContext });
+
+          if (result.type !== undefined) {
+            let byPath = celTypeByPath.get(m);
+            if (!byPath) celTypeByPath.set(m, (byPath = new Map()));
+            byPath.set(path, result.type);
+          }
+
+          // A non-deterministic call in a compile-eval field is baked once at
+          // load: `nowIso()` there freezes at boot. Sometimes that is the
+          // 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)) {
+            const volatile = [
+              ...new Set(result.calls.filter((c) => c.deterministic === false).map((c) => c.name)),
+            ].sort();
+            if (volatile.length > 0) {
               diagnostics.push({
-                severity: DiagnosticSeverity.Error,
-                code: "CEL_SYNTAX_ERROR",
+                severity: DiagnosticSeverity.Warning,
+                code: "CEL_NONDETERMINISTIC_IN_COMPILE_FIELD",
                 source: SOURCE,
-                message: `CEL syntax error at ${path}: ${f.message}`,
+                message: `${m.kind}/${resource.name}: '${path}' is evaluated once at startup, so ${volatile.map((n) => `\`${n}()\``).join(", ")} ${volatile.length === 1 ? "is" : "are"} baked in at load and never re-evaluated. Move the expression to a field evaluated per call (x-telo-eval: runtime) if it should change over time.`,
                 data: { resource, filePath, path },
               });
-            } else if (f.code === "CEL_UNKNOWN_FIELD") {
+            }
+          }
+
+          for (const f of result.diagnostics) {
+            // A repair is applicable only when the analyzed expression covers
+            // the whole scalar. For one `${{ }}` among literal text, replacing
+            // the node would drop the text around it, so the correction stays
+            // in the message and no fix is stamped.
+            const fix = e.surface.whole ? rewrapFix(f.fix, e.surface.wrapper) : undefined;
+            const data = { resource, filePath, path, ...(fix ? { fix } : {}) };
+            if (f.code === "CEL_SYNTAX_ERROR") {
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
-                code: "CEL_UNKNOWN_FIELD",
+                code: "CEL_SYNTAX_ERROR",
                 source: SOURCE,
-                message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
-                data: { resource, filePath, path },
+                message: `CEL syntax error at ${path}: ${f.message}`,
+                data,
               });
-            } else if (f.code === "CEL_NULLABLE_ACCESS") {
+            } else if (f.code === undefined) {
+              // No code from a future engine — pass the message through, tagged
+              // with a generic ENGINE_DIAGNOSTIC code so downstream filters can
+              // still bucket it.
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
-                code: "CEL_NULLABLE_ACCESS",
+                code: "ENGINE_DIAGNOSTIC",
                 source: SOURCE,
-                message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
-                data: { resource, filePath, path },
+                message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
+                data,
               });
             } else {
-              // Unknown code from a future engine — pass the message through,
-              // tagged with a generic ENGINE_DIAGNOSTIC code so downstream
-              // filters can still bucket it.
+              // Named by ENGINE, not hardcoded to CEL: the seam exists so a
+              // second engine can produce coded findings, and labelling them
+              // `CEL` would misattribute the first one that does.
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
-                code: f.code ?? "ENGINE_DIAGNOSTIC",
+                code: f.code,
                 source: SOURCE,
                 message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
-                data: { resource, filePath, path },
+                data,
               });
             }
           }
@@ -2284,6 +2324,24 @@ export class StaticAnalyzer {
       { aliases },
     );
 
+    // The two halves of "does this expression fit the slot it flows into" meet
+    // here: the engine resolved the expression's type during the walk above,
+    // and the schema walk recorded the slot. An expression that failed to check
+    // recorded no type and is already reported by its own diagnostic.
+    for (const slot of celReturnSlots) {
+      const type = celTypeByPath.get(slot.manifest)?.get(slot.path);
+      if (type === undefined) continue;
+      if (celTypeSatisfiesJsonSchema(type.split("<")[0]!, slot.schema)) continue;
+      const expected = slot.schema["x-telo-type"] ?? slot.schema.type ?? "unknown";
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "CEL_TYPE_ERROR",
+        source: SOURCE,
+        message: `${slot.resource.kind}/${slot.resource.name}: CEL at '${slot.path}' returns '${type}' but the field expects '${expected}'.`,
+        data: { resource: slot.resource, filePath: slot.filePath, path: slot.path },
+      });
+    }
+
     // Validate resource references (Phase 3)
     diagnostics.push(
       ...validateReferences(allManifests, { aliases, definitions: defs, aliasesByModule }),

package/src/flatten-for-analyzer.ts

@@ -41,7 +41,17 @@ export function parseExportEntry(entry: string): ParsedExportEntry {
  *  `byModuleName` and `!ref Alias.name` resolves, while `validate-references` /
  *  the per-resource validation loop never re-walk or re-validate it against the
  *  consumer's scope. A consumer that instead emits every module doc as a peer
- *  local manifest silently breaks both. */
+ *  local manifest silently breaks both.
+ *
+ *  Dropping the module doc costs the consumer's analysis the one thing a
+ *  forwarded manifest's CEL still needs: the `variables` / `secrets` / `ports`
+ *  contract its expressions are evaluated against. That contract is carried
+ *  across as {@link ModuleGlobals} on each forwarded manifest instead, so the
+ *  consumer can check those reads in the DECLARING module's scope rather than
+ *  either skipping them (a diagnostic performed nowhere) or judging them by its
+ *  own block (a hard error the library author cannot act on). Stamped here
+ *  because this is the only point where a manifest and its module doc are both
+ *  in hand — by the time `analyze()` sees the flat list, the doc is gone. */
 export function selectModuleManifestsForAnalysis(
   moduleManifests: ResourceManifest[],
   isRoot: boolean,
@@ -58,10 +68,12 @@ export function selectModuleManifestsForAnalysis(
     exportedResources.add(parseExportEntry(entry).name);
   }
 
+  const moduleGlobals = readModuleGlobals(libDoc);
+
   const out: ResourceManifest[] = [];
   for (const m of moduleManifests) {
     if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract" || m.kind === "Telo.Import") {
-      out.push(m);
+      out.push(withModuleGlobals(m, moduleGlobals));
     } else if (
       !isModuleKind(m.kind) &&
       typeof m.metadata?.name === "string" &&
@@ -69,13 +81,59 @@ export function selectModuleManifestsForAnalysis(
     ) {
       out.push({
         ...m,
-        metadata: { ...m.metadata, forwardedExport: true } as ResourceManifest["metadata"],
+        metadata: {
+          ...m.metadata,
+          forwardedExport: true,
+          ...(moduleGlobals ? { moduleGlobals } : {}),
+        } as ResourceManifest["metadata"],
       });
     }
   }
   return out;
 }
 
+/** The declaring module's config contract, carried on a forwarded manifest so
+ *  the consumer's analysis can type its CEL globals in the right scope. Only the
+ *  namespaces whose typing is scope-dependent: `resources` is deliberately
+ *  absent, see {@link readModuleGlobals}. */
+export interface ModuleGlobals {
+  variables?: Record<string, unknown>;
+  secrets?: Record<string, unknown>;
+  ports?: Record<string, unknown>;
+}
+
+/** Read the schema-map blocks off a module doc, or `undefined` when it declares
+ *  none (the globals then stay permissive, exactly as an absent doc does).
+ *
+ *  `resources` is NOT carried. The flat list holds only this module's EXPORTED
+ *  instances, so a name list built from it would omit every internal one — and a
+ *  `with:`-scoped resource is declared inline rather than as a doc, so it would
+ *  be missing too. Both would read as "no such resource" in a consumer's pass:
+ *  a false positive worse than the unchecked read it replaced. The consumer
+ *  leaves a forwarded manifest's `resources` node open and the library's own
+ *  analysis, which sees every name, does that check. */
+function readModuleGlobals(libDoc: ResourceManifest | undefined): ModuleGlobals | undefined {
+  const doc = libDoc as Record<string, any> | undefined;
+  if (!doc) return undefined;
+  const globals: ModuleGlobals = {};
+  for (const key of ["variables", "secrets", "ports"] as const) {
+    const block = doc[key];
+    if (block && typeof block === "object" && !Array.isArray(block)) globals[key] = block;
+  }
+  return Object.keys(globals).length > 0 ? globals : undefined;
+}
+
+function withModuleGlobals(
+  m: ResourceManifest,
+  moduleGlobals: ModuleGlobals | undefined,
+): ResourceManifest {
+  if (!moduleGlobals) return m;
+  return {
+    ...m,
+    metadata: { ...m.metadata, moduleGlobals } as ResourceManifest["metadata"],
+  };
+}
+
 /** Produce the flat manifest list `analyze()` consumes today.
  *
  *  Combines the entry module's manifests with `Telo.Definition`,

package/src/index.ts

@@ -207,6 +207,8 @@ export type {
   PlatformAxis,
   PlatformTarget,
 } from "./artifact-selector.js";
+export { collectModuleFileClaims } from "./module-file-claims.js";
+export type { ModuleFileClaim } from "./module-file-claims.js";
 export {
   LayerIndexError,
   matchControllerLayers,
@@ -224,10 +226,12 @@ export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-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 { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity, diagnosticFix } from "./types.js";
 export type {
     AnalysisDiagnostic,
     AnalysisOptions,
+    DiagnosticData,
+    DiagnosticFix,
     LoaderInitOptions,
     LoadOptions,
     ManifestSource,