@maroonedog/luq 0.1.2-alpha → 2.1.0

package/dist/json-schema/declare-value-keywords.mjs

@@ -0,0 +1,112 @@
+// ===========================================================================
+// L8  src/json-schema/declare-value-keywords.ts — the keywords
+// that judge the VALUE ITSELF: `type`, `enum` and `const`.
+//
+// The keyword table calls `type` structural because it "chooses the slot".
+// Choosing a slot is a TYPE-LEVEL act and asserts nothing at run time, so a
+// converter that only chose a slot would accept `42` for `{"type":"string"}` —
+// which is precisely what 1.x did (docs/legacy-spec/json-schema-mapping.md).
+// The slot choice is still made, in declare-scalar-keywords; the RULE is made
+// here, from create-rule, because no plugin in JsonSchemaBag asserts a
+// primitive type (`object` is the only type plugin in the catalogue and it is
+// not in the bag).
+//
+// `null` never reaches a check — src/runtime/decide-presence.ts settles absence
+// first — so `type: "null"` reads as "every value that got this far is wrong",
+// which is exactly right: the only null-shaped value was already accepted by
+// the nullable presence rule this module's neighbour declares.
+// ===========================================================================
+import { readChainRules } from "../chain/create-chain-node.mjs";
+import { createFieldSlots } from "../chain/create-field-slots.mjs";
+import { check } from "../plugin-kit/create-rule.mjs";
+import { PASS, fail, isArray, isPlainObject, isString } from "../types/index.mjs";
+import { applyKeywordBinding } from "./apply-keyword-binding.mjs";
+import { constBinding } from "./keyword-map-core.mjs";
+const NO_RULES = Object.freeze([]);
+/** Every Draft-07 `type` name, so an unknown one is a build-time refusal. */
+const JSON_TYPE_TESTS = {
+    string: isString,
+    number: (value) => typeof value === "number",
+    integer: (value) => typeof value === "number" && Number.isInteger(value),
+    boolean: (value) => typeof value === "boolean",
+    array: isArray,
+    object: isPlainObject,
+    null: (value) => value === null,
+};
+function isTypeKeyword(name) {
+    return Object.prototype.hasOwnProperty.call(JSON_TYPE_TESTS, name);
+}
+/** The declared names, always as a list, with unknown names rejected loudly. */
+export function readDeclaredTypes(schema) {
+    const declared = schema.type;
+    if (declared === undefined)
+        return Object.freeze([]);
+    const names = isArray(declared) ? declared : [declared];
+    return Object.freeze(names.filter((name) => isTypeKeyword(name)));
+}
+/** True when the document permits an explicit null at this position. */
+export function permitsNull(schema) {
+    const declared = readDeclaredTypes(schema);
+    return declared.length === 0 || declared.includes("null");
+}
+function describeActual(value) {
+    if (value === null)
+        return "null";
+    if (isArray(value))
+        return "array";
+    return typeof value;
+}
+/**
+ * One check for the whole list: `type: ["string","number"]` is a union, and
+ * running one rule per member would report a failure per member for a value
+ * that fails all of them.
+ */
+export function declareTypeRules(schema, context) {
+    const declared = readDeclaredTypes(schema);
+    if (declared.length === 0)
+        return NO_RULES;
+    const tests = declared.map((name) => JSON_TYPE_TESTS[name]);
+    const rendered = declared.join(" or ");
+    return Object.freeze([
+        check({
+            code: "type",
+            severity: context.build.config.defaultSeverity,
+            run: (value) => tests.some((test) => test(value))
+                ? PASS
+                : fail({ expected: rendered, actual: describeActual(value) }),
+            describe: (detail) => `Value must be of type ${rendered}, but got ${String(detail.actual)}`,
+            buildMessageContext: () => ({}),
+        }),
+    ]);
+}
+/** `type: "integer"` is the only `type` member that adds a chain method. */
+export function declareIntegerRules(schema, context) {
+    if (!readDeclaredTypes(schema).includes("integer"))
+        return NO_RULES;
+    const plugin = context.bag.numberInteger;
+    return Object.freeze([
+        plugin.build(context.ruleContextFor(plugin.name, "type")),
+    ]);
+}
+export function declareConstRules(schema, context) {
+    if (!Object.prototype.hasOwnProperty.call(schema, "const"))
+        return NO_RULES;
+    const chain = createFieldSlots(context.bag, context.build).any;
+    const applied = applyKeywordBinding(chain, constBinding, schema.const);
+    return readChainRules(applied) ?? NO_RULES;
+}
+/**
+ * `enum` drives the `.oneOf()` METHOD, which is a different thing from the
+ * `oneOf` KEYWORD. The list is typed against the FIELD (readonly SelfValue[]),
+ * so it carries a marker and can never be a keyword binding; the converter
+ * resolves the list and calls the plugin itself, exactly as the table says.
+ */
+export function declareEnumRules(schema, context) {
+    const allowed = schema.enum;
+    if (allowed === undefined || allowed.length === 0)
+        return NO_RULES;
+    const plugin = context.bag.oneOf;
+    return Object.freeze([
+        plugin.build(context.ruleContextFor(plugin.name, "enum"), allowed),
+    ]);
+}

package/dist/json-schema/draft07-keyword-value.types.d.ts

@@ -0,0 +1,61 @@
+import type { ContentEncodingName } from "../plugins/string-content-encoding";
+import type { Draft07Schema, Draft07TypeKeyword } from "./draft07.types";
+export type Draft07CoreKeyword = "$schema" | "$id" | "$ref" | "$comment" | "definitions" | "title" | "description" | "default" | "examples" | "readOnly" | "writeOnly" | "type" | "enum" | "const" | "allOf" | "anyOf" | "oneOf" | "not" | "if" | "then" | "else";
+export type Draft07NumberKeyword = "multipleOf" | "maximum" | "exclusiveMaximum" | "minimum" | "exclusiveMinimum";
+export type Draft07StringKeyword = "maxLength" | "minLength" | "pattern" | "format" | "contentEncoding" | "contentMediaType";
+export type Draft07ArrayKeyword = "items" | "additionalItems" | "maxItems" | "minItems" | "uniqueItems" | "contains";
+export type Draft07ObjectKeyword = "maxProperties" | "minProperties" | "required" | "properties" | "patternProperties" | "additionalProperties" | "dependencies" | "propertyNames";
+/** All 46 Draft-07 keywords. Written by hand; checked against the record. */
+export type Draft07Keyword = Draft07CoreKeyword | Draft07NumberKeyword | Draft07StringKeyword | Draft07ArrayKeyword | Draft07ObjectKeyword;
+export interface Draft07KeywordValues {
+    readonly $schema: string;
+    readonly $id: string;
+    readonly $ref: string;
+    readonly $comment: string;
+    readonly definitions: Readonly<Record<string, Draft07Schema>>;
+    readonly title: string;
+    readonly description: string;
+    readonly default: unknown;
+    readonly examples: readonly unknown[];
+    readonly readOnly: boolean;
+    readonly writeOnly: boolean;
+    readonly type: Draft07TypeKeyword | readonly Draft07TypeKeyword[];
+    readonly enum: readonly unknown[];
+    readonly const: unknown;
+    readonly allOf: readonly Draft07Schema[];
+    readonly anyOf: readonly Draft07Schema[];
+    readonly oneOf: readonly Draft07Schema[];
+    readonly not: Draft07Schema;
+    readonly if: Draft07Schema;
+    readonly then: Draft07Schema;
+    readonly else: Draft07Schema;
+    readonly multipleOf: number;
+    readonly maximum: number;
+    readonly exclusiveMaximum: number;
+    readonly minimum: number;
+    readonly exclusiveMinimum: number;
+    readonly maxLength: number;
+    readonly minLength: number;
+    readonly pattern: string;
+    readonly format: string;
+    /** Normalised: an unknown encoding name never reaches the binding. */
+    readonly contentEncoding: ContentEncodingName;
+    readonly contentMediaType: string;
+    readonly items: Draft07Schema | readonly Draft07Schema[];
+    readonly additionalItems: Draft07Schema;
+    readonly maxItems: number;
+    readonly minItems: number;
+    /** Normalised: `uniqueItems: false` is a no-op and is dropped first. */
+    readonly uniqueItems: true;
+    readonly contains: Draft07Schema;
+    readonly maxProperties: number;
+    readonly minProperties: number;
+    /** Normalised: the parent's array, resolved to one flag per child. */
+    readonly required: true;
+    readonly properties: Readonly<Record<string, Draft07Schema>>;
+    readonly patternProperties: Readonly<Record<string, Draft07Schema>>;
+    /** Normalised: only the boolean form binds; the schema form is structural. */
+    readonly additionalProperties: boolean;
+    readonly dependencies: Readonly<Record<string, Draft07Schema | readonly string[]>>;
+    readonly propertyNames: Draft07Schema;
+}

package/dist/json-schema/draft07-keyword-value.types.js

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

package/dist/json-schema/draft07-keyword-value.types.mjs

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

package/dist/json-schema/draft07.types.d.ts

@@ -0,0 +1,57 @@
+/** The seven values Draft-07 allows in `type`. `integer` is NOT a Luq slot. */
+export type Draft07TypeKeyword = "string" | "number" | "integer" | "boolean" | "array" | "object" | "null";
+export type Draft07Schema = boolean | Draft07SchemaObject;
+export interface Draft07SchemaObject {
+    readonly $id?: string;
+    readonly $schema?: string;
+    readonly $ref?: string;
+    readonly $comment?: string;
+    readonly definitions?: Readonly<Record<string, Draft07Schema>>;
+    /** 2019-09 spelling. Not a Draft-07 keyword; only the RESOLVER accepts it. */
+    readonly $defs?: Readonly<Record<string, Draft07Schema>>;
+    readonly title?: string;
+    readonly description?: string;
+    readonly default?: unknown;
+    readonly readOnly?: boolean;
+    readonly writeOnly?: boolean;
+    readonly examples?: readonly unknown[];
+    readonly type?: Draft07TypeKeyword | readonly Draft07TypeKeyword[];
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly format?: string;
+    readonly multipleOf?: number;
+    readonly maximum?: number;
+    readonly exclusiveMaximum?: number;
+    readonly minimum?: number;
+    readonly exclusiveMinimum?: number;
+    readonly maxLength?: number;
+    readonly minLength?: number;
+    readonly pattern?: string;
+    readonly contentMediaType?: string;
+    readonly contentEncoding?: string;
+    readonly items?: Draft07Schema | readonly Draft07Schema[];
+    readonly additionalItems?: Draft07Schema;
+    readonly maxItems?: number;
+    readonly minItems?: number;
+    readonly uniqueItems?: boolean;
+    readonly contains?: Draft07Schema;
+    readonly maxProperties?: number;
+    readonly minProperties?: number;
+    readonly required?: readonly string[];
+    readonly properties?: Readonly<Record<string, Draft07Schema>>;
+    readonly patternProperties?: Readonly<Record<string, Draft07Schema>>;
+    readonly additionalProperties?: Draft07Schema;
+    readonly dependencies?: Readonly<Record<string, Draft07Schema | readonly string[]>>;
+    readonly propertyNames?: Draft07Schema;
+    readonly allOf?: readonly Draft07Schema[];
+    readonly anyOf?: readonly Draft07Schema[];
+    readonly oneOf?: readonly Draft07Schema[];
+    readonly not?: Draft07Schema;
+    readonly if?: Draft07Schema;
+    readonly then?: Draft07Schema;
+    readonly else?: Draft07Schema;
+}
+/** Narrows away the boolean form of §4.4 without an assertion. */
+export declare function isSchemaObject(schema: Draft07Schema): schema is Draft07SchemaObject;
+/** The one entry gate for untyped JSON. `null` is NOT a schema. */
+export declare function isDraft07Schema(value: unknown): value is Draft07Schema;

package/dist/json-schema/draft07.types.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSchemaObject = isSchemaObject;
+exports.isDraft07Schema = isDraft07Schema;
+// ===========================================================================
+// L8  src/json-schema/draft07.types.ts — the DOCUMENT shape.
+//
+// This is what a Draft-07 JSON document is allowed to say, keyword for
+// keyword, straight from the draft-07 meta-schema's `properties` (46 keys).
+// It is deliberately NOT the same thing as `Draft07KeywordValues`: this type
+// is as wide as the specification, while the value types next door are as
+// narrow as the handling can accept, so the converter is FORCED by the
+// compiler to normalise (`uniqueItems: boolean` -> `true`, a `required` array
+// -> a per-field flag) instead of quietly passing the wide form through.
+//
+// A schema may also be a bare boolean — Draft-07 §4.4 — and 1.x's converter
+// could not represent that at all (it tested `typeof x === "object"` and
+// dropped the rest), so it is in the union here from the start.
+// ===========================================================================
+const types_1 = require("../types");
+/** Narrows away the boolean form of §4.4 without an assertion. */
+function isSchemaObject(schema) {
+    return typeof schema !== "boolean";
+}
+/** The one entry gate for untyped JSON. `null` is NOT a schema. */
+function isDraft07Schema(value) {
+    return typeof value === "boolean" || (0, types_1.isPlainObject)(value);
+}

package/dist/json-schema/draft07.types.mjs

@@ -0,0 +1,24 @@
+// ===========================================================================
+// L8  src/json-schema/draft07.types.ts — the DOCUMENT shape.
+//
+// This is what a Draft-07 JSON document is allowed to say, keyword for
+// keyword, straight from the draft-07 meta-schema's `properties` (46 keys).
+// It is deliberately NOT the same thing as `Draft07KeywordValues`: this type
+// is as wide as the specification, while the value types next door are as
+// narrow as the handling can accept, so the converter is FORCED by the
+// compiler to normalise (`uniqueItems: boolean` -> `true`, a `required` array
+// -> a per-field flag) instead of quietly passing the wide form through.
+//
+// A schema may also be a bare boolean — Draft-07 §4.4 — and 1.x's converter
+// could not represent that at all (it tested `typeof x === "object"` and
+// dropped the rest), so it is in the union here from the start.
+// ===========================================================================
+import { isPlainObject } from "../types/index.mjs";
+/** Narrows away the boolean form of §4.4 without an assertion. */
+export function isSchemaObject(schema) {
+    return typeof schema !== "boolean";
+}
+/** The one entry gate for untyped JSON. `null` is NOT a schema. */
+export function isDraft07Schema(value) {
+    return typeof value === "boolean" || isPlainObject(value);
+}

package/dist/json-schema/extensions/json-schema/index.d.ts

@@ -0,0 +1,4 @@
+export { SCHEMA_BRANCH_LABEL, collectDocumentRules, jsonSchemaPlugin, } from "./json-schema";
+export type { JsonSchemaOptions } from "./json-schema";
+export { NotASchemaError, UnsupportedKeywordError, RefResolutionError, buildFieldEntries, buildFromSchema, fromJsonSchema, isDraft07Schema, listBoundPluginNames, listDraft07Keywords, listFormatNames, } from "../../index";
+export type { Draft07Schema, Draft07SchemaObject, JsonSchemaBag, } from "../../index";

package/dist/json-schema/extensions/json-schema/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listFormatNames = exports.listDraft07Keywords = exports.listBoundPluginNames = exports.isDraft07Schema = exports.fromJsonSchema = exports.buildFromSchema = exports.buildFieldEntries = exports.RefResolutionError = exports.UnsupportedKeywordError = exports.NotASchemaError = exports.jsonSchemaPlugin = exports.collectDocumentRules = exports.SCHEMA_BRANCH_LABEL = void 0;
+// ===========================================================================
+// The public subpath `@maroonedog/luq/plugins/jsonSchema`. Re-exports only.
+//
+// 1.x published this subpath as "the jsonSchema barrel": the plugin plus the
+// module's named helpers. The same shape is kept — the plugin, the conversion
+// front door, and the errors a caller has to be able to catch by identity —
+// with ONE deliberate omission: no plugin entry file is imported from here, so
+// a consumer of this subpath pays only for the plugins they import themselves.
+// ===========================================================================
+var json_schema_1 = require("./json-schema");
+Object.defineProperty(exports, "SCHEMA_BRANCH_LABEL", { enumerable: true, get: function () { return json_schema_1.SCHEMA_BRANCH_LABEL; } });
+Object.defineProperty(exports, "collectDocumentRules", { enumerable: true, get: function () { return json_schema_1.collectDocumentRules; } });
+Object.defineProperty(exports, "jsonSchemaPlugin", { enumerable: true, get: function () { return json_schema_1.jsonSchemaPlugin; } });
+var index_1 = require("../../index");
+Object.defineProperty(exports, "NotASchemaError", { enumerable: true, get: function () { return index_1.NotASchemaError; } });
+Object.defineProperty(exports, "UnsupportedKeywordError", { enumerable: true, get: function () { return index_1.UnsupportedKeywordError; } });
+Object.defineProperty(exports, "RefResolutionError", { enumerable: true, get: function () { return index_1.RefResolutionError; } });
+Object.defineProperty(exports, "buildFieldEntries", { enumerable: true, get: function () { return index_1.buildFieldEntries; } });
+Object.defineProperty(exports, "buildFromSchema", { enumerable: true, get: function () { return index_1.buildFromSchema; } });
+Object.defineProperty(exports, "fromJsonSchema", { enumerable: true, get: function () { return index_1.fromJsonSchema; } });
+Object.defineProperty(exports, "isDraft07Schema", { enumerable: true, get: function () { return index_1.isDraft07Schema; } });
+Object.defineProperty(exports, "listBoundPluginNames", { enumerable: true, get: function () { return index_1.listBoundPluginNames; } });
+Object.defineProperty(exports, "listDraft07Keywords", { enumerable: true, get: function () { return index_1.listDraft07Keywords; } });
+Object.defineProperty(exports, "listFormatNames", { enumerable: true, get: function () { return index_1.listFormatNames; } });

package/dist/json-schema/extensions/json-schema/index.mjs

@@ -0,0 +1,11 @@
+// ===========================================================================
+// The public subpath `@maroonedog/luq/plugins/jsonSchema`. Re-exports only.
+//
+// 1.x published this subpath as "the jsonSchema barrel": the plugin plus the
+// module's named helpers. The same shape is kept — the plugin, the conversion
+// front door, and the errors a caller has to be able to catch by identity —
+// with ONE deliberate omission: no plugin entry file is imported from here, so
+// a consumer of this subpath pays only for the plugins they import themselves.
+// ===========================================================================
+export { SCHEMA_BRANCH_LABEL, collectDocumentRules, jsonSchemaPlugin, } from "./json-schema.mjs";
+export { NotASchemaError, UnsupportedKeywordError, RefResolutionError, buildFieldEntries, buildFromSchema, fromJsonSchema, isDraft07Schema, listBoundPluginNames, listDraft07Keywords, listFormatNames, } from "../../index.mjs";

package/dist/json-schema/extensions/json-schema/json-schema.d.ts

@@ -0,0 +1,33 @@
+import type { Rule } from "../../../plugin-kit/compiled-rule";
+import { type MessageContextExtra, type TypeName } from "../../../types";
+import type { RuleBuildContext } from "../../../plugin-kit/rule-build-context";
+import type { Unchanged } from "../../../plugin-kit/marker.types";
+import { type JsonSchemaBag } from "../../index";
+/** The label the whole document carries inside the composite it becomes. */
+export declare const SCHEMA_BRANCH_LABEL = "schema";
+/**
+ * What the converter may reach beyond the document itself.
+ *
+ * `externalDocuments` is a MAP, deliberately, and not a loader function:
+ *   * Luq never opens a socket, so a schema cannot make the process fetch a
+ *     URL it names (SSRF) — what can be read is written in the caller's code;
+ *   * conversion stays synchronous, so `build()` keeps returning a validator
+ *     rather than a promise;
+ *   * nothing is evaluated, so the CSP guarantee is untouched.
+ * The caller fetches, reads from disk, or bundles — whichever is right for
+ * their deployment — and hands over what they already have.
+ */
+export interface JsonSchemaOptions {
+    readonly externalDocuments?: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+ * The document as a rule list over ONE subject. Exported because it is the
+ * only part of this plugin the full-feature bundle needs, and because a test
+ * can then count the rules a document produces without building a validator.
+ */
+export declare function collectDocumentRules(ctx: RuleBuildContext<MessageContextExtra>, document: unknown, bag: JsonSchemaBag, options?: JsonSchemaOptions): readonly Rule[];
+export declare const jsonSchemaPlugin: import("../../../plugin-kit/plugin-definition").PluginDefinition<"jsonSchema", "jsonSchema", readonly TypeName[], {
+    args: readonly [document: unknown, bag: JsonSchemaBag, options?: JsonSchemaOptions];
+    out: Unchanged;
+    context: MessageContextExtra;
+}>;

package/dist/json-schema/extensions/json-schema/json-schema.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonSchemaPlugin = exports.SCHEMA_BRANCH_LABEL = void 0;
+exports.collectDocumentRules = collectDocumentRules;
+// ===========================================================================
+// L8 (tier `extension`)  src/json-schema/extensions/json-schema/json-schema.ts
+// `./plugins/jsonSchema` — the TREE-SHAKEABLE half of the two-tier story.
+//
+// WHAT CHANGED FROM 1.x, AND WHY (this is a deviation; it is argued, not hidden):
+// 1.x shipped `jsonSchemaPlugin` as a BuilderExtensionPlugin that grew a
+// `.fromJsonSchema()` method onto `Builder` itself. The rewritten core has no
+// builder-extension mechanism at all — `Builder` was frozen at the contract
+// gate (step 7) with exactly `use` / `withConfig` / `for` — so the method
+// cannot be grown back without breaking that freeze. The conversion front door
+// is therefore the FUNCTION `fromJsonSchema(bag, schema)` (step 25), re-exported
+// from this directory's index, and this file adds the thing a function cannot
+// express: a CHAIN METHOD, so a document can constrain one declared field.
+//
+// `.jsonSchema(document, bag)` takes the bag EXPLICITLY. That is the whole
+// point of this subpath: importing the forty-five plugin entry files here would
+// make every one of them statically reachable and end per-plugin tree-shaking,
+// which is exactly the size difference 1.x published between this subpath and
+// ./plugins/jsonSchemaFullFeature. The caller assembles the bag from the
+// plugins they already import; the full-feature bundle ships a complete one.
+//
+// THE ROOT IS DECLARABLE HERE. flatten-schema refuses a rule-bearing keyword on
+// the document ROOT because Luq declares rules per FIELD and the empty path is
+// not a field. A chain method has a field — the one it is called on — so the
+// WHOLE document becomes rules over that one subject through the same
+// collectSubSchemaRules() every applicator arm already uses. `additionalProperties`,
+// `anyOf`, `not`, `if/then/else`, `minProperties`, `propertyNames` and the rest
+// are reachable at the top of a document through this method and through no
+// other route in the library.
+//
+// WHAT IT STILL CANNOT DO: `null`. src/runtime/decide-presence.ts settles
+// absence before any check runs, so a composite rule is never handed a null and
+// `{"type":"string"}` cannot reject one from here. Nullability is the FIELD's
+// presence policy — declare `.optional()` when the document forbids null, which
+// is precisely what declare-presence.ts does for every child property. See
+// needsFromOthers: a document-driven presence rule has no home yet.
+// ===========================================================================
+const create_rule_1 = require("../../../plugin-kit/create-rule");
+const plugin_definition_1 = require("../../../plugin-kit/plugin-definition");
+const types_1 = require("../../../types");
+const index_1 = require("../../index");
+/** Every slot: a JSON Schema document constrains a value of any shape. */
+const SCHEMA_SLOTS = [
+    "string",
+    "number",
+    "boolean",
+    "date",
+    "array",
+    "tuple",
+    "object",
+    "union",
+    "any",
+];
+/** The label the whole document carries inside the composite it becomes. */
+exports.SCHEMA_BRANCH_LABEL = "schema";
+const NO_EXTERNAL_DOCUMENTS = Object.freeze({});
+/**
+ * The document as a rule list over ONE subject. Exported because it is the
+ * only part of this plugin the full-feature bundle needs, and because a test
+ * can then count the rules a document produces without building a validator.
+ */
+function collectDocumentRules(ctx, document, bag, options = {}) {
+    if (!(0, index_1.isDraft07Schema)(document))
+        throw new index_1.NotASchemaError(document);
+    const root = document;
+    const scope = (0, index_1.createDocumentScope)(root, options.externalDocuments ?? NO_EXTERNAL_DOCUMENTS);
+    // The seed's `chain` is a ChainBuildContext, whose three members a
+    // RuleBuildContext already carries. Written inline because naming the type
+    // would mean importing src/chain, which tier `extension` forbids.
+    const seed = {
+        bag,
+        scope,
+        chain: {
+            fieldPath: ctx.fieldPath,
+            declaredSiblingKeys: ctx.declaredSiblingKeys,
+            config: ctx.config,
+        },
+    };
+    const resolved = (0, index_1.resolveSchemaNodeInScope)(root, scope);
+    const context = (0, index_1.createStructuralContext)(seed, resolved.node, [], resolved.scope);
+    // The branch subject carries its own null policy, like every sub-schema
+    // subject: collectSubSchemaRules puts it there. `judgesNull` on the plugin
+    // gets null as far as this composite; that policy gets it the rest of the
+    // way, into the document's own rules.
+    return (0, index_1.collectSubSchemaRules)(resolved.node, context);
+}
+exports.jsonSchemaPlugin = (0, plugin_definition_1.definePlugin)()({
+    name: "jsonSchema",
+    // The document decides whether null is allowed, so null has to reach it.
+    judgesNull: true,
+    method: "jsonSchema",
+    slots: SCHEMA_SLOTS,
+    build: (ctx, document, bag, options) => (0, create_rule_1.composite)({
+        code: ctx.code,
+        messageFactory: ctx.messageFactory,
+        severity: ctx.severity,
+        branches: [
+            (0, create_rule_1.branch)(exports.SCHEMA_BRANCH_LABEL, collectDocumentRules(ctx, document, bag, options)),
+        ],
+        combine: (runners) => (value, runContext) => runners[0]?.run(value, runContext) ?? types_1.PASS,
+        describe: () => "Value does not match the JSON Schema document",
+        buildMessageContext: () => ({}),
+    }),
+});

package/dist/json-schema/extensions/json-schema/json-schema.mjs

@@ -0,0 +1,104 @@
+// ===========================================================================
+// L8 (tier `extension`)  src/json-schema/extensions/json-schema/json-schema.ts
+// `./plugins/jsonSchema` — the TREE-SHAKEABLE half of the two-tier story.
+//
+// WHAT CHANGED FROM 1.x, AND WHY (this is a deviation; it is argued, not hidden):
+// 1.x shipped `jsonSchemaPlugin` as a BuilderExtensionPlugin that grew a
+// `.fromJsonSchema()` method onto `Builder` itself. The rewritten core has no
+// builder-extension mechanism at all — `Builder` was frozen at the contract
+// gate (step 7) with exactly `use` / `withConfig` / `for` — so the method
+// cannot be grown back without breaking that freeze. The conversion front door
+// is therefore the FUNCTION `fromJsonSchema(bag, schema)` (step 25), re-exported
+// from this directory's index, and this file adds the thing a function cannot
+// express: a CHAIN METHOD, so a document can constrain one declared field.
+//
+// `.jsonSchema(document, bag)` takes the bag EXPLICITLY. That is the whole
+// point of this subpath: importing the forty-five plugin entry files here would
+// make every one of them statically reachable and end per-plugin tree-shaking,
+// which is exactly the size difference 1.x published between this subpath and
+// ./plugins/jsonSchemaFullFeature. The caller assembles the bag from the
+// plugins they already import; the full-feature bundle ships a complete one.
+//
+// THE ROOT IS DECLARABLE HERE. flatten-schema refuses a rule-bearing keyword on
+// the document ROOT because Luq declares rules per FIELD and the empty path is
+// not a field. A chain method has a field — the one it is called on — so the
+// WHOLE document becomes rules over that one subject through the same
+// collectSubSchemaRules() every applicator arm already uses. `additionalProperties`,
+// `anyOf`, `not`, `if/then/else`, `minProperties`, `propertyNames` and the rest
+// are reachable at the top of a document through this method and through no
+// other route in the library.
+//
+// WHAT IT STILL CANNOT DO: `null`. src/runtime/decide-presence.ts settles
+// absence before any check runs, so a composite rule is never handed a null and
+// `{"type":"string"}` cannot reject one from here. Nullability is the FIELD's
+// presence policy — declare `.optional()` when the document forbids null, which
+// is precisely what declare-presence.ts does for every child property. See
+// needsFromOthers: a document-driven presence rule has no home yet.
+// ===========================================================================
+import { branch, composite } from "../../../plugin-kit/create-rule.mjs";
+import { definePlugin } from "../../../plugin-kit/plugin-definition.mjs";
+import { PASS } from "../../../types/index.mjs";
+import { NotASchemaError, collectSubSchemaRules, createStructuralContext, createDocumentScope, isDraft07Schema, resolveSchemaNodeInScope, } from "../../index.mjs";
+/** Every slot: a JSON Schema document constrains a value of any shape. */
+const SCHEMA_SLOTS = [
+    "string",
+    "number",
+    "boolean",
+    "date",
+    "array",
+    "tuple",
+    "object",
+    "union",
+    "any",
+];
+/** The label the whole document carries inside the composite it becomes. */
+export const SCHEMA_BRANCH_LABEL = "schema";
+const NO_EXTERNAL_DOCUMENTS = Object.freeze({});
+/**
+ * The document as a rule list over ONE subject. Exported because it is the
+ * only part of this plugin the full-feature bundle needs, and because a test
+ * can then count the rules a document produces without building a validator.
+ */
+export function collectDocumentRules(ctx, document, bag, options = {}) {
+    if (!isDraft07Schema(document))
+        throw new NotASchemaError(document);
+    const root = document;
+    const scope = createDocumentScope(root, options.externalDocuments ?? NO_EXTERNAL_DOCUMENTS);
+    // The seed's `chain` is a ChainBuildContext, whose three members a
+    // RuleBuildContext already carries. Written inline because naming the type
+    // would mean importing src/chain, which tier `extension` forbids.
+    const seed = {
+        bag,
+        scope,
+        chain: {
+            fieldPath: ctx.fieldPath,
+            declaredSiblingKeys: ctx.declaredSiblingKeys,
+            config: ctx.config,
+        },
+    };
+    const resolved = resolveSchemaNodeInScope(root, scope);
+    const context = createStructuralContext(seed, resolved.node, [], resolved.scope);
+    // The branch subject carries its own null policy, like every sub-schema
+    // subject: collectSubSchemaRules puts it there. `judgesNull` on the plugin
+    // gets null as far as this composite; that policy gets it the rest of the
+    // way, into the document's own rules.
+    return collectSubSchemaRules(resolved.node, context);
+}
+export const jsonSchemaPlugin = /*#__PURE__*/ definePlugin()({
+    name: "jsonSchema",
+    // The document decides whether null is allowed, so null has to reach it.
+    judgesNull: true,
+    method: "jsonSchema",
+    slots: SCHEMA_SLOTS,
+    build: (ctx, document, bag, options) => composite({
+        code: ctx.code,
+        messageFactory: ctx.messageFactory,
+        severity: ctx.severity,
+        branches: [
+            branch(SCHEMA_BRANCH_LABEL, collectDocumentRules(ctx, document, bag, options)),
+        ],
+        combine: (runners) => (value, runContext) => runners[0]?.run(value, runContext) ?? PASS,
+        describe: () => "Value does not match the JSON Schema document",
+        buildMessageContext: () => ({}),
+    }),
+});

package/dist/json-schema/extensions/json-schema-full-feature/bundle-coverage.d.ts

@@ -0,0 +1,38 @@
+import { type JsonSchemaBag } from "../../index";
+/**
+ * Plugins the bundle carries that NO keyword or format binding names.
+ *
+ * Every one is driven by the converter itself (a structural expansion calls
+ * `plugin.build` directly) or is reachable only from a hand-written chain. The
+ * list is the MEASURED complement of `listBoundPluginNames()`: 31 names are
+ * bound, 45 are bundled, and these are the 14 that are left. It is written out
+ * rather than derived so that a change on EITHER side — a new binding, or a
+ * plugin leaving the bag — fails the test instead of quietly re-balancing.
+ *
+ * `required` is deliberately NOT here: keyword-map-object.ts binds it, even
+ * though declare-presence.ts builds the child-property presence rule from
+ * create-rule instead (see its header for why `.required()` is the wrong shape
+ * for Draft-07 §6.5.3).
+ */
+export declare const UNBOUND_BUNDLED_PLUGIN_NAMES: readonly string[];
+/** The plugin NAMES the bag carries. Not its keys: bindings name `plugin.name`. */
+export declare function listBundledPluginNames(bag: JsonSchemaBag): readonly string[];
+/**
+ * A keyword or format is bound to a plugin the bundle does not ship. Non-empty
+ * means `fromJsonSchema` would reach for a missing member at build time.
+ */
+export declare function findUnbundledBoundPlugins(bag: JsonSchemaBag): readonly string[];
+/**
+ * The bundle ships a plugin that no binding names AND that is not declared
+ * above as converter-driven. Non-empty means the bundle grew weight nothing
+ * asked for, or that a declared exemption is now bound and should be deleted.
+ */
+export declare function findUnexplainedBundledPlugins(bag: JsonSchemaBag): readonly string[];
+/**
+ * A declared exemption that has since become bound. Stale; delete it.
+ *
+ * `declared` is a parameter so the check can be run against a list that is
+ * deliberately wrong — otherwise "it returns nothing" and "it can never return
+ * anything" look the same from a test.
+ */
+export declare function findStaleUnboundDeclarations(declared?: readonly string[]): readonly string[];