@telorun/analyzer 0.62.1 → 0.64.0

package/src/referrer-rule.ts

@@ -0,0 +1,116 @@
+/**
+ * The single reader for `x-telo-referrer-rules` — a kind declaring, as data,
+ * what must be true of whoever REFERENCES one of its resources.
+ *
+ * `x-telo-resource-rules` relates the fields of one resource; this relates a
+ * resource to the one that reached it. `Http.Reference` renders the OpenAPI
+ * document its server collects, so a server mounting it without an `openapi:`
+ * block has nothing to render — a disagreement neither kind can state alone,
+ * and one that otherwise surfaces only at boot, after the port is bound.
+ *
+ * Declared by the kind that HAS the requirement, never by the kind that must
+ * satisfy it. That is what lets a third-party mount carry its own requirement
+ * without `Http.Server` knowing the kind exists — and it is what keeps the rule
+ * free of a kind literal on the subject side, where the spelling would be the
+ * consumer's import alias rather than anything the rule author controls.
+ *
+ * The CEL scope is `self` (the declaring resource) and `referrer` (the one that
+ * references it). Deliberately NOT `this`: in a resource rule `this` is an
+ * ELEMENT of a collection, and binding it to a whole foreign manifest would give
+ * one word two meanings across the two families.
+ *
+ * Lenient by design, the `ref-slot.ts` precedent: anything unreadable here reads
+ * as absent, and `validate-referrer-rules.ts` is the strict half that reports it.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import { celSourceOf, type ResourceRuleSeverity } from "./resource-rule.js";
+
+export const REFERRER_RULES_ANNOTATION = "x-telo-referrer-rules";
+
+export interface ReferrerRule {
+  /**
+   * Kind the referring resource must be for this rule to apply, in the
+   * alias-qualified grammar `extends:` and `x-telo-ref` use — canonicalized in
+   * the declaring module's scope at registration, so evaluation never sees an
+   * alias. Absent = any referrer, which conflates "references me" with the
+   * relation the rule is about, so a kind should write it.
+   */
+  readonly referrer?: string;
+  /** CEL source. TRUE when the rule holds. */
+  readonly condition: string;
+  /** The rule's own name, carried in `data.rule`. Never a diagnostic code —
+   *  every violation reports under the analyzer-owned envelope. */
+  readonly code: string;
+  readonly message: string;
+  readonly severity: ResourceRuleSeverity;
+  /** Position in the annotation array — the anchor for a declaration defect. */
+  readonly index: number;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/** The annotation exactly as written, for the strict half. `undefined` when the
+ *  kind declares none; a non-array is returned as-is so the shape can be
+ *  reported rather than silently skipped. */
+export function readRawReferrerRules(schema: unknown): unknown {
+  if (!isObject(schema)) return undefined;
+  return schema[REFERRER_RULES_ANNOTATION];
+}
+
+/** Every rule this kind declares that is well-formed enough to run. */
+export function readReferrerRules(schema: unknown): ReferrerRule[] {
+  const raw = readRawReferrerRules(schema);
+  if (!Array.isArray(raw)) return [];
+  const rules: ReferrerRule[] = [];
+  raw.forEach((entry, index) => {
+    if (!isObject(entry)) return;
+    const condition = celSourceOf(entry.condition);
+    const { code, message, referrer } = entry;
+    if (!condition || typeof code !== "string" || typeof message !== "string") return;
+    if (code.length === 0 || message.length === 0) return;
+    if (referrer !== undefined && typeof referrer !== "string") return;
+    if (entry.severity !== undefined && entry.severity !== "warning" && entry.severity !== "error") {
+      return;
+    }
+    rules.push({
+      ...(referrer === undefined ? {} : { referrer }),
+      condition,
+      code,
+      message,
+      severity: entry.severity === "warning" ? "warning" : "error",
+      index,
+    });
+  });
+  return rules;
+}
+
+/** True when this node carries the annotation — the recognizer the schema-kind
+ *  canonicalization walk tests, so shape knowledge stays in this file. */
+export function hasReferrerRules(node: Record<string, unknown>): boolean {
+  return Array.isArray(node[REFERRER_RULES_ANNOTATION]);
+}
+
+/**
+ * Rewrite each rule's `referrer:` kind through `rewrite`, in place.
+ *
+ * The mirror of `rewriteRequiresZoneKind`: the alias→canonical rule lives in
+ * `resolve-schema-ref-kinds.ts` and the shape lives here, so a filter is
+ * canonical everywhere downstream and a name that resolves to nothing is
+ * reported once, at the kind that wrote it. A rewrite returning `undefined`
+ * leaves the value as written — the caller reports it.
+ */
+export function rewriteReferrerRuleKinds(
+  node: Record<string, unknown>,
+  rewrite: (kind: string) => string | undefined,
+): void {
+  const raw = node[REFERRER_RULES_ANNOTATION];
+  if (!Array.isArray(raw)) return;
+  for (const entry of raw) {
+    if (!isObject(entry) || typeof entry.referrer !== "string") continue;
+    const rewritten = rewrite(entry.referrer);
+    if (rewritten !== undefined) entry.referrer = rewritten;
+  }
+}

package/src/release/index.ts

@@ -59,6 +59,7 @@ export {
   readManifestVersion,
   stampCrateVersion,
   stampManifestVersion,
+  stampSelfNpmPins,
   stampPackageVersion,
 } from "./version-stamp.js";
 

package/src/release/version-stamp.ts

@@ -66,6 +66,64 @@ export function stampManifestVersion(
   return spliceScalar(text, node, version, where);
 }
 
+/**
+ * `pkg:npm/<name>@<version>` candidates naming the module's OWN package.
+ *
+ * A module has one version, and its manifest pins the package it ships itself —
+ * so the pin has to move with the rest of it. Left behind, the manifest names a
+ * tarball older than the module describing it, which is exactly how an
+ * npm-delivered module came to point at a years-old version of itself.
+ *
+ * Anchored on the `controllers:` SCALARS the YAML actually holds, not on a free
+ * text match: this file's whole rule is find the scalar, splice its span, touch
+ * nothing else, and a bare regex over the document would also reach a PURL
+ * written in a description, an example or a comment. Matched by exact package
+ * name, so a PURL naming a DIFFERENT package — a real dependency, pinned
+ * deliberately — is untouched.
+ */
+export function stampSelfNpmPins(
+  text: string,
+  packageName: string,
+  version: string,
+  where = "controllers",
+): string {
+  const docs = parseAllDocuments(text, { customTags: defaultCustomTags() });
+  const prefix = `pkg:npm/${packageName}@`;
+  const edits: { start: number; end: number; newText: string }[] = [];
+
+  for (const doc of docs) {
+    const controllers = doc.get("controllers", true);
+    const items = (controllers as { items?: unknown[] } | undefined)?.items;
+    if (!Array.isArray(items)) continue;
+    for (const item of items) {
+      if (!isScalar(item) || typeof item.value !== "string") continue;
+      const purl = item.value;
+      if (!purl.startsWith(prefix)) continue;
+      // Everything from the version up to the first qualifier or fragment is the
+      // pin; the rest of the PURL (`?local_path=…#Export`) is carried through.
+      const rest = purl.slice(prefix.length);
+      const tail = rest.search(/[?#]/);
+      const rewritten = `${prefix}${version}${tail === -1 ? "" : rest.slice(tail)}`;
+      if (rewritten === purl) continue;
+      const range = item.range;
+      if (!range) {
+        throw new VersionStampError(`${where}: a controller PURL carries no source range.`);
+      }
+      const [start, end] = range;
+      const replacement = renderFixReplacement(text.slice(start, end), rewritten);
+      if (replacement === undefined) {
+        throw new VersionStampError(
+          `${where}: the controller PURL '${purl}' cannot be rewritten in place. ` +
+            `Write it as a plain or quoted scalar on one line.`,
+        );
+      }
+      edits.push({ start, end, newText: replacement });
+    }
+  }
+
+  return edits.length === 0 ? text : applyTextEdits(text, edits);
+}
+
 /** Read the module doc's `metadata.version` without rewriting it. */
 export function readManifestVersion(text: string): string | undefined {
   const docs = parseAllDocuments(text, { customTags: defaultCustomTags() });

package/src/release/workspace-config.ts

@@ -8,12 +8,16 @@
  * would read every example and every cached `.telo/manifests` copy as a released
  * module).
  *
- * The file is **optional and read only by `telo release`**. Nothing else — not
- * `run`, `check`, `publish`, `install`, `upgrade`, `migrate`, `module`, and not
- * the kernel — looks for it, so a single-manifest repo, a bare `examples/`
- * directory and a third-party module checkout keep working with nothing added.
- * Any field added later must be true of the whole tree, not derivable from it,
- * and harmless by its absence.
+ * The file is **optional**, and everything reading it is harmless without one.
+ * `telo release` requires one. `telo run` uses its LOCATION — never `modules:`,
+ * which is release scope — as the bound on the walk-up that collects `.env` /
+ * `.env.local`, and with no marker reads the manifest's own directory alone, as
+ * it did before this file existed; a bound is what keeps that walk out of a
+ * user's home directory. Nothing else — not `check`, `publish`, `install`,
+ * `upgrade`, `migrate`, `module`, and not the kernel — looks for it, so a
+ * single-manifest repo, a bare `examples/` directory and a third-party module
+ * checkout keep working with nothing added. Any field added later must be true
+ * of the whole tree, not derivable from it, and harmless by its absence.
  *
  * Parsing lives here, in the browser-safe half, because the editor answers
  * "what does changing this library bump?" from the same model. Finding the file

package/src/resolve-schema-ref-kinds.ts

@@ -1,6 +1,11 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import { rewriteRefSlotKinds } from "./ref-slot.js";
+import {
+  REFERRER_RULES_ANNOTATION,
+  hasReferrerRules,
+  rewriteReferrerRuleKinds,
+} from "./referrer-rule.js";
 import { hasRequiresZone, rewriteRequiresZoneKind } from "./zone-slot.js";
 
 const REF_ANNOTATION = "x-telo-ref";
@@ -27,9 +32,10 @@ export interface RefConstraintIssue {
   manifest: ResourceManifest;
   reason: RefConstraintReason;
   /** Which annotation carried the unresolved name: an `x-telo-ref` constraint
-   *  (the default) or an `x-telo-requires-zone` provider kind — the caller
-   *  reports the latter as ZONE_PROVIDER_UNRESOLVED. */
-  annotation?: "ref" | "zone";
+   *  (the default), an `x-telo-requires-zone` provider kind, or an
+   *  `x-telo-referrer-rules` `referrer:` filter — the caller reports those as
+   *  ZONE_PROVIDER_UNRESOLVED and REFERRER_RULE_INVALID. */
+  annotation?: "ref" | "zone" | "referrer";
   /** For `gated`: the target module and the kinds it does export. */
   gate?: { module: string; exported: string[] };
   /** Aliases the declaring scope does know — the "did you mean" material for
@@ -75,7 +81,11 @@ export function resolveSchemaRefKinds(
 ): RefConstraintIssue[] {
   const issues: RefConstraintIssue[] = [];
 
-  const record = (ref: string, path: string, annotation: "ref" | "zone" = "ref"): void => {
+  const record = (
+    ref: string,
+    path: string,
+    annotation: "ref" | "zone" | "referrer" = "ref",
+  ): void => {
     if (isLegacyRefIdentity(ref)) {
       issues.push({ ref, path, manifest: definition, reason: "legacy", annotation });
       return;
@@ -135,6 +145,20 @@ export function resolveSchemaRefKinds(
         return undefined;
       });
     }
+    if (hasReferrerRules(obj)) {
+      // A referrer rule's `referrer:` filter names a kind through the identical
+      // alias-qualified grammar, resolved in the same declaring scope — so the
+      // evaluation pass compares canonical kinds and never has to know which
+      // alias the CONSUMER happened to import the kind under. That is the whole
+      // reason such a rule can be sound where the same test written on the
+      // referring kind cannot.
+      rewriteReferrerRuleKinds(obj, (kind) => {
+        const result = resolver.resolveKindResult(kind);
+        if (result.status === "ok") return result.kind;
+        record(kind, `${path}.${REFERRER_RULES_ANNOTATION}`, "referrer");
+        return undefined;
+      });
+    }
     for (const key of Object.keys(obj)) {
       walk(obj[key], path ? `${path}.${key}` : key);
     }

package/src/resolve-throws-union.ts

@@ -2,6 +2,7 @@ import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { isTaggedSentinel } from "@telorun/templating";
 import { scopeResolverForModule, type AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { readStepSlot } from "./step-slot.js";
 
 export interface ThrowsCodeMeta {
   data?: Record<string, any>;
@@ -174,8 +175,8 @@ function resolveInherited(
   if (!props) return result;
 
   for (const [fieldName, fieldSchema] of Object.entries(props)) {
-    const stepCtx = fieldSchema["x-telo-step-context"] as Record<string, string> | undefined;
-    if (!stepCtx?.invoke) continue;
+    const stepCtx = readStepSlot(fieldSchema);
+    if (!stepCtx) continue;
     const steps = (manifest as Record<string, any>)[fieldName];
     if (!Array.isArray(steps)) continue;
     unionInto(result, collectStepArrayThrows(steps, stepCtx.invoke, undefined, ctx, ownerModule));
@@ -205,7 +206,7 @@ function collectStepArrayThrows(
 /** Walk one step, dispatching by shape. Generic for any Run.Sequence-style
  *  composer: the step keys it recognises (`try` / `catch` / `finally` / `then`
  *  / `else` / `elseif` / `do` / `cases` / `default`) are the same set already
- *  traversed by the analyzer's `x-telo-step-context` schema builder, so future
+ *  traversed by the analyzer's step-body walk, so future
  *  composers that reuse those shape conventions work without changes here. */
 function collectStepThrows(
   step: Record<string, any>,

package/src/resolve-zone-containment.ts

@@ -0,0 +1,329 @@
+/**
+ * Zone containment — *what is inside this zone*, which is the opposite question
+ * from the one `resolve-zone-requirements.ts` answers.
+ *
+ * The landed projection propagates a requirement callee→caller and asks *is this
+ * requirement satisfied*. Every check built on zone ATTRIBUTES asks the reverse:
+ * a `noSuspend` region has to know what it contains before it can forbid parking
+ * inside it, a `replayed` region before it can reject a detached dispatch, an
+ * `idempotent` region before it can call impure CEL a broken promise. So this is
+ * a DOWNWARD walk from a providing slot to everything its body reaches.
+ *
+ * It is a second consumer of the shared call graph, not a second graph, and it
+ * is **parameterized over the attribute that opens the region** — so the durable
+ * zone (`replayed`) and the constraint zones (`noSuspend`, `atomic`,
+ * `idempotent`) share one traversal. It resolves an attribute NAME and nothing
+ * else: no kind is named here, which is what keeps `modules/durable` out of the
+ * analyzer's surface and satisfies the topology-driven constraint.
+ *
+ * **Two shapes of body slot, one region.** A slot may hold its body as a
+ * reference to an executable (`Sql.Transaction.steps`) or carry a step array
+ * natively (the shared `Step` fragment, which any kind may point at). Both are
+ * regions; the first is entered through the slot's edge, the second through the
+ * step nodes the slot declares. Handling only the first would have made the
+ * checks silently vacuous on exactly the kinds written after the grammar became
+ * shared vocabulary.
+ *
+ * **The walk under-approximates, and that is the safe direction — for a CHECK.**
+ * A dynamically dispatched edge is invisible here, so a check over the result
+ * may stay silent where it should have spoken, and the runtime enforcement is
+ * what closes it. A consumer at the OPPOSITE polarity — the durable manifest
+ * digest, whose blind spot is silent replay against changed code rather than a
+ * missed diagnostic — must not inherit this tolerance, and verifies its coverage
+ * against the journal instead of trusting this set.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import type { CallGraph, CallGraphEdge, CallGraphNode, ResourceGraphNode } from "./call-graph.js";
+import { propertySchemas, resolveLocalRef } from "./manifest-navigation.js";
+import { isStepSlot } from "./step-slot.js";
+import { readProvidesZone } from "./zone-slot.js";
+
+/** One node the region reaches, with the route taken to it. */
+export interface ContainedNode {
+  node: CallGraphNode;
+  /** Labels of the hops from the body slot to this node, for a diagnostic that
+   *  names the path rather than only the endpoint. */
+  via: string[];
+}
+
+/** A dispatch that leaves the region without extending it.
+ *
+ *  Recorded rather than followed, because the two facts are different and both
+ *  are wanted: the zone's lifetime does NOT reach the target (so nothing inside
+ *  it is contained), while the dispatch itself is a site inside the region that
+ *  a check may forbid outright — `DURABLE_DETACH_FORBIDDEN` is exactly that. */
+export interface RegionBoundary {
+  edge: CallGraphEdge;
+  /** The resource whose slot dispatches this way. */
+  from: ResourceGraphNode;
+  via: string[];
+  /** Why the zone stops here: the uses that do not extend it. */
+  escaping: string[];
+}
+
+/** A region opened by one providing slot carrying the requested attribute. */
+export interface ZoneRegion {
+  /** The attribute that opened it — the one the walk was asked for. */
+  attribute: string;
+  /** The author's reason, quoted verbatim by every diagnostic over this region.
+   *  Present by construction: an attribute's value IS the reason. */
+  reason: string;
+  /** The resource whose slot establishes the zone. */
+  provider: ResourceGraphNode;
+  /** Field-map path of the body slot (`steps`, `invoke`). */
+  slot: string;
+  /** Every attribute the slot declares, not only the requested one — a consumer
+   *  deciding collapse reads `atomic` and `idempotent` off one region. */
+  attributes: Readonly<Record<string, string>>;
+  /** Everything control reaches from the body, keyed by node id. Includes the
+   *  step nodes of a native body, since a step is where a check anchors. */
+  contents: ReadonlyMap<string, ContainedNode>;
+  /** Dispatches inside the region that the zone does not extend through. */
+  boundaries: readonly RegionBoundary[];
+}
+
+/** Resolves a kind name to its definition in the scope of the module that
+ *  DECLARED it — the same resolver the projection takes, passed in rather than
+ *  rebuilt so both walks agree about what a kind means. */
+export type DefinitionLookup = (kind: string, module?: string) => ResourceDefinition | undefined;
+
+const moduleOf = (node: ResourceGraphNode): string | undefined =>
+  (node.manifest.metadata as { module?: string } | undefined)?.module;
+
+/** The schema node at a field-map path, following `[]` into `items`, `{}` into
+ *  `additionalProperties` and local `$defs` refs. Same navigation the projection
+ *  performs — a slot's annotations live wherever this lands. */
+function schemaNodeAt(
+  rootSchema: Record<string, any> | undefined,
+  slotPath: string,
+): Record<string, any> | undefined {
+  if (!rootSchema) return undefined;
+  let current: Record<string, any> | undefined = rootSchema;
+  for (const segment of slotPath.split(".")) {
+    if (!current) return undefined;
+    const bare = segment.replace(/(\[\]|\{\})+$/g, "");
+    let next: Record<string, any> | undefined = propertySchemas(current).find(
+      ([k]) => k === bare,
+    )?.[1];
+    for (const marker of segment.slice(bare.length).match(/\[\]|\{\}/g) ?? []) {
+      next = resolveLocalRef(
+        marker === "[]"
+          ? (next?.items as Record<string, any> | undefined)
+          : (next?.additionalProperties as Record<string, any> | undefined),
+        rootSchema,
+      );
+      if (!next || typeof next !== "object") return undefined;
+    }
+    current = resolveLocalRef(next, rootSchema);
+  }
+  return current;
+}
+
+/**
+ * Does a zone's lifetime extend through this edge?
+ *
+ * EVERY member of `use` must be `call`. This is the landed reduction, and its
+ * asymmetry with the propagation rule is deliberate: a set says several
+ * relations hold at once, so a slot declaring `[call, detached]` really does
+ * detach on some dispatch, and a detached dispatch is never inside the caller's
+ * zone. An edge whose `use` could not be read extends nothing either — the
+ * conservative direction HERE, since over-reporting containment would invent
+ * failures inside regions that are correct.
+ */
+function extendsZone(edge: CallGraphEdge): boolean {
+  return edge.use.length > 0 && !edge.unresolved && edge.use.every((u) => u === "call");
+}
+
+/** Uses on an edge that leave the region, for the boundary record. */
+function escapingUses(edge: CallGraphEdge): string[] {
+  return edge.use.filter((u) => u !== "call" && u !== "dependency" && u !== "schema");
+}
+
+/** Walk down from one entry edge, collecting what the zone reaches. */
+function collect(
+  graph: CallGraph,
+  entries: readonly { edge?: CallGraphEdge; node: CallGraphNode; via: string[] }[],
+  contents: Map<string, ContainedNode>,
+  boundaries: RegionBoundary[],
+): void {
+  const queue = [...entries];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (contents.has(current.node.id)) continue;
+    contents.set(current.node.id, { node: current.node, via: current.via });
+
+    // A resource's own step nodes are part of whatever region reaches the
+    // resource: a step is where a check anchors (`the retry at
+    // importAll/fetch`), and its outgoing edge is the dispatch a rule judges.
+    const stepNodes =
+      current.node.type === "resource" ? graph.steps(current.node.id) : [];
+    for (const step of stepNodes) {
+      if (contents.has(step.id)) continue;
+      queue.push({
+        node: step,
+        via: [...current.via, step.name ? `step '${step.name}'` : step.path],
+      });
+    }
+
+    const owner: ResourceGraphNode | undefined =
+      current.node.type === "resource"
+        ? current.node
+        : (graph.nodes.get(current.node.owner) as ResourceGraphNode | undefined);
+
+    for (const edge of graph.edgesFrom(current.node.id)) {
+      if (edge.use.every((u) => u === "dependency" || u === "schema")) continue;
+      const target = edge.to ? graph.nodes.get(edge.to) : undefined;
+      if (!extendsZone(edge)) {
+        if (owner && escapingUses(edge).length > 0) {
+          boundaries.push({
+            edge,
+            from: owner,
+            via: current.via,
+            escaping: escapingUses(edge),
+          });
+        }
+        continue;
+      }
+      if (!target) continue;
+      queue.push({
+        node: target,
+        via: [...current.via, `${edge.slot} → ${edge.toName}`],
+      });
+    }
+  }
+}
+
+/**
+ * Every region in the graph opened by a slot declaring `attribute`.
+ *
+ * The provider itself is NOT in `contents` — a zone constrains what runs inside
+ * its body, not the resource that establishes it. A transaction's own
+ * `connection:` dependency is outside the region it opens, and a rule that
+ * treated the provider as contained would report the provider against its own
+ * constraint.
+ */
+export function findZoneRegions(
+  graph: CallGraph,
+  resolveDef: DefinitionLookup,
+  attribute: string,
+): ZoneRegion[] {
+  const regions: ZoneRegion[] = [];
+
+  for (const node of graph.nodes.values()) {
+    if (node.type !== "resource") continue;
+    const def = resolveDef(node.kind, moduleOf(node));
+    const rootSchema = def?.schema as Record<string, any> | undefined;
+    if (!rootSchema) continue;
+
+    // The providing slots of this kind, found by walking its own declared
+    // properties rather than by knowing any kind's field names.
+    for (const [slot, slotSchema] of providingSlots(rootSchema)) {
+      const provides = readProvidesZone(slotSchema);
+      const reason = provides?.attributes[attribute as keyof typeof provides.attributes];
+      if (!provides || typeof reason !== "string") continue;
+
+      const contents = new Map<string, ContainedNode>();
+      const boundaries: RegionBoundary[] = [];
+
+      // Shape one: the slot carries a step array natively. Its steps are the
+      // body, and they are owned by this resource, so they are found by path
+      // rather than by an edge.
+      if (isStepSlot(slotSchema)) {
+        const entries = graph
+          .steps(node.id)
+          .filter((step) => step.array === slot || step.array.startsWith(`${slot}[`))
+          .map((step) => ({
+            node: step as CallGraphNode,
+            via: [step.name ? `step '${step.name}'` : step.path],
+          }));
+        collect(graph, entries, contents, boundaries);
+      } else {
+        // Shape two: the slot references an executable. Its edges are the body.
+        // Entered regardless of the slot's OWN use — a providing slot
+        // establishes its zone before the enclosing lifetime terminates on that
+        // use, which is what lets a detached durable body both shed every
+        // enclosing zone and open its own.
+        const entries = graph
+          .edgesFrom(node.id)
+          .filter((edge) => edge.slot === slot && edge.to)
+          .map((edge) => ({
+            node: graph.nodes.get(edge.to!)!,
+            via: [`${slot} → ${edge.toName}`],
+          }))
+          .filter((entry) => entry.node !== undefined);
+        collect(graph, entries, contents, boundaries);
+      }
+
+      regions.push({
+        attribute,
+        reason,
+        provider: node,
+        slot,
+        attributes: provides.attributes as Readonly<Record<string, string>>,
+        contents,
+        boundaries,
+      });
+    }
+  }
+
+  return regions;
+}
+
+/** Field-map paths of every slot in a kind's schema carrying a provides-zone
+ *  annotation, with the schema node at each. Walks properties, array items and
+ *  `additionalProperties`, resolving local `$ref`s — the paths the call graph's
+ *  own edges are keyed by, so a slot found here matches an edge's `slot`. */
+function providingSlots(
+  rootSchema: Record<string, any>,
+): Array<[slot: string, schema: Record<string, any>]> {
+  const found: Array<[string, Record<string, any>]> = [];
+  const seen = new Set<object>();
+
+  const walk = (schema: Record<string, any> | undefined, path: string): void => {
+    const node = resolveLocalRef(schema, rootSchema);
+    if (!node || typeof node !== "object" || seen.has(node)) return;
+    seen.add(node);
+    if (path && readProvidesZone(node)) found.push([path, node]);
+    for (const [key, child] of propertySchemas(node)) {
+      const childPath = path ? `${path}.${key}` : key;
+      walk(child, childPath);
+      // A slot's zone annotation may sit on the ARRAY (`steps`) or on its item
+      // (`routes[].handler`); both are real field-map paths.
+      const items = resolveLocalRef(child?.items as Record<string, any> | undefined, rootSchema);
+      if (items) walk(items, `${childPath}[]`);
+      const additional = resolveLocalRef(
+        child?.additionalProperties as Record<string, any> | undefined,
+        rootSchema,
+      );
+      if (additional) walk(additional, `${childPath}{}`);
+    }
+  };
+
+  walk(rootSchema, "");
+  return found;
+}
+
+/** Convenience for a consumer that only wants membership: every node id inside
+ *  any region opened by `attribute`, mapped to the region that contains it. */
+export function containmentIndex(
+  regions: readonly ZoneRegion[],
+): ReadonlyMap<string, ZoneRegion> {
+  const index = new Map<string, ZoneRegion>();
+  for (const region of regions) {
+    for (const id of region.contents.keys()) {
+      if (!index.has(id)) index.set(id, region);
+    }
+  }
+  return index;
+}
+
+/** The manifests a region's contents belong to — what a diagnostic anchors on. */
+export function regionManifests(region: ZoneRegion): ResourceManifest[] {
+  const out: ResourceManifest[] = [];
+  for (const { node } of region.contents.values()) {
+    if (node.type === "resource") out.push(node.manifest);
+  }
+  return out;
+}