@telorun/analyzer 0.63.0 → 0.65.0

package/dist/schema-compat.js

@@ -3,6 +3,7 @@ import addFormats from "ajv-formats";
 import { isRefSentinel, isTaggedSentinel, producedTypeOf, } from "@telorun/templating";
 import { celBaseOfValueType, celTypeOfValueType, readValueTypeSlot, valueBrandBases, valueTypeOf, valueTypePlaceholder, } from "@telorun/sdk";
 import { ManifestRootSchema } from "./manifest-schemas.js";
+import { schemaIssues } from "./schema-error-report.js";
 import { registerTeloKeywords } from "./value-type-keyword.js";
 const Ajv = AjvModule.default ?? AjvModule;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
@@ -193,48 +194,7 @@ function compare(rawSource, rawTarget, path, issues, resolveRef, seen) {
         }
     }
 }
-export function formatSingleError(err) {
-    const p = err.instancePath || "/";
-    const params = err.params ?? {};
-    switch (err.keyword) {
-        case "additionalProperties":
-            return `${p} must NOT have additional properties ('${params.additionalProperty}' is not allowed)`;
-        case "required":
-            return `${p} is missing required property '${params.missingProperty}'`;
-        case "enum":
-            return `${p} ${err.message ?? "is invalid"} (${params.allowedValues?.join(" | ")})`;
-        case "type":
-            return `${p} must be ${params.type} (got ${typeof err.data})`;
-        default:
-            return `${p} ${err.message ?? "is invalid"}`;
-    }
-}
-export function formatAjvErrors(errors) {
-    if (!errors || errors.length === 0)
-        return "Unknown schema error";
-    return errors.map(formatSingleError).join("; ");
-}
-/** Converts an AJV error object to a dotted path string compatible with PositionIndex keys.
- *  e.g. instancePath "/config/routes/0/handler" → "config.routes[0].handler"
- *  For "required" keyword errors, appends the missing property to the parent path. */
-function ajvErrorToPath(err) {
-    const instancePath = (err.instancePath ?? "");
-    const parts = instancePath.split("/").filter((p) => p !== "");
-    let result = "";
-    for (const part of parts) {
-        if (/^\d+$/.test(part)) {
-            result += `[${part}]`;
-        }
-        else {
-            result += result ? `.${part}` : part;
-        }
-    }
-    if (err.keyword === "required" && err.params?.missingProperty) {
-        const missing = err.params.missingProperty;
-        result += result ? `.${missing}` : missing;
-    }
-    return result;
-}
+export { formatAjvErrors, formatSingleError } from "./schema-error-report.js";
 /** Does `schema` compile as-authored? Used to tell a malformed module schema
  *  (the author's problem) apart from a fault we introduced while normalizing it. */
 function schemaCompiles(schema) {
@@ -268,10 +228,7 @@ export function validateAgainstSchema(data, schema) {
     }
     if (validate(data))
         return [];
-    return (validate.errors ?? []).map((err) => ({
-        message: formatSingleError(err),
-        path: ajvErrorToPath(err),
-    }));
+    return schemaIssues(validate.errors);
 }
 /** Resolves a JSON Pointer (RFC 6901, must start with "/") into a schema object.
  *  Returns undefined when any segment along the path is missing or not an object. */
@@ -590,15 +547,43 @@ function objectPlaceholder(schema) {
     return out;
 }
 const CEL_PURE_RE = /^\s*\$\{\{[^}]*\}\}\s*$/;
-/** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
-export function resolveRef(schema, root) {
-    if (schema.$ref && typeof schema.$ref === "string" && schema.$ref.startsWith("#/$defs/")) {
-        const defName = schema.$ref.slice("#/$defs/".length);
-        const resolved = root.$defs?.[defName];
-        if (resolved)
-            return resolved;
-    }
-    return schema;
+/**
+ * Resolve a `$ref` — the document-local `#/$defs/...` form against `root`, and
+ * anything else through `external` when a caller supplies one.
+ *
+ * A named shape is addressed by a registered id (`telo:<module>/<Type>`), which
+ * lives in a schema store rather than in this document, so without the hook a
+ * walk stops at the reference and treats a described value as undescribed:
+ * every CEL leaf under it is handed the schema-unaware `""` placeholder and
+ * then rejected against a branch it was never measured against. The caller
+ * supplies the store because only the caller has one.
+ */
+export function resolveRef(schema, root, external) {
+    return resolveRefIn(schema, root, external).schema;
+}
+/**
+ * {@link resolveRef}, reporting the ROOT the result's own `#/...` references
+ * resolve against.
+ *
+ * Following an external reference enters another document, and a `$ref` inside
+ * it is relative to THAT document — which is the whole of how a shape declares
+ * its own vocabulary (`anyOf: [{$ref: "#/$defs/Text"}, …]`). Resolving those
+ * against the referring document finds nothing, and a walker that then treats
+ * the branches as unconstrained accepts every one of them, resolves the union
+ * to nothing, and hands the values underneath an untyped stand-in. So the base
+ * travels with the schema.
+ */
+export function resolveRefIn(schema, root, external) {
+    if (!schema.$ref || typeof schema.$ref !== "string")
+        return { schema, root };
+    if (schema.$ref === "#")
+        return { schema: root, root };
+    if (schema.$ref.startsWith("#/$defs/")) {
+        const resolved = root.$defs?.[schema.$ref.slice("#/$defs/".length)];
+        return resolved ? { schema: resolved, root } : { schema, root };
+    }
+    const target = external?.(schema.$ref);
+    return target ? { schema: target, root: target } : { schema, root };
 }
 /** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
 /**
@@ -617,7 +602,7 @@ export function resolveRef(schema, root) {
  * — an ambiguous union is one the analyzer should not resolve on the author's
  * behalf.
  */
-export function selectUnionBranch(schema, data, root) {
+export function selectUnionBranch(schema, data, root, external) {
     const branches = (schema.oneOf ?? schema.anyOf);
     if (!Array.isArray(branches) || branches.length === 0)
         return schema;
@@ -639,7 +624,7 @@ export function selectUnionBranch(schema, data, root) {
     if (!kind)
         return schema;
     const fits = branches
-        .map((b) => resolveRef(b, root))
+        .map((b) => resolveRef(b, root, external))
         .filter((b) => {
         const types = Array.isArray(b.type) ? b.type : b.type ? [b.type] : [];
         if (types.length > 0 && !types.includes(kind))
@@ -680,21 +665,13 @@ export function collectProperties(schema) {
     }
     return props;
 }
-/** Deep-clone `data`, replacing every pure CEL template string (`${{ expr }}`) with a
- *  schema-appropriate placeholder so AJV can validate non-CEL fields without false positives. */
-export function substituteCelFields(data, schema, rootSchema, 
-/** Called with the dotted path of every value replaced by a placeholder.
- *
- *  A placeholder is a stand-in for something only known at runtime, so its
- *  VALUE says nothing: a caller that judges constraints at these paths reports
- *  against a value no author wrote. Some constraints cannot be satisfied by
- *  construction at all (`pattern`, `format`, a `oneOf` of unrelated shapes),
- *  so making every placeholder acceptable is not achievable in general —
- *  knowing where not to look is. Structural findings survive because they are
- *  located at the CONTAINER, not at the substituted leaf. */
-onSubstitute, path = "") {
-    const root = rootSchema ?? schema;
-    const resolved = selectUnionBranch(resolveRef(schema, root), data, root);
+export function substituteCelFields(data, schema, rootSchema, options = {}) {
+    const { onSubstitute, external } = options;
+    const path = options.path ?? "";
+    const base = rootSchema ?? schema;
+    const entered = resolveRefIn(schema, base, external);
+    const root = entered.root;
+    const resolved = selectUnionBranch(entered.schema, data, root, external);
     const mark = () => onSubstitute?.(path);
     if (typeof data === "string" && CEL_PURE_RE.test(data)) {
         mark();
@@ -733,8 +710,12 @@ onSubstitute, path = "") {
         return celPlaceholderForSchema(resolved);
     }
     if (Array.isArray(data)) {
-        const itemSchema = resolveRef((resolved.items ?? {}), root);
-        return data.map((item, i) => substituteCelFields(item, itemSchema, root, onSubstitute, `${path}[${i}]`));
+        const item = resolveRefIn((resolved.items ?? {}), root, external);
+        return data.map((element, i) => substituteCelFields(element, item.schema, item.root, {
+            onSubstitute,
+            path: `${path}[${i}]`,
+            external,
+        }));
     }
     if (data !== null && typeof data === "object") {
         const props = collectProperties(resolved);
@@ -743,7 +724,11 @@ onSubstitute, path = "") {
             : undefined;
         const result = {};
         for (const [k, v] of Object.entries(data)) {
-            result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}), root, onSubstitute, path ? `${path}.${k}` : k);
+            result[k] = substituteCelFields(v, (props[k] ?? addlProps ?? {}), root, {
+                onSubstitute,
+                path: path ? `${path}.${k}` : k,
+                external,
+            });
         }
         return result;
     }

package/dist/schema-error-report.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The one renderer for AJV validation failures.
+ *
+ * Browser-safe and re-imported by the kernel — the split `buildEvalPaths` and
+ * the redaction path parser already use — so a failure is phrased identically
+ * under `telo check` and at runtime. Three implementations used to answer this
+ * (the analyzer's keyword prose, the kernel's raw `instancePath + message`
+ * join, and observed state's own inline variant), so a developer who fixed what
+ * the analyzer told them met a different sentence describing the same thing.
+ *
+ * UNION REDUCTION is the second half. A union must attempt every branch, and
+ * AJV cannot know which one was intended — `discriminator: true` works only
+ * against an explicit OpenAPI-style discriminator property, which would mean
+ * changing what every module's authors write. So branch selection is a
+ * reporting concern and lives here.
+ *
+ * It narrows the error SET, never just the sentence: every consumer maps the
+ * surviving errors to manifest paths to anchor a diagnostic, so reducing at the
+ * prose layer alone would move the soup out of the message and into the
+ * problems list, one entry per branch on a different line.
+ *
+ * Selection is made from the ERRORS ALONE, never from the schema. A branch
+ * whose discriminating key is present emits no complaint at the union's own
+ * instancePath; one whose key is absent says `required`, and one that forbids a
+ * key the value carries says `additionalProperties`. That is the whole signal,
+ * and reading it off the errors is what lets reduction work across a `$ref`
+ * into another registered schema, where navigating to the branch subschema
+ * would mean re-implementing AJV's resolution.
+ */
+/** An AJV error object. Structurally typed — the analyzer and the kernel hand
+ *  over errors from their own AJV instances. */
+export interface AjvErrorLike {
+    keyword?: string;
+    instancePath?: string;
+    schemaPath?: string;
+    message?: string;
+    params?: Record<string, any>;
+    data?: unknown;
+}
+/** A schema validation issue with a dotted-path pointer to the offending field. */
+export interface SchemaIssue {
+    message: string;
+    /** Dotted path to the field (e.g. "config.handler"). Empty string means root. */
+    path: string;
+}
+export declare function formatSingleError(err: AjvErrorLike): string;
+/**
+ * Replace each failing union with the errors of the branch the author plainly
+ * meant, recursively, outside in.
+ *
+ * Attribution runs to the DEEPEST occurrence that could own an error, which is
+ * what keeps a container's own complaint apart from its child's when both carry
+ * the same `schemaPath`. An occurrence reached through a branch becomes a
+ * candidate branch of its own — it raised nothing at the parent's node, so it is
+ * plausible exactly when the value really did take that shape and fail further
+ * in, and reducing it recursively is what stops an inner union's alternatives
+ * from surviving inside the outer one's selection.
+ */
+export declare function reduceSchemaErrors(errors: AjvErrorLike[] | null | undefined): AjvErrorLike[];
+/** Converts an AJV error to a dotted path compatible with PositionIndex keys.
+ *  e.g. instancePath "/config/routes/0/handler" → "config.routes[0].handler"
+ *  For "required" keyword errors, appends the missing property to the parent path. */
+export declare function ajvErrorToPath(err: AjvErrorLike): string;
+/** Reduced, path-anchored issues — what a diagnostic list is built from. */
+export declare function schemaIssues(errors: AjvErrorLike[] | null | undefined): SchemaIssue[];
+/** Reduced, rendered as one sentence — what a thrown runtime error carries. */
+export declare function formatAjvErrors(errors: AjvErrorLike[] | null | undefined): string;
+//# sourceMappingURL=schema-error-report.d.ts.map

package/dist/schema-error-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-error-report.d.ts","sourceRoot":"","sources":["../src/schema-error-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;gDACgD;AAChD,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;CACd;AAWD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAe3D;AAkGD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,EAAE,CAsF5F;AAqHD;;sFAEsF;AACtF,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAaxD;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,EAAE,CAKrF;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAIjF"}

package/dist/schema-error-report.js

@@ -0,0 +1,356 @@
+/**
+ * The one renderer for AJV validation failures.
+ *
+ * Browser-safe and re-imported by the kernel — the split `buildEvalPaths` and
+ * the redaction path parser already use — so a failure is phrased identically
+ * under `telo check` and at runtime. Three implementations used to answer this
+ * (the analyzer's keyword prose, the kernel's raw `instancePath + message`
+ * join, and observed state's own inline variant), so a developer who fixed what
+ * the analyzer told them met a different sentence describing the same thing.
+ *
+ * UNION REDUCTION is the second half. A union must attempt every branch, and
+ * AJV cannot know which one was intended — `discriminator: true` works only
+ * against an explicit OpenAPI-style discriminator property, which would mean
+ * changing what every module's authors write. So branch selection is a
+ * reporting concern and lives here.
+ *
+ * It narrows the error SET, never just the sentence: every consumer maps the
+ * surviving errors to manifest paths to anchor a diagnostic, so reducing at the
+ * prose layer alone would move the soup out of the message and into the
+ * problems list, one entry per branch on a different line.
+ *
+ * Selection is made from the ERRORS ALONE, never from the schema. A branch
+ * whose discriminating key is present emits no complaint at the union's own
+ * instancePath; one whose key is absent says `required`, and one that forbids a
+ * key the value carries says `additionalProperties`. That is the whole signal,
+ * and reading it off the errors is what lets reduction work across a `$ref`
+ * into another registered schema, where navigating to the branch subschema
+ * would mean re-implementing AJV's resolution.
+ */
+const UNION_KEYWORDS = new Set(["anyOf", "oneOf"]);
+/** Keywords a branch raises at the union's OWN instancePath when the value is
+ *  not of that branch's shape at all — as opposed to being that shape and wrong
+ *  further in. These are what make a branch implausible. */
+const SHAPE_KEYWORDS = new Set(["required", "type", "additionalProperties", "enum", "const"]);
+/* ------------------------------------------------------------------ prose */
+export function formatSingleError(err) {
+    const p = err.instancePath || "/";
+    const params = err.params ?? {};
+    switch (err.keyword) {
+        case "additionalProperties":
+            return `${p} must NOT have additional properties ('${params.additionalProperty}' is not allowed)`;
+        case "required":
+            return `${p} is missing required property '${params.missingProperty}'`;
+        case "enum":
+            return `${p} ${err.message ?? "is invalid"} (${params.allowedValues?.join(" | ")})`;
+        case "type":
+            return `${p} must be ${params.type}${describeActual(err)}`;
+        default:
+            return `${p} ${err.message ?? "is invalid"}`;
+    }
+}
+/** ` (got string)`, or nothing when the value is not in hand. AJV carries
+ *  `data` only under `verbose`, and a reducer that navigated the root value
+ *  would have to be given it at every call site; an absent actual type is worth
+ *  less than a wrong one. */
+function describeActual(err) {
+    if (!("data" in err))
+        return "";
+    const d = err.data;
+    if (d === null)
+        return " (got null)";
+    if (Array.isArray(d))
+        return " (got array)";
+    return ` (got ${typeof d})`;
+}
+/* -------------------------------------------------------------- reduction */
+/** The branch index a `schemaPath` sits under, for a union whose own schemaPath
+ *  is `unionPath` (`…/anyOf`): a child is `…/anyOf/<i>/…` and nothing else can
+ *  collide with it. */
+function branchIndexUnder(unionPath, schemaPath) {
+    if (!schemaPath || !schemaPath.startsWith(unionPath + "/"))
+        return undefined;
+    const rest = schemaPath.slice(unionPath.length + 1);
+    const slash = rest.indexOf("/");
+    const head = slash === -1 ? rest : rest.slice(0, slash);
+    const index = Number(head);
+    return Number.isInteger(index) ? index : undefined;
+}
+function instanceDepth(path) {
+    if (!path)
+        return 0;
+    return path.split("/").filter((s) => s !== "").length;
+}
+/**
+ * How the alternatives at a union node are described, one phrase each.
+ *
+ * Read off the complaints made at the union's own node, and deliberately ONE
+ * PHRASE PER MISSING KEY rather than one per error group. AJV inlines most
+ * `$ref` branches and reports them all under the same bare `schemaPath`, so
+ * several branches are genuinely indistinguishable in the error set — joining
+ * their keys into a single phrase would read as one alternative demanding all
+ * of them, which is a claim about the schema that is simply false. Listing them
+ * separately under-specifies a branch that requires two keys at once, and each
+ * clause is still a true necessary condition; asserting a conjunction that does
+ * not exist is not.
+ */
+function describeAlternatives(errors, unionInstancePath) {
+    const own = errors.filter((e) => (e.instancePath || "") === unionInstancePath);
+    const phrases = [];
+    for (const e of own) {
+        if (e.keyword === "required")
+            phrases.push(`one with '${e.params?.missingProperty}'`);
+        else if (e.keyword === "type")
+            phrases.push(`a ${e.params?.type}`);
+        else if (e.keyword === "enum") {
+            phrases.push(`one of ${e.params?.allowedValues?.join(" | ")}`);
+        }
+    }
+    return phrases.length > 0 ? phrases : ["another shape"];
+}
+/** Is this branch a plausible reading of the value — does it accept the value's
+ *  shape at the union node itself, and only disagree further in? */
+function isPlausible(errors, unionInstancePath) {
+    return !errors.some((e) => (e.instancePath || "") === unionInstancePath && SHAPE_KEYWORDS.has(e.keyword ?? ""));
+}
+function isUnder(child, parent) {
+    return parent === "" ? child !== "" : child.startsWith(parent + "/");
+}
+/** The value path one level up, or undefined at the root. `""` is the root, so
+ *  a non-empty path with no separator has the root as its parent. */
+function parentPath(path) {
+    if (path === "")
+        return undefined;
+    const cut = path.lastIndexOf("/");
+    return cut <= 0 ? "" : path.slice(0, cut);
+}
+/**
+ * Replace each failing union with the errors of the branch the author plainly
+ * meant, recursively, outside in.
+ *
+ * Attribution runs to the DEEPEST occurrence that could own an error, which is
+ * what keeps a container's own complaint apart from its child's when both carry
+ * the same `schemaPath`. An occurrence reached through a branch becomes a
+ * candidate branch of its own — it raised nothing at the parent's node, so it is
+ * plausible exactly when the value really did take that shape and fail further
+ * in, and reducing it recursively is what stops an inner union's alternatives
+ * from surviving inside the outer one's selection.
+ */
+export function reduceSchemaErrors(errors) {
+    if (!errors || errors.length === 0)
+        return [];
+    const occurrences = errors
+        .filter((e) => UNION_KEYWORDS.has(e.keyword ?? "") && typeof e.schemaPath === "string")
+        .map((e) => ({
+        error: e,
+        schemaPath: e.schemaPath,
+        instancePath: e.instancePath || "",
+        owned: [],
+        children: [],
+    }));
+    if (occurrences.length === 0)
+        return errors;
+    // The VALUE NODE is the claim, not the schemaPath. A branch written as a
+    // `$ref` is reported by AJV under the TARGET's schemaPath — and AJV inlines
+    // some of them, reporting several branches under one identical path — so
+    // nothing in such an error points back at the union that dispatched to it. A
+    // large union is written exactly that way, a branch per `$defs` entry, so
+    // claiming by schemaPath alone would leave the biggest unions unreduced.
+    //
+    // Indexed by instancePath rather than scanned: an error is claimed by the
+    // DEEPEST occurrence enclosing it, which is found by walking that error's own
+    // path upwards — bounded by the path's depth instead of by the number of
+    // unions. The scan this replaced was O(errors × occurrences), and both grow
+    // with nesting depth on a recursive shape, on a path the editor runs per
+    // keystroke.
+    const byPath = new Map();
+    const isOccurrence = new Set();
+    for (const o of occurrences) {
+        isOccurrence.add(o.error);
+        // Several unions can occur at ONE value node (a union inside a union
+        // branch); the first is kept, and the rest nest under it below.
+        if (!byPath.has(o.instancePath))
+            byPath.set(o.instancePath, o);
+    }
+    /** The nearest occurrence at or above `path`, excluding `path` itself when
+     *  `strict` — which is how an occurrence finds its parent rather than itself. */
+    const enclosing = (path, strict) => {
+        let current = strict ? parentPath(path) : path;
+        while (current !== undefined) {
+            const hit = byPath.get(current);
+            if (hit)
+                return hit;
+            current = parentPath(current);
+        }
+        return undefined;
+    };
+    const owner = new Map();
+    for (const err of errors) {
+        if (isOccurrence.has(err))
+            continue;
+        const best = enclosing(err.instancePath || "", false);
+        if (best) {
+            best.owned.push(err);
+            owner.set(err, best);
+        }
+    }
+    // Nest occurrences the same way: an occurrence deeper in the value was reached
+    // through some branch of the nearest one enclosing it.
+    const roots = [];
+    for (const o of occurrences) {
+        const parent = o === byPath.get(o.instancePath)
+            ? enclosing(o.instancePath, true)
+            : byPath.get(o.instancePath);
+        if (parent && parent !== o)
+            parent.children.push(o);
+        else
+            roots.push(o);
+    }
+    const replaced = new Map();
+    for (const root of roots)
+        replaced.set(root.error, resolveOccurrence(root));
+    const out = [];
+    for (const err of errors) {
+        const replacement = replaced.get(err);
+        if (replacement) {
+            out.push(...replacement);
+            continue;
+        }
+        // Everything an occurrence owns is spoken for by whichever branch survived,
+        // and a nested occurrence is carried inside its parent's selection.
+        if (owner.has(err))
+            continue;
+        if (occurrences.some((o) => o.error === err))
+            continue;
+        out.push(err);
+    }
+    return out;
+}
+/** Groups one union's complaints into candidate readings of the value.
+ *
+ *  The branch INDEX is used wherever the error carries it. It does not when the
+ *  branch is a `$ref` — AJV reports under the target's schemaPath — so the
+ *  fallback groups by the VALUE NODE each complaint is about: everything said
+ *  about the union node itself is one candidate (those are the branches that
+ *  rejected the value's shape outright), and each child node complained about is
+ *  its own. That is the same question asked of the data instead of the schema,
+ *  and it is what the ordering below actually reads. */
+function groupCandidates(occurrence) {
+    const byIndex = new Map();
+    const byNode = new Map();
+    for (const err of occurrence.owned) {
+        const index = branchIndexUnder(occurrence.schemaPath, err.schemaPath);
+        const bucket = index === undefined
+            ? mapBucket(byNode, childSegment(err.instancePath || "", occurrence.instancePath))
+            : mapBucket(byIndex, index);
+        bucket.push(err);
+    }
+    return [...byIndex]
+        .map(([index, errs]) => ({ index, errors: errs, nested: false }))
+        .concat([...byNode].map(([, errs]) => ({ index: Number.MAX_SAFE_INTEGER, errors: errs, nested: false })))
+        .concat(occurrence.children.map((child) => ({
+        index: Number.POSITIVE_INFINITY,
+        errors: resolveOccurrence(child),
+        nested: true,
+    })));
+}
+function mapBucket(map, key) {
+    const existing = map.get(key);
+    if (existing)
+        return existing;
+    const created = [];
+    map.set(key, created);
+    return created;
+}
+/** The first value-path segment below `parent`, or "" for the node itself. */
+function childSegment(instancePath, parent) {
+    if (!isUnder(instancePath, parent))
+        return "";
+    const rest = instancePath.slice(parent.length + 1);
+    const slash = rest.indexOf("/");
+    return slash === -1 ? rest : rest.slice(0, slash);
+}
+function resolveOccurrence(occurrence) {
+    const candidates = groupCandidates(occurrence);
+    // `oneOf` matching SEVERAL branches emits the union error with no branch
+    // errors at all — nothing was rejected, so there is no branch to select.
+    if (candidates.length === 0)
+        return [occurrence.error];
+    const plausible = candidates.filter((c) => c.nested || isPlausible(c.errors, occurrence.instancePath));
+    if (plausible.length === 0) {
+        return [alternativesError(candidates, occurrence)];
+    }
+    // Deepest agreement first — a branch that matched further into the value is
+    // the one the author was writing — then the fewest complaints, then the
+    // declaration order, so the choice is stable.
+    plausible.sort((a, b) => {
+        const depth = maxDepth(b.errors) - maxDepth(a.errors);
+        if (depth !== 0)
+            return depth;
+        if (a.errors.length !== b.errors.length)
+            return a.errors.length - b.errors.length;
+        return a.index - b.index;
+    });
+    const winner = plausible[0];
+    return winner.nested ? winner.errors : reduceSchemaErrors(winner.errors);
+}
+function maxDepth(errors) {
+    let max = 0;
+    for (const e of errors)
+        max = Math.max(max, instanceDepth(e.instancePath));
+    return max;
+}
+/** One error anchored at the union node, listing what could have gone there.
+ *  The honest fallback: a confident wrong message is worse than the
+ *  concatenation this replaces, so when no branch is a plausible reading the
+ *  reader is told what the alternatives are rather than shown one branch's
+ *  complaints as if it were the intended one. */
+function alternativesError(candidates, occurrence) {
+    const seen = new Set();
+    const described = [];
+    for (const text of describeAlternatives(candidates.flatMap((c) => c.errors), occurrence.instancePath)) {
+        if (seen.has(text))
+            continue;
+        seen.add(text);
+        described.push(text);
+    }
+    return {
+        ...occurrence.error,
+        instancePath: occurrence.instancePath,
+        message: `matches no alternative — expected ${described.join(", or ")}`,
+    };
+}
+/* --------------------------------------------------------------- rendering */
+/** Converts an AJV error to a dotted path compatible with PositionIndex keys.
+ *  e.g. instancePath "/config/routes/0/handler" → "config.routes[0].handler"
+ *  For "required" keyword errors, appends the missing property to the parent path. */
+export function ajvErrorToPath(err) {
+    const instancePath = err.instancePath ?? "";
+    const parts = instancePath.split("/").filter((p) => p !== "");
+    let result = "";
+    for (const part of parts) {
+        if (/^\d+$/.test(part))
+            result += `[${part}]`;
+        else
+            result += result ? `.${part}` : part;
+    }
+    if (err.keyword === "required" && err.params?.missingProperty) {
+        const missing = err.params.missingProperty;
+        result += result ? `.${missing}` : missing;
+    }
+    return result;
+}
+/** Reduced, path-anchored issues — what a diagnostic list is built from. */
+export function schemaIssues(errors) {
+    return reduceSchemaErrors(errors).map((err) => ({
+        message: formatSingleError(err),
+        path: ajvErrorToPath(err),
+    }));
+}
+/** Reduced, rendered as one sentence — what a thrown runtime error carries. */
+export function formatAjvErrors(errors) {
+    const reduced = reduceSchemaErrors(errors);
+    if (reduced.length === 0)
+        return "Unknown schema error";
+    return reduced.map(formatSingleError).join("; ");
+}

package/dist/schema-walk.d.ts

@@ -0,0 +1,25 @@
+/** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
+ *  Non-refs and unresolved refs pass through unchanged. */
+export declare function resolveLocalRef(schema: Record<string, any> | undefined, root: Record<string, any>): Record<string, any> | undefined;
+/** Gather property schemas from a (possibly variant-bearing) object schema:
+ *  top-level `properties` plus every `oneOf` / `anyOf` / `allOf` branch.
+ *
+ *  Each branch is resolved through {@link resolveLocalRef} first, so a branch
+ *  that points at a shared shape — a `oneOf` arm that IS the kernel's dispatch
+ *  site — contributes its properties like an inline one. Without that, pointing a
+ *  composer at a shared shape would silently empty every role-driven lookup that
+ *  reads this (the inputs slot, the retry policy, the eval paths), which is a
+ *  failure with no diagnostic attached to it. */
+export declare function gatherPropertySchemas(schema: Record<string, any>, root?: Record<string, any>): Array<[string, Record<string, any>]>;
+/**
+ * Generic, role-driven walk over a step array. Calls
+ * `visit(step, stepPath)` for every step — top-level and nested through the
+ * `x-telo-topology-role` forms (`branch`, `branch-list`, `case-map`). This is
+ * the single definition of how steps nest, shared by `buildStepContextSchema`
+ * (which types `steps.<name>.result`) and `validateStepInvokeReferences` (which
+ * checks invoke refs), so the topology contract lives in one place — adding a
+ * role or nesting form updates both consumers at once. No resource kind is
+ * hardcoded; recursion is driven entirely by the schema annotations.
+ */
+export declare function walkStepArray(steps: unknown[], stepItemSchema: Record<string, any> | undefined, rootSchema: Record<string, any>, basePath: string, visit: (step: Record<string, any>, stepPath: string) => void): void;
+//# sourceMappingURL=schema-walk.d.ts.map

package/dist/schema-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-walk.d.ts","sourceRoot":"","sources":["../src/schema-walk.ts"],"names":[],"mappings":"AAYA;2DAC2D;AAC3D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACxB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAqBjC;AAID;;;;;;;;iDAQiD;AACjD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACzB,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAsBtC;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EAAE,EAChB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAC/C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,GAC3D,IAAI,CAiDN"}