@maroonedog/luq 0.1.1-alpha → 2.0.0

package/dist/builder/create-builder.mjs

@@ -0,0 +1,92 @@
+// ===========================================================================
+// L6  src/builder/create-builder.ts — THE SINGLE PUBLIC ENTRY POINT, and the
+// one place in src/ that calls eraseBuilderSurface.
+//
+// `use()` MUTATES and returns the receiver; that is the 1.x behaviour and it is
+// what separates a builder from a FieldRule registry (step 14), whose use() is
+// immutable. Duplicates are dropped FIRST-WINS: a bag is a name -> plugin map,
+// and letting the second registration overwrite the first is how legacy made
+// `.use(a).use(b)` depend on import order.
+//
+// `for<T>()` snapshots the bag. A use() after it therefore cannot reach back
+// into a field builder that was already handed out.
+// ===========================================================================
+import { eraseBuilderSurface } from "../core/type-erasure.mjs";
+import { isPlainObject, isString } from "../types/index.mjs";
+import { createFieldBuilderSurface } from "./create-field-builder.mjs";
+/** `use()` given something that is not a plugin. Named, and thrown at once:
+ *  legacy swallowed it and produced a validator that permitted everything. */
+export class NamelessPluginError extends Error {
+    constructor(received) {
+        super(`use() expects a plugin with a name and a build(); received ` +
+            `${renderReceived(received)}. Pass the plugin itself, for example ` +
+            `use(requiredPlugin).`);
+        this.received = received;
+        this.name = "NamelessPluginError";
+    }
+}
+/**
+ * The implementation behind `Builder()`. The exported const lives in
+ * ./field-builder.types.ts, beside the interface it merges with; this module
+ * reaches that file for a TYPE only, so the emitted module graph has one edge
+ * between the two and no cycle.
+ */
+export function createBuilder() {
+    return eraseBuilderSurface(createBuilderSurface());
+}
+export function createBuilderSurface() {
+    const registration = {
+        plugins: new Map(),
+        config: undefined,
+    };
+    const surface = {
+        use(plugin) {
+            registerPlugin(registration.plugins, plugin);
+            return surface;
+        },
+        withConfig(config) {
+            registration.config = Object.assign({}, registration.config, config);
+            return surface;
+        },
+        for: () => createFieldBuilderSurface(toPluginBag(registration.plugins), registration.config),
+    };
+    return surface;
+}
+function registerPlugin(plugins, candidate) {
+    if (!isNamedPlugin(candidate))
+        throw new NamelessPluginError(candidate);
+    if (plugins.has(candidate.name))
+        return;
+    plugins.set(candidate.name, candidate);
+}
+/**
+ * A GUARD, not a shape assertion: `use()` is the boundary a JavaScript caller
+ * crosses, so the declared parameter type proves nothing here.
+ */
+function isNamedPlugin(candidate) {
+    if (!isPlainObject(candidate))
+        return false;
+    const name = candidate["name"];
+    return (isString(name) &&
+        name.length > 0 &&
+        typeof candidate["build"] === "function");
+}
+/**
+ * defineProperty rather than assignment, because a plugin named `__proto__`
+ * would otherwise be swallowed by the prototype setter instead of landing in
+ * the bag — and attachSlotMethods walks the bag with Object.keys.
+ */
+function toPluginBag(plugins) {
+    const bag = {};
+    for (const [name, plugin] of plugins) {
+        Object.defineProperty(bag, name, { value: plugin, enumerable: true });
+    }
+    return Object.freeze(bag);
+}
+function renderReceived(received) {
+    if (received === null)
+        return "null";
+    if (isPlainObject(received))
+        return `an object with no name`;
+    return typeof received;
+}

package/dist/builder/create-field-builder.d.ts

@@ -0,0 +1,5 @@
+import type { PluginBag } from "../chain/plugin-bag.types";
+import type { GlobalConfig } from "../types/global-config";
+import type { FieldBuilderSurface } from "./builder-surface.types";
+import type { FieldEntry } from "./field-entry.types";
+export declare function createFieldBuilderSurface(bag: PluginBag, configOverride: GlobalConfig | undefined, entries?: readonly FieldEntry[]): FieldBuilderSurface;

package/dist/builder/create-field-builder.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFieldBuilderSurface = createFieldBuilderSurface;
+// ===========================================================================
+// L6  src/builder/create-field-builder.ts — the IMMUTABLE declaration list.
+//
+// `.v()` does not run the callback and does not touch the receiver: it returns
+// a NEW surface carrying one more entry. Two chains branched from the same
+// field builder therefore cannot contaminate each other, and — the reason that
+// matters more — the user's callback has not run yet, so nothing has been
+// decided before build() knows the config and the declared sibling keys.
+//
+// `.strict()` returns the receiver. Strictness is a type-level obligation with
+// no runtime effect (docs/legacy-spec/documented-promises.md): rejecting an
+// undeclared property at run time is objectAdditionalProperties' job.
+// ===========================================================================
+const collect_field_rules_1 = require("../chain/collect-field-rules");
+const compile_declarations_1 = require("./compile-declarations");
+const create_plan_validator_1 = require("./create-plan-validator");
+const resolve_field_default_1 = require("./resolve-field-default");
+/** No declaration yet: shared and frozen, so `.for<T>()` allocates nothing. */
+const NO_ENTRIES = Object.freeze([]);
+function createFieldBuilderSurface(bag, configOverride, entries = NO_ENTRIES) {
+    const surface = {
+        v: (path, define, options) => createFieldBuilderSurface(bag, configOverride, [
+            ...entries,
+            toFieldEntry(bag, path, define, options),
+        ]),
+        strict: () => surface,
+        build: () => (0, create_plan_validator_1.createPlanBackedValidator)((0, compile_declarations_1.compileDeclarations)(entries, configOverride)),
+    };
+    return Object.freeze(surface);
+}
+/**
+ * The bag is captured HERE, at `.v()`, and the callback is not. That is the
+ * whole of "the callback runs only at build()": collectRules is the only way
+ * back to it, compileDeclarations is its only caller, and it calls it once.
+ */
+function toFieldEntry(bag, path, define, options) {
+    const policy = (0, resolve_field_default_1.resolveFieldDefault)(options);
+    return {
+        path,
+        defaultOf: policy.defaultOf,
+        applyDefaultToNull: policy.applyDefaultToNull,
+        collectRules: (context) => (0, collect_field_rules_1.collectFieldRules)(bag, context, define),
+    };
+}

package/dist/builder/create-field-builder.mjs

@@ -0,0 +1,44 @@
+// ===========================================================================
+// L6  src/builder/create-field-builder.ts — the IMMUTABLE declaration list.
+//
+// `.v()` does not run the callback and does not touch the receiver: it returns
+// a NEW surface carrying one more entry. Two chains branched from the same
+// field builder therefore cannot contaminate each other, and — the reason that
+// matters more — the user's callback has not run yet, so nothing has been
+// decided before build() knows the config and the declared sibling keys.
+//
+// `.strict()` returns the receiver. Strictness is a type-level obligation with
+// no runtime effect (docs/legacy-spec/documented-promises.md): rejecting an
+// undeclared property at run time is objectAdditionalProperties' job.
+// ===========================================================================
+import { collectFieldRules } from "../chain/collect-field-rules.mjs";
+import { compileDeclarations } from "./compile-declarations.mjs";
+import { createPlanBackedValidator } from "./create-plan-validator.mjs";
+import { resolveFieldDefault } from "./resolve-field-default.mjs";
+/** No declaration yet: shared and frozen, so `.for<T>()` allocates nothing. */
+const NO_ENTRIES = Object.freeze([]);
+export function createFieldBuilderSurface(bag, configOverride, entries = NO_ENTRIES) {
+    const surface = {
+        v: (path, define, options) => createFieldBuilderSurface(bag, configOverride, [
+            ...entries,
+            toFieldEntry(bag, path, define, options),
+        ]),
+        strict: () => surface,
+        build: () => createPlanBackedValidator(compileDeclarations(entries, configOverride)),
+    };
+    return Object.freeze(surface);
+}
+/**
+ * The bag is captured HERE, at `.v()`, and the callback is not. That is the
+ * whole of "the callback runs only at build()": collectRules is the only way
+ * back to it, compileDeclarations is its only caller, and it calls it once.
+ */
+function toFieldEntry(bag, path, define, options) {
+    const policy = resolveFieldDefault(options);
+    return {
+        path,
+        defaultOf: policy.defaultOf,
+        applyDefaultToNull: policy.applyDefaultToNull,
+        collectRules: (context) => collectFieldRules(bag, context, define),
+    };
+}

package/dist/builder/create-plan-validator.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationPlan } from "../compile/validation-plan.types";
+import type { PlanBackedValidator } from "./builder-surface.types";
+export declare function createPlanBackedValidator(plan: ValidationPlan): PlanBackedValidator;

package/dist/builder/create-plan-validator.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPlanBackedValidator = createPlanBackedValidator;
+const create_field_validator_1 = require("../runtime/create-field-validator");
+const create_validator_1 = require("../runtime/create-validator");
+const create_subset_validator_1 = require("./create-subset-validator");
+function createPlanBackedValidator(plan) {
+    const validator = (0, create_validator_1.createValidator)(plan);
+    return Object.freeze({
+        validate: validator.validate,
+        parse: validator.parse,
+        pick: (key) => (0, create_field_validator_1.createFieldValidator)(plan, key),
+        pickAll: (paths) => (0, create_subset_validator_1.createSubsetValidator)(plan, paths),
+    });
+}

package/dist/builder/create-plan-validator.mjs

@@ -0,0 +1,12 @@
+import { createFieldValidator } from "../runtime/create-field-validator.mjs";
+import { createValidator } from "../runtime/create-validator.mjs";
+import { createSubsetValidator } from "./create-subset-validator.mjs";
+export function createPlanBackedValidator(plan) {
+    const validator = createValidator(plan);
+    return Object.freeze({
+        validate: validator.validate,
+        parse: validator.parse,
+        pick: (key) => createFieldValidator(plan, key),
+        pickAll: (paths) => createSubsetValidator(plan, paths),
+    });
+}

package/dist/builder/create-projection-reader.d.ts

@@ -0,0 +1,3 @@
+export type ProjectionReader = (subject: unknown) => unknown;
+/** Throws PathSyntaxError at pickAll() time, naming the path, never later. */
+export declare function createProjectionReader(path: string): ProjectionReader;

package/dist/builder/create-projection-reader.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProjectionReader = createProjectionReader;
+// ===========================================================================
+// L6  src/builder/create-projection-reader.ts
+// pickAll()'s output side: one declared path becomes one closure that lifts the
+// value(s) at that path out of a subject. Built ONCE, when pickAll() is called,
+// which is what "the paths are pre-resolved at that moment" means.
+//
+// It is NOT a second traversal of the plan: nothing here validates, nothing
+// here reads a rule. It is a projection, and it is expressed entirely by
+// composing the L1 readers so the two directions cannot disagree about what a
+// segment means. createValueReader refuses a wildcard on purpose (it has one
+// return value), so a `[*]` is split off here and mapped, exactly as the array
+// runner splits one.
+// ===========================================================================
+const create_array_reader_1 = require("../path/create-array-reader");
+const create_value_reader_1 = require("../path/create-value-reader");
+const parse_field_path_1 = require("../path/parse-field-path");
+/** Throws PathSyntaxError at pickAll() time, naming the path, never later. */
+function createProjectionReader(path) {
+    return createSegmentProjection((0, parse_field_path_1.parseFieldPath)(path));
+}
+/**
+ * A wildcard-free template reads one value. A wildcard template reads the array
+ * before the first `[*]` and maps the rest over its elements, so
+ * `items[*].name` projects to `string[]` and `grid[*][*]` to `unknown[][]` —
+ * the same shape ValueAtPath gives the caller.
+ *
+ * A non-array at a wildcard path projects to `undefined` rather than to `[]`:
+ * createArrayReader already answers null for "there is no array here", and
+ * inventing an empty array would tell the caller the field was present.
+ */
+function createSegmentProjection(template) {
+    const wildcardAt = template.findIndex((segment) => segment.kind === "each");
+    if (wildcardAt === -1)
+        return (0, create_value_reader_1.createValueReader)(template);
+    const readArray = (0, create_array_reader_1.createArrayReader)(template.slice(0, wildcardAt));
+    const readElement = createSegmentProjection(template.slice(wildcardAt + 1));
+    return (subject) => {
+        const elements = readArray(subject);
+        return elements === null ? undefined : elements.map(readElement);
+    };
+}

package/dist/builder/create-projection-reader.mjs

@@ -0,0 +1,41 @@
+// ===========================================================================
+// L6  src/builder/create-projection-reader.ts
+// pickAll()'s output side: one declared path becomes one closure that lifts the
+// value(s) at that path out of a subject. Built ONCE, when pickAll() is called,
+// which is what "the paths are pre-resolved at that moment" means.
+//
+// It is NOT a second traversal of the plan: nothing here validates, nothing
+// here reads a rule. It is a projection, and it is expressed entirely by
+// composing the L1 readers so the two directions cannot disagree about what a
+// segment means. createValueReader refuses a wildcard on purpose (it has one
+// return value), so a `[*]` is split off here and mapped, exactly as the array
+// runner splits one.
+// ===========================================================================
+import { createArrayReader } from "../path/create-array-reader.mjs";
+import { createValueReader } from "../path/create-value-reader.mjs";
+import { parseFieldPath } from "../path/parse-field-path.mjs";
+/** Throws PathSyntaxError at pickAll() time, naming the path, never later. */
+export function createProjectionReader(path) {
+    return createSegmentProjection(parseFieldPath(path));
+}
+/**
+ * A wildcard-free template reads one value. A wildcard template reads the array
+ * before the first `[*]` and maps the rest over its elements, so
+ * `items[*].name` projects to `string[]` and `grid[*][*]` to `unknown[][]` —
+ * the same shape ValueAtPath gives the caller.
+ *
+ * A non-array at a wildcard path projects to `undefined` rather than to `[]`:
+ * createArrayReader already answers null for "there is no array here", and
+ * inventing an empty array would tell the caller the field was present.
+ */
+function createSegmentProjection(template) {
+    const wildcardAt = template.findIndex((segment) => segment.kind === "each");
+    if (wildcardAt === -1)
+        return createValueReader(template);
+    const readArray = createArrayReader(template.slice(0, wildcardAt));
+    const readElement = createSegmentProjection(template.slice(wildcardAt + 1));
+    return (subject) => {
+        const elements = readArray(subject);
+        return elements === null ? undefined : elements.map(readElement);
+    };
+}

package/dist/builder/create-subset-validator.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationPlan } from "../compile/validation-plan.types";
+import type { PlanSubsetValidator } from "./builder-surface.types";
+export declare function createSubsetValidator(plan: ValidationPlan, paths: readonly string[]): PlanSubsetValidator;

package/dist/builder/create-subset-validator.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSubsetValidator = createSubsetValidator;
+const match_path_pattern_1 = require("../path/match-path-pattern");
+const create_validator_1 = require("../runtime/create-validator");
+const create_projection_reader_1 = require("./create-projection-reader");
+function createSubsetValidator(plan, paths) {
+    const projections = Object.freeze(paths.map((path) => ({ path, read: (0, create_projection_reader_1.createProjectionReader)(path) })));
+    const declared = Object.freeze(paths.slice());
+    const validator = (0, create_validator_1.createValidator)(plan);
+    const subset = {
+        paths: declared,
+        validate(value, options) {
+            const outcome = validator.validate(value, {
+                ...options,
+                abortEarly: false,
+            });
+            const issues = Object.freeze(outcome.issues.filter((issue) => projections.some((projection) => (0, match_path_pattern_1.matchPathPattern)(projection.path, issue.path))));
+            if ((0, create_validator_1.hasRejectingIssue)(issues))
+                return { valid: false, issues };
+            return { valid: true, data: projectPaths(projections, value), issues };
+        },
+    };
+    return Object.freeze(subset);
+}
+/**
+ * The result is keyed by the declared path STRING — `{"user.name": "…"}` — and
+ * not re-nested, which is what PickPaths<T, P> describes and what lets the
+ * caller read back exactly what it asked for with no re-narrowing.
+ */
+function projectPaths(projections, value) {
+    const projected = {};
+    for (const projection of projections) {
+        Object.defineProperty(projected, projection.path, {
+            value: projection.read(value),
+            enumerable: true,
+        });
+    }
+    return Object.freeze(projected);
+}

package/dist/builder/create-subset-validator.mjs

@@ -0,0 +1,37 @@
+import { matchPathPattern } from "../path/match-path-pattern.mjs";
+import { createValidator, hasRejectingIssue, } from "../runtime/create-validator.mjs";
+import { createProjectionReader } from "./create-projection-reader.mjs";
+export function createSubsetValidator(plan, paths) {
+    const projections = Object.freeze(paths.map((path) => ({ path, read: createProjectionReader(path) })));
+    const declared = Object.freeze(paths.slice());
+    const validator = createValidator(plan);
+    const subset = {
+        paths: declared,
+        validate(value, options) {
+            const outcome = validator.validate(value, {
+                ...options,
+                abortEarly: false,
+            });
+            const issues = Object.freeze(outcome.issues.filter((issue) => projections.some((projection) => matchPathPattern(projection.path, issue.path))));
+            if (hasRejectingIssue(issues))
+                return { valid: false, issues };
+            return { valid: true, data: projectPaths(projections, value), issues };
+        },
+    };
+    return Object.freeze(subset);
+}
+/**
+ * The result is keyed by the declared path STRING — `{"user.name": "…"}` — and
+ * not re-nested, which is what PickPaths<T, P> describes and what lets the
+ * caller read back exactly what it asked for with no re-narrowing.
+ */
+function projectPaths(projections, value) {
+    const projected = {};
+    for (const projection of projections) {
+        Object.defineProperty(projected, projection.path, {
+            value: projection.read(value),
+            enumerable: true,
+        });
+    }
+    return Object.freeze(projected);
+}

package/dist/builder/field-builder.types.d.ts

@@ -0,0 +1,43 @@
+import type { AnyPlugin } from "../plugin-kit/plugin-definition";
+import type { FieldPath } from "../path/field-path.types";
+import type { ValueAtPath } from "../path/value-at-path.types";
+import type { MissingLeafPaths } from "../path/leaf-path.types";
+import type { BagEntry, PluginBag } from "../chain/plugin-bag.types";
+import type { AnyChain, ChainOutput, ChainStateOf } from "../chain/field-chain.types";
+import type { FieldSlots } from "../chain/field-slots.types";
+import type { UncoveredMembers, UnionGuardCoverageError } from "../chain/chain-state.types";
+import type { GlobalConfig } from "../types/global-config";
+import type { FieldOptions } from "./field-options.types";
+import type { Validator } from "./validator.types";
+export type UncoveredOf<C> = UncoveredMembers<ChainOutput<C>, ChainStateOf<C>>;
+export interface MissingFieldsError<TMissing> {
+    readonly luqError: "missingFieldDeclarations";
+    readonly message: "Declare every leaf path, or drop .strict().";
+    readonly missing: TMissing;
+}
+export interface FieldBuilder<T extends object, B extends PluginBag, TDeclared extends string> {
+    /**
+     * `options` is a FIELD CONFIGURATION and never a Rule; it is where a default
+     * is declared. See ./field-options.types.ts.
+     */
+    v<K extends FieldPath<T> & string, C extends AnyChain>(path: K, define: (b: FieldSlots<T, B, ValueAtPath<T, K>>) => C, options?: FieldOptions<ValueAtPath<T, K>>): [UncoveredOf<C>] extends [never] ? FieldBuilder<T, B, TDeclared | K> : UnionGuardCoverageError<K, UncoveredOf<C>>;
+    strict(): [MissingLeafPaths<T, TDeclared>] extends [never] ? FieldBuilder<T, B, TDeclared> : MissingFieldsError<MissingLeafPaths<T, TDeclared>>;
+    build(): Validator<T>;
+}
+export interface Builder<B extends PluginBag = Record<never, never>> {
+    use<P extends AnyPlugin>(plugin: P): Builder<B & BagEntry<P>>;
+    /**
+     * The per-builder override of the process-wide GlobalConfig. Merged over
+     * getGlobalConfig() once, at build(), and handed to every plugin as
+     * RuleBuildContext.config.
+     */
+    withConfig(config: GlobalConfig): Builder<B>;
+    for<T extends object>(): FieldBuilder<T, B, never>;
+}
+/**
+ * THE SINGLE PUBLIC ENTRY POINT. It is declared here, beside the interface it
+ * merges with, so `Builder` names both the value and the type; the
+ * implementation lives in ./create-builder.ts and is reached by a value import,
+ * while that module reaches back for a TYPE only — one runtime edge, no cycle.
+ */
+export declare const Builder: () => Builder;

package/dist/builder/field-builder.types.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Builder = void 0;
+const create_builder_1 = require("./create-builder");
+/**
+ * THE SINGLE PUBLIC ENTRY POINT. It is declared here, beside the interface it
+ * merges with, so `Builder` names both the value and the type; the
+ * implementation lives in ./create-builder.ts and is reached by a value import,
+ * while that module reaches back for a TYPE only — one runtime edge, no cycle.
+ */
+exports.Builder = create_builder_1.createBuilder;

package/dist/builder/field-builder.types.mjs

@@ -0,0 +1,8 @@
+import { createBuilder } from "./create-builder.mjs";
+/**
+ * THE SINGLE PUBLIC ENTRY POINT. It is declared here, beside the interface it
+ * merges with, so `Builder` names both the value and the type; the
+ * implementation lives in ./create-builder.ts and is reached by a value import,
+ * while that module reaches back for a TYPE only — one runtime edge, no cycle.
+ */
+export const Builder = createBuilder;

package/dist/builder/field-entry.types.d.ts

@@ -0,0 +1,10 @@
+import type { ChainBuildContext } from "../chain/create-chain-node";
+import type { Rule } from "../plugin-kit/compiled-rule";
+export interface FieldEntry {
+    readonly path: string;
+    /** null unless `.v()`'s third argument declared a default. */
+    readonly defaultOf: ((root: unknown) => unknown) | null;
+    readonly applyDefaultToNull: boolean;
+    /** Runs the user's chain callback ONCE and returns its ordered rules. */
+    collectRules(context: ChainBuildContext): readonly Rule[];
+}

package/dist/builder/field-entry.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/builder/field-entry.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/builder/field-options.types.d.ts

@@ -0,0 +1,11 @@
+/** The lazy form of a default. A zero-argument function is assignable to it. */
+export type DefaultFactory<TValue> = (root: unknown) => TValue;
+export interface FieldOptions<TValue> {
+    /**
+     * Substituted before ANY rule looks at the value, so validate() and parse()
+     * judge the same thing; only parse() writes it back.
+     */
+    readonly default?: TValue | DefaultFactory<TValue>;
+    /** Defaults to true — a declared null is replaced, matching 1.x. */
+    readonly applyDefaultToNull?: boolean;
+}

package/dist/builder/field-options.types.js

@@ -0,0 +1,13 @@
+"use strict";
+// ===========================================================================
+// L6  src/builder/field-options.types.ts
+// The third argument of `.v()`. It is a FIELD CONFIGURATION, never a Rule:
+// compile/validation-plan.types.ts says so, and that is why `defaultOf` and
+// `applyDefaultToNull` sit on FieldDeclaration rather than in its rule list.
+//
+// Legacy shape (should-preserve, docs/legacy-spec/documented-promises.md:211):
+//     { default?: T | (() => T); applyDefaultToNull?: boolean }
+// The factory form is widened to `(root: unknown) => T` so a default can read
+// the object it is filling in; a legacy zero-argument factory still fits.
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/builder/field-options.types.mjs

@@ -0,0 +1,12 @@
+// ===========================================================================
+// L6  src/builder/field-options.types.ts
+// The third argument of `.v()`. It is a FIELD CONFIGURATION, never a Rule:
+// compile/validation-plan.types.ts says so, and that is why `defaultOf` and
+// `applyDefaultToNull` sit on FieldDeclaration rather than in its rule list.
+//
+// Legacy shape (should-preserve, docs/legacy-spec/documented-promises.md:211):
+//     { default?: T | (() => T); applyDefaultToNull?: boolean }
+// The factory form is widened to `(root: unknown) => T` so a default can read
+// the object it is filling in; a legacy zero-argument factory still fits.
+// ===========================================================================
+export {};

package/dist/builder/global-config-store.d.ts

@@ -0,0 +1,4 @@
+import { type GlobalConfig, type ResolvedGlobalConfig } from "../types/global-config";
+export declare function setGlobalConfig(config: GlobalConfig): void;
+export declare function getGlobalConfig(): ResolvedGlobalConfig;
+export declare function resetGlobalConfig(): void;

package/dist/builder/global-config-store.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setGlobalConfig = setGlobalConfig;
+exports.getGlobalConfig = getGlobalConfig;
+exports.resetGlobalConfig = resetGlobalConfig;
+// ===========================================================================
+// L6  src/builder/global-config-store.ts
+// RESIDUAL 4 / item 4, second half — the legacy process-wide accessors
+// (globalConfig / setGlobalConfig / getGlobalConfig / resetGlobalConfig) are
+// kept, but they are now a BUILD-TIME default source, not a runtime lookup.
+// Builder.build() reads this store once; from then on the built validator holds
+// its own frozen ResolvedGlobalConfig and later setGlobalConfig calls cannot
+// change how it behaves. That is the only difference from 1.x, and it is what
+// makes the config compatible with "pre-compute at build" (user decision 1).
+//
+// Lives at L6 rather than L0 so the vocabulary layer keeps its "zero mutable
+// state" property; the public export map can still surface it from the root.
+// ===========================================================================
+const global_config_1 = require("../types/global-config");
+let processConfig = global_config_1.DEFAULT_GLOBAL_CONFIG;
+function setGlobalConfig(config) {
+    processConfig = (0, global_config_1.resolveGlobalConfig)(config, processConfig);
+}
+function getGlobalConfig() {
+    return processConfig;
+}
+function resetGlobalConfig() {
+    processConfig = global_config_1.DEFAULT_GLOBAL_CONFIG;
+}

package/dist/builder/global-config-store.mjs

@@ -0,0 +1,24 @@
+// ===========================================================================
+// L6  src/builder/global-config-store.ts
+// RESIDUAL 4 / item 4, second half — the legacy process-wide accessors
+// (globalConfig / setGlobalConfig / getGlobalConfig / resetGlobalConfig) are
+// kept, but they are now a BUILD-TIME default source, not a runtime lookup.
+// Builder.build() reads this store once; from then on the built validator holds
+// its own frozen ResolvedGlobalConfig and later setGlobalConfig calls cannot
+// change how it behaves. That is the only difference from 1.x, and it is what
+// makes the config compatible with "pre-compute at build" (user decision 1).
+//
+// Lives at L6 rather than L0 so the vocabulary layer keeps its "zero mutable
+// state" property; the public export map can still surface it from the root.
+// ===========================================================================
+import { DEFAULT_GLOBAL_CONFIG, resolveGlobalConfig, } from "../types/global-config.mjs";
+let processConfig = DEFAULT_GLOBAL_CONFIG;
+export function setGlobalConfig(config) {
+    processConfig = resolveGlobalConfig(config, processConfig);
+}
+export function getGlobalConfig() {
+    return processConfig;
+}
+export function resetGlobalConfig() {
+    processConfig = DEFAULT_GLOBAL_CONFIG;
+}

package/dist/builder/index.d.ts

@@ -0,0 +1,6 @@
+export { Builder } from "./field-builder.types";
+export type { FieldBuilder, MissingFieldsError, UncoveredOf, } from "./field-builder.types";
+export { NamelessPluginError, createBuilder } from "./create-builder";
+export { getGlobalConfig, resetGlobalConfig, setGlobalConfig, } from "./global-config-store";
+export type { DefaultFactory, FieldOptions } from "./field-options.types";
+export type { FieldValidator, SubsetValidator, Validator, } from "./validator.types";

package/dist/builder/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setGlobalConfig = exports.resetGlobalConfig = exports.getGlobalConfig = exports.createBuilder = exports.NamelessPluginError = exports.Builder = void 0;
+// ===========================================================================
+// L6  src/builder/index.ts — re-exports only. Nothing is defined in this file.
+// `Builder` names both the entry point and its type; the two are one merged
+// declaration in ./field-builder.types.ts, so one export line carries both.
+// ===========================================================================
+var field_builder_types_1 = require("./field-builder.types");
+Object.defineProperty(exports, "Builder", { enumerable: true, get: function () { return field_builder_types_1.Builder; } });
+var create_builder_1 = require("./create-builder");
+Object.defineProperty(exports, "NamelessPluginError", { enumerable: true, get: function () { return create_builder_1.NamelessPluginError; } });
+Object.defineProperty(exports, "createBuilder", { enumerable: true, get: function () { return create_builder_1.createBuilder; } });
+var global_config_store_1 = require("./global-config-store");
+Object.defineProperty(exports, "getGlobalConfig", { enumerable: true, get: function () { return global_config_store_1.getGlobalConfig; } });
+Object.defineProperty(exports, "resetGlobalConfig", { enumerable: true, get: function () { return global_config_store_1.resetGlobalConfig; } });
+Object.defineProperty(exports, "setGlobalConfig", { enumerable: true, get: function () { return global_config_store_1.setGlobalConfig; } });

package/dist/builder/index.mjs

@@ -0,0 +1,8 @@
+// ===========================================================================
+// L6  src/builder/index.ts — re-exports only. Nothing is defined in this file.
+// `Builder` names both the entry point and its type; the two are one merged
+// declaration in ./field-builder.types.ts, so one export line carries both.
+// ===========================================================================
+export { Builder } from "./field-builder.types.mjs";
+export { NamelessPluginError, createBuilder } from "./create-builder.mjs";
+export { getGlobalConfig, resetGlobalConfig, setGlobalConfig, } from "./global-config-store.mjs";