@maroonedog/luq 2.1.0 → 2.3.0

package/dist/builder/create-builder.js

@@ -50,6 +50,14 @@ function createBuilderSurface() {
             registerPlugin(registration.plugins, plugin);
             return surface;
         },
+        useAll(plugins) {
+            // 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);
+            }
+            return surface;
+        },
         withConfig(config) {
             registration.config = Object.assign({}, registration.config, config);
             return surface;

package/dist/builder/create-builder.mjs

@@ -44,6 +44,14 @@ export function createBuilderSurface() {
             registerPlugin(registration.plugins, plugin);
             return surface;
         },
+        useAll(plugins) {
+            // 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);
+            }
+            return surface;
+        },
         withConfig(config) {
             registration.config = Object.assign({}, registration.config, config);
             return surface;

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-builder.types.d.ts

@@ -26,6 +26,19 @@ export interface FieldBuilder<T extends object, B extends PluginBag, TDeclared e
 }
 export interface Builder<B extends PluginBag = Record<never, never>> {
     use<P extends AnyPlugin>(plugin: P): Builder<B & BagEntry<P>>;
+    /**
+     * A whole SET of plugins at once — a preset, or any object of them.
+     *
+     * A bag is a name -> plugin map, so a preset is that value and nothing more;
+     * there is no registry and no preset type to learn. `use()` one at a time
+     * still works and still costs only what it names, which is the point of the
+     * subpaths — this is for the case where writing fifteen `use()` lines is the
+     * thing standing between you and the validator.
+     *
+     * Duplicates follow the same rule as `use()`: FIRST WINS, so a preset cannot
+     * quietly replace a plugin you already registered.
+     */
+    useAll<Bag extends PluginBag>(plugins: Bag): Builder<B & Bag>;
     /**
      * The per-builder override of the process-wide GlobalConfig. Merged over
      * getGlobalConfig() once, at build(), and handed to every plugin as

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

@@ -0,0 +1,23 @@
+import type { FieldPath } from "../path/field-path.types";
+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.
+ *
+ * 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`.
+ *
+ * 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/bundle-paths.types.js

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

package/dist/chain/bundle-paths.types.mjs

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

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/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;
+}

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

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

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

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

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

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