@maroonedog/luq 2.0.0 → 2.2.0

package/dist/chain/chain-method.types.d.ts

@@ -1,13 +1,18 @@
-import type { GuardOut, TransformOut } from "../plugin-kit/marker.types";
+import type { BundleOut, GuardOut, StitchOut, TransformOut } from "../plugin-kit/marker.types";
+import type { BundleChain, BundlePaths } from "./bundle-paths.types";
 import type { PluginDefinition, PluginSignature } from "../plugin-kit/plugin-definition";
-import type { Present, RuleOptions, TypeName } from "../types";
+import type { CrossFieldOutcome, Present, RuleOptions, TypeName } from "../types";
+import type { FieldPath } from "../path/field-path.types";
+import type { PickPaths } from "../path/value-at-path.types";
 import type { PluginBag } from "./plugin-bag.types";
 import type { ChainState, CoverWith } from "./chain-state.types";
 import type { ResolveArgs, ResolveOut } from "./resolve-args.types";
 import type { AnyChain, FieldChain } from "./field-chain.types";
 import type { FieldSlots } from "./field-slots.types";
 /** One plugin definition -> one call signature. */
-export type ChainMethod<P, B extends PluginBag, S extends TypeName, TRoot, TValue, TState extends ChainState> = P extends PluginDefinition<string, string, readonly TypeName[], infer Sig extends PluginSignature> ? [Sig["out"]] extends [TransformOut] ? <R>(map: (value: Present<TValue, TState>) => R, options?: RuleOptions<Sig["context"]>) => FieldChain<B, S, TRoot, R, TState> : [Sig["out"]] extends [GuardOut] ? <X extends Present<TValue, TState>>(condition: (value: Present<TValue, TState>) => value is X, define: (b: FieldSlots<TRoot, B, X>) => AnyChain, options?: RuleOptions<Sig["context"]>) => FieldChain<B, S, TRoot, TValue, CoverWith<TState, X>> : (...args: [
+export type ChainMethod<P, B extends PluginBag, S extends TypeName, TRoot, TValue, TState extends ChainState> = P extends PluginDefinition<string, string, readonly TypeName[], infer Sig extends PluginSignature> ? [Sig["out"]] extends [TransformOut] ? <R>(map: (value: Present<TValue, TState>) => R, options?: RuleOptions<Sig["context"]>) => FieldChain<B, S, TRoot, R, TState> : [Sig["out"]] extends [GuardOut] ? <X extends Present<TValue, TState>>(condition: (value: Present<TValue, TState>) => value is X, define: (b: FieldSlots<TRoot, B, X>) => AnyChain, options?: RuleOptions<Sig["context"]>) => FieldChain<B, S, TRoot, TValue, CoverWith<TState, X>> : [
+    Sig["out"]
+] extends [StitchOut] ? <const F extends readonly (FieldPath<TRoot> & string)[]>(fields: F, check: (fieldValues: PickPaths<TRoot, F>, value: Present<TValue, TState>, root: TRoot) => CrossFieldOutcome, options?: RuleOptions<Sig["context"]>) => FieldChain<B, S, TRoot, TValue, TState> : [Sig["out"]] extends [BundleOut] ? <const M extends BundlePaths<TRoot>>(fields: M, define: BundleChain<TRoot, M, B>, options?: RuleOptions<Sig["context"]>) => FieldChain<B, S, TRoot, TValue, TState> : (...args: [
     ...ResolveArgs<Sig["args"], B, TRoot, TValue, TState>,
     options?: RuleOptions<Sig["context"]>
 ]) => ResolveOut<Sig["out"], TValue, TState> extends [

package/dist/chain/create-chain-node.js

@@ -22,6 +22,7 @@ exports.readChainRules = readChainRules;
 // needs no assertion and no runtime shape check.
 // ===========================================================================
 const types_1 = require("../types");
+const create_rule_1 = require("../plugin-kit/create-rule");
 const refine_methods_types_1 = require("./refine-methods.types");
 const attach_slot_methods_1 = require("./attach-slot-methods");
 const chainRulesByNode = new WeakMap();
@@ -52,13 +53,33 @@ function buildRuleContext(wiring, plugin, rawOptions) {
         declaredSiblingKeys: wiring.context.declaredSiblingKeys,
     };
 }
+/**
+ * The presence rule a `judgesNull` plugin brings with it. It forbids
+ * NOTHING — it only says that null must reach the checks instead of ending
+ * the field, which is the one thing a check cannot say for itself.
+ */
+function nullIsAValue(severity) {
+    return (0, create_rule_1.presence)({
+        code: "type",
+        severity,
+        allowUndefined: true,
+        allowNull: true,
+        emptyStringIsMissing: false,
+        nullIsValue: true,
+        describe: (messageContext) => `${messageContext.path} must not be null`,
+        buildMessageContext: () => ({}),
+    });
+}
 function createSlotMethod(wiring, slot, rules, plugin) {
     const arity = Math.max(plugin.build.length - 1, 0);
     return (...args) => {
         const rawOptions = args.length > arity ? args[arity] : undefined;
         const resolved = wiring.resolveArguments(plugin, args.slice(0, arity));
         const rule = plugin.build(buildRuleContext(wiring, plugin, rawOptions), ...resolved);
-        return createChainNode(wiring, slot, [...rules, rule]);
+        const added = plugin.judgesNull === true
+            ? [nullIsAValue(wiring.context.config.defaultSeverity), rule]
+            : [rule];
+        return createChainNode(wiring, slot, [...rules, ...added]);
     };
 }
 function attachRefineMethods(target, wiring, rules) {

package/dist/chain/create-chain-node.mjs

@@ -17,6 +17,7 @@
 // needs no assertion and no runtime shape check.
 // ===========================================================================
 import { isPlainObject, isString } from "../types/index.mjs";
+import { presence } from "../plugin-kit/create-rule.mjs";
 import { REFINE_METHOD_SLOTS } from "./refine-methods.types.mjs";
 import { attachSlotMethods } from "./attach-slot-methods.mjs";
 const chainRulesByNode = new WeakMap();
@@ -47,13 +48,33 @@ function buildRuleContext(wiring, plugin, rawOptions) {
         declaredSiblingKeys: wiring.context.declaredSiblingKeys,
     };
 }
+/**
+ * The presence rule a `judgesNull` plugin brings with it. It forbids
+ * NOTHING — it only says that null must reach the checks instead of ending
+ * the field, which is the one thing a check cannot say for itself.
+ */
+function nullIsAValue(severity) {
+    return presence({
+        code: "type",
+        severity,
+        allowUndefined: true,
+        allowNull: true,
+        emptyStringIsMissing: false,
+        nullIsValue: true,
+        describe: (messageContext) => `${messageContext.path} must not be null`,
+        buildMessageContext: () => ({}),
+    });
+}
 function createSlotMethod(wiring, slot, rules, plugin) {
     const arity = Math.max(plugin.build.length - 1, 0);
     return (...args) => {
         const rawOptions = args.length > arity ? args[arity] : undefined;
         const resolved = wiring.resolveArguments(plugin, args.slice(0, arity));
         const rule = plugin.build(buildRuleContext(wiring, plugin, rawOptions), ...resolved);
-        return createChainNode(wiring, slot, [...rules, rule]);
+        const added = plugin.judgesNull === true
+            ? [nullIsAValue(wiring.context.config.defaultSeverity), rule]
+            : [rule];
+        return createChainNode(wiring, slot, [...rules, ...added]);
     };
 }
 function attachRefineMethods(target, wiring, rules) {

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. */
@@ -37,11 +38,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. */
@@ -33,11 +34,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.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,14 +13,22 @@ 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;
+/** 添字はここでは入らない。開いている添字は実行時に接頭辞が持つ。 */
+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;
     const template = Object.freeze(request.template);
+    // read を先に作る。ワイルドカードを含むテンプレートを拒むのは
+    // createValueReader の役目で、それより先に formatIssuePath を呼ぶと
+    // 「添字が足りない」という RangeError が、本来の PathSyntaxError を
+    // 追い越して出てしまう (テストがそれを捕まえた)。
+    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,

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,14 +8,22 @@ 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;
+/** 添字はここでは入らない。開いている添字は実行時に接頭辞が持つ。 */
+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;
     const template = Object.freeze(request.template);
+    // read を先に作る。ワイルドカードを含むテンプレートを拒むのは
+    // createValueReader の役目で、それより先に formatIssuePath を呼ぶと
+    // 「添字が足りない」という RangeError が、本来の PathSyntaxError を
+    // 追い越して出てしまう (テストがそれを捕まえた)。
+    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,

package/dist/compile/resolve-conditional-presence.js

@@ -33,6 +33,7 @@ function toPolicy(rule, allowance) {
         allowUndefined: allowance.allowUndefined,
         allowNull: allowance.allowNull,
         emptyStringIsMissing: allowance.emptyStringIsMissing,
+        nullIsValue: allowance.nullIsValue === true,
         // Wrapped rather than aliased, so a `describe` written as an object
         // method keeps its receiver.
         describe: (messageContext) => rule.describe(messageContext),

package/dist/compile/resolve-conditional-presence.mjs

@@ -29,6 +29,7 @@ function toPolicy(rule, allowance) {
         allowUndefined: allowance.allowUndefined,
         allowNull: allowance.allowNull,
         emptyStringIsMissing: allowance.emptyStringIsMissing,
+        nullIsValue: allowance.nullIsValue === true,
         // Wrapped rather than aliased, so a `describe` written as an object
         // method keeps its receiver.
         describe: (messageContext) => rule.describe(messageContext),

package/dist/compile/resolve-presence.js

@@ -11,6 +11,7 @@ const OPEN_POLICY = {
     allowUndefined: true,
     allowNull: true,
     emptyStringIsMissing: false,
+    nullIsValue: false,
     describe: () => "This field declares no presence rule",
 };
 exports.OPEN_PRESENCE = Object.freeze(OPEN_POLICY);
@@ -24,6 +25,9 @@ function resolvePresence(rules) {
         allowUndefined: rules.some((rule) => rule.allowUndefined),
         allowNull: rules.some((rule) => rule.allowNull),
         emptyStringIsMissing: rules.some((rule) => rule.emptyStringIsMissing),
+        // One rule saying "null is a value here" is enough: the checks then run
+        // and decide, which is strictly more judgement, never less.
+        nullIsValue: rules.some((rule) => rule.nullIsValue === true),
         describe: (ctx) => strictest.describe(ctx),
     };
     return Object.freeze(policy);

package/dist/compile/resolve-presence.mjs

@@ -7,6 +7,7 @@ const OPEN_POLICY = {
     allowUndefined: true,
     allowNull: true,
     emptyStringIsMissing: false,
+    nullIsValue: false,
     describe: () => "This field declares no presence rule",
 };
 export const OPEN_PRESENCE = Object.freeze(OPEN_POLICY);
@@ -20,6 +21,9 @@ export function resolvePresence(rules) {
         allowUndefined: rules.some((rule) => rule.allowUndefined),
         allowNull: rules.some((rule) => rule.allowNull),
         emptyStringIsMissing: rules.some((rule) => rule.emptyStringIsMissing),
+        // One rule saying "null is a value here" is enough: the checks then run
+        // and decide, which is strictly more judgement, never less.
+        nullIsValue: rules.some((rule) => rule.nullIsValue === true),
         describe: (ctx) => strictest.describe(ctx),
     };
     return Object.freeze(policy);

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

@@ -11,6 +11,30 @@ class UnknownRuleKindError extends Error {
     }
 }
 exports.UnknownRuleKindError = UnknownRuleKindError;
+/**
+ * 空の束は一つを共有する。
+ *
+ * 七つの種のうち、どのフィールドもたいてい二つか三つしか使わない。残りは
+ * 空配列だが、フィールドごとに新しく Object.freeze([]) を作っていたので、
+ * 空であること自体は同じなのにマップの同一性だけが全部違っていた。実行時の
+ * `field.gates.length` や `field.transforms` の読み出しは、フィールドを
+ * またぐたびに別の受け手を見ることになる。
+ *
+ * この置き換えは src/compile/resolve-conditional-presence.ts の
+ * NO_PRESENCE_OVERRIDES と src/runtime/output-writer.ts の NO_WRITE_TARGETS が
+ * 既にやっていることを、残りの種にも広げただけである。
+ */
+const NO_RULES_OF_THIS_KIND = Object.freeze([]);
+/**
+ * 空なら共有の一つを返す。中身があるならその配列を凍結して返す。
+ *
+ * `readonly never[]` はどの `readonly R[]` にも代入できるので、共有する
+ * ためにアサーションを書く必要はない。型アサーションを書いてよいのは
+ * src/core/type-erasure.ts だけである。
+ */
+function freezeRules(rules) {
+    return rules.length === 0 ? NO_RULES_OF_THIS_KIND : Object.freeze(rules);
+}
 function splitRulesByKind(rules) {
     const checks = [];
     const presences = [];
@@ -38,13 +62,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,30 @@ export class UnknownRuleKindError extends Error {
         this.name = "UnknownRuleKindError";
     }
 }
+/**
+ * 空の束は一つを共有する。
+ *
+ * 七つの種のうち、どのフィールドもたいてい二つか三つしか使わない。残りは
+ * 空配列だが、フィールドごとに新しく Object.freeze([]) を作っていたので、
+ * 空であること自体は同じなのにマップの同一性だけが全部違っていた。実行時の
+ * `field.gates.length` や `field.transforms` の読み出しは、フィールドを
+ * またぐたびに別の受け手を見ることになる。
+ *
+ * この置き換えは src/compile/resolve-conditional-presence.ts の
+ * NO_PRESENCE_OVERRIDES と src/runtime/output-writer.ts の NO_WRITE_TARGETS が
+ * 既にやっていることを、残りの種にも広げただけである。
+ */
+const NO_RULES_OF_THIS_KIND = Object.freeze([]);
+/**
+ * 空なら共有の一つを返す。中身があるならその配列を凍結して返す。
+ *
+ * `readonly never[]` はどの `readonly R[]` にも代入できるので、共有する
+ * ためにアサーションを書く必要はない。型アサーションを書いてよいのは
+ * src/core/type-erasure.ts だけである。
+ */
+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 +57,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

@@ -23,6 +23,16 @@ export interface PresencePolicy {
     readonly allowUndefined: boolean;
     readonly allowNull: boolean;
     readonly emptyStringIsMissing: boolean;
+    /**
+     * True when `null` is a VALUE this subject has to judge, rather than an
+     * absence presence may settle. Draft-07 sub-schemas need it: `false`,
+     * `{"not": {}}` and an `enum` without null all forbid null WITHOUT saying
+     * anything about `type`, and presence — which runs first — was answering
+     * for them. `[null]` passed `{"items":{"not":{}}}` because no check ever
+     * ran. Only src/json-schema/ sets it; a field the user declared keeps the
+     * builder's meaning, where `.nullable()` ends the field.
+     */
+    readonly nullIsValue: boolean;
     describe(ctx: MessageContext): string;
 }
 /**
@@ -55,6 +65,17 @@ export interface RecursionPolicy {
 }
 export interface CompiledField {
     readonly template: readonly PathSegment[];
+    /**
+     * この フィールド自身のパスを、配列の添字を除いて描画したもの。
+     *
+     * コンパイル時に一度だけ作る。実行時に組み直していたのは、テンプレートが
+     * 固定なので **毎回同じ文字列を作る** ことを意味していた: 50要素・3
+     * フィールドの配列なら、1回の validate で 150 回、issue が1件も出なくても
+     * である。実測でそれが要素あたりの費用の 35% を占めていた。
+     *
+     * 実行時に残るのは、開いている添字の接頭辞と繋ぐ連結ひとつだけになる。
+     */
+    readonly renderedPath: string;
     readonly read: (subject: unknown) => unknown;
     /**
      * null unless the field declared a transform or a default — the runtime then
@@ -85,6 +106,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[];

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

@@ -8,7 +8,7 @@ const create_field_builder_1 = require("../builder/create-field-builder");
 const type_erasure_1 = require("../core/type-erasure");
 const create_structural_context_1 = require("./create-structural-context");
 const declare_presence_1 = require("./declare-presence");
-const declare_value_keywords_1 = require("./declare-value-keywords");
+const ref_scope_1 = require("./ref-scope");
 const draft07_types_1 = require("./draft07.types");
 const flatten_schema_1 = require("./flatten-schema");
 const schema_to_declarations_1 = require("./schema-to-declarations");
@@ -25,11 +25,10 @@ class NotASchemaError extends Error {
 exports.NotASchemaError = NotASchemaError;
 /** The rules ONE declared path carries: its presence policy and its schema. */
 function collectDeclaredRules(declaration, bag, root, chain) {
-    const context = (0, create_structural_context_1.createStructuralContext)({ bag, root, chain }, declaration.schema, Object.freeze([]));
+    const context = (0, create_structural_context_1.createStructuralContext)({ bag, scope: (0, ref_scope_1.createLocalScope)(root), chain }, declaration.schema, Object.freeze([]));
     return Object.freeze([
         ...(0, declare_presence_1.declarePresenceRules)({
             isRequired: declaration.isRequired,
-            allowsNull: (0, declare_value_keywords_1.permitsNull)(declaration.schema),
             severity: chain.config.defaultSeverity,
         }),
         ...(0, schema_to_declarations_1.expandSchemaRules)(declaration.schema, context),

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

@@ -2,7 +2,7 @@ import { createFieldBuilderSurface } from "../builder/create-field-builder.mjs";
 import { eraseSchemaValidator } from "../core/type-erasure.mjs";
 import { createStructuralContext } from "./create-structural-context.mjs";
 import { declarePresenceRules } from "./declare-presence.mjs";
-import { permitsNull } from "./declare-value-keywords.mjs";
+import { createLocalScope } from "./ref-scope.mjs";
 import { isDraft07Schema } from "./draft07.types.mjs";
 import { flattenSchema } from "./flatten-schema.mjs";
 import { expandSchemaRules, readChildSchemas } from "./schema-to-declarations.mjs";
@@ -18,11 +18,10 @@ export class NotASchemaError extends Error {
 }
 /** The rules ONE declared path carries: its presence policy and its schema. */
 function collectDeclaredRules(declaration, bag, root, chain) {
-    const context = createStructuralContext({ bag, root, chain }, declaration.schema, Object.freeze([]));
+    const context = createStructuralContext({ bag, scope: createLocalScope(root), chain }, declaration.schema, Object.freeze([]));
     return Object.freeze([
         ...declarePresenceRules({
             isRequired: declaration.isRequired,
-            allowsNull: permitsNull(declaration.schema),
             severity: chain.config.defaultSeverity,
         }),
         ...expandSchemaRules(declaration.schema, context),

package/dist/json-schema/collect-definitions.d.ts

@@ -1,4 +1,5 @@
 import type { Draft07Schema, Draft07SchemaObject } from "./draft07.types";
+import type { RefScope } from "./ref-scope";
 /** The two container spellings, in the order a pointer would try them. */
 export declare const DEFINITION_CONTAINERS: readonly string[];
 export declare function isDefinitionContainer(keyword: string): boolean;
@@ -10,6 +11,35 @@ export declare function toSchemaObject(schema: Draft07Schema): Draft07SchemaObje
  * this draft `$ref` replaces the object it appears in.
  */
 export declare function resolveSchemaNode(schema: Draft07Schema, root: Draft07Schema): Draft07SchemaObject;
+/** What a node resolved to, and the scope that is in force INSIDE it. */
+export interface ResolvedNode {
+    readonly node: Draft07SchemaObject;
+    readonly scope: RefScope;
+}
+/**
+ * The scope-aware form, and the one the converter uses.
+ *
+ * The returned scope is not the one passed in: following a `$ref` can cross
+ * into another document, and a `$ref` written inside THAT document resolves
+ * against ITS base. Returning only the node — which is what the root-taking
+ * form above can do — loses that, and is why a two-document schema resolved
+ * its second hop against the first document.
+ */
+export declare function resolveSchemaNodeInScope(schema: Draft07Schema, scope: RefScope): ResolvedNode;
+/**
+ * The ONE place a base URI advances. It was also being done by the caller,
+ * and doing it in both meant a relative `$id` was applied twice: a `$ref`
+ * of "nested/foo.json" under `$id: "nested/"` went looking for
+ * ".../nested/nested/foo.json".
+ *
+ * A base-setting `$id` starts a new RESOURCE, so the node also becomes the
+ * document that `#/definitions/x` written under it resolves against. Moving
+ * the base without moving the document is why
+ * `{"$id":"a.json","properties":{"foo":{"$id":"b.json","definitions":{...},
+ * "allOf":[{"$ref":"#/definitions/inner"}]}}}` looked for `inner` in the
+ * OUTER document, where it does not exist.
+ */
+export declare function advanceBase(scope: RefScope, node: Draft07SchemaObject): RefScope;
 /**
  * The pointer a node forwards to, or undefined. Used by the flattener to spot
  * a recursive definition BEFORE it walks into it: `#/definitions/node` inside

package/dist/json-schema/collect-definitions.js

@@ -4,10 +4,14 @@ exports.DEFINITION_CONTAINERS = void 0;
 exports.isDefinitionContainer = isDefinitionContainer;
 exports.toSchemaObject = toSchemaObject;
 exports.resolveSchemaNode = resolveSchemaNode;
+exports.resolveSchemaNodeInScope = resolveSchemaNodeInScope;
+exports.advanceBase = advanceBase;
 exports.readRefPointer = readRefPointer;
 exports.collectDefinitionNames = collectDefinitionNames;
 const draft07_types_1 = require("./draft07.types");
+const ref_scope_1 = require("./ref-scope");
 const resolve_ref_1 = require("./resolve-ref");
+const uri_reference_1 = require("./uri-reference");
 /** `true`: matches every instance. */
 const ALWAYS_SCHEMA = Object.freeze({});
 /** `false`: matches nothing. `not` of the empty schema, so no new rule kind. */
@@ -36,10 +40,50 @@ function toSchemaObject(schema) {
  * this draft `$ref` replaces the object it appears in.
  */
 function resolveSchemaNode(schema, root) {
+    return resolveSchemaNodeInScope(schema, (0, ref_scope_1.createLocalScope)(root)).node;
+}
+/**
+ * The scope-aware form, and the one the converter uses.
+ *
+ * The returned scope is not the one passed in: following a `$ref` can cross
+ * into another document, and a `$ref` written inside THAT document resolves
+ * against ITS base. Returning only the node — which is what the root-taking
+ * form above can do — loses that, and is why a two-document schema resolved
+ * its second hop against the first document.
+ */
+function resolveSchemaNodeInScope(schema, scope) {
     const node = toSchemaObject(schema);
-    if (node.$ref === undefined)
-        return node;
-    return toSchemaObject((0, resolve_ref_1.resolveRef)(node.$ref, root));
+    if (node.$ref === undefined) {
+        // A node's own `$id` moves the base for everything inside it (§8.2).
+        return { node, scope: advanceBase(scope, node) };
+    }
+    // Following a `$ref` lands in whatever base the TARGET lives in, and
+    // resolve-ref already knows it — for a document fetched by URI that is the
+    // retrieval URI, which the draft says wins over the document's own `$id`.
+    const resolved = (0, resolve_ref_1.resolveRefInScope)(node.$ref, scope);
+    return { node: toSchemaObject(resolved.schema), scope: resolved.scope };
+}
+/**
+ * The ONE place a base URI advances. It was also being done by the caller,
+ * and doing it in both meant a relative `$id` was applied twice: a `$ref`
+ * of "nested/foo.json" under `$id: "nested/"` went looking for
+ * ".../nested/nested/foo.json".
+ *
+ * A base-setting `$id` starts a new RESOURCE, so the node also becomes the
+ * document that `#/definitions/x` written under it resolves against. Moving
+ * the base without moving the document is why
+ * `{"$id":"a.json","properties":{"foo":{"$id":"b.json","definitions":{...},
+ * "allOf":[{"$ref":"#/definitions/inner"}]}}}` looked for `inner` in the
+ * OUTER document, where it does not exist.
+ */
+function advanceBase(scope, node) {
+    const id = node.$id;
+    if (typeof id !== "string" || id === "")
+        return scope;
+    const baseUri = (0, uri_reference_1.nextBaseUri)(scope.baseUri, id);
+    if (baseUri === scope.baseUri)
+        return scope;
+    return { ...scope, baseUri, document: node };
 }
 /**
  * The pointer a node forwards to, or undefined. Used by the flattener to spot