@telorun/analyzer 0.64.0 → 0.66.0

package/src/schema-projection.ts

@@ -35,6 +35,8 @@
  * derivation can reach.
  */
 
+import { isRefSentinel } from "@telorun/templating";
+
 /** How a kind's entry collection projects to an object schema. */
 export interface SchemaProjection {
   /** JSON Pointer, from the resource root, to the entries. */
@@ -48,6 +50,33 @@ export interface SchemaProjection {
   readonly nullable?: string;
   /** Entry field that wraps the mapped node in an array. */
   readonly array?: string;
+  /**
+   * How an entry whose keyed field holds a REFERENCE projects.
+   *
+   * The map is keyed on the field's VALUE, and a reference is not a key, so a
+   * `type:` holding one falls through to this path. It is declared as data by the
+   * backend, which is what keeps the analyzer from learning that an enum exists:
+   * `from` names the field of the target declaration to read, `keyword` the
+   * schema keyword its values become, and `base` / `baseFrom` where the node's
+   * own type comes from — a literal for an engine whose named type IS its own
+   * base, a field of the target for one that declares a storage class.
+   *
+   * A backend that declares none projects exactly as it did before.
+   */
+  readonly reference?: ProjectionReference;
+}
+
+/** The reference path of a projection — see {@link SchemaProjection.reference}. */
+export interface ProjectionReference {
+  /** Field of the TARGET declaration whose value the keyword takes. */
+  readonly from: string;
+  /** The JSON Schema keyword those values become (`enum`). */
+  readonly keyword: string;
+  /** The node the keyword is added to, written literally. */
+  readonly base?: Record<string, unknown>;
+  /** Field of the target declaration naming a value in the kind's own
+   *  `x-telo-schema-map`, whose mapped node is the base. */
+  readonly baseFrom?: string;
 }
 
 export type SchemaMap = Readonly<Record<string, Record<string, unknown>>>;
@@ -71,6 +100,19 @@ export function readSchemaProjection(definition: unknown): SchemaProjection | un
     nameField: typeof raw.name === "string" ? raw.name : undefined,
     nullable: typeof raw.nullable === "string" ? raw.nullable : undefined,
     array: typeof raw.array === "string" ? raw.array : undefined,
+    reference: readProjectionReference(raw.reference),
+  };
+}
+
+function readProjectionReference(raw: unknown): ProjectionReference | undefined {
+  if (!isObject(raw)) return undefined;
+  const { from, keyword, base, baseFrom } = raw;
+  if (typeof from !== "string" || typeof keyword !== "string") return undefined;
+  return {
+    from,
+    keyword,
+    base: isObject(base) ? (base as Record<string, unknown>) : undefined,
+    baseFrom: typeof baseFrom === "string" ? baseFrom : undefined,
   };
 }
 
@@ -94,7 +136,35 @@ export function schemaProjectionIsMisplaced(definition: unknown): boolean {
   return isObject(schema) && schema["x-telo-schema-projection"] !== undefined;
 }
 
+/**
+ * The schema node that CARRIES the value vocabulary — the node itself, or the
+ * branch of a union that declares the map.
+ *
+ * A slot unioning a closed value vocabulary with a reference keeps its map on the
+ * value branch, exactly as the ref-slot reader peels the same union for its
+ * constraint. Exported because the strict half checks the map against the same
+ * branch's `enum`, and two implementations of "which branch is the value one"
+ * would eventually disagree — silently, since the failure of missing one is a
+ * completeness check that quietly stops running.
+ */
+export function schemaMapBranch(node: unknown): Record<string, unknown> | undefined {
+  if (!isObject(node)) return undefined;
+  if (node["x-telo-schema-map"] !== undefined) return node;
+  for (const key of ["oneOf", "anyOf"] as const) {
+    const branches = node[key];
+    if (!Array.isArray(branches)) continue;
+    for (const branch of branches) {
+      if (isObject(branch) && branch["x-telo-schema-map"] !== undefined) return branch;
+    }
+  }
+  return undefined;
+}
+
 export function readSchemaMap(node: unknown): SchemaMap | undefined {
+  return ownSchemaMap(schemaMapBranch(node));
+}
+
+function ownSchemaMap(node: unknown): SchemaMap | undefined {
   if (!isObject(node)) return undefined;
   const raw = node["x-telo-schema-map"];
   if (!isObject(raw)) return undefined;
@@ -146,6 +216,76 @@ export function projectionKeyMap(
   return readSchemaMap(entry.properties[projection.key]);
 }
 
+/**
+ * The node an entry whose keyed field holds a REFERENCE projects to.
+ *
+ * This is the one place a projection crosses to another declaration, and it is
+ * a deliberate exception to the projection's lossiness: length, precision and
+ * collation stop at the boundary because the database enforces them, while a
+ * domain crosses because it IS the type at the granularity a consumer acts on —
+ * the enum in a CRUD model's OpenAPI operation, a completion list in the editor,
+ * a filter a repository can reject before the query.
+ *
+ * **A reference that cannot be read projects OPEN, never to nothing**, and that
+ * is the opposite of the rule an unmapped VALUE follows. The two failures are
+ * not the same failure: an unmapped value is a gap in the kind's own vocabulary,
+ * so there is no entry to speak of, while an unreadable reference names an entry
+ * the declaration plainly HAS and only leaves its type unknown. Dropping it made
+ * the projection deny the entry exists — a table whose enum reference had a typo
+ * reported `'status' is not allowed` against a column declared three lines up,
+ * blaming the seed row for the reference's mistake. Open is the honest
+ * under-approximation, and the reason is reported alongside.
+ */
+function referencedNode(
+  value: unknown,
+  entryName: string,
+  projection: SchemaProjection,
+  map: SchemaMap,
+  options?: {
+    readonly scope?: ProjectionScope;
+    readonly pointer?: string;
+    readonly failures?: ProjectionFailure[];
+  },
+): Record<string, unknown> | undefined {
+  const reference = projection.reference;
+  if (!reference || !isObject(value)) return undefined;
+  // Through the single reader, so the name in the diagnostic is the one the
+  // author wrote whichever shape the slot holds — reading `value.name` here
+  // reported `<unnamed>` for an unresolved `!ref`, which is precisely the case
+  // that produces the diagnostic.
+  const name = readProjectionRef(value)?.name ?? "<unnamed>";
+  const report = (): Record<string, unknown> => {
+    options?.failures?.push({
+      reason: "entry-reference",
+      // The EMPTY pointer means the projected declaration is the one carrying
+      // the diagnostic, so the entry's own path is a real anchor in that file —
+      // the column, not the document root. Any other pointer names a slot
+      // holding a reference to a DIFFERENT manifest, whose entry paths mean
+      // nothing here, so the slot stays the anchor.
+      pointer:
+        options?.pointer === ""
+          ? `${projection.entries}/${entryName}`
+          : (options?.pointer ?? projection.entries),
+      entry: entryName,
+      name,
+    });
+    return {};
+  };
+  const found = options?.scope?.resolveManifest(value);
+  if (!found || "ambiguous" in found) return report();
+
+  const values = (found.manifest as Record<string, unknown>)[reference.from];
+  if (!Array.isArray(values) || values.length === 0) return report();
+
+  let base: Record<string, unknown> | undefined = reference.base;
+  if (reference.baseFrom !== undefined) {
+    const declared = (found.manifest as Record<string, unknown>)[reference.baseFrom];
+    base = typeof declared === "string" ? map[declared] : undefined;
+  }
+  if (!base) return report();
+  return { ...base, [reference.keyword]: values };
+}
+
 /**
  * Project one declaration to an object schema.
  *
@@ -164,6 +304,15 @@ export function projectEntries(
   manifest: unknown,
   projection: SchemaProjection,
   map: SchemaMap,
+  /** What a REFERENCE at the keyed field is resolved through, and where a
+   *  failure to resolve one is reported. A caller with no scope cannot resolve
+   *  one, so such an entry projects OPEN — present, untyped — rather than
+   *  vanishing from the row. */
+  options?: {
+    readonly scope?: ProjectionScope;
+    readonly pointer?: string;
+    readonly failures?: ProjectionFailure[];
+  },
 ): Record<string, unknown> | undefined {
   const entries = navigate(manifest, projection.entries);
   if (entries === undefined) return undefined;
@@ -172,7 +321,10 @@ export function projectEntries(
   const consider = (name: string | undefined, entry: unknown): void => {
     if (!isObject(entry) || name === undefined) return;
     const key = entry[projection.key];
-    const mapped = typeof key === "string" ? map[key] : undefined;
+    const mapped =
+      typeof key === "string"
+        ? map[key]
+        : referencedNode(key, name, projection, map, options);
     // A value with no map entry projects to nothing rather than to `any`: the
     // vocabulary is the kind's own enum, so an unmapped value is a gap in the
     // kind's declaration, not a shape to guess at.
@@ -215,10 +367,25 @@ export interface ProjectionRef {
   readonly alias?: string;
 }
 
-/** The `{kind, name, alias?}` reference a value holds, or undefined. Exported so
- *  a host whose slot may hold EITHER shape can fall back to this reading. */
+/**
+ * The `{kind, name, alias?}` reference a value holds, or undefined. Exported so
+ * a host whose slot may hold EITHER shape can fall back to this reading.
+ *
+ * The unresolved `!ref` SENTINEL is read too. `resolveRefSentinels` normally
+ * rewrites one before this pass, but not when the reference names nothing — and
+ * that is exactly when a projection failure is reported, so reading only the
+ * resolved shape made the diagnostic name the target `<unnamed>`, which is the
+ * one fact the author needed from it. A round-trip host (`compile` off) carries
+ * the sentinel for every reference, resolved or not.
+ */
 export function readProjectionRef(value: unknown): ProjectionRef | undefined {
   if (!isObject(value)) return undefined;
+  if (isRefSentinel(value)) {
+    const dot = value.source.indexOf(".");
+    return dot > 0
+      ? { name: value.source.slice(dot + 1), alias: value.source.slice(0, dot) }
+      : { name: value.source };
+  }
   const name = value.name;
   if (typeof name !== "string") return undefined;
   return {
@@ -306,11 +473,42 @@ export function manifestListScope(
   };
 }
 
+/**
+ * Why a slot could not be typed from a projection.
+ *
+ * Each reason is a DIFFERENT repair, which is why the three ways a target can
+ * carry no usable projection are kept apart rather than collapsed into
+ * `no-projection`: that one message ("declares no 'x-telo-schema-projection'")
+ * was printed for a kind that declares one whose key field carries no map, and
+ * for a declaration whose entry collection is simply absent — accusing the wrong
+ * author of the wrong omission in both.
+ */
 export type ProjectionFailure =
   | { readonly reason: "no-ref"; readonly pointer: string }
   | { readonly reason: "unresolved"; readonly pointer: string; readonly name: string }
   | { readonly reason: "ambiguous"; readonly pointer: string; readonly name: string }
-  | { readonly reason: "no-projection"; readonly pointer: string; readonly kind: string };
+  /** The target's KIND declares no `x-telo-schema-projection` at all. */
+  | { readonly reason: "no-projection"; readonly pointer: string; readonly kind: string }
+  /** It declares one, but the field it keys on carries no `x-telo-schema-map`. */
+  | { readonly reason: "no-projection-map"; readonly pointer: string; readonly kind: string }
+  /** Both are declared and the DECLARATION holds no entry collection to project
+   *  — an absent `columns:`, or a value that is not a collection. */
+  | {
+      readonly reason: "no-entries";
+      readonly pointer: string;
+      readonly kind: string;
+      readonly entries: string;
+    }
+  /** An ENTRY of the projected declaration references a shape that could not be
+   *  read. Reported rather than dropped: the entry would silently vanish from
+   *  the projected row, so a consumer naming it would be told the property does
+   *  not exist. */
+  | {
+      readonly reason: "entry-reference";
+      readonly pointer: string;
+      readonly entry: string;
+      readonly name: string;
+    };
 
 function refTarget(
   value: unknown,
@@ -331,10 +529,25 @@ function refTarget(
   return { manifest, definition };
 }
 
+/** The declaration the annotation is written on, as a projection target. */
+function ownTarget(
+  manifest: Record<string, any>,
+  scope: ProjectionScope,
+): { manifest: Record<string, any>; definition: Record<string, any> } | ProjectionFailure {
+  if (typeof manifest.kind !== "string") {
+    return { reason: "no-ref", pointer: "" };
+  }
+  const definition = scope.resolveDefinition(manifest.kind);
+  if (!definition) return { reason: "no-projection", pointer: "", kind: manifest.kind };
+  return { manifest, definition };
+}
+
 export function describeProjectionFailure(failure: ProjectionFailure): string {
   switch (failure.reason) {
     case "no-ref":
-      return `'${failure.pointer}' does not hold a reference, so there is no declaration to project.`;
+      return failure.pointer === ""
+        ? "this resource declares no 'kind:', so there is no definition to project it through."
+        : `'${failure.pointer}' does not hold a reference, so there is no declaration to project.`;
     case "unresolved":
       return `'${failure.pointer}' references '${failure.name}', which resolves to no resource.`;
     case "ambiguous":
@@ -347,6 +560,23 @@ export function describeProjectionFailure(failure: ProjectionFailure): string {
         `'${failure.pointer}' references a resource of kind '${failure.kind}', which declares no ` +
         `'x-telo-schema-projection' — so there is nothing for this slot to be typed from.`
       );
+    case "no-projection-map":
+      return (
+        `kind '${failure.kind}' declares an 'x-telo-schema-projection' whose key field carries ` +
+        `no 'x-telo-schema-map', so there is no vocabulary to project its entries through and ` +
+        `'${failure.pointer || "this declaration"}' cannot be typed from it.`
+      );
+    case "no-entries":
+      return (
+        `'${failure.entries}' holds no entry collection on this ${failure.kind}, so the ` +
+        `projection has nothing to type '${failure.pointer || "this declaration"}' from.`
+      );
+    case "entry-reference":
+      return (
+        `entry '${failure.entry}' at '${failure.pointer}' references '${failure.name}', which ` +
+        `resolves to no declaration this analysis can read — so that entry is projected as an ` +
+        `open value and nothing typed from it is checked against the shape it was meant to have.`
+      );
   }
 }
 
@@ -360,6 +590,16 @@ export function describeProjectionFailure(failure: ProjectionFailure): string {
  * `failures`, because degrading SILENTLY is the failure this whole mechanism
  * exists to move earlier: the consumer's contract quietly reopens and a
  * misspelled field passes `telo check` exactly as it did before.
+ *
+ * **A node that projected NOTHING is returned by IDENTITY**, and that is a
+ * correctness property of the caller rather than a micro-optimization:
+ * `DefinitionRegistry` memoizes a compiled AJV validator per schema OBJECT,
+ * because every resource of a kind is checked against the same one at keystroke
+ * time. Rebuilding each node unconditionally — which this did — misses that memo
+ * for every resource in the analysis, so AJV recompiled the whole kind schema
+ * once per resource: on `apps/hub` that was 197 compiles instead of 54, and 723
+ * ms instead of 97. Returning the input where nothing changed restores it for
+ * every kind that declares no projection at all, which is nearly all of them.
  */
 export function resolveSchemaProjections(
   schema: unknown,
@@ -368,36 +608,59 @@ export function resolveSchemaProjections(
   failures?: ProjectionFailure[],
 ): unknown {
   if (Array.isArray(schema)) {
-    return schema.map((item) => resolveSchemaProjections(item, manifest, scope, failures));
+    let moved = false;
+    const items = schema.map((item) => {
+      const next = resolveSchemaProjections(item, manifest, scope, failures);
+      if (next !== item) moved = true;
+      return next;
+    });
+    return moved ? items : schema;
   }
   if (!isObject(schema)) return schema;
 
   const pointer = readProjectionFrom(schema);
-  if (pointer && manifest) {
-    const target = refTarget(navigate(manifest, pointer), scope, pointer);
+  if (pointer !== undefined && manifest) {
+    // The EMPTY pointer names the declaration this annotation is written on,
+    // rather than a slot holding a reference to another. Resolution is skipped
+    // because the declaration is already in hand — which is what lets a kind
+    // type its own data against its own entries (a table's seed rows against its
+    // columns), something no reference could reach.
+    const target =
+      pointer === ""
+        ? ownTarget(manifest, scope)
+        : refTarget(navigate(manifest, pointer), scope, pointer);
     if ("reason" in target) {
       failures?.push(target);
     } else {
+      const kind = String(target.manifest.kind ?? "<unknown>");
       const projection = readSchemaProjection(target.definition);
       const map = projection && projectionKeyMap(target.definition.schema, projection);
       const projected =
-        projection && map ? projectEntries(target.manifest, projection, map) : undefined;
+        projection && map
+          ? projectEntries(target.manifest, projection, map, { scope, pointer, failures })
+          : undefined;
       if (projected) {
         const { ["x-telo-schema-projection-from"]: _dropped, ...rest } = schema;
         return { ...rest, ...projected };
       }
-      failures?.push({
-        reason: "no-projection",
-        pointer,
-        kind: String(target.manifest.kind ?? "<unknown>"),
-      });
+      // Three distinct omissions, three repairs by three different authors: the
+      // kind declares no projection, the kind declares one the key field has no
+      // vocabulary for, or this DECLARATION simply lists no entries.
+      if (!projection) failures?.push({ reason: "no-projection", pointer, kind });
+      else if (!map) failures?.push({ reason: "no-projection-map", pointer, kind });
+      else {
+        failures?.push({ reason: "no-entries", pointer, kind, entries: projection.entries });
+      }
     }
   }
 
-  return Object.fromEntries(
-    Object.entries(schema).map(([key, value]) => [
-      key,
-      key.startsWith("x-telo-") ? value : resolveSchemaProjections(value, manifest, scope, failures),
-    ]),
-  );
+  let moved = false;
+  const entries = Object.entries(schema).map(([key, value]) => {
+    const next = key.startsWith("x-telo-")
+      ? value
+      : resolveSchemaProjections(value, manifest, scope, failures);
+    if (next !== value) moved = true;
+    return [key, next] as const;
+  });
+  return moved ? Object.fromEntries(entries) : schema;
 }

package/src/telo-version.ts

@@ -6,4 +6,4 @@
 // written against, and every kernel in every language reports the same scale.
 
 /** The surface generation this analyzer implements. */
-export const TELO_SURFACE_VERSION = "0.80.0";
+export const TELO_SURFACE_VERSION = "0.82.1";

package/src/validate-cel-context.ts

@@ -6,8 +6,13 @@ import {
   parseCanonicalTypeSchemaId,
 } from "@telorun/sdk";
 import { KERNEL_BUILTINS } from "./builtins.js";
-import { isStepSlot } from "./step-slot.js";
 import { withRefSlotsAsReadings } from "./ref-slot-reading.js";
+// Where CEL is evaluated is one reader (`eval-paths.ts`), and the region half of
+// it moved there so the scope walk and the `x-telo-eval` walk answer the same
+// question in one place. Re-exported: this module is where every existing
+// consumer imports them from.
+export { extractCelRegionScopes, pathMatchesScope } from "./eval-paths.js";
+import { pathMatchesScope } from "./eval-paths.js";
 
 export interface ContextResolveOpts {
   /** When provided, used to resolve `x-telo-context-from-root` annotations against the
@@ -282,35 +287,6 @@ function collectionBindingWithheld(
   return isLiveSlot(resolveCollectionSchema(manifestRoot, from, allManifests));
 }
 
-/**
- * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
- * falls within the scope of a context (e.g. "$.routes[*].inputs").
- *
- * The scope is matched directly (no sibling sharing): a context at "$.routes[*].inputs" only
- * applies to expressions whose path starts with "routes[N].inputs", not to other sibling fields.
- */
-export function pathMatchesScope(exprPath: string, scope: string): boolean {
-  const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
-  if (!stripped) return false;
-
-  // Split on wildcard array segments; each [*] must match a concrete [N] in exprPath
-  const parts = stripped.split("[*]");
-  let remaining = exprPath;
-  for (let i = 0; i < parts.length; i++) {
-    const part = parts[i]!;
-    if (!remaining.startsWith(part)) return false;
-    remaining = remaining.slice(part.length);
-    if (i < parts.length - 1) {
-      // Expect a concrete array index like [0], [12], ...
-      const m = remaining.match(/^\[\d+\]/);
-      if (!m) return false;
-      remaining = remaining.slice(m[0].length);
-    }
-  }
-  // Expression must end here or continue into a child path
-  return remaining === "" || remaining[0] === "." || remaining[0] === "[";
-}
-
 /**
  * Resolves `x-telo-context-*` annotations in a context schema using the concrete
  * manifest item (per-scope) and the manifest root.
@@ -579,47 +555,6 @@ export function extractContextsFromSchema(
   return all.sort((a, b) => b.scope.length - a.scope.length);
 }
 
-/** Schema keys that declare a CEL-bearing region: a field carrying any of these
- *  is evaluated at runtime, so a `!cel` inside it (or a descendant) is live. A
- *  STEP BODY is one too, and says so through the grammar its items point at
- *  rather than through a key — {@link isStepSlot} reads either spelling. */
-const CEL_REGION_KEYS = [
-  "x-telo-context",
-  "x-telo-step-context",
-  "x-telo-error-context",
-] as const;
-
-/**
- * Walk a JSON Schema tree and collect the JSONPath scopes of every field that
- * declares a CEL-bearing region (`x-telo-context` / `x-telo-step-context` /
- * `x-telo-error-context`). Used — alongside `x-telo-eval` paths — to decide
- * whether a `!cel` expression sits in a slot the runtime actually evaluates.
- * Scopes use the same `$.a.b[*]` form as `extractContextsFromSchema`, matched
- * against expression paths with `pathMatchesScope`.
- */
-export function extractCelRegionScopes(schema: Record<string, any>, path = "$"): string[] {
-  if (!schema || typeof schema !== "object") return [];
-  const out: string[] = [];
-
-  if (CEL_REGION_KEYS.some((k) => schema[k]) || isStepSlot(schema)) out.push(path);
-
-  if (schema.properties) {
-    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
-      out.push(...extractCelRegionScopes(value, `${path}.${key}`));
-    }
-  }
-  if (schema.items && typeof schema.items === "object") {
-    out.push(...extractCelRegionScopes(schema.items, `${path}[*]`));
-  }
-  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
-    if (Array.isArray(schema[key])) {
-      for (const subschema of schema[key]) out.push(...extractCelRegionScopes(subschema, path));
-    }
-  }
-
-  return out;
-}
-
 function collectContexts(
   schema: Record<string, any>,
   path: string,

package/src/validate-nested-inline.ts

@@ -1,11 +1,8 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { collectRefs, isInlineResource } from "./reference-field-map.js";
-import {
-  collectProperties,
-  resolveRef,
-  substituteCelFields,
-  validateAgainstSchema,
-} from "./schema-compat.js";
+import type { ExternalSchemaResolver } from "./schema-compat.js";
+import { collectProperties, resolveRef, substituteCelFields } from "./schema-compat.js";
+import type { SchemaIssue } from "./schema-error-report.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 import { collectValueSchemaIssues } from "./validate-value-schema.js";
 
@@ -16,6 +13,22 @@ export interface InlineDefinitionLookup {
   (kind: string): { schema?: Record<string, any> } | undefined;
 }
 
+/**
+ * The validator this pass checks an inline resource's config with, and the
+ * resolver that lets both it and the stand-in walk see through a named shape.
+ *
+ * Passed in rather than reached for: the module-level AJV this used has no
+ * registered shapes, so a kind whose `schema:` references one compiled nowhere
+ * and every inline declaration of it was silently unchecked — while the
+ * identical resource written standalone was checked, and the kernel rejected
+ * both at boot. Two validators answering one question is what allowed that, so
+ * the caller supplies the one that holds the shapes.
+ */
+export interface InlineConfigValidator {
+  validate(data: unknown, schema: Record<string, any>): SchemaIssue[];
+  external: ExternalSchemaResolver;
+}
+
 /**
  * Validates inline resources nested inside a resource body against their kind's
  * config schema. The per-resource walk in `analyze()` validates a resource's
@@ -41,7 +54,11 @@ export function validateNestedInlineResources(
   rootSchema: Record<string, any>,
   lookupDefinition: InlineDefinitionLookup,
   /** Needed to resolve a `telo#Type` field a value slot is validated against. */
-  allManifests: Record<string, any>[] = [],
+  allManifests: Record<string, any>[],
+  /** REQUIRED, and deliberately not defaulted: a default would be a second
+   *  validator answering the same question, and omitting it would silently stop
+   *  checking rather than fail. */
+  validator: InlineConfigValidator,
 ): AnalysisDiagnostic[] {
   const diagnostics: AnalysisDiagnostic[] = [];
   const resource = { kind: manifest.kind, name: manifest.metadata?.name as string };
@@ -89,14 +106,18 @@ export function validateNestedInlineResources(
         ? (inline.metadata as Record<string, unknown>)
         : {};
     const data = { ...inline, metadata: { name: "__inline__", ...existingMeta } };
-    const substituted = substituteCelFields(data, effectiveSchema, effectiveSchema);
-    // The same two passes the top-level resource loop runs, so a kind's
-    // guarantees don't depend on whether the author wrote it standalone or
-    // inline (under a step's `invoke:`, or in a `with:` scope). `data` carries
-    // the synthesized metadata; `x-telo-value-schema-from` reads sibling fields
-    // off the resource, which are present either way.
+    const substituted = substituteCelFields(data, effectiveSchema, effectiveSchema, {
+      external: validator.external,
+    });
+    // The same two passes the top-level resource loop runs, on the same
+    // validator, so a kind's guarantees don't depend on whether the author wrote
+    // it standalone or inline (under a step's `invoke:`, or in a `with:` scope)
+    // — and CLAUDE.md mandates inline for a single-use resource, so inline is
+    // the common shape rather than the exception. `data` carries the synthesized
+    // metadata; `x-telo-value-schema-from` reads sibling fields off the
+    // resource, which are present either way.
     const inlineIssues = [
-      ...validateAgainstSchema(substituted, effectiveSchema),
+      ...validator.validate(substituted, effectiveSchema),
       ...collectValueSchemaIssues(data, schema, allManifests),
     ];
     for (const issue of inlineIssues) {

package/src/validate-reference-forms.ts

@@ -3,6 +3,7 @@ import { isTaggedSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import { visitManifest } from "./manifest-visitor.js";
+import { satisfiesValueBranch } from "./reference-field-map.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
@@ -29,6 +30,16 @@ const SOURCE = "telo-analyzer";
  * Rejected, each with an actionable diagnostic pointing at `!ref`:
  *   - the object form `{ kind, name }` (the old reference object), and
  *   - a bare string (the old name / dotted-FQN reference).
+ *
+ * **A value-or-reference union slot is the one exception**, and it is decided by
+ * the value rather than by a new spelling: where the reference constraint is a
+ * *branch* of a union (`type:` on a column, holding either a storage class or a
+ * `!ref` to a declared enum), a SCALAR is a value and is left to that branch,
+ * while an object is still checked for the removed `{kind, name}` form unless a
+ * branch describes it. The rule guards a REMOVED spelling — a bare string is
+ * simply not a reference in Telo — so admitting one takes nothing away: what it
+ * costs is the answer when an author meant a reference and wrote a bare name,
+ * which against a closed branch AJV reports as an unknown value.
  */
 export function validateReferenceForms(
   resources: ResourceManifest[],
@@ -52,6 +63,17 @@ export function validateReferenceForms(
         // `!ref` and `!cel`/`${{ }}` sentinels are the supported shapes.
         if (isTaggedSentinel(value)) return;
 
+        // A SCALAR at a slot whose union has a value branch is a value, and the
+        // value branch is what judges it. Reporting a mistyped storage class as
+        // a malformed reference — "write it as '!ref txt'" — instructs the author
+        // to convert a typo into a reference, and AJV has already said what the
+        // value must be one of. The object form below is not ambiguous the same
+        // way: `{kind, name}` is the removed reference object, so it is still
+        // reported unless a branch genuinely describes that shape.
+        const hasValueBranch = (e.entry.valueBranches?.length ?? 0) > 0;
+        if (hasValueBranch && typeof value !== "object") return;
+        if (satisfiesValueBranch(value, e.entry.valueBranches, registry)) return;
+
         const r = e.source;
         const resourceLabel = `${r.kind}/${r.metadata!.name as string}`;
         const resourceData = { kind: r.kind, name: r.metadata!.name as string };