@telorun/analyzer 0.10.0 → 0.11.0

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;AAa9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAgX/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,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IAqUvB,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;IAUxF,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;AAa9B,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA8c/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,OAAO,CACL,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,kBAAkB,EAAE;IA6avB,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;IAUxF,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

@@ -37,12 +37,89 @@ function lookupDefinitionTypeField(invokedKind, fieldName, defs, aliases, allMan
     return resolveTypeFieldToSchema(value, allManifests);
 }
 const SOURCE = "telo-analyzer";
+/** Build a closed JSON Schema for the `self` CEL variable available inside a
+ *  `Telo.Definition` template body. Mirrors the runtime template controller's
+ *  `const self = { ...resource, name: resource.metadata.name };` — every
+ *  property the user declared in `schema:` plus synthetic `name` / `kind` and
+ *  the metadata sub-object (kept open since metadata legitimately carries
+ *  arbitrary user-added fields). */
+function buildSelfSchema(definition) {
+    const userSchema = (definition.schema ?? {});
+    const userProps = (userSchema.properties ?? {});
+    const userRequired = Array.isArray(userSchema.required) ? userSchema.required : [];
+    return {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            ...userProps,
+            name: { type: "string" },
+            kind: { type: "string" },
+            metadata: {
+                type: "object",
+                additionalProperties: true,
+                properties: { name: { type: "string" } },
+            },
+        },
+        required: [...userRequired, "name", "kind"],
+    };
+}
+/** Build the JSON Schema for the `inputs` CEL variable available inside an
+ *  invocable template body. Three-layer fallback mirroring the runtime's
+ *  caller-supplied inputs:
+ *    1. The definition's own `inputType:` field (preferred).
+ *    2. The `extends:`-declared abstract's `inputType:` (so a concrete
+ *       definition inheriting a contract gets typed inputs without
+ *       redeclaring them).
+ *    3. Undefined — caller signals opaque `map<string, dyn>` upstream. */
+function lookupTemplateInputsSchema(definition, defs, aliases, allManifests) {
+    const own = resolveTypeFieldToSchema(definition.inputType, allManifests);
+    if (own)
+        return own;
+    const ext = definition.extends;
+    if (typeof ext === "string" && ext.length > 0) {
+        const canonical = aliases.resolveKind(ext) ?? ext;
+        const abstractDef = defs.resolve(canonical);
+        if (abstractDef) {
+            const inherited = resolveTypeFieldToSchema(abstractDef.inputType, allManifests);
+            if (inherited)
+                return inherited;
+        }
+    }
+    return undefined;
+}
+/** Returns a "resolver-facing" view of the manifest where the fields used as
+ *  navigation roots by Telo.Definition's `x-telo-context-from-root` annotations
+ *  have been pre-augmented:
+ *    - `schema`     → augmented `self` schema (synthetic `name`/`kind`/metadata).
+ *    - `inputType`  → resolved with extends fallback when the field isn't
+ *                     declared directly on the definition.
+ *
+ *  For non-definition manifests the original object is returned. */
+function manifestRootForResolver(m, defs, aliases, allManifests) {
+    if (m.kind !== "Telo.Definition")
+        return m;
+    const inputs = lookupTemplateInputsSchema(m, defs, aliases, allManifests);
+    return {
+        ...m,
+        schema: buildSelfSchema(m),
+        ...(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 = [];
@@ -51,16 +128,16 @@ function extractContextsFromSchema(schema, path = "$") {
     }
     if (schema.properties) {
         for (const [key, value] of Object.entries(schema.properties)) {
-            results.push(...extractContextsFromSchema(value, `${path}.${key}`));
+            results.push(...collectContexts(value, `${path}.${key}`));
         }
     }
     if (schema.items && typeof schema.items === "object") {
-        results.push(...extractContextsFromSchema(schema.items, `${path}[*]`));
+        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(...extractContextsFromSchema(subschema, path));
+                results.push(...collectContexts(subschema, path));
             }
         }
     }
@@ -436,7 +513,11 @@ export class StaticAnalyzer {
                 });
                 continue;
             }
-            if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") {
+            // Abstracts carry only inputType / outputType schema fields and no template
+            // body — nothing for the per-resource walk to validate. Definitions are now
+            // walked: their template bodies (`resources` / `invoke` / `run` / `provide`)
+            // contain CEL that must be checked against `self` / `inputs` / `result`.
+            if (m.kind === "Telo.Abstract") {
                 continue;
             }
             const resource = { kind: m.kind, name: m.metadata?.name };
@@ -489,6 +570,76 @@ export class StaticAnalyzer {
             }
             // (Invocation context compatibility check is handled via x-telo-context in the CEL pass below)
         }
+        // Template-body structural validations: check that template entry-points produce
+        // values matching the contract of their dispatch target and (for `provide:`)
+        // the abstract this definition `extends`. CEL fields inside the templated
+        // values are replaced with type-appropriate placeholders before AJV runs —
+        // same pattern as the per-resource schema validation above.
+        for (const m of allManifests) {
+            if (m.kind !== "Telo.Definition")
+                continue;
+            const filePath = m.metadata?.source;
+            const name = m.metadata?.name;
+            if (!name)
+                continue;
+            const resource = { kind: m.kind, name };
+            const md = m;
+            const emitTargetMismatch = (targetKind, valueSchema, value, path) => {
+                const substituted = substituteCelFields(value, valueSchema);
+                const issues = validateAgainstSchema(substituted, valueSchema);
+                for (const issue of issues) {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "TEMPLATE_TARGET_MISMATCH",
+                        source: SOURCE,
+                        message: `${m.kind}/${name}: ${path} does not satisfy ${targetKind}'s contract: ${issue.message}`,
+                        data: { resource, filePath, path: issue.path ? `${path}.${issue.path}` : path },
+                    });
+                }
+            };
+            // Resolve the dispatch target's kind, if statically known. Object-form
+            // `invoke: { kind, name }` and `provide: { kind, name }` carry it; the
+            // string-form `invoke: "name"` does not (the matching resource entry would
+            // need to be located by expanded name — out of scope here).
+            const invoke = md.invoke;
+            const provide = md.provide;
+            let dispatchKind;
+            if (invoke && typeof invoke === "object" && !Array.isArray(invoke) && typeof invoke.kind === "string") {
+                dispatchKind = invoke.kind;
+            }
+            else if (provide &&
+                typeof provide === "object" &&
+                !Array.isArray(provide) &&
+                typeof provide.kind === "string") {
+                dispatchKind = provide.kind;
+            }
+            // Top-level `inputs:` (sibling of `invoke:` / `provide:`) carries the
+            // values passed to the dispatch target's invoke(). Validate against the
+            // target's declared `inputType` when both sides have one.
+            if (dispatchKind && md.inputs && typeof md.inputs === "object") {
+                const targetSchema = lookupDefinitionTypeField(dispatchKind, "inputType", defs, aliases, allManifests);
+                if (targetSchema) {
+                    emitTargetMismatch(dispatchKind, targetSchema, md.inputs, "inputs");
+                }
+            }
+            // Top-level `result:` (a sibling, only meaningful with `provide:`) is a
+            // post-call mapping that must satisfy the abstract this definition
+            // `extends` (`outputType`). The target's outputType lives on `provide.kind`
+            // and is what `result` is typed against *inside* CEL — separate role.
+            if (provide &&
+                typeof provide === "object" &&
+                !Array.isArray(provide) &&
+                md.result &&
+                typeof md.result === "object") {
+                const extendsValue = md.extends;
+                if (typeof extendsValue === "string" && extendsValue.length > 0) {
+                    const abstractSchema = lookupDefinitionTypeField(extendsValue, "outputType", defs, aliases, allManifests);
+                    if (abstractSchema) {
+                        emitTargetMismatch(extendsValue, abstractSchema, md.result, "result");
+                    }
+                }
+            }
+        }
         // Validate CEL syntax and context variable access in all manifests
         for (const m of allManifests) {
             const resource = { kind: m.kind, name: m.metadata?.name };
@@ -533,7 +684,13 @@ export class StaticAnalyzer {
                     const manifestItem = matchedScope
                         ? getManifestItem(path, matchedScope, m)
                         : m;
-                    const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, allManifests);
+                    const rootForResolver = manifestRootForResolver(m, defs, aliases, allManifests);
+                    const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, {
+                        manifestRoot: rootForResolver,
+                        defs,
+                        aliases,
+                        allManifests: allManifests,
+                    });
                     effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
                 }
                 const engine = defaultRegistry().get(engineName);

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,EAsJ/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,EAwQ/C,CAAC"}

package/dist/builtins.js

@@ -38,7 +38,121 @@ export const KERNEL_BUILTINS = [
         kind: "Telo.Definition",
         metadata: { name: "Definition", module: "Telo" },
         capability: "Telo.Template",
-        schema: { type: "object" },
+        // Top-level shape stays open (`additionalProperties: true`) so this change
+        // attaches x-telo-context annotations to known template-body fields without
+        // tightening the Telo.Definition shape itself. The annotations drive
+        // static CEL validation of expressions inside `resources:` / `invoke:` /
+        // `run:` / `provide:` / top-level `inputs:` / top-level `result:` against
+        // `self` (typed from `schema:`) and `inputs` (typed from `inputType:`,
+        // falling back to the extends-declared abstract).
+        //
+        // `inputs:` and `result:` live as top-level siblings of `invoke:` / `provide:`,
+        // matching how Run.Sequence steps factor dispatch from data. The dispatch
+        // entry-point (`invoke` / `provide` / `run`) determines how `inputs`/`result`
+        // are interpreted at runtime. See analyzer/nodejs/plans/template-internal-cel-validation.md.
+        schema: {
+            type: "object",
+            additionalProperties: true,
+            properties: {
+                resources: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        additionalProperties: true,
+                        "x-telo-context": {
+                            type: "object",
+                            additionalProperties: false,
+                            properties: {
+                                self: { "x-telo-context-from-root": "schema" },
+                                inputs: { "x-telo-context-from-root": "inputType" },
+                            },
+                        },
+                    },
+                },
+                invoke: {
+                    oneOf: [
+                        {
+                            type: "string",
+                            "x-telo-context": {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    self: { "x-telo-context-from-root": "schema" },
+                                },
+                            },
+                        },
+                        {
+                            type: "object",
+                            additionalProperties: true,
+                            properties: {
+                                kind: { type: "string" },
+                                name: {
+                                    type: "string",
+                                    "x-telo-context": {
+                                        type: "object",
+                                        additionalProperties: false,
+                                        properties: {
+                                            self: { "x-telo-context-from-root": "schema" },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    ],
+                },
+                provide: {
+                    type: "object",
+                    additionalProperties: true,
+                    properties: {
+                        kind: { type: "string" },
+                        name: {
+                            type: "string",
+                            "x-telo-context": {
+                                type: "object",
+                                additionalProperties: false,
+                                properties: {
+                                    self: { "x-telo-context-from-root": "schema" },
+                                },
+                            },
+                        },
+                    },
+                },
+                run: {
+                    type: "string",
+                    "x-telo-context": {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            self: { "x-telo-context-from-root": "schema" },
+                        },
+                    },
+                },
+                inputs: {
+                    type: "object",
+                    additionalProperties: true,
+                    "x-telo-context": {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            self: { "x-telo-context-from-root": "schema" },
+                            inputs: { "x-telo-context-from-root": "inputType" },
+                        },
+                    },
+                },
+                result: {
+                    type: "object",
+                    additionalProperties: true,
+                    "x-telo-context": {
+                        type: "object",
+                        additionalProperties: false,
+                        properties: {
+                            self: { "x-telo-context-from-root": "schema" },
+                            result: { "x-telo-context-from-ref-kind": "provide/kind#outputType" },
+                        },
+                    },
+                },
+            },
+        },
     },
     {
         kind: "Telo.Definition",

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,49 @@ 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.
+ *
+ * - `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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;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,CA6FrB;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,56 @@ 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.
+ *
+ * - `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 +121,37 @@ export function resolveContextAnnotations(schema, manifestItem, allManifests) {
             additionalProperties: false,
         };
     }
+    const fromRoot = schema["x-telo-context-from-root"];
+    const fromRefKind = schema["x-telo-context-from-ref-kind"];
+    if (fromRoot || fromRefKind) {
+        if (fromRoot) {
+            const resolved = navigatePath(manifestRoot, fromRoot.split("/"));
+            if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
+                return resolved;
+            }
+        }
+        if (fromRefKind && defs) {
+            const hashIdx = fromRefKind.indexOf("#");
+            if (hashIdx > 0) {
+                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) {
+                    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 +177,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 };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -41,8 +41,8 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/sdk": "0.10.0",
-    "@telorun/templating": "0.2.2"
+    "@telorun/sdk": "0.11.1",
+    "@telorun/templating": "0.2.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/analyzer.ts

@@ -68,14 +68,108 @@ function lookupDefinitionTypeField(
 
 const SOURCE = "telo-analyzer";
 
+/** Build a closed JSON Schema for the `self` CEL variable available inside a
+ *  `Telo.Definition` template body. Mirrors the runtime template controller's
+ *  `const self = { ...resource, name: resource.metadata.name };` — every
+ *  property the user declared in `schema:` plus synthetic `name` / `kind` and
+ *  the metadata sub-object (kept open since metadata legitimately carries
+ *  arbitrary user-added fields). */
+function buildSelfSchema(definition: Record<string, any>): Record<string, any> {
+  const userSchema = (definition.schema ?? {}) as Record<string, any>;
+  const userProps = (userSchema.properties ?? {}) as Record<string, any>;
+  const userRequired = Array.isArray(userSchema.required) ? userSchema.required : [];
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      ...userProps,
+      name: { type: "string" },
+      kind: { type: "string" },
+      metadata: {
+        type: "object",
+        additionalProperties: true,
+        properties: { name: { type: "string" } },
+      },
+    },
+    required: [...userRequired, "name", "kind"],
+  };
+}
+
+/** Build the JSON Schema for the `inputs` CEL variable available inside an
+ *  invocable template body. Three-layer fallback mirroring the runtime's
+ *  caller-supplied inputs:
+ *    1. The definition's own `inputType:` field (preferred).
+ *    2. The `extends:`-declared abstract's `inputType:` (so a concrete
+ *       definition inheriting a contract gets typed inputs without
+ *       redeclaring them).
+ *    3. Undefined — caller signals opaque `map<string, dyn>` upstream. */
+function lookupTemplateInputsSchema(
+  definition: Record<string, any>,
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  allManifests: Record<string, any>[],
+): Record<string, any> | undefined {
+  const own = resolveTypeFieldToSchema(definition.inputType, allManifests);
+  if (own) return own;
+  const ext = definition.extends as string | undefined;
+  if (typeof ext === "string" && ext.length > 0) {
+    const canonical = aliases.resolveKind(ext) ?? ext;
+    const abstractDef = defs.resolve(canonical);
+    if (abstractDef) {
+      const inherited = resolveTypeFieldToSchema(
+        (abstractDef as unknown as Record<string, unknown>).inputType,
+        allManifests,
+      );
+      if (inherited) return inherited;
+    }
+  }
+  return undefined;
+}
+
+/** Returns a "resolver-facing" view of the manifest where the fields used as
+ *  navigation roots by Telo.Definition's `x-telo-context-from-root` annotations
+ *  have been pre-augmented:
+ *    - `schema`     → augmented `self` schema (synthetic `name`/`kind`/metadata).
+ *    - `inputType`  → resolved with extends fallback when the field isn't
+ *                     declared directly on the definition.
+ *
+ *  For non-definition manifests the original object is returned. */
+function manifestRootForResolver(
+  m: Record<string, any>,
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  allManifests: Record<string, any>[],
+): Record<string, any> {
+  if (m.kind !== "Telo.Definition") return m;
+  const inputs = lookupTemplateInputsSchema(m, defs, aliases, allManifests);
+  return {
+    ...m,
+    schema: buildSelfSchema(m),
+    ...(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: Record<string, any>,
   path = "$",
+): Array<{ scope: string; schema: Record<string, any> }> {
+  const all = collectContexts(schema, path);
+  return all.sort((a, b) => b.scope.length - a.scope.length);
+}
+
+function collectContexts(
+  schema: Record<string, any>,
+  path: string,
 ): Array<{ scope: string; schema: Record<string, any> }> {
   if (!schema || typeof schema !== "object") return [];
   const results: Array<{ scope: string; schema: Record<string, any> }> = [];
@@ -86,18 +180,18 @@ function extractContextsFromSchema(
 
   if (schema.properties) {
     for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
-      results.push(...extractContextsFromSchema(value, `${path}.${key}`));
+      results.push(...collectContexts(value, `${path}.${key}`));
     }
   }
 
   if (schema.items && typeof schema.items === "object") {
-    results.push(...extractContextsFromSchema(schema.items, `${path}[*]`));
+    results.push(...collectContexts(schema.items, `${path}[*]`));
   }
 
   for (const key of ["oneOf", "anyOf", "allOf"] as const) {
     if (Array.isArray(schema[key])) {
       for (const subschema of schema[key]) {
-        results.push(...extractContextsFromSchema(subschema, path));
+        results.push(...collectContexts(subschema, path));
       }
     }
   }
@@ -552,7 +646,11 @@ export class StaticAnalyzer {
         });
         continue;
       }
-      if (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") {
+      // Abstracts carry only inputType / outputType schema fields and no template
+      // body — nothing for the per-resource walk to validate. Definitions are now
+      // walked: their template bodies (`resources` / `invoke` / `run` / `provide`)
+      // contain CEL that must be checked against `self` / `inputs` / `result`.
+      if (m.kind === "Telo.Abstract") {
         continue;
       }
 
@@ -612,6 +710,99 @@ export class StaticAnalyzer {
       // (Invocation context compatibility check is handled via x-telo-context in the CEL pass below)
     }
 
+    // Template-body structural validations: check that template entry-points produce
+    // values matching the contract of their dispatch target and (for `provide:`)
+    // the abstract this definition `extends`. CEL fields inside the templated
+    // values are replaced with type-appropriate placeholders before AJV runs —
+    // same pattern as the per-resource schema validation above.
+    for (const m of allManifests) {
+      if (m.kind !== "Telo.Definition") continue;
+      const filePath = (m.metadata as { source?: string } | undefined)?.source;
+      const name = (m.metadata as any)?.name as string | undefined;
+      if (!name) continue;
+      const resource = { kind: m.kind, name };
+      const md = m as Record<string, any>;
+
+      const emitTargetMismatch = (
+        targetKind: string,
+        valueSchema: Record<string, any>,
+        value: unknown,
+        path: string,
+      ) => {
+        const substituted = substituteCelFields(value, valueSchema);
+        const issues = validateAgainstSchema(substituted, valueSchema);
+        for (const issue of issues) {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "TEMPLATE_TARGET_MISMATCH",
+            source: SOURCE,
+            message: `${m.kind}/${name}: ${path} does not satisfy ${targetKind}'s contract: ${issue.message}`,
+            data: { resource, filePath, path: issue.path ? `${path}.${issue.path}` : path },
+          });
+        }
+      };
+
+      // Resolve the dispatch target's kind, if statically known. Object-form
+      // `invoke: { kind, name }` and `provide: { kind, name }` carry it; the
+      // string-form `invoke: "name"` does not (the matching resource entry would
+      // need to be located by expanded name — out of scope here).
+      const invoke = md.invoke;
+      const provide = md.provide;
+      let dispatchKind: string | undefined;
+      if (invoke && typeof invoke === "object" && !Array.isArray(invoke) && typeof invoke.kind === "string") {
+        dispatchKind = invoke.kind;
+      } else if (
+        provide &&
+        typeof provide === "object" &&
+        !Array.isArray(provide) &&
+        typeof provide.kind === "string"
+      ) {
+        dispatchKind = provide.kind;
+      }
+
+      // Top-level `inputs:` (sibling of `invoke:` / `provide:`) carries the
+      // values passed to the dispatch target's invoke(). Validate against the
+      // target's declared `inputType` when both sides have one.
+      if (dispatchKind && md.inputs && typeof md.inputs === "object") {
+        const targetSchema = lookupDefinitionTypeField(
+          dispatchKind,
+          "inputType",
+          defs,
+          aliases,
+          allManifests as Record<string, any>[],
+        );
+        if (targetSchema) {
+          emitTargetMismatch(dispatchKind, targetSchema, md.inputs, "inputs");
+        }
+      }
+
+      // Top-level `result:` (a sibling, only meaningful with `provide:`) is a
+      // post-call mapping that must satisfy the abstract this definition
+      // `extends` (`outputType`). The target's outputType lives on `provide.kind`
+      // and is what `result` is typed against *inside* CEL — separate role.
+      if (
+        provide &&
+        typeof provide === "object" &&
+        !Array.isArray(provide) &&
+        md.result &&
+        typeof md.result === "object"
+      ) {
+        const extendsValue = md.extends as string | undefined;
+        if (typeof extendsValue === "string" && extendsValue.length > 0) {
+          const abstractSchema = lookupDefinitionTypeField(
+            extendsValue,
+            "outputType",
+            defs,
+            aliases,
+            allManifests as Record<string, any>[],
+          );
+          if (abstractSchema) {
+            emitTargetMismatch(extendsValue, abstractSchema, md.result, "result");
+          }
+        }
+      }
+    }
+
     // Validate CEL syntax and context variable access in all manifests
     for (const m of allManifests) {
       const resource = { kind: m.kind, name: m.metadata?.name as string };
@@ -670,11 +861,18 @@ export class StaticAnalyzer {
           const manifestItem = matchedScope
             ? getManifestItem(path, matchedScope, m as Record<string, any>)
             : (m as Record<string, any>);
-          const resolvedContext = resolveContextAnnotations(
-            matchedContext,
-            manifestItem,
+          const rootForResolver = manifestRootForResolver(
+            m as Record<string, any>,
+            defs,
+            aliases,
             allManifests as Record<string, any>[],
           );
+          const resolvedContext = resolveContextAnnotations(matchedContext, manifestItem, {
+            manifestRoot: rootForResolver,
+            defs,
+            aliases,
+            allManifests: allManifests as Record<string, any>[],
+          });
           effectiveContext = mergeKernelGlobalsIntoContext(resolvedContext, kernelGlobals);
         }
 

package/src/builtins.ts

@@ -40,7 +40,121 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
     kind: "Telo.Definition",
     metadata: { name: "Definition", module: "Telo" },
     capability: "Telo.Template",
-    schema: { type: "object" },
+    // Top-level shape stays open (`additionalProperties: true`) so this change
+    // attaches x-telo-context annotations to known template-body fields without
+    // tightening the Telo.Definition shape itself. The annotations drive
+    // static CEL validation of expressions inside `resources:` / `invoke:` /
+    // `run:` / `provide:` / top-level `inputs:` / top-level `result:` against
+    // `self` (typed from `schema:`) and `inputs` (typed from `inputType:`,
+    // falling back to the extends-declared abstract).
+    //
+    // `inputs:` and `result:` live as top-level siblings of `invoke:` / `provide:`,
+    // matching how Run.Sequence steps factor dispatch from data. The dispatch
+    // entry-point (`invoke` / `provide` / `run`) determines how `inputs`/`result`
+    // are interpreted at runtime. See analyzer/nodejs/plans/template-internal-cel-validation.md.
+    schema: {
+      type: "object",
+      additionalProperties: true,
+      properties: {
+        resources: {
+          type: "array",
+          items: {
+            type: "object",
+            additionalProperties: true,
+            "x-telo-context": {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                self: { "x-telo-context-from-root": "schema" },
+                inputs: { "x-telo-context-from-root": "inputType" },
+              },
+            },
+          },
+        },
+        invoke: {
+          oneOf: [
+            {
+              type: "string",
+              "x-telo-context": {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  self: { "x-telo-context-from-root": "schema" },
+                },
+              },
+            },
+            {
+              type: "object",
+              additionalProperties: true,
+              properties: {
+                kind: { type: "string" },
+                name: {
+                  type: "string",
+                  "x-telo-context": {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                      self: { "x-telo-context-from-root": "schema" },
+                    },
+                  },
+                },
+              },
+            },
+          ],
+        },
+        provide: {
+          type: "object",
+          additionalProperties: true,
+          properties: {
+            kind: { type: "string" },
+            name: {
+              type: "string",
+              "x-telo-context": {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                  self: { "x-telo-context-from-root": "schema" },
+                },
+              },
+            },
+          },
+        },
+        run: {
+          type: "string",
+          "x-telo-context": {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              self: { "x-telo-context-from-root": "schema" },
+            },
+          },
+        },
+        inputs: {
+          type: "object",
+          additionalProperties: true,
+          "x-telo-context": {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              self: { "x-telo-context-from-root": "schema" },
+              inputs: { "x-telo-context-from-root": "inputType" },
+            },
+          },
+        },
+        result: {
+          type: "object",
+          additionalProperties: true,
+          "x-telo-context": {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              self: { "x-telo-context-from-root": "schema" },
+              result: { "x-telo-context-from-ref-kind": "provide/kind#outputType" },
+            },
+          },
+        },
+      },
+    },
   },
   {
     kind: "Telo.Definition",

package/src/validate-cel-context.ts

@@ -1,5 +1,21 @@
 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)
@@ -70,21 +86,61 @@ export 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.
+ *
+ * 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.
  *
- * 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`).
+ * - `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: Record<string, any>,
   manifestItem: Record<string, any>,
-  allManifests?: Record<string, any>[],
+  opts?: ContextResolveOpts | Record<string, any>[],
 ): Record<string, any> {
   if (!schema || typeof schema !== "object") return schema;
 
+  // Back-compat: third positional arg used to be `allManifests: Record<string, any>[]`.
+  const normalizedOpts: ContextResolveOpts = Array.isArray(opts)
+    ? { allManifests: opts }
+    : (opts ?? {});
+  const { manifestRoot = manifestItem, defs, aliases, allManifests } = normalizedOpts;
+
   const from = schema["x-telo-context-from"] as string | undefined;
   if (from) {
     const resolved = navigatePath(manifestItem, from.split("/")) as Record<string, any> | undefined;
@@ -96,6 +152,40 @@ export function resolveContextAnnotations(
     };
   }
 
+  const fromRoot = schema["x-telo-context-from-root"] as string | undefined;
+  const fromRefKind = schema["x-telo-context-from-ref-kind"] as string | undefined;
+  if (fromRoot || fromRefKind) {
+    if (fromRoot) {
+      const resolved = navigatePath(manifestRoot, fromRoot.split("/")) as
+        | Record<string, any>
+        | undefined;
+      if (resolved && typeof resolved === "object" && !Array.isArray(resolved)) {
+        return resolved;
+      }
+    }
+    if (fromRefKind && defs) {
+      const hashIdx = fromRefKind.indexOf("#");
+      if (hashIdx > 0) {
+        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) {
+          const canonical = aliases?.resolveKind(kindValue) ?? kindValue;
+          const def = defs.resolve(canonical);
+          const typeField = def
+            ? (def as Record<string, unknown>)[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"] as string | undefined;
   if (refFrom && allManifests) {
     const slashIdx = refFrom.indexOf("/");
@@ -129,7 +219,7 @@ export function resolveContextAnnotations(
   if (schema.properties) {
     const props: Record<string, any> = {};
     for (const [k, v] of Object.entries(schema.properties)) {
-      props[k] = resolveContextAnnotations(v as Record<string, any>, manifestItem, allManifests);
+      props[k] = resolveContextAnnotations(v as Record<string, any>, manifestItem, normalizedOpts);
     }
     return { ...schema, properties: props };
   }