@telorun/analyzer 0.64.0 → 0.66.0

package/src/validate-references.ts

@@ -1,7 +1,13 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { isRefSentinel } from "@telorun/templating";
 import { visitManifest } from "./manifest-visitor.js";
-import { isInlineResource, resolveFieldEntries, resolveFieldValues, type RefFieldEntry } from "./reference-field-map.js";
+import {
+  isInlineResource,
+  resolveFieldEntries,
+  resolveFieldValues,
+  satisfiesValueBranch,
+  type RefFieldEntry,
+} from "./reference-field-map.js";
 import { navigateJsonPointer, substituteCelFields } from "./schema-compat.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
@@ -101,7 +107,7 @@ export function validateReferences(
   // Group manifests by name to detect collisions. Two subtleties:
   //
   //   1. Some analyzer hosts emit the SAME physical document twice through
-  //      their pipeline — e.g. the telo-editor's `toAnalysisManifests` walks
+  //      their pipeline — e.g. telo studio's `toAnalysisManifests` walks
   //      each workspace module's documents independently, and a file
   //      reachable from two angles (entry module + `include:` partial)
   //      shows up twice. The fingerprint includes `sourceLine` so identical
@@ -293,6 +299,13 @@ export function validateReferences(
         if (typeof val !== "object") return;
         const refVal = val as Record<string, unknown>;
 
+        // A value the slot's own union describes is a value, not a reference —
+        // the same narrowing `validateReferenceForms` applies, through the same
+        // function, because it has to be applied here too: an OBJECT-shaped value
+        // branch would otherwise reach the structural check below and be reported
+        // as a reference missing 'kind' and 'name'.
+        if (satisfiesValueBranch(val, entry.valueBranches, registry)) return;
+
         // Skip inline resources — Phase 2 normalization hasn't run yet.
         if (isInlineResource(refVal)) return;
 

package/src/validate-referrer-rules.ts

@@ -29,8 +29,22 @@ import {
   readReferrerRules,
   type ReferrerRule,
 } from "./referrer-rule.js";
-import { celSourceOf, findDynamicLeaf, readNodes } from "./resource-rule.js";
-import { RULE_BUDGET_MS, compileRuleCondition, conditionRefusals } from "./rule-condition.js";
+import type { PeerBinder, PeerBindingFailure, PeersTarget } from "./peer-binding.js";
+import {
+  celSourceOf,
+  findDynamicLeaf,
+  type DynamicLeaf,
+  isTaggedCondition,
+  pointerSegments,
+  pointerToPath,
+  readNodes,
+} from "./resource-rule.js";
+import {
+  RULE_BUDGET_MS,
+  UNTAGGED_CONDITION,
+  compileRuleCondition,
+  conditionRefusals,
+} from "./rule-condition.js";
 
 export interface ReferrerRuleIssue {
   code: "REFERRER_RULE_INVALID";
@@ -51,14 +65,40 @@ export interface Referrer {
 /** One rule's verdict on one referrer. */
 export type ReferrerRuleFinding =
   | { kind: "violation"; rule: ReferrerRule; referrer: Referrer; message: string }
-  | { kind: "skipped"; rule: ReferrerRule; referrer: Referrer; dynamicAt: string }
+  | { kind: "skipped"; rule: ReferrerRule; referrer: Referrer; dynamic: DynamicLeaf }
+  | { kind: "unbound"; rule: ReferrerRule; referrer: Referrer; failure: PeerBindingFailure }
   | { kind: "failed"; rule: ReferrerRule; referrer?: Referrer; reason: string }
   | { kind: "over-budget"; rule: ReferrerRule; referrer: Referrer; elapsedMs: number };
 
+/** What a peer rule needs beyond the referrers themselves: the binder that
+ *  resolves a referrer's collection into declarations. Absent for a host that
+ *  cannot resolve one — a rule declaring `peers:` then reports as unbound rather
+ *  than running with the binding missing, which would evaluate a condition
+ *  against names that are simply not there.
+ *
+ *  ONE binder per analysis, because it caches each referrer's resolved
+ *  collection and both the evaluation and the exercised check ask for it. */
+export interface ReferrerRuleContext {
+  readonly peerBinder?: PeerBinder;
+}
+
 function isObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+/** What a `peers:` pointer names in the referrer kind it is filtered to. Defined
+ *  with the binding vocabulary; re-exported here because this is the surface
+ *  that consumes it. The caller resolves it — only it holds the definition
+ *  registry, and only after every kind is registered, since a rule may name a
+ *  kind declared later in the same file. */
+export type { PeersTarget };
+
+export interface ReferrerRuleDeclarationContext {
+  /** Resolves a rule's `peers:` against its `referrer:` kind. Omit to skip the
+   *  check — the safe direction for a host with no registry. */
+  readonly peersTarget?: (referrerKind: string, pointer: string) => PeersTarget;
+}
+
 /**
  * Report every way a kind's referrer-rule declarations are malformed. Runs on
  * the `Telo.Definition` / `Telo.Abstract` doc, so a defect lands on the line the
@@ -68,7 +108,10 @@ function isObject(value: unknown): value is Record<string, unknown> {
  * declaring module's scope by `resolveSchemaRefKinds`, the only pass holding
  * that scope, and a name resolving to nothing is reported from there.
  */
-export function validateReferrerRuleDeclarations(manifest: ResourceManifest): ReferrerRuleIssue[] {
+export function validateReferrerRuleDeclarations(
+  manifest: ResourceManifest,
+  context: ReferrerRuleDeclarationContext = {},
+): ReferrerRuleIssue[] {
   const own = (manifest as unknown as Record<string, unknown>).schema;
   const raw = readRawReferrerRules(own);
   if (raw === undefined) return [];
@@ -137,6 +180,12 @@ export function validateReferrerRuleDeclarations(manifest: ResourceManifest): Re
       issue(`${at}.severity`, "'severity' must be 'error' or 'warning'.");
     }
 
+    if (condition !== undefined && condition.length > 0 && !isTaggedCondition(entry.condition)) {
+      issue(`${at}.condition`, UNTAGGED_CONDITION);
+    }
+
+    validatePeersDeclaration(entry, at, issue, context);
+
     if (condition) {
       for (const refusal of conditionRefusals(condition)) issue(`${at}.condition`, refusal);
     }
@@ -145,6 +194,59 @@ export function validateReferrerRuleDeclarations(manifest: ResourceManifest): Re
   return issues;
 }
 
+/** The strict half of `peers:` — the binding that lets a rule reach a referrer's
+ *  OTHER entries, which is also the one that fails invisibly: a pointer naming a
+ *  collection nothing in resolves would leave the rule seeing no declaration at
+ *  all, and a check that never sees its subject reads as passing. */
+function validatePeersDeclaration(
+  entry: Record<string, unknown>,
+  at: string,
+  issue: (path: string, message: string) => void,
+  context: ReferrerRuleDeclarationContext,
+): void {
+  const { peers } = entry;
+  if (peers === undefined) return;
+  if (typeof peers !== "string") {
+    issue(
+      `${at}.peers`,
+      "'peers' is a JSON Pointer naming a collection OF THE REFERRER (e.g. /tables), whose " +
+        "other entries bind as 'peers' and whose own entry binds as 'entry'.",
+    );
+    return;
+  }
+  if (pointerSegments(peers) === undefined || peers === "" || peers === "/") {
+    issue(
+      `${at}.peers`,
+      `'peers' must be a JSON Pointer to a collection, e.g. /tables — '${peers}' is not one.`,
+    );
+    return;
+  }
+  if (typeof entry.referrer !== "string" || entry.referrer.length === 0) {
+    issue(
+      `${at}.peers`,
+      "'peers' names a collection of the REFERRER, so the rule must also declare 'referrer:' — " +
+        "without a kind there is nothing to check the pointer against, and a pointer that " +
+        "resolves to nothing disables the rule in silence.",
+    );
+    return;
+  }
+  const target = context.peersTarget?.(entry.referrer, peers);
+  if (target === "absent") {
+    issue(
+      `${at}.peers`,
+      `'${entry.referrer}' declares no collection at '${peers}'. A pointer that resolves to ` +
+        "nothing binds no peers, so the rule would never see a sibling declaration.",
+    );
+  } else if (target === "plain") {
+    issue(
+      `${at}.peers`,
+      `'${peers}' on '${entry.referrer}' holds plain data — nothing in it is a reference, so ` +
+        "no entry resolves to a declaration and the rule would run against values it cannot " +
+        "compare. Name a collection whose items are, or contain, a reference.",
+    );
+  }
+}
+
 /**
  * Run a kind's referrer rules against every resource that references one of its
  * resources.
@@ -154,6 +256,11 @@ export function validateReferrerRuleDeclarations(manifest: ResourceManifest): Re
  * manifest identity, since a name alone is module-scoped — because the condition
  * reads the two manifests and nothing about the site, so a second site could only
  * produce the identical verdict at a different path.
+ *
+ * **A rule declaring `peers:` is the exception, and evaluates once per ENTRY.**
+ * That is a deliberate departure from judge-once rather than an inconsistency: a
+ * rule that binds `entry` is about the entry, so a resource listed twice has two
+ * entries to answer for, and the two sites can genuinely disagree.
  */
 export function evaluateReferrerRules(
   manifest: ResourceManifest,
@@ -163,6 +270,7 @@ export function evaluateReferrerRules(
    *  Liskov-substitutable, so a child of the named kind matches. Supplied by the
    *  caller, which holds the definition registry. */
   kindMatches: (filter: string, kind: string) => boolean,
+  context: ReferrerRuleContext = {},
 ): ReferrerRuleFinding[] {
   const rules = readReferrerRules(definitionSchema);
   if (rules.length === 0) return [];
@@ -171,7 +279,11 @@ export function evaluateReferrerRules(
   const findings: ReferrerRuleFinding[] = [];
 
   for (const rule of rules) {
-    const compiled = compileRuleCondition(rule.condition, ["self", "referrer"]);
+    const perEntry = rule.peers !== undefined;
+    const compiled = compileRuleCondition(
+      rule.condition,
+      perEntry ? ["self", "referrer", "entry", "peers"] : ["self", "referrer"],
+    );
     if ("reason" in compiled) {
       findings.push({ kind: "failed", rule, reason: compiled.reason });
       continue;
@@ -186,29 +298,47 @@ export function evaluateReferrerRules(
     const started = Date.now();
     for (const referrer of referrers) {
       if (rule.referrer !== undefined && !kindMatches(rule.referrer, referrer.kind)) continue;
-      if (seen.has(referrer.manifest)) continue;
-      seen.add(referrer.manifest);
+      if (!perEntry) {
+        if (seen.has(referrer.manifest)) continue;
+        seen.add(referrer.manifest);
+      }
+
+      const scope: Record<string, unknown> = {
+        self,
+        referrer: referrer.manifest as unknown as Record<string, unknown>,
+      };
+      if (perEntry) {
+        const bound = context.peerBinder
+          ? context.peerBinder.bind(referrer.manifest, referrer.kind, rule.peers!, referrer.path)
+          : ({
+              ok: false,
+              failure: { reason: "unknown-shape", at: pointerToPath(rule.peers!) },
+            } as const);
+        if (!bound.ok) {
+          findings.push({ kind: "unbound", rule, referrer, failure: bound.failure });
+          continue;
+        }
+        scope.peers = bound.binding.peers;
+        scope.entry = bound.binding.entry;
+      }
 
       // Only the nodes this condition READS decide whether it can run — the
       // resource-rule reasoning, and it bites harder here: the referrer is a
       // whole manifest, so scanning all of it would disable the rule for any
       // server carrying one unrelated expression.
-      let dynamicAt: string | undefined;
-      for (const node of readNodes(chains, {
-        self,
-        referrer: referrer.manifest as unknown as Record<string, unknown>,
-      })) {
-        dynamicAt = findDynamicLeaf(node);
-        if (dynamicAt !== undefined) break;
+      let dynamic: DynamicLeaf | undefined;
+      for (const node of readNodes(chains, scope)) {
+        dynamic = findDynamicLeaf(node);
+        if (dynamic !== undefined) break;
       }
-      if (dynamicAt !== undefined) {
-        findings.push({ kind: "skipped", rule, referrer, dynamicAt });
+      if (dynamic !== undefined) {
+        findings.push({ kind: "skipped", rule, referrer, dynamic });
         continue;
       }
 
       let held: unknown;
       try {
-        held = parsed({ self, referrer: referrer.manifest });
+        held = parsed(scope);
       } catch (err) {
         findings.push({
           kind: "failed",
@@ -239,10 +369,23 @@ export function referrerRuleExercised(
   rule: ReferrerRule,
   referrers: readonly Referrer[],
   kindMatches: (filter: string, kind: string) => boolean,
+  context: ReferrerRuleContext = {},
 ): boolean {
-  if (rule.referrer === undefined) return referrers.length > 0;
-  const filter = rule.referrer;
-  return referrers.some((referrer) => kindMatches(filter, referrer.kind));
+  const matching =
+    rule.referrer === undefined
+      ? referrers
+      : referrers.filter((referrer) => kindMatches(rule.referrer!, referrer.kind));
+  if (matching.length === 0) return false;
+  if (rule.peers === undefined) return true;
+  // A peer rule that ran against an EMPTY peer set proved nothing — and an empty
+  // set everywhere is exactly what a typo in `peers:` looks like from outside,
+  // which is silence that reads as passing. Asked through the binder, so it
+  // shares the resolution the evaluation already paid for.
+  const binder = context.peerBinder;
+  if (!binder) return false;
+  return matching.some((referrer) =>
+    binder.hasPeers(referrer.manifest, referrer.kind, rule.peers!, referrer.path),
+  );
 }
 
 /** Where a referrer-rule finding is reported, and how loudly. Plain data, so the
@@ -262,6 +405,29 @@ export interface ReferrerRuleDiagnostic {
   rule: string;
 }
 
+/** Why a peer binding could not be produced, as the sentence a reader acts on. */
+function peerBindingReason(failure: PeerBindingFailure): string {
+  switch (failure.reason) {
+    case "no-collection":
+      return `'${failure.at}' holds no collection to bind 'peers' from.`;
+    case "unresolved":
+      return (
+        `a reference at '${failure.at}' names a declaration this analysis does not hold, ` +
+        "so a peer would bind to nothing."
+      );
+    case "dynamic":
+      return (
+        `a value at '${failure.at}' holds ${failure.what ?? "a value"}, which is not known ` +
+        "until the resource is created, so the comparison would run against a placeholder."
+      );
+    case "unknown-shape":
+      return (
+        `which paths under '${failure.at}' hold references is not known here, so nothing ` +
+        "could be resolved into a declaration."
+      );
+  }
+}
+
 const nameOf = (manifest: ResourceManifest): string =>
   (manifest.metadata?.name as string | undefined) ?? "<unnamed>";
 
@@ -305,8 +471,8 @@ export function reportReferrerRules(
         message:
           `${finding.referrer.kind}/${nameOf(finding.referrer.manifest)}: rule ` +
           `'${finding.rule.code}' from ${declaringKind} did not run at ` +
-          `'${finding.referrer.path}' — the value holds a CEL expression at ` +
-          `'${finding.dynamicAt}', which is not known until the resource is created. ` +
+          `'${finding.referrer.path}' — the value holds ${finding.dynamic.what} at ` +
+          `'${finding.dynamic.path}', which is not known until the resource is created. ` +
           "Reported rather than dropped: a check whose coverage varies invisibly reads as passing.",
         manifest: finding.referrer.manifest,
         path: finding.referrer.path,
@@ -314,6 +480,21 @@ export function reportReferrerRules(
       });
       continue;
     }
+    if (finding.kind === "unbound") {
+      out.push({
+        code: "REFERRER_RULE_SKIPPED",
+        severity: "information",
+        message:
+          `${finding.referrer.kind}/${nameOf(finding.referrer.manifest)}: rule ` +
+          `'${finding.rule.code}' from ${declaringKind} did not run at ` +
+          `'${finding.referrer.path}' — ${peerBindingReason(finding.failure)}` +
+          " Reported rather than dropped: a check whose coverage varies invisibly reads as passing.",
+        manifest: finding.referrer.manifest,
+        path: finding.referrer.path,
+        rule: finding.rule.code,
+      });
+      continue;
+    }
 
     const because =
       finding.kind === "failed"
@@ -360,12 +541,18 @@ export function reportUnexercisedReferrerRule(
     code: "REFERRER_RULE_UNEXERCISED",
     severity: "information",
     message:
-      `Referrer rule '${rule.code}' never ran: nothing` +
-      (rule.referrer === undefined ? "" : ` of kind '${rule.referrer}'`) +
-      " references a resource of this kind, so nothing has proven the condition." +
-      (rule.referrer === undefined
-        ? ""
-        : " A 'referrer' naming a kind no manifest uses disables the rule in silence."),
+      rule.peers !== undefined
+        ? `Referrer rule '${rule.code}' never ran with peers to compare: nothing` +
+          (rule.referrer === undefined ? "" : ` of kind '${rule.referrer}'`) +
+          ` references a resource of this kind while '${rule.peers}' held another ` +
+          "declaration, so nothing has proven the condition. An empty peer set " +
+          "everywhere is what a typo in 'peers:' looks like from outside."
+        : `Referrer rule '${rule.code}' never ran: nothing` +
+          (rule.referrer === undefined ? "" : ` of kind '${rule.referrer}'`) +
+          " references a resource of this kind, so nothing has proven the condition." +
+          (rule.referrer === undefined
+            ? ""
+            : " A 'referrer' naming a kind no manifest uses disables the rule in silence."),
     manifest: definition,
     path: `schema.${REFERRER_RULES_ANNOTATION}[${rule.index}]`,
     rule: rule.code,

package/src/validate-resource-rules.ts

@@ -22,11 +22,18 @@
  * Browser-safe: no Node built-ins.
  */
 import type { ResourceManifest } from "@telorun/sdk";
-import { RULE_BUDGET_MS, compileRuleCondition, conditionRefusals } from "./rule-condition.js";
+import {
+  RULE_BUDGET_MS,
+  UNTAGGED_CONDITION,
+  compileRuleCondition,
+  conditionRefusals,
+} from "./rule-condition.js";
 import {
   RESOURCE_RULES_ANNOTATION,
   celSourceOf,
   findDynamicLeaf,
+  type DynamicLeaf,
+  isTaggedCondition,
   pointerSegments,
   readRawResourceRules,
   readResourceRules,
@@ -54,7 +61,7 @@ export type ResourceRuleFinding =
       path: string;
       message: string;
     }
-  | { kind: "skipped"; rule: ResourceRule; path: string; dynamicAt: string }
+  | { kind: "skipped"; rule: ResourceRule; path: string; dynamic: DynamicLeaf }
   | { kind: "failed"; rule: ResourceRule; path: string; reason: string }
   | { kind: "over-budget"; rule: ResourceRule; path: string; elapsedMs: number };
 
@@ -63,8 +70,11 @@ function isObject(value: unknown): value is Record<string, unknown> {
 }
 
 /** Navigate a kind's own schema to the node describing what a pointer names, so
- *  an `in:` naming a field the kind does not declare is caught at the kind. */
-function schemaAtPointer(schema: unknown, pointer: string): unknown {
+ *  an `in:` naming a field the kind does not declare is caught at the kind.
+ *  Exported because the peer-rule strict half asks the same question of the
+ *  REFERRER's schema, and two navigators would eventually disagree about what a
+ *  pointer names. */
+export function schemaAtPointer(schema: unknown, pointer: string): unknown {
   const segments = pointerSegments(pointer);
   if (!segments) return undefined;
   let node: unknown = schema;
@@ -83,7 +93,7 @@ function schemaAtPointer(schema: unknown, pointer: string): unknown {
 
 /** True when a schema node describes something a rule can iterate. Unknown or
  *  absent `type` passes: an open schema is not evidence of a defect. */
-function isIterableSchema(node: unknown): boolean {
+export function isIterableSchema(node: unknown): boolean {
   if (!isObject(node)) return true;
   const type = node.type;
   if (type === undefined) return true;
@@ -198,6 +208,10 @@ export function validateResourceRuleDeclarations(
       }
     }
 
+    if (condition !== undefined && condition.length > 0 && !isTaggedCondition(entry.condition)) {
+      issue(`${at}.condition`, UNTAGGED_CONDITION);
+    }
+
     if (condition) {
       for (const refusal of conditionRefusals(condition)) issue(`${at}.condition`, refusal);
     }
@@ -243,13 +257,13 @@ export function evaluateResourceRules(
       // Only the nodes this condition READS decide whether it can run — see
       // `readNodes`. Scanning the whole subject would disable every
       // resource-wide rule on any manifest containing one unrelated expression.
-      let dynamicAt: string | undefined;
+      let dynamic: DynamicLeaf | undefined;
       for (const node of readNodes(chains, { self, this: subject.value })) {
-        dynamicAt = findDynamicLeaf(node);
-        if (dynamicAt !== undefined) break;
+        dynamic = findDynamicLeaf(node);
+        if (dynamic !== undefined) break;
       }
-      if (dynamicAt !== undefined) {
-        findings.push({ kind: "skipped", rule, path: subject.path, dynamicAt });
+      if (dynamic !== undefined) {
+        findings.push({ kind: "skipped", rule, path: subject.path, dynamic });
         continue;
       }
       let held: unknown;
@@ -347,8 +361,8 @@ export function reportResourceRules(
         severity: "information",
         message:
           `${manifest.kind}/${name}: rule '${finding.rule.code}' did not run` +
-          `${at ? ` at '${at}'` : ""} — the value holds a CEL expression at ` +
-          `'${finding.dynamicAt}', which is not known until the resource is created. ` +
+          `${at ? ` at '${at}'` : ""} — the value holds ${finding.dynamic.what} at ` +
+          `'${finding.dynamic.path}', which is not known until the resource is created. ` +
           "Reported rather than dropped: a check whose coverage varies invisibly reads as passing.",
         manifest,
         path: at,

package/src/validate-schema-projection.ts

@@ -26,6 +26,7 @@ import {
   projectionKeyMap,
   rawSchemaProjection,
   readSchemaProjection,
+  schemaMapBranch,
   schemaProjectionIsMisplaced,
 } from "./schema-projection.js";
 
@@ -118,6 +119,48 @@ export function validateSchemaProjection(manifest: ResourceManifest): SchemaProj
     ];
   }
 
+  const reference = raw.reference;
+  if (reference !== undefined) {
+    if (!isObject(reference)) {
+      issues.push(
+        issue(
+          "SCHEMA_PROJECTION_INVALID",
+          `${base}.reference`,
+          `'reference' says how an entry whose '${projection.key}' holds a REFERENCE projects. ` +
+            `It is an object naming 'from' (the target field to read), 'keyword' (the schema ` +
+            `keyword its values become) and one of 'base' / 'baseFrom'.`,
+        ),
+      );
+    } else {
+      const absent = ["from", "keyword"].filter((f) => typeof reference[f] !== "string");
+      if (absent.length > 0) {
+        issues.push(
+          issue(
+            "SCHEMA_PROJECTION_INVALID",
+            `${base}.reference`,
+            `'reference' is missing ${absent.map((f) => `'${f}'`).join(" and ")}. Without them a ` +
+              `referenced entry projects to nothing, so it vanishes from every consumer's view.`,
+          ),
+        );
+      }
+      const bases = ["base", "baseFrom"].filter((f) => reference[f] !== undefined);
+      if (bases.length !== 1) {
+        issues.push(
+          issue(
+            "SCHEMA_PROJECTION_INVALID",
+            `${base}.reference`,
+            bases.length === 0
+              ? `'reference' declares neither 'base' nor 'baseFrom', so the projected node has no ` +
+                `type. Write 'base' where the named type IS its own base type, or 'baseFrom' ` +
+                `naming the target field that holds a value of this kind's own map.`
+              : `'reference' declares both 'base' and 'baseFrom'. They are two answers to one ` +
+                `question — where the projected node's type comes from — so declare exactly one.`,
+          ),
+        );
+      }
+    }
+  }
+
   const map = projectionKeyMap(schema, projection);
   if (!map) {
     return [
@@ -180,5 +223,11 @@ function keySchema(
       : undefined;
   if (!isObject(entry) || !isObject(entry.properties)) return undefined;
   const field = entry.properties[key];
-  return isObject(field) ? field : undefined;
+  if (!isObject(field)) return undefined;
+  // The vocabulary may sit on a BRANCH — a slot unioning a closed value set with
+  // a reference — and the branch carrying the map is the one whose `enum` the map
+  // has to answer for. Reading the union node instead finds no `enum` at all, so
+  // the completeness check would silently stop running exactly where the two
+  // halves can disagree. Asked through the single reader, never re-derived here.
+  return schemaMapBranch(field) ?? field;
 }

package/src/validate-step-inputs.ts

@@ -248,9 +248,15 @@ function checkCallSite(site: CallSite, ctx: CallCheckContext): StepInputIssue[]
       // findings (missing required, unknown property) are located at the
       // container and survive the filter.
       const celPaths = new Set<string>();
-      const substituted = substituteCelFields(values, contract.schema, undefined, (p) =>
-        celPaths.add(p),
-      );
+      const substituted = substituteCelFields(values, contract.schema, undefined, {
+        onSubstitute: (p) => celPaths.add(p),
+        // A contract may name a shape declared elsewhere. Both halves need the
+        // resolver or they disagree about the same slot: the stand-in walk hands
+        // its expressions a typeless value, and the check below compiles nothing
+        // at all — so a step's arguments went unchecked against exactly the
+        // contracts that describe them most precisely.
+        external: (ref) => defs.schemaForId(ref),
+      });
       // The type-argument check, at the one site where a produced value's schema
       // meets a consuming slot's. A CEL leaf's placeholder says nothing about
       // what the expression yields, so AJV above is silent here by design — and
@@ -328,7 +334,7 @@ function checkCallSite(site: CallSite, ctx: CallCheckContext): StepInputIssue[]
         }
       }
 
-      for (const issue of validateAgainstSchema(substituted, contract.schema)) {
+      for (const issue of defs.validateResourceConfig(substituted, contract.schema)) {
         if (celPaths.has(issue.path)) continue;
         // A missing-required issue names the property that ISN'T there, so
         // anchoring on it finds no node and the diagnostic degrades to 1:1 —

package/src/with-synthetic-positions.ts

@@ -10,7 +10,7 @@ import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
  * manifest (the dedup that backs `DUPLICATE_RESOURCE_NAME` reads
  * `(source, sourceLine)` to distinguish pipeline echoes from real
  * collisions). Production callers — the `Loader`, `flattenForAnalyzer`,
- * the telo-editor's `emitDocsFor`, the VSCode extension — all stamp
+ * telo studio's `emitDocsFor`, the VSCode extension — all stamp
  * positions already. This helper is the escape hatch for **programmatic
  * callers** (tests, ad-hoc scripts) that construct `ResourceManifest`
  * literals without going through a loader: it gives every otherwise-naked