@telorun/analyzer 0.12.1 → 1.0.0

package/dist/analysis-registry.d.ts

@@ -1,4 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { type ManifestVisitor } from "./manifest-visitor.js";
 import type { AnalysisContext } from "./types.js";
 /**
  * Accumulates type and alias knowledge for a running kernel or analysis session.
@@ -22,6 +23,18 @@ export declare class AnalysisRegistry {
      * sub-schema (e.g. Server.notFoundHandler.returns[].content[mime].encoder).
      */
     iterateFieldEntries(resource: ResourceManifest, onRef: (fieldPath: string) => void, onScope: (fieldPath: string) => void): void;
+    /**
+     * 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;
+        discoverNestedRefs?: boolean;
+    }): void;
     /**
      * 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/dist/analysis-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAIjD,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;OAOG;IACH,mBAAmB,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAkBP;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAM/D,QAAQ,IAAI,MAAM,EAAE;IAIpB;mEAC+D;IAC/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC;;;gCAG4B;IAC5B,oBAAoB,IAAI,MAAM,EAAE;IAIhC;wEACoE;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD;;;;;gEAK4D;IAC5D,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IA+B7D,qFAAqF;IACrF,QAAQ,IAAI,eAAe;CAG5B"}
+{"version":3,"file":"analysis-registry.d.ts","sourceRoot":"","sources":["../src/analysis-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKzE,OAAO,EAAqC,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAEhG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA4B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoC;IAEpE,kBAAkB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI;IAIjD,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAIpE,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIpE,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI7C;;;;;;;OAOG;IACH,mBAAmB,CACjB,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,GACnC,IAAI;IAkBP;;;;;;OAMG;IACH,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,EACxB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAE,GACzF,IAAI;IAQP;;;;OAIG;IACH,kBAAkB,IAAI,kBAAkB,EAAE;IAI1C,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAM/D,QAAQ,IAAI,MAAM,EAAE;IAIpB;mEAC+D;IAC/D,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAIxC;;;gCAG4B;IAC5B,oBAAoB,IAAI,MAAM,EAAE;IAIhC;wEACoE;IACpE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD;;;;;gEAK4D;IAC5D,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IA+B7D,qFAAqF;IACrF,QAAQ,IAAI,eAAe;CAG5B"}

package/dist/analysis-registry.js

@@ -2,6 +2,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 } from "./manifest-visitor.js";
 import { isRefEntry, isScopeEntry } from "./reference-field-map.js";
 /**
  * Accumulates type and alias knowledge for a running kernel or analysis session.
@@ -46,6 +47,20 @@ 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, visitor, opts) {
+        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/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAgB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAif/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAoiBvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAexF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAiB9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAuhB/F,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;gBAEzB,OAAO,GAAE,qBAA0B;IAI/C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAqlBvB,aAAa,CACX,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAMvB,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE,EAAE,QAAQ,EAAE,gBAAgB,GAAG,gBAAgB,EAAE;IAexF,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,gBAAgB,GACzB;QAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAsB5F"}

package/dist/analyzer.js

@@ -1,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;
@@ -625,6 +668,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;
@@ -678,8 +726,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 +839,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 +937,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 +959,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 +969,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);

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,EAsZ/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,

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"}