@maroonedog/luq 0.1.1-alpha → 2.0.0

package/dist/compile/split-rules-by-kind.d.ts

@@ -0,0 +1,16 @@
+import type { CheckRule, CompositeRule, ConditionalPresenceRule, GateRule, PresenceRule, RecursiveRule, Rule, TransformRule } from "../plugin-kit/compiled-rule";
+export interface RulesByKind {
+    readonly checks: readonly CheckRule[];
+    readonly presences: readonly PresenceRule[];
+    readonly conditionalPresences: readonly ConditionalPresenceRule[];
+    readonly gates: readonly GateRule[];
+    readonly transforms: readonly TransformRule[];
+    readonly composites: readonly CompositeRule[];
+    readonly recursions: readonly RecursiveRule[];
+}
+/** Thrown when a value shaped like a Rule carries a kind the union forbids. */
+export declare class UnknownRuleKindError extends Error {
+    readonly received: unknown;
+    constructor(received: unknown);
+}
+export declare function splitRulesByKind(rules: readonly Rule[]): RulesByKind;

package/dist/compile/split-rules-by-kind.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownRuleKindError = void 0;
+exports.splitRulesByKind = splitRulesByKind;
+/** Thrown when a value shaped like a Rule carries a kind the union forbids. */
+class UnknownRuleKindError extends Error {
+    constructor(received) {
+        super(`A rule of an unknown kind reached compilation: ${describeRule(received)}`);
+        this.received = received;
+        this.name = "UnknownRuleKindError";
+    }
+}
+exports.UnknownRuleKindError = UnknownRuleKindError;
+function splitRulesByKind(rules) {
+    const checks = [];
+    const presences = [];
+    const conditionalPresences = [];
+    const gates = [];
+    const transforms = [];
+    const composites = [];
+    const recursions = [];
+    for (const rule of rules) {
+        if (rule.kind === "check")
+            checks.push(rule);
+        else if (rule.kind === "presence")
+            presences.push(rule);
+        else if (rule.kind === "conditionalPresence")
+            conditionalPresences.push(rule);
+        else if (rule.kind === "gate")
+            gates.push(rule);
+        else if (rule.kind === "transform")
+            transforms.push(rule);
+        else if (rule.kind === "composite")
+            composites.push(rule);
+        else if (rule.kind === "recursive")
+            recursions.push(rule);
+        else
+            rejectUnknownRuleKind(rule);
+    }
+    return Object.freeze({
+        checks: Object.freeze(checks),
+        presences: Object.freeze(presences),
+        conditionalPresences: Object.freeze(conditionalPresences),
+        gates: Object.freeze(gates),
+        transforms: Object.freeze(transforms),
+        composites: Object.freeze(composites),
+        recursions: Object.freeze(recursions),
+    });
+}
+/** The exhaustiveness proof: the parameter is `never`, so an eighth kind is a
+ *  compile error at the call site and not a run-time surprise. */
+function rejectUnknownRuleKind(rule) {
+    throw new UnknownRuleKindError(rule);
+}
+function describeRule(received) {
+    if (typeof received !== "object" || received === null) {
+        return String(received);
+    }
+    const kind = Reflect.get(received, "kind");
+    return typeof kind === "string" ? JSON.stringify(kind) : "(no kind)";
+}

package/dist/compile/split-rules-by-kind.mjs

@@ -0,0 +1,56 @@
+/** Thrown when a value shaped like a Rule carries a kind the union forbids. */
+export class UnknownRuleKindError extends Error {
+    constructor(received) {
+        super(`A rule of an unknown kind reached compilation: ${describeRule(received)}`);
+        this.received = received;
+        this.name = "UnknownRuleKindError";
+    }
+}
+export function splitRulesByKind(rules) {
+    const checks = [];
+    const presences = [];
+    const conditionalPresences = [];
+    const gates = [];
+    const transforms = [];
+    const composites = [];
+    const recursions = [];
+    for (const rule of rules) {
+        if (rule.kind === "check")
+            checks.push(rule);
+        else if (rule.kind === "presence")
+            presences.push(rule);
+        else if (rule.kind === "conditionalPresence")
+            conditionalPresences.push(rule);
+        else if (rule.kind === "gate")
+            gates.push(rule);
+        else if (rule.kind === "transform")
+            transforms.push(rule);
+        else if (rule.kind === "composite")
+            composites.push(rule);
+        else if (rule.kind === "recursive")
+            recursions.push(rule);
+        else
+            rejectUnknownRuleKind(rule);
+    }
+    return Object.freeze({
+        checks: Object.freeze(checks),
+        presences: Object.freeze(presences),
+        conditionalPresences: Object.freeze(conditionalPresences),
+        gates: Object.freeze(gates),
+        transforms: Object.freeze(transforms),
+        composites: Object.freeze(composites),
+        recursions: Object.freeze(recursions),
+    });
+}
+/** The exhaustiveness proof: the parameter is `never`, so an eighth kind is a
+ *  compile error at the call site and not a run-time surprise. */
+function rejectUnknownRuleKind(rule) {
+    throw new UnknownRuleKindError(rule);
+}
+function describeRule(received) {
+    if (typeof received !== "object" || received === null) {
+        return String(received);
+    }
+    const kind = Reflect.get(received, "kind");
+    return typeof kind === "string" ? JSON.stringify(kind) : "(no kind)";
+}

package/dist/compile/validation-plan.types.d.ts

@@ -0,0 +1,113 @@
+import type { ArrayItemContext, CheckOutcome, IssueDetail, IssueSeverity, MessageContext, RuleContext } from "../types";
+import type { PathSegment } from "../path/path-segment.types";
+import type { ValueWriter } from "../path/create-value-writer";
+import type { GateRule, RecursionTarget, Rule, TransformRule } from "../plugin-kit/compiled-rule";
+/**
+ * A check after compilation. A CheckRule already has this exact shape.
+ *
+ * `severity` is carried, not dropped: ValidationIssue.severity is not optional
+ * and the chain resolved it once at build time. A CompiledCheck without it
+ * would force L5 to invent a fallback, which is precisely the second
+ * resolution site that makes an override stop working.
+ */
+export interface CompiledCheck {
+    readonly code: string;
+    readonly severity: IssueSeverity;
+    run(value: unknown, ctx: RuleContext): CheckOutcome;
+    describe(detail: IssueDetail, ctx: MessageContext): string;
+}
+/** Every PresenceRule on a field, merged into one order-independent policy. */
+export interface PresencePolicy {
+    readonly code: string;
+    readonly severity: IssueSeverity;
+    readonly allowUndefined: boolean;
+    readonly allowNull: boolean;
+    readonly emptyStringIsMissing: boolean;
+    describe(ctx: MessageContext): string;
+}
+/**
+ * Two finished policies and the predicate that picks between them.
+ *
+ * Both sides are built ONCE, at compile time. The run time evaluates `when`
+ * and takes a reference — it never merges flags, allocates a policy, or looks
+ * at a rule kind. A null side leaves whatever policy is standing in place, so
+ * a conditional rule can decline to have an opinion instead of having to
+ * fabricate a permissive policy that would erase the field's `.required()`.
+ */
+export interface ConditionalPresence {
+    when(root: unknown, arrayContext?: ArrayItemContext): boolean;
+    readonly whenMet: PresencePolicy | null;
+    readonly whenUnmet: PresencePolicy | null;
+}
+/** Late-bound reference to the plan a RecursiveRule re-enters. compileSchema
+ *  creates the holder BEFORE compiling its fields and fills it afterwards, so a
+ *  self-referential plan needs no forward declaration and no cast. */
+export interface PlanRef {
+    resolve(): ValidationPlan;
+}
+export interface RecursionPolicy {
+    readonly code: string;
+    readonly severity: IssueSeverity;
+    readonly target: RecursionTarget;
+    readonly maxDepth: number;
+    readonly plan: PlanRef;
+    describe(detail: IssueDetail, ctx: MessageContext): string;
+}
+export interface CompiledField {
+    readonly template: readonly PathSegment[];
+    readonly read: (subject: unknown) => unknown;
+    /**
+     * null unless the field declared a transform or a default — the runtime then
+     * skips the writer without asking why.
+     *
+     * It returns the NEW root rather than `void`: the writer is copy-on-write
+     * (src/path/create-value-writer.ts) and cannot report its result through the
+     * argument it refused to mutate.
+     */
+    readonly write: ValueWriter | null;
+    readonly defaultOf: ((root: unknown) => unknown) | null;
+    readonly applyDefaultToNull: boolean;
+    readonly presence: PresencePolicy;
+    /**
+     * The conditional overrides of `presence`, in declaration order, and the
+     * shared frozen empty array on every field that declared none — which is
+     * almost all of them, so the runtime's whole cost is one length test.
+     * A later applicable override wins over an earlier one.
+     */
+    readonly presenceOverrides: readonly ConditionalPresence[];
+    readonly gates: readonly GateRule[];
+    /** Composites are already erased into this list, in declaration order. */
+    readonly checks: readonly CompiledCheck[];
+    readonly transforms: readonly TransformRule[];
+    /** null for every field that declared no RecursiveRule, i.e. almost all. */
+    readonly recursion: RecursionPolicy | null;
+}
+/** Loop interchange: one array is read once however many element fields exist. */
+export interface ArrayNode {
+    readonly template: readonly PathSegment[];
+    readonly read: (subject: unknown) => unknown;
+    readonly elementFields: readonly CompiledField[];
+    readonly nested: readonly ArrayNode[];
+}
+export interface ValidationPlan {
+    readonly fields: readonly CompiledField[];
+    readonly arrays: readonly ArrayNode[];
+    readonly hasTransforms: boolean;
+    readonly hasDefaults: boolean;
+}
+/**
+ * What the chain collector hands compile: one path, its ordered rules, and the
+ * field options that are NOT rules.
+ *
+ * `defaultOf` / `applyDefaultToNull` come from `.v()`'s third argument, which
+ * is a field configuration and never a Rule — there is no "default" rule kind
+ * to carry them. Both are optional so a declaration that has neither stays
+ * `{ path, rules }`; compileField reads the documented fallbacks (no default,
+ * and `applyDefaultToNull` true).
+ */
+export interface FieldDeclaration {
+    readonly path: string;
+    readonly rules: readonly Rule[];
+    readonly defaultOf?: (root: unknown) => unknown;
+    readonly applyDefaultToNull?: boolean;
+}

package/dist/compile/validation-plan.types.js

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

package/dist/compile/validation-plan.types.mjs

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

package/dist/core/type-erasure.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 理由: 動的にキーを積み上げて組み立てたレコードは、実行時にはキーが揃って
+ * いても静的には Record<string, unknown> 止まりになる。呼び出し側のジェネリク
+ * ス（AsyncContextBuilder.set の `C & { [P in K]: V }`）が、そのキーと値の対応
+ * を型として保証している。
+ */
+export declare function eraseAssembledRecord<T extends object>(assembled: Readonly<Record<string, unknown>>): T;
+/**
+ * 理由: チェーンの実体は「バッグに入っているプラグインの数だけメソッドを生やした
+ * レコード」で、実行時にはキーが揃っていても静的には Record<string, unknown> 止まり
+ * になる。対応する型 FieldSlots / FieldChain は SlotPlugins によるマップ型なので、
+ * 「どのキーが生えるか」は型引数 B と S からしか決まらず、値の組み立て側では書けない。
+ * 正しさは attachSlotMethods が SlotPlugins と同じ規則（plugin.slots に S を含む
+ * プラグインの plugin.method だけを生やす）で組み立てていることに依存する。
+ */
+export declare function eraseChainSurface<T extends object>(assembled: Readonly<Record<string, unknown>>): T;
+/**
+ * 理由: ビルダー連鎖の実体は「use で積んだプラグイン」「v で積んだ宣言」を持つ
+ * 1 つのレコードで、実行時には段が進んでも同じ形のまま変わらない。一方その静的
+ * な型は、段ごとの型引数（バッグの交差 B & BagEntry<P>、宣言済みパスの和
+ * TDeclared | K、union guard の網羅で分岐する条件型）でしか書けず、組み立て側に
+ * はその型を書く手段が無い。同じ理由で、L5 の createValidator はプランしか知らな
+ * いので ValidationResult<unknown> しか返せず、宣言された T を戻せるのはこの
+ * 境界だけである。
+ * 正しさは、erased 側（src/builder/builder-surface.types.ts）が宣言型と同じ
+ * メンバー集合を型として持ち、実装がそれに構造的に適合していることに依存する。
+ * src/ 全体でこの関数の呼び出しは 1 箇所（src/builder/create-builder.ts）だけ。
+ */
+export declare function eraseBuilderSurface<T extends object>(assembled: object): T;
+/**
+ * 理由: fromJsonSchema<T>() は「実行時に読み込んだ JSON Schema」から検証器を作る。
+ * ドキュメントは実行時の値なので、宣言された T との対応をコンパイラが検査できる
+ * 材料は原理的に存在しない。L5 の PlanBackedValidator はプランしか知らず
+ * ValidationResult<unknown> しか返せないので、呼び出し側が明示した T を戻せるのは
+ * この境界だけである — eraseBuilderSurface と同じ性質の消去であり、同じ場所に置く。
+ * 正しさは、PlanBackedValidator（src/builder/builder-surface.types.ts）が
+ * Validator<T> と同じメンバー集合を持ち、実装がそれに構造的に適合していることに
+ * 依存する。T が実際のドキュメントと食い違っていた場合、型は嘘をつくが実行時の
+ * 検証結果は正しい: build-from-schema.ts の見出しがその逃げ道を明記している。
+ * src/ 全体でこの関数の呼び出しは 1 箇所（src/json-schema/build-from-schema.ts）だけ。
+ */
+export declare function eraseSchemaValidator<T>(planBacked: object): T;

package/dist/core/type-erasure.js

@@ -0,0 +1,63 @@
+"use strict";
+// ===========================================================================
+// src/core/type-erasure.ts — THE ONLY FILE PERMITTED TO ASSERT A TYPE.
+// The code standard names this file by hand; everything else in src/ must reach
+// a type by writing it, by a `unknown` + type-guard pair, or by a discriminated
+// union. Every function here carries its own reason, so a reviewer can audit
+// the whole escape hatch in one file.
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eraseAssembledRecord = eraseAssembledRecord;
+exports.eraseChainSurface = eraseChainSurface;
+exports.eraseBuilderSurface = eraseBuilderSurface;
+exports.eraseSchemaValidator = eraseSchemaValidator;
+/**
+ * 理由: 動的にキーを積み上げて組み立てたレコードは、実行時にはキーが揃って
+ * いても静的には Record<string, unknown> 止まりになる。呼び出し側のジェネリク
+ * ス（AsyncContextBuilder.set の `C & { [P in K]: V }`）が、そのキーと値の対応
+ * を型として保証している。
+ */
+function eraseAssembledRecord(assembled) {
+    return assembled;
+}
+/**
+ * 理由: チェーンの実体は「バッグに入っているプラグインの数だけメソッドを生やした
+ * レコード」で、実行時にはキーが揃っていても静的には Record<string, unknown> 止まり
+ * になる。対応する型 FieldSlots / FieldChain は SlotPlugins によるマップ型なので、
+ * 「どのキーが生えるか」は型引数 B と S からしか決まらず、値の組み立て側では書けない。
+ * 正しさは attachSlotMethods が SlotPlugins と同じ規則（plugin.slots に S を含む
+ * プラグインの plugin.method だけを生やす）で組み立てていることに依存する。
+ */
+function eraseChainSurface(assembled) {
+    return assembled;
+}
+/**
+ * 理由: ビルダー連鎖の実体は「use で積んだプラグイン」「v で積んだ宣言」を持つ
+ * 1 つのレコードで、実行時には段が進んでも同じ形のまま変わらない。一方その静的
+ * な型は、段ごとの型引数（バッグの交差 B & BagEntry<P>、宣言済みパスの和
+ * TDeclared | K、union guard の網羅で分岐する条件型）でしか書けず、組み立て側に
+ * はその型を書く手段が無い。同じ理由で、L5 の createValidator はプランしか知らな
+ * いので ValidationResult<unknown> しか返せず、宣言された T を戻せるのはこの
+ * 境界だけである。
+ * 正しさは、erased 側（src/builder/builder-surface.types.ts）が宣言型と同じ
+ * メンバー集合を型として持ち、実装がそれに構造的に適合していることに依存する。
+ * src/ 全体でこの関数の呼び出しは 1 箇所（src/builder/create-builder.ts）だけ。
+ */
+function eraseBuilderSurface(assembled) {
+    return assembled;
+}
+/**
+ * 理由: fromJsonSchema<T>() は「実行時に読み込んだ JSON Schema」から検証器を作る。
+ * ドキュメントは実行時の値なので、宣言された T との対応をコンパイラが検査できる
+ * 材料は原理的に存在しない。L5 の PlanBackedValidator はプランしか知らず
+ * ValidationResult<unknown> しか返せないので、呼び出し側が明示した T を戻せるのは
+ * この境界だけである — eraseBuilderSurface と同じ性質の消去であり、同じ場所に置く。
+ * 正しさは、PlanBackedValidator（src/builder/builder-surface.types.ts）が
+ * Validator<T> と同じメンバー集合を持ち、実装がそれに構造的に適合していることに
+ * 依存する。T が実際のドキュメントと食い違っていた場合、型は嘘をつくが実行時の
+ * 検証結果は正しい: build-from-schema.ts の見出しがその逃げ道を明記している。
+ * src/ 全体でこの関数の呼び出しは 1 箇所（src/json-schema/build-from-schema.ts）だけ。
+ */
+function eraseSchemaValidator(planBacked) {
+    return planBacked;
+}

package/dist/core/type-erasure.mjs

@@ -0,0 +1,57 @@
+// ===========================================================================
+// src/core/type-erasure.ts — THE ONLY FILE PERMITTED TO ASSERT A TYPE.
+// The code standard names this file by hand; everything else in src/ must reach
+// a type by writing it, by a `unknown` + type-guard pair, or by a discriminated
+// union. Every function here carries its own reason, so a reviewer can audit
+// the whole escape hatch in one file.
+// ===========================================================================
+/**
+ * 理由: 動的にキーを積み上げて組み立てたレコードは、実行時にはキーが揃って
+ * いても静的には Record<string, unknown> 止まりになる。呼び出し側のジェネリク
+ * ス（AsyncContextBuilder.set の `C & { [P in K]: V }`）が、そのキーと値の対応
+ * を型として保証している。
+ */
+export function eraseAssembledRecord(assembled) {
+    return assembled;
+}
+/**
+ * 理由: チェーンの実体は「バッグに入っているプラグインの数だけメソッドを生やした
+ * レコード」で、実行時にはキーが揃っていても静的には Record<string, unknown> 止まり
+ * になる。対応する型 FieldSlots / FieldChain は SlotPlugins によるマップ型なので、
+ * 「どのキーが生えるか」は型引数 B と S からしか決まらず、値の組み立て側では書けない。
+ * 正しさは attachSlotMethods が SlotPlugins と同じ規則（plugin.slots に S を含む
+ * プラグインの plugin.method だけを生やす）で組み立てていることに依存する。
+ */
+export function eraseChainSurface(assembled) {
+    return assembled;
+}
+/**
+ * 理由: ビルダー連鎖の実体は「use で積んだプラグイン」「v で積んだ宣言」を持つ
+ * 1 つのレコードで、実行時には段が進んでも同じ形のまま変わらない。一方その静的
+ * な型は、段ごとの型引数（バッグの交差 B & BagEntry<P>、宣言済みパスの和
+ * TDeclared | K、union guard の網羅で分岐する条件型）でしか書けず、組み立て側に
+ * はその型を書く手段が無い。同じ理由で、L5 の createValidator はプランしか知らな
+ * いので ValidationResult<unknown> しか返せず、宣言された T を戻せるのはこの
+ * 境界だけである。
+ * 正しさは、erased 側（src/builder/builder-surface.types.ts）が宣言型と同じ
+ * メンバー集合を型として持ち、実装がそれに構造的に適合していることに依存する。
+ * src/ 全体でこの関数の呼び出しは 1 箇所（src/builder/create-builder.ts）だけ。
+ */
+export function eraseBuilderSurface(assembled) {
+    return assembled;
+}
+/**
+ * 理由: fromJsonSchema<T>() は「実行時に読み込んだ JSON Schema」から検証器を作る。
+ * ドキュメントは実行時の値なので、宣言された T との対応をコンパイラが検査できる
+ * 材料は原理的に存在しない。L5 の PlanBackedValidator はプランしか知らず
+ * ValidationResult<unknown> しか返せないので、呼び出し側が明示した T を戻せるのは
+ * この境界だけである — eraseBuilderSurface と同じ性質の消去であり、同じ場所に置く。
+ * 正しさは、PlanBackedValidator（src/builder/builder-surface.types.ts）が
+ * Validator<T> と同じメンバー集合を持ち、実装がそれに構造的に適合していることに
+ * 依存する。T が実際のドキュメントと食い違っていた場合、型は嘘をつくが実行時の
+ * 検証結果は正しい: build-from-schema.ts の見出しがその逃げ道を明記している。
+ * src/ 全体でこの関数の呼び出しは 1 箇所（src/json-schema/build-from-schema.ts）だけ。
+ */
+export function eraseSchemaValidator(planBacked) {
+    return planBacked;
+}

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

@@ -0,0 +1,11 @@
+import type { Builder } from "../builder/field-builder.types";
+import type { PluginBag } from "../chain/plugin-bag.types";
+import type { FieldRule, FieldRuleDefine, FieldRuleOptions } from "./field-rule.types";
+/**
+ * The single declared path of the standalone subject, and the default rule
+ * name. A rule is not attached to a place yet, so every issue it reports on its
+ * own comes back under this path; spliced into an object by useField() the very
+ * same rules report under the path that useField was given.
+ */
+export declare const FIELD_RULE_SUBJECT_KEY = "value";
+export declare function createFieldRule<TValue, B extends PluginBag>(builder: Builder<B>, define: FieldRuleDefine<TValue, B>, options?: FieldRuleOptions<TValue>): FieldRule<TValue, B>;

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIELD_RULE_SUBJECT_KEY = void 0;
+exports.createFieldRule = createFieldRule;
+/**
+ * The single declared path of the standalone subject, and the default rule
+ * name. A rule is not attached to a place yet, so every issue it reports on its
+ * own comes back under this path; spliced into an object by useField() the very
+ * same rules report under the path that useField was given.
+ */
+exports.FIELD_RULE_SUBJECT_KEY = "value";
+/**
+ * `.v()` is reached with C inferred as AnyChain, so its union-guard conditional
+ * resolves and `.build()` is present. That is what lets this whole file hold no
+ * type assertion: the typed Validator comes from the builder's own single
+ * erasure, not from a second one here.
+ */
+function buildSubjectValidator(builder, define, fieldOptions) {
+    return builder
+        .for()
+        .v(exports.FIELD_RULE_SUBJECT_KEY, define, fieldOptions)
+        .build();
+}
+function createFieldRule(builder, define, options) {
+    const fieldOptions = options?.fieldOptions;
+    const validator = buildSubjectValidator(builder, define, fieldOptions);
+    const rule = {
+        name: options?.name ?? exports.FIELD_RULE_SUBJECT_KEY,
+        description: options?.description,
+        define,
+        fieldOptions,
+        validate(value, validateOptions) {
+            const outcome = validator.validate({ value }, validateOptions);
+            if (!outcome.valid)
+                return { valid: false, issues: outcome.issues };
+            return { valid: true, data: value, issues: outcome.issues };
+        },
+        parse(value, validateOptions) {
+            const outcome = validator.parse({ value }, validateOptions);
+            if (!outcome.valid)
+                return { valid: false, issues: outcome.issues };
+            return {
+                valid: true,
+                data: outcome.data.value,
+                issues: outcome.issues,
+            };
+        },
+    };
+    return Object.freeze(rule);
+}

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

@@ -0,0 +1,46 @@
+/**
+ * The single declared path of the standalone subject, and the default rule
+ * name. A rule is not attached to a place yet, so every issue it reports on its
+ * own comes back under this path; spliced into an object by useField() the very
+ * same rules report under the path that useField was given.
+ */
+export const FIELD_RULE_SUBJECT_KEY = "value";
+/**
+ * `.v()` is reached with C inferred as AnyChain, so its union-guard conditional
+ * resolves and `.build()` is present. That is what lets this whole file hold no
+ * type assertion: the typed Validator comes from the builder's own single
+ * erasure, not from a second one here.
+ */
+function buildSubjectValidator(builder, define, fieldOptions) {
+    return builder
+        .for()
+        .v(FIELD_RULE_SUBJECT_KEY, define, fieldOptions)
+        .build();
+}
+export function createFieldRule(builder, define, options) {
+    const fieldOptions = options?.fieldOptions;
+    const validator = buildSubjectValidator(builder, define, fieldOptions);
+    const rule = {
+        name: options?.name ?? FIELD_RULE_SUBJECT_KEY,
+        description: options?.description,
+        define,
+        fieldOptions,
+        validate(value, validateOptions) {
+            const outcome = validator.validate({ value }, validateOptions);
+            if (!outcome.valid)
+                return { valid: false, issues: outcome.issues };
+            return { valid: true, data: value, issues: outcome.issues };
+        },
+        parse(value, validateOptions) {
+            const outcome = validator.parse({ value }, validateOptions);
+            if (!outcome.valid)
+                return { valid: false, issues: outcome.issues };
+            return {
+                valid: true,
+                data: outcome.data.value,
+                issues: outcome.issues,
+            };
+        },
+    };
+    return Object.freeze(rule);
+}

package/dist/field-rule/create-plugin-registry.d.ts

@@ -0,0 +1,2 @@
+import type { PluginRegistry } from "./plugin-registry.types";
+export declare function createPluginRegistry(): PluginRegistry<Record<never, never>>;

package/dist/field-rule/create-plugin-registry.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPluginRegistry = createPluginRegistry;
+// ===========================================================================
+// src/field-rule/create-plugin-registry.ts — the IMMUTABLE plugin bag.
+//
+// A registry holds a THUNK that replays `use()` onto a fresh Builder, never a
+// Builder it hands out. Builder.use() mutates its receiver, so a stored builder
+// would make `base.use(a)` and `base.use(b)` land in the same object and every
+// branch of a shared base would see every other branch's plugins. Replaying is
+// O(n) per branch at BUILD time only, and it is the whole of the immutability
+// guarantee (docs/legacy-spec/plugin-contract.md:114).
+//
+// The thunk also carries the type: `makeBuilder().use(plugin)` is already
+// `Builder<B & BagEntry<P>>`, so the growing bag type is produced by the
+// builder's own signature and this file holds no assertion.
+// ===========================================================================
+const field_builder_types_1 = require("../builder/field-builder.types");
+const create_field_rule_1 = require("./create-field-rule");
+/** First-wins by name, the rule Builder.use() already follows. */
+function appendPlugin(plugins, plugin) {
+    if (plugins.some((registered) => registered.name === plugin.name)) {
+        return plugins;
+    }
+    return Object.freeze([...plugins, plugin]);
+}
+/**
+ * defineProperty rather than assignment, for the same reason toPluginBag uses
+ * it: a plugin named `__proto__` must land in the record instead of reaching
+ * the prototype setter.
+ */
+function indexPluginsByName(plugins) {
+    const indexed = {};
+    for (const plugin of plugins) {
+        Object.defineProperty(indexed, plugin.name, {
+            value: plugin,
+            enumerable: true,
+        });
+    }
+    return Object.freeze(indexed);
+}
+function createRegistry(makeBuilder, plugins) {
+    const registry = {
+        use(plugin) {
+            const grow = () => makeBuilder().use(plugin);
+            // Eagerly, so a nameless value throws NamelessPluginError HERE and not
+            // at the far-away call that first needed a builder.
+            grow();
+            return createRegistry(grow, appendPlugin(plugins, plugin));
+        },
+        createFieldRule: (define, options) => (0, create_field_rule_1.createFieldRule)(makeBuilder(), define, options),
+        toBuilder: () => makeBuilder(),
+        getPlugins: () => indexPluginsByName(plugins),
+    };
+    return Object.freeze(registry);
+}
+const NO_PLUGINS = Object.freeze([]);
+function createPluginRegistry() {
+    return createRegistry(() => (0, field_builder_types_1.Builder)(), NO_PLUGINS);
+}

package/dist/field-rule/create-plugin-registry.mjs

@@ -0,0 +1,57 @@
+// ===========================================================================
+// src/field-rule/create-plugin-registry.ts — the IMMUTABLE plugin bag.
+//
+// A registry holds a THUNK that replays `use()` onto a fresh Builder, never a
+// Builder it hands out. Builder.use() mutates its receiver, so a stored builder
+// would make `base.use(a)` and `base.use(b)` land in the same object and every
+// branch of a shared base would see every other branch's plugins. Replaying is
+// O(n) per branch at BUILD time only, and it is the whole of the immutability
+// guarantee (docs/legacy-spec/plugin-contract.md:114).
+//
+// The thunk also carries the type: `makeBuilder().use(plugin)` is already
+// `Builder<B & BagEntry<P>>`, so the growing bag type is produced by the
+// builder's own signature and this file holds no assertion.
+// ===========================================================================
+import { Builder } from "../builder/field-builder.types.mjs";
+import { createFieldRule } from "./create-field-rule.mjs";
+/** First-wins by name, the rule Builder.use() already follows. */
+function appendPlugin(plugins, plugin) {
+    if (plugins.some((registered) => registered.name === plugin.name)) {
+        return plugins;
+    }
+    return Object.freeze([...plugins, plugin]);
+}
+/**
+ * defineProperty rather than assignment, for the same reason toPluginBag uses
+ * it: a plugin named `__proto__` must land in the record instead of reaching
+ * the prototype setter.
+ */
+function indexPluginsByName(plugins) {
+    const indexed = {};
+    for (const plugin of plugins) {
+        Object.defineProperty(indexed, plugin.name, {
+            value: plugin,
+            enumerable: true,
+        });
+    }
+    return Object.freeze(indexed);
+}
+function createRegistry(makeBuilder, plugins) {
+    const registry = {
+        use(plugin) {
+            const grow = () => makeBuilder().use(plugin);
+            // Eagerly, so a nameless value throws NamelessPluginError HERE and not
+            // at the far-away call that first needed a builder.
+            grow();
+            return createRegistry(grow, appendPlugin(plugins, plugin));
+        },
+        createFieldRule: (define, options) => createFieldRule(makeBuilder(), define, options),
+        toBuilder: () => makeBuilder(),
+        getPlugins: () => indexPluginsByName(plugins),
+    };
+    return Object.freeze(registry);
+}
+const NO_PLUGINS = Object.freeze([]);
+export function createPluginRegistry() {
+    return createRegistry(() => Builder(), NO_PLUGINS);
+}