@maroonedog/luq 0.1.2-alpha → 2.1.0

package/dist/plugin-kit/external-context.d.ts

@@ -0,0 +1,2 @@
+import { type RuleContext } from "../types";
+export declare function readExternalContext<C extends object>(ctx: RuleContext, isContext: (value: unknown) => value is C): C | undefined;

package/dist/plugin-kit/external-context.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readExternalContext = readExternalContext;
+// ===========================================================================
+// L2  src/plugin-kit/external-context.ts
+// RESIDUAL 4 / item 1 — the READ side of the async story.
+//
+// It lives at L2, not at L9, for a layering reason found by compiling: the only
+// consumer that matters is a PLUGIN (fromContext), and a plugin at L7 may not
+// import L9. L9 re-exports this under the 1.x name so the public surface is
+// unchanged, but the mechanism is a plain read of RuleContext.external, which
+// is L0 vocabulary. Nothing in the engine knows the word "async".
+//
+// 1.x's getAsyncContext<C>(context) asserted the shape. Here the caller passes
+// the guard that proves it — alternative 2 in the code standard, not
+// alternative 4 — so a context that never resolved cannot masquerade as one
+// that did.
+// ===========================================================================
+const types_1 = require("../types");
+function readExternalContext(ctx, isContext) {
+    const external = ctx.external;
+    if (external === undefined || !(0, types_1.isPlainObject)(external))
+        return undefined;
+    return isContext(external) ? external : undefined;
+}

package/dist/plugin-kit/external-context.mjs

@@ -0,0 +1,22 @@
+// ===========================================================================
+// L2  src/plugin-kit/external-context.ts
+// RESIDUAL 4 / item 1 — the READ side of the async story.
+//
+// It lives at L2, not at L9, for a layering reason found by compiling: the only
+// consumer that matters is a PLUGIN (fromContext), and a plugin at L7 may not
+// import L9. L9 re-exports this under the 1.x name so the public surface is
+// unchanged, but the mechanism is a plain read of RuleContext.external, which
+// is L0 vocabulary. Nothing in the engine knows the word "async".
+//
+// 1.x's getAsyncContext<C>(context) asserted the shape. Here the caller passes
+// the guard that proves it — alternative 2 in the code standard, not
+// alternative 4 — so a context that never resolved cannot masquerade as one
+// that did.
+// ===========================================================================
+import { isPlainObject } from "../types/index.mjs";
+export function readExternalContext(ctx, isContext) {
+    const external = ctx.external;
+    if (external === undefined || !isPlainObject(external))
+        return undefined;
+    return isContext(external) ? external : undefined;
+}

package/dist/plugin-kit/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./compiled-rule";
+export * from "./create-conditional-presence";
+export * from "./create-rule";
+export * from "./external-context";
+export * from "./is-json-value-equal";
+export * from "./marker.types";
+export * from "./plugin-definition";
+export * from "./rule-build-context";
+export * from "./runtime-args.types";
+export * from "../types";
+export type { FieldPath, LeafPath, MissingLeafPaths, PickPaths, ValueAtPath, } from "../path/index";

package/dist/plugin-kit/index.js

@@ -0,0 +1,39 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// ===========================================================================
+// src/plugin-kit/index.ts — THE ./plugin-kit SUBPATH.
+//
+// Everything a plugin author may import, and nothing else. A plugin under
+// src/plugins/** imports these modules by relative path; a plugin published
+// OUTSIDE this repository imports this subpath. The two must name the same
+// set, so this barrel re-exports exactly the modules the isolation gate
+// permits an isolated-tier plugin to reach: plugin-kit itself, the L0
+// vocabulary, and the L1 path vocabulary.
+//
+// Re-exports only; nothing is defined here.
+// ===========================================================================
+__exportStar(require("./compiled-rule"), exports);
+__exportStar(require("./create-conditional-presence"), exports);
+__exportStar(require("./create-rule"), exports);
+__exportStar(require("./external-context"), exports);
+__exportStar(require("./is-json-value-equal"), exports);
+__exportStar(require("./marker.types"), exports);
+__exportStar(require("./plugin-definition"), exports);
+__exportStar(require("./rule-build-context"), exports);
+__exportStar(require("./runtime-args.types"), exports);
+// ---- the vocabulary a rule reads its value and its context with -----------
+__exportStar(require("../types"), exports);

package/dist/plugin-kit/index.mjs

@@ -0,0 +1,23 @@
+// ===========================================================================
+// src/plugin-kit/index.ts — THE ./plugin-kit SUBPATH.
+//
+// Everything a plugin author may import, and nothing else. A plugin under
+// src/plugins/** imports these modules by relative path; a plugin published
+// OUTSIDE this repository imports this subpath. The two must name the same
+// set, so this barrel re-exports exactly the modules the isolation gate
+// permits an isolated-tier plugin to reach: plugin-kit itself, the L0
+// vocabulary, and the L1 path vocabulary.
+//
+// Re-exports only; nothing is defined here.
+// ===========================================================================
+export * from "./compiled-rule.mjs";
+export * from "./create-conditional-presence.mjs";
+export * from "./create-rule.mjs";
+export * from "./external-context.mjs";
+export * from "./is-json-value-equal.mjs";
+export * from "./marker.types.mjs";
+export * from "./plugin-definition.mjs";
+export * from "./rule-build-context.mjs";
+export * from "./runtime-args.types.mjs";
+// ---- the vocabulary a rule reads its value and its context with -----------
+export * from "../types/index.mjs";

package/dist/plugin-kit/is-json-value-equal.d.ts

@@ -0,0 +1,10 @@
+/** NaN equals NaN; +0 equals -0. `a !== a` is the NaN test that needs no cast. */
+export declare function isSameValueZero(left: unknown, right: unknown): boolean;
+/**
+ * Structural comparison for arrays and PLAIN objects only. A Date, a RegExp, a
+ * Map or a class instance compares by identity, because reading their own
+ * enumerable keys would call every one of them equal to every other — a RegExp
+ * has none at all. JSON has none of those shapes, so nothing that came out of
+ * JSON.parse is affected.
+ */
+export declare function isJsonValueEqual(left: unknown, right: unknown): boolean;

package/dist/plugin-kit/is-json-value-equal.js

@@ -0,0 +1,81 @@
+"use strict";
+// ===========================================================================
+// L2  src/plugin-kit/is-json-value-equal.ts
+// THE single definition of "these two values are the same JSON value".
+//
+// It lives in plugin-kit because FOUR callers need the same answer and a plugin
+// may not import a sibling plugin: `unique` (array-unique), `oneOf`, `literal`,
+// and through the last two the Draft-07 `enum` and `const` keywords. Every one
+// of those keywords is defined by JSON Schema §4.2.3 in terms of the JSON data
+// model, where equality is STRUCTURAL — `{"a":1}` equals `{"a":1}` however many
+// times it was parsed — so three separate `===` tests were three ways of being
+// wrong at once. Measured on the official suite: reference equality cost 17 of
+// the 929 draft7 cases before this module existed.
+//
+// docs/legacy-spec/plugin-catalog-structural.md records two defects this closes
+// for `unique`, and they are the reason the implementation looks the way it does:
+//   * 1.x switched from a `===` double loop to a Set at length 11, so [NaN, NaN]
+//     was a duplicate in a long array and not in a short one. One definition is
+//     used here at every length.
+//   * the rewrite's first draft keyed on JSON.stringify, which is ORDER
+//     dependent: {a:1,b:2} and {b:2,a:1} are the same value and were reported as
+//     distinct. Keys are compared as a set, so order cannot matter.
+//
+// Leaves compare with SameValueZero (NaN equals NaN, +0 equals -0), which is the
+// definition `Set` and `Array.prototype.includes` already use, so `unique`,
+// `includes`, `oneOf` and `literal` all agree about what "the same value" means.
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSameValueZero = isSameValueZero;
+exports.isJsonValueEqual = isJsonValueEqual;
+/** NaN equals NaN; +0 equals -0. `a !== a` is the NaN test that needs no cast. */
+function isSameValueZero(left, right) {
+    return left === right || (left !== left && right !== right);
+}
+/**
+ * Structural comparison for arrays and PLAIN objects only. A Date, a RegExp, a
+ * Map or a class instance compares by identity, because reading their own
+ * enumerable keys would call every one of them equal to every other — a RegExp
+ * has none at all. JSON has none of those shapes, so nothing that came out of
+ * JSON.parse is affected.
+ */
+function isJsonValueEqual(left, right) {
+    if (isSameValueZero(left, right))
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            areElementsEqual(left, right));
+    }
+    if (!isPlainRecord(left) || !isPlainRecord(right))
+        return false;
+    return areEntriesEqual(left, right);
+}
+function areElementsEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let index = 0; index < left.length; index += 1) {
+        if (!isJsonValueEqual(left[index], right[index]))
+            return false;
+    }
+    return true;
+}
+function areEntriesEqual(left, right) {
+    const leftKeys = Object.keys(left);
+    if (leftKeys.length !== Object.keys(right).length)
+        return false;
+    for (const key of leftKeys) {
+        if (!Object.prototype.hasOwnProperty.call(right, key))
+            return false;
+        if (!isJsonValueEqual(left[key], right[key]))
+            return false;
+    }
+    return true;
+}
+/** Object.prototype or a null prototype: anything else keeps its identity. */
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/plugin-kit/is-json-value-equal.mjs

@@ -0,0 +1,77 @@
+// ===========================================================================
+// L2  src/plugin-kit/is-json-value-equal.ts
+// THE single definition of "these two values are the same JSON value".
+//
+// It lives in plugin-kit because FOUR callers need the same answer and a plugin
+// may not import a sibling plugin: `unique` (array-unique), `oneOf`, `literal`,
+// and through the last two the Draft-07 `enum` and `const` keywords. Every one
+// of those keywords is defined by JSON Schema §4.2.3 in terms of the JSON data
+// model, where equality is STRUCTURAL — `{"a":1}` equals `{"a":1}` however many
+// times it was parsed — so three separate `===` tests were three ways of being
+// wrong at once. Measured on the official suite: reference equality cost 17 of
+// the 929 draft7 cases before this module existed.
+//
+// docs/legacy-spec/plugin-catalog-structural.md records two defects this closes
+// for `unique`, and they are the reason the implementation looks the way it does:
+//   * 1.x switched from a `===` double loop to a Set at length 11, so [NaN, NaN]
+//     was a duplicate in a long array and not in a short one. One definition is
+//     used here at every length.
+//   * the rewrite's first draft keyed on JSON.stringify, which is ORDER
+//     dependent: {a:1,b:2} and {b:2,a:1} are the same value and were reported as
+//     distinct. Keys are compared as a set, so order cannot matter.
+//
+// Leaves compare with SameValueZero (NaN equals NaN, +0 equals -0), which is the
+// definition `Set` and `Array.prototype.includes` already use, so `unique`,
+// `includes`, `oneOf` and `literal` all agree about what "the same value" means.
+// ===========================================================================
+/** NaN equals NaN; +0 equals -0. `a !== a` is the NaN test that needs no cast. */
+export function isSameValueZero(left, right) {
+    return left === right || (left !== left && right !== right);
+}
+/**
+ * Structural comparison for arrays and PLAIN objects only. A Date, a RegExp, a
+ * Map or a class instance compares by identity, because reading their own
+ * enumerable keys would call every one of them equal to every other — a RegExp
+ * has none at all. JSON has none of those shapes, so nothing that came out of
+ * JSON.parse is affected.
+ */
+export function isJsonValueEqual(left, right) {
+    if (isSameValueZero(left, right))
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            areElementsEqual(left, right));
+    }
+    if (!isPlainRecord(left) || !isPlainRecord(right))
+        return false;
+    return areEntriesEqual(left, right);
+}
+function areElementsEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let index = 0; index < left.length; index += 1) {
+        if (!isJsonValueEqual(left[index], right[index]))
+            return false;
+    }
+    return true;
+}
+function areEntriesEqual(left, right) {
+    const leftKeys = Object.keys(left);
+    if (leftKeys.length !== Object.keys(right).length)
+        return false;
+    for (const key of leftKeys) {
+        if (!Object.prototype.hasOwnProperty.call(right, key))
+            return false;
+        if (!isJsonValueEqual(left[key], right[key]))
+            return false;
+    }
+    return true;
+}
+/** Object.prototype or a null prototype: anything else keeps its identity. */
+function isPlainRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/plugin-kit/marker.types.d.ts

@@ -0,0 +1,114 @@
+declare const MARKER: unique symbol;
+export interface FieldRef {
+    readonly [MARKER]: "fieldRef";
+}
+export interface FieldRefs {
+    readonly [MARKER]: "fieldRefs";
+}
+export interface RootPredicate {
+    readonly [MARKER]: "rootPredicate";
+}
+export interface RootReader<R> {
+    readonly [MARKER]: "rootReader";
+    readonly read: R;
+}
+export interface SelfReader<R> {
+    readonly [MARKER]: "selfReader";
+    readonly read: R;
+}
+export interface SelfValue {
+    readonly [MARKER]: "selfValue";
+}
+export interface ElementChain {
+    readonly [MARKER]: "elementChain";
+}
+export interface SelfGuard {
+    readonly [MARKER]: "selfGuard";
+}
+export interface NarrowedChain {
+    readonly [MARKER]: "narrowedChain";
+}
+/** A sub-chain over the VALUE behind any property key of the subject object. */
+export interface PropertyValueChain {
+    readonly [MARKER]: "propertyValueChain";
+}
+/** A sub-chain over the property KEY itself, which is always a string. */
+export interface PropertyKeyChain {
+    readonly [MARKER]: "propertyKeyChain";
+}
+export interface Unchanged {
+    readonly [MARKER]: "unchanged";
+}
+export interface TransformOut {
+    readonly [MARKER]: "transformOut";
+}
+export interface GuardOut {
+    readonly [MARKER]: "guardOut";
+}
+export type PresenceShiftKind = "excludeMissing" | "excludeUndefined" | "excludeNull" | "allowNull";
+export interface PresenceShift<K extends PresenceShiftKind> {
+    readonly [MARKER]: "presence";
+    readonly shift: K;
+}
+declare const PROBE: unique symbol;
+/** A type no resolver can produce by accident, used to spot an unresolved marker. */
+export interface MarkerProbe {
+    readonly [PROBE]: true;
+}
+/** THE registry of argument markers. Both resolvers are proved exhaustive
+ *  against it by src/chain/marker-coverage.types.ts. */
+export interface ArgumentMarkerRegistry {
+    readonly fieldRef: FieldRef;
+    readonly fieldRefs: FieldRefs;
+    readonly rootPredicate: RootPredicate;
+    readonly rootReader: RootReader<MarkerProbe>;
+    readonly selfReader: SelfReader<MarkerProbe>;
+    readonly selfValue: SelfValue;
+    readonly elementChain: ElementChain;
+    readonly selfGuard: SelfGuard;
+    readonly narrowedChain: NarrowedChain;
+    readonly propertyValueChain: PropertyValueChain;
+    readonly propertyKeyChain: PropertyKeyChain;
+}
+export type ArgumentMarkerKind = keyof ArgumentMarkerRegistry;
+export interface OutputMarkerRegistry {
+    readonly unchanged: Unchanged;
+    readonly transformOut: TransformOut;
+    readonly guardOut: GuardOut;
+    readonly excludeMissing: PresenceShift<"excludeMissing">;
+    readonly excludeUndefined: PresenceShift<"excludeUndefined">;
+    readonly excludeNull: PresenceShift<"excludeNull">;
+    readonly allowNull: PresenceShift<"allowNull">;
+}
+export type OutputMarkerKind = keyof OutputMarkerRegistry;
+export type ArgumentMarker = ArgumentMarkerRegistry[ArgumentMarkerKind];
+export type AnyMarker = ArgumentMarker | OutputMarkerRegistry[OutputMarkerKind];
+/**
+ * A record whose every value is an argument marker. `patternProperties` and
+ * `dependentSchemas` take one sub-chain PER KEY, and a key set is not a tuple,
+ * so neither resolver's array recursion reached them. Both resolvers now
+ * recurse into exactly this shape and leave every other object argument (e.g.
+ * `{ maxDepth?: number }`) untouched, so the recursion cannot silently rewrite
+ * an ordinary options bag.
+ */
+export type MarkerRecord = Readonly<Record<string, ArgumentMarker>>;
+export type AssertNever<T extends never> = T;
+export type BrandOf<M> = M extends {
+    readonly [MARKER]: infer K extends string;
+} ? K : never;
+type UnbrandedArgumentEntry = {
+    [K in ArgumentMarkerKind]: [BrandOf<ArgumentMarkerRegistry[K]>] extends [
+        never
+    ] ? K : never;
+}[ArgumentMarkerKind];
+type UnbrandedOutputEntry = {
+    [K in OutputMarkerKind]: [BrandOf<OutputMarkerRegistry[K]>] extends [never] ? K : never;
+}[OutputMarkerKind];
+export type MarkerRegistryProof = [
+    AssertNever<UnbrandedArgumentEntry>,
+    AssertNever<UnbrandedOutputEntry>
+];
+type MarkerInOne<A> = [Extract<A, ArgumentMarker>] extends [never] ? [A] extends [readonly unknown[]] ? MarkerInUnion<A[number]> : [A] extends [MarkerRecord] ? true : false : true;
+type MarkerInUnion<A> = A extends unknown ? MarkerInOne<A> : never;
+export type IsMarkerFree<A extends readonly unknown[]> = true extends MarkerInUnion<A[number]> ? false : true;
+export {};

package/dist/plugin-kit/marker.types.js

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

package/dist/plugin-kit/marker.types.mjs

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

package/dist/plugin-kit/plugin-definition.d.ts

@@ -0,0 +1,55 @@
+import type { MessageContextExtra, TypeName } from "../types";
+import type { RuleForOut, RuntimeArgs } from "./runtime-args.types";
+import type { RuleBuildContext } from "./rule-build-context";
+/** TOut defaults to `unknown`, NOT to `Unchanged`. */
+export interface PluginSignature<TArgs extends readonly unknown[] = readonly unknown[], TOut = unknown, TContext extends MessageContextExtra = MessageContextExtra> {
+    readonly args: TArgs;
+    readonly out: TOut;
+    readonly context: TContext;
+}
+export type PluginBuild<TSig extends PluginSignature> = (ctx: RuleBuildContext<TSig["context"]>, ...args: RuntimeArgs<TSig["args"]>) => RuleForOut<TSig["out"]>;
+export interface PluginDefinition<TName extends string, TMethod extends string, TSlots extends readonly TypeName[], TSig extends PluginSignature> {
+    readonly name: TName;
+    readonly method: TMethod;
+    readonly slots: TSlots;
+    build(ctx: RuleBuildContext<TSig["context"]>, ...args: RuntimeArgs<TSig["args"]>): RuleForOut<TSig["out"]>;
+    /**
+     * Which argument POSITIONS carry a sub-chain. Absent on a plugin that takes
+     * none. It cannot be recovered from the signature at run time — a
+     * NarrowedChain and a RootPredicate are both plain functions once the types
+     * are erased — so a composite declares it, and src/chain/collect-branch-rules
+     * resolves exactly those positions to `readonly Rule[]` before build() runs.
+     */
+    readonly subChainArguments?: readonly number[];
+    /** See PluginSpec.judgesNull. Read by src/chain/create-chain-node.ts. */
+    readonly judgesNull?: boolean;
+    readonly signature?: TSig;
+}
+export type AnyPlugin = PluginDefinition<string, string, readonly TypeName[], PluginSignature>;
+export interface PluginSpec<TName extends string, TMethod extends string, TSlots extends readonly TypeName[], TSig extends PluginSignature> {
+    readonly name: TName;
+    readonly method: TMethod;
+    readonly slots: TSlots;
+    readonly build: PluginBuild<TSig>;
+    readonly subChainArguments?: readonly number[];
+    /**
+     * True when this plugin's rule must be given `null` to judge, instead of
+     * presence settling it first.
+     *
+     * A field with no presence rule carries OPEN_PRESENCE, which ENDS the field
+     * on null before a single check runs. For most plugins that is right —
+     * `.min(3)` has no business firing on a value the schema said may be
+     * absent. It is wrong for a plugin that carries a whole document: a JSON
+     * Schema says whether null is allowed, and `false`, `{"not":{}}` and an
+     * `enum` without null all forbid it while saying nothing about `type`.
+     * Without this, `.jsonSchemaFullFeature({"type":"string"})` accepted null.
+     */
+    readonly judgesNull?: boolean;
+}
+/** Curried: the signature is explicit, the identity literals are inferred. */
+export declare function definePlugin<TSig extends PluginSignature>(): <TName extends string, TMethod extends string, TSlots extends readonly TypeName[]>(spec: PluginSpec<TName, TMethod, TSlots, TSig>) => PluginDefinition<TName, TMethod, TSlots, TSig>;
+export type PluginArgs<P> = P extends PluginDefinition<string, string, readonly TypeName[], infer Sig> ? Sig["args"] : never;
+export type PluginOut<P> = P extends PluginDefinition<string, string, readonly TypeName[], infer Sig> ? Sig["out"] : never;
+export declare class PluginArgumentError extends Error {
+    constructor(pluginName: string, argumentName: string, received: unknown);
+}

package/dist/plugin-kit/plugin-definition.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginArgumentError = void 0;
+exports.definePlugin = definePlugin;
+/** Curried: the signature is explicit, the identity literals are inferred. */
+function definePlugin() {
+    return (spec) => ({
+        name: spec.name,
+        method: spec.method,
+        slots: spec.slots,
+        build: spec.build,
+        judgesNull: spec.judgesNull,
+        // Only present when the plugin declared one, so a plugin that takes no
+        // sub-chain keeps exactly the four members it always had.
+        ...(spec.subChainArguments === undefined
+            ? {}
+            : { subChainArguments: spec.subChainArguments }),
+    });
+}
+class PluginArgumentError extends Error {
+    constructor(pluginName, argumentName, received) {
+        super(`${pluginName}: invalid argument "${argumentName}": ${String(received)}`);
+        this.name = "PluginArgumentError";
+    }
+}
+exports.PluginArgumentError = PluginArgumentError;

package/dist/plugin-kit/plugin-definition.mjs

@@ -0,0 +1,21 @@
+/** Curried: the signature is explicit, the identity literals are inferred. */
+export function definePlugin() {
+    return (spec) => ({
+        name: spec.name,
+        method: spec.method,
+        slots: spec.slots,
+        build: spec.build,
+        judgesNull: spec.judgesNull,
+        // Only present when the plugin declared one, so a plugin that takes no
+        // sub-chain keeps exactly the four members it always had.
+        ...(spec.subChainArguments === undefined
+            ? {}
+            : { subChainArguments: spec.subChainArguments }),
+    });
+}
+export class PluginArgumentError extends Error {
+    constructor(pluginName, argumentName, received) {
+        super(`${pluginName}: invalid argument "${argumentName}": ${String(received)}`);
+        this.name = "PluginArgumentError";
+    }
+}

package/dist/plugin-kit/rule-build-context.d.ts

@@ -0,0 +1,27 @@
+import type { IssueSeverity, MessageContext, MessageContextExtra, MessageFactory } from "../types";
+import type { ResolvedGlobalConfig } from "../types/global-config";
+export interface RuleBuildContext<C extends MessageContextExtra = MessageContextExtra> {
+    /** Identity of the plugin whose build() is running. */
+    readonly pluginName: string;
+    /** Error code already resolved from options.code, falling back to pluginName. */
+    readonly code: string;
+    /** Message factory already resolved from options.messageFactory. */
+    readonly messageFactory?: MessageFactory<C>;
+    /**
+     * Already resolved from options.severity, falling back to
+     * config.defaultSeverity. Resolved ONCE, here, for the same reason
+     * options.code is: two resolution sites is how an override stops working.
+     */
+    readonly severity: IssueSeverity;
+    /**
+     * The effective GlobalConfig for the builder that is building this rule.
+     * This is the ONLY way a plugin sees it; nothing reads a process-wide
+     * singleton at validation time.
+     */
+    readonly config: ResolvedGlobalConfig;
+    /** The field this rule is attached to, in L1 grammar. */
+    readonly fieldPath: string;
+    /** Immediate child object keys declared underneath fieldPath, frozen by L4. */
+    readonly declaredSiblingKeys: readonly string[];
+}
+export declare function renderMessage<C extends MessageContextExtra>(factory: MessageFactory<C> | undefined, ctx: MessageContext, extra: C, fallback: string): string;

package/dist/plugin-kit/rule-build-context.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderMessage = renderMessage;
+function renderMessage(factory, ctx, extra, fallback) {
+    return factory === undefined
+        ? fallback
+        : factory(Object.assign({}, ctx, extra));
+}

package/dist/plugin-kit/rule-build-context.mjs

@@ -0,0 +1,5 @@
+export function renderMessage(factory, ctx, extra, fallback) {
+    return factory === undefined
+        ? fallback
+        : factory(Object.assign({}, ctx, extra));
+}

package/dist/plugin-kit/runtime-args.types.d.ts

@@ -0,0 +1,27 @@
+import type { ElementChain, FieldRef, FieldRefs, MarkerRecord, NarrowedChain, PresenceShift, PresenceShiftKind, PropertyKeyChain, PropertyValueChain, RootPredicate, RootReader, SelfGuard, SelfReader, SelfValue, TransformOut } from "./marker.types";
+import type { ArrayItemContext } from "../types";
+import type { PresenceRule, Rule, TransformRule } from "./compiled-rule";
+export type RootPredicateFn = (root: unknown, item?: ArrayItemContext) => boolean;
+export type RootReaderFn<R> = (root: unknown) => R;
+export type SelfReaderFn<R> = (value: unknown) => R;
+export type SelfGuardFn = (value: unknown) => boolean;
+/**
+ * An OPTIONAL tuple element makes `A[I]` be `M | undefined`, which matches no
+ * marker branch. Undefined is stripped before matching and re-added afterwards.
+ */
+export type RuntimeArg<A> = [undefined] extends [A] ? ResolveRuntimeArg<Exclude<A, undefined>> | undefined : ResolveRuntimeArg<A>;
+type ResolveRuntimeArg<A> = [A] extends [FieldRef] ? string : [A] extends [FieldRefs] ? readonly string[] : [A] extends [RootPredicate] ? RootPredicateFn : [A] extends [RootReader<infer R>] ? RootReaderFn<R> : [A] extends [SelfReader<infer R>] ? SelfReaderFn<R> : [A] extends [SelfGuard] ? SelfGuardFn : [A] extends [SelfValue] ? unknown : [A] extends [ElementChain] ? readonly Rule[] : [A] extends [NarrowedChain] ? readonly Rule[] : [A] extends [PropertyValueChain] ? readonly Rule[] : [A] extends [PropertyKeyChain] ? readonly Rule[] : [
+    A
+] extends [readonly unknown[]] ? {
+    [I in keyof A]: RuntimeArg<A[I]>;
+} : [
+    A
+] extends [MarkerRecord] ? {
+    readonly [K in keyof A]: RuntimeArg<A[K]>;
+} : A;
+export type RuntimeArgs<A extends readonly unknown[]> = {
+    [I in keyof A]: RuntimeArg<A[I]>;
+};
+/** The runtime counterpart of the OUTPUT markers. */
+export type RuleForOut<O> = [O] extends [TransformOut] ? TransformRule : [O] extends [PresenceShift<PresenceShiftKind>] ? PresenceRule : Rule;
+export {};

package/dist/plugin-kit/runtime-args.types.js

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

package/dist/plugin-kit/runtime-args.types.mjs

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

package/dist/plugin-kit.d.ts

@@ -0,0 +1 @@
+export * from "./plugin-kit/index";

package/dist/plugin-kit.js

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./plugin-kit/index");

package/dist/plugin-kit.mjs

@@ -0,0 +1 @@
+export * from "./plugin-kit/index.mjs";

package/dist/plugins/array-contains/array-contains.d.ts

@@ -0,0 +1,22 @@
+import type { ElementChain, Unchanged } from "../../plugin-kit/marker.types";
+export interface ArrayContainsBounds {
+    readonly min?: number;
+    readonly max?: number;
+}
+export interface ArrayContainsContext {
+    readonly matched: number;
+    readonly min: number;
+    readonly max: number;
+}
+/**
+ * WHICH argument positions carry a sub-chain cannot be recovered from a
+ * plugin's type at run time — a NarrowedChain and a RootPredicate are both
+ * plain functions once erased — so src/chain/collect-branch-rules.ts reads it
+ * from this declared field. definePlugin's spec does not carry it yet (see
+ * needsFromOthers), which is why it is spread on rather than passed in.
+ */
+export declare const arrayContainsPlugin: import("../../plugin-kit/plugin-definition").PluginDefinition<"arrayContains", "contains", readonly ["array", "tuple"], {
+    args: readonly [element: ElementChain, bounds?: ArrayContainsBounds];
+    out: Unchanged;
+    context: ArrayContainsContext;
+}>;