@telorun/analyzer 0.65.0 → 0.66.0

package/src/reference-field-map.ts

@@ -19,6 +19,10 @@ export interface RefFieldEntry {
   inputs?: string;
   /** True when the field path traversed through at least one array (path contains "[]"). */
   isArray: boolean;
+  /** The slot's non-reference branches, when the reference constraint is a
+   *  branch of a union — see {@link RefSlot.valueBranches}. A value satisfying
+   *  one of these is a value, not a malformed reference. */
+  valueBranches?: Record<string, any>[];
   /** x-telo-context schema declared on this ref slot, if any. Describes the CEL invocation
    *  context available to resources placed in this slot. */
   context?: Record<string, any>;
@@ -62,6 +66,43 @@ export function isRefEntry(entry: FieldMapEntry): entry is RefFieldEntry {
   return "refs" in entry;
 }
 
+/** The half of a definition registry this question needs — structural, so the
+ *  field map keeps depending on nothing. */
+export interface ValueBranchValidator {
+  schemaCompileError(schema: Record<string, any>): string | undefined;
+  validateWithRefs(data: unknown, schema: Record<string, any>): string[];
+}
+
+/**
+ * True when a value at a ref slot satisfies one of the slot's VALUE branches —
+ * a storage class beside a `!ref`, so it is a value and not a malformed
+ * reference.
+ *
+ * One implementation, because BOTH reference passes have to narrow the same way:
+ * `validateReferenceForms` would otherwise call it a removed string reference,
+ * and `validateReferences` a reference missing `kind` and `name`. Two copies of
+ * the rule would eventually disagree about which of the two reported a value.
+ *
+ * A branch AJV cannot COMPILE is not a branch the value satisfies.
+ * `validateWithRefs` returns no issues for one — it swallows the compile failure
+ * by design, so one bad schema does not abort the pass — and reading that as
+ * "no issues, therefore a value" would switch the reference-form rule off for
+ * the slot silently. The uncompilable schema is reported on its own definition
+ * by `schemaCompileError`.
+ */
+export function satisfiesValueBranch(
+  value: unknown,
+  branches: readonly Record<string, any>[] | undefined,
+  registry: ValueBranchValidator,
+): boolean {
+  if (!branches?.length) return false;
+  return branches.some(
+    (branch) =>
+      registry.schemaCompileError(branch) === undefined &&
+      registry.validateWithRefs(value, branch).length === 0,
+  );
+}
+
 export function isScopeEntry(entry: FieldMapEntry): entry is ScopeFieldEntry {
   return "scope" in entry;
 }
@@ -234,6 +275,7 @@ function traverseNode(
     };
     if (slot.useCases) entry.useCases = slot.useCases;
     if (slot.inputs !== undefined) entry.inputs = slot.inputs;
+    if (slot.valueBranches.length > 0) entry.valueBranches = slot.valueBranches;
     if (node["x-telo-context"]) entry.context = node["x-telo-context"] as Record<string, any>;
     if (slot.inline) entry.inline = true;
     map.set(path, entry);

package/src/referrer-rule.ts

@@ -37,6 +37,23 @@ export interface ReferrerRule {
    * relation the rule is about, so a kind should write it.
    */
   readonly referrer?: string;
+  /**
+   * JSON Pointer to a collection OF THE REFERRER to resolve — the binding that
+   * lets a rule state a relation between SIBLING declarations, which neither a
+   * resource rule (one resource) nor a plain referrer rule (a pair joined by one
+   * reference) can reach.
+   *
+   * Declaring it binds `peers` (the collection's OTHER entries) and `entry` (my
+   * own), and makes the rule evaluate once per entry rather than once per
+   * referrer: a rule reading `entry` is about the entry, and a resource listed
+   * twice has two entries to answer for.
+   *
+   * Entries bind AS WRITTEN with the references *inside them* resolved one level
+   * — `p` is the declaration where the entry is a bare `!ref`, `p.mount` is the
+   * declaration with `p.prefix` beside it where it is not. Nothing is guessed
+   * from the item schema and there is no second pointer to write.
+   */
+  readonly peers?: string;
   /** CEL source. TRUE when the rule holds. */
   readonly condition: string;
   /** The rule's own name, carried in `data.rule`. Never a diagnostic code —
@@ -68,15 +85,17 @@ export function readReferrerRules(schema: unknown): ReferrerRule[] {
   raw.forEach((entry, index) => {
     if (!isObject(entry)) return;
     const condition = celSourceOf(entry.condition);
-    const { code, message, referrer } = entry;
+    const { code, message, referrer, peers } = entry;
     if (!condition || typeof code !== "string" || typeof message !== "string") return;
     if (code.length === 0 || message.length === 0) return;
     if (referrer !== undefined && typeof referrer !== "string") return;
+    if (peers !== undefined && typeof peers !== "string") return;
     if (entry.severity !== undefined && entry.severity !== "warning" && entry.severity !== "error") {
       return;
     }
     rules.push({
       ...(referrer === undefined ? {} : { referrer }),
+      ...(peers === undefined ? {} : { peers }),
       condition,
       code,
       message,

package/src/release/index.ts

@@ -2,7 +2,7 @@
  * The release model: module identity, fragments, the ledger, the edge graph,
  * level propagation and version planning.
  *
- * Browser-safe by construction — pure data in, plan out — so the telo editor can
+ * Browser-safe by construction — pure data in, plan out — so telo studio can
  * answer "what does changing this library bump?" from the same model the CLI
  * releases from. Everything Node-shaped (finding the workspace, running the
  * controller builder, building payloads, reading git, writing files) is

package/src/resource-rule.ts

@@ -21,6 +21,7 @@
  *
  * Browser-safe: no Node built-ins.
  */
+import { CEL_ENGINE, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 
 export const RESOURCE_RULES_ANNOTATION = "x-telo-resource-rules";
 
@@ -58,9 +59,42 @@ function isObject(value: unknown): value is Record<string, unknown> {
  *  Both markers are tested because they are not always both present: a
  *  registered definition's schema reaches the analyzer with `call` and
  *  `__compiled` dropped, keeping only `__tagged` + `source`. Testing one would
- *  make a rule readable on some paths and invisible on others. */
+ *  make a rule readable on some paths and invisible on others.
+ *
+ *  A tagged sentinel of ANOTHER engine is not one. `__tagged` marks every tag
+ *  the loader parses — `!ref` above all — so testing it alone read a reference
+ *  as an expression: a column whose `type:` holds a `!ref` skipped every rule
+ *  that touched `self.columns`, and said "the value holds a CEL expression" about
+ *  a manifest containing none. A reference names a declaration and is a
+ *  perfectly comparable value; what a rule cannot compare is a value COMPUTED at
+ *  create time, which is what this predicate exists to find. */
 function isCelNode(value: unknown): value is { source?: unknown } {
-  return isObject(value) && (value.__compiled === true || value.__tagged === true);
+  if (!isObject(value)) return false;
+  if (value.__compiled === true) return true;
+  return value.__tagged === true && value.engine === CEL_ENGINE;
+}
+
+/** The engine of a non-CEL tagged sentinel — a `!ref`, an `!include-*` — or
+ *  `undefined`. A reference is comparable and never blocks a rule; the other
+ *  tags hold a value only known once the resource is created, so they do, and
+ *  the diagnostic has to name the tag rather than claim CEL. */
+export function deferredTagOf(value: unknown): string | undefined {
+  if (!isTaggedSentinel(value) || isRefSentinel(value)) return undefined;
+  return value.engine === CEL_ENGINE ? undefined : value.engine;
+}
+
+/**
+ * True when a condition was written with the `!cel` tag.
+ *
+ * The readers stay lenient and take a bare string — a rule still runs either
+ * way. What an untagged condition loses is everything outside evaluation: to the
+ * editor's colouring, completion and hover it is a plain string, so a rule author
+ * writes CEL with no help and gets none of the checks a `!cel` scalar gets.
+ * Losing that silently is exactly what a strict half exists to move earlier, so
+ * the tag is reported by the strict halves and never enforced by the readers.
+ */
+export function isTaggedCondition(value: unknown): boolean {
+  return isCelNode(value);
 }
 
 /** A precompiled `!cel` node keeps its author-written text on `source`; a plain
@@ -179,17 +213,45 @@ export function resolveRuleSubjects(
   return undefined;
 }
 
+/** The first leaf a rule cannot compare, and what it is. `what` is a noun
+ *  phrase the diagnostic quotes verbatim, because "a CEL expression" printed
+ *  over an `!include-bytes` embed sends its author looking for an expression
+ *  that is not there. */
+export interface DynamicLeaf {
+  readonly path: string;
+  readonly what: string;
+}
+
+/** Classify ONE node, without descending. Exported because a caller that draws
+ *  its own bound on how far to look (`peer-binding`'s top-level-scalar scan)
+ *  must classify by the same rule as the recursive walk, or a `!ref` is a
+ *  reference to one of them and an expression to the other. */
+export function dynamicNode(value: unknown, path: string): DynamicLeaf | undefined {
+  const at = path || "(value)";
+  if (isCelNode(value)) return { path: at, what: "a CEL expression" };
+  const tag = deferredTagOf(value);
+  return tag ? { path: at, what: `an !${tag} embed` } : undefined;
+}
+
 /**
- * Path of the first CEL leaf inside a value, or `undefined` when every leaf is
- * literal. A rule reading an expression would be evaluating a placeholder, so
- * the subject is skipped — and the skip is reported, never silent.
+ * The first leaf inside a value whose contents are not known until the resource
+ * is created, or `undefined` when every leaf is literal. A rule reading one
+ * would be comparing against a placeholder, so the subject is skipped — and the
+ * skip is reported, never silent.
+ *
+ * A `!ref` is NOT one of them. It is a tagged sentinel like `!cel`, and testing
+ * `__tagged` alone read every reference as an expression: a column whose `type:`
+ * holds a `!ref` switched off every rule touching `self.columns` and reported a
+ * CEL expression in a manifest containing none. A reference names a declaration
+ * — a value a rule compares perfectly well, and the one peer rules are built on.
  *
  * Stops at nested inline `{ kind }` declarations for the reason every other walk
  * does: that CEL belongs to the nested kind, evaluated in its own scope.
  */
-export function findDynamicLeaf(value: unknown, base = ""): string | undefined {
+export function findDynamicLeaf(value: unknown, base = ""): DynamicLeaf | undefined {
   if (isObject(value)) {
-    if (isCelNode(value)) return base || "(value)";
+    const own = dynamicNode(value, base);
+    if (own) return own;
     if (typeof value.kind === "string" && base !== "") return undefined;
     for (const [key, child] of Object.entries(value)) {
       const found = findDynamicLeaf(child, base === "" ? key : `${base}.${key}`);

package/src/rule-condition.ts

@@ -32,6 +32,21 @@ import {
  */
 export const RULE_BUDGET_MS = 50;
 
+/**
+ * The one message for an untagged `condition:`, shared by every rule family so
+ * all of them say the same thing about the same defect.
+ *
+ * The readers stay lenient and a bare string still runs. What it loses is
+ * everything outside evaluation — to the editor's colouring, completion and
+ * hover an untagged condition is a plain string, so its author writes CEL with
+ * no help and none of the checks a `!cel` scalar gets. Losing that silently is
+ * the failure a strict half exists to move earlier.
+ */
+export const UNTAGGED_CONDITION =
+  "Write 'condition' with the !cel tag. The reader is lenient and a bare string still " +
+  "runs, but untagged the expression is not CEL to the editor's colouring, completion " +
+  "or hover, so a rule silently stops being CEL to every surface but this one.";
+
 const HOST_BACKED = new Set(CEL_FUNCTIONS.filter((f) => f.hostBacked).map((f) => f.name));
 const NON_DETERMINISTIC = new Set(
   CEL_FUNCTIONS.filter((f) => !f.deterministic).map((f) => f.name),

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.82.0";
+export const TELO_SURFACE_VERSION = "0.82.1";