@maroonedog/luq 0.1.2-alpha → 2.0.0

package/dist/compile/compile-array-node.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileRelativeDeclaration = compileRelativeDeclaration;
+exports.compileArrayNode = compileArrayNode;
+// ===========================================================================
+// L4  src/compile/compile-array-node.ts — one ArrayFieldGroup becomes one
+// ArrayNode, and its wildcard-carrying members become nested ArrayNodes.
+//
+// The node holds ONE reader for the array and a flat list of element fields.
+// That is the whole of the loop interchange at run time: read once, then walk
+// the elements, and for each element walk the fields.
+//
+// `read` is the ARRAY reader, so "there is no array at this path" is decided
+// here, at the boundary, as null. The legacy tree spelled that rule inline in
+// two places and forgot it in a third, which is how `matrix[*][*]` became
+// silently unvalidated.
+// ===========================================================================
+const create_array_reader_1 = require("../path/create-array-reader");
+const compile_field_1 = require("./compile-field");
+const group_array_fields_1 = require("./group-array-fields");
+/** The one adapter from a grouped declaration to compileField's request. */
+function compileRelativeDeclaration(declaration, context) {
+    return (0, compile_field_1.compileField)({
+        template: declaration.template,
+        rules: declaration.rules,
+        fieldPath: declaration.fieldPath,
+        defaultOf: declaration.defaultOf,
+        applyDefaultToNull: declaration.applyDefaultToNull,
+        planRef: context.planRef,
+        eraseComposite: context.eraseComposite,
+    });
+}
+/**
+ * Nesting is a re-grouping of the members, not a second traversal strategy:
+ * `items[*].sub[*].x` arrives here as the group `items` whose one member is
+ * still `sub[*].x`, and that member groups again into the nested node `sub`.
+ * `matrix[*][*]` reaches the same shape through an EMPTY nested template —
+ * the element of the outer array is itself the inner array.
+ */
+function compileArrayNode(group, context) {
+    const grouped = (0, group_array_fields_1.groupArrayFields)(group.members);
+    const template = Object.freeze(group.template);
+    const node = {
+        template,
+        read: (0, create_array_reader_1.createArrayReader)(template),
+        elementFields: Object.freeze(grouped.direct.map((declaration) => compileRelativeDeclaration(declaration, context))),
+        nested: Object.freeze(grouped.arrays.map((nested) => compileArrayNode(nested, context))),
+    };
+    return Object.freeze(node);
+}

package/dist/compile/compile-array-node.mjs

@@ -0,0 +1,46 @@
+// ===========================================================================
+// L4  src/compile/compile-array-node.ts — one ArrayFieldGroup becomes one
+// ArrayNode, and its wildcard-carrying members become nested ArrayNodes.
+//
+// The node holds ONE reader for the array and a flat list of element fields.
+// That is the whole of the loop interchange at run time: read once, then walk
+// the elements, and for each element walk the fields.
+//
+// `read` is the ARRAY reader, so "there is no array at this path" is decided
+// here, at the boundary, as null. The legacy tree spelled that rule inline in
+// two places and forgot it in a third, which is how `matrix[*][*]` became
+// silently unvalidated.
+// ===========================================================================
+import { createArrayReader } from "../path/create-array-reader.mjs";
+import { compileField } from "./compile-field.mjs";
+import { groupArrayFields, } from "./group-array-fields.mjs";
+/** The one adapter from a grouped declaration to compileField's request. */
+export function compileRelativeDeclaration(declaration, context) {
+    return compileField({
+        template: declaration.template,
+        rules: declaration.rules,
+        fieldPath: declaration.fieldPath,
+        defaultOf: declaration.defaultOf,
+        applyDefaultToNull: declaration.applyDefaultToNull,
+        planRef: context.planRef,
+        eraseComposite: context.eraseComposite,
+    });
+}
+/**
+ * Nesting is a re-grouping of the members, not a second traversal strategy:
+ * `items[*].sub[*].x` arrives here as the group `items` whose one member is
+ * still `sub[*].x`, and that member groups again into the nested node `sub`.
+ * `matrix[*][*]` reaches the same shape through an EMPTY nested template —
+ * the element of the outer array is itself the inner array.
+ */
+export function compileArrayNode(group, context) {
+    const grouped = groupArrayFields(group.members);
+    const template = Object.freeze(group.template);
+    const node = {
+        template,
+        read: createArrayReader(template),
+        elementFields: Object.freeze(grouped.direct.map((declaration) => compileRelativeDeclaration(declaration, context))),
+        nested: Object.freeze(grouped.arrays.map((nested) => compileArrayNode(nested, context))),
+    };
+    return Object.freeze(node);
+}

package/dist/compile/compile-composite.d.ts

@@ -0,0 +1,18 @@
+import type { CompositeBranch, CompositeRule } from "../plugin-kit/compiled-rule";
+import type { BranchExecutor } from "./branch-executor.port";
+import type { CompiledCheck, ValidationPlan } from "./validation-plan.types";
+/**
+ * Compiles one branch to a nested plan. Supplied by compileSchema, which owns
+ * plan assembly; injecting it is what keeps compile-composite and
+ * compile-schema from importing each other.
+ */
+export type BranchPlanCompiler = (branch: CompositeBranch) => ValidationPlan;
+export interface CompositeCompileContext {
+    readonly executor: BranchExecutor;
+    readonly compileBranchPlan: BranchPlanCompiler;
+}
+/**
+ * `runners[i]` corresponds to `branches[i]`: tupleBuilder addresses branch i by
+ * position, so the array must not be reordered or filtered.
+ */
+export declare function compileComposite(rule: CompositeRule, context: CompositeCompileContext): CompiledCheck;

package/dist/compile/compile-composite.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileComposite = compileComposite;
+/**
+ * `runners[i]` corresponds to `branches[i]`: tupleBuilder addresses branch i by
+ * position, so the array must not be reordered or filtered.
+ */
+function compileComposite(rule, context) {
+    const runners = rule.branches.map((branch) => compileBranchRunner(branch, context));
+    const execute = rule.combine(Object.freeze(runners));
+    const check = {
+        code: rule.code,
+        severity: rule.severity,
+        // Stored by identity: what combine returned IS the check's run.
+        run: execute,
+        // Wrapped, not aliased, so a `describe` written as an object method keeps
+        // its receiver.
+        describe: (detail, messageContext) => rule.describe(detail, messageContext),
+    };
+    return Object.freeze(check);
+}
+function compileBranchRunner(branch, context) {
+    const plan = context.compileBranchPlan(branch);
+    const { executor } = context;
+    const runner = {
+        label: branch.label,
+        run: (value, ruleContext) => executor.runBranch(plan, value, ruleContext),
+    };
+    return Object.freeze(runner);
+}

package/dist/compile/compile-composite.mjs

@@ -0,0 +1,27 @@
+/**
+ * `runners[i]` corresponds to `branches[i]`: tupleBuilder addresses branch i by
+ * position, so the array must not be reordered or filtered.
+ */
+export function compileComposite(rule, context) {
+    const runners = rule.branches.map((branch) => compileBranchRunner(branch, context));
+    const execute = rule.combine(Object.freeze(runners));
+    const check = {
+        code: rule.code,
+        severity: rule.severity,
+        // Stored by identity: what combine returned IS the check's run.
+        run: execute,
+        // Wrapped, not aliased, so a `describe` written as an object method keeps
+        // its receiver.
+        describe: (detail, messageContext) => rule.describe(detail, messageContext),
+    };
+    return Object.freeze(check);
+}
+function compileBranchRunner(branch, context) {
+    const plan = context.compileBranchPlan(branch);
+    const { executor } = context;
+    const runner = {
+        label: branch.label,
+        run: (value, ruleContext) => executor.runBranch(plan, value, ruleContext),
+    };
+    return Object.freeze(runner);
+}

package/dist/compile/compile-field.d.ts

@@ -0,0 +1,31 @@
+import type { PathSegment } from "../path/path-segment.types";
+import type { CompositeRule, Rule } from "../plugin-kit/compiled-rule";
+import type { CompiledCheck, CompiledField, FieldDeclaration, PlanRef } from "./validation-plan.types";
+/**
+ * Erases one CompositeRule to a plain CompiledCheck. Supplied by L4 part 2
+ * (compile-composite), which owns branch compilation and calls `combine` once.
+ * Injecting it here is what keeps "no rule kind other than check reaches L5"
+ * true without compile-field knowing anything about branches.
+ */
+export type CompositeEraser = (rule: CompositeRule) => CompiledCheck;
+/** Whether a field with no explicit setting replaces a null with its default. */
+export declare const APPLIES_DEFAULT_TO_NULL_BY_DEFAULT = true;
+export interface FieldCompileRequest {
+    /** The path RELATIVE to the subject this field is read from. */
+    readonly template: readonly PathSegment[];
+    readonly rules: readonly Rule[];
+    /** The declared path, used only to name a build-time failure. */
+    readonly fieldPath: string;
+    readonly defaultOf: ((root: unknown) => unknown) | null;
+    readonly applyDefaultToNull: boolean;
+    readonly planRef: PlanRef;
+    readonly eraseComposite: CompositeEraser;
+}
+export declare function compileField(request: FieldCompileRequest): CompiledField;
+/**
+ * The convenience entry point for a field declared at an absolute path. A
+ * malformed or unsafe path throws PathSyntaxError HERE, at build time, naming
+ * the path: the legacy silent `return () => null` turned a typo into a rule
+ * that never ran.
+ */
+export declare function compileFieldDeclaration(declaration: FieldDeclaration, planRef: PlanRef, eraseComposite: CompositeEraser): CompiledField;

package/dist/compile/compile-field.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT = void 0;
+exports.compileField = compileField;
+exports.compileFieldDeclaration = compileFieldDeclaration;
+const create_value_reader_1 = require("../path/create-value-reader");
+const create_value_writer_1 = require("../path/create-value-writer");
+const parse_field_path_1 = require("../path/parse-field-path");
+const resolve_conditional_presence_1 = require("./resolve-conditional-presence");
+const resolve_presence_1 = require("./resolve-presence");
+const resolve_recursion_1 = require("./resolve-recursion");
+const split_rules_by_kind_1 = require("./split-rules-by-kind");
+/** Whether a field with no explicit setting replaces a null with its default. */
+exports.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT = true;
+function compileField(request) {
+    const byKind = (0, split_rules_by_kind_1.splitRulesByKind)(request.rules);
+    const hasDefault = request.defaultOf !== null;
+    const needsWriter = byKind.transforms.length > 0 || hasDefault;
+    const template = Object.freeze(request.template);
+    const field = {
+        template,
+        read: (0, create_value_reader_1.createValueReader)(template),
+        write: needsWriter ? (0, create_value_writer_1.createValueWriter)(template) : null,
+        defaultOf: request.defaultOf,
+        applyDefaultToNull: request.applyDefaultToNull,
+        presence: (0, resolve_presence_1.resolvePresence)(byKind.presences),
+        presenceOverrides: (0, resolve_conditional_presence_1.resolveConditionalPresence)(byKind.conditionalPresences),
+        gates: byKind.gates,
+        checks: collectOrderedChecks(request.rules, request.eraseComposite),
+        transforms: byKind.transforms,
+        recursion: (0, resolve_recursion_1.resolveRecursion)(byKind.recursions, request.planRef, request.fieldPath),
+    };
+    return Object.freeze(field);
+}
+/**
+ * The convenience entry point for a field declared at an absolute path. A
+ * malformed or unsafe path throws PathSyntaxError HERE, at build time, naming
+ * the path: the legacy silent `return () => null` turned a typo into a rule
+ * that never ran.
+ */
+function compileFieldDeclaration(declaration, planRef, eraseComposite) {
+    return compileField({
+        template: (0, parse_field_path_1.parseFieldPath)(declaration.path),
+        rules: declaration.rules,
+        fieldPath: declaration.path,
+        defaultOf: declaration.defaultOf ?? null,
+        applyDefaultToNull: declaration.applyDefaultToNull ?? exports.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        planRef,
+        eraseComposite,
+    });
+}
+/**
+ * Checks and composites share one list because they share one call shape, and
+ * they keep DECLARATION order between them: a composite declared before a
+ * check must still run before it. Splitting them into two arrays and
+ * concatenating would quietly reorder the user's rules.
+ */
+function collectOrderedChecks(rules, eraseComposite) {
+    const checks = [];
+    for (const rule of rules) {
+        if (rule.kind === "check")
+            checks.push(rule);
+        else if (rule.kind === "composite")
+            checks.push(eraseComposite(rule));
+    }
+    return Object.freeze(checks);
+}

package/dist/compile/compile-field.mjs

@@ -0,0 +1,62 @@
+import { createValueReader } from "../path/create-value-reader.mjs";
+import { createValueWriter } from "../path/create-value-writer.mjs";
+import { parseFieldPath } from "../path/parse-field-path.mjs";
+import { resolveConditionalPresence } from "./resolve-conditional-presence.mjs";
+import { resolvePresence } from "./resolve-presence.mjs";
+import { resolveRecursion } from "./resolve-recursion.mjs";
+import { splitRulesByKind } from "./split-rules-by-kind.mjs";
+/** Whether a field with no explicit setting replaces a null with its default. */
+export const APPLIES_DEFAULT_TO_NULL_BY_DEFAULT = true;
+export function compileField(request) {
+    const byKind = splitRulesByKind(request.rules);
+    const hasDefault = request.defaultOf !== null;
+    const needsWriter = byKind.transforms.length > 0 || hasDefault;
+    const template = Object.freeze(request.template);
+    const field = {
+        template,
+        read: createValueReader(template),
+        write: needsWriter ? createValueWriter(template) : null,
+        defaultOf: request.defaultOf,
+        applyDefaultToNull: request.applyDefaultToNull,
+        presence: resolvePresence(byKind.presences),
+        presenceOverrides: resolveConditionalPresence(byKind.conditionalPresences),
+        gates: byKind.gates,
+        checks: collectOrderedChecks(request.rules, request.eraseComposite),
+        transforms: byKind.transforms,
+        recursion: resolveRecursion(byKind.recursions, request.planRef, request.fieldPath),
+    };
+    return Object.freeze(field);
+}
+/**
+ * The convenience entry point for a field declared at an absolute path. A
+ * malformed or unsafe path throws PathSyntaxError HERE, at build time, naming
+ * the path: the legacy silent `return () => null` turned a typo into a rule
+ * that never ran.
+ */
+export function compileFieldDeclaration(declaration, planRef, eraseComposite) {
+    return compileField({
+        template: parseFieldPath(declaration.path),
+        rules: declaration.rules,
+        fieldPath: declaration.path,
+        defaultOf: declaration.defaultOf ?? null,
+        applyDefaultToNull: declaration.applyDefaultToNull ?? APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        planRef,
+        eraseComposite,
+    });
+}
+/**
+ * Checks and composites share one list because they share one call shape, and
+ * they keep DECLARATION order between them: a composite declared before a
+ * check must still run before it. Splitting them into two arrays and
+ * concatenating would quietly reorder the user's rules.
+ */
+function collectOrderedChecks(rules, eraseComposite) {
+    const checks = [];
+    for (const rule of rules) {
+        if (rule.kind === "check")
+            checks.push(rule);
+        else if (rule.kind === "composite")
+            checks.push(eraseComposite(rule));
+    }
+    return Object.freeze(checks);
+}

package/dist/compile/compile-schema.d.ts

@@ -0,0 +1,8 @@
+import type { BranchExecutor } from "./branch-executor.port";
+import type { FieldDeclaration, ValidationPlan } from "./validation-plan.types";
+/** A PlanRef resolved before its plan was assembled: only compilation itself
+ *  could do that, and compilation resolving a recursive plan never ends. */
+export declare class UnresolvedPlanError extends Error {
+    constructor();
+}
+export declare function compileSchema(declarations: readonly FieldDeclaration[], branchExecutor: BranchExecutor): ValidationPlan;

package/dist/compile/compile-schema.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnresolvedPlanError = void 0;
+exports.compileSchema = compileSchema;
+// ===========================================================================
+// L4  src/compile/compile-schema.ts — PLAN ASSEMBLY with PlanRef BACK-PATCHING.
+//
+// One pass: parse every declared path once, split the wildcard-carrying ones
+// into array nodes, compile the rest into fields, and record whether the plan
+// writes anything at all. Nothing here executes a rule.
+//
+// The back-patch is what makes `objectRecursively` expressible as FINITE data.
+// A recursive schema's plan contains a RecursionPolicy that points at the very
+// plan being built, so the holder is created FIRST, handed to every field, and
+// filled in LAST. No field ever holds a partially built plan, no forward
+// declaration is needed, and — the point of doing it with a closure over a
+// local rather than a mutable plan object — not one assertion is written.
+//
+// `branchExecutor` is REQUIRED. compile/ has no traversal loop of its own and
+// must not grow one: branch execution is L5's single engine, reached through
+// the port. Making the parameter optional would be the door a second traversal
+// walks through, so there is no default.
+// ===========================================================================
+const parse_field_path_1 = require("../path/parse-field-path");
+const declared_child_keys_1 = require("./declared-child-keys");
+const compile_array_node_1 = require("./compile-array-node");
+const compile_composite_1 = require("./compile-composite");
+const compile_field_1 = require("./compile-field");
+const group_array_fields_1 = require("./group-array-fields");
+/** A PlanRef resolved before its plan was assembled: only compilation itself
+ *  could do that, and compilation resolving a recursive plan never ends. */
+class UnresolvedPlanError extends Error {
+    constructor() {
+        super("A PlanRef was resolved before its plan finished compiling. " +
+            "Recursion is resolved at validation time, never at build time.");
+        this.name = "UnresolvedPlanError";
+    }
+}
+exports.UnresolvedPlanError = UnresolvedPlanError;
+function compileSchema(declarations, branchExecutor) {
+    return compilePlan(declarations.map(parseRelativeDeclaration), branchExecutor);
+}
+/**
+ * `relatives` is the FLAT list for one plan — array members included, because
+ * grouping happens below. That is what lets hasTransforms / hasDefaults be
+ * decided by one scan instead of by walking the compiled node tree.
+ */
+function compilePlan(relatives, executor) {
+    let compiled = null;
+    const planRef = {
+        resolve: () => {
+            if (compiled === null)
+                throw new UnresolvedPlanError();
+            return compiled;
+        },
+    };
+    const grouped = (0, group_array_fields_1.groupArrayFields)(relatives);
+    const context = {
+        planRef,
+        eraseComposite: createCompositeEraser(executor),
+    };
+    compiled = Object.freeze({
+        fields: Object.freeze(grouped.direct.map((declaration) => (0, compile_array_node_1.compileRelativeDeclaration)(declaration, context))),
+        arrays: Object.freeze(grouped.arrays.map((group) => (0, compile_array_node_1.compileArrayNode)(group, context))),
+        hasTransforms: relatives.some((declaration) => declaration.rules.some((rule) => rule.kind === "transform")),
+        hasDefaults: relatives.some((declaration) => declaration.defaultOf !== null),
+    });
+    return compiled;
+}
+/** Each branch gets its OWN plan, so a `recursively` inside a branch re-enters
+ *  that branch and not the schema that happens to contain it. */
+function createCompositeEraser(executor) {
+    return (rule) => (0, compile_composite_1.compileComposite)(rule, {
+        executor,
+        compileBranchPlan: (branch) => compilePlan(collectBranchDeclarations(branch), executor),
+    });
+}
+/**
+ * ROOT_PATH declares a rule on the SUBJECT ITSELF, and its template is the
+ * EMPTY array — the very shape collectBranchDeclarations below already builds
+ * for a branch's own rules, so the runtime has always supported it and only
+ * this parse step forbade it. It is what lets a JSON Schema keyword that sits
+ * on the document root (`additionalProperties`, `minProperties`, `anyOf`,
+ * `if`/`then`/`else`, …) become a rule instead of being refused: see
+ * src/json-schema/flatten-schema.ts. parseFieldPath still rejects "" for every
+ * OTHER caller, because a *child* path may not be empty.
+ */
+function parseRelativeDeclaration(declaration) {
+    return {
+        template: declaration.path === declared_child_keys_1.ROOT_PATH
+            ? Object.freeze([])
+            : (0, parse_field_path_1.parseFieldPath)(declaration.path),
+        rules: declaration.rules,
+        fieldPath: declaration.path,
+        defaultOf: declaration.defaultOf ?? null,
+        applyDefaultToNull: declaration.applyDefaultToNull ?? compile_field_1.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+    };
+}
+/**
+ * A branch is a plan over the branch SUBJECT: its own rules bind to the empty
+ * template (the subject itself) and its fields to paths relative to it. The
+ * subject entry is omitted when the branch declares no rules of its own, so a
+ * pure `properties` branch compiles to exactly its fields.
+ */
+function collectBranchDeclarations(branch) {
+    const declarations = [];
+    if (branch.rules.length > 0) {
+        declarations.push({
+            template: Object.freeze([]),
+            rules: branch.rules,
+            fieldPath: branch.label,
+            defaultOf: null,
+            applyDefaultToNull: compile_field_1.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        });
+    }
+    for (const field of branch.fields) {
+        declarations.push({
+            template: (0, parse_field_path_1.parseFieldPath)(field.path),
+            rules: field.rules,
+            fieldPath: field.path,
+            defaultOf: null,
+            applyDefaultToNull: compile_field_1.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        });
+    }
+    return declarations;
+}

package/dist/compile/compile-schema.mjs

@@ -0,0 +1,121 @@
+// ===========================================================================
+// L4  src/compile/compile-schema.ts — PLAN ASSEMBLY with PlanRef BACK-PATCHING.
+//
+// One pass: parse every declared path once, split the wildcard-carrying ones
+// into array nodes, compile the rest into fields, and record whether the plan
+// writes anything at all. Nothing here executes a rule.
+//
+// The back-patch is what makes `objectRecursively` expressible as FINITE data.
+// A recursive schema's plan contains a RecursionPolicy that points at the very
+// plan being built, so the holder is created FIRST, handed to every field, and
+// filled in LAST. No field ever holds a partially built plan, no forward
+// declaration is needed, and — the point of doing it with a closure over a
+// local rather than a mutable plan object — not one assertion is written.
+//
+// `branchExecutor` is REQUIRED. compile/ has no traversal loop of its own and
+// must not grow one: branch execution is L5's single engine, reached through
+// the port. Making the parameter optional would be the door a second traversal
+// walks through, so there is no default.
+// ===========================================================================
+import { parseFieldPath } from "../path/parse-field-path.mjs";
+import { ROOT_PATH } from "./declared-child-keys.mjs";
+import { compileArrayNode, compileRelativeDeclaration, } from "./compile-array-node.mjs";
+import { compileComposite } from "./compile-composite.mjs";
+import { APPLIES_DEFAULT_TO_NULL_BY_DEFAULT } from "./compile-field.mjs";
+import { groupArrayFields } from "./group-array-fields.mjs";
+/** A PlanRef resolved before its plan was assembled: only compilation itself
+ *  could do that, and compilation resolving a recursive plan never ends. */
+export class UnresolvedPlanError extends Error {
+    constructor() {
+        super("A PlanRef was resolved before its plan finished compiling. " +
+            "Recursion is resolved at validation time, never at build time.");
+        this.name = "UnresolvedPlanError";
+    }
+}
+export function compileSchema(declarations, branchExecutor) {
+    return compilePlan(declarations.map(parseRelativeDeclaration), branchExecutor);
+}
+/**
+ * `relatives` is the FLAT list for one plan — array members included, because
+ * grouping happens below. That is what lets hasTransforms / hasDefaults be
+ * decided by one scan instead of by walking the compiled node tree.
+ */
+function compilePlan(relatives, executor) {
+    let compiled = null;
+    const planRef = {
+        resolve: () => {
+            if (compiled === null)
+                throw new UnresolvedPlanError();
+            return compiled;
+        },
+    };
+    const grouped = groupArrayFields(relatives);
+    const context = {
+        planRef,
+        eraseComposite: createCompositeEraser(executor),
+    };
+    compiled = Object.freeze({
+        fields: Object.freeze(grouped.direct.map((declaration) => compileRelativeDeclaration(declaration, context))),
+        arrays: Object.freeze(grouped.arrays.map((group) => compileArrayNode(group, context))),
+        hasTransforms: relatives.some((declaration) => declaration.rules.some((rule) => rule.kind === "transform")),
+        hasDefaults: relatives.some((declaration) => declaration.defaultOf !== null),
+    });
+    return compiled;
+}
+/** Each branch gets its OWN plan, so a `recursively` inside a branch re-enters
+ *  that branch and not the schema that happens to contain it. */
+function createCompositeEraser(executor) {
+    return (rule) => compileComposite(rule, {
+        executor,
+        compileBranchPlan: (branch) => compilePlan(collectBranchDeclarations(branch), executor),
+    });
+}
+/**
+ * ROOT_PATH declares a rule on the SUBJECT ITSELF, and its template is the
+ * EMPTY array — the very shape collectBranchDeclarations below already builds
+ * for a branch's own rules, so the runtime has always supported it and only
+ * this parse step forbade it. It is what lets a JSON Schema keyword that sits
+ * on the document root (`additionalProperties`, `minProperties`, `anyOf`,
+ * `if`/`then`/`else`, …) become a rule instead of being refused: see
+ * src/json-schema/flatten-schema.ts. parseFieldPath still rejects "" for every
+ * OTHER caller, because a *child* path may not be empty.
+ */
+function parseRelativeDeclaration(declaration) {
+    return {
+        template: declaration.path === ROOT_PATH
+            ? Object.freeze([])
+            : parseFieldPath(declaration.path),
+        rules: declaration.rules,
+        fieldPath: declaration.path,
+        defaultOf: declaration.defaultOf ?? null,
+        applyDefaultToNull: declaration.applyDefaultToNull ?? APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+    };
+}
+/**
+ * A branch is a plan over the branch SUBJECT: its own rules bind to the empty
+ * template (the subject itself) and its fields to paths relative to it. The
+ * subject entry is omitted when the branch declares no rules of its own, so a
+ * pure `properties` branch compiles to exactly its fields.
+ */
+function collectBranchDeclarations(branch) {
+    const declarations = [];
+    if (branch.rules.length > 0) {
+        declarations.push({
+            template: Object.freeze([]),
+            rules: branch.rules,
+            fieldPath: branch.label,
+            defaultOf: null,
+            applyDefaultToNull: APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        });
+    }
+    for (const field of branch.fields) {
+        declarations.push({
+            template: parseFieldPath(field.path),
+            rules: field.rules,
+            fieldPath: field.path,
+            defaultOf: null,
+            applyDefaultToNull: APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        });
+    }
+    return declarations;
+}

package/dist/compile/declared-child-keys.d.ts

@@ -0,0 +1,15 @@
+/** The parent path of a top-level declaration. Not a legal declared path. */
+export declare const ROOT_PATH = "";
+/** Answers "which child object keys were declared directly under this path". */
+export type DeclaredChildKeysReader = (parentPath: string) => readonly string[];
+/**
+ * Every path is parsed by the ONE parser, so a malformed declaration is
+ * rejected here at build time rather than producing an empty key list that a
+ * plugin would then read as "this object declares nothing".
+ *
+ * Ancestors count. `user.profile.name` alone declares `profile` under `user`
+ * and `name` under `user.profile`, because both facts are visible in the
+ * string. A wildcard contributes no key: the members of `items[*]` have an
+ * index, not a name, which is exactly what leafKeyOf's null means.
+ */
+export declare function indexDeclaredChildKeys(paths: readonly string[]): DeclaredChildKeysReader;