@telorun/analyzer 0.10.1 → 1.1.0

package/dist/normalize-inline-resources.js

@@ -60,7 +60,7 @@ export function normalizeInlineResources(resources, registry, aliases, aliasesBy
                 fieldPath.startsWith(prefix + ".") ||
                 fieldPath.startsWith(prefix + "["));
             const invocationContext = isRefEntry(entry) ? entry.context : undefined;
-            const extracted = extractInlinesAtPath(resource, fieldPath, parentName, parentModule, invocationContext);
+            const extracted = extractInlinesAtPath(resource, fieldPath, parentName, resource.kind, parentModule, invocationContext);
             for (const manifest of extracted) {
                 result.push(manifest);
                 queue.push(manifest);
@@ -75,11 +75,22 @@ export function normalizeInlineResources(resources, registry, aliases, aliasesBy
  * Walks `resource` following `fieldPath` (dot notation, `[]` = array traversal).
  * Mutates the resource in-place: replaces each inline value with `{kind, name}`.
  * Returns the extracted manifests.
+ *
+ * Each extracted manifest carries `metadata.xTeloOrigin` so downstream
+ * diagnostics can be rerouted back to the parent doc's YAML position:
+ *   - `parentKind` / `parentName` — the resource that owned the inline slot
+ *   - `pathFromParent` — concrete dotted path with `[N]` indices, matching
+ *     `buildPositionIndex` keys (e.g. `routes[0].handler`)
  */
-function extractInlinesAtPath(resource, fieldPath, parentName, parentModule, invocationContext) {
+function extractInlinesAtPath(resource, fieldPath, parentName, parentKind, parentModule, invocationContext) {
     const extracted = [];
     const parts = fieldPath.split(".");
-    function traverse(obj, partsLeft, nameParts) {
+    function emit(inline, nameSegments, concretePath) {
+        const name = sanitizeName([parentName, ...nameSegments].join("_"));
+        extracted.push(buildManifest(inline, name, parentKind, parentName, concretePath, parentModule, invocationContext));
+        return name;
+    }
+    function traverse(obj, partsLeft, nameParts, pathSoFar) {
         if (!obj || typeof obj !== "object" || partsLeft.length === 0)
             return;
         const [head, ...rest] = partsLeft;
@@ -92,15 +103,15 @@ function extractInlinesAtPath(resource, fieldPath, parentName, parentModule, inv
                 if (!elem || typeof elem !== "object")
                     continue;
                 const sanitizedKey = sanitizeName(mapKey);
+                const childPath = pathSoFar ? `${pathSoFar}.${mapKey}` : mapKey;
                 if (rest.length === 0) {
                     if (isInlineResource(elem)) {
-                        const name = sanitizeName([parentName, ...nameParts, sanitizedKey].join("_"));
-                        extracted.push(buildManifest(elem, name, parentModule, invocationContext));
+                        const name = emit(elem, [...nameParts, sanitizedKey], childPath);
                         container[mapKey] = { kind: elem.kind, name };
                     }
                 }
                 else {
-                    traverse(elem, rest, [...nameParts, sanitizedKey]);
+                    traverse(elem, rest, [...nameParts, sanitizedKey], childPath);
                 }
             }
             return;
@@ -111,6 +122,7 @@ function extractInlinesAtPath(resource, fieldPath, parentName, parentModule, inv
         const val = container[key];
         if (val == null)
             return;
+        const keyPath = pathSoFar ? `${pathSoFar}.${key}` : key;
         if (isArr) {
             if (!Array.isArray(val))
                 return;
@@ -121,16 +133,16 @@ function extractInlinesAtPath(resource, fieldPath, parentName, parentModule, inv
                 const elemId = typeof elem.name === "string"
                     ? elem.name
                     : String(idx);
+                const childPath = `${keyPath}[${idx}]`;
                 if (rest.length === 0) {
                     // Array element itself is the ref slot
                     if (isInlineResource(elem)) {
-                        const name = sanitizeName([parentName, ...nameParts, key, elemId].join("_"));
-                        extracted.push(buildManifest(elem, name, parentModule, invocationContext));
+                        const name = emit(elem, [...nameParts, key, elemId], childPath);
                         val[idx] = { kind: elem.kind, name };
                     }
                 }
                 else {
-                    traverse(elem, rest, [...nameParts, key, elemId]);
+                    traverse(elem, rest, [...nameParts, key, elemId], childPath);
                 }
             }
         }
@@ -138,20 +150,19 @@ function extractInlinesAtPath(resource, fieldPath, parentName, parentModule, inv
             if (rest.length === 0) {
                 // val is the ref slot
                 if (val && typeof val === "object" && !Array.isArray(val) && isInlineResource(val)) {
-                    const name = sanitizeName([parentName, ...nameParts, key].join("_"));
-                    extracted.push(buildManifest(val, name, parentModule, invocationContext));
+                    const name = emit(val, [...nameParts, key], keyPath);
                     container[key] = { kind: val.kind, name };
                 }
             }
             else {
-                traverse(val, rest, [...nameParts, key]);
+                traverse(val, rest, [...nameParts, key], keyPath);
             }
         }
     }
-    traverse(resource, parts, []);
+    traverse(resource, parts, [], "");
     return extracted;
 }
-function buildManifest(inline, name, parentModule, invocationContext) {
+function buildManifest(inline, name, parentKind, parentName, pathFromParent, parentModule, invocationContext) {
     const existingMeta = inline.metadata && typeof inline.metadata === "object"
         ? inline.metadata
         : {};
@@ -163,6 +174,7 @@ function buildManifest(inline, name, parentModule, invocationContext) {
             // Inherit parent module only if the inline doesn't already declare one
             ...(parentModule && !existingMeta.module ? { module: parentModule } : {}),
             ...(invocationContext ? { xTeloInvocationContext: invocationContext } : {}),
+            xTeloOrigin: { parentKind, parentName, pathFromParent },
         },
     };
 }

package/dist/position-metadata.d.ts

@@ -22,6 +22,10 @@ export declare function documentLineOffsets(text: string): number[];
  *  yaml-AST node range into Range coordinates. */
 export declare function buildLineOffsets(text: string): number[];
 /** Walks the YAML AST and records source ranges for every field value, keyed
- *  by dotted path (e.g. "kind", "config.handler", "config.routes[0].path"). */
+ *  by dotted path (e.g. "kind", "config.handler", "config.routes[0].path").
+ *  Map keys are also recorded under the `@key:<path>` namespace so diagnostic
+ *  resolvers can squiggle just the key identifier instead of the full value
+ *  block — used when a diagnostic targets a missing child property and the
+ *  resolver has to fall back to the parent. */
 export declare function buildPositionIndex(doc: Document, lineOffsets: number[]): PositionIndex;
 //# sourceMappingURL=position-metadata.d.ts.map

package/dist/position-metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"position-metadata.d.ts","sourceRoot":"","sources":["../src/position-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrE,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;oBAKoB;AAEpB,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,QAAQ,EAAE,GACrB,gBAAgB,EAAE,CAOpB;AAED;;8CAE8C;AAC9C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAED;;kDAEkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMvD;AAaD;+EAC+E;AAC/E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,aAAa,CAuCtF"}
+{"version":3,"file":"position-metadata.d.ts","sourceRoot":"","sources":["../src/position-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,QAAQ,EAAE,MAAM,MAAM,CAAC;AACrE,OAAO,KAAK,EAAY,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;oBAKoB;AAEpB,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,aAAa,CAAC;CAC9B;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,QAAQ,EAAE,GACrB,gBAAgB,EAAE,CAOpB;AAED;;8CAE8C;AAC9C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1D;AAED;;kDAEkD;AAClD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAMvD;AAaD;;;;;+CAK+C;AAC/C,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,aAAa,CA0CtF"}

package/dist/position-metadata.js

@@ -45,7 +45,11 @@ function offsetToPosition(offset, lineOffsets) {
     return { line: lo, character: offset - lineOffsets[lo] };
 }
 /** Walks the YAML AST and records source ranges for every field value, keyed
- *  by dotted path (e.g. "kind", "config.handler", "config.routes[0].path"). */
+ *  by dotted path (e.g. "kind", "config.handler", "config.routes[0].path").
+ *  Map keys are also recorded under the `@key:<path>` namespace so diagnostic
+ *  resolvers can squiggle just the key identifier instead of the full value
+ *  block — used when a diagnostic targets a missing child property and the
+ *  resolver has to fall back to the parent. */
 export function buildPositionIndex(doc, lineOffsets) {
     const index = new Map();
     function recordNode(node, path) {
@@ -66,6 +70,9 @@ export function buildPositionIndex(doc, lineOffsets) {
                 if (key == null)
                     continue;
                 const childPath = path ? `${path}.${key}` : key;
+                if (pair.key && pair.key.range) {
+                    recordNode(pair.key, `@key:${childPath}`);
+                }
                 if (pair.value != null) {
                     recordNode(pair.value, childPath);
                     walk(pair.value, childPath);

package/dist/reference-field-map.d.ts

@@ -43,12 +43,29 @@ export declare const REFERENCE_KEYS: Set<string>;
  *  A named reference (has string `name`) may carry extra keys (e.g. `inputs`)
  *  that are runtime call parameters — those are never inline resources. */
 export declare function isInlineResource(val: Record<string, unknown>): boolean;
-/** Resolves all values at a field map path in a resource config.
- *  Path-segment markers:
- *   - `[]`  iterate array values at this key
+/** A value found at a field-map path, paired with the concrete path that
+ *  produced it. `path` has every `[]` substituted with `[N]` and every `{}`
+ *  substituted with the actual map key, matching the format produced by
+ *  `buildPositionIndex`. Used so diagnostics emitted against a specific
+ *  array element / map entry can be resolved back to a YAML range. */
+export interface ResolvedFieldEntry {
+    value: unknown;
+    path: string;
+}
+/** Resolves all `{value, path}` entries at a field map path in a resource
+ *  config. The returned `path` is the concrete dotted path produced by the
+ *  substitutions below, matching the format `buildPositionIndex` keys on.
+ *  Path-segment markers accepted in the input `path`:
+ *   - `[]`  iterate array values at this key, substituting `[N]` per item
+ *           (e.g. `routes[]` → `routes[0]`, `routes[1]`, …).
  *   - `{}`  iterate map values (every value in an `additionalProperties`-typed
  *           object — used for fields like `content[mime]` whose schema declares
- *           a key-as-MIME map). The path is `<key>.{}.<rest>`. */
+ *           a key-as-MIME map). Substituted with the literal map key joined by
+ *           a dot, so the input `content.{}.encoder` yields concrete paths
+ *           like `content.application/json.encoder`. */
+export declare function resolveFieldEntries(obj: unknown, path: string): ResolvedFieldEntry[];
+/** Backwards-compat wrapper that drops the concrete path. Prefer
+ *  `resolveFieldEntries` for new code that wants positions. */
 export declare function resolveFieldValues(obj: unknown, path: string): unknown[];
 /**
  * Traverses a definition's JSON Schema once and returns a field map recording every

package/dist/reference-field-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reference-field-map.d.ts","sourceRoot":"","sources":["../src/reference-field-map.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;sDACkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0FAA0F;IAC1F,OAAO,EAAE,OAAO,CAAC;IACjB;8DAC0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B;2CACuC;IACvC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED;8CAC8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC;;qFAEiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEnF;0FAC0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,aAAa,CAEvE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,eAAe,CAE3E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,oBAAoB,CAErF;AAED,oGAAoG;AACpG,eAAO,MAAM,cAAc,aAAwC,CAAC;AAEpE;;;;;;;;;2EAS2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAItE;AAED;;;;;kEAKkE;AAClE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CA6BxE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAQrF;AAiBD;;;8CAG8C;AAC9C,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAInB"}
+{"version":3,"file":"reference-field-map.d.ts","sourceRoot":"","sources":["../src/reference-field-map.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;sDACkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0FAA0F;IAC1F,OAAO,EAAE,OAAO,CAAC;IACjB;8DAC0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B;2CACuC;IACvC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED;8CAC8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC;;qFAEiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEnF;0FAC0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,aAAa,CAEvE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,eAAe,CAE3E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,oBAAoB,CAErF;AAED,oGAAoG;AACpG,eAAO,MAAM,cAAc,aAAwC,CAAC;AAEpE;;;;;;;;;2EAS2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAItE;AAED;;;;sEAIsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;wDAUwD;AACxD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAoCpF;AAED;+DAC+D;AAC/D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAQrF;AAiBD;;;8CAG8C;AAC9C,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAInB"}

package/dist/reference-field-map.js

@@ -26,25 +26,30 @@ export function isInlineResource(val) {
         return false;
     return true;
 }
-/** Resolves all values at a field map path in a resource config.
- *  Path-segment markers:
- *   - `[]`  iterate array values at this key
+/** Resolves all `{value, path}` entries at a field map path in a resource
+ *  config. The returned `path` is the concrete dotted path produced by the
+ *  substitutions below, matching the format `buildPositionIndex` keys on.
+ *  Path-segment markers accepted in the input `path`:
+ *   - `[]`  iterate array values at this key, substituting `[N]` per item
+ *           (e.g. `routes[]` → `routes[0]`, `routes[1]`, …).
  *   - `{}`  iterate map values (every value in an `additionalProperties`-typed
  *           object — used for fields like `content[mime]` whose schema declares
- *           a key-as-MIME map). The path is `<key>.{}.<rest>`. */
-export function resolveFieldValues(obj, path) {
+ *           a key-as-MIME map). Substituted with the literal map key joined by
+ *           a dot, so the input `content.{}.encoder` yields concrete paths
+ *           like `content.application/json.encoder`. */
+export function resolveFieldEntries(obj, path) {
     const parts = path.split(".");
-    let current = [obj];
+    let current = [{ value: obj, path: "" }];
     for (const part of parts) {
         if (part === "{}") {
-            // Iterate the values of every map currently in `current`.
             const next = [];
-            for (const item of current) {
-                if (!item || typeof item !== "object")
+            for (const entry of current) {
+                if (!entry.value || typeof entry.value !== "object")
                     continue;
-                for (const v of Object.values(item)) {
-                    if (v != null)
-                        next.push(v);
+                for (const [k, v] of Object.entries(entry.value)) {
+                    if (v != null) {
+                        next.push({ value: v, path: entry.path ? `${entry.path}.${k}` : k });
+                    }
                 }
             }
             current = next;
@@ -53,21 +58,32 @@ export function resolveFieldValues(obj, path) {
         const isArray = part.endsWith("[]");
         const key = isArray ? part.slice(0, -2) : part;
         const next = [];
-        for (const item of current) {
-            if (!item || typeof item !== "object")
+        for (const entry of current) {
+            if (!entry.value || typeof entry.value !== "object")
                 continue;
-            const val = item[key];
+            const val = entry.value[key];
             if (val == null)
                 continue;
-            if (isArray && Array.isArray(val))
-                next.push(...val);
-            else if (!isArray)
-                next.push(val);
+            const basePath = entry.path ? `${entry.path}.${key}` : key;
+            if (isArray && Array.isArray(val)) {
+                for (let i = 0; i < val.length; i++) {
+                    if (val[i] != null)
+                        next.push({ value: val[i], path: `${basePath}[${i}]` });
+                }
+            }
+            else if (!isArray) {
+                next.push({ value: val, path: basePath });
+            }
         }
         current = next;
     }
     return current;
 }
+/** Backwards-compat wrapper that drops the concrete path. Prefer
+ *  `resolveFieldEntries` for new code that wants positions. */
+export function resolveFieldValues(obj, path) {
+    return resolveFieldEntries(obj, path).map((e) => e.value);
+}
 /**
  * Traverses a definition's JSON Schema once and returns a field map recording every
  * x-telo-ref slot and every x-telo-scope slot.

package/dist/residual-schema.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Build the residual JSON Schema for a `variables` / `secrets` entry.
+ *
+ * For Telo.Application env-binding entries (those with an `env:` key), strips
+ * the kernel-specific wrapper keys `env` and `default` — `default` here is
+ * the *fallback host value* the kernel coerces when the env var is unset, not
+ * a JSON Schema annotation, so it must not leak into the validator.
+ *
+ * For Telo.Library entries (no `env:`), passes the entry through unchanged.
+ * Library `default:` is a standard JSON Schema annotation and stays.
+ *
+ * Single source of truth for "residual schema" referenced by both the
+ * analyzer's CEL globals normalization and the kernel's runtime env-var
+ * resolver — keeping them aligned prevents the two surfaces from drifting.
+ */
+export declare function residualEntrySchema(entry: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/**
+ * Apply `residualEntrySchema` to every entry in a `variables` / `secrets` map.
+ * Returns a property-map suitable for use as the inner schema of CEL's
+ * `variables` / `secrets` namespaces.
+ */
+export declare function residualEntrySchemaMap(entries: Record<string, unknown> | null | undefined): Record<string, Record<string, unknown>>;
+//# sourceMappingURL=residual-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"residual-schema.d.ts","sourceRoot":"","sources":["../src/residual-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAChD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAClD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAWzC"}

package/dist/residual-schema.js

@@ -0,0 +1,45 @@
+/**
+ * Build the residual JSON Schema for a `variables` / `secrets` entry.
+ *
+ * For Telo.Application env-binding entries (those with an `env:` key), strips
+ * the kernel-specific wrapper keys `env` and `default` — `default` here is
+ * the *fallback host value* the kernel coerces when the env var is unset, not
+ * a JSON Schema annotation, so it must not leak into the validator.
+ *
+ * For Telo.Library entries (no `env:`), passes the entry through unchanged.
+ * Library `default:` is a standard JSON Schema annotation and stays.
+ *
+ * Single source of truth for "residual schema" referenced by both the
+ * analyzer's CEL globals normalization and the kernel's runtime env-var
+ * resolver — keeping them aligned prevents the two surfaces from drifting.
+ */
+export function residualEntrySchema(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return { type: "object", additionalProperties: true };
+    }
+    const isAppEnvBinding = "env" in entry;
+    const out = {};
+    for (const [key, value] of Object.entries(entry)) {
+        if (isAppEnvBinding && (key === "env" || key === "default"))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+/**
+ * Apply `residualEntrySchema` to every entry in a `variables` / `secrets` map.
+ * Returns a property-map suitable for use as the inner schema of CEL's
+ * `variables` / `secrets` namespaces.
+ */
+export function residualEntrySchemaMap(entries) {
+    const out = {};
+    if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+        return out;
+    }
+    for (const [name, value] of Object.entries(entries)) {
+        if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            out[name] = residualEntrySchema(value);
+        }
+    }
+    return out;
+}

package/dist/rewrite-synthetic-origins.d.ts

@@ -0,0 +1,10 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AnalysisDiagnostic } from "./types.js";
+/** Diagnostics emitted on synthetic manifests (resources extracted by
+ *  `normalizeInlineResources`) carry the synthetic's identity in
+ *  `data.resource`, which has no YAML source. Rewrite each such diagnostic
+ *  back to the chain root: walk up `metadata.xTeloOrigin` until a manifest
+ *  with no origin is reached, and prepend each hop's `pathFromParent` to
+ *  `data.path` so position-index lookups against the root doc resolve. */
+export declare function rewriteSyntheticOrigins(diagnostics: AnalysisDiagnostic[], manifests: ResourceManifest[]): AnalysisDiagnostic[];
+//# sourceMappingURL=rewrite-synthetic-origins.d.ts.map

package/dist/rewrite-synthetic-origins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewrite-synthetic-origins.d.ts","sourceRoot":"","sources":["../src/rewrite-synthetic-origins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAsBrD;;;;;0EAK0E;AAC1E,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,kBAAkB,EAAE,EACjC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,kBAAkB,EAAE,CA0CtB"}

package/dist/rewrite-synthetic-origins.js

@@ -0,0 +1,55 @@
+function readOrigin(manifest) {
+    if (!manifest)
+        return undefined;
+    const origin = manifest.metadata?.xTeloOrigin;
+    if (!origin ||
+        typeof origin.parentKind !== "string" ||
+        typeof origin.parentName !== "string" ||
+        typeof origin.pathFromParent !== "string") {
+        return undefined;
+    }
+    return origin;
+}
+/** Diagnostics emitted on synthetic manifests (resources extracted by
+ *  `normalizeInlineResources`) carry the synthetic's identity in
+ *  `data.resource`, which has no YAML source. Rewrite each such diagnostic
+ *  back to the chain root: walk up `metadata.xTeloOrigin` until a manifest
+ *  with no origin is reached, and prepend each hop's `pathFromParent` to
+ *  `data.path` so position-index lookups against the root doc resolve. */
+export function rewriteSyntheticOrigins(diagnostics, manifests) {
+    const byName = new Map();
+    for (const m of manifests) {
+        const name = m.metadata?.name;
+        if (typeof name === "string")
+            byName.set(name, m);
+    }
+    return diagnostics.map((d) => {
+        const data = d.data;
+        if (!data?.resource?.name)
+            return d;
+        let current = byName.get(data.resource.name);
+        let origin = readOrigin(current);
+        if (!origin)
+            return d;
+        let accumPath = typeof data.path === "string" ? data.path : "";
+        let rootKind = origin.parentKind;
+        let rootName = origin.parentName;
+        while (origin) {
+            accumPath = accumPath ? `${origin.pathFromParent}.${accumPath}` : origin.pathFromParent;
+            rootKind = origin.parentKind;
+            rootName = origin.parentName;
+            current = byName.get(origin.parentName);
+            origin = readOrigin(current);
+        }
+        const rootFilePath = current?.metadata?.source ?? data.filePath;
+        return {
+            ...d,
+            data: {
+                ...data,
+                resource: { kind: rootKind, name: rootName },
+                filePath: rootFilePath,
+                path: accumPath,
+            },
+        };
+    });
+}

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

@@ -1,4 +1,19 @@
 export { extractAccessChains, validateChainAgainstSchema } from "@telorun/templating";
+export interface ContextResolveOpts {
+    /** When provided, used to resolve `x-telo-context-from-root` annotations against the
+     *  root manifest. When omitted, defaults to `manifestItem`. */
+    manifestRoot?: Record<string, any>;
+    /** When provided alongside `aliases`, used to resolve `x-telo-context-from-ref-kind`
+     *  annotations: read a kind name from a path on `manifestRoot` and return the
+     *  declared definition's `<field>` schema. */
+    defs?: {
+        resolve(kind: string): Record<string, any> | undefined;
+    };
+    aliases?: {
+        resolveKind(kind: string): string | undefined;
+    };
+    allManifests?: Record<string, any>[];
+}
 /**
  * Resolve a type field value (string name, inline type, or raw schema) to a JSON Schema.
  * - String: look up the named type in allManifests (Type.JsonSchema resources)
@@ -15,15 +30,54 @@ export declare function resolveTypeFieldToSchema(value: unknown, allManifests: R
  */
 export declare function pathMatchesScope(exprPath: string, scope: string): boolean;
 /**
- * Resolves `x-telo-context-from` annotations in a context schema using the concrete
- * manifest item. Navigates the manifest item at the given slash-separated path and merges
- * the result as named properties into the annotated node (locking additionalProperties: false).
+ * Resolves `x-telo-context-*` annotations in a context schema using the concrete
+ * manifest item (per-scope) and the manifest root.
  *
- * Example: `x-telo-context-from: "request/schema"` on the `request` context node replaces
- * the open `request` schema with a closed schema whose properties are the keys of
- * `manifestItem.request.schema` (e.g. `query`, `body`, `params`, `headers`).
+ * Annotation forms:
+ *
+ * - `x-telo-context-from`: navigates `manifestItem.<path>` and treats the resolved
+ *   value as a **property map** (keys → sub-schemas) that is merged into the
+ *   annotated node's properties. Used for HTTP-style scopes where the navigated
+ *   value is itself a map of variable names.
+ *
+ *   Example: `x-telo-context-from: "request/schema"` reads `manifestItem.request.schema`
+ *   (= `{ query: {...}, body: {...}, … }`) and merges those keys as named properties
+ *   of the context node.
+ *
+ * - `x-telo-context-from-root`: navigates `manifestRoot.<path>` and **replaces** the
+ *   annotated node's schema with the resolved value. Used on individual property
+ *   schemas (e.g. `properties.self`) where the resolved value is a single variable's
+ *   full schema, not a property map.
+ *
+ *   Example: `properties.self.x-telo-context-from-root: "schema"` reads
+ *   `manifestRoot.schema` and uses it as the schema of the `self` CEL variable.
+ *
+ * - `x-telo-context-from-ref-kind`: reads a kind name from `manifestRoot.<refPath>`,
+ *   resolves it via the definition registry, and returns that kind's `<field>` schema
+ *   (e.g. `outputType`/`inputType`). Used to type `result` against the dispatch
+ *   target's declared output shape.
+ *
+ *   Syntax: `<refPath>#<field>` — slashes traverse the manifest tree.
+ *
+ *   Example: `x-telo-context-from-ref-kind: "provide/kind#outputType"` reads
+ *   `manifestRoot.provide.kind` as a kind name, looks up the kind's Telo.Definition,
+ *   and returns the `outputType` schema.
+ *
+ *   Accepts either a single string or an array of strings. With an array, paths
+ *   are tried in order and the first one that resolves to a usable schema wins —
+ *   used by `result:` to find its dispatch target under whichever entry-point
+ *   field (`provide:` or `invoke:`) the definition declares.
+ *
+ * - `x-telo-context-ref-from`: existing form — reads `{kind, name}` object from
+ *   `manifestItem.<path>`, looks up the named manifest, returns its `<subpath>` field.
+ *
+ * **Fallback chain.** When both `x-telo-context-from-root` and
+ * `x-telo-context-from-ref-kind` are present on the same node, the resolver tries
+ * `from-root` first; if that produces no usable schema, it falls back to `from-ref-kind`.
+ * This lets a definition declare typing from its own field with a sibling-kind fallback
+ * (e.g. `inputType` direct → `extends`-declared abstract's `inputType`).
  */
-export declare function resolveContextAnnotations(schema: Record<string, any>, manifestItem: Record<string, any>, allManifests?: Record<string, any>[]): Record<string, any>;
+export declare function resolveContextAnnotations(schema: Record<string, any>, manifestItem: Record<string, any>, opts?: ContextResolveOpts | Record<string, any>[]): Record<string, any>;
 /**
  * Extracts the concrete manifest array item for a given expression path + scope.
  * e.g. exprPath="routes[0].inputs.q", scope="$.routes[*].inputs" → manifest.routes[0]

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;;;;;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;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GACnC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqDrB;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"}

package/dist/validate-cel-context.js

@@ -61,17 +61,61 @@ export function pathMatchesScope(exprPath, scope) {
     return remaining === "" || remaining[0] === "." || remaining[0] === "[";
 }
 /**
- * Resolves `x-telo-context-from` annotations in a context schema using the concrete
- * manifest item. Navigates the manifest item at the given slash-separated path and merges
- * the result as named properties into the annotated node (locking additionalProperties: false).
+ * Resolves `x-telo-context-*` annotations in a context schema using the concrete
+ * manifest item (per-scope) and the manifest root.
  *
- * Example: `x-telo-context-from: "request/schema"` on the `request` context node replaces
- * the open `request` schema with a closed schema whose properties are the keys of
- * `manifestItem.request.schema` (e.g. `query`, `body`, `params`, `headers`).
+ * Annotation forms:
+ *
+ * - `x-telo-context-from`: navigates `manifestItem.<path>` and treats the resolved
+ *   value as a **property map** (keys → sub-schemas) that is merged into the
+ *   annotated node's properties. Used for HTTP-style scopes where the navigated
+ *   value is itself a map of variable names.
+ *
+ *   Example: `x-telo-context-from: "request/schema"` reads `manifestItem.request.schema`
+ *   (= `{ query: {...}, body: {...}, … }`) and merges those keys as named properties
+ *   of the context node.
+ *
+ * - `x-telo-context-from-root`: navigates `manifestRoot.<path>` and **replaces** the
+ *   annotated node's schema with the resolved value. Used on individual property
+ *   schemas (e.g. `properties.self`) where the resolved value is a single variable's
+ *   full schema, not a property map.
+ *
+ *   Example: `properties.self.x-telo-context-from-root: "schema"` reads
+ *   `manifestRoot.schema` and uses it as the schema of the `self` CEL variable.
+ *
+ * - `x-telo-context-from-ref-kind`: reads a kind name from `manifestRoot.<refPath>`,
+ *   resolves it via the definition registry, and returns that kind's `<field>` schema
+ *   (e.g. `outputType`/`inputType`). Used to type `result` against the dispatch
+ *   target's declared output shape.
+ *
+ *   Syntax: `<refPath>#<field>` — slashes traverse the manifest tree.
+ *
+ *   Example: `x-telo-context-from-ref-kind: "provide/kind#outputType"` reads
+ *   `manifestRoot.provide.kind` as a kind name, looks up the kind's Telo.Definition,
+ *   and returns the `outputType` schema.
+ *
+ *   Accepts either a single string or an array of strings. With an array, paths
+ *   are tried in order and the first one that resolves to a usable schema wins —
+ *   used by `result:` to find its dispatch target under whichever entry-point
+ *   field (`provide:` or `invoke:`) the definition declares.
+ *
+ * - `x-telo-context-ref-from`: existing form — reads `{kind, name}` object from
+ *   `manifestItem.<path>`, looks up the named manifest, returns its `<subpath>` field.
+ *
+ * **Fallback chain.** When both `x-telo-context-from-root` and
+ * `x-telo-context-from-ref-kind` are present on the same node, the resolver tries
+ * `from-root` first; if that produces no usable schema, it falls back to `from-ref-kind`.
+ * This lets a definition declare typing from its own field with a sibling-kind fallback
+ * (e.g. `inputType` direct → `extends`-declared abstract's `inputType`).
  */
-export function resolveContextAnnotations(schema, manifestItem, allManifests) {
+export function resolveContextAnnotations(schema, manifestItem, opts) {
     if (!schema || typeof schema !== "object")
         return schema;
+    // Back-compat: third positional arg used to be `allManifests: Record<string, any>[]`.
+    const normalizedOpts = Array.isArray(opts)
+        ? { allManifests: opts }
+        : (opts ?? {});
+    const { manifestRoot = manifestItem, defs, aliases, allManifests } = normalizedOpts;
     const from = schema["x-telo-context-from"];
     if (from) {
         const resolved = navigatePath(manifestItem, from.split("/"));
@@ -82,6 +126,44 @@ export function resolveContextAnnotations(schema, manifestItem, allManifests) {
             additionalProperties: false,
         };
     }
+    const fromRoot = schema["x-telo-context-from-root"];
+    const fromRefKindRaw = schema["x-telo-context-from-ref-kind"];
+    const fromRefKinds = fromRefKindRaw == null
+        ? []
+        : Array.isArray(fromRefKindRaw)
+            ? fromRefKindRaw
+            : [fromRefKindRaw];
+    if (fromRoot || fromRefKinds.length > 0) {
+        if (fromRoot) {
+            const resolved = navigatePath(manifestRoot, fromRoot.split("/"));
+            if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
+                return resolved;
+            }
+        }
+        if (defs) {
+            for (const fromRefKind of fromRefKinds) {
+                const hashIdx = fromRefKind.indexOf("#");
+                if (hashIdx <= 0)
+                    continue;
+                const refPath = fromRefKind.slice(0, hashIdx);
+                const field = fromRefKind.slice(hashIdx + 1);
+                const kindValue = navigatePath(manifestRoot, refPath.split("/"));
+                if (typeof kindValue !== "string" || kindValue.length === 0)
+                    continue;
+                const canonical = aliases?.resolveKind(kindValue) ?? kindValue;
+                const def = defs.resolve(canonical);
+                const typeField = def
+                    ? def[field]
+                    : undefined;
+                const resolved = resolveTypeFieldToSchema(typeField, allManifests ?? []);
+                if (resolved && typeof resolved === "object") {
+                    return resolved;
+                }
+            }
+        }
+        // Open fallback so unresolved types never produce false-positive CEL diagnostics.
+        return { type: "object", additionalProperties: true };
+    }
     const refFrom = schema["x-telo-context-ref-from"];
     if (refFrom && allManifests) {
         const slashIdx = refFrom.indexOf("/");
@@ -107,7 +189,7 @@ export function resolveContextAnnotations(schema, manifestItem, allManifests) {
     if (schema.properties) {
         const props = {};
         for (const [k, v] of Object.entries(schema.properties)) {
-            props[k] = resolveContextAnnotations(v, manifestItem, allManifests);
+            props[k] = resolveContextAnnotations(v, manifestItem, normalizedOpts);
         }
         return { ...schema, properties: props };
     }