@telorun/analyzer 0.64.0 → 0.66.0

package/dist/resource-rule.d.ts

@@ -1,26 +1,3 @@
-/**
- * The single reader for `x-telo-resource-rules` — a kind declaring, as data,
- * relationships between the fields of one resource that JSON Schema cannot
- * state: an index naming a column its table does not declare, a foreign key
- * whose two sides differ in length, a rename whose source is still declared.
- *
- * The predicate is CEL over `self` (the whole resource) and `this` (the element
- * under test), so correlating two collections is a comprehension closure rather
- * than a path language with wildcard bindings to design. `in:` names the
- * collection to iterate and IS the diagnostic anchor: iterating what the pointer
- * names is what makes a reported path exist by construction.
- *
- * Vocabulary borrowed from `Telo.JsonSchema.rules` — `condition` true when the
- * rule HOLDS, the subject bound as `this`, plus `code` and `message` — because
- * two CEL rule vocabularies with opposite polarity is a trap an author falls
- * into once per rule. The two mechanisms stay separate: a `Telo.JsonSchema` rule
- * runs at dispatch against a value, this one at `telo check` against a manifest.
- *
- * Lenient by design, the `ref-slot.ts` precedent: anything unreadable here reads
- * as absent, and `validate-resource-rules.ts` is the strict half that reports it.
- *
- * Browser-safe: no Node built-ins.
- */
 export declare const RESOURCE_RULES_ANNOTATION = "x-telo-resource-rules";
 export type ResourceRuleSeverity = "error" | "warning";
 export interface ResourceRule {
@@ -45,6 +22,22 @@ export interface RuleSubject {
     /** Present when the collection is a map: the entry's key. */
     readonly key?: string;
 }
+/** The engine of a non-CEL tagged sentinel — a `!ref`, an `!include-*` — or
+ *  `undefined`. A reference is comparable and never blocks a rule; the other
+ *  tags hold a value only known once the resource is created, so they do, and
+ *  the diagnostic has to name the tag rather than claim CEL. */
+export declare function deferredTagOf(value: unknown): string | undefined;
+/**
+ * True when a condition was written with the `!cel` tag.
+ *
+ * The readers stay lenient and take a bare string — a rule still runs either
+ * way. What an untagged condition loses is everything outside evaluation: to the
+ * editor's colouring, completion and hover it is a plain string, so a rule author
+ * writes CEL with no help and gets none of the checks a `!cel` scalar gets.
+ * Losing that silently is exactly what a strict half exists to move earlier, so
+ * the tag is reported by the strict halves and never enforced by the readers.
+ */
+export declare function isTaggedCondition(value: unknown): boolean;
 /** A precompiled `!cel` node keeps its author-written text on `source`; a plain
  *  string is taken verbatim so a rule reads the same however the loader was
  *  configured (a round-trip view runs with `compile` off). */
@@ -73,15 +66,35 @@ export declare function pointerToPath(pointer: string): string;
  * declaration defect the strict half reports, and an empty list would hide it.
  */
 export declare function resolveRuleSubjects(config: unknown, pointer: string): RuleSubject[] | undefined;
+/** The first leaf a rule cannot compare, and what it is. `what` is a noun
+ *  phrase the diagnostic quotes verbatim, because "a CEL expression" printed
+ *  over an `!include-bytes` embed sends its author looking for an expression
+ *  that is not there. */
+export interface DynamicLeaf {
+    readonly path: string;
+    readonly what: string;
+}
+/** Classify ONE node, without descending. Exported because a caller that draws
+ *  its own bound on how far to look (`peer-binding`'s top-level-scalar scan)
+ *  must classify by the same rule as the recursive walk, or a `!ref` is a
+ *  reference to one of them and an expression to the other. */
+export declare function dynamicNode(value: unknown, path: string): DynamicLeaf | undefined;
 /**
- * Path of the first CEL leaf inside a value, or `undefined` when every leaf is
- * literal. A rule reading an expression would be evaluating a placeholder, so
- * the subject is skipped — and the skip is reported, never silent.
+ * The first leaf inside a value whose contents are not known until the resource
+ * is created, or `undefined` when every leaf is literal. A rule reading one
+ * would be comparing against a placeholder, so the subject is skipped — and the
+ * skip is reported, never silent.
+ *
+ * A `!ref` is NOT one of them. It is a tagged sentinel like `!cel`, and testing
+ * `__tagged` alone read every reference as an expression: a column whose `type:`
+ * holds a `!ref` switched off every rule touching `self.columns` and reported a
+ * CEL expression in a manifest containing none. A reference names a declaration
+ * — a value a rule compares perfectly well, and the one peer rules are built on.
  *
  * Stops at nested inline `{ kind }` declarations for the reason every other walk
  * does: that CEL belongs to the nested kind, evaluated in its own scope.
  */
-export declare function findDynamicLeaf(value: unknown, base?: string): string | undefined;
+export declare function findDynamicLeaf(value: unknown, base?: string): DynamicLeaf | undefined;
 /**
  * The nodes a condition actually READS, resolved against the resource and the
  * element under test — the input to the dynamic-leaf check.

package/dist/resource-rule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-rule.d.ts","sourceRoot":"","sources":["../src/resource-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B;yEACqE;IACrE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;qEACiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAeD;;8DAE8D;AAC9D,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI9D;AAED;;6CAE6C;AAC7C,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAG7D;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,EAAE,CA0BjE;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAOrE;AAED;;yEAEyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAiBvE;AAED;+EAC+E;AAC/E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,GACd,WAAW,EAAE,GAAG,SAAS,CAe3B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAK,GAAG,MAAM,GAAG,SAAS,CAiB7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE;AACtC;;2BAE2B;AAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,EAAE,CAqBX"}
+{"version":3,"file":"resource-rule.d.ts","sourceRoot":"","sources":["../src/resource-rule.ts"],"names":[],"mappings":"AAyBA,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B;yEACqE;IACrE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;qEACiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAyBD;;;gEAGgE;AAChE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;8DAE8D;AAC9D,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI9D;AAED;;6CAE6C;AAC7C,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAG7D;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,EAAE,CA0BjE;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAOrE;AAED;;yEAEyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAiBvE;AAED;+EAC+E;AAC/E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,GACd,WAAW,EAAE,GAAG,SAAS,CAe3B;AAED;;;yBAGyB;AACzB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;+DAG+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAKjF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAK,GAAG,WAAW,GAAG,SAAS,CAkBlF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE;AACtC;;2BAE2B;AAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,EAAE,CAqBX"}

package/dist/resource-rule.js

@@ -21,6 +21,7 @@
  *
  * Browser-safe: no Node built-ins.
  */
+import { CEL_ENGINE, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 export const RESOURCE_RULES_ANNOTATION = "x-telo-resource-rules";
 function isObject(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
@@ -29,9 +30,43 @@ function isObject(value) {
  *  Both markers are tested because they are not always both present: a
  *  registered definition's schema reaches the analyzer with `call` and
  *  `__compiled` dropped, keeping only `__tagged` + `source`. Testing one would
- *  make a rule readable on some paths and invisible on others. */
+ *  make a rule readable on some paths and invisible on others.
+ *
+ *  A tagged sentinel of ANOTHER engine is not one. `__tagged` marks every tag
+ *  the loader parses — `!ref` above all — so testing it alone read a reference
+ *  as an expression: a column whose `type:` holds a `!ref` skipped every rule
+ *  that touched `self.columns`, and said "the value holds a CEL expression" about
+ *  a manifest containing none. A reference names a declaration and is a
+ *  perfectly comparable value; what a rule cannot compare is a value COMPUTED at
+ *  create time, which is what this predicate exists to find. */
 function isCelNode(value) {
-    return isObject(value) && (value.__compiled === true || value.__tagged === true);
+    if (!isObject(value))
+        return false;
+    if (value.__compiled === true)
+        return true;
+    return value.__tagged === true && value.engine === CEL_ENGINE;
+}
+/** The engine of a non-CEL tagged sentinel — a `!ref`, an `!include-*` — or
+ *  `undefined`. A reference is comparable and never blocks a rule; the other
+ *  tags hold a value only known once the resource is created, so they do, and
+ *  the diagnostic has to name the tag rather than claim CEL. */
+export function deferredTagOf(value) {
+    if (!isTaggedSentinel(value) || isRefSentinel(value))
+        return undefined;
+    return value.engine === CEL_ENGINE ? undefined : value.engine;
+}
+/**
+ * True when a condition was written with the `!cel` tag.
+ *
+ * The readers stay lenient and take a bare string — a rule still runs either
+ * way. What an untagged condition loses is everything outside evaluation: to the
+ * editor's colouring, completion and hover it is a plain string, so a rule author
+ * writes CEL with no help and gets none of the checks a `!cel` scalar gets.
+ * Losing that silently is exactly what a strict half exists to move earlier, so
+ * the tag is reported by the strict halves and never enforced by the readers.
+ */
+export function isTaggedCondition(value) {
+    return isCelNode(value);
 }
 /** A precompiled `!cel` node keeps its author-written text on `source`; a plain
  *  string is taken verbatim so a rule reads the same however the loader was
@@ -156,18 +191,37 @@ export function resolveRuleSubjects(config, pointer) {
     }
     return undefined;
 }
+/** Classify ONE node, without descending. Exported because a caller that draws
+ *  its own bound on how far to look (`peer-binding`'s top-level-scalar scan)
+ *  must classify by the same rule as the recursive walk, or a `!ref` is a
+ *  reference to one of them and an expression to the other. */
+export function dynamicNode(value, path) {
+    const at = path || "(value)";
+    if (isCelNode(value))
+        return { path: at, what: "a CEL expression" };
+    const tag = deferredTagOf(value);
+    return tag ? { path: at, what: `an !${tag} embed` } : undefined;
+}
 /**
- * Path of the first CEL leaf inside a value, or `undefined` when every leaf is
- * literal. A rule reading an expression would be evaluating a placeholder, so
- * the subject is skipped — and the skip is reported, never silent.
+ * The first leaf inside a value whose contents are not known until the resource
+ * is created, or `undefined` when every leaf is literal. A rule reading one
+ * would be comparing against a placeholder, so the subject is skipped — and the
+ * skip is reported, never silent.
+ *
+ * A `!ref` is NOT one of them. It is a tagged sentinel like `!cel`, and testing
+ * `__tagged` alone read every reference as an expression: a column whose `type:`
+ * holds a `!ref` switched off every rule touching `self.columns` and reported a
+ * CEL expression in a manifest containing none. A reference names a declaration
+ * — a value a rule compares perfectly well, and the one peer rules are built on.
  *
  * Stops at nested inline `{ kind }` declarations for the reason every other walk
  * does: that CEL belongs to the nested kind, evaluated in its own scope.
  */
 export function findDynamicLeaf(value, base = "") {
     if (isObject(value)) {
-        if (isCelNode(value))
-            return base || "(value)";
+        const own = dynamicNode(value, base);
+        if (own)
+            return own;
         if (typeof value.kind === "string" && base !== "")
             return undefined;
         for (const [key, child] of Object.entries(value)) {

package/dist/rule-condition.d.ts

@@ -25,6 +25,17 @@ import { buildCelEnvironment } from "@telorun/templating";
  * as defective rather than truncating coverage silently.
  */
 export declare const RULE_BUDGET_MS = 50;
+/**
+ * The one message for an untagged `condition:`, shared by every rule family so
+ * all of them say the same thing about the same defect.
+ *
+ * The readers stay lenient and a bare string still runs. What it loses is
+ * everything outside evaluation — to the editor's colouring, completion and
+ * hover an untagged condition is a plain string, so its author writes CEL with
+ * no help and none of the checks a `!cel` scalar gets. Losing that silently is
+ * the failure a strict half exists to move earlier.
+ */
+export declare const UNTAGGED_CONDITION: string;
 /** The analyzer's own environment — no host handlers, so every `hostBacked`
  *  entry is a throwing stub. Built once; it is stateless. */
 export declare function ruleEnv(): ReturnType<typeof buildCelEnvironment>;

package/dist/rule-condition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rule-condition.d.ts","sourceRoot":"","sources":["../src/rule-condition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAEL,mBAAmB,EAGpB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAQjC;6DAC6D;AAC7D,wBAAgB,OAAO,IAAI,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAGhE;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;CAAE,GAC7F;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAsBvB,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM;AACjB;wEACwE;AACxE,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,YAAY,CAoBd;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB7D"}
+{"version":3,"file":"rule-condition.d.ts","sourceRoot":"","sources":["../src/rule-condition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAEL,mBAAmB,EAGpB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAGgD,CAAC;AAQhF;6DAC6D;AAC7D,wBAAgB,OAAO,IAAI,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAGhE;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;CAAE,GAC7F;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAsBvB,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM;AACjB;wEACwE;AACxE,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,YAAY,CAoBd;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB7D"}

package/dist/rule-condition.js

@@ -25,6 +25,19 @@ import { CEL_FUNCTIONS, buildCelEnvironment, celEngine, extractAccessChains, } f
  * as defective rather than truncating coverage silently.
  */
 export const RULE_BUDGET_MS = 50;
+/**
+ * The one message for an untagged `condition:`, shared by every rule family so
+ * all of them say the same thing about the same defect.
+ *
+ * The readers stay lenient and a bare string still runs. What it loses is
+ * everything outside evaluation — to the editor's colouring, completion and
+ * hover an untagged condition is a plain string, so its author writes CEL with
+ * no help and none of the checks a `!cel` scalar gets. Losing that silently is
+ * the failure a strict half exists to move earlier.
+ */
+export const UNTAGGED_CONDITION = "Write 'condition' with the !cel tag. The reader is lenient and a bare string still " +
+    "runs, but untagged the expression is not CEL to the editor's colouring, completion " +
+    "or hover, so a rule silently stops being CEL to every surface but this one.";
 const HOST_BACKED = new Set(CEL_FUNCTIONS.filter((f) => f.hostBacked).map((f) => f.name));
 const NON_DETERMINISTIC = new Set(CEL_FUNCTIONS.filter((f) => !f.deterministic).map((f) => f.name));
 let sharedEnv;

package/dist/schema-compat.d.ts

@@ -1,3 +1,4 @@
+import { type SchemaIssue } from "./schema-error-report.js";
 declare const Ajv: any;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).
  *  Also registers the kernel manifest root schema under `telo://manifest` so
@@ -35,14 +36,8 @@ export interface CompatibilityResult {
  * {@link withLiveValuesSkipped} takes one.
  */
 export declare function checkSchemaCompatibility(source: Record<string, any>, target: Record<string, any>, resolveRef?: (ref: string) => Record<string, any> | undefined): CompatibilityResult;
-export declare function formatSingleError(err: any): string;
-export declare function formatAjvErrors(errors: any[] | null | undefined): string;
-/** 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 { formatAjvErrors, formatSingleError } from "./schema-error-report.js";
+export type { SchemaIssue } from "./schema-error-report.js";
 /** Validate actual data against a JSON Schema. Returns issues with path info, or empty array if valid. */
 export declare function validateAgainstSchema(data: unknown, schema: Record<string, any>): SchemaIssue[];
 /** Resolves a JSON Pointer (RFC 6901, must start with "/") into a schema object.
@@ -76,8 +71,36 @@ export declare function jsonSchemaToCelType(schema: Record<string, any> | undefi
 /** Check whether a CEL return type is compatible with a JSON Schema type constraint. */
 export declare function celTypeSatisfiesJsonSchema(celType: string, schema: Record<string, any>): boolean;
 export declare function celPlaceholderForSchema(rawSchema: Record<string, any>): unknown;
-/** Resolve a `$ref` (only `#/$defs/...` form) against the root schema. */
-export declare function resolveRef(schema: Record<string, any>, root: Record<string, any>): Record<string, any>;
+/**
+ * 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 declare function resolveRef(schema: Record<string, any>, root: Record<string, any>, external?: ExternalSchemaResolver): Record<string, any>;
+/**
+ * {@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 declare function resolveRefIn(schema: Record<string, any>, root: Record<string, any>, external?: ExternalSchemaResolver): {
+    schema: Record<string, any>;
+    root: Record<string, any>;
+};
+/** Looks a registered schema up by its `$id`. */
+export type ExternalSchemaResolver = (ref: string) => Record<string, any> | undefined;
 /** Collect property schemas from top-level `properties` and all `oneOf`/`anyOf` sub-schemas. */
 /**
  * The `oneOf` / `anyOf` branch a value is written against, when exactly one fits.
@@ -95,20 +118,34 @@ export declare function resolveRef(schema: Record<string, any>, root: Record<str
  * — an ambiguous union is one the analyzer should not resolve on the author's
  * behalf.
  */
-export declare function selectUnionBranch(schema: Record<string, any>, data: unknown, root: Record<string, any>): Record<string, any>;
+export declare function selectUnionBranch(schema: Record<string, any>, data: unknown, root: Record<string, any>, external?: ExternalSchemaResolver): Record<string, any>;
 export declare function collectProperties(schema: Record<string, any>): Record<string, any>;
 /** 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 declare function substituteCelFields(data: unknown, schema: Record<string, any>, rootSchema?: Record<string, any>, 
-/** Called with the dotted path of every value replaced by a placeholder.
+/** Everything {@link substituteCelFields} does beyond walking the value.
  *
- *  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: string) => void, path?: string): unknown;
-export {};
+ *  One object rather than trailing positionals: the resolver is the parameter a
+ *  caller most needs and was the LAST of six, so reaching it meant counting
+ *  `undefined`s — and a caller that stopped counting one short simply got the
+ *  old blind behaviour, silently. Two of them did. */
+export interface SubstituteOptions {
+    /** 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: string) => void;
+    /** Dotted path of `data` within the resource, for `onSubstitute`. */
+    path?: string;
+    /** Resolves a named shape (`telo:<module>/<Type>`) to its schema. Without it
+     *  a slot described by one reads as undescribed and every CEL leaf beneath it
+     *  is handed the typeless `""` stand-in — which the shape then rejects, so a
+     *  perfectly valid expression is reported as a violation. */
+    external?: ExternalSchemaResolver;
+}
+export declare function substituteCelFields(data: unknown, schema: Record<string, any>, rootSchema?: Record<string, any>, options?: SubstituteOptions): unknown;
 //# sourceMappingURL=schema-compat.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema-compat.d.ts","sourceRoot":"","sources":["../src/schema-compat.ts"],"names":[],"mappings":"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"}

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