@maroonedog/luq 0.1.2-alpha → 2.0.0

package/dist/path/reserved-segment.js

@@ -0,0 +1,68 @@
+"use strict";
+// ===========================================================================
+// L1  src/path/reserved-segment.ts
+// The prototype-pollution gate for the ONE path grammar, plus the error every
+// path-shaped rejection throws.
+//
+// PathSyntaxError lives here, not in parse-field-path.ts, because this module
+// is the first thing that throws it and parse-field-path.ts imports this one.
+// Putting the class the other way round would make the two files mutually
+// dependent for no gain.
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PathSyntaxError = exports.RESERVED_SEGMENTS = void 0;
+exports.isReservedSegment = isReservedSegment;
+exports.assertDeclarableKey = assertDeclarableKey;
+/** Segment names that reach `Object.prototype` and must never be walked,
+ *  written, or vivified. `fromJsonSchema` derives segments verbatim from
+ *  untrusted schema property names, so this list is a security boundary, not a
+ *  style preference. */
+exports.RESERVED_SEGMENTS = Object.freeze([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/** Thrown at BUILD time for every malformed or unsafe path. A declared rule
+ *  must either execute or fail loudly; the legacy silent `return () => null`
+ *  turned a typo into a rule that never ran. */
+class PathSyntaxError extends Error {
+    constructor(path, reason) {
+        super(`Invalid field path ${JSON.stringify(path)}: ${reason}`);
+        this.name = "PathSyntaxError";
+        this.path = path;
+    }
+}
+exports.PathSyntaxError = PathSyntaxError;
+function isReservedSegment(key) {
+    return exports.RESERVED_SEGMENTS.includes(key);
+}
+/**
+ * The single definition of "this string may be used as one path segment".
+ *
+ * `source` is the whole path (or the origin, for a key that has not been
+ * joined into a path yet) and appears in the message so a regression names the
+ * offender.
+ *
+ * A key containing `.` is rejected rather than escaped: the grammar splits on
+ * `.` and has no escape syntax, so such a key would silently mean something
+ * else. Rejecting is the only honest option, and it is the reason this
+ * function is exported — the JSON Schema converter must call it on raw
+ * property names BEFORE joining them into a path, where the dot is still
+ * visible as its own key.
+ */
+function assertDeclarableKey(key, source) {
+    if (key === "") {
+        throw new PathSyntaxError(source, "a path segment must not be empty");
+    }
+    if (key.includes(".")) {
+        throw new PathSyntaxError(source, `the key ${JSON.stringify(key)} contains "." and cannot be expressed; ` +
+            'the grammar splits on "." and defines no escape');
+    }
+    if (key.includes("[") || key.includes("]")) {
+        throw new PathSyntaxError(source, `the key ${JSON.stringify(key)} contains a bracket; "[*]" is the only ` +
+            "bracket form and it must trail a key");
+    }
+    if (isReservedSegment(key)) {
+        throw new PathSyntaxError(source, `${JSON.stringify(key)} is a reserved segment (prototype pollution)`);
+    }
+}

package/dist/path/reserved-segment.mjs

@@ -0,0 +1,62 @@
+// ===========================================================================
+// L1  src/path/reserved-segment.ts
+// The prototype-pollution gate for the ONE path grammar, plus the error every
+// path-shaped rejection throws.
+//
+// PathSyntaxError lives here, not in parse-field-path.ts, because this module
+// is the first thing that throws it and parse-field-path.ts imports this one.
+// Putting the class the other way round would make the two files mutually
+// dependent for no gain.
+// ===========================================================================
+/** Segment names that reach `Object.prototype` and must never be walked,
+ *  written, or vivified. `fromJsonSchema` derives segments verbatim from
+ *  untrusted schema property names, so this list is a security boundary, not a
+ *  style preference. */
+export const RESERVED_SEGMENTS = Object.freeze([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/** Thrown at BUILD time for every malformed or unsafe path. A declared rule
+ *  must either execute or fail loudly; the legacy silent `return () => null`
+ *  turned a typo into a rule that never ran. */
+export class PathSyntaxError extends Error {
+    constructor(path, reason) {
+        super(`Invalid field path ${JSON.stringify(path)}: ${reason}`);
+        this.name = "PathSyntaxError";
+        this.path = path;
+    }
+}
+export function isReservedSegment(key) {
+    return RESERVED_SEGMENTS.includes(key);
+}
+/**
+ * The single definition of "this string may be used as one path segment".
+ *
+ * `source` is the whole path (or the origin, for a key that has not been
+ * joined into a path yet) and appears in the message so a regression names the
+ * offender.
+ *
+ * A key containing `.` is rejected rather than escaped: the grammar splits on
+ * `.` and has no escape syntax, so such a key would silently mean something
+ * else. Rejecting is the only honest option, and it is the reason this
+ * function is exported — the JSON Schema converter must call it on raw
+ * property names BEFORE joining them into a path, where the dot is still
+ * visible as its own key.
+ */
+export function assertDeclarableKey(key, source) {
+    if (key === "") {
+        throw new PathSyntaxError(source, "a path segment must not be empty");
+    }
+    if (key.includes(".")) {
+        throw new PathSyntaxError(source, `the key ${JSON.stringify(key)} contains "." and cannot be expressed; ` +
+            'the grammar splits on "." and defines no escape');
+    }
+    if (key.includes("[") || key.includes("]")) {
+        throw new PathSyntaxError(source, `the key ${JSON.stringify(key)} contains a bracket; "[*]" is the only ` +
+            "bracket form and it must trail a key");
+    }
+    if (isReservedSegment(key)) {
+        throw new PathSyntaxError(source, `${JSON.stringify(key)} is a reserved segment (prototype pollution)`);
+    }
+}

package/dist/path/value-at-path.types.d.ts

@@ -0,0 +1,25 @@
+import type { ParsePath, Segment } from "./path-segment.types";
+import type { IsOpaqueObject } from "./opaque-object.types";
+import type { ElementOf } from "./element-of.types";
+/** `unknown extends T` is tested BEFORE NonNullable, because
+ *  `NonNullable<unknown>` is `{}` since TS 4.9 and would otherwise collapse
+ *  every Record<string, unknown> subtree to never on the second segment. */
+type ReadKey<T, K extends string> = unknown extends T ? unknown : NonNullable<T> extends infer U ? U extends readonly unknown[] ? never : IsOpaqueObject<U> extends true ? never : U extends object ? K extends keyof U ? U[K] : never : never : never;
+type WalkSegments<T, S extends readonly Segment[]> = S extends readonly [
+    infer H,
+    ...infer R extends readonly Segment[]
+] ? H extends {
+    readonly each: true;
+} ? WalkSegments<ElementOf<T>, R> : H extends {
+    readonly key: infer K extends string;
+} ? WalkSegments<ReadKey<T, K>, R> : never : T;
+/** The declared type at P. Optionality survives on the LAST segment only, so
+ *  the chain can observe presence type-state while intermediate steps stay
+ *  total: ValueAtPath<T,"opt"> is `Address | undefined`, ValueAtPath<T,
+ *  "opt.street"> is `string`. */
+export type ValueAtPath<T, P extends string> = WalkSegments<T, ParsePath<P>>;
+/** Maps a tuple of path literals to an object of their resolved value types. */
+export type PickPaths<T, P extends readonly string[]> = {
+    readonly [K in P[number]]: ValueAtPath<T, K>;
+};
+export {};

package/dist/path/value-at-path.types.js

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

package/dist/path/value-at-path.types.mjs

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

package/dist/plugin-kit/compiled-rule.d.ts

@@ -0,0 +1,99 @@
+import type { ArrayItemContext, CheckOutcome, IssueDetail, IssueSeverity, MessageContext, RuleContext } from "../types";
+export type RuleKind = "check" | "presence" | "conditionalPresence" | "gate" | "transform" | "composite" | "recursive";
+export interface CheckRule {
+    readonly kind: "check";
+    readonly code: string;
+    readonly severity: IssueSeverity;
+    run(value: unknown, ctx: RuleContext): CheckOutcome;
+    describe(detail: IssueDetail, ctx: MessageContext): string;
+}
+/**
+ * WHICH absences a rule permits, without the identity that reports a refusal.
+ * Split out because a conditional presence rule owns TWO of these — one per
+ * side of its predicate — while both sides share its code and its message.
+ */
+export interface PresenceAllowance {
+    readonly allowUndefined: boolean;
+    readonly allowNull: boolean;
+    readonly emptyStringIsMissing: boolean;
+}
+export interface PresenceRule extends PresenceAllowance {
+    readonly kind: "presence";
+    readonly code: string;
+    readonly severity: IssueSeverity;
+    describe(ctx: MessageContext): string;
+}
+/**
+ * Presence only a value of the ROOT can settle: `.requiredIf(when)` and
+ * `.optionalIf(when)`.
+ *
+ * Plain PresenceRules merge into ONE policy at build time, which is why
+ * nothing before this could make a MISSING value depend on a sibling field.
+ * requiredIf had to be a check instead, and a check never sees undefined
+ * because the presence gate returns first — so `.requiredIf(cond)` alone was
+ * silent on the very absence it exists to forbid.
+ *
+ * The condition is therefore carried HERE, and compilation turns each side
+ * into a finished PresencePolicy. The run time evaluates one predicate and
+ * PICKS; it never assembles a policy and never asks what a rule is.
+ *
+ * `whenMet` / `whenUnmet` is null on the side that has no opinion, and the
+ * field then keeps the policy its unconditional rules already merged to. That
+ * is what leaves `.required().requiredIf(cond)` rejecting a missing value
+ * while the condition is false.
+ */
+export interface ConditionalPresenceRule {
+    readonly kind: "conditionalPresence";
+    readonly code: string;
+    readonly severity: IssueSeverity;
+    /** Evaluated once per field run, BEFORE the value is judged. */
+    when(root: unknown, arrayContext?: ArrayItemContext): boolean;
+    readonly whenMet: PresenceAllowance | null;
+    readonly whenUnmet: PresenceAllowance | null;
+    describe(ctx: MessageContext): string;
+}
+export interface GateRule {
+    readonly kind: "gate";
+    readonly code: string;
+    shouldRun(value: unknown, ctx: RuleContext): boolean;
+}
+export interface TransformRule {
+    readonly kind: "transform";
+    apply(value: unknown, ctx: RuleContext): unknown;
+}
+/** Rules bound to a path RELATIVE to the branch subject. */
+export interface BranchField {
+    readonly path: string;
+    readonly rules: readonly Rule[];
+}
+export interface CompositeBranch {
+    readonly label: string;
+    readonly rules: readonly Rule[];
+    readonly fields: readonly BranchField[];
+}
+/** A branch after compilation: the same call shape as a check. */
+export interface BranchRunner {
+    readonly label: string;
+    run(value: unknown, ctx: RuleContext): CheckOutcome;
+}
+export type CompositeExecute = (value: unknown, ctx: RuleContext) => CheckOutcome;
+export type CompositeCombine = (runners: readonly BranchRunner[]) => CompositeExecute;
+export interface CompositeRule {
+    readonly kind: "composite";
+    readonly code: string;
+    readonly severity: IssueSeverity;
+    readonly branches: readonly CompositeBranch[];
+    /** Called ONCE at build time; runners[i] corresponds to branches[i]. */
+    readonly combine: CompositeCombine;
+    describe(detail: IssueDetail, ctx: MessageContext): string;
+}
+export type RecursionTarget = "self" | "element";
+export interface RecursiveRule {
+    readonly kind: "recursive";
+    readonly code: string;
+    readonly severity: IssueSeverity;
+    readonly target: RecursionTarget;
+    readonly maxDepth: number;
+    describe(detail: IssueDetail, ctx: MessageContext): string;
+}
+export type Rule = CheckRule | PresenceRule | ConditionalPresenceRule | GateRule | TransformRule | CompositeRule | RecursiveRule;

package/dist/plugin-kit/compiled-rule.js

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

package/dist/plugin-kit/compiled-rule.mjs

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

package/dist/plugin-kit/create-conditional-presence.d.ts

@@ -0,0 +1,25 @@
+import type { IssueSeverity, MessageContext, MessageContextExtra, MessageFactory } from "../types";
+import type { ConditionalPresenceRule, PresenceAllowance } from "./compiled-rule";
+import type { RootPredicateFn } from "./runtime-args.types";
+/** Rejects undefined, null and "" — legacy's emptiness, verbatim. */
+export declare const REQUIRES_A_VALUE: PresenceAllowance;
+/**
+ * Permits undefined and null. "" stays PRESENT here, so a conditionally
+ * optional field still runs its own checks against an empty string, exactly
+ * as `.optional().min(3)` does.
+ */
+export declare const PERMITS_ABSENCE: PresenceAllowance;
+export interface ConditionalPresenceSpec<C extends MessageContextExtra> {
+    readonly code: string;
+    readonly messageFactory?: MessageFactory<C>;
+    readonly severity: IssueSeverity;
+    /** The user's predicate. Stored by identity, never re-wrapped. */
+    readonly when: RootPredicateFn;
+    /** In force while the predicate holds; null defers to the merged policy. */
+    readonly whenMet: PresenceAllowance | null;
+    /** In force while it does not; null defers to the merged policy. */
+    readonly whenUnmet: PresenceAllowance | null;
+    describe(ctx: MessageContext): string;
+    buildMessageContext(): C;
+}
+export declare function conditionalPresence<C extends MessageContextExtra>(spec: ConditionalPresenceSpec<C>): ConditionalPresenceRule;

package/dist/plugin-kit/create-conditional-presence.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMITS_ABSENCE = exports.REQUIRES_A_VALUE = void 0;
+exports.conditionalPresence = conditionalPresence;
+const rule_build_context_1 = require("./rule-build-context");
+/** Rejects undefined, null and "" — legacy's emptiness, verbatim. */
+exports.REQUIRES_A_VALUE = Object.freeze({
+    allowUndefined: false,
+    allowNull: false,
+    emptyStringIsMissing: true,
+});
+/**
+ * Permits undefined and null. "" stays PRESENT here, so a conditionally
+ * optional field still runs its own checks against an empty string, exactly
+ * as `.optional().min(3)` does.
+ */
+exports.PERMITS_ABSENCE = Object.freeze({
+    allowUndefined: true,
+    allowNull: true,
+    emptyStringIsMissing: false,
+});
+function conditionalPresence(spec) {
+    return {
+        kind: "conditionalPresence",
+        code: spec.code,
+        severity: spec.severity,
+        when: spec.when,
+        whenMet: spec.whenMet,
+        whenUnmet: spec.whenUnmet,
+        describe: (ctx) => (0, rule_build_context_1.renderMessage)(spec.messageFactory, ctx, spec.buildMessageContext(), spec.describe(ctx)),
+    };
+}

package/dist/plugin-kit/create-conditional-presence.mjs

@@ -0,0 +1,28 @@
+import { renderMessage } from "./rule-build-context.mjs";
+/** Rejects undefined, null and "" — legacy's emptiness, verbatim. */
+export const REQUIRES_A_VALUE = Object.freeze({
+    allowUndefined: false,
+    allowNull: false,
+    emptyStringIsMissing: true,
+});
+/**
+ * Permits undefined and null. "" stays PRESENT here, so a conditionally
+ * optional field still runs its own checks against an empty string, exactly
+ * as `.optional().min(3)` does.
+ */
+export const PERMITS_ABSENCE = Object.freeze({
+    allowUndefined: true,
+    allowNull: true,
+    emptyStringIsMissing: false,
+});
+export function conditionalPresence(spec) {
+    return {
+        kind: "conditionalPresence",
+        code: spec.code,
+        severity: spec.severity,
+        when: spec.when,
+        whenMet: spec.whenMet,
+        whenUnmet: spec.whenUnmet,
+        describe: (ctx) => renderMessage(spec.messageFactory, ctx, spec.buildMessageContext(), spec.describe(ctx)),
+    };
+}

package/dist/plugin-kit/create-rule.d.ts

@@ -0,0 +1,48 @@
+import type { CheckOutcome, IssueDetail, IssueSeverity, MessageContext, MessageContextExtra, MessageFactory, RuleContext } from "../types";
+import type { BranchField, CheckRule, CompositeBranch, CompositeCombine, CompositeRule, GateRule, PresenceRule, RecursionTarget, RecursiveRule, Rule, TransformRule } from "./compiled-rule";
+export interface CheckSpec<C extends MessageContextExtra> {
+    readonly code: string;
+    readonly messageFactory?: MessageFactory<C>;
+    readonly severity: IssueSeverity;
+    run(value: unknown, ctx: RuleContext): CheckOutcome;
+    describe(detail: IssueDetail, ctx: MessageContext): string;
+    buildMessageContext(detail: IssueDetail): C;
+}
+export declare function check<C extends MessageContextExtra>(spec: CheckSpec<C>): CheckRule;
+export interface PresenceSpec<C extends MessageContextExtra> {
+    readonly code: string;
+    readonly messageFactory?: MessageFactory<C>;
+    readonly severity: IssueSeverity;
+    readonly allowUndefined: boolean;
+    readonly allowNull: boolean;
+    readonly emptyStringIsMissing: boolean;
+    describe(ctx: MessageContext): string;
+    buildMessageContext(): C;
+}
+export declare function presence<C extends MessageContextExtra>(spec: PresenceSpec<C>): PresenceRule;
+export declare function gate(code: string, shouldRun: (value: unknown, ctx: RuleContext) => boolean): GateRule;
+export declare function transform(apply: (value: unknown, ctx: RuleContext) => unknown): TransformRule;
+/** Declares a branch of a composite. */
+export declare function branch(label: string, rules: readonly Rule[], fields?: readonly BranchField[]): CompositeBranch;
+/** Declares a branch that only constrains sub-paths. */
+export declare function fieldsBranch(label: string, fields: readonly BranchField[]): CompositeBranch;
+export interface CompositeSpec<C extends MessageContextExtra> {
+    readonly code: string;
+    readonly messageFactory?: MessageFactory<C>;
+    readonly severity: IssueSeverity;
+    readonly branches: readonly CompositeBranch[];
+    readonly combine: CompositeCombine;
+    describe(detail: IssueDetail, ctx: MessageContext): string;
+    buildMessageContext(detail: IssueDetail): C;
+}
+export declare function composite<C extends MessageContextExtra>(spec: CompositeSpec<C>): CompositeRule;
+export interface RecursiveSpec<C extends MessageContextExtra> {
+    readonly code: string;
+    readonly messageFactory?: MessageFactory<C>;
+    readonly severity: IssueSeverity;
+    readonly target: RecursionTarget;
+    readonly maxDepth: number;
+    describe(detail: IssueDetail, ctx: MessageContext): string;
+    buildMessageContext(detail: IssueDetail): C;
+}
+export declare function recursive<C extends MessageContextExtra>(spec: RecursiveSpec<C>): RecursiveRule;

package/dist/plugin-kit/create-rule.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.check = check;
+exports.presence = presence;
+exports.gate = gate;
+exports.transform = transform;
+exports.branch = branch;
+exports.fieldsBranch = fieldsBranch;
+exports.composite = composite;
+exports.recursive = recursive;
+const rule_build_context_1 = require("./rule-build-context");
+const EMPTY_FIELDS = Object.freeze([]);
+const EMPTY_RULES = Object.freeze([]);
+function check(spec) {
+    return {
+        kind: "check",
+        code: spec.code,
+        severity: spec.severity,
+        run: (value, ctx) => spec.run(value, ctx),
+        describe: (detail, ctx) => (0, rule_build_context_1.renderMessage)(spec.messageFactory, ctx, spec.buildMessageContext(detail), spec.describe(detail, ctx)),
+    };
+}
+function presence(spec) {
+    return {
+        kind: "presence",
+        code: spec.code,
+        severity: spec.severity,
+        allowUndefined: spec.allowUndefined,
+        allowNull: spec.allowNull,
+        emptyStringIsMissing: spec.emptyStringIsMissing,
+        describe: (ctx) => (0, rule_build_context_1.renderMessage)(spec.messageFactory, ctx, spec.buildMessageContext(), spec.describe(ctx)),
+    };
+}
+function gate(code, shouldRun) {
+    return { kind: "gate", code, shouldRun };
+}
+function transform(apply) {
+    return { kind: "transform", apply };
+}
+/** Declares a branch of a composite. */
+function branch(label, rules, fields = EMPTY_FIELDS) {
+    return { label, rules, fields };
+}
+/** Declares a branch that only constrains sub-paths. */
+function fieldsBranch(label, fields) {
+    return { label, rules: EMPTY_RULES, fields };
+}
+function composite(spec) {
+    return {
+        kind: "composite",
+        code: spec.code,
+        severity: spec.severity,
+        branches: spec.branches,
+        combine: spec.combine,
+        describe: (detail, ctx) => (0, rule_build_context_1.renderMessage)(spec.messageFactory, ctx, spec.buildMessageContext(detail), spec.describe(detail, ctx)),
+    };
+}
+function recursive(spec) {
+    return {
+        kind: "recursive",
+        code: spec.code,
+        severity: spec.severity,
+        target: spec.target,
+        maxDepth: spec.maxDepth,
+        describe: (detail, ctx) => (0, rule_build_context_1.renderMessage)(spec.messageFactory, ctx, spec.buildMessageContext(detail), spec.describe(detail, ctx)),
+    };
+}

package/dist/plugin-kit/create-rule.mjs

@@ -0,0 +1,57 @@
+import { renderMessage } from "./rule-build-context.mjs";
+const EMPTY_FIELDS = Object.freeze([]);
+const EMPTY_RULES = Object.freeze([]);
+export function check(spec) {
+    return {
+        kind: "check",
+        code: spec.code,
+        severity: spec.severity,
+        run: (value, ctx) => spec.run(value, ctx),
+        describe: (detail, ctx) => renderMessage(spec.messageFactory, ctx, spec.buildMessageContext(detail), spec.describe(detail, ctx)),
+    };
+}
+export function presence(spec) {
+    return {
+        kind: "presence",
+        code: spec.code,
+        severity: spec.severity,
+        allowUndefined: spec.allowUndefined,
+        allowNull: spec.allowNull,
+        emptyStringIsMissing: spec.emptyStringIsMissing,
+        describe: (ctx) => renderMessage(spec.messageFactory, ctx, spec.buildMessageContext(), spec.describe(ctx)),
+    };
+}
+export function gate(code, shouldRun) {
+    return { kind: "gate", code, shouldRun };
+}
+export function transform(apply) {
+    return { kind: "transform", apply };
+}
+/** Declares a branch of a composite. */
+export function branch(label, rules, fields = EMPTY_FIELDS) {
+    return { label, rules, fields };
+}
+/** Declares a branch that only constrains sub-paths. */
+export function fieldsBranch(label, fields) {
+    return { label, rules: EMPTY_RULES, fields };
+}
+export function composite(spec) {
+    return {
+        kind: "composite",
+        code: spec.code,
+        severity: spec.severity,
+        branches: spec.branches,
+        combine: spec.combine,
+        describe: (detail, ctx) => renderMessage(spec.messageFactory, ctx, spec.buildMessageContext(detail), spec.describe(detail, ctx)),
+    };
+}
+export function recursive(spec) {
+    return {
+        kind: "recursive",
+        code: spec.code,
+        severity: spec.severity,
+        target: spec.target,
+        maxDepth: spec.maxDepth,
+        describe: (detail, ctx) => renderMessage(spec.messageFactory, ctx, spec.buildMessageContext(detail), spec.describe(detail, ctx)),
+    };
+}

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);