@telorun/analyzer 0.11.0 → 1.1.0

package/src/analyzer.ts

@@ -14,6 +14,7 @@ import { buildKernelGlobalsSchema, mergeKernelGlobalsIntoContext } from "./kerne
 import { computeSuggestKind } from "./kind-suggest.js";
 import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
+import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
 import {
   celTypeSatisfiesJsonSchema,
   substituteCelFields,
@@ -28,6 +29,7 @@ import {
   resolveTypeFieldToSchema,
 } from "./validate-cel-context.js";
 import { validateExtends } from "./validate-extends.js";
+import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
@@ -629,6 +631,35 @@ export class StaticAnalyzer {
       }
     }
 
+    // Library env: rejection — `env:` on a Library `variables` / `secrets`
+    // entry is forbidden. The Library entry schema is otherwise open so that
+    // any JSON Schema property schema is valid; this targeted check produces
+    // a clear diagnostic instead of a generic "additional property" error.
+    for (const m of allManifests) {
+      if (m.kind !== "Telo.Library") continue;
+      const filePath = (m.metadata as { source?: string } | undefined)?.source;
+      const moduleName = m.metadata?.name as string | undefined;
+      const resource = moduleName ? { kind: m.kind, name: moduleName } : undefined;
+      for (const block of ["variables", "secrets"] as const) {
+        const entries = (m as Record<string, any>)[block];
+        if (!entries || typeof entries !== "object" || Array.isArray(entries)) continue;
+        for (const [entryName, entry] of Object.entries(entries)) {
+          if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+          if ("env" in (entry as Record<string, unknown>)) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "LIBRARY_ENV_KEY_REJECTED",
+              source: SOURCE,
+              message:
+                `Telo.Library ${block}/${entryName}: 'env:' is only permitted on Telo.Application entries. ` +
+                `Libraries must receive values from importers via the parent manifest's variables / secrets block.`,
+              data: { resource, filePath, path: `${block}.${entryName}.env` },
+            });
+          }
+        }
+      }
+    }
+
     // Build typed kernel globals schema so x-telo-context chain validation
     // recognises variables, secrets, resources, env automatically
     const kernelGlobals = buildKernelGlobalsSchema(allManifests);
@@ -776,17 +807,15 @@ export class StaticAnalyzer {
         }
       }
 
-      // 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`
+      // Top-level `result:` is a post-call mapping that must satisfy the abstract
+      // this definition `extends` (`outputType`). It's a sibling of whichever
+      // dispatch entry-point declared a kind-typed target (`provide:` or
+      // `invoke:`). The target's outputType lives on the dispatcher's `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 hasDispatchObject =
+        (provide && typeof provide === "object" && !Array.isArray(provide)) ||
+        (invoke && typeof invoke === "object" && !Array.isArray(invoke));
+      if (hasDispatchObject && md.result && typeof md.result === "object") {
         const extendsValue = md.extends as string | undefined;
         if (typeof extendsValue === "string" && extendsValue.length > 0) {
           const abstractSchema = lookupDefinitionTypeField(
@@ -920,10 +949,15 @@ export class StaticAnalyzer {
     // Validate `extends` fields and flag legacy `capability: <UserAbstract>` overload.
     diagnostics.push(...validateExtends(allManifests, defs, aliases));
 
+    // Validate provider coherence rules for `provide:` template-target definitions.
+    diagnostics.push(...validateProviderCoherence(allManifests, defs, aliases));
+
     // Validate throws: declarations and catches: coverage (rules 1, 2, 4, 7)
     diagnostics.push(...validateThrowsCoverage(allManifests, defs, aliases, this.celEnv));
 
-    return diagnostics;
+    // Reroute diagnostics on synthetic (inline-extracted) resources back to
+    // the chain root so position-index lookups land on the parent doc.
+    return rewriteSyntheticOrigins(diagnostics, allManifests);
   }
 
   analyzeErrors(

package/src/builtins.ts

@@ -149,7 +149,12 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
             additionalProperties: false,
             properties: {
               self: { "x-telo-context-from-root": "schema" },
-              result: { "x-telo-context-from-ref-kind": "provide/kind#outputType" },
+              result: {
+                "x-telo-context-from-ref-kind": [
+                  "provide/kind#outputType",
+                  "invoke/kind#outputType",
+                ],
+              },
             },
           },
         },
@@ -222,6 +227,44 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
+        // Application-level environment contract. Each entry layers `env:`
+        // (required, names the source env var) and `default:` (optional, used
+        // when the env var is unset) on top of an open JSON Schema property
+        // schema. `type:` constrains the coercion rule applied to the raw env
+        // string (scalars per-type; `object` / `array` via JSON.parse with the
+        // matching top-level type). All other JSON Schema keywords are passed
+        // through unchanged and applied to the coerced value via the standard
+        // schema validator. See kernel/nodejs/src/application-env.ts.
+        variables: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            required: ["env", "type"],
+            properties: {
+              env: { type: "string" },
+              type: {
+                type: "string",
+                enum: ["string", "integer", "number", "boolean", "object", "array"],
+              },
+              default: {},
+            },
+          },
+        },
+        secrets: {
+          type: "object",
+          additionalProperties: {
+            type: "object",
+            required: ["env", "type"],
+            properties: {
+              env: { type: "string" },
+              type: {
+                type: "string",
+                enum: ["string", "integer", "number", "boolean", "object", "array"],
+              },
+              default: {},
+            },
+          },
+        },
       },
       required: ["metadata"],
       additionalProperties: false,

package/src/index.ts

@@ -14,6 +14,7 @@ export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export type { ModuleKind } from "./module-kinds.js";
 export { parseLoadedFile } from "./parse-loaded-file.js";
 export type { ParseOptions } from "./parse-loaded-file.js";
+export { residualEntrySchema, residualEntrySchemaMap } from "./residual-schema.js";
 export {
     buildDocumentPositions,
     buildLineOffsets,

package/src/kernel-globals.ts

@@ -1,4 +1,5 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { residualEntrySchemaMap } from "./residual-schema.js";
 
 /**
  * Kernel global names available in every CEL evaluation context at runtime.
@@ -72,20 +73,17 @@ export function buildKernelGlobalsSchema(
 }
 
 /** Wrap a JSON Schema property map (like `Telo.Application.variables`) into a
- *  closed object schema suitable for chain-access validation. Falls back to
- *  an open map when the module declares no variables/secrets. */
+ *  closed object schema suitable for chain-access validation. For Application
+ *  entries the per-entry shape carries kernel-specific keys (`env`, `default`)
+ *  on top of an otherwise-standard JSON Schema property schema; those keys are
+ *  stripped via `residualEntrySchemaMap` so CEL sees the coerced shape, not
+ *  the env-binding wrapper. Library entries are pure JSON Schema property
+ *  schemas and pass through the same call unchanged. Falls back to an open map
+ *  when the module declares no variables/secrets. */
 function buildSchemaMapSchema(
   schemaMap: Record<string, any> | null | undefined,
 ): Record<string, any> {
-  if (!schemaMap || typeof schemaMap !== "object" || Array.isArray(schemaMap)) {
-    return { type: "object", additionalProperties: true };
-  }
-  const props: Record<string, any> = {};
-  for (const [key, value] of Object.entries(schemaMap)) {
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-      props[key] = value;
-    }
-  }
+  const props = residualEntrySchemaMap(schemaMap);
   if (Object.keys(props).length === 0) {
     return { type: "object", additionalProperties: true };
   }

package/src/normalize-inline-resources.ts

@@ -82,7 +82,14 @@ export function normalizeInlineResources(
       );
 
       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 as ResourceManifest & { metadata: { name: string } });
@@ -99,18 +106,42 @@ export function normalizeInlineResources(
  * 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: ResourceManifest,
   fieldPath: string,
   parentName: string,
+  parentKind: string,
   parentModule: string | undefined,
   invocationContext?: Record<string, any>,
 ): ResourceManifest[] {
   const extracted: ResourceManifest[] = [];
   const parts = fieldPath.split(".");
 
-  function traverse(obj: unknown, partsLeft: string[], nameParts: string[]): void {
+  function emit(
+    inline: Record<string, unknown>,
+    nameSegments: string[],
+    concretePath: string,
+  ): string {
+    const name = sanitizeName([parentName, ...nameSegments].join("_"));
+    extracted.push(
+      buildManifest(inline, name, parentKind, parentName, concretePath, parentModule, invocationContext),
+    );
+    return name;
+  }
+
+  function traverse(
+    obj: unknown,
+    partsLeft: string[],
+    nameParts: string[],
+    pathSoFar: string,
+  ): void {
     if (!obj || typeof obj !== "object" || partsLeft.length === 0) return;
 
     const [head, ...rest] = partsLeft;
@@ -123,15 +154,15 @@ function extractInlinesAtPath(
         const elem = container[mapKey];
         if (!elem || typeof elem !== "object") continue;
         const sanitizedKey = sanitizeName(mapKey);
+        const childPath = pathSoFar ? `${pathSoFar}.${mapKey}` : mapKey;
 
         if (rest.length === 0) {
           if (isInlineResource(elem as Record<string, unknown>)) {
-            const name = sanitizeName([parentName, ...nameParts, sanitizedKey].join("_"));
-            extracted.push(buildManifest(elem as Record<string, unknown>, name, parentModule, invocationContext));
+            const name = emit(elem as Record<string, unknown>, [...nameParts, sanitizedKey], childPath);
             container[mapKey] = { kind: (elem as Record<string, unknown>).kind, name };
           }
         } else {
-          traverse(elem, rest, [...nameParts, sanitizedKey]);
+          traverse(elem, rest, [...nameParts, sanitizedKey], childPath);
         }
       }
       return;
@@ -142,6 +173,7 @@ function extractInlinesAtPath(
     const container = obj as Record<string, unknown>;
     const val = container[key];
     if (val == null) return;
+    const keyPath = pathSoFar ? `${pathSoFar}.${key}` : key;
 
     if (isArr) {
       if (!Array.isArray(val)) return;
@@ -152,39 +184,41 @@ function extractInlinesAtPath(
           typeof (elem as Record<string, unknown>).name === "string"
             ? ((elem as Record<string, unknown>).name as string)
             : String(idx);
+        const childPath = `${keyPath}[${idx}]`;
 
         if (rest.length === 0) {
           // Array element itself is the ref slot
           if (isInlineResource(elem as Record<string, unknown>)) {
-            const name = sanitizeName([parentName, ...nameParts, key, elemId].join("_"));
-            extracted.push(buildManifest(elem as Record<string, unknown>, name, parentModule, invocationContext));
+            const name = emit(elem as Record<string, unknown>, [...nameParts, key, elemId], childPath);
             val[idx] = { kind: (elem as Record<string, unknown>).kind, name };
           }
         } else {
-          traverse(elem, rest, [...nameParts, key, elemId]);
+          traverse(elem, rest, [...nameParts, key, elemId], childPath);
         }
       }
     } else {
       if (rest.length === 0) {
         // val is the ref slot
         if (val && typeof val === "object" && !Array.isArray(val) && isInlineResource(val as Record<string, unknown>)) {
-          const name = sanitizeName([parentName, ...nameParts, key].join("_"));
-          extracted.push(buildManifest(val as Record<string, unknown>, name, parentModule, invocationContext));
+          const name = emit(val as Record<string, unknown>, [...nameParts, key], keyPath);
           container[key] = { kind: (val as Record<string, unknown>).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: Record<string, unknown>,
   name: string,
+  parentKind: string,
+  parentName: string,
+  pathFromParent: string,
   parentModule: string | undefined,
   invocationContext?: Record<string, any>,
 ): ResourceManifest {
@@ -200,6 +234,7 @@ function buildManifest(
       // Inherit parent module only if the inline doesn't already declare one
       ...(parentModule && !existingMeta.module ? { module: parentModule } : {}),
       ...(invocationContext ? { xTeloInvocationContext: invocationContext } : {}),
+      xTeloOrigin: { parentKind, parentName, pathFromParent },
     },
-  } as ResourceManifest;
+  } as unknown as ResourceManifest;
 }

package/src/position-metadata.ts

@@ -63,7 +63,11 @@ function offsetToPosition(offset: number, lineOffsets: number[]): Position {
 }
 
 /** 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: Document, lineOffsets: number[]): PositionIndex {
   const index: PositionIndex = new Map();
 
@@ -83,6 +87,9 @@ export function buildPositionIndex(doc: Document, lineOffsets: number[]): Positi
         const key = isScalar(pair.key) ? String(pair.key.value) : null;
         if (key == null) continue;
         const childPath = path ? `${path}.${key}` : key;
+        if (pair.key && (pair.key as any).range) {
+          recordNode(pair.key, `@key:${childPath}`);
+        }
         if (pair.value != null) {
           recordNode(pair.value, childPath);
           walk(pair.value, childPath);

package/src/reference-field-map.ts

@@ -63,23 +63,39 @@ export function isInlineResource(val: Record<string, unknown>): boolean {
   return true;
 }
 
-/** 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>`. */
-export function resolveFieldValues(obj: unknown, path: string): unknown[] {
+ *           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: unknown, path: string): ResolvedFieldEntry[] {
   const parts = path.split(".");
-  let current: unknown[] = [obj];
+  let current: ResolvedFieldEntry[] = [{ value: obj, path: "" }];
   for (const part of parts) {
     if (part === "{}") {
-      // Iterate the values of every map currently in `current`.
-      const next: unknown[] = [];
-      for (const item of current) {
-        if (!item || typeof item !== "object") continue;
-        for (const v of Object.values(item as Record<string, unknown>)) {
-          if (v != null) next.push(v);
+      const next: ResolvedFieldEntry[] = [];
+      for (const entry of current) {
+        if (!entry.value || typeof entry.value !== "object") continue;
+        for (const [k, v] of Object.entries(entry.value as Record<string, unknown>)) {
+          if (v != null) {
+            next.push({ value: v, path: entry.path ? `${entry.path}.${k}` : k });
+          }
         }
       }
       current = next;
@@ -87,19 +103,31 @@ export function resolveFieldValues(obj: unknown, path: string): unknown[] {
     }
     const isArray = part.endsWith("[]");
     const key = isArray ? part.slice(0, -2) : part;
-    const next: unknown[] = [];
-    for (const item of current) {
-      if (!item || typeof item !== "object") continue;
-      const val = (item as Record<string, unknown>)[key];
+    const next: ResolvedFieldEntry[] = [];
+    for (const entry of current) {
+      if (!entry.value || typeof entry.value !== "object") continue;
+      const val = (entry.value as Record<string, unknown>)[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: unknown, path: string): unknown[] {
+  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/src/residual-schema.ts

@@ -0,0 +1,49 @@
+/**
+ * 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: Record<string, unknown> | null | undefined,
+): Record<string, unknown> {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return { type: "object", additionalProperties: true };
+  }
+  const isAppEnvBinding = "env" in entry;
+  const out: Record<string, unknown> = {};
+  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: Record<string, unknown> | null | undefined,
+): Record<string, Record<string, unknown>> {
+  const out: Record<string, Record<string, unknown>> = {};
+  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 as Record<string, unknown>);
+    }
+  }
+  return out;
+}

package/src/rewrite-synthetic-origins.ts

@@ -0,0 +1,75 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AnalysisDiagnostic } from "./types.js";
+
+interface XTeloOrigin {
+  parentKind: string;
+  parentName: string;
+  pathFromParent: string;
+}
+
+function readOrigin(manifest: ResourceManifest | undefined): XTeloOrigin | undefined {
+  if (!manifest) return undefined;
+  const origin = (manifest.metadata as { xTeloOrigin?: XTeloOrigin } | undefined)?.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: AnalysisDiagnostic[],
+  manifests: ResourceManifest[],
+): AnalysisDiagnostic[] {
+  const byName = new Map<string, ResourceManifest>();
+  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 as
+      | { resource?: { kind?: string; name?: string }; path?: string; filePath?: string }
+      | undefined;
+    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: string = origin.parentKind;
+    let rootName: string = 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 as { source?: string } | undefined)?.source ?? data.filePath;
+
+    return {
+      ...d,
+      data: {
+        ...data,
+        resource: { kind: rootKind, name: rootName },
+        filePath: rootFilePath,
+        path: accumPath,
+      },
+    };
+  });
+}

package/src/validate-cel-context.ts

@@ -119,6 +119,11 @@ export function pathMatchesScope(exprPath: string, scope: string): boolean {
  *   `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.
  *
@@ -153,8 +158,16 @@ 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) {
+  const fromRefKindRaw = schema["x-telo-context-from-ref-kind"] as
+    | string
+    | string[]
+    | undefined;
+  const fromRefKinds = fromRefKindRaw == null
+    ? []
+    : Array.isArray(fromRefKindRaw)
+      ? fromRefKindRaw
+      : [fromRefKindRaw];
+  if (fromRoot || fromRefKinds.length > 0) {
     if (fromRoot) {
       const resolved = navigatePath(manifestRoot, fromRoot.split("/")) as
         | Record<string, any>
@@ -163,22 +176,22 @@ export function resolveContextAnnotations(
         return resolved;
       }
     }
-    if (fromRefKind && defs) {
-      const hashIdx = fromRefKind.indexOf("#");
-      if (hashIdx > 0) {
+    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) {
-          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;
-          }
+        if (typeof kindValue !== "string" || kindValue.length === 0) continue;
+        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;
         }
       }
     }