@telorun/analyzer 0.52.0 → 0.54.0

package/src/validate-ref-slots.ts

@@ -0,0 +1,293 @@
+/**
+ * Static validation of the `x-telo-ref` annotation itself — the strict half of
+ * the accessor split. `readRefSlot` is deliberately lenient (it normalizes
+ * whatever it can read, because every surface must keep working mid-migration);
+ * this pass reads the RAW annotation and reports what leniency would otherwise
+ * silently absorb:
+ *
+ *  - an unrecognized `use` token — a typo like `use: cal` would degrade to the
+ *    legacy no-use reading, indistinguishable from a slot that never answered;
+ *  - a structured annotation with no `kind` — the editor would recognise the
+ *    slot but have nothing to pick against;
+ *  - a structured annotation with no `use` — the structured form is the
+ *    declaration that answers the question; omitting it is only legal in the
+ *    legacy bare-string spelling;
+ *  - `anyOf` branches whose declared uses disagree — a state with no meaning,
+ *    since `use` is a property of the slot, never of a branch;
+ *  - a `use` case map whose selector is written in CEL — a call graph known
+ *    only at runtime is not statically analyzable, which is the property the
+ *    typed reference graph exists to protect. There is deliberately no
+ *    fallback: no single value is conservative for every consumer.
+ *
+ * Scoping follows `X_TELO_REF_UNRESOLVED`: schema issues are reported only for
+ * definitions in the entry's own modules, and the dynamic-selector issue only
+ * for manifests in them — a published dependency's slot is not the consumer's
+ * to fix.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import { buildCallGraph, type CallGraph } from "./call-graph.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { isRefUse, REF_USES, type RefUse } from "./ref-slot.js";
+
+export interface RefSlotIssue {
+  code:
+    | "X_TELO_REF_INVALID_USE"
+    | "X_TELO_REF_MISSING_USE"
+    | "X_TELO_REF_MISSING_KIND"
+    | "X_TELO_REF_USE_CONFLICT"
+    | "X_TELO_REF_DYNAMIC_SELECTOR";
+  /** The definition (schema issues) or resource (selector issues) at fault. */
+  manifest: ResourceManifest;
+  /** Schema path of the slot (schema issues) or concrete value path of the
+   *  selector's site (dynamic-selector issues). */
+  path: string;
+  message: string;
+}
+
+const VALID_USES = REF_USES.join(", ");
+
+/** Raw `use` tokens carried by one annotation value: scalar, list, and every
+ *  case of a case map. Returned unfiltered so a typo is visible. */
+function rawUseTokens(use: unknown): unknown[] {
+  if (use === undefined) return [];
+  if (Array.isArray(use)) return use;
+  if (use && typeof use === "object") {
+    const cases = (use as Record<string, unknown>).cases;
+    if (!cases || typeof cases !== "object") return [];
+    return Object.values(cases as Record<string, unknown>).flatMap((v) =>
+      Array.isArray(v) ? v : [v],
+    );
+  }
+  return [use];
+}
+
+/** The declared fixed uses of one annotation (scalar/list form only), for the
+ *  branch-disagreement check. */
+function declaredUses(use: unknown): RefUse[] {
+  if (isRefUse(use)) return [use];
+  if (Array.isArray(use)) return use.filter(isRefUse);
+  return [];
+}
+
+function checkAnnotation(
+  annotation: unknown,
+  manifest: ResourceManifest,
+  path: string,
+  issues: RefSlotIssue[],
+): RefUse[] | undefined {
+  if (typeof annotation === "string" || annotation === undefined) return undefined;
+  if (!annotation || typeof annotation !== "object" || Array.isArray(annotation)) return undefined;
+  const obj = annotation as Record<string, unknown>;
+
+  const kind = obj.kind;
+  const hasKind =
+    (typeof kind === "string" && kind.length > 0) ||
+    (Array.isArray(kind) && kind.some((k) => typeof k === "string" && k.length > 0));
+  if (!hasKind) {
+    issues.push({
+      code: "X_TELO_REF_MISSING_KIND",
+      manifest,
+      path,
+      message:
+        `x-telo-ref at '${path}' declares no 'kind'. The structured form is ` +
+        `'{ kind: <Alias>.<Kind> | [<kinds>], use: <use> }' — without a kind the slot ` +
+        `constrains nothing and the editor has nothing to pick against.`,
+    });
+  }
+
+  const use = obj.use;
+  const isCaseMap =
+    !!use && typeof use === "object" && !Array.isArray(use) && "by" in (use as object);
+  if (use === undefined) {
+    issues.push({
+      code: "X_TELO_REF_MISSING_USE",
+      manifest,
+      path,
+      message:
+        `x-telo-ref at '${path}' declares no 'use'. The structured form must say what the ` +
+        `declaring resource does with the target — one of: ${VALID_USES} — or a ` +
+        `'{ by, cases }' map when a sibling config field selects the mode. Only the legacy ` +
+        `bare-string spelling ('x-telo-ref: <Kind>') may omit it.`,
+    });
+  } else {
+    for (const token of rawUseTokens(use)) {
+      if (isRefUse(token)) continue;
+      issues.push({
+        code: "X_TELO_REF_INVALID_USE",
+        manifest,
+        path,
+        message:
+          `x-telo-ref at '${path}' declares unrecognized use '${String(token)}'. ` +
+          `Valid uses: ${VALID_USES}. An unrecognized token would silently degrade the slot ` +
+          `to the legacy no-use reading.`,
+      });
+    }
+    if (isCaseMap) {
+      const by = (use as Record<string, unknown>).by;
+      if (typeof by !== "string" || !by.startsWith("/")) {
+        issues.push({
+          code: "X_TELO_REF_INVALID_USE",
+          manifest,
+          path,
+          message:
+            `x-telo-ref at '${path}' has a 'use' case map whose 'by' is not a JSON Pointer. ` +
+            `'by' names a sibling field of the object enclosing the slot, e.g. '/detach'.`,
+        });
+      }
+    }
+  }
+
+  return declaredUses(use);
+}
+
+/** True when a node is a reference slot: it carries `x-telo-ref` directly or on
+ *  an `anyOf`/`oneOf` branch. */
+function carriesRefAnnotation(obj: Record<string, unknown>): boolean {
+  if (obj["x-telo-ref"] !== undefined) return true;
+  for (const key of ["anyOf", "oneOf"] as const) {
+    const branches = obj[key];
+    if (!Array.isArray(branches)) continue;
+    if (
+      branches.some(
+        (b) => b && typeof b === "object" && (b as Record<string, unknown>)["x-telo-ref"] !== undefined,
+      )
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Walk a definition schema, invoking `onSlot` for every node that carries an
+ *  `x-telo-ref` (directly or on an `anyOf`/`oneOf` branch — the SLOT is the
+ *  node holding the branches, so a branch is never reported twice). Pure-schema
+ *  walk, so it needs — and has — a visited guard for cyclic `$defs`. */
+function walkSchema(
+  node: unknown,
+  path: string,
+  visited: Set<object>,
+  claimedBranches: Set<object>,
+  onSlot: (node: Record<string, unknown>, path: string) => void,
+): void {
+  if (!node || typeof node !== "object") return;
+  if (visited.has(node as object)) return;
+  visited.add(node as object);
+  if (Array.isArray(node)) {
+    node.forEach((item, i) => walkSchema(item, `${path}[${i}]`, visited, claimedBranches, onSlot));
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if (carriesRefAnnotation(obj) && !claimedBranches.has(obj)) {
+    onSlot(obj, path);
+    for (const key of ["anyOf", "oneOf"] as const) {
+      const branches = obj[key];
+      if (!Array.isArray(branches)) continue;
+      for (const branch of branches) {
+        if (branch && typeof branch === "object") claimedBranches.add(branch as object);
+      }
+    }
+  }
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === "x-telo-ref" || key === "examples" || key === "default") continue;
+    walkSchema(value, path ? `${path}.${key}` : key, visited, claimedBranches, onSlot);
+  }
+}
+
+/** Schema-level checks over one definition/abstract manifest. */
+export function validateRefSlotDeclarations(definition: ResourceManifest): RefSlotIssue[] {
+  const issues: RefSlotIssue[] = [];
+  const schema = (definition as Record<string, unknown>).schema;
+  if (!schema || typeof schema !== "object") return issues;
+
+  walkSchema(schema, "schema", new Set(), new Set(), (node, path) => {
+    const branchUses: RefUse[][] = [];
+    const own = checkAnnotation(node["x-telo-ref"], definition, path, issues);
+    if (own) branchUses.push(own);
+    for (const key of ["anyOf", "oneOf"] as const) {
+      const branches = node[key];
+      if (!Array.isArray(branches)) continue;
+      branches.forEach((branch, i) => {
+        if (!branch || typeof branch !== "object") return;
+        const declared = checkAnnotation(
+          (branch as Record<string, unknown>)["x-telo-ref"],
+          definition,
+          `${path}.${key}[${i}]`,
+          issues,
+        );
+        if (declared) branchUses.push(declared);
+      });
+    }
+    const nonEmpty = branchUses.filter((uses) => uses.length > 0);
+    if (nonEmpty.length > 1) {
+      const first = [...nonEmpty[0]].sort().join(",");
+      const disagrees = nonEmpty.some((uses) => [...uses].sort().join(",") !== first);
+      if (disagrees) {
+        issues.push({
+          code: "X_TELO_REF_USE_CONFLICT",
+          manifest: definition,
+          path,
+          message:
+            `x-telo-ref branches at '${path}' declare disagreeing uses ` +
+            `(${nonEmpty.map((u) => u.join("|")).join(" vs ")}). 'use' is a property of the ` +
+            `slot, never of a branch — declare several acceptable kinds as one ` +
+            `'kind: [<kinds>]' list with one 'use'.`,
+        });
+      }
+    }
+  });
+
+  return issues;
+}
+
+/** Manifest-level check: a `use` case map whose selector is written in CEL.
+ *  Reads the built graph's `unresolvedReason`, so the detection lives once, in
+ *  `resolveUseAtSite`, and this pass cannot disagree with what consumers saw. */
+export function validateDynamicSelectors(
+  allManifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases?: AliasResolver,
+  aliasesByModule?: Map<string, AliasResolver>,
+  graph?: CallGraph,
+): RefSlotIssue[] {
+  const issues: RefSlotIssue[] = [];
+  const callGraph = graph ?? buildCallGraph(allManifests, registry, { aliases, aliasesByModule });
+  for (const edge of callGraph.edges) {
+    if (edge.unresolvedReason !== "dynamic") continue;
+    const from = callGraph.nodes.get(edge.from);
+    const owner =
+      from?.type === "step" ? callGraph.nodes.get(from.owner) : from;
+    if (!owner || owner.type !== "resource") continue;
+    // Anchor at the SELECTOR — the field the author must change — not at the
+    // ref slot several lines away. Derivable: the slot's enclosing path plus
+    // the pointer's segments.
+    const selectorPath = selectorPathOf(edge.path, edge.unresolved?.by ?? "");
+    issues.push({
+      code: "X_TELO_REF_DYNAMIC_SELECTOR",
+      manifest: owner.manifest,
+      path: selectorPath,
+      message:
+        `The mode selector at '${selectorPath}' is a CEL expression, so which 'use' holds ` +
+        `for the reference at '${edge.path}' cannot be resolved statically. The selector must ` +
+        `be a literal or take its schema default — a call graph known only at runtime is not ` +
+        `statically analyzable. Write the mode as a literal, or split the wiring into one ` +
+        `resource per mode.`,
+    });
+  }
+  return issues;
+}
+
+/** Concrete path of a case-map selector: the slot's enclosing path joined with
+ *  the pointer's segments (`steps[0].invoke` + `/detach` → `steps[0].detach`). */
+function selectorPathOf(slotPath: string, pointer: string): string {
+  const lastDot = slotPath.lastIndexOf(".");
+  const enclosing = lastDot < 0 ? "" : slotPath.slice(0, lastDot);
+  const segments = pointer
+    .replace(/^\//, "")
+    .split("/")
+    .map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"))
+    .join(".");
+  return enclosing ? `${enclosing}.${segments}` : segments;
+}

package/src/validate-references.ts

@@ -40,7 +40,14 @@ function checkKind(
     if (subtypeKinds.has(resolved)) return [];
     if (targetDef.kind === "Telo.Abstract") {
       if (subtypes.length === 0) return []; // partial context — no implementations loaded yet
-      const options = [...subtypeKinds].join(", ");
+      // Suggest only what an author can actually wire: with abstract-extends-
+      // abstract real (Telo.Executable over Invocable/Runnable), the transitive
+      // subtype list contains abstracts, which are non-instantiable and would
+      // read as fixes that cannot work.
+      const concrete = subtypes
+        .filter((d) => d.kind !== "Telo.Abstract")
+        .map((d) => `${d.metadata.module}.${d.metadata.name}`);
+      const options = (concrete.length > 0 ? concrete : [...subtypeKinds]).join(", ");
       errors.push(
         `'${kind}' does not implement '${targetKind}' (known implementations: ${options})`,
       );

package/src/validate-zone-slots.ts

@@ -0,0 +1,175 @@
+/**
+ * Static validation of the two execution-zone annotations themselves — the
+ * strict half of the accessor split, mirroring `validate-ref-slots.ts`.
+ *
+ * `readProvidesZone` / `readRequiresZone` are deliberately lenient: they return
+ * `undefined` for anything they cannot read. Without this pass that leniency is
+ * silent in the worst possible direction, because the two annotations fail in
+ * OPPOSITE ways:
+ *
+ *  - an unreadable **requires** annotation drops the requirement entirely, so a
+ *    safety constraint the author wrote is never enforced — and the resource
+ *    then throws `ERR_ZONE_REQUIRED` / `ERR_ZONE_ANNOTATION_MISSING` at
+ *    dispatch. That is exactly the silent-non-enforcement `ZONE_PROVIDER_UNRESOLVED`
+ *    exists to prevent, reached by a different route.
+ *  - an unreadable **provides** annotation drops the discharge, so the pass
+ *    reports `ZONE_REQUIREMENT_UNSATISFIED` on manifests that are correct.
+ *
+ * A third shape is worse than either: a `key` the analyzer skips but the kernel
+ * accepts (a pointer with no leading `/` — the kernel's walk splits on `/` and
+ * drops empty segments, so it resolves) makes the two halves disagree about what
+ * the manifest MEANS, which is the one outcome neither severity can express.
+ *
+ * Scoping follows `X_TELO_REF_UNRESOLVED`: reported only for definitions in the
+ * entry's own modules — a published dependency's slot is not the consumer's to
+ * fix.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+
+export interface ZoneSlotIssue {
+  code: "ZONE_ANNOTATION_INVALID";
+  manifest: ResourceManifest;
+  /** Schema path of the annotated slot. */
+  path: string;
+  message: string;
+}
+
+const PROVIDES = "x-telo-provides-zone";
+const REQUIRES = "x-telo-requires-zone";
+
+/** A self-relative JSON Pointer, the only correlation-key spelling both halves
+ *  read identically. `""` (whole document) is meaningless as a key, so a
+ *  pointer must name at least one segment. */
+function isPointer(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith("/") && value.length > 1;
+}
+
+function describe(value: unknown): string {
+  if (typeof value === "string") return `'${value}'`;
+  if (Array.isArray(value)) return `a list`;
+  if (value === null) return "null";
+  return typeof value;
+}
+
+function checkProvides(
+  raw: unknown,
+  definition: ResourceManifest,
+  path: string,
+  issues: ZoneSlotIssue[],
+): void {
+  if (raw === true) return;
+  if (isPointer(raw)) return;
+  issues.push({
+    code: "ZONE_ANNOTATION_INVALID",
+    manifest: definition,
+    path,
+    message:
+      `${PROVIDES} at '${path}' is ${describe(raw)}. It takes 'true' (the zone is ` +
+      `uncorrelated) or a self-relative JSON Pointer naming this kind's own field ` +
+      `whose resolved reference the zone carries as its correlation payload ` +
+      `(e.g. '/connection'). It never names the zone — the zone a slot provides ` +
+      `is always the declaring kind.`,
+  });
+}
+
+function checkRequires(
+  raw: unknown,
+  definition: ResourceManifest,
+  path: string,
+  issues: ZoneSlotIssue[],
+): void {
+  const fail = (message: string): void => {
+    issues.push({ code: "ZONE_ANNOTATION_INVALID", manifest: definition, path, message });
+  };
+
+  // Bare-string form: the zone kind, uncorrelated.
+  if (typeof raw === "string") {
+    if (!raw) fail(`${REQUIRES} at '${path}' is an empty string; name the providing kind.`);
+    return;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    fail(
+      `${REQUIRES} at '${path}' is ${describe(raw)}. It takes an alias-qualified kind name ` +
+        `(e.g. 'Self.Transaction') or an object with 'zone', an optional 'key' and an ` +
+        `optional 'reason'.`,
+    );
+    return;
+  }
+
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.zone !== "string" || !obj.zone) {
+    fail(
+      `${REQUIRES} at '${path}' declares no 'zone'. Name the providing kind with the same ` +
+        `alias-qualified grammar 'extends' and 'x-telo-ref' use — '<Alias>.<Kind>', ` +
+        `'Self.<Kind>', or 'Telo.<Kind>'. Without it the requirement is silently ` +
+        `unenforced, and the resource throws at dispatch instead.`,
+    );
+  }
+
+  if (obj.key !== undefined) {
+    const pointers = Array.isArray(obj.key) ? obj.key : [obj.key];
+    if (Array.isArray(obj.key) && obj.key.length === 0) {
+      fail(`${REQUIRES} at '${path}' declares an empty 'key' list; omit 'key' instead.`);
+    }
+    for (const pointer of pointers) {
+      if (isPointer(pointer)) continue;
+      fail(
+        `${REQUIRES} at '${path}' declares the correlation key ${describe(pointer)}, which is ` +
+          `not a self-relative JSON Pointer. Write '/connection' (or a list of pointers tried ` +
+          `in order, first hit winning). A bare field name is read as a pointer by the runtime ` +
+          `but skipped by the checker, so the two halves would disagree about what this ` +
+          `manifest means.`,
+      );
+    }
+  }
+
+  if (obj.reason !== undefined && typeof obj.reason !== "string") {
+    fail(`${REQUIRES} at '${path}' declares a non-string 'reason'.`);
+  }
+
+  for (const key of Object.keys(obj)) {
+    if (key === "zone" || key === "key" || key === "reason") {
+      continue;
+    }
+    fail(
+      `${REQUIRES} at '${path}' declares an unknown property '${key}'. The object form takes ` +
+        `'zone', 'key' and 'reason'.`,
+    );
+  }
+}
+
+/** Walk a definition schema, reporting every zone annotation it cannot read.
+ *  Pure-schema walk, so it needs a visited guard for cyclic `$defs`. */
+function walkSchema(
+  node: unknown,
+  path: string,
+  visited: Set<object>,
+  definition: ResourceManifest,
+  issues: ZoneSlotIssue[],
+): void {
+  if (!node || typeof node !== "object") return;
+  if (visited.has(node as object)) return;
+  visited.add(node as object);
+  if (Array.isArray(node)) {
+    node.forEach((item, i) => walkSchema(item, `${path}[${i}]`, visited, definition, issues));
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if (obj[PROVIDES] !== undefined) checkProvides(obj[PROVIDES], definition, path, issues);
+  if (obj[REQUIRES] !== undefined) checkRequires(obj[REQUIRES], definition, path, issues);
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === PROVIDES || key === REQUIRES || key === "examples" || key === "default") continue;
+    walkSchema(value, path ? `${path}.${key}` : key, visited, definition, issues);
+  }
+}
+
+/** Schema-level zone-annotation checks over one definition/abstract manifest. */
+export function validateZoneSlotDeclarations(definition: ResourceManifest): ZoneSlotIssue[] {
+  const issues: ZoneSlotIssue[] = [];
+  const schema = (definition as Record<string, unknown>).schema;
+  if (!schema || typeof schema !== "object") return issues;
+  walkSchema(schema, "schema", new Set(), definition, issues);
+  return issues;
+}

package/src/zone-module-documents.ts

@@ -0,0 +1,27 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+/**
+ * One imported library's FULL document set, for the zone stage's per-library
+ * export derivation — what the flattened analysis view no longer holds, since
+ * it forwards only each library's export surface and never its internal
+ * dispatch chain.
+ *
+ * Plain data in a module of its own, deliberately. It is produced by the
+ * loading side (`collectZoneModuleDocuments`), named in `AnalysisOptions`, and
+ * consumed by the projection; putting it in any of the three would make the
+ * other two import that one, and `types.ts` ↔ the projection is a genuine
+ * cycle. A leaf module with no imports of its own breaks it without an inline
+ * `import(...)` type expression standing in for the dependency nobody wanted.
+ */
+export interface ZoneModuleDocuments {
+  /** The library's module name (its `Telo.Library` doc's `metadata.name`). */
+  module: string;
+  /** Stable source identity of the library's owner file — the cache key. */
+  sourceId: string;
+  /** Owner + partial manifests, stamped with `metadata.source` / `.module`. */
+  manifests: ResourceManifest[];
+  /** Precomputed content signature; derived from the documents when absent. */
+  signature?: string;
+  /** The library's declared `exports.resources` entries (bare names). */
+  exportedNames: readonly string[];
+}

package/src/zone-slot.ts

@@ -0,0 +1,116 @@
+/**
+ * The single reader of the two execution-zone annotations —
+ * `x-telo-provides-zone` and `x-telo-requires-zone` (see
+ * `kernel/specs/execution-zones.md`). The analyzer's zone projection, the
+ * kernel's `withZone` / `requireZone`, and any editor surface all recognise a
+ * zone slot here and nowhere else, the same one-accessor rule `ref-slot.ts`
+ * established for `x-telo-ref`. Browser-safe: no Node built-ins.
+ *
+ * Accepted shapes:
+ *
+ *   x-telo-provides-zone: true            # uncorrelated — the zone is the kind
+ *   x-telo-provides-zone: /connection     # correlation-key pointer (own field)
+ *
+ *   x-telo-requires-zone: Self.Transaction        # uncorrelated string form
+ *   x-telo-requires-zone:                          # object form
+ *     zone: Self.Transaction
+ *     key: [/connection, /transaction/connection]  # ordered, first hit wins
+ *     reason: the statement would execute outside any transaction
+ */
+
+const PROVIDES = "x-telo-provides-zone";
+const REQUIRES = "x-telo-requires-zone";
+
+/** A body slot that establishes the declaring kind's zone when dispatched
+ *  through. The zone's identity is always the declaring kind — the annotation
+ *  never names one, so provision-on-behalf-of is unrepresentable. */
+export interface ProvidesZoneSlot {
+  /** Self-relative JSON pointer to the declaring kind's own field whose resolved
+   *  reference the zone carries as its correlation payload. Absent =
+   *  uncorrelated (`true`). */
+  key?: string;
+}
+
+/** A field declaring that its resource must be reached through a zone. */
+export interface RequiresZoneSlot {
+  /** The providing kind, alias-qualified as authored (`Self.Transaction`,
+   *  `<Alias>.<Kind>`) — canonical `<module>.<Kind>` once
+   *  `resolveSchemaRefKinds` has rewritten it in the declaring scope. */
+  zone: string;
+  /** Ordered self-relative JSON pointers tried in order, first hit winning; a
+   *  pointer may traverse a `!ref` into the referenced resource's own field.
+   *  Empty = uncorrelated. */
+  key: string[];
+  /** The runtime consequence, quoted after the path in diagnostics. */
+  reason?: string;
+}
+
+/** A self-relative JSON Pointer — the only correlation-key spelling the
+ *  analyzer and the kernel read identically. Applied to BOTH the scalar and the
+ *  list form: the kernel's walk splits on `/` and drops empty segments, so a
+ *  bare `connection` would resolve there while the checker skipped it, and the
+ *  two halves would disagree about what the manifest means. `validate-zone-slots`
+ *  reports what this rejects. */
+function isPointer(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith("/") && value.length > 1;
+}
+
+/** Reads a schema node's provides-zone declaration, or undefined when it has
+ *  none or the value is malformed (`validate-zone-slots` reports those). */
+export function readProvidesZone(node: Record<string, any> | undefined): ProvidesZoneSlot | undefined {
+  const raw = node?.[PROVIDES];
+  if (raw === true) return {};
+  if (isPointer(raw)) return { key: raw };
+  return undefined;
+}
+
+/** True when the node carries `x-telo-provides-zone` in any shape, valid or not
+ *  — the recognition test validation needs before it judges the value. */
+export function hasProvidesZone(node: Record<string, any> | undefined): boolean {
+  return node?.[PROVIDES] !== undefined;
+}
+
+/** Reads a schema node's requires-zone declaration, or undefined when it has
+ *  none or the value is malformed (`validate-zone-slots` reports those). */
+export function readRequiresZone(node: Record<string, any> | undefined): RequiresZoneSlot | undefined {
+  const raw = node?.[REQUIRES];
+  if (typeof raw === "string" && raw) return { zone: raw, key: [] };
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.zone !== "string" || !obj.zone) return undefined;
+  // One filter for both spellings — see `isPointer`.
+  const key = (Array.isArray(obj.key) ? obj.key : [obj.key]).filter(isPointer);
+  const slot: RequiresZoneSlot = { zone: obj.zone, key };
+  if (typeof obj.reason === "string") slot.reason = obj.reason;
+  return slot;
+}
+
+/** True when the node carries `x-telo-requires-zone` in any shape. */
+export function hasRequiresZone(node: Record<string, any> | undefined): boolean {
+  return node?.[REQUIRES] !== undefined;
+}
+
+/**
+ * Rewrites the requires-zone kind name in place, in whichever shape it is
+ * written — the write-side twin of {@link readRequiresZone}, mirroring
+ * `rewriteRefSlotKinds` so `resolveSchemaRefKinds` canonicalizes both
+ * annotations in one walk. `map` returns the replacement or `undefined` to
+ * leave the authored name untouched (idempotence + quotable diagnostics).
+ */
+export function rewriteRequiresZoneKind(
+  annotationHolder: Record<string, any>,
+  map: (kind: string) => string | undefined,
+): void {
+  const raw = annotationHolder[REQUIRES];
+  if (typeof raw === "string") {
+    const next = map(raw);
+    if (next !== undefined) annotationHolder[REQUIRES] = next;
+    return;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+  const obj = raw as Record<string, unknown>;
+  if (typeof obj.zone === "string") {
+    const next = map(obj.zone);
+    if (next !== undefined) obj.zone = next;
+  }
+}