@telorun/analyzer 0.52.0 → 0.54.0

package/src/dependency-graph.ts

@@ -1,9 +1,7 @@
 import type { ResourceManifest } from "@telorun/sdk";
-import { isRefSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
+import { buildCallGraph, projectToPairs, type ResourceGraphNode } from "./call-graph.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
-import { visitManifest } from "./manifest-visitor.js";
-import { DEPENDENCY_GRAPH_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
 export interface ResourceNode {
   kind: string;
@@ -22,16 +20,26 @@ export interface DependencyGraph {
 const nodeKey = (kind: string, name: string) => `${kind}\0${name}`;
 
 /**
- * Builds a directed acyclic graph (DAG) of runtime resource dependencies and
+ * Builds a directed acyclic graph (DAG) of boot-time resource dependencies and
  * returns either a topological initialization order or the cycle path.
  *
- * Edges represent boot-time dependencies only:
- * - x-telo-ref fields that fall within a scope visibility path are excluded
- *   (scoped resources are initialized on demand at runtime, not at boot).
- * - x-telo-scope fields themselves are excluded from the graph.
+ * A projection of the typed reference graph, not a second walk of the manifest.
+ * What this consumer keeps of the full graph:
  *
- * The registry is queried for each resource's field map by kind — callers do
- * not pre-compute or pass field maps separately.
+ * - **Injection sites only.** A site the reference field map reaches is a
+ *   Phase-5 injection site, so its target must be constructed first — including
+ *   `Telo.Application`'s inline `targets[].invoke`, which is step-declared but
+ *   injected. A step slot behind a local `$ref` and a value-tree-discovered ref
+ *   resolve at dispatch, so their targets need only exist by the time the step
+ *   runs. All can be `use: call` — the difference is the site, never the node
+ *   kind or the use.
+ * - **Every use but `schema`.** A `Telo.Type` slot names a shape; no runtime
+ *   instance is constructed, so there is nothing to order against.
+ * - **No edge into the source's own scope.** A scoped resource is created when
+ *   the scope opens, not at boot.
+ * - **Pairs, not parallel edges.** This is the one consumer for which two slots
+ *   naming the same target genuinely mean the same thing, so it collapses the
+ *   multigraph itself instead of the graph erasing the distinction for everyone.
  */
 export function buildDependencyGraph(
   resources: ResourceManifest[],
@@ -39,67 +47,25 @@ export function buildDependencyGraph(
   aliases?: AliasResolver,
   aliasesByModule?: Map<string, AliasResolver>,
 ): DependencyGraph {
-  // --- Build node set + name index ---
+  const graph = buildCallGraph(resources, registry, { aliases, aliasesByModule });
+
   const nodes = new Map<string, ResourceNode>();
-  // Sentinel lookup (`!ref <name>`) needs to resolve a bare name to its
-  // declared kind. Names are unique within a manifest scope, so a flat
-  // map suffices and lets the sentinel branch below avoid a full
-  // O(N) scan of the node set on every reference.
-  const nodesByName = new Map<string, ResourceNode>();
-  for (const r of resources) {
-    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
-    const node = { kind: r.kind, name: r.metadata.name as string };
-    nodes.set(nodeKey(node.kind, node.name), node);
-    nodesByName.set(node.name, node);
+  for (const node of graph.nodes.values()) {
+    if (node.type !== "resource") continue;
+    const resource = node as ResourceGraphNode;
+    // A scope-declared resource is created when its scope opens, never at boot.
+    if (resource.scoped) continue;
+    nodes.set(resource.id, { kind: resource.kind, name: resource.name });
   }
 
-  // --- Build adjacency: from → deps (from depends on dep) ---
-  const deps = new Map<string, Set<string>>();
-  for (const key of nodes.keys()) deps.set(key, new Set());
-
-  // Names of resources declared inside the *current* resource's scope fields —
-  // initialized on-demand at runtime, not at boot, so edges pointing to them
-  // are excluded. Scoping is per-source-resource: an edge A → B is dropped only
-  // when B is declared inside A's own scope (the visitor's ScopeBoundary fires
-  // before that resource's RefSites, so this is set before any edge is added).
-  let scopedNames = new Set<string>();
-
-  // Expanded map so refs nested behind x-telo-schema-from contribute edges to
-  // the DAG. Without these, a parent (e.g. Http.Server) can init before its
-  // extracted encoder and Phase 5 injection fires against a not-yet-created
-  // dependency.
-  visitManifest(
-    resources,
-    registry,
-    {
-      onScope: (e) => {
-        scopedNames = e.enclosedNames;
-      },
-      onRef: (e) => {
-        const sourceKey = nodeKey(e.source.kind, e.source.metadata!.name as string);
-        const val = e.value;
-
-        // `!ref <name>` sentinel — look up the target's kind from the name
-        // (resources are unique by name) so the edge carries the concrete kind,
-        // matching the {kind, name} edge shape below.
-        if (isRefSentinel(val)) {
-          const refName = val.source;
-          if (scopedNames.has(refName)) return;
-          const node = nodesByName.get(refName);
-          if (node) deps.get(sourceKey)!.add(nodeKey(node.kind, node.name));
-          return;
-        }
-
-        if (typeof val !== "object") return;
-        const ref = val as Record<string, unknown>;
-        if (!ref.kind || !ref.name) return;
-        if (scopedNames.has(ref.name as string)) return;
-        const targetKey = nodeKey(ref.kind as string, ref.name as string);
-        if (nodes.has(targetKey)) deps.get(sourceKey)!.add(targetKey);
-      },
-    },
-    { aliases, aliasesByModule, skipKinds: SYSTEM_KINDS, expand: true },
-  );
+  const deps = projectToPairs(graph, {
+    keepUse: (use) => use.length === 0 || use.some((u) => u !== "schema"),
+  });
+  for (const edge of graph.edges) {
+    if (!edge.scoped || !edge.to) continue;
+    deps.get(edge.from)?.delete(edge.to);
+  }
+  for (const key of nodes.keys()) if (!deps.has(key)) deps.set(key, new Set());
 
   // --- Kahn's topological sort ---
   // in-degree[X] = number of X's dependencies (size of deps[X])

package/src/flatten-for-analyzer.ts

@@ -2,6 +2,7 @@ import type { ResourceManifest } from "@telorun/sdk";
 import type { LoadedGraph, LoadedModule } from "./loaded-types.js";
 import type { LoadedFile } from "./loaded-types.js";
 import { isModuleKind } from "./module-kinds.js";
+import type { ZoneModuleDocuments } from "./zone-module-documents.js";
 
 /** One parsed `exports.resources` / `exports.kinds` entry. `name` is the exported
  *  instance name or kind suffix (the part after the dot, or the whole entry); `alias`
@@ -380,6 +381,37 @@ function forwardReExports(graph: LoadedGraph, result: ResourceManifest[]): void
   stampExportedKinds(imports, declaredKinds);
 }
 
+/** Collect every imported library's FULL document set for the zone stage's
+ *  per-library export derivation (`AnalysisOptions.moduleDocuments`) — the
+ *  flat list above deliberately drops library internals, and the zone
+ *  projection needs the internal dispatch chain to derive an export's open
+ *  requirements. Only libraries that actually export instances are included:
+ *  a library exporting nothing has no export contract to derive. */
+export function collectZoneModuleDocuments(graph: LoadedGraph): ZoneModuleDocuments[] {
+  const out: ZoneModuleDocuments[] = [];
+  for (const [source, mod] of graph.modules) {
+    if (source === graph.rootSource) continue;
+    const libDoc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind)) as
+      | (ResourceManifest & { exports?: { resources?: unknown[] } })
+      | undefined;
+    const moduleName = libDoc?.metadata?.name as string | undefined;
+    if (!libDoc || !moduleName) continue;
+    const exportedNames: string[] = [];
+    for (const entry of libDoc.exports?.resources ?? []) {
+      if (typeof entry !== "string") continue;
+      exportedNames.push(parseExportEntry(entry).name);
+    }
+    if (exportedNames.length === 0) continue;
+    out.push({
+      module: moduleName,
+      sourceId: mod.owner.source,
+      manifests: collectModuleManifests(mod),
+      exportedNames,
+    });
+  }
+  return out;
+}
+
 /** Project a LoadedModule (owner + partials) to a flat ResourceManifest[]
  *  with `metadata.module` stamped on non-module docs. The kernel's runtime
  *  entry load uses this to convert a `Loader.loadModule` result into the

package/src/index.ts

@@ -11,6 +11,7 @@ export type {
     ParseError,
 } from "./loaded-types.js";
 export {
+    collectZoneModuleDocuments,
     flattenForAnalyzer,
     flattenLoadedModule,
     forwardReExportManifests,
@@ -73,8 +74,54 @@ export {
   RedactionPathError,
 } from "./redaction-path.js";
 export type { RedactionSegment } from "./redaction-path.js";
+export { buildCallGraph, projectToPairs, resourceId } from "./call-graph.js";
+export type {
+  BuildCallGraphOptions,
+  CallGraph,
+  CallGraphEdge,
+  CallGraphNode,
+  ResourceGraphNode,
+  StepGraphNode,
+} from "./call-graph.js";
 export { buildReferenceFieldMap, isRefEntry, isScopeEntry } from "./reference-field-map.js";
 export type { ReferenceFieldMap, RefFieldEntry } from "./reference-field-map.js";
+export {
+  hasDeclaredUse,
+  isRefSlot,
+  isRefUse,
+  possibleUses,
+  readRefSlot,
+  REF_USES,
+  refSlotAnnotation,
+  rewriteRefSlotKinds,
+  transfersControl,
+} from "./ref-slot.js";
+export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
+export {
+  hasProvidesZone,
+  hasRequiresZone,
+  readProvidesZone,
+  readRequiresZone,
+  rewriteRequiresZoneKind,
+} from "./zone-slot.js";
+export type { ProvidesZoneSlot, RequiresZoneSlot } from "./zone-slot.js";
+export {
+  deriveLibraryExportRequirements,
+  projectZoneRequirements,
+  runZoneAnalysis,
+  zoneDocumentsSignature,
+} from "./resolve-zone-requirements.js";
+export type {
+  ZoneExportCache,
+  ZoneExportCacheEntry,
+  ZoneExportRequirements,
+  ZoneRequirementSpec,
+} from "./resolve-zone-requirements.js";
+export type { ZoneModuleDocuments } from "./zone-module-documents.js";
+export { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
+export type { ZoneSlotIssue } from "./validate-zone-slots.js";
+export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validate-ref-slots.js";
+export type { RefSlotIssue } from "./validate-ref-slots.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type {
     CelSiteEvent,
@@ -167,6 +214,10 @@ export {
 } from "./artifact-layer-index.js";
 export type { ArtifactLayer } from "./artifact-layer-index.js";
 export { validateModuleArtifact } from "./validate-module-artifact.js";
+// Warnings everywhere, fatal at `telo publish` — descriptive metadata has no
+// runtime failure mode, so it must not stop a manifest running, but it is the
+// module's public face the moment it is published.
+export { PUBLISH_BLOCKING_CODES } from "./validate-module-metadata.js";
 export { withSyntheticPositions } from "./with-synthetic-positions.js";
 export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";

package/src/manifest-navigation.ts

@@ -0,0 +1,91 @@
+/**
+ * Navigating a manifest value and a definition schema by path — the primitives
+ * the call graph and the zone projection both need.
+ *
+ * They live here rather than in either consumer because they encode *rules*,
+ * not conveniences: which object a JSON Pointer anchors at, and when a path
+ * refuses to resolve. Two copies of a rule drift, and the drift is invisible —
+ * a second `enclosingOf` that returned the resource root where the first
+ * returned `undefined` would silently anchor a correlation pointer at the wrong
+ * object rather than failing.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+
+/**
+ * The object ENCLOSING a concrete site — its path with the last segment
+ * dropped. `routes[2].handler` → the value at `routes[2]`.
+ *
+ * A slot that IS an array element (`targets[0]`) has no enclosing object: its
+ * siblings are other elements, and a pointer must not cross an array boundary —
+ * returning the root here would silently do exactly that. The bracket test runs
+ * BEFORE the no-dot early return, so a top-level array path refuses too.
+ */
+export function enclosingOf(root: unknown, concretePath: string): unknown {
+  const lastDot = concretePath.lastIndexOf(".");
+  const lastSegment = concretePath.slice(lastDot + 1);
+  if (lastSegment.includes("[")) return undefined;
+  if (lastDot < 0) return root;
+  return navigateConcrete(root, concretePath.slice(0, lastDot));
+}
+
+/** Navigate a concrete dotted path (`routes[2].handler`, `content.a/b.encoder`). */
+export function navigateConcrete(root: unknown, path: string): unknown {
+  let current: unknown = root;
+  for (const rawSegment of path.split(".")) {
+    if (current == null || typeof current !== "object") return undefined;
+    let segment = rawSegment;
+    const indices: number[] = [];
+    const bracket = segment.indexOf("[");
+    if (bracket >= 0) {
+      for (const m of segment.slice(bracket).matchAll(/\[(\d+)\]/g)) {
+        indices.push(Number(m[1]));
+      }
+      segment = segment.slice(0, bracket);
+    }
+    if (segment) current = (current as Record<string, unknown>)[segment];
+    for (const index of indices) {
+      if (!Array.isArray(current)) return undefined;
+      current = current[index];
+    }
+  }
+  return current;
+}
+
+/** Resolve a local `#/$defs/<name>` ref against the root schema; any other
+ *  schema (including one with no `$ref`) is returned unchanged. */
+export function resolveLocalRef(
+  schema: Record<string, any> | undefined,
+  root: Record<string, any>,
+): Record<string, any> | undefined {
+  if (!schema) return undefined;
+  const ref = schema.$ref;
+  if (typeof ref === "string" && ref.startsWith("#/$defs/")) {
+    const resolved = root.$defs?.[ref.slice("#/$defs/".length)];
+    if (resolved && typeof resolved === "object") return resolved as Record<string, any>;
+  }
+  return schema;
+}
+
+/** Property schemas of a possibly variant-bearing object schema — `properties`
+ *  plus every `oneOf` / `anyOf` / `allOf` branch's. */
+export function propertySchemas(
+  schema: Record<string, any>,
+): Array<[string, Record<string, any>]> {
+  const out: Array<[string, Record<string, any>]> = [];
+  if (schema.properties && typeof schema.properties === "object") {
+    for (const [k, v] of Object.entries(schema.properties)) out.push([k, v as Record<string, any>]);
+  }
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    const variants = schema[key];
+    if (!Array.isArray(variants)) continue;
+    for (const variant of variants) {
+      if (variant?.properties && typeof variant.properties === "object") {
+        for (const [k, v] of Object.entries(variant.properties)) {
+          out.push([k, v as Record<string, any>]);
+        }
+      }
+    }
+  }
+  return out;
+}

package/src/manifest-visitor.ts

@@ -146,7 +146,7 @@ export interface VisitOptions {
 
 /** Synthetic entry for a value-tree-discovered ref — these carry no declared
  *  x-telo-ref constraint. */
-const NESTED_REF_ENTRY: RefFieldEntry = { refs: [], isArray: false };
+const NESTED_REF_ENTRY: RefFieldEntry = { refs: [], uses: [], isArray: false };
 
 /** Scans a value tree for ref-shaped values, emitting each with its concrete
  *  path. Recognizes `!ref <name>` sentinels and named `{kind, name}` reference

package/src/ref-slot.ts

@@ -0,0 +1,273 @@
+/**
+ * The single reader of the `x-telo-ref` annotation.
+ *
+ * A reference slot is *recognised* here and nowhere else. Four surfaces ask what
+ * a slot accepts — the analyzer's reference checks, the kernel's Phase-5
+ * injection, the GUI editor's reference picker, and `ide-support`'s completions
+ * / hover / go-to-definition — and before this module each recognised the
+ * annotation by pattern-matching its shape (`typeof node["x-telo-ref"] ===
+ * "string"`, plus a hand-rolled `anyOf` peel in three of them, and no peel at all
+ * in hover). That is why the shape could not change without silently turning
+ * every ref slot in the GUI into a free-text field.
+ *
+ * Browser-safe by construction: no Node built-ins, so the editor and
+ * `ide-support` import it directly and the kernel re-imports it rather than
+ * carrying a second reader — the split already used for the invocation-contract
+ * resolver, the eval-path matcher and the redaction path parser.
+ *
+ * Two annotation shapes are accepted during the migration:
+ *
+ *   x-telo-ref: Telo.Invocable                  # bare string, no declared use
+ *   x-telo-ref:                                 # structured
+ *     kind: [Telo.Invocable, Telo.Runnable]
+ *     use: call
+ *     inputs: /inputs
+ */
+
+/** How control reaches a slot's target, relative to the declaring resource's own
+ *  invocation. The one primitive fact every consumer derives its own semantics
+ *  from — see `plans/typed-reference-graph.md`. */
+export type RefUse =
+  /** Names a shape; no runtime instance exists. No edge of any kind. */
+  | "schema"
+  /** Held and read; control never transfers. Init-order edge only. */
+  | "dependency"
+  /** Control transfers during my invocation and returns to me. */
+  | "call"
+  /** Control transfers during my invocation through the kernel's detach
+   *  primitive; I do not await it. */
+  | "detached"
+  /** I register the target; control reaches it after my invocation, driven by a
+   *  request or a timer, and the runtime guarantees a fresh ambient context. */
+  | "trigger.inbound"
+  /** I register the target; control reaches it when someone drains a value I
+   *  returned, so no guarantee holds either way. */
+  | "trigger.consumer";
+
+export const REF_USES: readonly RefUse[] = [
+  "schema",
+  "dependency",
+  "call",
+  "detached",
+  "trigger.inbound",
+  "trigger.consumer",
+];
+
+export function isRefUse(value: unknown): value is RefUse {
+  return typeof value === "string" && (REF_USES as readonly string[]).includes(value);
+}
+
+/** True for a use that transfers control to the target at some point. Everything
+ *  but `schema` and `dependency`. */
+export function transfersControl(use: RefUse): boolean {
+  return use !== "schema" && use !== "dependency";
+}
+
+/** A slot whose use is selected by a sibling config field. The selector must be
+ *  statically resolvable — a literal or a schema default — because a call graph
+ *  known only at runtime is not statically analyzable. */
+export interface RefUseCases {
+  /** JSON Pointer relative to the object ENCLOSING the annotated slot: the
+   *  resource root for a resource-level slot, the array item for a slot inside
+   *  one. No pointer can reach across an array boundary. */
+  by: string;
+  /** Selector value (stringified as written in YAML) → the uses that hold. */
+  cases: Record<string, RefUse[]>;
+}
+
+/** A reference slot's declaration, normalized from every accepted shape. */
+export interface RefSlot {
+  /** Accepted kinds, unioned across a `kind:` list and across `anyOf` branches.
+   *  Canonical `<module>.<Kind>` keys once `resolveSchemaRefKinds` has run;
+   *  alias-qualified as authored before that, or the legacy `<ns>/<mod>#<Kind>`
+   *  identity form for an already-published module. */
+  kinds: string[];
+  /** The relations the declaring resource has with the target. A set, because a
+   *  slot may dispatch its target more than one way within a single invocation
+   *  (`Cache.View` calls inline on a miss and detached on a background
+   *  revalidation). Empty when the slot declares no use — the bare-string form,
+   *  or a slot that defers to {@link RefSlot.useCases}. */
+  uses: RefUse[];
+  /** Present when the use is chosen by configuration rather than fixed. */
+  useCases?: RefUseCases;
+  /** JSON Pointer (same anchoring as {@link RefUseCases.by}) naming the field
+   *  that carries this call's arguments. Replaces
+   *  `x-telo-topology-role: inputs`. */
+  inputs?: string;
+  /** `x-telo-inline: true` on the slot or any `anyOf` branch — accepts an inline
+   *  `{kind, ...config}` definition, not only a `!ref`. */
+  inline: boolean;
+}
+
+/** Every use a slot can take, flattening a case map. The conservative reading
+ *  for a consumer that does not resolve the selector. */
+export function possibleUses(slot: RefSlot): RefUse[] {
+  if (!slot.useCases) return slot.uses;
+  const out = new Set<RefUse>(slot.uses);
+  for (const uses of Object.values(slot.useCases.cases)) {
+    for (const use of uses) out.add(use);
+  }
+  return [...out];
+}
+
+/** True when the slot states what the declaring resource does with the target.
+ *  False only for the legacy bare-string form. */
+export function hasDeclaredUse(slot: RefSlot): boolean {
+  return slot.uses.length > 0 || slot.useCases !== undefined;
+}
+
+function normalizeUses(raw: unknown): RefUse[] {
+  if (isRefUse(raw)) return [raw];
+  if (Array.isArray(raw)) return raw.filter(isRefUse);
+  return [];
+}
+
+function readUseCases(raw: unknown): RefUseCases | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.by !== "string") return undefined;
+  const rawCases = obj.cases;
+  if (!rawCases || typeof rawCases !== "object" || Array.isArray(rawCases)) return undefined;
+  const cases: Record<string, RefUse[]> = {};
+  for (const [key, value] of Object.entries(rawCases as Record<string, unknown>)) {
+    cases[key] = normalizeUses(value);
+  }
+  return { by: obj.by, cases };
+}
+
+/** Kind names declared by one annotation value, in either shape. */
+function readKinds(annotation: unknown): string[] {
+  if (typeof annotation === "string") return annotation ? [annotation] : [];
+  if (!annotation || typeof annotation !== "object" || Array.isArray(annotation)) return [];
+  const kind = (annotation as Record<string, unknown>).kind;
+  if (typeof kind === "string") return kind ? [kind] : [];
+  if (Array.isArray(kind)) return kind.filter((k): k is string => typeof k === "string" && !!k);
+  return [];
+}
+
+/** The nodes carrying an `x-telo-ref` for this slot: the node itself plus any
+ *  `anyOf` / `oneOf` branch. The multi-kind shape the `kind:` list replaces.
+ *
+ *  `oneOf` is peeled because the editor's picker always did and the analyzer
+ *  never did — unifying on the wider reading is the point of a single accessor.
+ *  The no-op claim is scoped to THIS repo: no schema here puts an `x-telo-ref`
+ *  under `oneOf`, so for the standard library this cannot add a field-map entry
+ *  (and hence a Phase-5 injection site) that did not exist before. An
+ *  already-published third-party module that does use that spelling gains an
+ *  injection site on upgrade — behavior its author most plausibly intended (the
+ *  editor already treated the slot as a reference), but a change of behavior
+ *  nonetheless, and part of this release's contract. */
+function annotationNodes(node: Record<string, any> | undefined): Record<string, any>[] {
+  if (!node || typeof node !== "object") return [];
+  const out: Record<string, any>[] = [];
+  if (node["x-telo-ref"] !== undefined) out.push(node);
+  for (const key of ["anyOf", "oneOf"] as const) {
+    const branches = node[key];
+    if (!Array.isArray(branches)) continue;
+    for (const branch of branches) {
+      if (branch && typeof branch === "object" && branch["x-telo-ref"] !== undefined) {
+        out.push(branch);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Reads a schema node as a reference slot, or `undefined` when it declares none.
+ *
+ * Unions the accepted kinds across the `kind:` list and across `anyOf` branches,
+ * which is the model the analyzer has always had internally — `RefFieldEntry`
+ * has carried a flat `refs: string[]` since before the structured form existed.
+ * A `use` declared on more than one branch is taken once; a *disagreement*
+ * between branches is left visible in the returned set rather than silently
+ * resolved here, so `validate-ref-slots.ts` reports it against the authored
+ * node (`X_TELO_REF_USE_CONFLICT`) — the same split that keeps this reader
+ * lenient about unrecognized `use` tokens while that pass rejects them.
+ */
+export function readRefSlot(node: Record<string, any> | undefined): RefSlot | undefined {
+  const nodes = annotationNodes(node);
+  if (nodes.length === 0) return undefined;
+
+  const kinds: string[] = [];
+  const uses = new Set<RefUse>();
+  let useCases: RefUseCases | undefined;
+  let inputs: string | undefined;
+
+  for (const carrier of nodes) {
+    const annotation = carrier["x-telo-ref"];
+    for (const kind of readKinds(annotation)) {
+      if (!kinds.includes(kind)) kinds.push(kind);
+    }
+    if (!annotation || typeof annotation !== "object" || Array.isArray(annotation)) continue;
+    const obj = annotation as Record<string, unknown>;
+    for (const use of normalizeUses(obj.use)) uses.add(use);
+    useCases ??= readUseCases(obj.use);
+    if (typeof obj.inputs === "string") inputs ??= obj.inputs;
+  }
+
+  const slot: RefSlot = {
+    kinds,
+    uses: [...uses],
+    inline: node?.["x-telo-inline"] === true || nodes.some((n) => n["x-telo-inline"] === true),
+  };
+  if (useCases) slot.useCases = useCases;
+  if (inputs !== undefined) slot.inputs = inputs;
+  return slot;
+}
+
+/** True when the node declares a reference slot in any accepted shape. The
+ *  recognition test every surface used to spell for itself. */
+export function isRefSlot(node: Record<string, any> | undefined): boolean {
+  return annotationNodes(node).length > 0;
+}
+
+/**
+ * Re-emits a slot as a canonical structured annotation value.
+ *
+ * For a consumer that has to *synthesize* a schema node and keep its reference
+ * slot intact — `ide-support` merges `anyOf` branches into one node for
+ * completion, and the merged node would otherwise carry no constraint at all,
+ * because the branches that held it are gone.
+ */
+export function refSlotAnnotation(slot: RefSlot): Record<string, unknown> {
+  const annotation: Record<string, unknown> = {
+    kind: slot.kinds.length === 1 ? slot.kinds[0] : slot.kinds,
+  };
+  if (slot.useCases) annotation.use = slot.useCases;
+  else if (slot.uses.length === 1) annotation.use = slot.uses[0];
+  else if (slot.uses.length > 1) annotation.use = slot.uses;
+  if (slot.inputs !== undefined) annotation.inputs = slot.inputs;
+  return annotation;
+}
+
+/**
+ * Rewrites every kind name an annotation declares, in place, in whichever shape
+ * it is written. `map` returns the replacement, or `undefined` to leave the name
+ * untouched (which is what keeps `resolveSchemaRefKinds` idempotent and lets it
+ * report an unresolvable constraint while quoting what the author wrote).
+ *
+ * Lives here rather than in the caller so that adding an annotation shape is a
+ * one-file change on the write side as well as the read side.
+ */
+export function rewriteRefSlotKinds(
+  annotationHolder: Record<string, any>,
+  map: (kind: string) => string | undefined,
+): void {
+  const annotation = annotationHolder["x-telo-ref"];
+  if (typeof annotation === "string") {
+    const next = map(annotation);
+    if (next !== undefined) annotationHolder["x-telo-ref"] = next;
+    return;
+  }
+  if (!annotation || typeof annotation !== "object" || Array.isArray(annotation)) return;
+  const obj = annotation as Record<string, unknown>;
+  if (typeof obj.kind === "string") {
+    const next = map(obj.kind);
+    if (next !== undefined) obj.kind = next;
+    return;
+  }
+  if (Array.isArray(obj.kind)) {
+    obj.kind = obj.kind.map((k) => (typeof k === "string" ? (map(k) ?? k) : k));
+  }
+}