@maroonedog/luq 0.1.2-alpha → 2.0.0

package/dist/async/async-context.d.ts

@@ -0,0 +1,41 @@
+import { readExternalContext } from "../plugin-kit/external-context";
+/**
+ * The 1.x `getAsyncContext(context)` accessor, kept under a verb-phrase name.
+ * The mechanism lives at L2 (see l2-external-context.ts) because plugins need
+ * it and a plugin may not import this layer; this is the public alias.
+ */
+export declare const readAsyncContext: typeof readExternalContext;
+export interface AsyncContextOptions {
+    /** Per-entry timeout in milliseconds. */
+    readonly timeout?: number;
+    /** Substituted when an entry rejects or times out. */
+    readonly defaultValues?: Readonly<Record<string, unknown>>;
+    /** When true, a failed entry still yields a ready context. */
+    readonly continueOnError?: boolean;
+}
+export interface AsyncContextFailure {
+    readonly key: string;
+    readonly reason: unknown;
+}
+export interface AsyncContext<C extends object> {
+    /** The typed view. */
+    readonly data: C;
+    /** The same object, as the untyped bag ValidateOptions.external accepts. */
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly isReady: boolean;
+    readonly hasErrors: boolean;
+    readonly failures: readonly AsyncContextFailure[];
+}
+/** Immutable: every `set` returns a new builder, so a shared prefix is safe. */
+export declare class AsyncContextBuilder<C extends object> {
+    private readonly entries;
+    private readonly options;
+    private constructor();
+    static start(): AsyncContextBuilder<Record<never, never>>;
+    set<K extends string, V>(key: K, promise: Promise<V>): AsyncContextBuilder<C & {
+        readonly [P in K]: V;
+    }>;
+    withOptions(options: AsyncContextOptions): AsyncContextBuilder<C>;
+    build(): Promise<AsyncContext<C>>;
+}
+export declare function createAsyncContext(): AsyncContextBuilder<Record<never, never>>;

package/dist/async/async-context.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncContextBuilder = exports.readAsyncContext = void 0;
+exports.createAsyncContext = createAsyncContext;
+// ===========================================================================
+// L9  src/async/async-context.ts
+// RESIDUAL 4 / item 1, first half. Legacy public shape, preserved verbatim:
+//   await createAsyncContext<C>().set(key, promise).build()
+// (docs/legacy-spec/documented-promises.md:226).
+//
+// This layer RESOLVES PROMISES AND NOTHING ELSE. No rule runs here; the
+// resolved bag leaves as a plain Readonly<Record<string, unknown>> and enters
+// validation through ValidateOptions.external, which L5 already forwards to
+// RuleContext.external. That is the whole async story: one await, then the
+// existing synchronous engine.
+// ===========================================================================
+const type_erasure_1 = require("../core/type-erasure");
+const external_context_1 = require("../plugin-kit/external-context");
+/**
+ * The 1.x `getAsyncContext(context)` accessor, kept under a verb-phrase name.
+ * The mechanism lives at L2 (see l2-external-context.ts) because plugins need
+ * it and a plugin may not import this layer; this is the public alias.
+ */
+exports.readAsyncContext = external_context_1.readExternalContext;
+function raceWithTimeout(promise, timeout, key) {
+    return Promise.race([
+        promise,
+        new Promise((_resolve, reject) => {
+            setTimeout(() => reject(new Error(`Async context entry timed out: ${key}`)), timeout);
+        }),
+    ]);
+}
+/** Immutable: every `set` returns a new builder, so a shared prefix is safe. */
+class AsyncContextBuilder {
+    constructor(entries, options) {
+        this.entries = entries;
+        this.options = options;
+    }
+    static start() {
+        return new AsyncContextBuilder([], {});
+    }
+    set(key, promise) {
+        return new AsyncContextBuilder([...this.entries, { key, promise }], this.options);
+    }
+    withOptions(options) {
+        return new AsyncContextBuilder(this.entries, {
+            ...this.options,
+            ...options,
+        });
+    }
+    async build() {
+        const values = {};
+        const failures = [];
+        const timeout = this.options.timeout;
+        const settled = await Promise.allSettled(this.entries.map((entry) => timeout === undefined
+            ? entry.promise
+            : raceWithTimeout(entry.promise, timeout, entry.key)));
+        settled.forEach((outcome, index) => {
+            const entry = this.entries[index];
+            if (entry === undefined)
+                return;
+            if (outcome.status === "fulfilled") {
+                values[entry.key] = outcome.value;
+                return;
+            }
+            failures.push({ key: entry.key, reason: outcome.reason });
+            const fallback = this.options.defaultValues?.[entry.key];
+            if (fallback !== undefined)
+                values[entry.key] = fallback;
+        });
+        const frozen = Object.freeze(values);
+        return {
+            data: (0, type_erasure_1.eraseAssembledRecord)(frozen),
+            values: frozen,
+            isReady: failures.length === 0 || this.options.continueOnError === true,
+            hasErrors: failures.length > 0,
+            failures: Object.freeze(failures),
+        };
+    }
+}
+exports.AsyncContextBuilder = AsyncContextBuilder;
+function createAsyncContext() {
+    return AsyncContextBuilder.start();
+}

package/dist/async/async-context.mjs

@@ -0,0 +1,79 @@
+// ===========================================================================
+// L9  src/async/async-context.ts
+// RESIDUAL 4 / item 1, first half. Legacy public shape, preserved verbatim:
+//   await createAsyncContext<C>().set(key, promise).build()
+// (docs/legacy-spec/documented-promises.md:226).
+//
+// This layer RESOLVES PROMISES AND NOTHING ELSE. No rule runs here; the
+// resolved bag leaves as a plain Readonly<Record<string, unknown>> and enters
+// validation through ValidateOptions.external, which L5 already forwards to
+// RuleContext.external. That is the whole async story: one await, then the
+// existing synchronous engine.
+// ===========================================================================
+import { eraseAssembledRecord } from "../core/type-erasure.mjs";
+import { readExternalContext } from "../plugin-kit/external-context.mjs";
+/**
+ * The 1.x `getAsyncContext(context)` accessor, kept under a verb-phrase name.
+ * The mechanism lives at L2 (see l2-external-context.ts) because plugins need
+ * it and a plugin may not import this layer; this is the public alias.
+ */
+export const readAsyncContext = readExternalContext;
+function raceWithTimeout(promise, timeout, key) {
+    return Promise.race([
+        promise,
+        new Promise((_resolve, reject) => {
+            setTimeout(() => reject(new Error(`Async context entry timed out: ${key}`)), timeout);
+        }),
+    ]);
+}
+/** Immutable: every `set` returns a new builder, so a shared prefix is safe. */
+export class AsyncContextBuilder {
+    constructor(entries, options) {
+        this.entries = entries;
+        this.options = options;
+    }
+    static start() {
+        return new AsyncContextBuilder([], {});
+    }
+    set(key, promise) {
+        return new AsyncContextBuilder([...this.entries, { key, promise }], this.options);
+    }
+    withOptions(options) {
+        return new AsyncContextBuilder(this.entries, {
+            ...this.options,
+            ...options,
+        });
+    }
+    async build() {
+        const values = {};
+        const failures = [];
+        const timeout = this.options.timeout;
+        const settled = await Promise.allSettled(this.entries.map((entry) => timeout === undefined
+            ? entry.promise
+            : raceWithTimeout(entry.promise, timeout, entry.key)));
+        settled.forEach((outcome, index) => {
+            const entry = this.entries[index];
+            if (entry === undefined)
+                return;
+            if (outcome.status === "fulfilled") {
+                values[entry.key] = outcome.value;
+                return;
+            }
+            failures.push({ key: entry.key, reason: outcome.reason });
+            const fallback = this.options.defaultValues?.[entry.key];
+            if (fallback !== undefined)
+                values[entry.key] = fallback;
+        });
+        const frozen = Object.freeze(values);
+        return {
+            data: eraseAssembledRecord(frozen),
+            values: frozen,
+            isReady: failures.length === 0 || this.options.continueOnError === true,
+            hasErrors: failures.length > 0,
+            failures: Object.freeze(failures),
+        };
+    }
+}
+export function createAsyncContext() {
+    return AsyncContextBuilder.start();
+}

package/dist/async/async-validator.d.ts

@@ -0,0 +1,20 @@
+import type { ValidateOptions, ValidationResult } from "../types/validation-result.types";
+import type { Validator } from "../builder/validator.types";
+import type { AsyncContext } from "./async-context";
+export declare const ASYNC_CONTEXT_ISSUE_CODE = "asyncContextUnavailable";
+/**
+ * What `withAsyncContext(ctx)` returns. `context` replaces 1.x's
+ * `getContextType()`, which existed only to recover the context type: here the
+ * context itself is on the object, so the type is reachable without a call.
+ */
+export interface AsyncBoundValidator<T extends object, C extends object> {
+    readonly context: AsyncContext<C>;
+    validate(value: unknown, options?: ValidateOptions): Promise<ValidationResult<T>>;
+    parse(value: unknown, options?: ValidateOptions): Promise<ValidationResult<T>>;
+}
+export interface AsyncAwareValidator<T extends object> extends Validator<T> {
+    withAsyncContext<C extends object>(context: AsyncContext<C>): AsyncBoundValidator<T, C>;
+}
+export declare function withAsyncContext<T extends object, C extends object>(validator: Validator<T>, context: AsyncContext<C>): AsyncBoundValidator<T, C>;
+/** The 1.x decorator name, kept. Adds the method without touching the core. */
+export declare function addAsyncSupport<T extends object>(validator: Validator<T>): AsyncAwareValidator<T>;

package/dist/async/async-validator.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASYNC_CONTEXT_ISSUE_CODE = void 0;
+exports.withAsyncContext = withAsyncContext;
+exports.addAsyncSupport = addAsyncSupport;
+exports.ASYNC_CONTEXT_ISSUE_CODE = "asyncContextUnavailable";
+function describeFailures(context) {
+    return context.failures.map((failure) => ({
+        path: failure.key,
+        code: exports.ASYNC_CONTEXT_ISSUE_CODE,
+        message: `Async context entry "${failure.key}" did not resolve.`,
+        severity: "error",
+    }));
+}
+function mergeExternal(context, options) {
+    return { ...options, external: { ...options?.external, ...context.values } };
+}
+function withAsyncContext(validator, context) {
+    return {
+        context,
+        async validate(value, options) {
+            if (!context.isReady)
+                return { valid: false, issues: describeFailures(context) };
+            return validator.validate(value, mergeExternal(context, options));
+        },
+        async parse(value, options) {
+            if (!context.isReady)
+                return { valid: false, issues: describeFailures(context) };
+            return validator.parse(value, mergeExternal(context, options));
+        },
+    };
+}
+/** The 1.x decorator name, kept. Adds the method without touching the core. */
+function addAsyncSupport(validator) {
+    return {
+        validate(value, options) {
+            return validator.validate(value, options);
+        },
+        parse(value, options) {
+            return validator.parse(value, options);
+        },
+        pick(key) {
+            return validator.pick(key);
+        },
+        pickAll(paths) {
+            return validator.pickAll(paths);
+        },
+        withAsyncContext(context) {
+            return withAsyncContext(validator, context);
+        },
+    };
+}

package/dist/async/async-validator.mjs

@@ -0,0 +1,47 @@
+export const ASYNC_CONTEXT_ISSUE_CODE = "asyncContextUnavailable";
+function describeFailures(context) {
+    return context.failures.map((failure) => ({
+        path: failure.key,
+        code: ASYNC_CONTEXT_ISSUE_CODE,
+        message: `Async context entry "${failure.key}" did not resolve.`,
+        severity: "error",
+    }));
+}
+function mergeExternal(context, options) {
+    return { ...options, external: { ...options?.external, ...context.values } };
+}
+export function withAsyncContext(validator, context) {
+    return {
+        context,
+        async validate(value, options) {
+            if (!context.isReady)
+                return { valid: false, issues: describeFailures(context) };
+            return validator.validate(value, mergeExternal(context, options));
+        },
+        async parse(value, options) {
+            if (!context.isReady)
+                return { valid: false, issues: describeFailures(context) };
+            return validator.parse(value, mergeExternal(context, options));
+        },
+    };
+}
+/** The 1.x decorator name, kept. Adds the method without touching the core. */
+export function addAsyncSupport(validator) {
+    return {
+        validate(value, options) {
+            return validator.validate(value, options);
+        },
+        parse(value, options) {
+            return validator.parse(value, options);
+        },
+        pick(key) {
+            return validator.pick(key);
+        },
+        pickAll(paths) {
+            return validator.pickAll(paths);
+        },
+        withAsyncContext(context) {
+            return withAsyncContext(validator, context);
+        },
+    };
+}

package/dist/async/index.d.ts

@@ -0,0 +1,4 @@
+export { AsyncContextBuilder, createAsyncContext, readAsyncContext, } from "./async-context";
+export type { AsyncContext, AsyncContextFailure, AsyncContextOptions, } from "./async-context";
+export { ASYNC_CONTEXT_ISSUE_CODE, addAsyncSupport, withAsyncContext, } from "./async-validator";
+export type { AsyncAwareValidator, AsyncBoundValidator, } from "./async-validator";

package/dist/async/index.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAsyncContext = exports.addAsyncSupport = exports.ASYNC_CONTEXT_ISSUE_CODE = exports.readAsyncContext = exports.createAsyncContext = exports.AsyncContextBuilder = void 0;
+// ===========================================================================
+// L9  src/async/index.ts — THE ./async SUBPATH. Re-exports only; nothing is
+// defined in this file.
+//
+// The whole subpath is one await followed by the ordinary synchronous engine.
+// It contains no rule, no plan, no loop over fields — deliberately, because a
+// second execution path is exactly how 1.x's async story died: the real
+// getAsyncContext-based branch existed but no call site reached it
+// (docs/legacy-spec/plugin-catalog-relational.md:76).
+//
+// So this layer imports the compiler and the runtime NOWHERE. It resolves a
+// promise map, hands the resolved bag to the validator it decorates through
+// ValidateOptions.external, and gets out of the way.
+// ===========================================================================
+var async_context_1 = require("./async-context");
+Object.defineProperty(exports, "AsyncContextBuilder", { enumerable: true, get: function () { return async_context_1.AsyncContextBuilder; } });
+Object.defineProperty(exports, "createAsyncContext", { enumerable: true, get: function () { return async_context_1.createAsyncContext; } });
+Object.defineProperty(exports, "readAsyncContext", { enumerable: true, get: function () { return async_context_1.readAsyncContext; } });
+var async_validator_1 = require("./async-validator");
+Object.defineProperty(exports, "ASYNC_CONTEXT_ISSUE_CODE", { enumerable: true, get: function () { return async_validator_1.ASYNC_CONTEXT_ISSUE_CODE; } });
+Object.defineProperty(exports, "addAsyncSupport", { enumerable: true, get: function () { return async_validator_1.addAsyncSupport; } });
+Object.defineProperty(exports, "withAsyncContext", { enumerable: true, get: function () { return async_validator_1.withAsyncContext; } });

package/dist/async/index.mjs

@@ -0,0 +1,16 @@
+// ===========================================================================
+// L9  src/async/index.ts — THE ./async SUBPATH. Re-exports only; nothing is
+// defined in this file.
+//
+// The whole subpath is one await followed by the ordinary synchronous engine.
+// It contains no rule, no plan, no loop over fields — deliberately, because a
+// second execution path is exactly how 1.x's async story died: the real
+// getAsyncContext-based branch existed but no call site reached it
+// (docs/legacy-spec/plugin-catalog-relational.md:76).
+//
+// So this layer imports the compiler and the runtime NOWHERE. It resolves a
+// promise map, hands the resolved bag to the validator it decorates through
+// ValidateOptions.external, and gets out of the way.
+// ===========================================================================
+export { AsyncContextBuilder, createAsyncContext, readAsyncContext, } from "./async-context.mjs";
+export { ASYNC_CONTEXT_ISSUE_CODE, addAsyncSupport, withAsyncContext, } from "./async-validator.mjs";

package/dist/async.d.ts

@@ -0,0 +1 @@
+export * from "./async/index";

package/dist/async.js

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./async/index");

package/dist/async.mjs

@@ -0,0 +1 @@
+export * from "./async/index.mjs";

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

@@ -0,0 +1,39 @@
+import type { AnyChain } from "../chain/field-chain.types";
+import type { FieldSlots } from "../chain/field-slots.types";
+import type { PluginBag } from "../chain/plugin-bag.types";
+import type { AnyPlugin } from "../plugin-kit/plugin-definition";
+import type { PlanFieldValidator } from "../runtime/create-field-validator";
+import type { GlobalConfig } from "../types/global-config";
+import type { ValidateOptions, ValidationResult } from "../types/validation-result.types";
+import type { FieldOptions } from "./field-options.types";
+/** The erased twin of SubsetValidator<TRoot, TPaths>. */
+export interface PlanSubsetValidator {
+    readonly paths: readonly string[];
+    validate(value: unknown, options?: ValidateOptions): ValidationResult<unknown>;
+}
+/** The erased twin of Validator<T>: the same four members. */
+export interface PlanBackedValidator {
+    validate(value: unknown, options?: ValidateOptions): ValidationResult<unknown>;
+    parse(value: unknown, options?: ValidateOptions): ValidationResult<unknown>;
+    pick(key: string): PlanFieldValidator;
+    pickAll(paths: readonly string[]): PlanSubsetValidator;
+}
+/** What `.v()` is handed. Erased on both ends: any root, any field type. */
+export type ErasedFieldDefine = (slots: FieldSlots<unknown, PluginBag, unknown>) => AnyChain;
+/**
+ * The erased twin of FieldBuilder<T, B, TDeclared>. `v` returns a NEW surface —
+ * the declaration list is never mutated — and `strict` returns the receiver,
+ * because strictness is a type-level obligation with no runtime effect
+ * (docs/legacy-spec/documented-promises.md, strict()).
+ */
+export interface FieldBuilderSurface {
+    v(path: string, define: ErasedFieldDefine, options?: FieldOptions<unknown>): FieldBuilderSurface;
+    strict(): FieldBuilderSurface;
+    build(): PlanBackedValidator;
+}
+/** The erased twin of Builder<B>. `use` mutates and returns the receiver. */
+export interface BuilderSurface {
+    use(plugin: AnyPlugin): BuilderSurface;
+    withConfig(config: GlobalConfig): BuilderSurface;
+    for(): FieldBuilderSurface;
+}

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

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

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

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

package/dist/builder/compile-declarations.d.ts

@@ -0,0 +1,4 @@
+import type { ValidationPlan } from "../compile/validation-plan.types";
+import type { GlobalConfig } from "../types/global-config";
+import type { FieldEntry } from "./field-entry.types";
+export declare function compileDeclarations(entries: readonly FieldEntry[], configOverride: GlobalConfig | undefined): ValidationPlan;

package/dist/builder/compile-declarations.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileDeclarations = compileDeclarations;
+// ===========================================================================
+// L6  src/builder/compile-declarations.ts — WHAT build() ACTUALLY DOES.
+//
+// Four things, once, in this order:
+//   1. resolve the effective GlobalConfig — ONCE. The process-wide store is
+//      read here and nowhere else, so a later setGlobalConfig() cannot change
+//      how an already-built validator behaves, and no rule reads a global at
+//      validation time (user decision 1).
+//   2. index the declared child keys from the declared PATH STRINGS, so
+//      RuleBuildContext.declaredSiblingKeys is known before any callback runs.
+//   3. run every `.v()` callback EXACTLY ONCE, through the L3 collector.
+//   4. compile the declarations into one plan, wired to the one BranchExecutor.
+//
+// L6 is the only layer that may know both L4 and L5, which is why the port is
+// wired here: compileSchema takes the executor as a required argument and
+// compile/ therefore never grows a traversal of its own.
+// ===========================================================================
+const compile_schema_1 = require("../compile/compile-schema");
+const declared_child_keys_1 = require("../compile/declared-child-keys");
+const run_branch_1 = require("../runtime/run-branch");
+const global_config_1 = require("../types/global-config");
+const global_config_store_1 = require("./global-config-store");
+function compileDeclarations(entries, configOverride) {
+    const config = (0, global_config_1.resolveGlobalConfig)(configOverride, (0, global_config_store_1.getGlobalConfig)());
+    const childKeysOf = (0, declared_child_keys_1.indexDeclaredChildKeys)(entries.map((entry) => entry.path));
+    const declarations = entries.map((entry) => ({
+        path: entry.path,
+        rules: entry.collectRules({
+            fieldPath: entry.path,
+            declaredSiblingKeys: childKeysOf(entry.path),
+            config,
+        }),
+        defaultOf: entry.defaultOf ?? undefined,
+        applyDefaultToNull: entry.applyDefaultToNull,
+    }));
+    return (0, compile_schema_1.compileSchema)(declarations, (0, run_branch_1.createBranchExecutor)());
+}

package/dist/builder/compile-declarations.mjs

@@ -0,0 +1,37 @@
+// ===========================================================================
+// L6  src/builder/compile-declarations.ts — WHAT build() ACTUALLY DOES.
+//
+// Four things, once, in this order:
+//   1. resolve the effective GlobalConfig — ONCE. The process-wide store is
+//      read here and nowhere else, so a later setGlobalConfig() cannot change
+//      how an already-built validator behaves, and no rule reads a global at
+//      validation time (user decision 1).
+//   2. index the declared child keys from the declared PATH STRINGS, so
+//      RuleBuildContext.declaredSiblingKeys is known before any callback runs.
+//   3. run every `.v()` callback EXACTLY ONCE, through the L3 collector.
+//   4. compile the declarations into one plan, wired to the one BranchExecutor.
+//
+// L6 is the only layer that may know both L4 and L5, which is why the port is
+// wired here: compileSchema takes the executor as a required argument and
+// compile/ therefore never grows a traversal of its own.
+// ===========================================================================
+import { compileSchema } from "../compile/compile-schema.mjs";
+import { indexDeclaredChildKeys } from "../compile/declared-child-keys.mjs";
+import { createBranchExecutor } from "../runtime/run-branch.mjs";
+import { resolveGlobalConfig } from "../types/global-config.mjs";
+import { getGlobalConfig } from "./global-config-store.mjs";
+export function compileDeclarations(entries, configOverride) {
+    const config = resolveGlobalConfig(configOverride, getGlobalConfig());
+    const childKeysOf = indexDeclaredChildKeys(entries.map((entry) => entry.path));
+    const declarations = entries.map((entry) => ({
+        path: entry.path,
+        rules: entry.collectRules({
+            fieldPath: entry.path,
+            declaredSiblingKeys: childKeysOf(entry.path),
+            config,
+        }),
+        defaultOf: entry.defaultOf ?? undefined,
+        applyDefaultToNull: entry.applyDefaultToNull,
+    }));
+    return compileSchema(declarations, createBranchExecutor());
+}

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

@@ -0,0 +1,16 @@
+import type { BuilderSurface } from "./builder-surface.types";
+import type * as fieldBuilderTypes from "./field-builder.types";
+/** `use()` given something that is not a plugin. Named, and thrown at once:
+ *  legacy swallowed it and produced a validator that permitted everything. */
+export declare class NamelessPluginError extends Error {
+    readonly received: unknown;
+    constructor(received: unknown);
+}
+/**
+ * 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 declare function createBuilder(): fieldBuilderTypes.Builder;
+export declare function createBuilderSurface(): BuilderSurface;

package/dist/builder/create-builder.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NamelessPluginError = void 0;
+exports.createBuilder = createBuilder;
+exports.createBuilderSurface = createBuilderSurface;
+// ===========================================================================
+// 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.
+// ===========================================================================
+const type_erasure_1 = require("../core/type-erasure");
+const types_1 = require("../types");
+const create_field_builder_1 = require("./create-field-builder");
+/** `use()` given something that is not a plugin. Named, and thrown at once:
+ *  legacy swallowed it and produced a validator that permitted everything. */
+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";
+    }
+}
+exports.NamelessPluginError = 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.
+ */
+function createBuilder() {
+    return (0, type_erasure_1.eraseBuilderSurface)(createBuilderSurface());
+}
+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: () => (0, create_field_builder_1.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 (!(0, types_1.isPlainObject)(candidate))
+        return false;
+    const name = candidate["name"];
+    return ((0, types_1.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 ((0, types_1.isPlainObject)(received))
+        return `an object with no name`;
+    return typeof received;
+}