@json-schema-engine/core 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Andrews
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @json-schema-engine/core
+
+Interpreter core for JSON Schema: a registry, dialects, evaluation, annotations, and output rendering for draft 2020-12, draft 2019-09, draft-07, and draft-06. Install this package on its own for validation and annotation collection; add `@json-schema-engine/compiler`, `@json-schema-engine/formats`, or `@json-schema-engine/dialect-draft04` alongside it when you need compiled artifacts, format assertions, or draft-04 support.
+
+## Install
+
+```sh
+npm install @json-schema-engine/core
+```
+
+## Example
+
+```ts
+import assert from "node:assert";
+import { createEngine } from "@json-schema-engine/core";
+
+const engine = createEngine();
+const uri = engine.registerSchema(
+  {
+    type: "object",
+    properties: {
+      id: { type: "integer" },
+      tags: { type: "array", items: { type: "string" } },
+    },
+    required: ["id"],
+  },
+  "https://example.com/item",
+);
+
+const result = engine.evaluate(uri, { tags: [2] }, { output: "basic" });
+assert.equal(result.valid, false);
+assert.ok(result.errors && result.errors.length > 0);
+assert.equal(engine.evaluate(uri, { id: 1, tags: ["a"] }).valid, true);
+```
+
+## Status
+
+Version 0.0.1 is published for initial public feedback on both the functionality and the documentation. APIs may change before 1.0. [STATUS.md](https://github.com/handrews/json-schema-engine/blob/main/STATUS.md) is the authoritative statement of what is built and what is staged.
+
+## Documentation
+
+- [User guide](https://github.com/handrews/json-schema-engine/blob/main/docs/guide/index.md)
+- [Validation](https://github.com/handrews/json-schema-engine/blob/main/docs/guide/validation.md)
+- [Annotations](https://github.com/handrews/json-schema-engine/blob/main/docs/guide/annotations.md)
+- [Conformance](https://github.com/handrews/json-schema-engine/blob/main/docs/conformance.md)
+- [Repository](https://github.com/handrews/json-schema-engine)
+
+## License
+
+MIT

package/dist/coverage.d.ts

@@ -0,0 +1,30 @@
+import { DependencyRecord } from "./engine.js";
+import { Cursor } from "./cursor.js";
+/**
+ * Folded name coverage: the set of evaluated property names. Ports
+ * `unevaluatedProperties.evaluate`'s seen-set union — every `string[]` entry
+ * contributes its names; other shapes are ignored.
+ */
+export declare function foldNameCoverage(channel: readonly unknown[]): Set<string>;
+/**
+ * Folded index coverage over an array of the given length. Ports
+ * `unevaluatedItems.evaluate`'s coveredPrefix/coveredIdx computation: `true`
+ * covers the whole array, a `number` extends the covered prefix to value+1
+ * (max-folded), a `number[]` marks individual indexes.
+ */
+export declare function foldIndexCoverage(channel: readonly unknown[], length: number): {
+    coveredPrefix: number;
+    coveredIdx: Set<number>;
+};
+/**
+ * Channel entries a fragment (interpreted island) contributes: the data of
+ * coverage-producer dependency records at the island's root cursor.
+ * `evaluateFragment` returns root-frame surviving records with cursor
+ * identity intact; filtering to the fragment's root `cursor` keeps coverage
+ * per-instance-location, and filtering to `coverageIds`
+ * (SchemaRegistry.coverageIds) keeps only the producers whose data the
+ * shape-dispatching folds above understand — other dependency data (an
+ * `if` outcome, say) never reaches the channel. Data passes through untouched.
+ */
+export declare function harvestCoverage(dependencies: readonly DependencyRecord[], cursor: Cursor, coverageIds: ReadonlySet<string>): unknown[];
+//# sourceMappingURL=coverage.d.ts.map

package/dist/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAUzE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,OAAO,EAAE,EAC3B,MAAM,EAAE,MAAM,GACb;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CAgBpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,SAAS,gBAAgB,EAAE,EACzC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,OAAO,EAAE,CAMX"}

package/dist/coverage.js

@@ -0,0 +1,81 @@
+// Compiled-tier port of the consumer keywords' channel-reading semantics
+// (COMPILED-CONSUMERS.md). The runtime coverage channel is a flat array of
+// RAW DEPENDENCY DATA — the same values `ctx.produce` yields — merged with
+// mark/truncate at application boundaries by the serializer (phase B). These
+// helpers fold that channel exactly as the interpreter's `unevaluated*`
+// evaluate() folds visible dependency records, dispatching on VALUE SHAPE
+// (the shape is unambiguous, so one mixed names+indexes channel is sound):
+//
+// - `string[]`  evaluated property names (properties/patternProperties/
+//               additionalProperties/unevaluatedProperties values); folds
+//               into name coverage. Empty array is a no-op.
+// - `true`      full index coverage (items / contains-all /
+//               prefixItems-covered-whole-array / unevaluatedItems values).
+// - `number` n  prefix coverage of indexes 0..n, i.e. coveredPrefix = n+1
+//               (prefixItems' largest-applied-index value).
+// - `number[]`  individual covered indexes (contains' matched list).
+//
+// Name folding ignores non-`string[]` entries; index folding ignores
+// `string[]` entries; `[]` is a no-op for both.
+/**
+ * Folded name coverage: the set of evaluated property names. Ports
+ * `unevaluatedProperties.evaluate`'s seen-set union — every `string[]` entry
+ * contributes its names; other shapes are ignored.
+ */
+export function foldNameCoverage(channel) {
+    const seen = new Set();
+    for (const entry of channel) {
+        if (Array.isArray(entry)) {
+            for (const el of entry) {
+                if (typeof el === "string")
+                    seen.add(el);
+            }
+        }
+    }
+    return seen;
+}
+/**
+ * Folded index coverage over an array of the given length. Ports
+ * `unevaluatedItems.evaluate`'s coveredPrefix/coveredIdx computation: `true`
+ * covers the whole array, a `number` extends the covered prefix to value+1
+ * (max-folded), a `number[]` marks individual indexes.
+ */
+export function foldIndexCoverage(channel, length) {
+    let coveredPrefix = 0;
+    const coveredIdx = new Set();
+    for (const entry of channel) {
+        if (entry === true) {
+            coveredPrefix = length;
+        }
+        else if (typeof entry === "number") {
+            coveredPrefix = Math.max(coveredPrefix, entry + 1);
+        }
+        else if (Array.isArray(entry)) {
+            // number[] (contains' matched list); string[] contributes no indexes.
+            for (const el of entry) {
+                if (typeof el === "number")
+                    coveredIdx.add(el);
+            }
+        }
+    }
+    return { coveredPrefix, coveredIdx };
+}
+/**
+ * Channel entries a fragment (interpreted island) contributes: the data of
+ * coverage-producer dependency records at the island's root cursor.
+ * `evaluateFragment` returns root-frame surviving records with cursor
+ * identity intact; filtering to the fragment's root `cursor` keeps coverage
+ * per-instance-location, and filtering to `coverageIds`
+ * (SchemaRegistry.coverageIds) keeps only the producers whose data the
+ * shape-dispatching folds above understand — other dependency data (an
+ * `if` outcome, say) never reaches the channel. Data passes through untouched.
+ */
+export function harvestCoverage(dependencies, cursor, coverageIds) {
+    const out = [];
+    for (const d of dependencies) {
+        if (d.cursor === cursor && coverageIds.has(d.behaviorId))
+            out.push(d.data);
+    }
+    return out;
+}
+//# sourceMappingURL=coverage.js.map

package/dist/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.js","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,2EAA2E;AAC3E,2EAA2E;AAC3E,6EAA6E;AAC7E,wEAAwE;AACxE,0EAA0E;AAC1E,2EAA2E;AAC3E,EAAE;AACF,wEAAwE;AACxE,0EAA0E;AAC1E,4DAA4D;AAC5D,4DAA4D;AAC5D,4EAA4E;AAC5E,0EAA0E;AAC1E,4DAA4D;AAC5D,qEAAqE;AACrE,EAAE;AACF,qEAAqE;AACrE,gDAAgD;AAKhD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA2B;IAC1D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;gBACvB,IAAI,OAAO,EAAE,KAAK,QAAQ;oBAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA2B,EAC3B,MAAc;IAEd,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,aAAa,GAAG,MAAM,CAAC;QACzB,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrC,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACrD,CAAC;aAAM,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,sEAAsE;YACtE,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;gBACvB,IAAI,OAAO,EAAE,KAAK,QAAQ;oBAAE,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,YAAyC,EACzC,MAAc,EACd,WAAgC;IAEhC,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cursor.d.ts

@@ -0,0 +1,16 @@
+import { JsonValue } from "./json.js";
+/** A parent-linked position in the instance document. */
+export interface Cursor {
+    readonly value: JsonValue;
+    readonly parent: Cursor | null;
+    readonly segment: string | number | null;
+    /** Lazily cached JSON Pointer; use {@link instancePointer}. */
+    ptr?: string;
+}
+/** Creates a cursor at the instance document root. */
+export declare const rootCursor: (value: JsonValue) => Cursor;
+/** Creates a cursor for a named or indexed child of `parent`. */
+export declare const childCursor: (parent: Cursor, segment: string | number, value: JsonValue) => Cursor;
+/** Computes the JSON Pointer for a cursor's instance location, caching the result. */
+export declare function instancePointer(cursor: Cursor): string;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,SAAS,EAAiB,MAAM,WAAW,CAAC;AAErD,yDAAyD;AACzD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACzC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,sDAAsD;AACtD,eAAO,MAAM,UAAU,GAAI,OAAO,SAAS,KAAG,MAI5C,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,WAAW,GACtB,QAAQ,MAAM,EACd,SAAS,MAAM,GAAG,MAAM,EACxB,OAAO,SAAS,KACf,MAAsC,CAAC;AAE1C,sFAAsF;AACtF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOtD"}

package/dist/cursor.js

@@ -0,0 +1,28 @@
+// Instance cursor: a parent-linked position in the instance document.
+//
+// Cursor identity carries semantic weight: in-place applicators ($ref, allOf,
+// if, ...) apply subschemas to the *same* cursor object, while child
+// applicators (properties, items, ...) create child cursors. The channel's
+// visibility query keys on this identity (engine.ts). JSON Pointer strings
+// are materialized lazily, only when output units escape.
+import { escapeSegment } from "./json.js";
+/** Creates a cursor at the instance document root. */
+export const rootCursor = (value) => ({
+    value,
+    parent: null,
+    segment: null,
+});
+/** Creates a cursor for a named or indexed child of `parent`. */
+export const childCursor = (parent, segment, value) => ({ value, parent, segment });
+/** Computes the JSON Pointer for a cursor's instance location, caching the result. */
+export function instancePointer(cursor) {
+    if (cursor.ptr !== undefined)
+        return cursor.ptr;
+    if (cursor.parent === null)
+        return (cursor.ptr = "");
+    return (cursor.ptr =
+        instancePointer(cursor.parent) +
+            "/" +
+            escapeSegment(String(cursor.segment)));
+}
+//# sourceMappingURL=cursor.js.map

package/dist/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,8EAA8E;AAC9E,qEAAqE;AACrE,2EAA2E;AAC3E,2EAA2E;AAC3E,0DAA0D;AAE1D,OAAO,EAAa,aAAa,EAAE,MAAM,WAAW,CAAC;AAWrD,sDAAsD;AACtD,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAgB,EAAU,EAAE,CAAC,CAAC;IACvD,KAAK;IACL,MAAM,EAAE,IAAI;IACZ,OAAO,EAAE,IAAI;CACd,CAAC,CAAC;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,WAAW,GAAG,CACzB,MAAc,EACd,OAAwB,EACxB,KAAgB,EACR,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;AAE1C,sFAAsF;AACtF,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,IAAI,MAAM,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC;IAChD,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,CAAC,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;IACrD,OAAO,CAAC,MAAM,CAAC,GAAG;QAChB,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC;YAC9B,GAAG;YACH,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/dialect.d.ts

@@ -0,0 +1,316 @@
+import { JsonValue } from "./json.js";
+import { Cursor } from "./cursor.js";
+import { SchemaRef } from "./ref.js";
+import { CompiledRegex } from "./regex.js";
+import { LoweringContext } from "./lowering.js";
+/**
+ * Static contribution of one keyword to the evaluated-property-name set of
+ * its schema object (D9a). A coverage is a *predicate description*, not
+ * necessarily a finite set: `patterns` still lowers (hoisted regexes in the
+ * sweep test); only `dynamic` forces runtime evaluated-set tracking.
+ */
+export type NameCoverage = {
+    kind: "names";
+    names: readonly string[];
+} | {
+    kind: "patterns";
+    patterns: readonly string[];
+} | {
+    kind: "all";
+} | {
+    kind: "dynamic";
+};
+/** Static contribution to the evaluated-index coverage of an array (D9a). */
+export type IndexCoverage = {
+    kind: "prefix";
+    count: number;
+} | {
+    kind: "allFrom";
+    start: number;
+} | {
+    kind: "all";
+} | {
+    kind: "dynamic";
+};
+/**
+ * How a keyword applies one subschema — the compilation planner's edge
+ * facts, richer than `subschemas` (which only says where children live and
+ * keeps driving the registration walk).
+ */
+export interface SubschemaApplication {
+    /** position relative to the keyword's value; [] is the value itself. A leading "../name" is expressed via `sibling` instead. */
+    path: readonly (string | number)[];
+    /** set when the applied subschema is a sibling keyword's value (if → then/else) */
+    sibling?: string;
+    /** for reference keywords: the reference value, resolved against the lexical base at plan time (path is ignored) */
+    ref?: string;
+    mode: "inPlace" | "childByKey" | "childByIndex" | "childSweep" | "propertyName";
+    /** application depends on runtime branching (anyOf/oneOf alternatives, if-guarded), not merely instance shape */
+    conditional: boolean;
+    /** the subschema's verdict feeds this keyword's verdict (false for if's condition role and contains' per-item probes) */
+    asserts: boolean;
+    /**
+     * The verdict feeds NEGATED (`not`): subschema success fails the keyword.
+     * Coverage analysis (D9a) skips inverted edges — their records never
+     * survive into the parent on the parent-success path (success fails the
+     * node; failure discards the frame).
+     */
+    inverted?: boolean;
+}
+/**
+ * Static facts about one keyword occurrence, derived from its value alone.
+ * This is the compiler tier's entire window into keyword semantics (D1), and
+ * it also drives the registry's schema-position walk.
+ */
+export interface StaticFacts {
+    /** paths to child schemas, relative to the keyword's value */
+    subschemas?: readonly (readonly (string | number)[])[];
+    /**
+     * reference URIs this keyword's value points at (relative to the lexical
+     * base); drives transitive resource loading (D7)
+     */
+    references?: readonly string[];
+    /**
+     * behavior ids of dependency records this keyword can emit — its own id;
+     * `produce()` refuses an undeclared producer (engine.ts
+     * UndeclaredProductionError). Annotation keywords declare nothing.
+     */
+    produces?: readonly string[];
+    /** behavior ids of dependency records this keyword reads from the channel */
+    consumes?: readonly string[];
+    /**
+     * regular-expression values this keyword compiles (e.g. `pattern`, the
+     * property-name patterns of `patternProperties`); screened by
+     * `rejectUnsafeRegex` at registration (see regex.ts)
+     */
+    regexes?: readonly string[];
+    /**
+     * format names this keyword needs a table entry for (the compiler hoists
+     * one lookup per name); screened by `UnknownFormatError` at registration
+     * under the refuse-unknown posture (see keywords/format.ts)
+     */
+    formats?: readonly string[];
+    /** participates in dynamic scope resolution ($dynamicRef and friends) */
+    dynamicScopeSensitive?: boolean;
+    /** static evaluated-name contribution (D9a; see {@link NameCoverage}) */
+    evaluatesNames?: NameCoverage;
+    /** static evaluated-index contribution (D9a; see {@link IndexCoverage}) */
+    evaluatesIndexes?: IndexCoverage;
+    /**
+     * how this keyword applies its subschemas — planner edge facts
+     * ({@link SubschemaApplication}); `subschemas` remains the registration
+     * walk's position list
+     */
+    applications?: readonly SubschemaApplication[];
+}
+/**
+ * Context for {@link KeywordBehavior.analyze}: the keyword's containing
+ * schema object, for sibling-dependent facts (`items` starts after
+ * `prefixItems`; `if` declares applications for sibling `then`/`else`) —
+ * the same sibling reads `evaluate()` performs through `ctx.schema`.
+ */
+export interface AnalyzeContext {
+    readonly schema: Readonly<Record<string, JsonValue>>;
+}
+/** Minimal view of a dependency record, for consumer keywords. */
+export interface DependencyView {
+    behaviorId: string;
+    data: unknown;
+}
+/**
+ * The engine services available to one keyword application. This is the only
+ * path to subschema application, the channel, and error reporting — the
+ * engine owns path/scope/frame bookkeeping in exactly one place (DESIGN.md
+ * §3), which is what makes locations compile-time constants for the M6
+ * compiler.
+ */
+/**
+ * Structured data about one failure, keyed per keyword (D13). Values are
+ * plain JSON so downstream mappers (ajv-compat) consume them mechanically
+ * instead of parsing message strings.
+ */
+export type ErrorParams = Readonly<Record<string, JsonValue>>;
+export interface KeywordContext {
+    /** the current schema object (this keyword's siblings included) */
+    readonly schema: Record<string, JsonValue>;
+    readonly cursor: Cursor;
+    /** apply the subschema at `segments` (relative to the current schema object) */
+    apply(segments: readonly (string | number)[], cursor: Cursor): boolean;
+    /** resolve a reference against the current lexical base */
+    resolveRef(ref: string): SchemaRef;
+    /** resolve a `$dynamicRef`-class reference, with dynamic-scope rebinding (D8; see engine.ts resolveDynamic) */
+    resolveDynamic(ref: string): SchemaRef;
+    /** resolve a 2019-09 `$recursiveRef`, D8's degenerate case (see engine.ts resolveRecursive) */
+    resolveRecursive(ref: string): SchemaRef;
+    /** apply a resolved reference target at the current cursor */
+    applyResolved(target: SchemaRef): boolean;
+    /** compile a `pattern`/`patternProperties` regex through the engine's regex engine and cache (see regex.ts) */
+    compileRegex(pattern: string): CompiledRegex;
+    /**
+     * record this keyword's value as an annotation at the current cursor —
+     * the annotation value is the keyword value (draft-03 §12.9), so there is
+     * nothing to pass
+     */
+    annotate(): void;
+    /**
+     * communicate computed dependency data to other keywords at the current
+     * cursor; never output. `analyze().produces` must list this keyword's id.
+     */
+    produce(data: unknown): void;
+    /**
+     * dependency records visible at the current cursor from the listed
+     * behaviors; `analyze().consumes` must list them. Draft-03 §12.3 allows a
+     * dependency on the same dynamic scope or on successful subscopes: `"all"`
+     * (default) sees both — this schema object's keywords plus records merged
+     * from successful in-place sub-applications, what `unevaluated*` needs;
+     * `"adjacent"` sees only this schema object's own keywords, what `then`
+     * and `else` need from `if`.
+     */
+    visible(behaviorIds: readonly string[], scope?: "all" | "adjacent"): readonly DependencyView[];
+    /** report an assertion failure for this keyword, with optional structured params (D13) */
+    error(message: string, params?: ErrorParams): void;
+}
+/** A keyword's static analysis and evaluation semantics. */
+export interface KeywordBehavior {
+    /** keyword URI — the stable identity, independent of its name in a dialect */
+    readonly id: string;
+    /**
+     * Evaluation phase within a schema object: phase 1 keywords (unevaluated*)
+     * run after all phase 0 keywords have merged their records.
+     */
+    readonly phase?: 0 | 1;
+    /**
+     * An identifier or reserved-location keyword (`$id`, `$defs`, `$comment`,
+     * ...): it evaluates to nothing and appears in no output unit (IETF
+     * draft-03 §12.6, §12.10), so a trace records no keyword entry for it.
+     */
+    readonly structural?: boolean;
+    /**
+     * Static facts; also drives the registration walk's descent. The context
+     * (sibling access) is supplied by every caller; implementations that need
+     * no sibling facts ignore it.
+     */
+    analyze?(value: JsonValue, context?: AnalyzeContext): StaticFacts;
+    /**
+     * Evaluates the keyword at `cursor`. A keyword that reports an error
+     * through `ctx.error()` must return `false`: the engine drops the errors
+     * of an accepting keyword's sub-evaluations (draft-03 §12.2) and throws
+     * `KeywordContractError` when the keyword itself reported one.
+     */
+    evaluate(value: JsonValue, cursor: Cursor, ctx: KeywordContext): boolean;
+    /**
+     * Optional compiler lowering (D1/D9): describe this keyword's compiled
+     * form as IR through the {@link LoweringContext} — never JavaScript text.
+     * Absent ⇒ schema objects containing this keyword become interpreted
+     * units (the trampoline fallback). Keep `lower` beside `evaluate` and
+     * share their error-message builders: the differential gate compares
+     * error text.
+     */
+    lower?(value: JsonValue, lctx: LoweringContext): void;
+}
+/** A keyword's binding within one dialect: its name there, behavior, and owning vocabulary. */
+export interface DialectKeyword {
+    name: string;
+    behavior: KeywordBehavior;
+    vocabularyUri: string;
+}
+/**
+ * Identifiers found in one schema object, per the dialect's identifier
+ * syntax (D18; see {@link IdentifierExtractor}).
+ */
+export interface IdentifierFacts {
+    /** value that changes the lexical base (and starts a schema resource) */
+    baseId?: string;
+    /** plain-name anchors minted at this schema object */
+    anchors?: readonly string[];
+    /** anchor participating in $dynamicRef rebinding (D8) */
+    dynamicAnchor?: string;
+    /** 2019-09 $recursiveAnchor; effective at a resource root */
+    recursiveAnchor?: boolean;
+}
+/**
+ * Extracts identifier facts from a schema object. Identifier syntax varies
+ * by draft (D18): 2020-12 has `$id`/`$anchor`/`$dynamicAnchor`; 2019-09
+ * replaces the dynamic pair with boolean `$recursiveAnchor`; draft-07/06
+ * mint anchors from plain-fragment `$id` and have no anchor keywords at all.
+ * The extractor is dialect data consumed by the registry's walk and pointer
+ * navigation — keyword behaviors stay syntax-free.
+ */
+export type IdentifierExtractor = (node: Record<string, JsonValue>) => IdentifierFacts;
+/** Identifier syntax for the 2020-12 dialect: `$id`/`$anchor`/`$dynamicAnchor`. */
+export declare const identifiers2020: IdentifierExtractor;
+/** Identifier syntax for the 2019-09 dialect: `$id`/`$anchor`/boolean `$recursiveAnchor`. */
+export declare const identifiers2019: IdentifierExtractor;
+/**
+ * Identifier syntax for legacy draft-07/06 dialects: a schema object
+ * containing `$ref` has no identifiers at all (the suite's "`$ref` prevents
+ * a sibling `$id` from changing the base uri"), and a plain-fragment `$id`
+ * is an anchor rather than a base change.
+ */
+export declare const identifiersLegacy: IdentifierExtractor;
+/** An ordered set of vocabularies with identifier and `$ref` semantics (D18). */
+export interface Dialect {
+    uri: string;
+    /** name -\> entry */
+    keywords: ReadonlyMap<string, DialectKeyword>;
+    /** evaluation order: phase 0 entries then phase 1 entries */
+    ordered: readonly DialectKeyword[];
+    /** the vocabularies this dialect was assembled from, in order */
+    vocabularyUris: readonly string[];
+    allowUnknownKeywords: boolean;
+    identifiers: IdentifierExtractor;
+    /** draft-07/06: siblings of $ref are treated as if absent */
+    refIgnoresSiblings: boolean;
+}
+/** Options for {@link DialectRegistry.registerDialect}. */
+export interface DialectOptions {
+    /** unknown keywords are collected as annotations (spec SHOULD); default true */
+    allowUnknownKeywords?: boolean;
+    /** identifier syntax for this dialect (D18); default 2020-12 */
+    identifiers?: IdentifierExtractor;
+    /** draft-07/06 $ref semantics: siblings are ignored, not evaluated */
+    refIgnoresSiblings?: boolean;
+}
+/** Thrown when a dialect or vocabulary URI has no registered entry. */
+export declare class UnknownDialectError extends Error {
+}
+/** Thrown when a `$vocabulary` URI is required but not registered. */
+export declare class UnknownVocabularyError extends Error {
+}
+/** Thrown when a registry snapshot (a read-only view) is asked to register. */
+export declare class ReadOnlyRegistryError extends Error {
+}
+/** Registry of vocabularies and the dialects assembled from them. */
+export declare class DialectRegistry {
+    private vocabularies;
+    private dialects;
+    private shared;
+    private readOnly;
+    /**
+     * A read-only view of the current registrations. Later registrations on
+     * this registry are invisible to the view, and registering into the view
+     * throws {@link ReadOnlyRegistryError}. A compiled artifact binds to one
+     * so that a compilation boundary cannot change dialect lookups.
+     */
+    snapshot(): DialectRegistry;
+    private mutable;
+    /** Registers a vocabulary's keyword behaviors under its URI. */
+    registerVocabulary(uri: string, keywords: Readonly<Record<string, KeywordBehavior>>): void;
+    /**
+     * Assembles a dialect from already-registered vocabularies.
+     * @throws UnknownDialectError if a listed vocabulary is not registered.
+     */
+    registerDialect(uri: string, vocabularyUris: readonly string[], options?: DialectOptions): void;
+    /**
+     * Looks up a registered dialect by URI.
+     * @throws UnknownDialectError if the URI has no registered dialect.
+     */
+    getDialect(uri: string): Dialect;
+    /** True if a dialect is registered under this URI. */
+    hasDialect(uri: string): boolean;
+    /** True if a vocabulary is registered under this URI. */
+    hasVocabulary(uri: string): boolean;
+}
+/** Behavior id for annotations from keywords the dialect doesn't know. */
+export declare const unknownKeywordId: (name: string) => string;
+//# sourceMappingURL=dialect.d.ts.map

package/dist/dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect.d.ts","sourceRoot":"","sources":["../src/dialect.ts"],"names":[],"mappings":"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"}