@maroonedog/luq 2.1.0 → 2.3.0

package/dist/chain/declared-call.types.mjs

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

package/dist/chain/index.d.ts

@@ -1,8 +1,10 @@
 export { attachSlotMethods, CHAIN_BUILT_IN_OWNER, PluginMethodCollisionError, } from "./attach-slot-methods";
 export { createChainNode, readChainRules, EMPTY_RULES, type ChainBuildContext, type ChainNodeWiring, } from "./create-chain-node";
+export type { DeclaredCall } from "./declared-call.types";
+export type { DeclarationRecorder } from "./declaration-recorder.port";
 export { collectBranchRules, resolvePluginArguments, SubChainResultError, type SlotSurfaceFactory, type SubChainArgumentDeclaration, type SubChainDefine, } from "./collect-branch-rules";
 export { buildSlotSurface, createFieldSlots } from "./create-field-slots";
-export { collectFieldRules, FieldChainResultError, } from "./collect-field-rules";
+export { collectFieldRules, FieldChainResultError, type FieldChainOutcome, } from "./collect-field-rules";
 export type { PluginBag, BagEntry, SlotPlugins } from "./plugin-bag.types";
 export type { AllowNull, ChainState, CoverWith, ExcludeMissing, ExcludeNull, ExcludeUndefined, OpenState, UncoveredMembers, UnionGuardCoverageError, } from "./chain-state.types";
 export type { ChainMethod } from "./chain-method.types";

package/dist/chain/resolve-args.types.d.ts

@@ -1,5 +1,5 @@
 import type { ArrayItemContext, Present } from "../types";
-import type { ElementChain, FieldRef, FieldRefs, GuardOut, MarkerRecord, NarrowedChain, PresenceShift, PropertyKeyChain, PropertyValueChain, RootPredicate, RootReader, SelfGuard, SelfReader, SelfValue, TransformOut, Unchanged } from "../plugin-kit/marker.types";
+import type { ElementChain, FieldRef, FieldRefs, GuardOut, MarkerRecord, NarrowedChain, PresenceShift, PropertyKeyChain, PropertyValueChain, RootPredicate, RootReader, SelfGuard, SelfReader, SelfValue, BundleOut, StitchOut, TransformOut, Unchanged } from "../plugin-kit/marker.types";
 import type { ElementOf } from "../path/element-of.types";
 import type { PropertyValueOf } from "../path/property-value-of.types";
 import type { FieldPath } from "../path/field-path.types";
@@ -24,5 +24,7 @@ export type ResolveArgs<A extends readonly unknown[], B extends PluginBag, TRoot
 /** Presence shifts go through the NAMED operators over ChainState. */
 export type ResolveOut<O, TValue, TState extends ChainState> = [O] extends [
     Unchanged
-] ? [TValue, TState] : [O] extends [TransformOut] ? [unknown, TState] : [O] extends [GuardOut] ? [TValue, TState] : [O] extends [PresenceShift<"excludeMissing">] ? [TValue, ExcludeMissing<TState>] : [O] extends [PresenceShift<"excludeUndefined">] ? [TValue, ExcludeUndefined<TState>] : [O] extends [PresenceShift<"excludeNull">] ? [TValue, ExcludeNull<TState>] : [O] extends [PresenceShift<"allowNull">] ? [TValue | null, AllowNull<TState>] : [O, TState];
+] ? [TValue, TState] : [O] extends [TransformOut] ? [unknown, TState] : [O] extends [GuardOut] ? [TValue, TState] : [
+    O
+] extends [StitchOut] ? [TValue, TState] : [O] extends [BundleOut] ? [TValue, TState] : [O] extends [PresenceShift<"excludeMissing">] ? [TValue, ExcludeMissing<TState>] : [O] extends [PresenceShift<"excludeUndefined">] ? [TValue, ExcludeUndefined<TState>] : [O] extends [PresenceShift<"excludeNull">] ? [TValue, ExcludeNull<TState>] : [O] extends [PresenceShift<"allowNull">] ? [TValue | null, AllowNull<TState>] : [O, TState];
 export {};

package/dist/compile/compile-array-node.d.ts

@@ -9,11 +9,4 @@ export interface NodeCompileContext {
 }
 /** The one adapter from a grouped declaration to compileField's request. */
 export declare function compileRelativeDeclaration(declaration: RelativeDeclaration, context: NodeCompileContext): CompiledField;
-/**
- * Nesting is a re-grouping of the members, not a second traversal strategy:
- * `items[*].sub[*].x` arrives here as the group `items` whose one member is
- * still `sub[*].x`, and that member groups again into the nested node `sub`.
- * `matrix[*][*]` reaches the same shape through an EMPTY nested template —
- * the element of the outer array is itself the inner array.
- */
 export declare function compileArrayNode(group: ArrayFieldGroup, context: NodeCompileContext): ArrayNode;

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

@@ -16,6 +16,7 @@ exports.compileArrayNode = compileArrayNode;
 // silently unvalidated.
 // ===========================================================================
 const create_array_reader_1 = require("../path/create-array-reader");
+const format_issue_path_1 = require("../path/format-issue-path");
 const compile_field_1 = require("./compile-field");
 const group_array_fields_1 = require("./group-array-fields");
 /** The one adapter from a grouped declaration to compileField's request. */
@@ -26,6 +27,7 @@ function compileRelativeDeclaration(declaration, context) {
         fieldPath: declaration.fieldPath,
         defaultOf: declaration.defaultOf,
         applyDefaultToNull: declaration.applyDefaultToNull,
+        normalize: declaration.normalize,
         planRef: context.planRef,
         eraseComposite: context.eraseComposite,
     });
@@ -37,11 +39,14 @@ function compileRelativeDeclaration(declaration, context) {
  * `matrix[*][*]` reaches the same shape through an EMPTY nested template —
  * the element of the outer array is itself the inner array.
  */
+/** A grouped node template never keeps a wildcard, so rendering needs no index. */
+const NO_INDICES = Object.freeze([]);
 function compileArrayNode(group, context) {
     const grouped = (0, group_array_fields_1.groupArrayFields)(group.members);
     const template = Object.freeze(group.template);
     const node = {
         template,
+        renderedPath: (0, format_issue_path_1.formatIssuePath)(template, NO_INDICES),
         read: (0, create_array_reader_1.createArrayReader)(template),
         elementFields: Object.freeze(grouped.direct.map((declaration) => compileRelativeDeclaration(declaration, context))),
         nested: Object.freeze(grouped.arrays.map((nested) => compileArrayNode(nested, context))),

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

@@ -12,6 +12,7 @@
 // silently unvalidated.
 // ===========================================================================
 import { createArrayReader } from "../path/create-array-reader.mjs";
+import { formatIssuePath } from "../path/format-issue-path.mjs";
 import { compileField } from "./compile-field.mjs";
 import { groupArrayFields, } from "./group-array-fields.mjs";
 /** The one adapter from a grouped declaration to compileField's request. */
@@ -22,6 +23,7 @@ export function compileRelativeDeclaration(declaration, context) {
         fieldPath: declaration.fieldPath,
         defaultOf: declaration.defaultOf,
         applyDefaultToNull: declaration.applyDefaultToNull,
+        normalize: declaration.normalize,
         planRef: context.planRef,
         eraseComposite: context.eraseComposite,
     });
@@ -33,11 +35,14 @@ export function compileRelativeDeclaration(declaration, context) {
  * `matrix[*][*]` reaches the same shape through an EMPTY nested template —
  * the element of the outer array is itself the inner array.
  */
+/** A grouped node template never keeps a wildcard, so rendering needs no index. */
+const NO_INDICES = Object.freeze([]);
 export function compileArrayNode(group, context) {
     const grouped = groupArrayFields(group.members);
     const template = Object.freeze(group.template);
     const node = {
         template,
+        renderedPath: formatIssuePath(template, NO_INDICES),
         read: createArrayReader(template),
         elementFields: Object.freeze(grouped.direct.map((declaration) => compileRelativeDeclaration(declaration, context))),
         nested: Object.freeze(grouped.arrays.map((nested) => compileArrayNode(nested, context))),

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

@@ -18,6 +18,7 @@ export interface FieldCompileRequest {
     readonly fieldPath: string;
     readonly defaultOf: ((root: unknown) => unknown) | null;
     readonly applyDefaultToNull: boolean;
+    readonly normalize: ((value: unknown) => unknown) | null;
     readonly planRef: PlanRef;
     readonly eraseComposite: CompositeEraser;
 }

package/dist/compile/compile-field.js

@@ -4,6 +4,7 @@ exports.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT = void 0;
 exports.compileField = compileField;
 exports.compileFieldDeclaration = compileFieldDeclaration;
 const create_value_reader_1 = require("../path/create-value-reader");
+const format_issue_path_1 = require("../path/format-issue-path");
 const create_value_writer_1 = require("../path/create-value-writer");
 const parse_field_path_1 = require("../path/parse-field-path");
 const resolve_conditional_presence_1 = require("./resolve-conditional-presence");
@@ -12,17 +13,26 @@ const resolve_recursion_1 = require("./resolve-recursion");
 const split_rules_by_kind_1 = require("./split-rules-by-kind");
 /** Whether a field with no explicit setting replaces a null with its default. */
 exports.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT = true;
+/** No indices here: an open index is carried by the run-time prefix. */
+const NO_INDICES = Object.freeze([]);
 function compileField(request) {
     const byKind = (0, split_rules_by_kind_1.splitRulesByKind)(request.rules);
     const hasDefault = request.defaultOf !== null;
-    const needsWriter = byKind.transforms.length > 0 || hasDefault;
+    // Normalizing replaces the value too, so it needs a writer just as default does.
+    const needsWriter = byKind.transforms.length > 0 || hasDefault || request.normalize !== null;
     const template = Object.freeze(request.template);
+    // The reader is made first. Refusing a template that still holds a wildcard
+    // is the reader's job; formatting the path before that raises a "not enough
+    // indices" RangeError which overtakes the PathSyntaxError that should win.
+    const read = (0, create_value_reader_1.createValueReader)(template);
     const field = {
         template,
-        read: (0, create_value_reader_1.createValueReader)(template),
+        renderedPath: (0, format_issue_path_1.formatIssuePath)(template, NO_INDICES),
+        read,
         write: needsWriter ? (0, create_value_writer_1.createValueWriter)(template) : null,
         defaultOf: request.defaultOf,
         applyDefaultToNull: request.applyDefaultToNull,
+        normalize: request.normalize,
         presence: (0, resolve_presence_1.resolvePresence)(byKind.presences),
         presenceOverrides: (0, resolve_conditional_presence_1.resolveConditionalPresence)(byKind.conditionalPresences),
         gates: byKind.gates,
@@ -45,6 +55,7 @@ function compileFieldDeclaration(declaration, planRef, eraseComposite) {
         fieldPath: declaration.path,
         defaultOf: declaration.defaultOf ?? null,
         applyDefaultToNull: declaration.applyDefaultToNull ?? exports.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        normalize: declaration.normalize ?? null,
         planRef,
         eraseComposite,
     });

package/dist/compile/compile-field.mjs

@@ -1,4 +1,5 @@
 import { createValueReader } from "../path/create-value-reader.mjs";
+import { formatIssuePath } from "../path/format-issue-path.mjs";
 import { createValueWriter } from "../path/create-value-writer.mjs";
 import { parseFieldPath } from "../path/parse-field-path.mjs";
 import { resolveConditionalPresence } from "./resolve-conditional-presence.mjs";
@@ -7,17 +8,26 @@ import { resolveRecursion } from "./resolve-recursion.mjs";
 import { splitRulesByKind } from "./split-rules-by-kind.mjs";
 /** Whether a field with no explicit setting replaces a null with its default. */
 export const APPLIES_DEFAULT_TO_NULL_BY_DEFAULT = true;
+/** No indices here: an open index is carried by the run-time prefix. */
+const NO_INDICES = Object.freeze([]);
 export function compileField(request) {
     const byKind = splitRulesByKind(request.rules);
     const hasDefault = request.defaultOf !== null;
-    const needsWriter = byKind.transforms.length > 0 || hasDefault;
+    // Normalizing replaces the value too, so it needs a writer just as default does.
+    const needsWriter = byKind.transforms.length > 0 || hasDefault || request.normalize !== null;
     const template = Object.freeze(request.template);
+    // The reader is made first. Refusing a template that still holds a wildcard
+    // is the reader's job; formatting the path before that raises a "not enough
+    // indices" RangeError which overtakes the PathSyntaxError that should win.
+    const read = createValueReader(template);
     const field = {
         template,
-        read: createValueReader(template),
+        renderedPath: formatIssuePath(template, NO_INDICES),
+        read,
         write: needsWriter ? createValueWriter(template) : null,
         defaultOf: request.defaultOf,
         applyDefaultToNull: request.applyDefaultToNull,
+        normalize: request.normalize,
         presence: resolvePresence(byKind.presences),
         presenceOverrides: resolveConditionalPresence(byKind.conditionalPresences),
         gates: byKind.gates,
@@ -40,6 +50,7 @@ export function compileFieldDeclaration(declaration, planRef, eraseComposite) {
         fieldPath: declaration.path,
         defaultOf: declaration.defaultOf ?? null,
         applyDefaultToNull: declaration.applyDefaultToNull ?? APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        normalize: declaration.normalize ?? null,
         planRef,
         eraseComposite,
     });

package/dist/compile/compile-schema.js

@@ -64,6 +64,7 @@ function compilePlan(relatives, executor) {
         arrays: Object.freeze(grouped.arrays.map((group) => (0, compile_array_node_1.compileArrayNode)(group, context))),
         hasTransforms: relatives.some((declaration) => declaration.rules.some((rule) => rule.kind === "transform")),
         hasDefaults: relatives.some((declaration) => declaration.defaultOf !== null),
+        hasNormalizers: relatives.some((declaration) => declaration.normalize !== null),
     });
     return compiled;
 }
@@ -94,6 +95,7 @@ function parseRelativeDeclaration(declaration) {
         fieldPath: declaration.path,
         defaultOf: declaration.defaultOf ?? null,
         applyDefaultToNull: declaration.applyDefaultToNull ?? compile_field_1.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        normalize: declaration.normalize ?? null,
     };
 }
 /**
@@ -111,6 +113,7 @@ function collectBranchDeclarations(branch) {
             fieldPath: branch.label,
             defaultOf: null,
             applyDefaultToNull: compile_field_1.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+            normalize: null,
         });
     }
     for (const field of branch.fields) {
@@ -120,6 +123,7 @@ function collectBranchDeclarations(branch) {
             fieldPath: field.path,
             defaultOf: null,
             applyDefaultToNull: compile_field_1.APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+            normalize: null,
         });
     }
     return declarations;

package/dist/compile/compile-schema.mjs

@@ -59,6 +59,7 @@ function compilePlan(relatives, executor) {
         arrays: Object.freeze(grouped.arrays.map((group) => compileArrayNode(group, context))),
         hasTransforms: relatives.some((declaration) => declaration.rules.some((rule) => rule.kind === "transform")),
         hasDefaults: relatives.some((declaration) => declaration.defaultOf !== null),
+        hasNormalizers: relatives.some((declaration) => declaration.normalize !== null),
     });
     return compiled;
 }
@@ -89,6 +90,7 @@ function parseRelativeDeclaration(declaration) {
         fieldPath: declaration.path,
         defaultOf: declaration.defaultOf ?? null,
         applyDefaultToNull: declaration.applyDefaultToNull ?? APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+        normalize: declaration.normalize ?? null,
     };
 }
 /**
@@ -106,6 +108,7 @@ function collectBranchDeclarations(branch) {
             fieldPath: branch.label,
             defaultOf: null,
             applyDefaultToNull: APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+            normalize: null,
         });
     }
     for (const field of branch.fields) {
@@ -115,6 +118,7 @@ function collectBranchDeclarations(branch) {
             fieldPath: field.path,
             defaultOf: null,
             applyDefaultToNull: APPLIES_DEFAULT_TO_NULL_BY_DEFAULT,
+            normalize: null,
         });
     }
     return declarations;

package/dist/compile/group-array-fields.d.ts

@@ -14,6 +14,7 @@ export interface RelativeDeclaration {
     readonly fieldPath: string;
     readonly defaultOf: ((root: unknown) => unknown) | null;
     readonly applyDefaultToNull: boolean;
+    readonly normalize: ((value: unknown) => unknown) | null;
 }
 /** Every declaration that reaches through the same array, plus that array. */
 export interface ArrayFieldGroup {

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

@@ -11,6 +11,26 @@ class UnknownRuleKindError extends Error {
     }
 }
 exports.UnknownRuleKindError = UnknownRuleKindError;
+/**
+ * Every empty bucket is the same object.
+ *
+ * A field typically uses two or three of the kinds and leaves the rest empty.
+ * Freezing a fresh [] per field per kind made every one of those empties a
+ * distinct object, so reading the same empty list across fields kept landing
+ * on a different receiver.
+ */
+const NO_RULES_OF_THIS_KIND = Object.freeze([]);
+/**
+ * Returns the shared empty for an empty bucket, and the frozen array
+ * otherwise.
+ *
+ * `readonly never[]` is assignable to every `readonly R[]`, so sharing needs
+ * no type assertion — which matters, because this is not a file allowed to
+ * write one.
+ */
+function freezeRules(rules) {
+    return rules.length === 0 ? NO_RULES_OF_THIS_KIND : Object.freeze(rules);
+}
 function splitRulesByKind(rules) {
     const checks = [];
     const presences = [];
@@ -38,13 +58,13 @@ function splitRulesByKind(rules) {
             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),
+        checks: freezeRules(checks),
+        presences: freezeRules(presences),
+        conditionalPresences: freezeRules(conditionalPresences),
+        gates: freezeRules(gates),
+        transforms: freezeRules(transforms),
+        composites: freezeRules(composites),
+        recursions: freezeRules(recursions),
     });
 }
 /** The exhaustiveness proof: the parameter is `never`, so an eighth kind is a

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

@@ -6,6 +6,26 @@ export class UnknownRuleKindError extends Error {
         this.name = "UnknownRuleKindError";
     }
 }
+/**
+ * Every empty bucket is the same object.
+ *
+ * A field typically uses two or three of the kinds and leaves the rest empty.
+ * Freezing a fresh [] per field per kind made every one of those empties a
+ * distinct object, so reading the same empty list across fields kept landing
+ * on a different receiver.
+ */
+const NO_RULES_OF_THIS_KIND = Object.freeze([]);
+/**
+ * Returns the shared empty for an empty bucket, and the frozen array
+ * otherwise.
+ *
+ * `readonly never[]` is assignable to every `readonly R[]`, so sharing needs
+ * no type assertion — which matters, because this is not a file allowed to
+ * write one.
+ */
+function freezeRules(rules) {
+    return rules.length === 0 ? NO_RULES_OF_THIS_KIND : Object.freeze(rules);
+}
 export function splitRulesByKind(rules) {
     const checks = [];
     const presences = [];
@@ -33,13 +53,13 @@ export function splitRulesByKind(rules) {
             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),
+        checks: freezeRules(checks),
+        presences: freezeRules(presences),
+        conditionalPresences: freezeRules(conditionalPresences),
+        gates: freezeRules(gates),
+        transforms: freezeRules(transforms),
+        composites: freezeRules(composites),
+        recursions: freezeRules(recursions),
     });
 }
 /** The exhaustiveness proof: the parameter is `never`, so an eighth kind is a

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

@@ -65,6 +65,18 @@ export interface RecursionPolicy {
 }
 export interface CompiledField {
     readonly template: readonly PathSegment[];
+    /**
+     * This field's own path, rendered without array indices.
+     *
+     * Rendered once, at compile time. The template is fixed, so rebuilding it
+     * per call meant **producing the same string every time** — once per field
+     * per element, whether or not a single issue was reported, and it was a
+     * large share of the per-element cost.
+     *
+     * What remains at validation time is one concatenation with the prefix
+     * holding the open indices.
+     */
+    readonly renderedPath: string;
     readonly read: (subject: unknown) => unknown;
     /**
      * null unless the field declared a transform or a default — the runtime then
@@ -77,6 +89,11 @@ export interface CompiledField {
     readonly write: ValueWriter | null;
     readonly defaultOf: ((root: unknown) => unknown) | null;
     readonly applyDefaultToNull: boolean;
+    /**
+     * null unless the field declared one. Runs after the default and BEFORE
+     * presence, on a value that is neither undefined nor null.
+     */
+    readonly normalize: ((value: unknown) => unknown) | null;
     readonly presence: PresencePolicy;
     /**
      * The conditional overrides of `presence`, in declaration order, and the
@@ -95,6 +112,18 @@ export interface CompiledField {
 /** Loop interchange: one array is read once however many element fields exist. */
 export interface ArrayNode {
     readonly template: readonly PathSegment[];
+    /**
+     * The node's own path, rendered once at build time — `lines`, never
+     * `lines[*]`, because the grouping already cut the wildcard off.
+     *
+     * CompiledField has carried its `renderedPath` since rebuilding it per
+     * element was measured at 35% of the per-element price. The array NODE was
+     * left behind and went on rendering the same string on every validate().
+     * Rendering can throw on a template with an unconsumed wildcard, so moving
+     * it here also moves that throw from validate() to build(), which is the
+     * direction this layer is supposed to push everything.
+     */
+    readonly renderedPath: string;
     readonly read: (subject: unknown) => unknown;
     readonly elementFields: readonly CompiledField[];
     readonly nested: readonly ArrayNode[];
@@ -104,6 +133,12 @@ export interface ValidationPlan {
     readonly arrays: readonly ArrayNode[];
     readonly hasTransforms: boolean;
     readonly hasDefaults: boolean;
+    /**
+     * A normalizer substitutes a value the same way a default does, so the
+     * writer must exist for it too. Kept as its own flag rather than folded
+     * into hasDefaults, which would make that name say something it does not.
+     */
+    readonly hasNormalizers: boolean;
 }
 /**
  * What the chain collector hands compile: one path, its ordered rules, and the
@@ -120,4 +155,5 @@ export interface FieldDeclaration {
     readonly rules: readonly Rule[];
     readonly defaultOf?: (root: unknown) => unknown;
     readonly applyDefaultToNull?: boolean;
+    readonly normalize?: (value: unknown) => unknown;
 }

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

@@ -1,42 +1,48 @@
 /**
- * 理由: 動的にキーを積み上げて組み立てたレコードは、実行時にはキーが揃って
- * いても静的には Record<string, unknown> 止まりになる。呼び出し側のジェネリク
- * ス（AsyncContextBuilder.set の `C & { [P in K]: V }`）が、そのキーと値の対応
- * を型として保証している。
+ * Why: a record built up key by key has all its keys at run time but stays
+ * Record<string, unknown> statically. The generic on the calling side —
+ * AsyncContextBuilder.set's `C & { [P in K]: V }` — is what holds the
+ * key-to-value correspondence as a type.
  */
 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 だけを生やす）で組み立てていることに依存する。
+ * Why: a chain is a record carrying one method per plugin in the bag. The
+ * keys are all there at run time but the value stays Record<string, unknown>
+ * statically, while the matching types are mapped types — which keys appear
+ * follows from the type arguments alone and cannot be written where the value
+ * is assembled.
+ *
+ * Soundness depends on the assembly following the same rule the mapped type
+ * does: attach a method for a plugin exactly when that plugin declares the
+ * slot.
  */
 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）だけ。
+ * Why: a builder chain is one record holding the plugins added by use() and
+ * the declarations added by v(), and its shape does not change as the chain
+ * advances. Its static type does — each step is expressed with type arguments
+ * (the bag intersection, the union of declared paths, the conditional that
+ * branches on union guard exhaustiveness) that the assembling code has no way
+ * to write. For the same reason the runtime knows only the plan and can only
+ * answer ValidationResult<unknown>; this boundary is the one place the
+ * declared T can be put back.
+ *
+ * Soundness depends on the erased surface declaring the same member set as
+ * the public type, with the implementation structurally conforming to it.
+ * Exactly one call site is allowed.
  */
 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）だけ。
+ * Why: building a validator from a JSON Schema read at run time gives the
+ * compiler nothing to check the declared T against — the document is a value,
+ * not a type. The plan-backed validator can only answer
+ * ValidationResult<unknown>, so this boundary is the one place the caller's
+ * explicit T can be put back. Same kind of erasure as the builder surface,
+ * hence the same home.
+ *
+ * Soundness depends on the plan-backed validator declaring the same member
+ * set as Validator<T>, with the implementation structurally conforming to it.
+ * When T disagrees with the actual document the type lies, but the runtime
+ * result is still correct. Exactly one call site is allowed.
  */
 export declare function eraseSchemaValidator<T>(planBacked: object): T;

package/dist/core/type-erasure.js

@@ -12,51 +12,57 @@ exports.eraseChainSurface = eraseChainSurface;
 exports.eraseBuilderSurface = eraseBuilderSurface;
 exports.eraseSchemaValidator = eraseSchemaValidator;
 /**
- * 理由: 動的にキーを積み上げて組み立てたレコードは、実行時にはキーが揃って
- * いても静的には Record<string, unknown> 止まりになる。呼び出し側のジェネリク
- * ス（AsyncContextBuilder.set の `C & { [P in K]: V }`）が、そのキーと値の対応
- * を型として保証している。
+ * Why: a record built up key by key has all its keys at run time but stays
+ * Record<string, unknown> statically. The generic on the calling side —
+ * AsyncContextBuilder.set's `C & { [P in K]: V }` — is what holds the
+ * key-to-value correspondence as a type.
  */
 function eraseAssembledRecord(assembled) {
     return assembled;
 }
 /**
- * 理由: チェーンの実体は「バッグに入っているプラグインの数だけメソッドを生やした
- * レコード」で、実行時にはキーが揃っていても静的には Record<string, unknown> 止まり
- * になる。対応する型 FieldSlots / FieldChain は SlotPlugins によるマップ型なので、
- * 「どのキーが生えるか」は型引数 B と S からしか決まらず、値の組み立て側では書けない。
- * 正しさは attachSlotMethods が SlotPlugins と同じ規則（plugin.slots に S を含む
- * プラグインの plugin.method だけを生やす）で組み立てていることに依存する。
+ * Why: a chain is a record carrying one method per plugin in the bag. The
+ * keys are all there at run time but the value stays Record<string, unknown>
+ * statically, while the matching types are mapped types — which keys appear
+ * follows from the type arguments alone and cannot be written where the value
+ * is assembled.
+ *
+ * Soundness depends on the assembly following the same rule the mapped type
+ * does: attach a method for a plugin exactly when that plugin declares the
+ * slot.
  */
 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）だけ。
+ * Why: a builder chain is one record holding the plugins added by use() and
+ * the declarations added by v(), and its shape does not change as the chain
+ * advances. Its static type does — each step is expressed with type arguments
+ * (the bag intersection, the union of declared paths, the conditional that
+ * branches on union guard exhaustiveness) that the assembling code has no way
+ * to write. For the same reason the runtime knows only the plan and can only
+ * answer ValidationResult<unknown>; this boundary is the one place the
+ * declared T can be put back.
+ *
+ * Soundness depends on the erased surface declaring the same member set as
+ * the public type, with the implementation structurally conforming to it.
+ * Exactly one call site is allowed.
  */
 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）だけ。
+ * Why: building a validator from a JSON Schema read at run time gives the
+ * compiler nothing to check the declared T against — the document is a value,
+ * not a type. The plan-backed validator can only answer
+ * ValidationResult<unknown>, so this boundary is the one place the caller's
+ * explicit T can be put back. Same kind of erasure as the builder surface,
+ * hence the same home.
+ *
+ * Soundness depends on the plan-backed validator declaring the same member
+ * set as Validator<T>, with the implementation structurally conforming to it.
+ * When T disagrees with the actual document the type lies, but the runtime
+ * result is still correct. Exactly one call site is allowed.
  */
 function eraseSchemaValidator(planBacked) {
     return planBacked;