@maroonedog/luq 2.1.0 → 2.3.0

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;

package/dist/json-schema/build-from-schema.js

@@ -42,7 +42,14 @@ function buildFieldEntries(bag, schema) {
         path: declaration.path,
         defaultOf: null,
         applyDefaultToNull: false,
-        collectRules: (chain) => collectDeclaredRules(declaration, bag, schema, chain),
+        normalize: null,
+        // No record of declared calls: what is assembled here comes from a
+        // document, and nobody called a chain method. null rather than the empty
+        // list is what lets a writer say "not known" instead of "none".
+        collectRules: (chain) => ({
+            rules: collectDeclaredRules(declaration, bag, schema, chain),
+            calls: null,
+        }),
     }));
 }
 /** The erased front door: the declarations, with nothing compiled yet. */

package/dist/json-schema/build-from-schema.mjs

@@ -35,7 +35,14 @@ export function buildFieldEntries(bag, schema) {
         path: declaration.path,
         defaultOf: null,
         applyDefaultToNull: false,
-        collectRules: (chain) => collectDeclaredRules(declaration, bag, schema, chain),
+        normalize: null,
+        // No record of declared calls: what is assembled here comes from a
+        // document, and nobody called a chain method. null rather than the empty
+        // list is what lets a writer say "not known" instead of "none".
+        collectRules: (chain) => ({
+            rules: collectDeclaredRules(declaration, bag, schema, chain),
+            calls: null,
+        }),
     }));
 }
 /** The erased front door: the declarations, with nothing compiled yet. */

package/dist/json-schema/declare-additional-properties.d.ts

@@ -3,17 +3,17 @@ import type { ConverterChain } from "./apply-keyword-binding";
 import type { Draft07SchemaObject } from "./draft07.types";
 import type { StructuralContext } from "./structural-expansion.types";
 /**
- * `patternProperties` のキー、つまり正規表現の文字列。
- * additionalProperties が「該当しないキー」を選ぶのに要る。
+ * The keys of `patternProperties`, which are regular expression strings.
+ * additionalProperties needs them to pick out the keys that match none.
  */
 export declare function patternPropertyKeys(schema: Draft07SchemaObject): readonly string[];
 /**
- * BOOLEAN 形。
+ * The BOOLEAN form.
  *
- * キーワード束縛は自分の値 (boolean) しか運べないので、パターンがあるときだけ
- * プラグインを直接呼ぶ。束縛のほうは残す: キーワード表と「そのメソッドが
- * 実在する」というコンパイル時のゲートはそちらが持っている。
+ * A keyword binding can only carry its own value, so when patterns are present
+ * the plugin is called directly. The binding stays either way: it is what
+ * holds the keyword table and the compile-time check that the method exists.
  */
 export declare function applyAdditionalPropertiesBoolean(chain: ConverterChain<"object">, schema: Draft07SchemaObject, allowed: boolean): ConverterChain<"object">;
-/** SCHEMA 形: 宣言にもパターンにも該当しない値が、そのスキーマに従う。 */
+/** The SCHEMA form: whatever matches neither a declaration nor a pattern follows it. */
 export declare function declareAdditionalPropertiesSchema(schema: Draft07SchemaObject, context: StructuralContext): readonly Rule[];

package/dist/json-schema/declare-additional-properties.js

@@ -7,8 +7,8 @@ const apply_keyword_binding_1 = require("./apply-keyword-binding");
 const keyword_map_object_1 = require("./keyword-map-object");
 const NO_RULES = Object.freeze([]);
 /**
- * `patternProperties` のキー、つまり正規表現の文字列。
- * additionalProperties が「該当しないキー」を選ぶのに要る。
+ * The keys of `patternProperties`, which are regular expression strings.
+ * additionalProperties needs them to pick out the keys that match none.
  */
 function patternPropertyKeys(schema) {
     const patterns = schema.patternProperties;
@@ -17,11 +17,11 @@ function patternPropertyKeys(schema) {
     return Object.freeze(Object.keys(patterns));
 }
 /**
- * BOOLEAN 形。
+ * The BOOLEAN form.
  *
- * キーワード束縛は自分の値 (boolean) しか運べないので、パターンがあるときだけ
- * プラグインを直接呼ぶ。束縛のほうは残す: キーワード表と「そのメソッドが
- * 実在する」というコンパイル時のゲートはそちらが持っている。
+ * A keyword binding can only carry its own value, so when patterns are present
+ * the plugin is called directly. The binding stays either way: it is what
+ * holds the keyword table and the compile-time check that the method exists.
  */
 function applyAdditionalPropertiesBoolean(chain, schema, allowed) {
     const patterns = patternPropertyKeys(schema);
@@ -29,7 +29,7 @@ function applyAdditionalPropertiesBoolean(chain, schema, allowed) {
         ? (0, apply_keyword_binding_1.applyKeywordBinding)(chain, keyword_map_object_1.additionalPropertiesBinding, allowed)
         : chain.additionalProperties(allowed, undefined, patterns);
 }
-/** SCHEMA 形: 宣言にもパターンにも該当しない値が、そのスキーマに従う。 */
+/** The SCHEMA form: whatever matches neither a declaration nor a pattern follows it. */
 function declareAdditionalPropertiesSchema(schema, context) {
     const additional = schema.additionalProperties;
     if (additional === undefined || typeof additional === "boolean") {

package/dist/json-schema/declare-additional-properties.mjs

@@ -2,8 +2,8 @@ import { applyKeywordBinding } from "./apply-keyword-binding.mjs";
 import { additionalPropertiesBinding } from "./keyword-map-object.mjs";
 const NO_RULES = Object.freeze([]);
 /**
- * `patternProperties` のキー、つまり正規表現の文字列。
- * additionalProperties が「該当しないキー」を選ぶのに要る。
+ * The keys of `patternProperties`, which are regular expression strings.
+ * additionalProperties needs them to pick out the keys that match none.
  */
 export function patternPropertyKeys(schema) {
     const patterns = schema.patternProperties;
@@ -12,11 +12,11 @@ export function patternPropertyKeys(schema) {
     return Object.freeze(Object.keys(patterns));
 }
 /**
- * BOOLEAN 形。
+ * The BOOLEAN form.
  *
- * キーワード束縛は自分の値 (boolean) しか運べないので、パターンがあるときだけ
- * プラグインを直接呼ぶ。束縛のほうは残す: キーワード表と「そのメソッドが
- * 実在する」というコンパイル時のゲートはそちらが持っている。
+ * A keyword binding can only carry its own value, so when patterns are present
+ * the plugin is called directly. The binding stays either way: it is what
+ * holds the keyword table and the compile-time check that the method exists.
  */
 export function applyAdditionalPropertiesBoolean(chain, schema, allowed) {
     const patterns = patternPropertyKeys(schema);
@@ -24,7 +24,7 @@ export function applyAdditionalPropertiesBoolean(chain, schema, allowed) {
         ? applyKeywordBinding(chain, additionalPropertiesBinding, allowed)
         : chain.additionalProperties(allowed, undefined, patterns);
 }
-/** SCHEMA 形: 宣言にもパターンにも該当しない値が、そのスキーマに従う。 */
+/** The SCHEMA form: whatever matches neither a declaration nor a pattern follows it. */
 export function declareAdditionalPropertiesSchema(schema, context) {
     const additional = schema.additionalProperties;
     if (additional === undefined || typeof additional === "boolean") {

package/dist/json-schema/declare-object-keywords.js

@@ -40,10 +40,10 @@ function declareObjectRules(schema, context) {
     }
     const additional = schema.additionalProperties;
     if (typeof additional === "boolean") {
-        // §6.5.4 の対象は「properties にも patternProperties にも該当しない」キー。
-        // キーワード束縛は自分の値 (boolean) しか運べないので、パターンがある
-        // ときだけプラグインを直接呼ぶ。束縛のほうは残す: キーワード表と
-        // 「そのメソッドが実在する」というコンパイル時のゲートはそちらが持つ。
+        // §6.5.4 applies to the keys matched by neither properties nor
+        // patternProperties. A keyword binding can only carry its own value, so
+        // when patterns are present the plugin is called directly. The binding
+        // stays: it holds the keyword table and the check that the method exists.
         chain = (0, declare_additional_properties_1.applyAdditionalPropertiesBoolean)(chain, schema, additional);
     }
     return readRules(chain);

package/dist/json-schema/declare-object-keywords.mjs

@@ -33,10 +33,10 @@ export function declareObjectRules(schema, context) {
     }
     const additional = schema.additionalProperties;
     if (typeof additional === "boolean") {
-        // §6.5.4 の対象は「properties にも patternProperties にも該当しない」キー。
-        // キーワード束縛は自分の値 (boolean) しか運べないので、パターンがある
-        // ときだけプラグインを直接呼ぶ。束縛のほうは残す: キーワード表と
-        // 「そのメソッドが実在する」というコンパイル時のゲートはそちらが持つ。
+        // §6.5.4 applies to the keys matched by neither properties nor
+        // patternProperties. A keyword binding can only carry its own value, so
+        // when patterns are present the plugin is called directly. The binding
+        // stays: it holds the keyword table and the check that the method exists.
         chain = applyAdditionalPropertiesBoolean(chain, schema, additional);
     }
     return readRules(chain);

package/dist/json-schema/flatten-schema.js

@@ -91,7 +91,7 @@ function hasRootRuleKeyword(node) {
 /** The root node MINUS the three keywords the flattener applies itself. A rest
  *  destructuring, so the compiler and not a comment keeps the result a schema. */
 function dropDistributedKeywords(node) {
-    const { type, required, allOf, ...residual } = node;
+    const { type: _type, required: _required, allOf: _allOf, ...residual } = node;
     return residual;
 }
 /** Children of the root, merged across the `allOf` arms, first arm winning. */

package/dist/json-schema/flatten-schema.mjs

@@ -86,7 +86,7 @@ function hasRootRuleKeyword(node) {
 /** The root node MINUS the three keywords the flattener applies itself. A rest
  *  destructuring, so the compiler and not a comment keeps the result a schema. */
 function dropDistributedKeywords(node) {
-    const { type, required, allOf, ...residual } = node;
+    const { type: _type, required: _required, allOf: _allOf, ...residual } = node;
     return residual;
 }
 /** Children of the root, merged across the `allOf` arms, first arm winning. */

package/dist/json-schema/follow-json-pointer.d.ts

@@ -8,14 +8,15 @@ export declare function toPointerTokens(fragment: string): readonly string[];
  */
 export declare function stepInto(current: unknown, token: string): unknown;
 /**
- * ポインタを辿りながら、**途中で跨いだ `$id` を数える**。
+ * Walks the pointer while **counting every `$id` crossed on the way**.
  *
- * `#/definitions/baz/definitions/bar` の `baz` が `$id: "folder/"` を持つとき、
- * `bar` の中に書かれた相対 `$ref` は folder/ の下で解決されなければならない。
- * 着地したノードの `$id` だけを見ると、通過したノードの分が落ちる。
+ * When an intermediate node along the path carries `$id: "folder/"`, a
+ * relative `$ref` written deeper in must resolve under folder/. Looking only
+ * at the `$id` of the node landed on loses every node passed through.
  *
- * ベースをどう進めるかは呼び出し側が渡す (`advance`)。この関数は「どのノードを
- * どの順に跨いだか」だけを知っていればよく、URI の演算は持たない。
+ * How the base advances is supplied by the caller. This function only needs
+ * to know which nodes were crossed and in what order; it does no URI
+ * arithmetic of its own.
  */
 export declare function walkPointer<TScope>(fragment: string, document: unknown, scope: TScope, advance: (scope: TScope, node: unknown) => TScope, onMissing: (token: string) => never): {
     readonly node: unknown;

package/dist/json-schema/follow-json-pointer.js

@@ -4,13 +4,12 @@ exports.toPointerTokens = toPointerTokens;
 exports.stepInto = stepInto;
 exports.walkPointer = walkPointer;
 // ===========================================================================
-// L8  src/json-schema/follow-json-pointer.ts — RFC 6901 のポインタを辿る。
+// L8  src/json-schema/follow-json-pointer.ts — walks an RFC 6901 pointer.
 //
-// `$ref` のうち **場所** を表す部分だけを担う。どの文書を見るかは
-// schema-registry.ts と resolve-ref.ts の仕事で、ここは「その文書の中の
-// どこか」だけを答える。分けてあるのは、`$id` によるベース URI の話と
-// ポインタの復号の話が別物であり、混ぜると 200 行を超えて両方読みにくく
-// なるからである。
+// Answers only WHERE INSIDE a document, never WHICH document. Choosing the
+// document is a separate job, kept separate because base-URI arithmetic and
+// pointer decoding are different problems and neither reads well once they
+// share a file.
 // ===========================================================================
 const types_1 = require("../types");
 /** RFC 6901: `~1` is "/" and `~0` is "~", decoded in that order. */
@@ -18,18 +17,18 @@ function decodePointerToken(token) {
     return token.replace(/~1/g, "/").replace(/~0/g, "~");
 }
 /**
- * `$ref` は URI で、ポインタはそのフラグメント。RFC 6901 §6 は
- * 「フラグメントの規則でパーセント符号化されている」と定めるので、
- * **スラッシュで割る前にフラグメント全体を復号する**。
+ * A `$ref` is a URI and the pointer is its fragment. RFC 6901 §6 says the
+ * fragment is percent-encoded by the fragment rules, so **the whole fragment
+ * is decoded before splitting on slashes**.
  *
- * 順序が意味を持つ。`#/definitions/percent%25field` は復号して
- * `/definitions/percent%field` になり、そこで割ってトークンを得る。
- * 先に割ってからトークンごとに復号すると `%25` は復号されるが、
- * `%2F` が「区切りとしてのスラッシュ」に戻る仕様どおりの挙動にならない。
+ * The order matters. `#/definitions/percent%25field` decodes to
+ * `/definitions/percent%field` and is split from there. Splitting first and
+ * decoding each token does decode `%25`, but then `%2F` turns back into a
+ * separator, which is not what the spec says it means.
  *
- * 壊れたパーセント列 (`%zz`) は decodeURIComponent が投げるので、
- * 復号できないポインタはそのまま扱う。ここで投げると、ポインタが1つ
- * 壊れているだけで文書全体が読めなくなる。
+ * decodeURIComponent throws on a malformed sequence like `%zz`, and a
+ * pointer that cannot be decoded is used as-is. Throwing here would make one
+ * broken pointer take the whole document down.
  */
 function decodeFragment(pointer) {
     try {
@@ -44,8 +43,8 @@ function toPointerTokens(fragment) {
     const pointer = decodeFragment(fragment);
     if (pointer === "")
         return [];
-    // "/" は「ルート直下の空文字キー」であって空のトークン列ではない。
-    // ここを [] にすると `{"": ...}` を指すポインタがルートに化ける。
+    // "/" is the empty-string key directly under the root, not an empty token
+    // list. Returning [] here would turn a pointer at `{"": ...}` into the root.
     return pointer.split("/").slice(1).map(decodePointerToken);
 }
 /**
@@ -65,14 +64,15 @@ function stepInto(current, token) {
     return current[token];
 }
 /**
- * ポインタを辿りながら、**途中で跨いだ `$id` を数える**。
+ * Walks the pointer while **counting every `$id` crossed on the way**.
  *
- * `#/definitions/baz/definitions/bar` の `baz` が `$id: "folder/"` を持つとき、
- * `bar` の中に書かれた相対 `$ref` は folder/ の下で解決されなければならない。
- * 着地したノードの `$id` だけを見ると、通過したノードの分が落ちる。
+ * When an intermediate node along the path carries `$id: "folder/"`, a
+ * relative `$ref` written deeper in must resolve under folder/. Looking only
+ * at the `$id` of the node landed on loses every node passed through.
  *
- * ベースをどう進めるかは呼び出し側が渡す (`advance`)。この関数は「どのノードを
- * どの順に跨いだか」だけを知っていればよく、URI の演算は持たない。
+ * How the base advances is supplied by the caller. This function only needs
+ * to know which nodes were crossed and in what order; it does no URI
+ * arithmetic of its own.
  */
 function walkPointer(fragment, document, scope, advance, onMissing) {
     let current = document;

package/dist/json-schema/follow-json-pointer.mjs

@@ -1,11 +1,10 @@
 // ===========================================================================
-// L8  src/json-schema/follow-json-pointer.ts — RFC 6901 のポインタを辿る。
+// L8  src/json-schema/follow-json-pointer.ts — walks an RFC 6901 pointer.
 //
-// `$ref` のうち **場所** を表す部分だけを担う。どの文書を見るかは
-// schema-registry.ts と resolve-ref.ts の仕事で、ここは「その文書の中の
-// どこか」だけを答える。分けてあるのは、`$id` によるベース URI の話と
-// ポインタの復号の話が別物であり、混ぜると 200 行を超えて両方読みにくく
-// なるからである。
+// Answers only WHERE INSIDE a document, never WHICH document. Choosing the
+// document is a separate job, kept separate because base-URI arithmetic and
+// pointer decoding are different problems and neither reads well once they
+// share a file.
 // ===========================================================================
 import { isArray, isPlainObject } from "../types/index.mjs";
 /** RFC 6901: `~1` is "/" and `~0` is "~", decoded in that order. */
@@ -13,18 +12,18 @@ function decodePointerToken(token) {
     return token.replace(/~1/g, "/").replace(/~0/g, "~");
 }
 /**
- * `$ref` は URI で、ポインタはそのフラグメント。RFC 6901 §6 は
- * 「フラグメントの規則でパーセント符号化されている」と定めるので、
- * **スラッシュで割る前にフラグメント全体を復号する**。
+ * A `$ref` is a URI and the pointer is its fragment. RFC 6901 §6 says the
+ * fragment is percent-encoded by the fragment rules, so **the whole fragment
+ * is decoded before splitting on slashes**.
  *
- * 順序が意味を持つ。`#/definitions/percent%25field` は復号して
- * `/definitions/percent%field` になり、そこで割ってトークンを得る。
- * 先に割ってからトークンごとに復号すると `%25` は復号されるが、
- * `%2F` が「区切りとしてのスラッシュ」に戻る仕様どおりの挙動にならない。
+ * The order matters. `#/definitions/percent%25field` decodes to
+ * `/definitions/percent%field` and is split from there. Splitting first and
+ * decoding each token does decode `%25`, but then `%2F` turns back into a
+ * separator, which is not what the spec says it means.
  *
- * 壊れたパーセント列 (`%zz`) は decodeURIComponent が投げるので、
- * 復号できないポインタはそのまま扱う。ここで投げると、ポインタが1つ
- * 壊れているだけで文書全体が読めなくなる。
+ * decodeURIComponent throws on a malformed sequence like `%zz`, and a
+ * pointer that cannot be decoded is used as-is. Throwing here would make one
+ * broken pointer take the whole document down.
  */
 function decodeFragment(pointer) {
     try {
@@ -39,8 +38,8 @@ export function toPointerTokens(fragment) {
     const pointer = decodeFragment(fragment);
     if (pointer === "")
         return [];
-    // "/" は「ルート直下の空文字キー」であって空のトークン列ではない。
-    // ここを [] にすると `{"": ...}` を指すポインタがルートに化ける。
+    // "/" is the empty-string key directly under the root, not an empty token
+    // list. Returning [] here would turn a pointer at `{"": ...}` into the root.
     return pointer.split("/").slice(1).map(decodePointerToken);
 }
 /**
@@ -60,14 +59,15 @@ export function stepInto(current, token) {
     return current[token];
 }
 /**
- * ポインタを辿りながら、**途中で跨いだ `$id` を数える**。
+ * Walks the pointer while **counting every `$id` crossed on the way**.
  *
- * `#/definitions/baz/definitions/bar` の `baz` が `$id: "folder/"` を持つとき、
- * `bar` の中に書かれた相対 `$ref` は folder/ の下で解決されなければならない。
- * 着地したノードの `$id` だけを見ると、通過したノードの分が落ちる。
+ * When an intermediate node along the path carries `$id: "folder/"`, a
+ * relative `$ref` written deeper in must resolve under folder/. Looking only
+ * at the `$id` of the node landed on loses every node passed through.
  *
- * ベースをどう進めるかは呼び出し側が渡す (`advance`)。この関数は「どのノードを
- * どの順に跨いだか」だけを知っていればよく、URI の演算は持たない。
+ * How the base advances is supplied by the caller. This function only needs
+ * to know which nodes were crossed and in what order; it does no URI
+ * arithmetic of its own.
  */
 export function walkPointer(fragment, document, scope, advance, onMissing) {
     let current = document;

package/dist/json-schema/ref-resolution-error.js

@@ -2,9 +2,9 @@
 // ===========================================================================
 // L8  src/json-schema/ref-resolution-error.ts
 //
-// `$ref` が解けなかったことを表す例外。呼び出し側が **identity で捕まえられる**
-// ことが要件なので、独立したクラスであり、独立したモジュールである
-// (resolve-ref.ts から import すると、その巨大な依存を一緒に引く)。
+// Raised when a `$ref` cannot be resolved. Callers must be able to catch it
+// **by identity**, so it is its own class — and its own module, so catching it
+// does not drag in the resolver's dependencies.
 // ===========================================================================
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RefResolutionError = void 0;

package/dist/json-schema/ref-resolution-error.mjs

@@ -1,9 +1,9 @@
 // ===========================================================================
 // L8  src/json-schema/ref-resolution-error.ts
 //
-// `$ref` が解けなかったことを表す例外。呼び出し側が **identity で捕まえられる**
-// ことが要件なので、独立したクラスであり、独立したモジュールである
-// (resolve-ref.ts から import すると、その巨大な依存を一緒に引く)。
+// Raised when a `$ref` cannot be resolved. Callers must be able to catch it
+// **by identity**, so it is its own class — and its own module, so catching it
+// does not drag in the resolver's dependencies.
 // ===========================================================================
 export class RefResolutionError extends Error {
     constructor(ref, reason) {

package/dist/json-schema/schema-registry.js

@@ -2,19 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSchemaRegistry = createSchemaRegistry;
 // ===========================================================================
-// L8  src/json-schema/schema-registry.ts — どの URI がどのスキーマを指すか。
+// L8  src/json-schema/schema-registry.ts — which URI names which schema.
 //
-// Draft-07 §8.2 では `$id` が二つの働きをする: 場所を示す URI はベースを
-// 立て直し、`#name` の形は**位置に依らない名前**を付ける。どちらも
-// 「この URI はこのノード」という索引で、それがこのファイルの責務である。
-// ポインタ (`#/definitions/x`) を辿るのは場所の話なので resolve-ref.ts が持つ。
+// Draft-07 §8.2 gives `$id` two jobs: a URI that names a location re-bases
+// what follows, and the `#name` form gives a **location-independent name**.
+// Both are the same index — this URI is that node — which is this file's whole
+// responsibility. Walking a pointer is about location, and lives elsewhere.
 //
-// 外部文書は**呼び出し側が渡したものだけ**である。Luq は取りに行かない:
-// 関数ではなく地図 (`externalDocuments`) を受けるのは、そうすれば
-//   * スキーマに書かれた URI でプロセスがソケットを開くことがない (SSRF)、
-//   * 変換が同期のままで、CSP でも動く、
-//   * 何が読まれうるかが呼び出し側のコードに全部書いてある、
-// の三つが同時に成り立つからで、非同期ローダーではどれも失われる。
+// External documents are **only what the caller passed in**; nothing is
+// fetched. Taking a map rather than a loader function is what makes all three
+// of these true at once:
+//   * a URI written in a schema can never make this process open a socket,
+//   * conversion stays synchronous, so it works under CSP,
+//   * everything that could possibly be read is visible in the caller's code.
+// An async loader gives up all three.
 // ===========================================================================
 const draft07_types_1 = require("./draft07.types");
 const types_1 = require("../types");

package/dist/json-schema/schema-registry.mjs

@@ -1,17 +1,18 @@
 // ===========================================================================
-// L8  src/json-schema/schema-registry.ts — どの URI がどのスキーマを指すか。
+// L8  src/json-schema/schema-registry.ts — which URI names which schema.
 //
-// Draft-07 §8.2 では `$id` が二つの働きをする: 場所を示す URI はベースを
-// 立て直し、`#name` の形は**位置に依らない名前**を付ける。どちらも
-// 「この URI はこのノード」という索引で、それがこのファイルの責務である。
-// ポインタ (`#/definitions/x`) を辿るのは場所の話なので resolve-ref.ts が持つ。
+// Draft-07 §8.2 gives `$id` two jobs: a URI that names a location re-bases
+// what follows, and the `#name` form gives a **location-independent name**.
+// Both are the same index — this URI is that node — which is this file's whole
+// responsibility. Walking a pointer is about location, and lives elsewhere.
 //
-// 外部文書は**呼び出し側が渡したものだけ**である。Luq は取りに行かない:
-// 関数ではなく地図 (`externalDocuments`) を受けるのは、そうすれば
-//   * スキーマに書かれた URI でプロセスがソケットを開くことがない (SSRF)、
-//   * 変換が同期のままで、CSP でも動く、
-//   * 何が読まれうるかが呼び出し側のコードに全部書いてある、
-// の三つが同時に成り立つからで、非同期ローダーではどれも失われる。
+// External documents are **only what the caller passed in**; nothing is
+// fetched. Taking a map rather than a loader function is what makes all three
+// of these true at once:
+//   * a URI written in a schema can never make this process open a socket,
+//   * conversion stays synchronous, so it works under CSP,
+//   * everything that could possibly be read is visible in the caller's code.
+// An async loader gives up all three.
 // ===========================================================================
 import { isDraft07Schema, isSchemaObject } from "./draft07.types.mjs";
 import { isArray, isPlainObject } from "../types/index.mjs";

package/dist/json-schema/uri-reference.js

@@ -1,20 +1,20 @@
 "use strict";
 // ===========================================================================
-// L8  src/json-schema/uri-reference.ts — `$id` と `$ref` の URI 演算。
+// L8  src/json-schema/uri-reference.ts — the URI arithmetic of `$id`/`$ref`.
 //
-// Draft-07 §8.2 の `$id` はベース URI を立て、`$ref` はその上で解決される。
-// つまり `$ref` は「文書内のポインタ」ではなく **URI 参照** であり、
-// 同じ文字列でも、どの `$id` の下に書かれたかで別の場所を指す。
+// Draft-07 §8.2 makes `$id` establish a base URI that `$ref` resolves
+// against. A `$ref` is therefore a **URI reference** and not a pointer within
+// a document: the same string points somewhere else depending on which `$id`
+// it was written under.
 //
-// 解決は WHATWG URL に任せる。RFC 3986 §5.3 を手で書き直しても、
-// パーセント符号化・ドットセグメント・スキーム相対 (`//host/x`) の三つで
-// 必ずずれる — そして URL はブラウザにも Node にもある標準グローバルで、
-// eval も new Function も使わない (check:no-dynamic-code が見ている)。
+// Resolution is delegated to the WHATWG URL. Rewriting RFC 3986 §5.3 by hand
+// goes wrong on percent-encoding, dot segments and scheme-relative
+// (`//host/x`) every time — and URL is a standard global in both browsers and
+// Node, needing neither eval nor new Function.
 //
-// ネットワークには**触れない**。ここにあるのは文字列演算だけで、
-// 解決した URI をどう手に入れるかは呼び出し側の責任である
-// (schema-registry.ts の externalDocuments)。スキーマが書いた URI で
-// このプロセスがソケットを開くことは無い。
+// **Nothing here touches the network.** This is string arithmetic; how a
+// resolved URI is actually obtained is the caller's responsibility. A URI
+// written in a schema never causes this process to open a socket.
 // ===========================================================================
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.splitUri = splitUri;