@telorun/analyzer 0.63.0 → 0.65.0

package/src/definition-registry.ts

@@ -8,10 +8,19 @@ import {
   isSchemaFromEntry,
   type ReferenceFieldMap,
 } from "./reference-field-map.js";
-import { createAjv, formatSingleError, navigateJsonPointer } from "./schema-compat.js";
+import { createAjv, navigateJsonPointer } from "./schema-compat.js";
+import {
+  formatSingleError,
+  reduceSchemaErrors,
+  schemaIssues,
+  type SchemaIssue,
+} from "./schema-error-report.js";
 import { effectiveAuthorSchema } from "./extends-resolution.js";
 
 /** Pure kind → ResourceDefinition map. No controller loading, no lifecycle. */
+/** What `ajv.compile` hands back: a predicate carrying its own `errors`. */
+type CompiledValidator = ((data: unknown) => boolean) & { errors?: any[] | null };
+
 export class DefinitionRegistry {
   constructor() {
     for (const def of KERNEL_BUILTINS) this.register(def);
@@ -22,6 +31,7 @@ export class DefinitionRegistry {
    *  across analyze() calls and no unbounded growth across the process lifetime. */
   private readonly ajv = createAjv();
   private readonly registeredSchemaIds = new Set<string>();
+  private readonly compiledValidators = new WeakMap<Record<string, any>, CompiledValidator>();
   /** The subset of `registeredSchemaIds` claimed by a kind's schema. Kinds and
    *  named `Telo.Type`s share one `telo://<module>/<Name>` id space, so this is
    *  what lets a colliding type name be reported instead of silently dropped. */
@@ -162,20 +172,47 @@ export class DefinitionRegistry {
     return schema && typeof schema === "object" ? (schema as Record<string, any>) : undefined;
   }
 
-  /** Validates data against a schema using this registry's AJV instance, which has all
-   *  registered definition schemas loaded — enabling cross-module $ref resolution.
-   *  A compile failure returns `[]` here; it is surfaced loudly (once, on the
-   *  owning definition) by `schemaCompileError` via the analyzer's
-   *  definition-schema compile check, so resources are never silently skipped. */
+  /**
+   * Validates a resource's configuration against its kind's schema, with the
+   * offending field's path — what a `SCHEMA_VIOLATION` diagnostic is built from.
+   *
+   * On THIS registry's AJV, which is the point: it holds every registered
+   * definition schema and every named `Telo.Type`, so a kind whose schema
+   * references a shape declared elsewhere is checked rather than skipped. The
+   * module-level instance this used to run on had none of them registered, so
+   * such a schema failed to compile and the failure was swallowed — a resource
+   * could be arbitrarily wrong and `telo check` reported nothing, while the
+   * kernel (whose validator does resolve the reference) rejected it at boot.
+   * Two AJVs answering one question is what made that possible; there is now
+   * one, and it is the same one `schemaCompileError` reports through.
+   */
   validateWithRefs(data: unknown, schema: Record<string, any>): string[] {
-    let validate: ReturnType<typeof this.ajv.compile>;
+    const validate = this.compiledFor(schema);
+    if (!validate || validate(data)) return [];
+    return reduceSchemaErrors(validate.errors).map(formatSingleError);
+  }
+
+  /** {@link validateWithRefs}, with the path each issue is anchored at. */
+  validateResourceConfig(data: unknown, schema: Record<string, any>): SchemaIssue[] {
+    const validate = this.compiledFor(schema);
+    if (!validate || validate(data)) return [];
+    return schemaIssues(validate.errors);
+  }
+
+  /** Memoized per schema OBJECT — the analyzer validates every resource of a
+   *  kind against the same one, and this runs at keystroke time in an editor.
+   *  A schema AJV refuses compiles to `undefined`; that is reported once,
+   *  anchored on the owning definition, by `schemaCompileError`. */
+  private compiledFor(schema: Record<string, any>): CompiledValidator | undefined {
+    const cached = this.compiledValidators.get(schema);
+    if (cached) return cached;
     try {
-      validate = this.ajv.compile(schema);
+      const validate = this.ajv.compile(schema);
+      this.compiledValidators.set(schema, validate);
+      return validate;
     } catch {
-      return [];
+      return undefined;
     }
-    if (validate(data)) return [];
-    return (validate.errors ?? []).map(formatSingleError);
   }
 
   /** Returns the AJV compile error for `schema`, or `undefined` when it compiles.
@@ -321,35 +358,53 @@ export class DefinitionRegistry {
     return expanded;
   }
 
-  private resolveSchemaFromSubMap(
+  /**
+   * The schema an `x-telo-schema-from` slot derives its shape from.
+   *
+   * Only the STATIC form resolves: an anchor that is a dotted alias-qualified
+   * kind (`HttpDispatch.Request/$defs/Matcher`). The polymorphic forms — a
+   * relative anchor, or a single-segment absolute one — name a sibling property
+   * whose value is known per resource, so a definition-level lookup would be
+   * guessing at one instance's shape.
+   *
+   * Its own method because a schema-from slot is otherwise INVISIBLE to anything
+   * reading `properties`: the field map needs the nested ref slots, and an IDE
+   * needs the very same node to offer a key or describe one. Two resolutions of
+   * one annotation would eventually disagree about which anchors are static.
+   */
+  resolveSchemaFromNode(
     schemaFrom: string,
-    fieldPath: string,
     ownerScope: AliasResolver,
-  ): ReferenceFieldMap | null {
+  ): Record<string, any> | undefined {
     const isAbsolute = schemaFrom.startsWith("/");
     const expr = isAbsolute ? schemaFrom.slice(1) : schemaFrom;
     const slashIdx = expr.indexOf("/");
-    if (slashIdx === -1) return null;
+    if (slashIdx === -1) return undefined;
     const anchorName = expr.slice(0, slashIdx);
     const jsonPointer = "/" + expr.slice(slashIdx + 1);
 
-    // Static form: absolute path whose anchor is a dotted alias (e.g.
-    // "HttpDispatch.Outcomes/$defs/Returns"). Polymorphic forms — relative
-    // anchors or single-segment absolute anchors — only resolve once we know a
-    // sibling property's value, which is per-resource.
-    if (!anchorName.includes(".")) return null;
+    if (!anchorName.includes(".")) return undefined;
 
     const targetKind = ownerScope.resolveKind(anchorName);
-    if (!targetKind) return null;
+    if (!targetKind) return undefined;
     const targetDef = this.resolve(targetKind);
-    if (!targetDef?.schema) return null;
+    if (!targetDef?.schema) return undefined;
     const subSchema = navigateJsonPointer(
       targetDef.schema as Record<string, unknown>,
       jsonPointer,
     );
-    if (!subSchema || typeof subSchema !== "object") return null;
+    if (!subSchema || typeof subSchema !== "object") return undefined;
+    return subSchema as Record<string, any>;
+  }
 
-    return buildFieldMapAtPath(subSchema as Record<string, any>, fieldPath);
+  private resolveSchemaFromSubMap(
+    schemaFrom: string,
+    fieldPath: string,
+    ownerScope: AliasResolver,
+  ): ReferenceFieldMap | null {
+    const subSchema = this.resolveSchemaFromNode(schemaFrom, ownerScope);
+    if (!subSchema) return null;
+    return buildFieldMapAtPath(subSchema, fieldPath);
   }
 
   /** Returns all definitions that transitively extend the given abstract kind.

package/src/find-manifest.ts

@@ -0,0 +1,19 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+/**
+ * The manifest a `(kind, name)` pair addresses.
+ *
+ * One implementation, because two consumers needed it and a manifest set is
+ * exactly the thing `ManifestAnalysis` exists to have one answer over. Undefined
+ * when the set holds no such resource — a document the author is still writing.
+ */
+export function findManifest(
+  manifests: readonly ResourceManifest[],
+  kind: string | undefined,
+  name: string | undefined,
+): ResourceManifest | undefined {
+  if (!kind || !name) return undefined;
+  return manifests.find(
+    (m) => m.kind === kind && (m.metadata as { name?: string } | undefined)?.name === name,
+  );
+}

package/src/index.ts

@@ -247,8 +247,16 @@ export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validat
 export type { RefSlotIssue } from "./validate-ref-slots.js";
 export { validateValueTypeSlots } from "./validate-value-type-slots.js";
 export type { ValueTypeSlotIssue } from "./validate-value-type-slots.js";
-export { checkSchemaCompatibility, selectUnionBranch } from "./schema-compat.js";
-export type { CompatibilityResult } from "./schema-compat.js";
+export { checkSchemaCompatibility, resolveRefIn, selectUnionBranch } from "./schema-compat.js";
+export type { CompatibilityResult, ExternalSchemaResolver } from "./schema-compat.js";
+export {
+  ajvErrorToPath,
+  formatAjvErrors,
+  formatSingleError,
+  reduceSchemaErrors,
+  schemaIssues,
+} from "./schema-error-report.js";
+export type { AjvErrorLike, SchemaIssue } from "./schema-error-report.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type {
     CelSiteEvent,
@@ -370,6 +378,19 @@ export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";
 export { CelParseError, buildCelSegments, wrapCelAst } from "./cel-ast.js";
 export type { CelNode, CelSegment } from "./cel-ast.js";
+
+// The CEL scope rule, and the way into it from outside the analysis pass. What
+// completes, what hovers and what type-checks are one answer because they are
+// one function.
+export { CelScopeResolver } from "./cel-scope.js";
+export type { CelScope, CelScopeInputs, CelSiteRef } from "./cel-scope.js";
+export { CelScopeQuery } from "./cel-scope-query.js";
+export type { CelScopeQueryContext, ContextDeclarationSite } from "./cel-scope-query.js";
+// The pairing of a registry and the manifests it analyzed — the one seam a host
+// threads for every question that needs both.
+export { navigateConcretePath } from "./manifest-path.js";
+export { ManifestAnalysis } from "./manifest-analysis.js";
+export type { ManifestRef } from "./manifest-analysis.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity, diagnosticFix } from "./types.js";
 export type {
     AnalysisDiagnostic,

package/src/invocation-contract.ts

@@ -1,4 +1,6 @@
 import { isLiveSlot, type ResourceDefinition, valueTypeOf } from "@telorun/sdk";
+import { AliasResolver, moduleScopedDefResolver, type ModuleScopes } from "./alias-resolver.js";
+import { DefinitionRegistry } from "./definition-registry.js";
 import {
   type ContractDirection,
   contractDeclarer,
@@ -14,6 +16,26 @@ import {
 
 export type { ContractDirection };
 
+/** The {@link ContractScope} the analyzer resolves invocation contracts in: kinds
+ *  resolve in the module that declared the definition they were read off (so an
+ *  `extends` chain crossing module boundaries re-scopes at every hop), and named
+ *  `telo#Type` references resolve against the flattened manifest list. `resolveIn`
+ *  is the top-level entry point, where the kind was written by the READING
+ *  module and there is no declaring definition yet. */
+export function analyzerContractScope(
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  scopes: ModuleScopes,
+  allManifests: Record<string, any>[],
+): ContractScope & { resolveIn(kind: string, module?: string): ResourceDefinition | undefined } {
+  const resolve = moduleScopedDefResolver<ResourceDefinition>(defs, aliases, scopes);
+  return {
+    resolveDefinition: resolve,
+    resolveIn: resolve.in,
+    typeManifestsFor: () => allManifests,
+  };
+}
+
 /**
  * The one answer to "what is this target's input / output schema".
  *

package/src/manifest-analysis.ts

@@ -0,0 +1,132 @@
+/**
+ * **One analyzed manifest set, and the questions asked of it.**
+ *
+ * Several answers a host needs require the SAME two things: the registry's
+ * definitions and aliases, and the manifest set they were resolved against. The
+ * registry deliberately holds no manifests — it is populated per analysis and
+ * reused across them — so each such answer would otherwise become another
+ * factory on the registry and another optional parameter on every IDE entry
+ * point. Four of those arrived in short order (CEL scope, step declarations,
+ * context-binding declarations, invocation contracts) and the next one is not
+ * hypothetical.
+ *
+ * So the pairing is named once and the questions hang off it. A host threads ONE
+ * object and gains later questions for free; each facet keeps its own honest
+ * name rather than accreting onto whichever one happened to exist first.
+ *
+ * Nothing here re-implements an answer. `contractFor` is the shared
+ * {@link resolveContract} — the one `telo check` runs and the kernel binds at
+ * dispatch — given the scope to run in; `celScope` is the same
+ * {@link CelScopeQuery} the analysis pass's rule is built from. That is the
+ * whole point: a completion list is a claim about what the checker accepts, and
+ * a second implementation of any of these could not be held to it.
+ */
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { AliasResolver, type ModuleScopes } from "./alias-resolver.js";
+import { CelScopeQuery, type CelScopeQueryContext } from "./cel-scope-query.js";
+import { DefinitionRegistry } from "./definition-registry.js";
+import type { ContractDirection } from "./extends-resolution.js";
+import { analyzerContractScope, resolveContract } from "./invocation-contract.js";
+import { findManifest } from "./find-manifest.js";
+import { isModuleKind } from "./module-kinds.js";
+
+/**
+ * A reference as the loader leaves it — the internal `{kind, name, alias?}`
+ * shape `resolveRefSentinels` rewrites `!ref` into.
+ */
+export interface ManifestRef {
+  kind?: string;
+  name?: string;
+  alias?: string;
+}
+
+export class ManifestAnalysis {
+  private readonly scopes: ModuleScopes;
+  private celScopeQuery: CelScopeQuery | undefined;
+
+  constructor(
+    readonly manifests: ResourceManifest[],
+    private readonly ctx: CelScopeQueryContext,
+  ) {
+    const rootModules = new Set<string>();
+    for (const m of manifests) {
+      if (isModuleKind(m.kind) && m.metadata?.name) rootModules.add(m.metadata.name as string);
+    }
+    this.scopes = { aliasesByModule: ctx.aliasesByModule, rootModules };
+  }
+
+  /** What CEL sees, per site. Built on first use — its indices are a function of
+   *  the whole set, and a host that never opens a CEL body should not pay for
+   *  them. */
+  get celScope(): CelScopeQuery {
+    return (this.celScopeQuery ??= new CelScopeQuery(this.manifests, this.ctx));
+  }
+
+  /** The manifest a `(kind, name)` pair addresses. */
+  resourceFor(kind: string | undefined, name: string | undefined): ResourceManifest | undefined {
+    return findManifest(this.manifests, kind, name);
+  }
+
+  /**
+   * The invocation contract of the resource a reference names.
+   *
+   * The shared resolver, so an editor offering a target's input keys is offering
+   * exactly what `telo check` validates that call site against and what the
+   * kernel binds at dispatch. Layered instance-first: a resource declaring its
+   * own `inputType:` narrows the kind's, which is the common case for a
+   * `Run.Sequence` used as a handler.
+   */
+  contractFor(ref: ManifestRef, direction: ContractDirection): Record<string, any> | undefined {
+    const target = this.resolveRef(ref);
+    const definition = ref.kind ? this.definitionFor(ref.kind) : undefined;
+    if (!target && !definition) return undefined;
+    return resolveContract(
+      direction,
+      target as Record<string, any> | undefined,
+      definition,
+      analyzerContractScope(
+        this.ctx.defs,
+        this.ctx.aliases,
+        this.scopes,
+        this.manifests as Record<string, any>[],
+      ),
+    )?.schema;
+  }
+
+  /**
+   * The manifest a reference names.
+   *
+   * An ALIAS narrows before the name does: a flattened set carries every
+   * imported library's exported instances, so two libraries exporting a `store`
+   * are two manifests with one name. Matching the alias to its target module
+   * picks the right one; where the alias resolves to nothing the name alone is
+   * used, which is what a local reference needs anyway.
+   */
+  private resolveRef(ref: ManifestRef): ResourceManifest | undefined {
+    if (!ref.name) return undefined;
+    const byName = this.manifests.filter(
+      (m) => (m.metadata as { name?: string } | undefined)?.name === ref.name,
+    );
+    if (byName.length === 0) return undefined;
+    if (byName.length === 1) return byName[0];
+
+    const targetModule = ref.alias ? this.ctx.aliases.moduleForAlias?.(ref.alias) : undefined;
+    if (targetModule) {
+      const scoped = byName.find(
+        (m) => (m.metadata as { module?: string } | undefined)?.module === targetModule,
+      );
+      if (scoped) return scoped;
+    }
+    // Several candidates and nothing to choose between them: refusing is the
+    // honest answer, since typing a call site against the wrong resource's
+    // contract is worse than typing it against none.
+    return ref.kind ? byName.find((m) => m.kind === ref.kind) : undefined;
+  }
+
+  private definitionFor(kind: string): ResourceDefinition | undefined {
+    const canonical = this.ctx.aliases.resolveKind(kind);
+    return this.ctx.defs.resolve(kind) ?? (canonical ? this.ctx.defs.resolve(canonical) : undefined);
+  }
+}
+
+export type { CelScopeQueryContext, AliasResolver, DefinitionRegistry };

package/src/manifest-path.ts

@@ -0,0 +1,34 @@
+/**
+ * Navigating a MANIFEST by a concrete path (`routes[0].request.schema.query`).
+ *
+ * The counterpart to `schema-walk.ts`, which navigates a schema: this addresses
+ * the author's own document, indices and all. Its own module because three
+ * places needed it independently — the CEL scope query resolving a context
+ * binding's declaration, the call-site checker resolving an argument map, and
+ * the IDE resolving the same map for completion — and three copies of one
+ * traversal is exactly what the shared-answer rule exists to prevent.
+ */
+
+/**
+ * The value at `path`, or `undefined` when any segment is absent.
+ *
+ * Absence is what makes a candidate path a CHECK rather than a guess: a caller
+ * offering several possible shapes can try each and know a hit is a real node.
+ */
+export function navigateConcretePath(root: Record<string, any>, path: string): unknown {
+  let current: unknown = root;
+  for (const segment of path.split(".")) {
+    if (!segment) continue;
+    const match = segment.match(/^([^[]*)((?:\[\d+\])*)$/);
+    if (!match) return undefined;
+    if (match[1]) {
+      if (current === null || typeof current !== "object") return undefined;
+      current = (current as Record<string, unknown>)[match[1]];
+    }
+    for (const index of match[2].matchAll(/\[(\d+)\]/g)) {
+      if (!Array.isArray(current)) return undefined;
+      current = current[Number(index[1])];
+    }
+  }
+  return current;
+}

package/src/schema-compat.ts

@@ -14,6 +14,7 @@ import {
   valueTypePlaceholder,
 } from "@telorun/sdk";
 import { ManifestRootSchema } from "./manifest-schemas.js";
+import { schemaIssues, type SchemaIssue } from "./schema-error-report.js";
 import { registerTeloKeywords } from "./value-type-keyword.js";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
@@ -255,55 +256,8 @@ function compare(
   }
 }
 
-export function formatSingleError(err: any): string {
-  const p = err.instancePath || "/";
-  const params = err.params ?? {};
-  switch (err.keyword) {
-    case "additionalProperties":
-      return `${p} must NOT have additional properties ('${params.additionalProperty}' is not allowed)`;
-    case "required":
-      return `${p} is missing required property '${params.missingProperty}'`;
-    case "enum":
-      return `${p} ${err.message ?? "is invalid"} (${(params.allowedValues as unknown[])?.join(" | ")})`;
-    case "type":
-      return `${p} must be ${params.type} (got ${typeof err.data})`;
-    default:
-      return `${p} ${err.message ?? "is invalid"}`;
-  }
-}
-
-export function formatAjvErrors(errors: any[] | null | undefined): string {
-  if (!errors || errors.length === 0) return "Unknown schema error";
-  return errors.map(formatSingleError).join("; ");
-}
-
-/** Converts an AJV error object to a dotted path string compatible with PositionIndex keys.
- *  e.g. instancePath "/config/routes/0/handler" → "config.routes[0].handler"
- *  For "required" keyword errors, appends the missing property to the parent path. */
-function ajvErrorToPath(err: any): string {
-  const instancePath = (err.instancePath ?? "") as string;
-  const parts = instancePath.split("/").filter((p) => p !== "");
-  let result = "";
-  for (const part of parts) {
-    if (/^\d+$/.test(part)) {
-      result += `[${part}]`;
-    } else {
-      result += result ? `.${part}` : part;
-    }
-  }
-  if (err.keyword === "required" && err.params?.missingProperty) {
-    const missing = err.params.missingProperty as string;
-    result += result ? `.${missing}` : missing;
-  }
-  return result;
-}
-
-/** A schema validation issue with a dotted-path pointer to the offending field. */
-export interface SchemaIssue {
-  message: string;
-  /** Dotted path to the field (e.g. "config.handler"). Empty string means root. */
-  path: string;
-}
+export { formatAjvErrors, formatSingleError } from "./schema-error-report.js";
+export type { SchemaIssue } from "./schema-error-report.js";
 
 /** Does `schema` compile as-authored? Used to tell a malformed module schema
  *  (the author's problem) apart from a fault we introduced while normalizing it. */
@@ -335,10 +289,7 @@ export function validateAgainstSchema(data: unknown, schema: Record<string, any>
     compiledSchemaValidators.set(schema, validate);
   }
   if (validate(data)) return [];
-  return (validate.errors ?? []).map((err: any) => ({
-    message: formatSingleError(err),
-    path: ajvErrorToPath(err),
-  }));
+  return schemaIssues(validate.errors);
 }
 
 /** Resolves a JSON Pointer (RFC 6901, must start with "/") into a schema object.
@@ -640,16 +591,55 @@ function objectPlaceholder(schema: Record<string, any>): Record<string, unknown>
 
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
 
-/** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
-export function resolveRef(schema: Record<string, any>, root: Record<string, any>): Record<string, any> {
-  if (schema.$ref && typeof schema.$ref === "string" && schema.$ref.startsWith("#/$defs/")) {
-    const defName = schema.$ref.slice("#/$defs/".length);
-    const resolved = root.$defs?.[defName];
-    if (resolved) return resolved;
-  }
-  return schema;
+/**
+ * Resolve a `$ref` — the document-local `#/$defs/...` form against `root`, and
+ * anything else through `external` when a caller supplies one.
+ *
+ * A named shape is addressed by a registered id (`telo:<module>/<Type>`), which
+ * lives in a schema store rather than in this document, so without the hook a
+ * walk stops at the reference and treats a described value as undescribed:
+ * every CEL leaf under it is handed the schema-unaware `""` placeholder and
+ * then rejected against a branch it was never measured against. The caller
+ * supplies the store because only the caller has one.
+ */
+export function resolveRef(
+  schema: Record<string, any>,
+  root: Record<string, any>,
+  external?: ExternalSchemaResolver,
+): Record<string, any> {
+  return resolveRefIn(schema, root, external).schema;
+}
+
+/**
+ * {@link resolveRef}, reporting the ROOT the result's own `#/...` references
+ * resolve against.
+ *
+ * Following an external reference enters another document, and a `$ref` inside
+ * it is relative to THAT document — which is the whole of how a shape declares
+ * its own vocabulary (`anyOf: [{$ref: "#/$defs/Text"}, …]`). Resolving those
+ * against the referring document finds nothing, and a walker that then treats
+ * the branches as unconstrained accepts every one of them, resolves the union
+ * to nothing, and hands the values underneath an untyped stand-in. So the base
+ * travels with the schema.
+ */
+export function resolveRefIn(
+  schema: Record<string, any>,
+  root: Record<string, any>,
+  external?: ExternalSchemaResolver,
+): { schema: Record<string, any>; root: Record<string, any> } {
+  if (!schema.$ref || typeof schema.$ref !== "string") return { schema, root };
+  if (schema.$ref === "#") return { schema: root, root };
+  if (schema.$ref.startsWith("#/$defs/")) {
+    const resolved = root.$defs?.[schema.$ref.slice("#/$defs/".length)];
+    return resolved ? { schema: resolved, root } : { schema, root };
+  }
+  const target = external?.(schema.$ref);
+  return target ? { schema: target, root: target } : { schema, root };
 }
 
+/** Looks a registered schema up by its `$id`. */
+export type ExternalSchemaResolver = (ref: string) => Record<string, any> | undefined;
+
 /** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
 /**
  * The `oneOf` / `anyOf` branch a value is written against, when exactly one fits.
@@ -671,6 +661,7 @@ export function selectUnionBranch(
   schema: Record<string, any>,
   data: unknown,
   root: Record<string, any>,
+  external?: ExternalSchemaResolver,
 ): Record<string, any> {
   const branches = (schema.oneOf ?? schema.anyOf) as Record<string, any>[] | undefined;
   if (!Array.isArray(branches) || branches.length === 0) return schema;
@@ -692,7 +683,7 @@ export function selectUnionBranch(
   if (!kind) return schema;
 
   const fits = branches
-    .map((b) => resolveRef(b, root))
+    .map((b) => resolveRef(b, root, external))
     .filter((b) => {
       const types = Array.isArray(b.type) ? b.type : b.type ? [b.type] : [];
       if (types.length > 0 && !types.includes(kind)) return false;
@@ -733,10 +724,13 @@ export function collectProperties(schema: Record<string, any>): Record<string, a
 
 /** Deep-clone `data`, replacing every pure CEL template string (`${{ expr }}`) with a
  *  schema-appropriate placeholder so AJV can validate non-CEL fields without false positives. */
-export function substituteCelFields(
-  data: unknown,
-  schema: Record<string, any>,
-  rootSchema?: Record<string, any>,
+/** Everything {@link substituteCelFields} does beyond walking the value.
+ *
+ *  One object rather than trailing positionals: the resolver is the parameter a
+ *  caller most needs and was the LAST of six, so reaching it meant counting
+ *  `undefined`s — and a caller that stopped counting one short simply got the
+ *  old blind behaviour, silently. Two of them did. */
+export interface SubstituteOptions {
   /** Called with the dotted path of every value replaced by a placeholder.
    *
    *  A placeholder is a stand-in for something only known at runtime, so its
@@ -746,11 +740,28 @@ export function substituteCelFields(
    *  so making every placeholder acceptable is not achievable in general —
    *  knowing where not to look is. Structural findings survive because they are
    *  located at the CONTAINER, not at the substituted leaf. */
-  onSubstitute?: (path: string) => void,
-  path = "",
+  onSubstitute?: (path: string) => void;
+  /** Dotted path of `data` within the resource, for `onSubstitute`. */
+  path?: string;
+  /** Resolves a named shape (`telo:<module>/<Type>`) to its schema. Without it
+   *  a slot described by one reads as undescribed and every CEL leaf beneath it
+   *  is handed the typeless `""` stand-in — which the shape then rejects, so a
+   *  perfectly valid expression is reported as a violation. */
+  external?: ExternalSchemaResolver;
+}
+
+export function substituteCelFields(
+  data: unknown,
+  schema: Record<string, any>,
+  rootSchema?: Record<string, any>,
+  options: SubstituteOptions = {},
 ): unknown {
-  const root = rootSchema ?? schema;
-  const resolved = selectUnionBranch(resolveRef(schema, root), data, root);
+  const { onSubstitute, external } = options;
+  const path = options.path ?? "";
+  const base = rootSchema ?? schema;
+  const entered = resolveRefIn(schema, base, external);
+  const root = entered.root;
+  const resolved = selectUnionBranch(entered.schema, data, root, external);
   const mark = () => onSubstitute?.(path);
 
   if (typeof data === "string" && CEL_PURE_RE.test(data)) {
@@ -789,9 +800,13 @@ export function substituteCelFields(
     return celPlaceholderForSchema(resolved);
   }
   if (Array.isArray(data)) {
-    const itemSchema = resolveRef((resolved.items ?? {}) as Record<string, any>, root);
-    return data.map((item, i) =>
-      substituteCelFields(item, itemSchema, root, onSubstitute, `${path}[${i}]`),
+    const item = resolveRefIn((resolved.items ?? {}) as Record<string, any>, root, external);
+    return data.map((element, i) =>
+      substituteCelFields(element, item.schema, item.root, {
+        onSubstitute,
+        path: `${path}[${i}]`,
+        external,
+      }),
     );
   }
   if (data !== null && typeof data === "object") {
@@ -802,13 +817,11 @@ export function substituteCelFields(
         : undefined;
     const result: Record<string, unknown> = {};
     for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
-      result[k] = substituteCelFields(
-        v,
-        (props[k] ?? addlProps ?? {}) as Record<string, any>,
-        root,
+      result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}) as Record<string, any>, root, {
         onSubstitute,
-        path ? `${path}.${k}` : k,
-      );
+        path: path ? `${path}.${k}` : k,
+        external,
+      });
     }
     return result;
   }