@telorun/analyzer 0.62.0 → 0.63.0

package/src/manifest-schemas.ts

@@ -246,6 +246,39 @@ export const InvokeStepSchema = {
     retry: {
       title: "Retry",
       $ref: `${MANIFEST_SCHEMA_URI}#/$defs/RetryPolicy`,
+      // A sibling of the shared policy rather than a member of it, the way
+      // `Http.Request.retry` adds `honorRetryAfter` — fragment expansion merges
+      // siblings, so the policy stays closed and each consumer's surface stays
+      // honest. `nonRetryable` matches an ERROR CODE, which is what a step's
+      // failures carry; an HTTP retry classifies on a response STATUS and has
+      // `retryOn` for it, so putting this on the shared shape would advertise a
+      // field there that nothing could read.
+      properties: {
+        nonRetryable: {
+          title: "Non-retryable codes",
+          description:
+            "Error codes that end the loop immediately instead of consuming the budget. " +
+            "The built-in exclusions are the ones decidable without judgement — a " +
+            "cancellation, and the kernel's verdicts on the shape of the call; whether a " +
+            "DOMAIN failure is worth re-attempting only the author knows, and without " +
+            "this every terminal one is retried to exhaustion — for a non-idempotent " +
+            "target, N extra attempts at a side effect.",
+          type: "array",
+          items: { type: "string" },
+          default: [],
+        },
+      },
+    },
+    timeout: {
+      title: "Timeout",
+      description:
+        "How long ONE attempt may take, in milliseconds; on elapse the dispatch is " +
+        "cancelled and the step fails ERR_STEP_TIMEOUT. Per attempt rather than for " +
+        "the whole retry loop, so what a single call is allowed to take does not " +
+        "depend on how slow the earlier attempts were. It belongs to the step rather " +
+        "than the target because the target does not know who is waiting.",
+      type: "integer",
+      minimum: 1,
     },
   },
 };
@@ -306,12 +339,241 @@ export const KindSchemaSchema = {
   additionalProperties: true,
 };
 
+
+/** The `error` variable a `catch:` / `finally:` branch binds. One object, used
+ *  twice with different nullability — `finally` runs on the success path too. */
+const stepErrorProperties = {
+  code: {
+    description: "Structured error code; INTERNAL_ERROR for plain errors.",
+    type: "string",
+  },
+  message: { description: "Human-readable error message.", type: "string" },
+  step: { description: "Name of the step that threw.", type: "string" },
+  data: { description: "Structured payload from an InvokeError, else undefined." },
+};
+
+/** A step list's own items, written as the self-reference the localizer leaves
+ *  behind. A recursive fragment states its self-references ALREADY localized:
+ *  `hoistFragmentDef` copies the body verbatim into the consuming schema's
+ *  `$defs`, so a foreign `telo://manifest#/…` written here would survive into a
+ *  document the editor's local-only resolver throws on. */
+const stepList = (title: string, description: string) => ({
+  title,
+  description,
+  "x-telo-topology-role": "branch",
+  type: "array",
+  items: { $ref: `#/$defs/${hoistedDefKey("Step")}` },
+});
+
+/**
+ * One step of a step body: a dispatch, a computed value, or a control-flow block.
+ *
+ * THE GRAMMAR, owned here rather than by `modules/run`. It was declared four
+ * times in one file — `$defs` are local to the schema that declares them, so
+ * four kinds in one module could not share one, let alone four kinds in four
+ * modules — and that is why a kind wanting a body had to take a `!ref` to an
+ * executable instead. A fragment is what makes `Sql.Transaction` or a durable
+ * `Workflow` able to carry one directly.
+ *
+ * RECURSIVE (a branch holds steps), so a reference to it is localized and
+ * hoisted rather than expanded in place — see {@link localizeRecursiveFragment}.
+ *
+ * `while/do` is admitted in EVERY body. Three of the four copies dropped it
+ * ("the kind is itself the loop"), which is an editorial nudge rather than a
+ * soundness rule — a nested `while` inside a for-each body is ordinary control
+ * flow the same engine already runs — and a fragment cannot be narrowed by its
+ * consumer anyway: draft-07 makes `$ref` exclusive, so a sibling restating a
+ * subset would be silently ignored by AJV while still reaching completion. One
+ * grammar, or two fragments and the duplication back where it started.
+ */
+export const StepSchema = {
+  title: "Step",
+  description: "Single executable step or control-flow block.",
+  type: "object",
+  properties: {
+    name: { title: "Name", description: "Unique step name.", type: "string" },
+  },
+  oneOf: [
+    // THE dispatch site, shared with an Application's `targets:` rather than
+    // restated. `name` is hoisted to the enclosing step object above, which is
+    // why this branch carries only what a dispatch itself needs.
+    {
+      title: "invoke",
+      description: "Invokes an invocable or runnable resource.",
+      $ref: `${MANIFEST_SCHEMA_URI}#/$defs/InvokeStep`,
+    },
+    {
+      title: "if/then/else",
+      description: "Conditional branch; executes then or else based on a boolean expression.",
+      properties: {
+        if: {
+          title: "If",
+          description: "CEL boolean expression; true executes then, false executes else.",
+          "x-telo-topology-role": "predicate",
+          type: "boolean",
+        },
+        elseif: {
+          title: "Else If",
+          description: "Additional condition-branch pairs evaluated when if is false.",
+          "x-telo-topology-role": "branch-list",
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              if: {
+                title: "If",
+                description: "CEL boolean expression for this else-if branch.",
+                "x-telo-topology-role": "predicate",
+                type: "boolean",
+              },
+              then: stepList("Then", "Steps executed when this else-if condition is true."),
+            },
+            required: ["if", "then"],
+          },
+        },
+        then: stepList("Then", "Steps executed when if evaluates true."),
+        else: stepList(
+          "Else",
+          "Steps executed when if (and all elseif conditions) evaluate false.",
+        ),
+      },
+      required: ["if", "then"],
+    },
+    {
+      title: "while/do",
+      description: "Loop; executes do steps repeatedly while condition is true.",
+      properties: {
+        while: {
+          title: "While",
+          description: "CEL boolean expression; evaluated before each iteration.",
+          "x-telo-topology-role": "predicate",
+          type: "boolean",
+        },
+        do: stepList("Do", "Steps executed on each iteration."),
+      },
+      required: ["while", "do"],
+    },
+    {
+      title: "switch/cases/default",
+      description: "Multi-branch dispatch; matches a value expression against case keys.",
+      properties: {
+        switch: {
+          title: "Switch",
+          description: "CEL expression; result matched against case keys.",
+          "x-telo-topology-role": "discriminator",
+          type: "string",
+        },
+        cases: {
+          title: "Cases",
+          description: "Map of value to step list; executed when switch matches the key.",
+          "x-telo-topology-role": "case-map",
+          type: "object",
+          additionalProperties: {
+            type: "array",
+            items: { $ref: `#/$defs/${hoistedDefKey("Step")}` },
+          },
+        },
+        default: stepList("Default", "Steps executed when no case matches."),
+      },
+      required: ["switch", "cases"],
+    },
+    {
+      title: "try/catch/finally",
+      description:
+        "Error boundary; executes try steps and handles failure via catch and finally.",
+      properties: {
+        try: stepList("Try", "Steps executed; halts on first failure and jumps to catch."),
+        catch: {
+          ...stepList("Catch", "Steps executed when try fails; receives error context."),
+          "x-telo-error-context": {
+            type: "object",
+            description: "The caught failure (always present inside catch).",
+            properties: stepErrorProperties,
+            additionalProperties: false,
+          },
+        },
+        finally: {
+          ...stepList(
+            "Finally",
+            "Steps always executed after try/catch regardless of outcome.",
+          ),
+          // error is null on the success path and the caught failure when a
+          // try/catch failure propagates. Typed nullable so the analyzer flags
+          // unguarded field access (CEL_NULLABLE_ACCESS).
+          "x-telo-error-context": {
+            type: ["object", "null"],
+            description: "The caught failure, or null when try (and catch) succeeded.",
+            properties: stepErrorProperties,
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ["try"],
+    },
+    {
+      title: "throw",
+      description:
+        "Throws an InvokeError unconditionally. Works inside catch blocks via CEL " +
+        '(e.g. code set to `!cel "error.code"`).',
+      properties: {
+        throw: {
+          title: "Throw",
+          description: "InvokeError descriptor; code is required, message/data optional.",
+          type: "object",
+          properties: {
+            code: {
+              title: "Code",
+              description: "Structured error code; uppercase SNAKE_CASE by convention.",
+              type: "string",
+            },
+            message: {
+              title: "Message",
+              description: "Human-readable error message. Defaults to `code` when omitted.",
+              type: "string",
+            },
+            data: {
+              title: "Data",
+              description: "Optional structured payload attached to the error.",
+            },
+          },
+          required: ["code"],
+        },
+      },
+      required: ["throw"],
+    },
+    {
+      title: "value",
+      description:
+        "Computes a value and publishes it as `steps.<name>.result`, with no dispatch — " +
+        "no resource, no span, no topology node. For an intermediate derived from an " +
+        "earlier step: reshape a response, total some rows, build the next call's inputs.",
+      properties: {
+        value: {
+          title: "Value",
+          description:
+            "A CEL expression — or a structure (map / array) with `!cel` leaves — " +
+            "evaluated in the step scope: `inputs`, the results of the steps before it, " +
+            "and whatever the enclosing kind binds (`item` / `index` / `items`, " +
+            "`iteration` / `previous`).",
+        },
+      },
+      required: ["value"],
+    },
+  ],
+  required: ["name"],
+};
+
+/** The fragments that CONTAIN THEMSELVES — a schema's properties hold schemas, a
+ *  step's branches hold steps. A reference to one is localized and hoisted
+ *  rather than expanded in place ({@link localizeRecursiveFragment}), because
+ *  inlining cannot terminate. */
+const RECURSIVE_FRAGMENTS = new Set(["JsonSchema7", "KindSchema", "Step"]);
+
 /** The fragments that describe author-written JSON Schema, whichever vocabulary
- *  they admit. They are also exactly the RECURSIVE ones — a schema is the only
- *  shape in this set that contains itself — so a reference to one is localized
- *  and hoisted rather than expanded in place ({@link localizeRecursiveFragment});
- *  should a self-containing fragment that is not a schema ever land, the two
- *  ideas split and this set stays the one about schemas. */
+ *  they admit. Split from {@link RECURSIVE_FRAGMENTS} when `Step` landed: being
+ *  recursive is a fact about how a reference is RESOLVED, being a schema is a
+ *  fact about which vocabulary a slot admits, and `Step` is the first fragment
+ *  that is one without the other. */
 const SCHEMA_FRAGMENTS = new Set(["JsonSchema7", "KindSchema"]);
 
 /** True when a slot's `x-telo-fragment` stamp says it holds author-written JSON
@@ -362,6 +624,7 @@ export const ManifestRootSchema = {
     RetryPolicy: RetryPolicySchema,
     RetryAttempts: RetryAttemptsSchema,
     InvokeStep: InvokeStepSchema,
+    Step: StepSchema,
     JsonSchema7: JsonSchema7Schema,
     KindSchema: KindSchemaSchema,
   },
@@ -369,16 +632,62 @@ export const ManifestRootSchema = {
 
 deepFreeze(ManifestRootSchema);
 
+/**
+ * One expanded template per fragment, cloned per consumer.
+ *
+ * Expansion is a full walk of the body and the result is identical every time —
+ * `Step` alone is a couple of hundred nodes and `modules/run` hoists it four
+ * times, on the kernel's boot path. The copy handed out is still fresh, because
+ * downstream passes (`resolveSchemaRefKinds`, migrations) rewrite schemas in
+ * place.
+ */
+const expandedFragments = new Map<string, Record<string, unknown>>();
+
+/**
+ * A fresh, fully expanded copy of a fragment body.
+ *
+ * TARGET-INDEPENDENT, which is what makes caching it correct: the walk is given
+ * a scratch hoist target and REFUSED if anything lands in it. A localized copy
+ * belongs in the schema a validator compiles, never inside another `$defs`
+ * entry, so a body that needed one could not have a single cached form — the
+ * first consumer would receive the entry and every later one would silently get
+ * a pointer to nothing. Nothing exercises that today: a recursive fragment
+ * writes its own self-references already localized, and a cross-reference
+ * between two recursive fragments is hoisted at the top level by
+ * {@link hoistFragmentDef}'s `pending` loop. If one ever does, this throws at
+ * the write instead of resolving by accident.
+ */
+function expandedFragment(name: string): Record<string, unknown> {
+  let template = expandedFragments.get(name);
+  if (!template) {
+    const fragment = (ManifestRootSchema.$defs as Record<string, unknown>)[name];
+    template = structuredClone(fragment) as Record<string, unknown>;
+    const scratch: Record<string, unknown> = {};
+    walkFragments(template, new Set(), { hoistTarget: scratch, depth: 1 });
+    if (scratch.$defs !== undefined) {
+      throw new Error(
+        `Manifest fragment '${name}' references a recursive fragment from inside its body. ` +
+          `Its expanded form is no longer independent of where it is hoisted — localize the ` +
+          `reference in the fragment source (write '#/$defs/telo:<Name>' directly) or teach ` +
+          `expandedFragment to take the hoist target.`,
+      );
+    }
+    expandedFragments.set(name, template);
+  }
+  return structuredClone(template);
+}
+
 /** A private, expanded copy of a fragment, for a consumer that must EMBED one
  *  rather than `$ref` it — `builtins.ts` is not a manifest and never passes
  *  through the loader, so its dispatch site has to arrive already resolved and
  *  already stamped. Cloned for the reason {@link deepFreeze} explains. */
+
 export function manifestFragment(name: string): Record<string, unknown> {
   const fragment = (ManifestRootSchema.$defs as Record<string, unknown>)[name];
   if (!fragment || typeof fragment !== "object") {
     throw new Error(`Unknown manifest fragment '${name}'`);
   }
-  if (SCHEMA_FRAGMENTS.has(name)) {
+  if (RECURSIVE_FRAGMENTS.has(name)) {
     // A recursive fragment has no expanded form — that is the whole reason it is
     // localized instead. Embedding one would hand the consumer a body whose
     // `#/$defs` pointers resolve against nothing.
@@ -388,8 +697,7 @@ export function manifestFragment(name: string): Record<string, unknown> {
         `enclosing schema through withSchemaFragments().`,
     );
   }
-  const copy = structuredClone(fragment) as Record<string, unknown>;
-  expandManifestFragments(copy);
+  const copy = expandedFragment(name);
   copy[X_TELO_FRAGMENT] = name;
   return copy;
 }
@@ -500,7 +808,7 @@ function localizeRecursiveFragment(
   const ref = value.$ref;
   if (typeof ref !== "string" || !ref.startsWith(FRAGMENT_PREFIX)) return undefined;
   const name = ref.slice(FRAGMENT_PREFIX.length);
-  if (!SCHEMA_FRAGMENTS.has(name)) return undefined;
+  if (!RECURSIVE_FRAGMENTS.has(name)) return undefined;
 
   hoistFragmentDef(ctx.hoistTarget, name);
   return { ...value, $ref: `#/$defs/${hoistedDefKey(name)}`, [X_TELO_FRAGMENT]: name };
@@ -522,8 +830,15 @@ function hoistFragmentDef(target: Record<string, unknown>, name: string): void {
     // fragment reached through its own self-reference, with no slot in sight.
     // That node is exactly where an annotation like `x-telo-eval` is written,
     // so it is where the stamp has to be readable.
-    defs[key] = { ...(structuredClone(fragment) as object), [X_TELO_FRAGMENT]: next };
-    for (const nested of SCHEMA_FRAGMENTS) {
+    // A hoisted body may point at a NON-recursive fragment (`Step`'s dispatch
+    // branch is `InvokeStep`), and a copy left unexpanded carries a foreign
+    // `telo://manifest#/…` reference into a document the editor's resolver
+    // throws on — the same failure gating fragment expansion once caused. Where
+    // a nested LOCALIZED copy would belong is not this body; see
+    // {@link expandedFragment}, which refuses that case rather than guessing.
+    const body = expandedFragment(next);
+    defs[key] = { ...body, [X_TELO_FRAGMENT]: next };
+    for (const nested of RECURSIVE_FRAGMENTS) {
       if (nested !== next && referencesLocalDef(defs[key], nested)) pending.push(nested);
     }
   }
@@ -589,10 +904,9 @@ function fragmentFor(value: unknown): Record<string, unknown> | undefined {
   const fragment = (ManifestRootSchema.$defs as Record<string, unknown>)[name];
   if (!fragment || typeof fragment !== "object") return undefined;
 
-  const expanded = structuredClone(fragment) as Record<string, unknown>;
   // A fragment may reference another (InvokeStep holds a RetryPolicy); the copy
-  // is expanded too, so one pass leaves no reference behind.
-  expandManifestFragments(expanded);
+  // arrives expanded, so one pass leaves no reference behind.
+  const expanded = expandedFragment(name);
 
   for (const [key, own] of Object.entries(node)) {
     if (key === "$ref") continue;

package/src/module-compatibility.ts

@@ -0,0 +1,72 @@
+/**
+ * Can this runtime host that module version? One question, one answer, one
+ * implementation — the CLI's `upgrade` and every IDE's upgrade affordance all
+ * ask it of a candidate version's `telo.yaml` text.
+ *
+ * It lives beside {@link readRequires} because the `requires:` grammar has
+ * exactly one reader by rule, and the moment a second host learned to filter
+ * candidates by compatibility that rule needed a shared verdict, not a second
+ * parser. Browser-safe: text in, verdict out, no transport and no filesystem —
+ * fetching the candidate manifest is the caller's job, since only the caller
+ * knows which transport (or cache) addresses it.
+ */
+
+import { defaultCustomTags } from "@telorun/templating";
+import { parseAllDocuments } from "yaml";
+import { isModuleKind } from "./module-kinds.js";
+import { evaluateRequires, readRequires, type HostVersions } from "./requires-block.js";
+
+/**
+ * How a candidate version answered the compatibility question.
+ *
+ * `unknown` — the manifest could not be read or names no module document — is
+ * never treated as incompatible, since an unreachable registry must not
+ * silently freeze a consumer's imports.
+ *
+ * The two rejecting answers are kept APART because they call for different
+ * actions and the user is told which one applies: `too-new` is fixed by
+ * upgrading telo, `unreadable` cannot be fixed by the consumer at all.
+ * Collapsing them into one "no" and then printing "requires a newer telo" would
+ * assert a cause the check never established, and point at a runtime upgrade
+ * that will not help.
+ */
+export type ModuleCompatibility = "yes" | "too-new" | "unreadable" | "unknown";
+
+/**
+ * Read a module manifest's declared `requires:` and decide whether the runtime
+ * described by `teloVersion` / `host` can host it.
+ *
+ * A module that declares nothing is compatible — the bootstrap rule, permanent
+ * for everything published before the mechanism existed. A host that reports no
+ * version for an axis skips it rather than guessing, which is exactly the
+ * editor case: an IDE is not the machine that will run the manifest, so it
+ * speaks for the telo surface and for nothing else.
+ */
+export function manifestCompatibility(
+  manifestText: string,
+  teloVersion: string | undefined,
+  host: HostVersions = {},
+): ModuleCompatibility {
+  let doc: Record<string, unknown> | undefined;
+  try {
+    for (const parsed of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
+      const value = parsed.toJS() as Record<string, unknown> | null;
+      const kind = value?.kind;
+      if (typeof kind === "string" && isModuleKind(kind)) {
+        doc = value as Record<string, unknown>;
+        break;
+      }
+    }
+  } catch {
+    return "unknown";
+  }
+  if (!doc) return "unknown";
+
+  const { block, issues } = readRequires(doc);
+  // A malformed declaration is not a licence to install: the module claims a
+  // requirement it failed to state, and guessing which way it pointed is how a
+  // consumer ends up on a version that cannot load. The load gate warns about
+  // this same manifest, so the two halves agree.
+  if (issues.some((i) => !i.unknownAxis)) return "unreadable";
+  return evaluateRequires(block, teloVersion, host).satisfied ? "yes" : "too-new";
+}

package/src/ref-slot-reading.ts

@@ -0,0 +1,156 @@
+/**
+ * What a `self.<refSlot>` READS as.
+ *
+ * A ref slot holds the live instance after Phase-5 injection, and the kernel
+ * substitutes each one with its last published reading before evaluating a
+ * template body (`celSelfView`) — so `self.table.name` and `resources.users.name`
+ * name the same fact. This is the static half of that equivalence: without it a
+ * ref slot's schema is whatever the kind wrote at the slot (a title, a
+ * description and the annotation), which types nothing at all.
+ *
+ * A published reading has two halves and they are typed differently, exactly as
+ * `resources.<name>` is:
+ *
+ *  - the FLAT half is what `snapshot()` returned, which no manifest declares, so
+ *    it stays open. Closing it would reject reads that are correct today, and
+ *    there is nothing to close it against.
+ *  - `status` is DECLARED (`status:` on the kind, folded along `extends`), so it
+ *    is typed and a typo below it is `CEL_UNKNOWN_FIELD`.
+ *
+ * Deliberately no attempt to type the flat half from the kind's own `schema:`:
+ * a snapshot is what the controller chose to publish, not the config it was
+ * given, and the two coincide only by convention. Typing one as the other would
+ * invent errors on a kind that publishes anything else.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import { effectiveStatusSchema } from "./extends-resolution.js";
+import { isRefSlot, readRefSlot } from "./ref-slot.js";
+
+export interface RefReadingScope {
+  /** The definition a canonical kind names. */
+  resolve(kind: string): Record<string, any> | undefined;
+  /** Canonicalizes an alias-qualified kind, for a slot whose constraint has not
+   *  been rewritten yet. */
+  resolveKind?(kind: string): string | undefined;
+}
+
+function isObject(value: unknown): value is Record<string, any> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The reading schema for one ref slot, or undefined when the slot's constraint
+ * resolves to nothing — in which case the slot is left exactly as it was, the
+ * degrade-to-today direction every unresolved annotation takes here.
+ *
+ * A slot constrained to SEVERAL kinds types `status` from the kinds that agree
+ * and drops the rest: a read valid against one permitted target must not be
+ * rejected because a sibling kind does not declare that field.
+ */
+export function refSlotReadingSchema(
+  slot: Record<string, any>,
+  scope: RefReadingScope,
+): Record<string, any> | undefined {
+  const ref = readRefSlot(slot);
+  if (!ref || ref.kinds.length === 0) return undefined;
+
+  const statuses: Record<string, any>[] = [];
+  for (const kind of ref.kinds) {
+    const canonical = scope.resolveKind?.(kind) ?? kind;
+    const definition = scope.resolve(canonical) ?? scope.resolve(kind);
+    if (!definition) continue;
+    const status = effectiveStatusSchema(definition as any, (k) => scope.resolve(k) as any);
+    if (isObject(status) && isObject(status.properties)) statuses.push(status);
+  }
+  if (statuses.length === 0) return openReading(slot);
+
+  const shared = statuses.length === 1 ? statuses[0]!.properties : sharedProperties(statuses);
+  return {
+    ...describedBy(slot),
+    type: "object",
+    additionalProperties: true,
+    properties: {
+      status: { type: "object", additionalProperties: false, properties: shared },
+    },
+  };
+}
+
+/** Properties every candidate kind declares. A field only some of them report
+ *  is not one a read can rely on, and rejecting it would be wrong for the kinds
+ *  that do — so it degrades to the open half rather than to an error. */
+function sharedProperties(statuses: readonly Record<string, any>[]): Record<string, any> {
+  const [first, ...rest] = statuses;
+  const out: Record<string, any> = {};
+  for (const [name, schema] of Object.entries(first!.properties as Record<string, any>)) {
+    if (rest.every((other) => name in (other.properties as Record<string, any>))) {
+      out[name] = schema;
+    }
+  }
+  return out;
+}
+
+/** A reading whose `status` cannot be typed: open, so nothing new is rejected. */
+function openReading(slot: Record<string, any>): Record<string, any> {
+  return { ...describedBy(slot), type: "object", additionalProperties: true };
+}
+
+/** The slot's own prose, kept so hover and completion still say what it is. */
+function describedBy(slot: Record<string, any>): Record<string, any> {
+  const out: Record<string, any> = {};
+  if (typeof slot.title === "string") out.title = slot.title;
+  if (typeof slot.description === "string") out.description = slot.description;
+  return out;
+}
+
+/**
+ * Rewrite every ref slot in a kind's own `schema:` to what reading it yields, so
+ * the `self` CEL variable answers about published state rather than about the
+ * annotation node.
+ *
+ * A SCHEMA walk, so it recurses through `properties` / `items` /
+ * `additionalProperties` and nothing else — there is no inline-declaration
+ * boundary to stop at here, because a `kind` key inside a schema is a property
+ * NAMED kind, not a nested resource. Untouched subtrees keep their identity, so
+ * a schema declaring no ref slot is returned as it was.
+ */
+export function withRefSlotsAsReadings(
+  schema: unknown,
+  scope: RefReadingScope,
+): unknown {
+  if (Array.isArray(schema)) return schema.map((item) => withRefSlotsAsReadings(item, scope));
+  if (!isObject(schema)) return schema;
+
+  if (isRefSlot(schema)) return refSlotReadingSchema(schema, scope) ?? schema;
+
+  let changed = false;
+  const out: Record<string, any> = { ...schema };
+  for (const key of ["properties", "items", "additionalProperties"]) {
+    const node = schema[key];
+    if (node === undefined) continue;
+    const next =
+      key === "properties"
+        ? mapValues(node, (value) => withRefSlotsAsReadings(value, scope))
+        : withRefSlotsAsReadings(node, scope);
+    if (next !== node) {
+      out[key] = next;
+      changed = true;
+    }
+  }
+  return changed ? out : schema;
+}
+
+function mapValues(
+  node: unknown,
+  fn: (value: unknown) => unknown,
+): unknown {
+  if (!isObject(node)) return node;
+  let changed = false;
+  const out: Record<string, any> = {};
+  for (const [key, value] of Object.entries(node)) {
+    const next = fn(value);
+    if (next !== value) changed = true;
+    out[key] = next;
+  }
+  return changed ? out : node;
+}