@telorun/analyzer 0.12.1 → 1.0.0

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,6 +26,7 @@ import {
 } from "./schema-compat.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisOptions } from "./types.js";
 import {
+  extractContextsFromSchema,
   getManifestItem,
   pathMatchesScope,
   resolveContextAnnotations,
@@ -34,6 +36,7 @@ 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.";
@@ -187,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(
@@ -426,6 +379,78 @@ function buildStepContextSchema(
   return undefined;
 }
 
+/**
+ * Collect every field annotated with `x-telo-error-context` anywhere in a
+ * definition schema (resolving local `$ref`s into `$defs`, cycle-safe), mapping
+ * the annotated field name to its declared error-shape schema. The field name
+ * is matched against CEL paths so the context applies at any nesting depth under
+ * that field — e.g. `error` inside a `catch:` nested inside another `try:`. No
+ * specific field name (or `Run.Sequence`) is hardcoded; any composer that tags
+ * its error-bearing branch fields opts in the same way.
+ */
+function collectErrorContextScopes(
+  defSchema: Record<string, any> | undefined,
+): Map<string, Record<string, any>> {
+  const out = new Map<string, Record<string, any>>();
+  if (!defSchema || typeof defSchema !== "object") return out;
+  const seen = new Set<Record<string, any>>();
+
+  const walk = (schema: Record<string, any> | undefined): void => {
+    if (!schema || typeof schema !== "object" || seen.has(schema)) return;
+    seen.add(schema);
+
+    const props = schema.properties as Record<string, any> | undefined;
+    if (props) {
+      for (const [fieldName, fieldSchema] of Object.entries(props)) {
+        if (fieldSchema && typeof fieldSchema === "object") {
+          const errCtx = (fieldSchema as Record<string, any>)["x-telo-error-context"];
+          if (errCtx && typeof errCtx === "object" && !out.has(fieldName)) {
+            out.set(fieldName, errCtx as Record<string, any>);
+          }
+        }
+        walk(resolveLocalRef(fieldSchema as Record<string, any>, defSchema));
+      }
+    }
+    if (schema.items) walk(resolveLocalRef(schema.items as Record<string, any>, defSchema));
+    for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+      const arr = schema[key];
+      if (Array.isArray(arr)) for (const sub of arr) walk(resolveLocalRef(sub, defSchema));
+    }
+    if (schema.$defs && typeof schema.$defs === "object") {
+      for (const sub of Object.values(schema.$defs as Record<string, any>)) {
+        walk(sub as Record<string, any>);
+      }
+    }
+  };
+
+  walk(defSchema);
+  return out;
+}
+
+/**
+ * Return the error-context schema for a CEL `path` when the path lies within
+ * (any depth under) one of the error-bearing fields, else undefined. A path is
+ * "within" field `f` when it contains a segment `f[<index>]`. When multiple
+ * error-bearing fields match (e.g. a `finally` nested inside a `catch`), the
+ * deepest — the one whose segment appears latest in the path — wins, so the
+ * innermost branch's schema governs.
+ */
+function errorContextForPath(
+  path: string,
+  scopes: Map<string, Record<string, any>>,
+): Record<string, any> | undefined {
+  let best: { index: number; schema: Record<string, any> } | undefined;
+  for (const [fieldName, schema] of scopes) {
+    const escaped = fieldName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    for (const match of path.matchAll(new RegExp(`(^|\\.)${escaped}\\[\\d+\\]`, "g"))) {
+      if (best === undefined || match.index > best.index) {
+        best = { index: match.index, schema };
+      }
+    }
+  }
+  return best?.schema;
+}
+
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 const CEL_EXPR_RE = /\$\{\{\s*([^}]+?)\s*\}\}/;
 
@@ -439,20 +464,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;
         }
       }
@@ -475,8 +511,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,
           });
         }
@@ -497,6 +534,7 @@ function collectCelTypeIssues(
           manifest,
           baseTypedEnv,
           rootEnv,
+          rootModuleManifest,
         ),
       );
     }
@@ -512,6 +550,7 @@ function collectCelTypeIssues(
           manifest,
           baseTypedEnv,
           rootEnv,
+          rootModuleManifest,
         ),
       );
     }
@@ -758,6 +797,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;
@@ -816,8 +862,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];
@@ -959,125 +1014,155 @@ 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;
+    let celErrorScopes: Map<string, Record<string, any>> = new Map();
+
+    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;
+          celErrorScopes = collectErrorContextScopes(
+            e.definition?.schema as Record<string, any> | 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);
-        }
+          // `error` is only in scope inside an error-bearing branch (e.g. a
+          // `catch:` / `finally:`), so it's merged per-path, not resource-wide.
+          const errorSchema =
+            celErrorScopes.size > 0 ? errorContextForPath(path, celErrorScopes) : undefined;
+          if (errorSchema) {
+            const base =
+              matchedContext ?? { type: "object", properties: {}, additionalProperties: true };
+            matchedContext = {
+              ...base,
+              properties: {
+                ...(base.properties ?? {}),
+                error: errorSchema,
+              },
+            };
+          }
 
-        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: "UNKNOWN_ENGINE",
-            source: SOURCE,
-            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 },
+          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 if (f.code === "CEL_NULLABLE_ACCESS") {
+              diagnostics.push({
+                severity: DiagnosticSeverity.Error,
+                code: "CEL_NULLABLE_ACCESS",
+                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(
@@ -1093,6 +1178,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

@@ -234,6 +234,66 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                 },
                 additionalProperties: true,
               },
+              // Gated reference: run() a Runnable/Service only when the
+              // `when` CEL guard holds. Discriminated by the `ref` key. `ref`
+              // is a bare name or a resolved `!ref` (`{ kind, name }`).
+              {
+                type: "object",
+                required: ["ref"],
+                properties: {
+                  ref: {
+                    anyOf: [
+                      { type: "string", "x-telo-ref": "telo#Runnable" },
+                      { type: "string", "x-telo-ref": "telo#Service" },
+                      {
+                        type: "object",
+                        required: ["kind", "name"],
+                        properties: {
+                          kind: { type: "string" },
+                          name: { type: "string" },
+                        },
+                        additionalProperties: true,
+                      },
+                    ],
+                  },
+                  when: { type: "string" },
+                },
+                additionalProperties: false,
+              },
+              // Inline flat invoke step: invoke an Invocable / Runnable on boot
+              // with an optional `name` (for steps.<name>.result plumbing),
+              // `when` guard, and `inputs`. Discriminated by the `invoke` key.
+              // Control flow (if/while/switch/try) is not available here —
+              // reach for Run.Sequence. `invoke` is ref-only and must resolve
+              // to a `{ kind, name }` reference (a `!ref` / `{kind,name}`):
+              // requiring `name` rejects an inline `{ kind }` definition (no
+              // name) at analysis instead of failing at boot with an undefined
+              // resource name. The Invocable/Runnable kind set mirrors
+              // Run.Sequence invoke steps.
+              {
+                type: "object",
+                required: ["invoke"],
+                properties: {
+                  name: { type: "string" },
+                  invoke: {
+                    "x-telo-topology-role": "invoke",
+                    type: "object",
+                    required: ["kind", "name"],
+                    properties: {
+                      kind: { type: "string" },
+                      name: { type: "string" },
+                    },
+                    additionalProperties: true,
+                    anyOf: [
+                      { "x-telo-ref": "telo#Invocable" },
+                      { "x-telo-ref": "telo#Runnable" },
+                    ],
+                  },
+                  inputs: { type: "object", additionalProperties: true },
+                  when: { type: "string" },
+                },
+                additionalProperties: false,
+              },
             ],
           },
         },
@@ -279,6 +339,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,