@telorun/analyzer 0.73.0 → 0.74.0

package/src/resolve-throws-union.ts

@@ -1,12 +1,18 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import { isTaggedSentinel } from "@telorun/templating";
 import { scopeResolverForModule, type AliasResolver } from "./alias-resolver.js";
-import { resolveScopedName } from "./call-graph.js";
+import { resolveScopedName, resolveSlotUseAt } from "./call-graph.js";
 import { refSentinelTarget, type RefSentinelTarget } from "./ref-sentinel-target.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
-import { possibleUses, readRefSlot, transfersControl, type RefSlot } from "./ref-slot.js";
-import { readStepSlot } from "./step-slot.js";
+import {
+  hasDeclaredUse,
+  possibleUses,
+  transfersControl,
+  type RefSlot,
+  type RefUse,
+} from "./ref-slot.js";
 import { forEachDrivenSlot } from "./schema-walk.js";
+import type { StepSlot } from "./step-slot.js";
 
 export interface ThrowsCodeMeta {
   data?: Record<string, any>;
@@ -207,10 +213,10 @@ function codesFromDefinition(definition: ResourceDefinition): Map<string, Throws
 }
 
 /** Resolve the effective throw union for a named manifest. The result combines
- *  explicit `throws.codes`, `throws.inherit: true` dataflow (step-context
- *  traversal with try/catch subtraction), and unbounded markers for
- *  unresolvable passthrough call sites. Cycles short-circuit to an empty
- *  result so resolution always terminates. */
+ *  explicit `throws.codes`, `throws.inherit: true` dataflow (step bodies with
+ *  try/catch subtraction, plus reference slots that hand a failure back), and
+ *  unbounded markers for unresolvable passthrough call sites. Cycles
+ *  short-circuit to an empty result so resolution always terminates. */
 export function resolveThrowsUnion(
   manifest: ResourceManifest,
   ctx: ResolveCtx,
@@ -266,14 +272,42 @@ export function resolveThrowsUnion(
 }
 
 /**
- * `throws.inherit: true` — the union a composer's own STEP BODIES reach.
+ * True for a use through which a target's failure reaches the declaring
+ * resource's CALLER: `call` returns into my invocation, and `trigger.consumer`
+ * rejects the value my caller drains. `detached` and `trigger.inbound` run where
+ * no caller of mine awaits them; `dependency` and `schema` dispatch nothing.
  *
- * Deliberately steps only, and not every slot the resource drives: `inherit` is
- * a DECLARATION that a kind's union is the union of what it dispatches, and a
- * kind that does not make that claim must not have it inferred — a kind holding
- * a `call` ref it catches internally would silently gain codes it never lets
- * escape. What a CATCH SCOPE needs is a different question with a different
- * answer, and it has its own resolver below.
+ * The reduction `inherit` is read through — by the resolver and by the check
+ * that a definition declaring it has something to inherit from.
+ */
+export function handsFailureBack(use: RefUse): boolean {
+  return use === "call" || use === "trigger.consumer";
+}
+
+/**
+ * The uses a throws consumer reads off a slot. A slot that declares no use —
+ * the legacy bare-string form — reads as `call`: the throws union must assume
+ * `call` to keep an error path, the direction the call graph takes for the same
+ * slot. The zone projection reads it the opposite way, deliberately.
+ *
+ * `uses` defaults to every use the slot can take; a consumer that resolved the
+ * slot's case map for one instance passes that answer instead.
+ */
+export function throwsUses(
+  slot: RefSlot,
+  uses: readonly RefUse[] = possibleUses(slot),
+): readonly RefUse[] {
+  return hasDeclaredUse(slot) ? uses : ["call"];
+}
+
+/**
+ * `throws.inherit: true` — the union of what the resource dispatches: its step
+ * bodies (try/catch subtraction included) and every reference slot whose use,
+ * resolved for THIS instance, hands a failure back ({@link handsFailureBack}).
+ *
+ * Only on a kind that DECLARES `inherit`: it is a claim that the kind lets what
+ * it dispatches escape, and a kind catching a slot internally does not make it.
+ * What a CATCH SCOPE encloses is a different question, answered below.
  */
 function resolveInherited(
   manifest: ResourceManifest,
@@ -282,16 +316,23 @@ function resolveInherited(
   ownerModule: string | undefined,
 ): ThrowsUnion {
   const result: ThrowsUnion = { codes: new Map(), unbounded: false };
-  const props = definition.schema?.properties as Record<string, any> | undefined;
-  if (!props) return result;
-
-  for (const [fieldName, fieldSchema] of Object.entries(props)) {
-    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));
-  }
+  const schema = definition.schema as Record<string, any> | undefined;
+
+  forEachDrivenSlot(schema, manifest, (driven) => {
+    if (driven.kind === "step") {
+      unionInto(result, stepSiteThrows(driven.data, driven.slots, ctx, ownerModule));
+      return;
+    }
+    // Several slots at one site are the branches declaring it; any one that
+    // hands a failure back counts, since a branch not applying can only add codes.
+    const handsBack = driven.slots.some(({ slot, fieldPath }) =>
+      throwsUses(
+        slot,
+        resolveSlotUseAt(slot, manifest, schema, driven.path, fieldPath).use,
+      ).some(handsFailureBack),
+    );
+    if (handsBack) unionInto(result, resolveRefTargetThrows(driven.data, ctx, ownerModule));
+  });
 
   return result;
 }
@@ -327,13 +368,15 @@ export function resolveScopeUnion(
 
   forEachDrivenSlot(definition.schema, manifest, (driven) => {
     if (driven.kind === "step") {
-      unionInto(
-        result,
-        collectStepArrayThrows(driven.data, driven.slot.invoke, undefined, ctx, ownerModule),
-      );
+      unionInto(result, stepSiteThrows(driven.data, driven.slots, ctx, ownerModule));
       return;
     }
-    if (driven.slot.throwsThrough) {
+    if (
+      driven.slots.some(({ slot }) => !slot.throwsThrough && throwsUses(slot).some(transfersControl))
+    ) {
+      unionInto(result, resolveRefTargetThrows(driven.data, ctx, ownerModule));
+    }
+    if (driven.slots.some(({ slot }) => slot.throwsThrough)) {
       const target = resolveRefManifest(driven.data, ctx, ownerModule);
       const targetDef = target
         ? definitionFor(
@@ -347,15 +390,27 @@ export function resolveScopeUnion(
       // A target that cannot be resolved says nothing about what it throws, so
       // the scope's union is no longer enumerable.
       else result.unbounded = true;
-      return;
     }
-    if (!possibleUses(driven.slot).some(transfersControl)) return;
-    unionInto(result, resolveRefTargetThrows(driven.data, ctx, ownerModule));
   });
 
   return result;
 }
 
+/** The union a step-body site reaches — once per distinct invoke field, since
+ *  several branches may declare a body at one site. */
+function stepSiteThrows(
+  steps: unknown[],
+  slots: StepSlot[],
+  ctx: ResolveCtx,
+  ownerModule: string | undefined,
+): ThrowsUnion {
+  const result = emptyUnion();
+  for (const invoke of new Set(slots.map((slot) => slot.invoke))) {
+    unionInto(result, collectStepArrayThrows(steps, invoke, undefined, ctx, ownerModule));
+  }
+  return result;
+}
+
 function collectStepArrayThrows(
   steps: unknown[],
   invokeField: string,

package/src/resolve-zone-requirements.ts

@@ -32,6 +32,7 @@ import type { ModuleDocuments } from "./module-documents.js";
 import { readProvidesZone, readRequiresZone } from "./zone-slot.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 import { moduleAliasScope } from "./module-alias-scope.js";
+import { isForwardedDeclaration } from "./forwarded-declaration.js";
 
 const SOURCE = "telo-analyzer";
 
@@ -616,7 +617,7 @@ export function projectZoneRequirements(args: ProjectionArgs): ProjectionResult
     // (with the internal graph in hand) and seeded below — deriving them here
     // against the flattened view would resolve correlation against a graph
     // that no longer holds the library's internals.
-    if (meta?.forwardedExport) continue;
+    if (isForwardedDeclaration(node.manifest)) continue;
     const def = resolveDef(node.kind, meta?.module);
     const schema = def?.schema as Record<string, any> | undefined;
     if (!def || !schema) continue;

package/src/rewrite-synthetic-origins.ts

@@ -7,9 +7,9 @@ interface XTeloOrigin {
   pathFromParent: string;
 }
 
-function readOrigin(manifest: ResourceManifest | undefined): XTeloOrigin | undefined {
-  if (!manifest) return undefined;
-  const origin = (manifest.metadata as { xTeloOrigin?: XTeloOrigin } | undefined)?.xTeloOrigin;
+function readOrigin(manifest: unknown): XTeloOrigin | undefined {
+  if (!manifest || typeof manifest !== "object") return undefined;
+  const origin = (manifest as { metadata?: { xTeloOrigin?: XTeloOrigin } }).metadata?.xTeloOrigin;
   if (
     !origin ||
     typeof origin.parentKind !== "string" ||
@@ -26,7 +26,12 @@ function readOrigin(manifest: ResourceManifest | undefined): XTeloOrigin | undef
  *  `data.resource`, which has no YAML source. Rewrite each such diagnostic
  *  back to the chain root: walk up `metadata.xTeloOrigin` until a manifest
  *  with no origin is reached, and prepend each hop's `pathFromParent` to
- *  `data.path` so position-index lookups against the root doc resolve. */
+ *  `data.path` so position-index lookups against the root doc resolve.
+ *
+ *  An extraction from a scope member lives INSIDE the scope array rather than at
+ *  the top level, so a diagnostic about it names the top-level owner and a path
+ *  through an array index the author never wrote (`with[3]`). That prefix is
+ *  unfolded the same way, into the position the declaration was written at. */
 export function rewriteSyntheticOrigins(
   diagnostics: AnalysisDiagnostic[],
   manifests: ResourceManifest[],
@@ -45,31 +50,117 @@ export function rewriteSyntheticOrigins(
 
     let current = byName.get(data.resource.name);
     let origin = readOrigin(current);
-    if (!origin) return d;
-
-    let accumPath = typeof data.path === "string" ? data.path : "";
-    let rootKind: string = origin.parentKind;
-    let rootName: string = origin.parentName;
+    const path = typeof data.path === "string" ? data.path : "";
+    let accumPath = path;
+    let root: { kind?: string; name?: string } = data.resource;
 
     while (origin) {
       accumPath = accumPath ? `${origin.pathFromParent}.${accumPath}` : origin.pathFromParent;
-      rootKind = origin.parentKind;
-      rootName = origin.parentName;
+      root = { kind: origin.parentKind, name: origin.parentName };
       current = byName.get(origin.parentName);
       origin = readOrigin(current);
     }
 
-    const rootFilePath =
-      (current?.metadata as { source?: string } | undefined)?.source ?? data.filePath;
+    const rerouted = root !== data.resource;
+    const unfolded = current ? unfoldScopedOrigins(current, accumPath) : accumPath;
+    if (!rerouted && unfolded === path) return d;
 
     return {
       ...d,
       data: {
         ...data,
-        resource: { kind: rootKind, name: rootName },
-        filePath: rootFilePath,
-        path: accumPath,
+        resource: root,
+        filePath: rerouted
+          ? ((current?.metadata as { source?: string } | undefined)?.source ?? data.filePath)
+          : data.filePath,
+        path: unfolded,
       },
     };
   });
 }
+
+type Segment = string | number;
+
+/** Replace every scope-array index that holds an extraction with the position
+ *  the extraction was written at, until none is left. */
+function unfoldScopedOrigins(root: ResourceManifest, path: string): string {
+  let segments = parseSegments(path);
+  let unfoldedAny = false;
+  // Each unfolding replaces one extraction with its parent, which is strictly
+  // closer to what the author wrote, so the chain is as long as the nesting.
+  for (let hops = 0; hops <= segments.length + 16; hops++) {
+    const next = unfoldOnce(root, segments);
+    if (!next) break;
+    segments = next;
+    unfoldedAny = true;
+  }
+  // Re-formatting is lossy (an empty segment in `entries../x` is dropped), so a
+  // path nothing unfolded is returned as written.
+  return unfoldedAny ? formatSegments(segments) : path;
+}
+
+function unfoldOnce(root: ResourceManifest, segments: Segment[]): Segment[] | undefined {
+  let node: unknown = root;
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    const container = node;
+    node =
+      typeof segment === "number"
+        ? Array.isArray(container)
+          ? container[segment]
+          : undefined
+        : container && typeof container === "object" && !Array.isArray(container)
+          ? (container as Record<string, unknown>)[segment]
+          : undefined;
+    if (node === undefined || node === null) return undefined;
+    if (typeof segment !== "number" || i === 0) continue;
+    const origin = readOrigin(node);
+    if (!origin) continue;
+
+    // Its parent is either the resource holding this scope array (a slot of
+    // the resource that declares the scope) or a sibling member of the array.
+    const holderPath = segments.slice(0, i - 1);
+    let parentPath: Segment[] | undefined;
+    if (nameOf(at(root, holderPath)) === origin.parentName) {
+      parentPath = holderPath;
+    } else {
+      const sibling = (container as unknown[]).findIndex((m) => nameOf(m) === origin.parentName);
+      if (sibling >= 0) parentPath = [...segments.slice(0, i), sibling];
+    }
+    if (!parentPath) return undefined;
+    return [...parentPath, ...parseSegments(origin.pathFromParent), ...segments.slice(i + 1)];
+  }
+  return undefined;
+}
+
+function at(root: unknown, segments: Segment[]): unknown {
+  let node = root;
+  for (const segment of segments) {
+    if (!node || typeof node !== "object") return undefined;
+    node = (node as Record<string | number, unknown>)[segment];
+  }
+  return node;
+}
+
+function nameOf(value: unknown): string | undefined {
+  const name = (value as { metadata?: { name?: unknown } } | undefined)?.metadata?.name;
+  return typeof name === "string" ? name : undefined;
+}
+
+/** `with[3].steps[0].invoke` → `["with", 3, "steps", 0, "invoke"]`. */
+function parseSegments(path: string): Segment[] {
+  const out: Segment[] = [];
+  for (const match of path.matchAll(/\[(\d+)\]|([^.[\]]+)/g)) {
+    out.push(match[1] !== undefined ? Number(match[1]) : match[2]!);
+  }
+  return out;
+}
+
+function formatSegments(segments: Segment[]): string {
+  let out = "";
+  for (const segment of segments) {
+    if (typeof segment === "number") out += `[${segment}]`;
+    else out += out ? `.${segment}` : segment;
+  }
+  return out;
+}

package/src/schema-compat.ts

@@ -10,6 +10,7 @@ import {
   celTypeOfValueType,
   isCompiledValue,
   readValueTypeSlot,
+  VALUE_TYPE_BINDINGS,
   valueBrandBases,
   valueTypeOf,
   valueTypePlaceholder,
@@ -36,8 +37,9 @@ export function createAjv(): InstanceType<typeof Ajv> {
   // One registration site for every Telo keyword — the annotations as no-ops and
   // `x-telo-type` as the one that checks. Registered here and in the kernel's
   // validators from one definition, so a literal at an instance-typed slot is
-  // rejected statically and at dispatch by the identical rule.
-  registerTeloKeywords(instance);
+  // rejected statically and at dispatch by the identical rule. This instance is
+  // static analysis alone, so it also asserts a `live` type: no literal can be one.
+  registerTeloKeywords(instance, { assertLive: true });
   instance.addSchema(ManifestRootSchema);
   return instance;
 }
@@ -508,6 +510,18 @@ function foldedConstraints(schema: Record<string, any>): Record<string, any> {
   return out;
 }
 
+/** The stand-in for a CEL leaf at a `live` slot. Static analysis asserts a live
+ *  type like any instance type (a literal can never be one), so the leaf's
+ *  stand-in has to BE one. A live binding declares no factory, and building an
+ *  instance would mean knowing its constructor's signature; an object on the
+ *  constructor's prototype satisfies `instanceof` and is never used as one. */
+function liveValuePlaceholder(schema: Record<string, any>): unknown | undefined {
+  const entry = readValueTypeSlot(schema)?.entry;
+  if (!entry?.live || entry.representation !== "instance") return undefined;
+  const binding = VALUE_TYPE_BINDINGS[entry.binding!];
+  return binding ? Object.create(binding.constructor.prototype) : undefined;
+}
+
 export function celPlaceholderForSchema(rawSchema: Record<string, any>): unknown {
   const schema = foldedConstraints(rawSchema);
   // An instance-typed slot's placeholder must BE an instance: the same keyword
@@ -516,8 +530,8 @@ export function celPlaceholderForSchema(rawSchema: Record<string, any>): unknown
   // rejected because no YAML literal is a byte buffer, while a value arriving by
   // reference passes. The stand-in comes from the binding table, so a new
   // instance type brings its own rather than adding a branch here; a `live` type
-  // declares none, because nothing validates it.
-  const placeholder = valueTypePlaceholder(schema);
+  // declares none, because nothing validates it at dispatch.
+  const placeholder = valueTypePlaceholder(schema) ?? liveValuePlaceholder(schema);
   if (placeholder !== undefined) return placeholder;
   if (schema.default !== undefined) return schema.default;
   // An enum-constrained field needs a placeholder drawn from the enum: the

package/src/schema-walk.ts

@@ -9,8 +9,9 @@
  * scope rule is consumed by the IDE, which must not pull the pass in behind it.
  */
 import { MANIFEST_SCHEMA_URI, ManifestRootSchema } from "./manifest-schemas.js";
-import { readRefSlot, type RefSlot } from "./ref-slot.js";
-import { readStepSlot, type StepSlot } from "./step-slot.js";
+import type { RefSlot } from "./ref-slot.js";
+import type { StepSlot } from "./step-slot.js";
+import { buildDrivenSlotMap, refSlotOfEntry, type DrivenSlots } from "./reference-field-map.js";
 
 /** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
  *  Non-refs and unresolved refs pass through unchanged. */
@@ -144,57 +145,184 @@ export function walkStepArray(
     }
   });
 }
-/** A slot through which a resource drives another. */
+/** A slot a kind's schema declares through which its resources drive another.
+ *  `path` is the field-map form (`routes[].handler`, `content.{}.encoder`);
+ *  `slots` holds every slot any branch declares there. */
+export type DeclaredSlot =
+  | { kind: "step"; slots: StepSlot[]; path: string }
+  | { kind: "ref"; slots: RefSlot[]; path: string };
+
+/** A reference slot at a site, with the declaration it came from — which is
+ *  what a case-map selector's schema default is read against. */
+export interface DrivenRef {
+  slot: RefSlot;
+  fieldPath: string;
+}
+
+/** The slots at one concrete site of one resource (`routes[0].handler`): every
+ *  slot any branch or recursion route declares there. A consumer reads them as
+ *  a union — a branch that does not apply to this resource can only add what
+ *  counts, never remove it. */
 export type DrivenSlot =
-  | { kind: "step"; slot: StepSlot; data: unknown[]; path: string }
-  | { kind: "ref"; slot: RefSlot; data: unknown; path: string };
+  | { kind: "step"; slots: StepSlot[]; data: unknown[]; path: string }
+  | { kind: "ref"; slots: DrivenRef[]; data: unknown; path: string };
+
+/**
+ * Every slot a kind's schema declares through which its resources drive
+ * another — the schema-only mode of {@link forEachDrivenSlot}, read off the
+ * same {@link buildDrivenSlotMap}.
+ */
+export function forEachDeclaredSlot(schema: unknown, visit: (slot: DeclaredSlot) => void): void {
+  if (!schema || typeof schema !== "object") return;
+  for (const [path, at] of buildDrivenSlotMap(schema as Record<string, any>).paths) {
+    if (at.steps.length > 0) visit({ kind: "step", slots: at.steps, path });
+    if (at.refs.length > 0) visit({ kind: "ref", slots: at.refs.map(refSlotOfEntry), path });
+  }
+}
 
 /**
  * Every slot of one resource through which it drives another, schema and data in
  * tandem.
  *
- * One traversal with two consumers — the inherited union here, and the catch
- * scope enclosure in `validate-throws-coverage.ts` — because both ask the same
- * structural question and two copies would eventually disagree about where the
- * walk stops. It terminates on the manifest's own depth, and it stops AT a step
- * slot (that traversal owns everything below it, `try`/`catch` subtraction
- * included) and AT a reference slot (a resolved ref is a leaf, `{kind, name}`,
- * with nothing beneath it to visit).
+ * One traversal for every throws question — a kind's `inherit` union, a scope
+ * list's denominator, catch-scope enclosure, and whether `inherit` is legal —
+ * because they ask the same structural question and two copies would eventually
+ * disagree about where the walk stops. The slots are the driven-slot map's, so
+ * the reach is the reference field map's plus local `$ref`; a step slot is a
+ * stop (that traversal owns everything below it, `try`/`catch` subtraction
+ * included) and so is a reference slot (a resolved ref is a leaf).
+ *
+ * Each concrete site is visited once, with every slot that reaches it. A
+ * map-value (`additionalProperties`) slot applies only to keys its schema does
+ * not declare, and never to the resource envelope at the root, as JSON Schema
+ * applies it. A recursive schema's back-edge is followed as deep as the data
+ * goes, guarded against data that aliases one of its own ancestors. A schema
+ * whose map holds no step or reference slot is not walked at all.
  */
 export function forEachDrivenSlot(
   schema: unknown,
   data: unknown,
   visit: (slot: DrivenSlot) => void,
-  path = "",
 ): void {
   if (!schema || typeof schema !== "object" || data === undefined || data === null) return;
-  const node = schema as Record<string, any>;
-
-  const stepSlot = readStepSlot(node);
-  if (stepSlot) {
-    if (Array.isArray(data)) visit({ kind: "step", slot: stepSlot, data, path });
-    return;
-  }
+  const driven = buildDrivenSlotMap(schema as Record<string, any>);
+  if (!driven.drives) return;
+  const sites = new Map<
+    string,
+    { data: unknown; steps: StepSlot[]; refs: DrivenRef[]; from: Set<object> }
+  >();
+  const onData = new Set<unknown>([data]);
 
-  const refSlot = readRefSlot(node);
-  if (refSlot) {
-    visit({ kind: "ref", slot: refSlot, data, path });
-    return;
-  }
+  const walk = (prefix: string, value: unknown, base: string): void => {
+    for (const [fieldPath, at] of driven.paths) {
+      const rel = relativeFieldPath(fieldPath, prefix);
+      if (rel === undefined) continue;
+      for (const found of resolveSites(value, rel, prefix, driven)) {
+        const path = joinConcrete(base, found.path);
+        if (at.steps.length > 0 || at.refs.length > 0) {
+          let site = sites.get(path);
+          if (!site) {
+            site = { data: found.value, steps: [], refs: [], from: new Set() };
+            sites.set(path, site);
+          }
+          for (const step of at.steps) {
+            if (site.from.has(step)) continue;
+            site.from.add(step);
+            site.steps.push(step);
+          }
+          for (const entry of at.refs) {
+            if (site.from.has(entry)) continue;
+            site.from.add(entry);
+            site.refs.push({ slot: refSlotOfEntry(entry), fieldPath });
+          }
+        }
+        if (at.recurse.length === 0) continue;
+        if (!found.value || typeof found.value !== "object" || onData.has(found.value)) continue;
+        onData.add(found.value);
+        for (const to of at.recurse) walk(to, found.value, path);
+        onData.delete(found.value);
+      }
+    }
+  };
+  walk("", data, "");
 
-  const props = node.properties as Record<string, any> | undefined;
-  if (props && typeof data === "object" && !Array.isArray(data)) {
-    const obj = data as Record<string, unknown>;
-    for (const [key, propSchema] of Object.entries(props)) {
-      if (obj[key] === undefined) continue;
-      forEachDrivenSlot(propSchema, obj[key], visit, path ? `${path}.${key}` : key);
+  for (const [path, site] of sites) {
+    if (site.steps.length > 0 && Array.isArray(site.data)) {
+      visit({ kind: "step", slots: site.steps, data: site.data, path });
+    } else if (site.refs.length > 0) {
+      visit({ kind: "ref", slots: site.refs, data: site.data, path });
     }
   }
+}
+
+interface Site {
+  value: unknown;
+  path: string;
+}
 
-  if (node.items && Array.isArray(data)) {
-    for (const [i, item] of data.entries()) {
-      forEachDrivenSlot(node.items, item, visit, `${path}[${i}]`);
+/** The values at `rel` below `value`, where `rel` is relative to the field path
+ *  `prefix`. A `{}` segment skips the keys the driven map records as declared
+ *  for that map path; each `[]` iterates one array level. */
+function resolveSites(value: unknown, rel: string, prefix: string, driven: DrivenSlots): Site[] {
+  let sites: Site[] = [{ value, path: "" }];
+  let field = prefix;
+  for (const part of rel.split(".")) {
+    const next: Site[] = [];
+    if (part === "{}") {
+      field = joinKey(field, "{}");
+      const declared = driven.declaredKeys.get(field);
+      for (const site of sites) {
+        if (!site.value || typeof site.value !== "object" || Array.isArray(site.value)) continue;
+        for (const [key, entry] of Object.entries(site.value as Record<string, unknown>)) {
+          if (entry == null || declared?.has(key)) continue;
+          next.push({ value: entry, path: joinKey(site.path, key) });
+        }
+      }
+    } else {
+      const key = part.replace(/(\[\])+$/, "");
+      const depth = (part.length - key.length) / 2;
+      field = key ? joinKey(field, part) : `${field}${part}`;
+      for (const site of sites) {
+        let level: Site[];
+        if (key) {
+          if (!site.value || typeof site.value !== "object") continue;
+          const entry = (site.value as Record<string, unknown>)[key];
+          if (entry == null) continue;
+          level = [{ value: entry, path: joinKey(site.path, key) }];
+        } else {
+          level = [site];
+        }
+        for (let d = 0; d < depth; d++) {
+          const items: Site[] = [];
+          for (const holder of level) {
+            if (!Array.isArray(holder.value)) continue;
+            holder.value.forEach((item, i) => {
+              if (item != null) items.push({ value: item, path: `${holder.path}[${i}]` });
+            });
+          }
+          level = items;
+        }
+        next.push(...level);
+      }
     }
+    sites = next;
   }
+  return sites;
+}
+
+const joinKey = (path: string, key: string): string => (path ? `${path}.${key}` : key);
+
+/** `fieldPath` relative to `prefix`, or undefined when it is not strictly
+ *  below it. A result starting `[]` iterates the value at `prefix` itself. */
+function relativeFieldPath(fieldPath: string, prefix: string): string | undefined {
+  if (prefix === "") return fieldPath;
+  if (fieldPath.startsWith(`${prefix}.`)) return fieldPath.slice(prefix.length + 1);
+  if (fieldPath.startsWith(`${prefix}[]`)) return fieldPath.slice(prefix.length);
+  return undefined;
+}
+
+function joinConcrete(base: string, rel: string): string {
+  if (!base) return rel;
+  return rel.startsWith("[") ? `${base}${rel}` : `${base}.${rel}`;
 }