@telorun/analyzer 0.12.0 → 0.13.0

package/dist/validate-unused-declarations.js

@@ -0,0 +1,91 @@
+import { extractAccessChains, INDEX_SEGMENT, walkCelExpressions } from "@telorun/templating";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/** Module-doc namespaces whose entries are consumed via `<ns>.<name>` CEL
+ *  access. One table drives the whole check — adding a namespace is an entry,
+ *  not a branch. */
+const NAMESPACES = ["variables", "secrets", "ports"];
+/**
+ * Warn about declared `variables` / `secrets` / `ports` entries that no CEL
+ * expression references. A declared-but-unconsumed entry is dead weight at
+ * best and misleading at worst (an unbound `ports` entry makes a runner
+ * advertise a port the app never listens on).
+ *
+ * Generic across all three namespaces. References are collected from every CEL
+ * expression (both `${{ … }}` and `!cel`, via `walkCelExpressions`) by
+ * extracting member-access chains: a `<ns>.<name>` chain marks `<name>` used.
+ * Dynamic access (`<ns>[expr]`, or the namespace passed whole, e.g.
+ * `keys(variables)`) yields a chain that stops at the namespace root — that
+ * can't be attributed to a name, so the whole namespace is conservatively
+ * suppressed to avoid false positives.
+ *
+ * Application-only: an Application's `variables` / `secrets` / `ports` flow
+ * exclusively through CEL (into resource fields, or into `Telo.Import` inputs),
+ * so unreferenced means dead. A `Telo.Library`'s `variables` / `secrets` are a
+ * public input contract consumed by its controllers — invisible to CEL
+ * analysis — so they are deliberately not flagged.
+ */
+export function validateUnusedDeclarations(manifests, celEnv) {
+    const moduleManifest = manifests.find((m) => m.kind === "Telo.Application");
+    if (!moduleManifest)
+        return [];
+    const declared = new Map();
+    for (const ns of NAMESPACES) {
+        const block = moduleManifest[ns];
+        if (block && typeof block === "object" && !Array.isArray(block)) {
+            const names = Object.keys(block);
+            if (names.length > 0)
+                declared.set(ns, names);
+        }
+    }
+    if (declared.size === 0)
+        return [];
+    const used = new Map(NAMESPACES.map((ns) => [ns, new Set()]));
+    const suppressed = new Set();
+    for (const m of manifests) {
+        walkCelExpressions(m, "", (expr, _path, engineName) => {
+            if (engineName !== "cel")
+                return;
+            let ast;
+            try {
+                ast = celEnv.parse(expr).ast;
+            }
+            catch {
+                return; // syntax errors are reported by the CEL engine pass
+            }
+            for (const chain of extractAccessChains(ast)) {
+                const ns = chain[0];
+                if (!used.has(ns))
+                    continue;
+                const member = chain[1];
+                // No static member after the namespace root — either the namespace is
+                // used whole (`keys(ports)` → ["ports"]) or accessed dynamically
+                // (`ports[x]` → ["ports", "[*]"]). Neither can be attributed to a
+                // declared name, so suppress the namespace rather than false-positive.
+                if (member === undefined || member === INDEX_SEGMENT)
+                    suppressed.add(ns);
+                else
+                    used.get(ns).add(member);
+            }
+        });
+    }
+    const diagnostics = [];
+    const filePath = moduleManifest.metadata?.source;
+    for (const [ns, names] of declared) {
+        if (suppressed.has(ns))
+            continue;
+        const seen = used.get(ns);
+        for (const name of names) {
+            if (seen.has(name))
+                continue;
+            diagnostics.push({
+                severity: DiagnosticSeverity.Warning,
+                code: "UNUSED_DECLARATION",
+                source: SOURCE,
+                message: `${ns}.${name} is declared but never referenced in any CEL expression.`,
+                data: { filePath, path: `${ns}.${name}` },
+            });
+        }
+    }
+    return diagnostics;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,7 +42,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.3.0"
+    "@telorun/templating": "0.3.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/analysis-registry.ts

@@ -3,6 +3,7 @@ import { AliasResolver } from "./alias-resolver.js";
 import { KERNEL_BUILTINS } from "./builtins.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import { computeSuggestKind, computeValidUserFacingKinds } from "./kind-suggest.js";
+import { visitManifest as runVisitManifest, type ManifestVisitor } from "./manifest-visitor.js";
 import { isRefEntry, isScopeEntry } from "./reference-field-map.js";
 import type { AnalysisContext } from "./types.js";
 
@@ -62,6 +63,25 @@ export class AnalysisRegistry {
     }
   }
 
+  /**
+   * Walks a manifest's annotation sites (refs, scopes, schema-from, CEL) via
+   * the shared manifest visitor, bound to this registry's definitions and
+   * aliases. The public seam for hosts (editor overview graph, tooling) that
+   * need the same site discovery the analyzer's own passes use, without
+   * reaching into the internal DefinitionRegistry.
+   */
+  visitManifest(
+    resources: ResourceManifest[],
+    visitor: ManifestVisitor,
+    opts?: { skipKinds?: ReadonlySet<string>; expand?: boolean },
+  ): void {
+    runVisitManifest(resources, this.defs, visitor, {
+      aliases: this.aliases,
+      aliasesByModule: this.aliasesByModule,
+      ...opts,
+    });
+  }
+
   /**
    * Returns the built-in kernel definitions. The underlying DefinitionRegistry already
    * seeds these on construction; this method exposes them so callers (e.g. the kernel's

package/src/analyzer.ts

@@ -1,6 +1,6 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { Environment } from "@marcbachmann/cel-js";
-import { defaultRegistry, walkCelExpressions } from "@telorun/templating";
+import { defaultRegistry, isTaggedSentinel } from "@telorun/templating";
 import { AliasResolver } from "./alias-resolver.js";
 import { AnalysisRegistry } from "./analysis-registry.js";
 import {
@@ -12,6 +12,7 @@ import { DefinitionRegistry } from "./definition-registry.js";
 import { buildDependencyGraph, formatCycle } from "./dependency-graph.js";
 import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kernel-globals.js";
 import { computeSuggestKind } from "./kind-suggest.js";
+import { visitManifest } from "./manifest-visitor.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
@@ -25,14 +26,17 @@ import {
 } from "./schema-compat.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
+  extractContextsFromSchema,
   getManifestItem,
   pathMatchesScope,
   resolveContextAnnotations,
   resolveTypeFieldToSchema,
 } from "./validate-cel-context.js";
 import { validateExtends } from "./validate-extends.js";
+import { validateNestedInlineResources } from "./validate-nested-inline.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
+import { validateUnusedDeclarations } from "./validate-unused-declarations.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
 const SELF_PREFIX = "Self.";
@@ -186,56 +190,6 @@ function manifestRootForResolver(
   };
 }
 
-/**
- * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
- * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —
- * the same format the analyzer uses for CEL context validation.
- *
- * Result is sorted by scope specificity (longer scope first) so that the
- * per-expression resolver's first-match-wins logic picks the most-specific
- * context. Without this, a broader ancestor scope (e.g. `$.resources[*]`)
- * could shadow a narrower descendant scope whose activation differs.
- */
-function extractContextsFromSchema(
-  schema: Record<string, any>,
-  path = "$",
-): Array<{ scope: string; schema: Record<string, any> }> {
-  const all = collectContexts(schema, path);
-  return all.sort((a, b) => b.scope.length - a.scope.length);
-}
-
-function collectContexts(
-  schema: Record<string, any>,
-  path: string,
-): Array<{ scope: string; schema: Record<string, any> }> {
-  if (!schema || typeof schema !== "object") return [];
-  const results: Array<{ scope: string; schema: Record<string, any> }> = [];
-
-  if (schema["x-telo-context"]) {
-    results.push({ scope: path, schema: schema["x-telo-context"] });
-  }
-
-  if (schema.properties) {
-    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
-      results.push(...collectContexts(value, `${path}.${key}`));
-    }
-  }
-
-  if (schema.items && typeof schema.items === "object") {
-    results.push(...collectContexts(schema.items, `${path}[*]`));
-  }
-
-  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
-    if (Array.isArray(schema[key])) {
-      for (const subschema of schema[key]) {
-        results.push(...collectContexts(subschema, path));
-      }
-    }
-  }
-
-  return results;
-}
-
 /** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
  *  Non-refs and unresolved refs pass through unchanged. */
 function resolveLocalRef(
@@ -438,20 +392,31 @@ function collectCelTypeIssues(
   manifest: ResourceManifest,
   baseTypedEnv: Environment,
   rootEnv: Environment,
+  rootModuleManifest?: ResourceManifest,
 ): SchemaIssue[] {
   const issues: SchemaIssue[] = [];
 
-  if (typeof data === "string" && CEL_PURE_RE.test(data)) {
-    const exprMatch = data.match(CEL_EXPR_RE);
-    if (exprMatch) {
-      const expr = exprMatch[1].trim();
+  // A pure CEL value type-checks the same regardless of surface form: a
+  // `${{ … }}` string and a `!cel`-tagged sentinel must behave identically.
+  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;
+    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);
+          typedEnv = buildTypedCelEnvironment(rootEnv, manifest, ctx.schema, rootModuleManifest);
           break;
         }
       }
@@ -474,8 +439,9 @@ function collectCelTypeIssues(
       } 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 '${schema.type ?? "unknown"}'`,
+            message: `CEL returns '${checkResult.type}' but field expects '${expected}'`,
             path,
           });
         }
@@ -496,6 +462,7 @@ function collectCelTypeIssues(
           manifest,
           baseTypedEnv,
           rootEnv,
+          rootModuleManifest,
         ),
       );
     }
@@ -511,6 +478,7 @@ function collectCelTypeIssues(
           manifest,
           baseTypedEnv,
           rootEnv,
+          rootModuleManifest,
         ),
       );
     }
@@ -698,6 +666,32 @@ export class StaticAnalyzer {
       }
     }
 
+    // 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
+    // kind — surface the broken schema once, anchored on the definition itself.
+    for (const m of allManifests) {
+      if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract") continue;
+      const schema = (m as Record<string, any>).schema;
+      if (!schema || typeof schema !== "object") continue;
+      const name = m.metadata?.name as string | undefined;
+      if (!name) continue;
+      const compileError = defs.schemaCompileError(schema as Record<string, any>);
+      if (compileError) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "SCHEMA_COMPILE_ERROR",
+          source: SOURCE,
+          message: `${m.kind}/${name}: definition schema failed to compile: ${compileError}`,
+          data: {
+            resource: { kind: m.kind, name },
+            filePath: (m.metadata as { source?: string } | undefined)?.source,
+            path: "schema",
+          },
+        });
+      }
+    }
+
     // Library env: rejection — `env:` on a Library `variables` / `secrets`
     // entry is forbidden. The Library entry schema is otherwise open so that
     // any JSON Schema property schema is valid; this targeted check produces
@@ -731,6 +725,13 @@ export class StaticAnalyzer {
     // recognises variables, secrets, resources, env automatically
     const kernelGlobals = buildKernelGlobalsSchema(allManifests);
 
+    // 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.
+    const moduleManifest =
+      allManifests.find((mm) => mm.kind === "Telo.Application") ??
+      allManifests.find((mm) => mm.kind === "Telo.Library");
+
     // Validate each non-definition, non-system resource
     for (const m of allManifests) {
       const filePath = (m.metadata as { source?: string } | undefined)?.source;
@@ -789,8 +790,17 @@ export class StaticAnalyzer {
               }
             : definition.schema;
         // Phase 1: CEL type checking — walk data+schema together, check env.check() return types
-        const baseTypedEnv = buildTypedCelEnvironment(this.celEnv, m);
-        const celIssues = collectCelTypeIssues(m, schema, "", definition, m, baseTypedEnv, this.celEnv);
+        const baseTypedEnv = buildTypedCelEnvironment(this.celEnv, m, undefined, moduleManifest);
+        const celIssues = collectCelTypeIssues(
+          m,
+          schema,
+          "",
+          definition,
+          m,
+          baseTypedEnv,
+          this.celEnv,
+          moduleManifest,
+        );
         // Phase 2+3: AJV on substituted data — CEL fields replaced with typed placeholders
         const ajvIssues = validateAgainstSchema(substituteCelFields(m, schema), schema);
         const issues = [...celIssues, ...ajvIssues];
@@ -805,6 +815,39 @@ export class StaticAnalyzer {
         }
       }
 
+      // Validate inline resources nested inside this resource's body (e.g. a
+      // Run.Sequence step's `invoke: { kind, ...config }`). These sit at
+      // x-telo-ref slots reached only through local `$ref`s, which the
+      // reference field map intentionally does not follow, so they escape both
+      // inline-extraction and the per-resource schema check above.
+      if (definition.schema) {
+        // Resolve inline kinds in the parent resource's scope: direct kind
+        // first, then the parent module's own aliases (for resources declared
+        // inside an imported module), then the root aliases. Mirrors how the
+        // analyzer resolves kinds elsewhere so module-scoped aliases don't
+        // produce false UNDEFINED_KIND diagnostics.
+        const ownModule = (m.metadata as { module?: string } | undefined)?.module;
+        const scopeResolver =
+          ownModule && !rootModules.has(ownModule) ? aliasesByModule.get(ownModule) : undefined;
+        diagnostics.push(
+          ...validateNestedInlineResources(
+            m,
+            definition.schema as Record<string, any>,
+            (kind: string) => {
+              const direct = defs.resolve(kind);
+              if (direct) return direct;
+              const viaScope = scopeResolver?.resolveKind(kind);
+              if (viaScope) {
+                const scoped = defs.resolve(viaScope);
+                if (scoped) return scoped;
+              }
+              const viaRoot = aliases.resolveKind(kind);
+              return viaRoot ? defs.resolve(viaRoot) : undefined;
+            },
+          ),
+        );
+      }
+
       // (Invocation context compatibility check is handled via x-telo-context in the CEL pass below)
     }
 
@@ -899,114 +942,127 @@ export class StaticAnalyzer {
       }
     }
 
-    // Validate CEL syntax and context variable access in all manifests
-    for (const m of allManifests) {
-      const resource = { kind: m.kind, name: m.metadata?.name as string };
-      const filePath = (m.metadata as { source?: string } | undefined)?.source;
-
-      const resolvedKind = aliases.resolveKind(m.kind);
-      const mDefinition =
-        defs.resolve(m.kind) ?? (resolvedKind ? defs.resolve(resolvedKind) : undefined);
-
-      // Pre-compute step context for manifests with x-telo-step-context
-      const stepContextSchema = mDefinition?.schema
-        ? buildStepContextSchema(
-            m as Record<string, any>,
-            mDefinition.schema as Record<string, any>,
-            allManifests as Record<string, any>[],
-            defs,
-            aliases,
-          )
-        : undefined;
-
-      walkCelExpressions(m, "", (expr, path, engineName) => {
-        // Resolve the effective context for this expression's path. The
-        // engine receives a single closed schema and validates member-access
-        // chains against it; per-path resolution (step context, x-telo-context,
-        // kernel-globals merge) stays on the analyzer side because it depends
-        // on analyzer-internal state (definitions, aliases).
-        const contexts = mDefinition?.schema ? extractContextsFromSchema(mDefinition.schema) : [];
-        const invocationContext = (m.metadata as any)?.xTeloInvocationContext as
-          | Record<string, any>
-          | undefined;
-
-        let matchedContext: Record<string, any> | undefined;
-        let matchedScope: string | undefined;
-        for (const ctx of contexts) {
-          if (pathMatchesScope(path, ctx.scope)) {
-            matchedContext = ctx.schema;
-            matchedScope = ctx.scope;
-            break;
+    // Validate CEL syntax and context variable access in all manifests. The
+    // walker discovers every compiled CEL node by scanning the value tree and
+    // hands back the `x-telo-context` schema matched at the enclosing path; the
+    // per-path resolution (step context, kernel-globals merge, x-telo-context-*
+    // annotation resolution) stays here because it depends on analyzer-internal
+    // state (definitions, aliases, the typed CEL env).
+    // Per-resource state computed at enter and read by that resource's CEL
+    // sites. The manifest / resource / filePath come straight off each CelSite's
+    // `source` (no need to capture them); only the derived step / invocation
+    // context — which require analyzer state to build — are stashed here.
+    let celStepContextSchema: Record<string, any> | undefined;
+    let celInvocationContext: Record<string, any> | undefined;
+
+    visitManifest(
+      allManifests,
+      defs,
+      {
+        onResourceEnter: (e) => {
+          const m = e.source;
+          celInvocationContext = (m.metadata as any)?.xTeloInvocationContext as
+            | Record<string, any>
+            | undefined;
+          celStepContextSchema = e.definition?.schema
+            ? buildStepContextSchema(
+                m as Record<string, any>,
+                e.definition.schema as Record<string, any>,
+                allManifests as Record<string, any>[],
+                defs,
+                aliases,
+              )
+            : undefined;
+        },
+        onCel: (e) => {
+          const m = e.source;
+          const resource = { kind: m.kind, name: m.metadata?.name as string };
+          const filePath = (m.metadata as { source?: string } | undefined)?.source;
+          const { expr, path, engineName, matchedScope } = e;
+
+          let matchedContext: Record<string, any> | undefined =
+            e.contextSchema ?? celInvocationContext;
+
+          if (celStepContextSchema) {
+            const base =
+              matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
+            matchedContext = {
+              ...base,
+              properties: {
+                ...(base.properties ?? {}),
+                steps: celStepContextSchema,
+              },
+            };
           }
-        }
-        if (!matchedContext) matchedContext = invocationContext;
-
-        if (stepContextSchema) {
-          const base = matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
-          matchedContext = {
-            ...base,
-            properties: {
-              ...(base.properties ?? {}),
-              steps: stepContextSchema,
-            },
-          };
-        }
-
-        let effectiveContext: Record<string, any> | null = null;
-        if (matchedContext) {
-          const manifestItem = matchedScope
-            ? getManifestItem(path, matchedScope, m as Record<string, any>)
-            : (m as Record<string, any>);
-          const rootForResolver = manifestRootForResolver(
-            m as Record<string, any>,
-            defs,
-            aliases,
-            allManifests as Record<string, any>[],
-          );
-          const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, {
-            manifestRoot: rootForResolver,
-            defs,
-            aliases,
-            allManifests: allManifests as Record<string, any>[],
-          });
-          effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
-        }
 
-        const engine = defaultRegistry().get(engineName);
-        if (!engine) return;
-        const findings = engine.analyze(expr, { celEnv: this.celEnv, contextSchema: effectiveContext });
-        for (const f of findings) {
-          if (f.code === "CEL_SYNTAX_ERROR") {
-            diagnostics.push({
-              severity: DiagnosticSeverity.Error,
-              code: "CEL_SYNTAX_ERROR",
-              source: SOURCE,
-              message: `CEL syntax error at ${path}: ${f.message}`,
-              data: { resource, filePath, path },
-            });
-          } else if (f.code === "CEL_UNKNOWN_FIELD") {
-            diagnostics.push({
-              severity: DiagnosticSeverity.Error,
-              code: "CEL_UNKNOWN_FIELD",
-              source: SOURCE,
-              message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
-              data: { resource, filePath, path },
+          let effectiveContext: Record<string, any> | null = null;
+          if (matchedContext) {
+            const manifestItem = matchedScope
+              ? getManifestItem(path, matchedScope, m as Record<string, any>)
+              : (m as Record<string, any>);
+            const rootForResolver = manifestRootForResolver(
+              m as Record<string, any>,
+              defs,
+              aliases,
+              allManifests as Record<string, any>[],
+            );
+            const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, {
+              manifestRoot: rootForResolver,
+              defs,
+              aliases,
+              allManifests: allManifests as Record<string, any>[],
             });
-          } 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.
+            effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
+          }
+
+          const engine = defaultRegistry().get(engineName);
+          if (!engine) {
+            // No registered engine owns this tag — the expression would go
+            // entirely unanalyzed. Surface it rather than skipping silently.
             diagnostics.push({
               severity: DiagnosticSeverity.Error,
-              code: f.code ?? "ENGINE_DIAGNOSTIC",
+              code: "UNKNOWN_ENGINE",
               source: SOURCE,
-              message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
+              message: `${m.kind}/${resource.name}: no templating engine registered for '!${engineName}' at '${path}'.`,
               data: { resource, filePath, path },
             });
+            return;
           }
-        }
-      });
-    }
+          const findings = engine.analyze(expr, { celEnv: this.celEnv, contextSchema: effectiveContext });
+          for (const f of findings) {
+            if (f.code === "CEL_SYNTAX_ERROR") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "CEL_SYNTAX_ERROR",
+                source: SOURCE,
+                message: `CEL syntax error at ${path}: ${f.message}`,
+                data: { resource, filePath, path },
+              });
+            } else if (f.code === "CEL_UNKNOWN_FIELD") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "CEL_UNKNOWN_FIELD",
+                source: SOURCE,
+                message: `${m.kind}/${resource.name}: CEL at '${path}': ${f.message}`,
+                data: { resource, filePath, path },
+              });
+            } 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.
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: f.code ?? "ENGINE_DIAGNOSTIC",
+                source: SOURCE,
+                message: `${m.kind}/${resource.name}: !${engineName} at '${path}': ${f.message}`,
+                data: { resource, filePath, path },
+              });
+            }
+          }
+        },
+      },
+      { aliases },
+    );
 
     // Validate resource references (Phase 3)
     diagnostics.push(
@@ -1022,6 +1078,9 @@ export class StaticAnalyzer {
     // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
     diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv));
 
+    // Warn about declared variables / secrets / ports that no CEL references.
+    diagnostics.push(...validateUnusedDeclarations(allManifests, this.celEnv));
+
     // Reroute diagnostics on synthetic (inline-extracted) resources back to
     // the chain root so position-index lookups land on the parent doc.
     return rewriteSyntheticOrigins(diagnostics, allManifests);

package/src/builtins.ts

@@ -279,6 +279,31 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             },
           },
         },
+        // Inbound ports the Application listens on. A name-keyed map mirroring
+        // `variables`: each entry binds a host env var (`env:`) that supplies a
+        // port integer (implicitly typed `integer`, 1–65535), with an optional
+        // `default:` used when the env var is unset. `protocol:` (default `tcp`)
+        // selects the transport — the runner reads this list to know the
+        // exposed ports before launch, and the analyzer brands the resolved
+        // `ports.<name>` value (tcp → TcpPort, udp → UdpPort) for static wiring
+        // checks. Application-only. See kernel/nodejs/src/application-env.ts.
+        ports: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            required: ["env"],
+            properties: {
+              env: { type: "string" },
+              protocol: {
+                type: "string",
+                enum: ["tcp", "udp"],
+                default: "tcp",
+              },
+              default: { type: "integer", minimum: 1, maximum: 65535 },
+            },
+            additionalProperties: false,
+          },
+        },
       },
       required: ["metadata"],
       additionalProperties: false,