@telorun/analyzer 0.65.0 → 0.67.0

package/src/schema-projection.ts

@@ -35,6 +35,10 @@
  * derivation can reach.
  */
 
+import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
+import { isInjectedDeclaration } from "./resource-input.js";
+
 /** 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 +52,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 +102,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 +138,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 +218,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 +306,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 +323,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 +369,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 +475,51 @@ 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;
+    }
+  /** The slot names a resource the module does not DECLARE — a library's
+   *  `resources:` input, standing in for an instance its importer supplies. A
+   *  projection is DECLARATION-derived, so it cannot be answered here at all;
+   *  the stand-in has no entries, and reporting that would tell the library
+   *  author their block is wrong when it is correct. Resolution moves to the
+   *  injection site, where the real declaration is. Carried as its own reason
+   *  rather than as `no-entries` so a consumer can tell "unanswerable here"
+   *  from "answered, and empty". */
+  | { readonly reason: "injected"; readonly pointer: string; readonly name: 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,
@@ -325,18 +534,41 @@ function refTarget(
   if (!found) return { reason: "unresolved", pointer, name };
   if ("ambiguous" in found) return { reason: "ambiguous", pointer, name };
   const manifest = found.manifest;
+  if (isInjectedDeclaration(manifest as ResourceManifest)) {
+    return { reason: "injected", pointer, name };
+  }
   if (typeof manifest.kind !== "string") return { reason: "unresolved", pointer, name };
   const definition = scope.resolveDefinition(manifest.kind);
   if (!definition) return { reason: "no-projection", pointer, kind: manifest.kind };
   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 "injected":
+      return (
+        `'${failure.pointer}' references '${failure.name}', a resource input this module does ` +
+        `not declare — its entries belong to whoever supplies it.`
+      );
     case "ambiguous":
       return (
         `'${failure.pointer}' references '${failure.name}', which matches more than one resource ` +
@@ -347,6 +579,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 +609,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 +627,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/system-kinds.ts

@@ -28,8 +28,13 @@ export const DEPENDENCY_GRAPH_SKIP_KINDS: ReadonlySet<string> = new Set([
 /** Skipped by `!ref` sentinel resolution: kinds whose bodies are
  *  blueprints or import-time metadata, not resource instances with
  *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
- *  also drops Telo.Import (its `source` isn't a ref slot, and walking
- *  the field map on it is pointless since there's no registered kind). */
+ *  also lists Telo.Import, because walking its field map is pointless —
+ *  there is no registered kind behind it.
+ *
+ *  `resolveRefSentinels` reaches Telo.Import's `resources:` block AHEAD of this
+ *  set, deliberately: those are the references an importer supplies for a
+ *  library's declared inputs, and they resolve exactly like any other. Nothing
+ *  else on the document is a reference slot, so only that subtree is walked. */
 export const REF_RESOLUTION_SKIP_KINDS: ReadonlySet<string> = new Set([
   "Telo.Definition",
   "Telo.Abstract",

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.83.0";

package/src/template-body.ts

@@ -0,0 +1,104 @@
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import type { ModuleScopes } from "./alias-resolver.js";
+
+/**
+ * A `Telo.Definition`'s `resources:` entries — the bodies a kind writes for
+ * ANOTHER kind — read as what they are: declarations of that other kind.
+ *
+ * The consequence is the whole point. CEL inside such a body used to be typed in
+ * the ENCLOSING definition's scope, against one fixed permissive context
+ * (`self`, plus open `request` / `result` / `steps` / `error`). So `inputs` and
+ * `item` were undefined wherever the nested kind declares them, while `error`
+ * was offered everywhere regardless of whether a `catch:` was in scope — a body
+ * of more than one dispatch was unwritable, which is why no standard-library
+ * template has one.
+ *
+ * Resolving through the nested kind's OWN annotations — its `x-telo-context`
+ * regions, its step body, its error branches — makes a nested declaration answer
+ * exactly as the same declaration written at the top level does, with `self`
+ * merged in from the enclosing definition's `schema:`.
+ *
+ * Browser-safe.
+ */
+export interface TemplateBody {
+  /** Concrete path prefix of this entry (`resources[0]`), as CEL sites are
+   *  addressed. */
+  prefix: string;
+  /** JSONPath prefix for context scopes (`$.resources[0]`). */
+  scopePrefix: string;
+  manifest: ResourceManifest;
+  definition: ResourceDefinition | undefined;
+}
+
+/** The template bodies a manifest declares — empty for anything that is not a
+ *  `Telo.Definition` with a `resources:` array. */
+export function templateBodies(
+  m: ResourceManifest,
+  registry: DefinitionRegistry,
+  aliases: AliasResolver | undefined,
+  scopes: ModuleScopes | undefined,
+): TemplateBody[] {
+  if (m.kind !== "Telo.Definition") return [];
+  const bodies = (m as Record<string, unknown>).resources;
+  if (!Array.isArray(bodies)) return [];
+
+  // A nested kind is written through the alias scope of the module that DECLARED
+  // the definition, never the consumer's — the same rule every other kind
+  // resolution in a forwarded manifest follows.
+  const ownModule = (m.metadata as { module?: string } | undefined)?.module;
+  const scope =
+    (ownModule && scopes && !scopes.rootModules.has(ownModule)
+      ? scopes.aliasesByModule.get(ownModule)
+      : undefined) ?? aliases;
+
+  const out: TemplateBody[] = [];
+  for (let i = 0; i < bodies.length; i++) {
+    const body = bodies[i];
+    if (!body || typeof body !== "object" || Array.isArray(body)) continue;
+    const kind = (body as { kind?: unknown }).kind;
+    if (typeof kind !== "string") continue;
+    const canonical = scope?.resolveKind(kind);
+    const definition = registry.resolve(kind) ?? (canonical ? registry.resolve(canonical) : undefined);
+    out.push({
+      prefix: `resources[${i}]`,
+      scopePrefix: `$.resources[${i}]`,
+      manifest: body as ResourceManifest,
+      definition,
+    });
+  }
+  return out;
+}
+
+/** True when a CEL path lies at or inside a body's own subtree. */
+export function pathInBody(path: string, prefix: string): boolean {
+  return (
+    path === prefix || path.startsWith(`${prefix}.`) || path.startsWith(`${prefix}[`)
+  );
+}
+
+/** The body a CEL path belongs to, or undefined for a path in the definition's
+ *  own fields. Generic over what the caller keyed to each body — the resolver
+ *  carries a step context and an error map, the visitor carries the schema. */
+export function bodyForPath<T extends { prefix: string }>(
+  bodies: readonly T[],
+  path: string,
+): T | undefined {
+  return bodies.find((b) => pathInBody(path, b.prefix));
+}
+
+/** `self` is in scope throughout a template body — it is how the body reaches
+ *  the configuration its enclosing kind was given — so it is merged into every
+ *  context the nested kind declares, which knows nothing about it. Merged UNDER
+ *  the nested kind's own properties: a name the nested kind declares wins, since
+ *  that is what its controller will bind. */
+export function withTemplateSelf(contextSchema: Record<string, any>): Record<string, any> {
+  return {
+    ...contextSchema,
+    properties: {
+      self: { "x-telo-context-from-root": "schema" },
+      ...(contextSchema.properties ?? {}),
+    },
+  };
+}