@telorun/analyzer 0.12.1 → 0.14.0

package/dist/analyzer.js

@@ -1,10 +1,11 @@
-import { defaultRegistry, walkCelExpressions } from "@telorun/templating";
+import { defaultRegistry, isTaggedSentinel } from "@telorun/templating";
 import { AliasResolver } from "./alias-resolver.js";
 import { buildCelEnvironment, buildTypedCelEnvironment, } from "./cel-environment.js";
 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";
@@ -12,11 +13,12 @@ import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import { celTypeSatisfiesJsonSchema, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { DiagnosticSeverity } from "./types.js";
-import { getManifestItem, pathMatchesScope, resolveContextAnnotations, resolveTypeFieldToSchema, } from "./validate-cel-context.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.";
 /**
@@ -142,44 +144,6 @@ function manifestRootForResolver(m, defs, aliases, allManifests) {
         ...(inputs ? { inputType: inputs } : {}),
     };
 }
-/**
- * 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, path = "$") {
-    const all = collectContexts(schema, path);
-    return all.sort((a, b) => b.scope.length - a.scope.length);
-}
-function collectContexts(schema, path) {
-    if (!schema || typeof schema !== "object")
-        return [];
-    const results = [];
-    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)) {
-            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"]) {
-        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(schema, root) {
@@ -343,23 +307,101 @@ function buildStepContextSchema(manifest, defSchema, allManifests, defs, aliases
     }
     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) {
+    const out = new Map();
+    if (!defSchema || typeof defSchema !== "object")
+        return out;
+    const seen = new Set();
+    const walk = (schema) => {
+        if (!schema || typeof schema !== "object" || seen.has(schema))
+            return;
+        seen.add(schema);
+        const props = schema.properties;
+        if (props) {
+            for (const [fieldName, fieldSchema] of Object.entries(props)) {
+                if (fieldSchema && typeof fieldSchema === "object") {
+                    const errCtx = fieldSchema["x-telo-error-context"];
+                    if (errCtx && typeof errCtx === "object" && !out.has(fieldName)) {
+                        out.set(fieldName, errCtx);
+                    }
+                }
+                walk(resolveLocalRef(fieldSchema, defSchema));
+            }
+        }
+        if (schema.items)
+            walk(resolveLocalRef(schema.items, defSchema));
+        for (const key of ["oneOf", "anyOf", "allOf"]) {
+            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)) {
+                walk(sub);
+            }
+        }
+    };
+    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, scopes) {
+    let best;
+    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*\}\}/;
 /** Recursively walk `data`+`schema` together, type-checking every pure CEL template
  *  string via `env.check()`. Returns `SchemaIssue[]` for any type mismatches found. */
-function collectCelTypeIssues(data, schema, path, definition, manifest, baseTypedEnv, rootEnv) {
+function collectCelTypeIssues(data, schema, path, definition, manifest, baseTypedEnv, rootEnv, rootModuleManifest) {
     const issues = [];
-    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;
+    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;
                 }
             }
@@ -382,8 +424,9 @@ function collectCelTypeIssues(data, schema, path, definition, manifest, baseType
             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,
                     });
                 }
@@ -394,13 +437,13 @@ function collectCelTypeIssues(data, schema, path, definition, manifest, baseType
     if (Array.isArray(data)) {
         const itemSchema = (schema.items ?? {});
         for (let i = 0; i < data.length; i++) {
-            issues.push(...collectCelTypeIssues(data[i], itemSchema, `${path}[${i}]`, definition, manifest, baseTypedEnv, rootEnv));
+            issues.push(...collectCelTypeIssues(data[i], itemSchema, `${path}[${i}]`, definition, manifest, baseTypedEnv, rootEnv, rootModuleManifest));
         }
     }
     else if (data !== null && typeof data === "object") {
         const props = (schema.properties ?? {});
         for (const [k, v] of Object.entries(data)) {
-            issues.push(...collectCelTypeIssues(v, (props[k] ?? {}), path ? `${path}.${k}` : k, definition, manifest, baseTypedEnv, rootEnv));
+            issues.push(...collectCelTypeIssues(v, (props[k] ?? {}), path ? `${path}.${k}` : k, definition, manifest, baseTypedEnv, rootEnv, rootModuleManifest));
         }
     }
     return issues;
@@ -468,9 +511,12 @@ export class StaticAnalyzer {
                 // through the same alias machinery as user-declared Telo.Imports —
                 // honours the library's `exports.kinds` list, no special cases.
                 if (moduleName) {
-                    const exportedKinds = m.exports?.kinds ?? [];
+                    // `Self` resolves the library's own kinds UNGATED — a library may reference
+                    // its own kinds regardless of `exports.kinds`, which gates importers, not
+                    // internal use. This is what lets a library declare an instance of a kind it
+                    // does not export (e.g. console's `writeLine`) to enforce a singleton.
                     if (rootModules.has(moduleName)) {
-                        aliases.registerImport("Self", moduleName, exportedKinds);
+                        aliases.registerImport("Self", moduleName, []);
                     }
                     else {
                         let libResolver = aliasesByModule.get(moduleName);
@@ -478,7 +524,7 @@ export class StaticAnalyzer {
                             libResolver = new AliasResolver();
                             aliasesByModule.set(moduleName, libResolver);
                         }
-                        libResolver.registerImport("Self", moduleName, exportedKinds);
+                        libResolver.registerImport("Self", moduleName, []);
                     }
                 }
             }
@@ -625,6 +671,11 @@ export class StaticAnalyzer {
         // Build typed kernel globals schema so x-telo-context chain validation
         // 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?.source;
@@ -645,6 +696,16 @@ export class StaticAnalyzer {
             if (m.kind === "Telo.Abstract") {
                 continue;
             }
+            // Forwarded foreign exports (an imported library's exported instances, whose
+            // metadata.module isn't a root module here) were already validated in their own
+            // module's standalone analysis, and their `kind`/CEL are authored in that module's
+            // scope (e.g. `Self.X` resolves to that module, not the consumer). Re-validating them
+            // against the consumer's scope yields false UNDEFINED_KIND / scope-mismatch errors, so
+            // skip — they participate in this analysis only as cross-module resolution targets.
+            const mModule = m.metadata?.module;
+            if (typeof mModule === "string" && !rootModules.has(mModule)) {
+                continue;
+            }
             const resource = { kind: m.kind, name: m.metadata?.name };
             // Resolve kind through alias if needed; direct lookup takes priority so that
             // aliases whose name matches the module name (the common case) work without
@@ -678,8 +739,8 @@ 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];
@@ -791,42 +852,54 @@ 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 };
-            const filePath = m.metadata?.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, mDefinition.schema, allManifests, 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?.xTeloInvocationContext;
-                let matchedContext;
-                let matchedScope;
-                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;
+        let celInvocationContext;
+        let celErrorScopes = new Map();
+        visitManifest(allManifests, defs, {
+            onResourceEnter: (e) => {
+                const m = e.source;
+                celInvocationContext = m.metadata?.xTeloInvocationContext;
+                celStepContextSchema = e.definition?.schema
+                    ? buildStepContextSchema(m, e.definition.schema, allManifests, defs, aliases)
+                    : undefined;
+                celErrorScopes = collectErrorContextScopes(e.definition?.schema);
+            },
+            onCel: (e) => {
+                const m = e.source;
+                const resource = { kind: m.kind, name: m.metadata?.name };
+                const filePath = m.metadata?.source;
+                const { expr, path, engineName, matchedScope } = e;
+                let matchedContext = 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) {
+                // `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 ?? {}),
-                            steps: stepContextSchema,
+                            error: errorSchema,
                         },
                     };
                 }
@@ -877,6 +950,15 @@ export class StaticAnalyzer {
                             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
@@ -890,8 +972,8 @@ export class StaticAnalyzer {
                         });
                     }
                 }
-            });
-        }
+            },
+        }, { aliases });
         // Validate resource references (Phase 3)
         diagnostics.push(...validateReferences(allManifests, { aliases, definitions: defs, aliasesByModule }));
         // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
@@ -900,6 +982,8 @@ export class StaticAnalyzer {
         diagnostics.push(...validateProviderCoherence(allManifests, defs, aliases));
         // 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);
@@ -907,13 +991,17 @@ export class StaticAnalyzer {
     analyzeErrors(manifests, options, registry) {
         return this.analyze(manifests, options, registry).filter((d) => d.severity === DiagnosticSeverity.Error);
     }
-    normalize(manifests, registry) {
+    normalize(manifests, registry, 
+    // Forwarded foreign exports used only as cross-module resolution targets (see
+    // resolveRefSentinels). The kernel passes its analyzer-flattened set so the
+    // entry-only runtime pass can still resolve `!ref Alias.name`.
+    crossModuleTargets) {
         const ctx = registry._context();
         const normalized = normalizeInlineResources(manifests, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
         // Resolve !ref sentinels after normalize so both the original and
         // inline-extracted manifests get their refs canonicalized to
         // {kind, name} for the kernel that consumes this output.
-        resolveRefSentinels(normalized, ctx.definitions, ctx.aliases, ctx.aliasesByModule);
+        resolveRefSentinels(normalized, ctx.definitions, ctx.aliases, ctx.aliasesByModule, crossModuleTargets ?? []);
         return normalized;
     }
     prepare(manifests, registry) {

package/dist/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EAiU/C,CAAC"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,eAAO,MAAM,eAAe,EAAE,kBAAkB,EAuZ/C,CAAC"}

package/dist/builtins.js

@@ -232,6 +232,66 @@ export const KERNEL_BUILTINS = [
                                 },
                                 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,
+                            },
                         ],
                     },
                 },
@@ -277,6 +337,31 @@ export const KERNEL_BUILTINS = [
                         },
                     },
                 },
+                // 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,
@@ -311,6 +396,7 @@ export const KERNEL_BUILTINS = [
                     type: "object",
                     properties: {
                         kinds: { type: "array", items: { type: "string" } },
+                        resources: { type: "array", items: { type: "string" } },
                     },
                     additionalProperties: true,
                 },

package/dist/cel-environment.d.ts

@@ -12,5 +12,5 @@ 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): Environment;
+export declare function buildTypedCelEnvironment(baseEnv: Environment, manifest: ResourceManifest, extraContextSchema?: Record<string, any> | null, rootModuleManifest?: ResourceManifest): Environment;
 //# sourceMappingURL=cel-environment.d.ts.map

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;AAGrD,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,GAC9C,WAAW,CAyCb"}
+{"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;AAUrD,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,CAuEb"}

package/dist/cel-environment.js

@@ -1,4 +1,10 @@
-import { jsonSchemaToCelType } from "./schema-compat.js";
+import { jsonSchemaToCelType, VALUE_BRAND_BASE } from "./schema-compat.js";
+/** Transport protocol on a `ports` entry → the nominal CEL brand its resolved
+ *  value carries. Mirrors the `protocol` enum in the Application schema. */
+const PORT_PROTOCOL_BRAND = {
+    tcp: "TcpPort",
+    udp: "UdpPort",
+};
 export { buildCelEnvironment } from "@telorun/templating";
 /** Clone `baseEnv` and register typed variable declarations so that
  *  `env.check(expr)` can infer return types for expressions referencing known variables.
@@ -10,9 +16,21 @@ export { buildCelEnvironment } 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 function buildTypedCelEnvironment(baseEnv, manifest, extraContextSchema) {
+export function buildTypedCelEnvironment(baseEnv, manifest, extraContextSchema, 
+// The `ports` namespace is Application-only and lives on the module doc, not
+// on the resource being analyzed. When validating a resource, the caller
+// passes the module manifest here so `${{ ports.X }}` types cross-doc.
+rootModuleManifest) {
     try {
         const env = baseEnv.clone();
+        // Register nominal value brands (TcpPort/UdpPort/…) on the *clone* so the
+        // type-checker can distinguish structurally-identical values. The base env
+        // (shared with the kernel runtime) is untouched — a branded value flows as
+        // a plain integer at runtime, so only static checking needs these. cel-js
+        // auto-generates a field-less wrapper class; no runtime constructor needed.
+        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)) {
@@ -31,6 +49,26 @@ export function buildTypedCelEnvironment(baseEnv, manifest, extraContextSchema)
         else {
             env.registerVariable("variables", "map");
         }
+        // `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.
+        const portsManifest = (rootModuleManifest ?? manifest).ports;
+        if (portsManifest !== null && typeof portsManifest === "object" && !Array.isArray(portsManifest)) {
+            const portEntries = Object.entries(portsManifest).filter(([, v]) => v !== null && typeof v === "object" && !Array.isArray(v));
+            if (portEntries.length > 0) {
+                const schema = {};
+                for (const [k, v] of portEntries) {
+                    schema[k] = PORT_PROTOCOL_BRAND[v.protocol ?? "tcp"] ?? "int";
+                }
+                env.registerVariable({ name: "ports", schema });
+            }
+            else {
+                env.registerVariable("ports", "map");
+            }
+        }
+        else {
+            env.registerVariable("ports", "map");
+        }
         env.registerVariable("secrets", "map");
         env.registerVariable("resources", "map");
         env.registerVariable("env", "map");

package/dist/dependency-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B;kDAC8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC;oFACgF;IAChF,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACrC;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CAkHjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B;kDAC8C;IAC9C,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACpC;oFACgF;IAChF,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACrC;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,eAAe,CAmGjB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,MAAM,CAOtE"}