@maroonedog/luq 2.2.0 → 2.3.0

package/dist/builder/compile-declarations.d.ts

@@ -1,4 +1,10 @@
 import type { ValidationPlan } from "../compile/validation-plan.types";
 import type { GlobalConfig } from "../types/global-config";
 import type { FieldEntry } from "./field-entry.types";
-export declare function compileDeclarations(entries: readonly FieldEntry[], configOverride: GlobalConfig | undefined): ValidationPlan;
+import type { FieldDeclaredCalls } from "./field-declared-calls.types";
+/** What build() makes in one pass: the plan to run, and what was declared. */
+export interface CompiledDeclarations {
+    readonly plan: ValidationPlan;
+    readonly declaredCalls: readonly FieldDeclaredCalls[];
+}
+export declare function compileDeclarations(entries: readonly FieldEntry[], configOverride: GlobalConfig | undefined): CompiledDeclarations;

package/dist/builder/compile-declarations.js

@@ -26,15 +26,25 @@ const global_config_store_1 = require("./global-config-store");
 function compileDeclarations(entries, configOverride) {
     const config = (0, global_config_1.resolveGlobalConfig)(configOverride, (0, global_config_store_1.getGlobalConfig)());
     const childKeysOf = (0, declared_child_keys_1.indexDeclaredChildKeys)(entries.map((entry) => entry.path));
-    const declarations = entries.map((entry) => ({
-        path: entry.path,
-        rules: entry.collectRules({
+    const declarations = [];
+    const declaredCalls = [];
+    for (const entry of entries) {
+        const outcome = entry.collectRules({
             fieldPath: entry.path,
             declaredSiblingKeys: childKeysOf(entry.path),
             config,
-        }),
-        defaultOf: entry.defaultOf ?? undefined,
-        applyDefaultToNull: entry.applyDefaultToNull,
-    }));
-    return (0, compile_schema_1.compileSchema)(declarations, (0, run_branch_1.createBranchExecutor)());
+        });
+        declarations.push({
+            path: entry.path,
+            rules: outcome.rules,
+            defaultOf: entry.defaultOf ?? undefined,
+            applyDefaultToNull: entry.applyDefaultToNull,
+            normalize: entry.normalize ?? undefined,
+        });
+        declaredCalls.push({ path: entry.path, calls: outcome.calls });
+    }
+    return {
+        plan: (0, compile_schema_1.compileSchema)(declarations, (0, run_branch_1.createBranchExecutor)()),
+        declaredCalls,
+    };
 }

package/dist/builder/compile-declarations.mjs

@@ -23,15 +23,25 @@ import { getGlobalConfig } from "./global-config-store.mjs";
 export function compileDeclarations(entries, configOverride) {
     const config = resolveGlobalConfig(configOverride, getGlobalConfig());
     const childKeysOf = indexDeclaredChildKeys(entries.map((entry) => entry.path));
-    const declarations = entries.map((entry) => ({
-        path: entry.path,
-        rules: entry.collectRules({
+    const declarations = [];
+    const declaredCalls = [];
+    for (const entry of entries) {
+        const outcome = entry.collectRules({
             fieldPath: entry.path,
             declaredSiblingKeys: childKeysOf(entry.path),
             config,
-        }),
-        defaultOf: entry.defaultOf ?? undefined,
-        applyDefaultToNull: entry.applyDefaultToNull,
-    }));
-    return compileSchema(declarations, createBranchExecutor());
+        });
+        declarations.push({
+            path: entry.path,
+            rules: outcome.rules,
+            defaultOf: entry.defaultOf ?? undefined,
+            applyDefaultToNull: entry.applyDefaultToNull,
+            normalize: entry.normalize ?? undefined,
+        });
+        declaredCalls.push({ path: entry.path, calls: outcome.calls });
+    }
+    return {
+        plan: compileSchema(declarations, createBranchExecutor()),
+        declaredCalls,
+    };
 }

package/dist/builder/create-builder.js

@@ -51,9 +51,8 @@ function createBuilderSurface() {
             return surface;
         },
         useAll(plugins) {
-            // 順序は Object.values の列挙順。first-wins なので、同じ名前が二度
-            // 来ても最初のものが残る — プリセットが既に登録したものを黙って
-            // 置き換えることはない。
+            // In enumeration order, first-wins: a name arriving twice keeps the
+            // first one, so a preset never silently replaces what is registered.
             for (const plugin of Object.values(plugins)) {
                 registerPlugin(registration.plugins, plugin);
             }

package/dist/builder/create-builder.mjs

@@ -45,9 +45,8 @@ export function createBuilderSurface() {
             return surface;
         },
         useAll(plugins) {
-            // 順序は Object.values の列挙順。first-wins なので、同じ名前が二度
-            // 来ても最初のものが残る — プリセットが既に登録したものを黙って
-            // 置き換えることはない。
+            // In enumeration order, first-wins: a name arriving twice keeps the
+            // first one, so a preset never silently replaces what is registered.
             for (const plugin of Object.values(plugins)) {
                 registerPlugin(registration.plugins, plugin);
             }

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

@@ -17,9 +17,20 @@ exports.createFieldBuilderSurface = createFieldBuilderSurface;
 const collect_field_rules_1 = require("../chain/collect-field-rules");
 const compile_declarations_1 = require("./compile-declarations");
 const create_plan_validator_1 = require("./create-plan-validator");
+const declared_calls_store_1 = require("./declared-calls-store");
 const resolve_field_default_1 = require("./resolve-field-default");
 /** No declaration yet: shared and frozen, so `.for<T>()` allocates nothing. */
 const NO_ENTRIES = Object.freeze([]);
+/**
+ * Builds the plan and attaches whatever was recorded during that same single
+ * pass. The attachment is external, so the validator gains no member.
+ */
+function buildValidator(entries, configOverride) {
+    const compiled = (0, compile_declarations_1.compileDeclarations)(entries, configOverride);
+    const validator = (0, create_plan_validator_1.createPlanBackedValidator)(compiled.plan);
+    (0, declared_calls_store_1.rememberDeclaredCalls)(validator, compiled.declaredCalls);
+    return validator;
+}
 function createFieldBuilderSurface(bag, configOverride, entries = NO_ENTRIES) {
     const surface = {
         v: (path, define, options) => createFieldBuilderSurface(bag, configOverride, [
@@ -27,7 +38,7 @@ function createFieldBuilderSurface(bag, configOverride, entries = NO_ENTRIES) {
             toFieldEntry(bag, path, define, options),
         ]),
         strict: () => surface,
-        build: () => (0, create_plan_validator_1.createPlanBackedValidator)((0, compile_declarations_1.compileDeclarations)(entries, configOverride)),
+        build: () => buildValidator(entries, configOverride),
     };
     return Object.freeze(surface);
 }
@@ -42,6 +53,7 @@ function toFieldEntry(bag, path, define, options) {
         path,
         defaultOf: policy.defaultOf,
         applyDefaultToNull: policy.applyDefaultToNull,
+        normalize: options?.normalize ?? null,
         collectRules: (context) => (0, collect_field_rules_1.collectFieldRules)(bag, context, define),
     };
 }

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

@@ -14,9 +14,20 @@
 import { collectFieldRules } from "../chain/collect-field-rules.mjs";
 import { compileDeclarations } from "./compile-declarations.mjs";
 import { createPlanBackedValidator } from "./create-plan-validator.mjs";
+import { rememberDeclaredCalls } from "./declared-calls-store.mjs";
 import { resolveFieldDefault } from "./resolve-field-default.mjs";
 /** No declaration yet: shared and frozen, so `.for<T>()` allocates nothing. */
 const NO_ENTRIES = Object.freeze([]);
+/**
+ * Builds the plan and attaches whatever was recorded during that same single
+ * pass. The attachment is external, so the validator gains no member.
+ */
+function buildValidator(entries, configOverride) {
+    const compiled = compileDeclarations(entries, configOverride);
+    const validator = createPlanBackedValidator(compiled.plan);
+    rememberDeclaredCalls(validator, compiled.declaredCalls);
+    return validator;
+}
 export function createFieldBuilderSurface(bag, configOverride, entries = NO_ENTRIES) {
     const surface = {
         v: (path, define, options) => createFieldBuilderSurface(bag, configOverride, [
@@ -24,7 +35,7 @@ export function createFieldBuilderSurface(bag, configOverride, entries = NO_ENTR
             toFieldEntry(bag, path, define, options),
         ]),
         strict: () => surface,
-        build: () => createPlanBackedValidator(compileDeclarations(entries, configOverride)),
+        build: () => buildValidator(entries, configOverride),
     };
     return Object.freeze(surface);
 }
@@ -39,6 +50,7 @@ function toFieldEntry(bag, path, define, options) {
         path,
         defaultOf: policy.defaultOf,
         applyDefaultToNull: policy.applyDefaultToNull,
+        normalize: options?.normalize ?? null,
         collectRules: (context) => collectFieldRules(bag, context, define),
     };
 }

package/dist/builder/declared-calls-store.d.ts

@@ -0,0 +1,9 @@
+import type { FieldDeclaredCalls } from "./field-declared-calls.types";
+/** Called only by build(), attaching to an already frozen validator. */
+export declare function rememberDeclaredCalls(validator: object, calls: readonly FieldDeclaredCalls[]): void;
+/**
+ * undefined means this validator did not come from build(). Keeping it
+ * distinct from the empty list is the point: it lets a writer tell "no
+ * constraints were declared" from "what was declared is not known".
+ */
+export declare function readDeclaredCalls(validator: unknown): readonly FieldDeclaredCalls[] | undefined;

package/dist/builder/declared-calls-store.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rememberDeclaredCalls = rememberDeclaredCalls;
+exports.readDeclaredCalls = readDeclaredCalls;
+const declaredCallsByValidator = new WeakMap();
+/** Called only by build(), attaching to an already frozen validator. */
+function rememberDeclaredCalls(validator, calls) {
+    declaredCallsByValidator.set(validator, calls);
+}
+/**
+ * undefined means this validator did not come from build(). Keeping it
+ * distinct from the empty list is the point: it lets a writer tell "no
+ * constraints were declared" from "what was declared is not known".
+ */
+function readDeclaredCalls(validator) {
+    if (typeof validator !== "object" || validator === null)
+        return undefined;
+    return declaredCallsByValidator.get(validator);
+}

package/dist/builder/declared-calls-store.mjs

@@ -0,0 +1,15 @@
+const declaredCallsByValidator = new WeakMap();
+/** Called only by build(), attaching to an already frozen validator. */
+export function rememberDeclaredCalls(validator, calls) {
+    declaredCallsByValidator.set(validator, calls);
+}
+/**
+ * undefined means this validator did not come from build(). Keeping it
+ * distinct from the empty list is the point: it lets a writer tell "no
+ * constraints were declared" from "what was declared is not known".
+ */
+export function readDeclaredCalls(validator) {
+    if (typeof validator !== "object" || validator === null)
+        return undefined;
+    return declaredCallsByValidator.get(validator);
+}

package/dist/builder/field-declared-calls.types.d.ts

@@ -0,0 +1,6 @@
+import type { DeclaredCall } from "../chain/declared-call.types";
+export interface FieldDeclaredCalls {
+    readonly path: string;
+    /** null means no record was kept; the empty list means nothing was declared. */
+    readonly calls: readonly DeclaredCall[] | null;
+}

package/dist/builder/field-declared-calls.types.js

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

package/dist/builder/field-declared-calls.types.mjs

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

package/dist/builder/field-entry.types.d.ts

@@ -1,10 +1,16 @@
 import type { ChainBuildContext } from "../chain/create-chain-node";
-import type { Rule } from "../plugin-kit/compiled-rule";
+import type { FieldChainOutcome } from "../chain/collect-field-rules";
+import type { FieldNormalizer } from "./field-options.types";
 export interface FieldEntry {
     readonly path: string;
     /** null unless `.v()`'s third argument declared a default. */
     readonly defaultOf: ((root: unknown) => unknown) | null;
     readonly applyDefaultToNull: boolean;
-    /** Runs the user's chain callback ONCE and returns its ordered rules. */
-    collectRules(context: ChainBuildContext): readonly Rule[];
+    /** null unless `.v()`'s third argument declared a normalizer. */
+    readonly normalize: FieldNormalizer | null;
+    /**
+     * Runs the user's chain callback ONCE and returns its ordered rules,
+     * together with what was declared to produce them.
+     */
+    collectRules(context: ChainBuildContext): FieldChainOutcome;
 }

package/dist/builder/field-options.types.d.ts

@@ -1,5 +1,14 @@
 /** The lazy form of a default. A zero-argument function is assignable to it. */
 export type DefaultFactory<TValue> = (root: unknown) => TValue;
+/**
+ * Tidies a value before anything judges it. See `normalize` below.
+ *
+ * Both sides are `unknown` on purpose: the input has not been validated yet,
+ * and a form puts a string in a numeric field, so `"42"` → `42` is the main
+ * use of this layer. Typing it `(value: TValue) => TValue` would be a lie.
+ * What comes back out is judged by the rules, not by the type.
+ */
+export type FieldNormalizer = (value: unknown) => unknown;
 export interface FieldOptions<TValue> {
     /**
      * Substituted before ANY rule looks at the value, so validate() and parse()
@@ -8,4 +17,21 @@ export interface FieldOptions<TValue> {
     readonly default?: TValue | DefaultFactory<TValue>;
     /** Defaults to true — a declared null is replaced, matching 1.x. */
     readonly applyDefaultToNull?: boolean;
+    /**
+     * Tidies the value before anything judges it. Runs straight after
+     * `default` and before presence is decided.
+     *
+     * Same promise as `default`: validate() and parse() judge the same value,
+     * and only parse() writes it back, so the two can never disagree.
+     *
+     * **Never called for undefined or null.** Otherwise
+     * `(v) => String(v).trim()` would turn a missing field into the string
+     * `"undefined"` and let it past `.required()`. Absence is `default`'s
+     * business; this one only ever sees a value that is there, which is why a
+     * normalizer needs no null check of its own.
+     *
+     * That ordering is what makes the common case work: `"  "` → trim → `""`
+     * → presence reads the empty string as missing → required reports it.
+     */
+    readonly normalize?: FieldNormalizer;
 }

package/dist/chain/bundle-paths.types.d.ts

@@ -3,24 +3,21 @@ import type { ValueAtPath } from "../path/value-at-path.types";
 import type { AnyChain } from "./field-chain.types";
 import type { FieldSlots } from "./field-slots.types";
 import type { PluginBag } from "./plugin-bag.types";
-/** 別名 -> ルートのパス。パスはルートに実在するものしか書けない。 */
+/** Alias to a path from the root; only paths that exist there are writable. */
 export type BundlePaths<TRoot> = Readonly<Record<string, FieldPath<TRoot> & string>>;
-/** 対応表から組み上がる束。別名がキーで、値はそのパスの値。 */
+/** The bundle built from the table: aliases as keys, the path's value as value. */
 export type BundleOf<TRoot, M extends BundlePaths<TRoot>> = {
     readonly [A in keyof M & string]: ValueAtPath<TRoot, M[A]>;
 };
 /**
- * 束ひとつに対するサブチェーン。
+ * The sub-chain for one bundle.
  *
- * stitch の核は「複数のフィールドを **1つの判定** にまとめる」ことなので、
- * 主体は束そのものであって別名ごとではない。別名ごとにルールを並べる形も
- * 書けるが、それは `total === price * quantity` のような判定が書けず、
- * stitch ではなくなる。
+ * The subject is the bundle itself, not each alias: bringing several fields
+ * into ONE judgement is the point, and a per-alias form cannot express
+ * `total === price * quantity`.
  *
- * 主体が束なので、束の中を `.v()` 的に見るのではなく、`b.object` などの
- * スロットがそのまま開く。型は BundleOf なので、束のメンバーは補完も効くし
- * 取り違えればコンパイルエラーになる — stitch が
- * `Readonly<Record<string, unknown>>` を渡していたのに対する、ここの一点だけ
- * が違いである。
+ * Because the subject is the bundle, the slots (`b.object` and friends) open
+ * on it directly rather than descending into it. The bundle is typed, so its
+ * members complete and mistaking one fails to compile.
  */
 export type BundleChain<TRoot, M extends BundlePaths<TRoot>, B extends PluginBag> = (b: FieldSlots<BundleOf<TRoot, M>, B, BundleOf<TRoot, M>>) => AnyChain;

package/dist/chain/chain-node-store.d.ts

@@ -0,0 +1,5 @@
+import type { Rule } from "../plugin-kit/compiled-rule";
+/** Called only by whoever made the node, once, just before freezing it. */
+export declare function rememberChainNode(node: object, rules: readonly Rule[]): void;
+/** The one way back out of a chain: undefined for anything that is not a node. */
+export declare function readChainNode(candidate: unknown): readonly Rule[] | undefined;

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

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rememberChainNode = rememberChainNode;
+exports.readChainNode = readChainNode;
+const rulesByNode = new WeakMap();
+/** Called only by whoever made the node, once, just before freezing it. */
+function rememberChainNode(node, rules) {
+    rulesByNode.set(node, rules);
+}
+/** The one way back out of a chain: undefined for anything that is not a node. */
+function readChainNode(candidate) {
+    if (typeof candidate !== "object" || candidate === null)
+        return undefined;
+    return rulesByNode.get(candidate);
+}

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

@@ -0,0 +1,11 @@
+const rulesByNode = new WeakMap();
+/** Called only by whoever made the node, once, just before freezing it. */
+export function rememberChainNode(node, rules) {
+    rulesByNode.set(node, rules);
+}
+/** The one way back out of a chain: undefined for anything that is not a node. */
+export function readChainNode(candidate) {
+    if (typeof candidate !== "object" || candidate === null)
+        return undefined;
+    return rulesByNode.get(candidate);
+}

package/dist/chain/collect-field-rules.d.ts

@@ -2,9 +2,20 @@ import type { Rule } from "../plugin-kit/compiled-rule";
 import type { PluginBag } from "./plugin-bag.types";
 import type { AnyChain } from "./field-chain.types";
 import type { FieldSlots } from "./field-slots.types";
-import { type ChainBuildContext } from "./create-chain-node";
+import type { ChainBuildContext } from "./create-chain-node";
+import type { DeclaredCall } from "./declared-call.types";
+/** What the single run produced: rules for the runtime, calls for a writer. */
+export interface FieldChainOutcome {
+    readonly rules: readonly Rule[];
+    /**
+     * null means no record was kept, which is not the empty list's "nothing was
+     * declared". Collapsing the two lets a writer return a schema with no
+     * constraints and no idea that it is missing them.
+     */
+    readonly calls: readonly DeclaredCall[] | null;
+}
 export declare class FieldChainResultError extends Error {
     readonly fieldPath: string;
     constructor(fieldPath: string);
 }
-export declare function collectFieldRules<TRoot, B extends PluginBag, TField>(bag: B, context: ChainBuildContext, define: (b: FieldSlots<TRoot, B, TField>) => AnyChain): readonly Rule[];
+export declare function collectFieldRules<TRoot, B extends PluginBag, TField>(bag: B, context: ChainBuildContext, define: (b: FieldSlots<TRoot, B, TField>) => AnyChain): FieldChainOutcome;

package/dist/chain/collect-field-rules.js

@@ -2,7 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FieldChainResultError = void 0;
 exports.collectFieldRules = collectFieldRules;
-const create_chain_node_1 = require("./create-chain-node");
+const chain_node_store_1 = require("./chain-node-store");
+const declaration_recorder_port_1 = require("./declaration-recorder.port");
 const create_field_slots_1 = require("./create-field-slots");
 class FieldChainResultError extends Error {
     constructor(fieldPath) {
@@ -15,8 +16,14 @@ class FieldChainResultError extends Error {
 exports.FieldChainResultError = FieldChainResultError;
 function collectFieldRules(bag, context, define) {
     const chain = define((0, create_field_slots_1.createFieldSlots)(bag, context));
-    const rules = (0, create_chain_node_1.readChainRules)(chain);
+    const rules = (0, chain_node_store_1.readChainNode)(chain);
     if (rules === undefined)
         throw new FieldChainResultError(context.fieldPath);
-    return Object.freeze(rules.slice());
+    const recorder = declaration_recorder_port_1.declarationRecorder;
+    return Object.freeze({
+        rules: Object.freeze(rules.slice()),
+        calls: recorder === null
+            ? null
+            : Object.freeze((recorder.read(chain) ?? []).slice()),
+    });
 }

package/dist/chain/collect-field-rules.mjs

@@ -1,4 +1,5 @@
-import { readChainRules } from "./create-chain-node.mjs";
+import { readChainNode } from "./chain-node-store.mjs";
+import { declarationRecorder } from "./declaration-recorder.port.mjs";
 import { createFieldSlots } from "./create-field-slots.mjs";
 export class FieldChainResultError extends Error {
     constructor(fieldPath) {
@@ -10,8 +11,14 @@ export class FieldChainResultError extends Error {
 }
 export function collectFieldRules(bag, context, define) {
     const chain = define(createFieldSlots(bag, context));
-    const rules = readChainRules(chain);
+    const rules = readChainNode(chain);
     if (rules === undefined)
         throw new FieldChainResultError(context.fieldPath);
-    return Object.freeze(rules.slice());
+    const recorder = declarationRecorder;
+    return Object.freeze({
+        rules: Object.freeze(rules.slice()),
+        calls: recorder === null
+            ? null
+            : Object.freeze((recorder.read(chain) ?? []).slice()),
+    });
 }

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

@@ -20,12 +20,18 @@ exports.readChainRules = readChainRules;
 // The rule list is held in a WeakMap rather than on the node, so the node
 // carries exactly the members its type declares and reading the rules back
 // needs no assertion and no runtime shape check.
+//
+// A node does NOT carry what was called with what. This file builds no record
+// of the call; it only notifies whoever asked to be told, and with nobody
+// asking that is one null check per chain step. See
+// declaration-recorder.port.ts.
 // ===========================================================================
 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();
+const declaration_recorder_port_1 = require("./declaration-recorder.port");
+const chain_node_store_1 = require("./chain-node-store");
 const EMPTY_RECORD = Object.freeze({});
 exports.EMPTY_RULES = Object.freeze([]);
 function isIssueSeverity(value) {
@@ -70,7 +76,7 @@ function nullIsAValue(severity) {
         buildMessageContext: () => ({}),
     });
 }
-function createSlotMethod(wiring, slot, rules, plugin) {
+function createSlotMethod(wiring, parent, slot, rules, plugin) {
     const arity = Math.max(plugin.build.length - 1, 0);
     return (...args) => {
         const rawOptions = args.length > arity ? args[arity] : undefined;
@@ -79,25 +85,29 @@ function createSlotMethod(wiring, slot, rules, plugin) {
         const added = plugin.judgesNull === true
             ? [nullIsAValue(wiring.context.config.defaultSeverity), rule]
             : [rule];
-        return createChainNode(wiring, slot, [...rules, ...added]);
+        const child = createChainNode(wiring, slot, [...rules, ...added]);
+        declaration_recorder_port_1.declarationRecorder?.record(parent, child, plugin, slot, resolved);
+        return child;
     };
 }
 function attachRefineMethods(target, wiring, rules) {
     for (const [methodName, slot] of Object.entries(refine_methods_types_1.REFINE_METHOD_SLOTS)) {
-        target[methodName] = () => createChainNode(wiring, slot, rules);
+        target[methodName] = () => {
+            const child = createChainNode(wiring, slot, rules);
+            declaration_recorder_port_1.declarationRecorder?.inherit(target, child);
+            return child;
+        };
     }
 }
 /** The runtime value behind FieldChain. Erased to its type by its callers. */
 function createChainNode(wiring, slot, rules) {
     const node = {};
     attachRefineMethods(node, wiring, rules);
-    (0, attach_slot_methods_1.attachSlotMethods)(node, wiring.bag, slot, (plugin) => createSlotMethod(wiring, slot, rules, plugin));
-    chainRulesByNode.set(node, rules);
+    (0, attach_slot_methods_1.attachSlotMethods)(node, wiring.bag, slot, (plugin) => createSlotMethod(wiring, node, slot, rules, plugin));
+    (0, chain_node_store_1.rememberChainNode)(node, rules);
     return Object.freeze(node);
 }
 /** The one way back out of a chain: undefined when the value is not a node. */
 function readChainRules(candidate) {
-    if (typeof candidate !== "object" || candidate === null)
-        return undefined;
-    return chainRulesByNode.get(candidate);
+    return (0, chain_node_store_1.readChainNode)(candidate);
 }

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

@@ -15,12 +15,18 @@
 // The rule list is held in a WeakMap rather than on the node, so the node
 // carries exactly the members its type declares and reading the rules back
 // needs no assertion and no runtime shape check.
+//
+// A node does NOT carry what was called with what. This file builds no record
+// of the call; it only notifies whoever asked to be told, and with nobody
+// asking that is one null check per chain step. See
+// declaration-recorder.port.ts.
 // ===========================================================================
 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();
+import { declarationRecorder } from "./declaration-recorder.port.mjs";
+import { readChainNode, rememberChainNode } from "./chain-node-store.mjs";
 const EMPTY_RECORD = Object.freeze({});
 export const EMPTY_RULES = Object.freeze([]);
 function isIssueSeverity(value) {
@@ -65,7 +71,7 @@ function nullIsAValue(severity) {
         buildMessageContext: () => ({}),
     });
 }
-function createSlotMethod(wiring, slot, rules, plugin) {
+function createSlotMethod(wiring, parent, slot, rules, plugin) {
     const arity = Math.max(plugin.build.length - 1, 0);
     return (...args) => {
         const rawOptions = args.length > arity ? args[arity] : undefined;
@@ -74,25 +80,29 @@ function createSlotMethod(wiring, slot, rules, plugin) {
         const added = plugin.judgesNull === true
             ? [nullIsAValue(wiring.context.config.defaultSeverity), rule]
             : [rule];
-        return createChainNode(wiring, slot, [...rules, ...added]);
+        const child = createChainNode(wiring, slot, [...rules, ...added]);
+        declarationRecorder?.record(parent, child, plugin, slot, resolved);
+        return child;
     };
 }
 function attachRefineMethods(target, wiring, rules) {
     for (const [methodName, slot] of Object.entries(REFINE_METHOD_SLOTS)) {
-        target[methodName] = () => createChainNode(wiring, slot, rules);
+        target[methodName] = () => {
+            const child = createChainNode(wiring, slot, rules);
+            declarationRecorder?.inherit(target, child);
+            return child;
+        };
     }
 }
 /** The runtime value behind FieldChain. Erased to its type by its callers. */
 export function createChainNode(wiring, slot, rules) {
     const node = {};
     attachRefineMethods(node, wiring, rules);
-    attachSlotMethods(node, wiring.bag, slot, (plugin) => createSlotMethod(wiring, slot, rules, plugin));
-    chainRulesByNode.set(node, rules);
+    attachSlotMethods(node, wiring.bag, slot, (plugin) => createSlotMethod(wiring, node, slot, rules, plugin));
+    rememberChainNode(node, rules);
     return Object.freeze(node);
 }
 /** The one way back out of a chain: undefined when the value is not a node. */
 export function readChainRules(candidate) {
-    if (typeof candidate !== "object" || candidate === null)
-        return undefined;
-    return chainRulesByNode.get(candidate);
+    return readChainNode(candidate);
 }

package/dist/chain/declaration-recorder.port.d.ts

@@ -0,0 +1,31 @@
+import type { TypeName } from "../types";
+import type { AnyPlugin } from "../plugin-kit/plugin-definition";
+import type { DeclaredCall } from "./declared-call.types";
+/**
+ * Only the parent-to-child relation between nodes crosses this line; how the
+ * record is held is the implementation's business. Nothing passed here is
+ * built for the occasion — the plugin, the slot and the arguments are all
+ * already in hand for building the rule.
+ */
+export interface DeclarationRecorder {
+    /**
+     * `child`'s record is `parent`'s with one call appended. Called once, by
+     * whoever made the node, immediately after freezing it.
+     */
+    record(parent: object, child: object, plugin: AnyPlugin, slot: TypeName, args: readonly unknown[]): void;
+    /** A refine step adds no call. It carries the record across unchanged. */
+    inherit(parent: object, child: object): void;
+    /** The calls declared up to that node, or undefined when there are none. */
+    read(node: object): readonly DeclaredCall[] | undefined;
+}
+/**
+ * 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 declare let declarationRecorder: DeclarationRecorder | null;
+/**
+ * Called once, when the implementation is loaded. A second call overwrites,
+ * which is harmless while there is one implementation.
+ */
+export declare function installDeclarationRecorder(recorder: DeclarationRecorder | null): void;

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.declarationRecorder = void 0;
+exports.installDeclarationRecorder = installDeclarationRecorder;
+/**
+ * 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.
+ */
+exports.declarationRecorder = null;
+/**
+ * Called once, when the implementation is loaded. A second call overwrites,
+ * which is harmless while there is one implementation.
+ */
+function installDeclarationRecorder(recorder) {
+    exports.declarationRecorder = recorder;
+}