@telorun/analyzer 0.12.1 → 1.0.0

package/dist/resolve-throws-union.js

@@ -1,3 +1,8 @@
+import { isTaggedSentinel } from "@telorun/templating";
+/** Code a non-`InvokeError` failure surfaces as inside a `catch` block. Mirrors
+ *  `PLAIN_ERROR_CODE` in `@telorun/run`'s `toSequenceError`: any invoke can throw
+ *  a plain error, which the catch sees as `error.code === "INTERNAL_ERROR"`. */
+export const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
 export function createResolveCtx(allManifests, defs, aliases) {
     return {
         allManifests,
@@ -17,6 +22,8 @@ function unionInto(target, src) {
     }
     if (src.unbounded)
         target.unbounded = true;
+    if (src.canThrowPlain)
+        target.canThrowPlain = true;
 }
 function definitionFor(kind, defs, aliases) {
     const resolved = aliases.resolveKind(kind);
@@ -115,7 +122,11 @@ function collectStepArrayThrows(steps, invokeField, enclosingTryCodes, ctx) {
  *  composers that reuse those shape conventions work without changes here. */
 function collectStepThrows(step, invokeField, enclosingTryCodes, ctx) {
     if (step[invokeField]) {
-        return resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx);
+        // Any invoked resource can throw a non-InvokeError at runtime, which an
+        // enclosing catch surfaces as PLAIN_ERROR_CODE — record that possibility.
+        const u = cloneUnion(resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx));
+        u.canThrowPlain = true;
+        return u;
     }
     if (step.throw && typeof step.throw === "object") {
         return resolveThrowStepCode(step.throw, enclosingTryCodes);
@@ -128,6 +139,11 @@ function collectStepThrows(step, invokeField, enclosingTryCodes, ctx) {
             // out instead. Sequence-specific subtraction — the plan explicitly
             // anchors this to Run.Sequence's try/catch schema shape.
             const tryCodes = new Set(tryUnion.codes.keys());
+            // A plain (non-InvokeError) failure in the try block reaches the catch as
+            // `error.code === PLAIN_ERROR_CODE`, so a `throw: { code: error.code }`
+            // rethrow can propagate it — seed the set the catch resolves against.
+            if (tryUnion.canThrowPlain)
+                tryCodes.add(PLAIN_ERROR_CODE);
             propagated = collectStepArrayThrows(step.catch, invokeField, tryCodes, ctx);
             // Unbounded in the try block still signals the caller to expect
             // arbitrary codes to flow through the catch (e.g. via passthrough).
@@ -179,6 +195,8 @@ function cloneUnion(u) {
     for (const [c, m] of u.codes)
         out.codes.set(c, m);
     out.unbounded = u.unbounded;
+    if (u.canThrowPlain)
+        out.canThrowPlain = true;
     return out;
 }
 function resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx) {
@@ -226,14 +244,24 @@ function resolveThrowStepCode(throwSpec, enclosingTryCodes) {
     return resolveCodeExpression(throwSpec.code, enclosingTryCodes);
 }
 function resolveCodeExpression(codeInput, enclosingTryCodes) {
-    if (typeof codeInput !== "string" || codeInput.length === 0) {
-        return { codes: new Map(), unbounded: true };
+    // A `!cel`-tagged sentinel and a `${{ … }}` string must resolve identically —
+    // normalize both to the inner CEL expression (or a bare literal code).
+    let expr;
+    if (isTaggedSentinel(codeInput)) {
+        if (codeInput.engine !== "cel")
+            return { codes: new Map(), unbounded: true };
+        expr = codeInput.source.trim();
     }
-    const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
-    if (!match) {
-        return { codes: new Map([[codeInput, {}]]), unbounded: false };
+    else if (typeof codeInput === "string" && codeInput.length > 0) {
+        const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
+        if (!match) {
+            return { codes: new Map([[codeInput, {}]]), unbounded: false };
+        }
+        expr = match[1].trim();
+    }
+    else {
+        return { codes: new Map(), unbounded: true };
     }
-    const expr = match[1].trim();
     const litMatch = expr.match(/^'([^']+)'$|^"([^"]+)"$/);
     if (litMatch) {
         const code = litMatch[1] ?? litMatch[2];

package/dist/schema-compat.d.ts

@@ -35,6 +35,16 @@ export declare function navigateJsonPointer(schema: unknown, pointer: string): u
  *  Stops and returns the current node when a union type (`anyOf`/`oneOf`) is reached.
  *  Returns `undefined` if any segment cannot be resolved. */
 export declare function navigateSchemaToExprPath(schema: Record<string, any>, path: string): Record<string, any> | undefined;
+/**
+ * Recognized `x-telo-type` value brands and the CEL primitive each refines.
+ * A brand is a nominal type the analyzer registers (see cel-environment.ts) so
+ * structurally-identical values (a `TcpPort` and a `UdpPort` are both integers)
+ * stay distinct for static wiring checks. Brands carry no runtime effect — the
+ * value flows as its base type. Add new brands here (e.g. `Url: "string"`).
+ */
+export declare const VALUE_BRAND_BASE: Record<string, string>;
+/** Read a recognized `x-telo-type` brand off a schema, or undefined. */
+export declare function brandOfSchema(schema: Record<string, any> | undefined): string | undefined;
 /** Map a JSON Schema type annotation to a CEL type string. */
 export declare function jsonSchemaToCelType(schema: Record<string, any> | undefined): string;
 /** Check whether a CEL return type is compatible with a JSON Schema type constraint. */

package/dist/schema-compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;;;;;;;mCAOmC;AACnC,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAOpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CAmB/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAuBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAqBhG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AAID,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOtG;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAUlF;AAED;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CAqCT"}
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"AAIA,QAAA,MAAM,GAAG,KAA0C,CAAC;AAEpD;;;;;;;mCAOmC;AACnC,wBAAgB,SAAS,IAAI,YAAY,CAAC,OAAO,GAAG,CAAC,CAOpD;AAKD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;oEAEoE;AACpE,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,mBAAmB,CAIrB;AAiDD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAelD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGxE;AAuBD,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,EAAE,CAmB/F;AAED;qFACqF;AACrF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQ7E;AAED;;;;6DAI6D;AAC7D,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGnD,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGzF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,MAAM,CAyBnF;AAED,wFAAwF;AACxF,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiChG;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAiB5E;AAID,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOtG;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAUlF;AAED;iGACiG;AACjG,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,OAAO,CAqCT"}

package/dist/schema-compat.js

@@ -172,10 +172,29 @@ export function navigateSchemaToExprPath(schema, path) {
     }
     return current;
 }
+/**
+ * Recognized `x-telo-type` value brands and the CEL primitive each refines.
+ * A brand is a nominal type the analyzer registers (see cel-environment.ts) so
+ * structurally-identical values (a `TcpPort` and a `UdpPort` are both integers)
+ * stay distinct for static wiring checks. Brands carry no runtime effect — the
+ * value flows as its base type. Add new brands here (e.g. `Url: "string"`).
+ */
+export const VALUE_BRAND_BASE = {
+    TcpPort: "int",
+    UdpPort: "int",
+};
+/** Read a recognized `x-telo-type` brand off a schema, or undefined. */
+export function brandOfSchema(schema) {
+    const brand = schema?.["x-telo-type"];
+    return typeof brand === "string" && brand in VALUE_BRAND_BASE ? brand : undefined;
+}
 /** Map a JSON Schema type annotation to a CEL type string. */
 export function jsonSchemaToCelType(schema) {
     if (!schema || typeof schema !== "object")
         return "dyn";
+    const brand = brandOfSchema(schema);
+    if (brand)
+        return brand;
     if (schema.anyOf || schema.oneOf || schema.allOf)
         return "dyn";
     if (Array.isArray(schema.type))
@@ -206,6 +225,19 @@ export function jsonSchemaToCelType(schema) {
 export function celTypeSatisfiesJsonSchema(celType, schema) {
     if (celType === "dyn")
         return true;
+    // Nominal value brands: when the expression's type is a recognized brand,
+    // a branded consuming field must match exactly (a UdpPort wired into a
+    // TcpPort-branded field is the error we want). An unbranded field accepts
+    // the brand as its base type — gradual typing, so a TcpPort flows freely
+    // into a plain integer field. (A plain integer into a branded field is also
+    // allowed: only a *conflicting* brand is rejected.)
+    const sourceBase = VALUE_BRAND_BASE[celType];
+    if (sourceBase) {
+        const fieldBrand = brandOfSchema(schema);
+        if (fieldBrand)
+            return fieldBrand === celType;
+        celType = sourceBase;
+    }
     if (!schema.type && !schema.anyOf && !schema.oneOf && !schema.allOf)
         return true;
     if (schema.anyOf || schema.oneOf || schema.allOf)

package/dist/validate-cel-context.d.ts

@@ -83,4 +83,18 @@ export declare function resolveContextAnnotations(schema: Record<string, any>, m
  * e.g. exprPath="routes[0].inputs.q", scope="$.routes[*].inputs" → manifest.routes[0]
  */
 export declare function getManifestItem(exprPath: string, scope: string, manifest: Record<string, any>): Record<string, any>;
+/**
+ * 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.
+ */
+export declare function extractContextsFromSchema(schema: Record<string, any>, path?: string): Array<{
+    scope: string;
+    schema: Record<string, any>;
+}>;
 //# sourceMappingURL=validate-cel-context.d.ts.map

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqGrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CA6BjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqGrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD"}

package/dist/validate-cel-context.js

@@ -219,3 +219,41 @@ function navigatePath(obj, segments) {
     }
     return cur;
 }
+/**
+ * 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.
+ */
+export 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;
+}

package/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAKrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAsbtB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAiZtB"}

package/dist/validate-references.js

@@ -1,5 +1,6 @@
 import { isRefSentinel } from "@telorun/templating";
-import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues } from "./reference-field-map.js";
+import { visitManifest } from "./manifest-visitor.js";
+import { isInlineResource, resolveFieldEntries, resolveFieldValues } from "./reference-field-map.js";
 import { navigateJsonPointer } from "./schema-compat.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity } from "./types.js";
@@ -147,142 +148,36 @@ export function validateReferences(resources, context) {
     const byName = new Map();
     for (const [name, list] of byNameAll)
         byName.set(name, list[0]);
-    for (const r of resources) {
-        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
-            continue;
-        // Use the expanded map so refs nested behind x-telo-schema-from get the
-        // same kind-check / unresolved-name validation as locally-declared refs.
-        // Falls back to the base map when aliasesByModule isn't supplied.
-        const fieldMap = aliasesByModule
-            ? registry.expandedFieldMapForResource(r, aliases, aliasesByModule)
-            : registry.getFieldMapForKind(r.kind, aliases);
-        if (!fieldMap)
-            continue;
-        const resourceLabel = `${r.kind}/${r.metadata.name}`;
-        const resourceData = { kind: r.kind, name: r.metadata.name };
-        const filePath = r.metadata?.source;
-        // Collect scope visibility prefixes (JSON Pointer → dot prefix) and their manifests.
-        // scope field path → flat array of ResourceManifest declared in that scope.
-        const scopeManifestsByPointer = new Map();
-        for (const [fieldPath, entry] of fieldMap) {
-            if (!isScopeEntry(entry))
-                continue;
-            const raw = resolveFieldValues(r, fieldPath)
-                .flatMap((v) => (Array.isArray(v) ? v : [v]))
-                .filter((v) => !!v && typeof v === "object");
-            const pointers = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
-            for (const pointer of pointers) {
-                scopeManifestsByPointer.set(pointer, raw);
-            }
-        }
-        const scopePrefixes = Array.from(scopeManifestsByPointer.keys()).map((p) => p.replace(/^\//, "").replace(/\//g, "."));
-        for (const [fieldPath, entry] of fieldMap) {
-            if (!isRefEntry(entry))
-                continue;
-            const inScope = scopePrefixes.some((prefix) => fieldPath === prefix ||
-                fieldPath.startsWith(prefix + ".") ||
-                fieldPath.startsWith(prefix + "["));
-            // Scope manifests visible to this ref path.
-            const visibleScopeManifests = [];
-            if (inScope) {
-                for (const [pointer, manifests] of scopeManifestsByPointer) {
-                    const prefix = pointer.replace(/^\//, "").replace(/\//g, ".");
-                    if (fieldPath === prefix ||
-                        fieldPath.startsWith(prefix + ".") ||
-                        fieldPath.startsWith(prefix + "[")) {
-                        visibleScopeManifests.push(...manifests);
-                    }
-                }
-            }
-            for (const { value: val, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
-                if (!val)
-                    continue;
-                // `!ref <name>` sentinel — bare resource name marked at parse time as a
-                // reference. Look it up against the slot's x-telo-ref constraint exactly
-                // like the legacy bare-string path; the only difference is the value's
-                // shape (a TaggedSentinel rather than a raw string), which removed the
-                // string/inline ambiguity at the source.
-                if (isRefSentinel(val)) {
-                    const refName = val.source;
-                    const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
-                    if (!target) {
-                        diagnostics.push({
-                            severity: DiagnosticSeverity.Error,
-                            code: "UNRESOLVED_REFERENCE",
-                            source: SOURCE,
-                            message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
-                            data: { resource: resourceData, filePath, path: concretePath },
-                        });
-                        continue;
-                    }
-                    const kindErrors = checkKind(target.kind, entry, registry, aliases);
-                    if (kindErrors.length > 0) {
-                        diagnostics.push({
-                            severity: DiagnosticSeverity.Error,
-                            code: "REFERENCE_KIND_MISMATCH",
-                            source: SOURCE,
-                            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
-                            data: { resource: resourceData, filePath, path: concretePath },
-                        });
-                    }
-                    continue;
-                }
-                // Name-only reference (plain string) — look up by name to validate.
-                // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
-                // extract the resource name from the last dot segment.
-                if (typeof val === "string") {
-                    const lastDot = val.lastIndexOf(".");
-                    const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
-                    const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
-                    const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
-                    if (!target) {
-                        // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
-                        // The resource lives in the imported module's scope and can't be validated here.
-                        // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
-                        // kinds — those must be validated.
-                        if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
-                            continue;
-                        }
-                        diagnostics.push({
-                            severity: DiagnosticSeverity.Error,
-                            code: "UNRESOLVED_REFERENCE",
-                            source: SOURCE,
-                            message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
-                            data: { resource: resourceData, filePath, path: concretePath },
-                        });
-                        continue;
-                    }
-                    const kindErrors = checkKind(target.kind, entry, registry, aliases);
-                    if (kindErrors.length > 0) {
-                        diagnostics.push({
-                            severity: DiagnosticSeverity.Error,
-                            code: "REFERENCE_KIND_MISMATCH",
-                            source: SOURCE,
-                            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
-                            data: { resource: resourceData, filePath, path: concretePath },
-                        });
-                    }
-                    continue;
-                }
-                if (typeof val !== "object")
-                    continue;
-                const refVal = val;
-                // Skip inline resources — Phase 2 normalization hasn't run yet.
-                if (isInlineResource(refVal))
-                    continue;
-                // 1. Structural check
-                if (typeof refVal.kind !== "string" || typeof refVal.name !== "string") {
+    // Phase 3 — per-ref validation. The walker supplies each ref site already
+    // resolved against the schema-from-expanded field map, with its source
+    // enclosure (`inScope`) and the scope manifests visible to it — so this
+    // handler only validates, it does not re-walk.
+    visitManifest(resources, registry, {
+        onRef: (e) => {
+            const r = e.source;
+            const resourceLabel = `${r.kind}/${r.metadata.name}`;
+            const resourceData = { kind: r.kind, name: r.metadata.name };
+            const filePath = r.metadata?.source;
+            const { value: val, concretePath, entry, visibleScopeManifests } = e;
+            // `!ref <name>` sentinel — bare resource name marked at parse time as a
+            // reference. Look it up against the slot's x-telo-ref constraint exactly
+            // like the legacy bare-string path; the only difference is the value's
+            // shape (a TaggedSentinel rather than a raw string), which removed the
+            // string/inline ambiguity at the source.
+            if (isRefSentinel(val)) {
+                const refName = val.source;
+                const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+                if (!target) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
-                        code: "INVALID_REFERENCE",
+                        code: "UNRESOLVED_REFERENCE",
                         source: SOURCE,
-                        message: `${resourceLabel}: reference at '${concretePath}' must have string 'kind' and 'name' fields`,
+                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
                         data: { resource: resourceData, filePath, path: concretePath },
                     });
-                    continue;
+                    return;
                 }
-                // 2. Kind check
-                const kindErrors = checkKind(refVal.kind, entry, registry, aliases);
+                const kindErrors = checkKind(target.kind, entry, registry, aliases);
                 if (kindErrors.length > 0) {
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
@@ -292,38 +187,107 @@ export function validateReferences(resources, context) {
                         data: { resource: resourceData, filePath, path: concretePath },
                     });
                 }
-                // 3. Resolution check — resource with this name must exist.
-                const exists = byName.has(refVal.name) ||
-                    visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
-                if (!exists) {
+                return;
+            }
+            // Name-only reference (plain string) — look up by name to validate.
+            // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
+            // extract the resource name from the last dot segment.
+            if (typeof val === "string") {
+                const lastDot = val.lastIndexOf(".");
+                const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
+                const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
+                const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+                if (!target) {
+                    // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
+                    // The resource lives in the imported module's scope and can't be validated here.
+                    // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
+                    // kinds — those must be validated.
+                    if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
+                        return;
+                    }
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
                         code: "UNRESOLVED_REFERENCE",
                         source: SOURCE,
-                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${refVal.name}' not found`,
+                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
+                        data: { resource: resourceData, filePath, path: concretePath },
+                    });
+                    return;
+                }
+                const kindErrors = checkKind(target.kind, entry, registry, aliases);
+                if (kindErrors.length > 0) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "REFERENCE_KIND_MISMATCH",
+                        source: SOURCE,
+                        message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
                         data: { resource: resourceData, filePath, path: concretePath },
                     });
                 }
+                return;
             }
-        }
-    }
+            if (typeof val !== "object")
+                return;
+            const refVal = val;
+            // Skip inline resources — Phase 2 normalization hasn't run yet.
+            if (isInlineResource(refVal))
+                return;
+            // Polymorphic ref slots (Application `targets`) accept object forms
+            // whose references live in nested slots rather than being a `{kind,
+            // name}` ref themselves — inline `{ invoke }` and gated `{ ref }`.
+            // Those nested refs are validated via their own field-map entries, so
+            // skip the item-level structural check here.
+            if (typeof refVal.kind !== "string" && ("invoke" in refVal || "ref" in refVal))
+                return;
+            // 1. Structural check
+            if (typeof refVal.kind !== "string" || typeof refVal.name !== "string") {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "INVALID_REFERENCE",
+                    source: SOURCE,
+                    message: `${resourceLabel}: reference at '${concretePath}' must have string 'kind' and 'name' fields`,
+                    data: { resource: resourceData, filePath, path: concretePath },
+                });
+                return;
+            }
+            // 2. Kind check
+            const kindErrors = checkKind(refVal.kind, entry, registry, aliases);
+            if (kindErrors.length > 0) {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "REFERENCE_KIND_MISMATCH",
+                    source: SOURCE,
+                    message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+                    data: { resource: resourceData, filePath, path: concretePath },
+                });
+            }
+            // 3. Resolution check — resource with this name must exist.
+            const exists = byName.has(refVal.name) ||
+                visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
+            if (!exists) {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "UNRESOLVED_REFERENCE",
+                    source: SOURCE,
+                    message: `${resourceLabel}: reference at '${concretePath}' → resource '${refVal.name}' not found`,
+                    data: { resource: resourceData, filePath, path: concretePath },
+                });
+            }
+        },
+    }, { aliases, aliasesByModule, skipKinds: SYSTEM_KINDS, expand: true });
     // Phase 3b — x-telo-schema-from validation.
     // For each field with a schemaFrom path expression, resolve the anchor ref to get the
     // concrete kind, navigate the JSON Pointer into that kind's definition schema, and
-    // validate the field value against the resulting sub-schema.
-    for (const r of resources) {
-        if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind))
-            continue;
-        const fieldMap = registry.getFieldMapForKind(r.kind, aliases);
-        if (!fieldMap)
-            continue;
-        const resourceLabel = `${r.kind}/${r.metadata.name}`;
-        const resourceData = { kind: r.kind, name: r.metadata.name };
-        const filePath = r.metadata?.source;
-        for (const [fieldPath, entry] of fieldMap) {
-            if (!isSchemaFromEntry(entry))
-                continue;
-            const { schemaFrom } = entry;
+    // validate the field value against the resulting sub-schema. Driven off the base map
+    // (un-expanded) so each schema-from slot is seen as its own site.
+    visitManifest(resources, registry, {
+        onSchemaFrom: (e) => {
+            const r = e.source;
+            const fieldPath = e.fieldPath;
+            const resourceLabel = `${r.kind}/${r.metadata.name}`;
+            const resourceData = { kind: r.kind, name: r.metadata.name };
+            const filePath = r.metadata?.source;
+            const { schemaFrom } = e.entry;
             const isAbsolute = schemaFrom.startsWith("/");
             const expr = isAbsolute ? schemaFrom.slice(1) : schemaFrom;
             const slashIdx = expr.indexOf("/");
@@ -335,7 +299,7 @@ export function validateReferences(resources, context) {
                     message: `${resourceLabel}: x-telo-schema-from "${schemaFrom}" must contain at least one "/" to separate anchor from JSON Pointer`,
                     data: { resource: resourceData, filePath, path: fieldPath },
                 });
-                continue;
+                return;
             }
             const anchorName = expr.slice(0, slashIdx);
             const jsonPointer = "/" + expr.slice(slashIdx + 1);
@@ -360,7 +324,7 @@ export function validateReferences(resources, context) {
                         message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → cannot resolve alias '${anchorName}'`,
                         data: { resource: resourceData, filePath, path: fieldPath },
                     });
-                    continue;
+                    return;
                 }
                 const targetDef = registry.resolve(targetKind);
                 if (!targetDef?.schema) {
@@ -371,7 +335,7 @@ export function validateReferences(resources, context) {
                         message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${targetKind}' has no schema`,
                         data: { resource: resourceData, filePath, path: fieldPath },
                     });
-                    continue;
+                    return;
                 }
                 const subSchema = navigateJsonPointer(targetDef.schema, jsonPointer);
                 if (subSchema === undefined) {
@@ -382,7 +346,7 @@ export function validateReferences(resources, context) {
                         message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${targetKind}' has no schema path '${jsonPointer}'`,
                         data: { resource: resourceData, filePath, path: fieldPath },
                     });
-                    continue;
+                    return;
                 }
                 for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
                     if (fieldValue == null)
@@ -398,7 +362,7 @@ export function validateReferences(resources, context) {
                         });
                     }
                 }
-                continue;
+                return;
             }
             // Derive the anchor path in the resource config.
             let anchorPath;
@@ -413,7 +377,7 @@ export function validateReferences(resources, context) {
             }
             const anchorValues = resolveFieldValues(r, anchorPath);
             if (anchorValues.length === 0)
-                continue; // anchor field not set — nothing to validate
+                return; // anchor field not set — nothing to validate
             const fieldEntries = resolveFieldEntries(r, fieldPath);
             for (let i = 0; i < fieldEntries.length; i++) {
                 const { value: fieldValue, path: concretePath } = fieldEntries[i];
@@ -460,7 +424,7 @@ export function validateReferences(resources, context) {
                     });
                 }
             }
-        }
-    }
+        },
+    }, { aliases, aliasesByModule, skipKinds: SYSTEM_KINDS, expand: false });
     return diagnostics;
 }

package/dist/validate-unused-declarations.d.ts

@@ -0,0 +1,25 @@
+import type { Environment } from "@marcbachmann/cel-js";
+import type { ResourceManifest } from "@telorun/sdk";
+import { type AnalysisDiagnostic } from "./types.js";
+/**
+ * Warn about declared `variables` / `secrets` / `ports` entries that no CEL
+ * expression references. A declared-but-unconsumed entry is dead weight at
+ * best and misleading at worst (an unbound `ports` entry makes a runner
+ * advertise a port the app never listens on).
+ *
+ * Generic across all three namespaces. References are collected from every CEL
+ * expression (both `${{ … }}` and `!cel`, via `walkCelExpressions`) by
+ * extracting member-access chains: a `<ns>.<name>` chain marks `<name>` used.
+ * Dynamic access (`<ns>[expr]`, or the namespace passed whole, e.g.
+ * `keys(variables)`) yields a chain that stops at the namespace root — that
+ * can't be attributed to a name, so the whole namespace is conservatively
+ * suppressed to avoid false positives.
+ *
+ * Application-only: an Application's `variables` / `secrets` / `ports` flow
+ * exclusively through CEL (into resource fields, or into `Telo.Import` inputs),
+ * so unreferenced means dead. A `Telo.Library`'s `variables` / `secrets` are a
+ * public input contract consumed by its controllers — invisible to CEL
+ * analysis — so they are deliberately not flagged.
+ */
+export declare function validateUnusedDeclarations(manifests: ResourceManifest[], celEnv: Environment): AnalysisDiagnostic[];
+//# sourceMappingURL=validate-unused-declarations.d.ts.map

package/dist/validate-unused-declarations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-unused-declarations.d.ts","sourceRoot":"","sources":["../src/validate-unused-declarations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAAE,KAAK,kBAAkB,EAAsB,MAAM,YAAY,CAAC;AASzE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,MAAM,EAAE,WAAW,GAClB,kBAAkB,EAAE,CA2DtB"}