@maroonedog/luq 2.2.0 → 2.3.0

package/dist/chain/declaration-recorder.port.mjs

@@ -0,0 +1,13 @@
+/**
+ * Null until someone installs. Exposed as the binding rather than behind a
+ * getter because that measured smaller: with no installer reachable, what
+ * survives minification is one `let` and an optional chain.
+ */
+export let declarationRecorder = null;
+/**
+ * Called once, when the implementation is loaded. A second call overwrites,
+ * which is harmless while there is one implementation.
+ */
+export function installDeclarationRecorder(recorder) {
+    declarationRecorder = recorder;
+}

package/dist/chain/declared-call.types.d.ts

@@ -0,0 +1,15 @@
+import type { TypeName } from "../types";
+/** One call of one chain method. */
+export interface DeclaredCall {
+    readonly pluginName: string;
+    readonly method: string;
+    readonly slot: TypeName;
+    /**
+     * The arguments as declared, after argument resolution and nothing else.
+     *
+     * They are not converted: a RegExp stays a RegExp. How a given output format
+     * spells a value is that writer's business, and converting here would make
+     * everyone pay for a conversion only some of them want.
+     */
+    readonly args: readonly unknown[];
+}

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

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

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/compile/compile-array-node.js

@@ -27,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,
     });

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

@@ -23,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,
     });

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

@@ -13,17 +13,17 @@ 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);
-    // read を先に作る。ワイルドカードを含むテンプレートを拒むのは
-    // createValueReader の役目で、それより先に formatIssuePath を呼ぶと
-    // 「添字が足りない」という RangeError が、本来の PathSyntaxError を
-    // 追い越して出てしまう (テストがそれを捕まえた)。
+    // 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,
@@ -32,6 +32,7 @@ function compileField(request) {
         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,
@@ -54,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

@@ -8,17 +8,17 @@ 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);
-    // read を先に作る。ワイルドカードを含むテンプレートを拒むのは
-    // createValueReader の役目で、それより先に formatIssuePath を呼ぶと
-    // 「添字が足りない」という RangeError が、本来の PathSyntaxError を
-    // 追い越して出てしまう (テストがそれを捕まえた)。
+    // 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,
@@ -27,6 +27,7 @@ export function compileField(request) {
         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,
@@ -49,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

@@ -12,25 +12,21 @@ class UnknownRuleKindError extends Error {
 }
 exports.UnknownRuleKindError = UnknownRuleKindError;
 /**
- * 空の束は一つを共有する。
+ * Every empty bucket is the same object.
  *
- * 七つの種のうち、どのフィールドもたいてい二つか三つしか使わない。残りは
- * 空配列だが、フィールドごとに新しく Object.freeze([]) を作っていたので、
- * 空であること自体は同じなのにマップの同一性だけが全部違っていた。実行時の
- * `field.gates.length` や `field.transforms` の読み出しは、フィールドを
- * またぐたびに別の受け手を見ることになる。
- *
- * この置き換えは src/compile/resolve-conditional-presence.ts の
- * NO_PRESENCE_OVERRIDES と src/runtime/output-writer.ts の NO_WRITE_TARGETS が
- * 既にやっていることを、残りの種にも広げただけである。
+ * 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[]` はどの `readonly R[]` にも代入できるので、共有する
- * ためにアサーションを書く必要はない。型アサーションを書いてよいのは
- * src/core/type-erasure.ts だけである。
+ * `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);

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

@@ -7,25 +7,21 @@ export class UnknownRuleKindError extends Error {
     }
 }
 /**
- * 空の束は一つを共有する。
+ * Every empty bucket is the same object.
  *
- * 七つの種のうち、どのフィールドもたいてい二つか三つしか使わない。残りは
- * 空配列だが、フィールドごとに新しく Object.freeze([]) を作っていたので、
- * 空であること自体は同じなのにマップの同一性だけが全部違っていた。実行時の
- * `field.gates.length` や `field.transforms` の読み出しは、フィールドを
- * またぐたびに別の受け手を見ることになる。
- *
- * この置き換えは src/compile/resolve-conditional-presence.ts の
- * NO_PRESENCE_OVERRIDES と src/runtime/output-writer.ts の NO_WRITE_TARGETS が
- * 既にやっていることを、残りの種にも広げただけである。
+ * 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[]` はどの `readonly R[]` にも代入できるので、共有する
- * ためにアサーションを書く必要はない。型アサーションを書いてよいのは
- * src/core/type-erasure.ts だけである。
+ * `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);

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

@@ -66,14 +66,15 @@ export interface RecursionPolicy {
 export interface CompiledField {
     readonly template: readonly PathSegment[];
     /**
-     * この フィールド自身のパスを、配列の添字を除いて描画したもの。
+     * This field's own path, rendered without array indices.
      *
-     * コンパイル時に一度だけ作る。実行時に組み直していたのは、テンプレートが
-     * 固定なので **毎回同じ文字列を作る** ことを意味していた: 50要素・3
-     * フィールドの配列なら、1回の validate で 150 回、issue が1件も出なくても
-     * である。実測でそれが要素あたりの費用の 35% を占めていた。
+     * 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;
@@ -88,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
@@ -127,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
@@ -143,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;

package/dist/core/type-erasure.mjs

@@ -6,51 +6,57 @@
 // the whole escape hatch in one file.
 // ===========================================================================
 /**
- * 理由: 動的にキーを積み上げて組み立てたレコードは、実行時にはキーが揃って
- * いても静的には 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 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.
  */
 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）だけ。
+ * 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 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.
  */
 export function eraseSchemaValidator(planBacked) {
     return planBacked;