@json-schema-engine/compiler 0.0.1

package/dist/index.js

@@ -0,0 +1,169 @@
+// @json-schema-engine/compiler public API (M6.2 vertical slice): compile a registered
+// schema into a specialized flag-mode validator. Static subschemas become
+// emitted JS; dynamic islands and every fallback cause trampoline to the
+// interpreter through core's evaluateFragment, so the compiled artifact is
+// exactly as correct as the interpreter — never less complete.
+import { DEFAULT_MAX_DEPTH, OutputOptionsError, assembleResult, renderBasic, resolveOutputDemand, } from "@json-schema-engine/core";
+import { buildPlan } from "./plan.js";
+import { serializePlan } from "./serialize/index.js";
+import { finishTrace, makeRuntime } from "./runtime.js";
+import { instantiate, instantiateList, instantiateListAnn, instantiateTrace, } from "./runtime-compile.js";
+export { buildPlan } from "./plan.js";
+export { explainCompilation } from "./explain.js";
+export { serializePlan } from "./serialize/index.js";
+export { emitStandalone, StandaloneUnsupportedError } from "./standalone.js";
+/**
+ * Compile a registered schema into a flag-mode validator. The artifact
+ * binds to a snapshot of the engine's schema and dialect registries taken at
+ * compile time, plus the engine's pattern cache: schemas registered,
+ * re-registered, or given a new dialect later are invisible to it, and a
+ * reference unresolved at compile time stays unresolved for it (E1).
+ */
+export function compileValidator(engine, schemaUri, options = {}) {
+    const plan = buildPlan(engine, schemaUri);
+    // Compilation is synchronous, so the plan (built from the live registry)
+    // and this snapshot see one state; the artifact's islands never see a
+    // later registration.
+    const registry = engine.registry.snapshot();
+    const source = serializePlan(plan, registry, {
+        flags: options.conservative
+            ? { inline: false, plainData: false }
+            : { inline: true, plainData: true },
+    });
+    const runtime = makeRuntime(registry, engine.patternCache, plan.patterns, options.maxDepth ?? DEFAULT_MAX_DEPTH, false, undefined, engine.formats, plan.formats);
+    const validate = instantiate(source, runtime, plan.targets.map((t) => t.ref));
+    return {
+        validate: (instance) => validate(instance),
+        plan,
+        source,
+    };
+}
+/**
+ * Compile a registered schema into a list-output validator (D9e): flat,
+ * interpreter-exact error units — the same elements
+ * `Engine.evaluate(uri, x, { output: "list" }).errors` yields, in the same
+ * order (list artifacts never short-circuit; every branch runs, DESIGN §7).
+ * Error-unit objects materialize only on failure paths. Binds to registry
+ * snapshots exactly like {@link compileValidator}.
+ */
+export function compileList(engine, schemaUri, options = {}) {
+    const selection = options.annotations ?? false;
+    const collect = selection !== false;
+    const errorParams = options.errorParams ?? false;
+    const plan = buildPlan(engine, schemaUri, { output: "list" });
+    const registry = engine.registry.snapshot();
+    const source = serializePlan(plan, registry, {
+        flags: options.conservative
+            ? { inline: false, plainData: false }
+            : { inline: true, plainData: true },
+        output: "list",
+        listParams: errorParams,
+        annotate: collect ? { selection } : undefined,
+    });
+    const runtime = makeRuntime(registry, engine.patternCache, plan.patterns, options.maxDepth ?? DEFAULT_MAX_DEPTH, errorParams, collect ? { selection } : undefined, engine.formats, plan.formats);
+    const targets = plan.targets.map((t) => t.ref);
+    const root = registry.rootRef(schemaUri);
+    const rootLocation = `${root.baseUri}#${root.pointer}`;
+    const keep = typeof selection === "object" ? selection.keep : undefined;
+    if (!collect) {
+        const evaluateList = instantiateList(source, runtime, targets);
+        return {
+            evaluateList,
+            basic: (instance) => {
+                const { valid, errors } = evaluateList(instance);
+                return renderBasic(valid, rootLocation, errors, []);
+            },
+            plan,
+            source,
+        };
+    }
+    // The emitted evaluator returns the raw (static-list-filtered) annotation
+    // array; the wrapper applies `keep` (over the native unit, as the
+    // interpreter does) and the valid-only presence rule, matching
+    // `Engine.evaluate`'s Result.annotations; `basic()` renders that same
+    // flat surface through core's renderer.
+    const rawEval = instantiateListAnn(source, runtime, targets);
+    const evaluateList = (instance) => {
+        const r = rawEval(instance);
+        if (!r.valid)
+            return { valid: false, errors: r.errors };
+        const anns = keep ? r.annotations.filter(keep) : r.annotations;
+        return { valid: true, errors: r.errors, annotations: anns };
+    };
+    return {
+        evaluateList,
+        basic: (instance) => {
+            const r = evaluateList(instance);
+            return renderBasic(r.valid, rootLocation, r.errors, r.annotations ?? []);
+        },
+        plan,
+        source,
+    };
+}
+/**
+ * Compile a registered schema into an evaluator that renders every output
+ * format: a list artifact that also records each application's node —
+ * locations, keyword verdicts, and the records it raised — into core's
+ * located tree, so the documents render through the same code as the
+ * interpreter's. Format, level, and `trace` are chosen per evaluation; the
+ * annotation selection, `errorParams`, and whether irrelevant records are
+ * retained (`verbose`) are fixed here (D5). Without retention the records
+ * are discarded at the cut and a verbose-level request throws
+ * {@link OutputOptionsError}. Binds to registry snapshots exactly like
+ * {@link compileValidator}.
+ */
+export function compileEvaluator(engine, schemaUri, options = {}) {
+    const selection = options.annotations ?? false;
+    const collect = selection !== false;
+    const errorParams = options.errorParams ?? false;
+    const retain = options.verbose ?? false;
+    const plan = buildPlan(engine, schemaUri, { output: "list" });
+    const registry = engine.registry.snapshot();
+    const source = serializePlan(plan, registry, {
+        flags: options.conservative
+            ? { inline: false, plainData: false }
+            : { inline: true, plainData: true },
+        output: "list",
+        listParams: errorParams,
+        annotate: collect ? { selection } : undefined,
+        trace: true,
+    });
+    const runtime = makeRuntime(registry, engine.patternCache, plan.patterns, options.maxDepth ?? DEFAULT_MAX_DEPTH, errorParams, collect ? { selection } : undefined, engine.formats, plan.formats, true, retain);
+    const run = instantiateTrace(source, runtime, plan.targets.map((t) => t.ref));
+    const root = registry.rootRef(schemaUri);
+    const rootLocation = `${root.baseUri}#${root.pointer}`;
+    const keep = typeof selection === "object" ? selection.keep : undefined;
+    const evaluate = (instance, evaluateOptions = {}) => {
+        // The controls fixed at compile time are rejected, not ignored (ADR
+        // 0003: every combination is supported or refused).
+        for (const fixed of ["annotations", "errorParams", "positions"]) {
+            if (fixed in evaluateOptions) {
+                throw new OutputOptionsError(`'${fixed}' is fixed when the evaluator is compiled`);
+            }
+        }
+        // The compiled selection stands in for the option; `flag` is admitted
+        // whatever the selection, since it renders no records.
+        const demand = {
+            ...resolveOutputDemand({
+                output: evaluateOptions.output,
+                verbose: evaluateOptions.verbose,
+                trace: evaluateOptions.trace,
+            }),
+            annotations: selection,
+        };
+        if (demand.verbose && !retain) {
+            throw new OutputOptionsError("the verbose level needs an evaluator compiled with verbose: true");
+        }
+        const st = run(instance);
+        if (demand.format === "flag")
+            return { valid: st.valid };
+        const { units, root: node } = finishTrace(st, keep, demand.verbose);
+        return assembleResult(demand, st.valid, units, node, rootLocation, evaluateOptions.trace === true);
+    };
+    return {
+        evaluate: evaluate,
+        plan,
+        source,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/plan.d.ts

@@ -0,0 +1,83 @@
+import { type Engine, type SchemaRef, type SubschemaApplication } from "@json-schema-engine/core";
+/** Why a unit is interpreted rather than compiled. */
+export type FallbackCause = "dynamic" | "unlowerable" | "cycle" | "nonSchema";
+/** Static evaluated-name coverage for one schema object (slice: own-node trio only). */
+export interface StaticNameCoverage {
+    names: readonly string[];
+    patterns: readonly string[];
+    coversAllNames: boolean;
+    prefixCount: number;
+    coversAllIndexes: boolean;
+}
+/** One application edge out of a unit, resolved at plan time. */
+export interface PlannedApplication {
+    keyword: string;
+    app: SubschemaApplication;
+    targetKey: string;
+}
+export interface PlannedUnit {
+    key: string;
+    ref: SchemaRef;
+    kind: "static" | "interpreted";
+    cause?: FallbackCause;
+    /** static units: resolved outgoing application edges (keyword order preserved) */
+    edges: PlannedApplication[];
+    /** static coverage for this schema object, when computable (slice rule) */
+    coverage: StaticNameCoverage | null;
+    /**
+     * Consumer compiled with RUNTIME evaluated-set tracking instead of the
+     * interpreter (COMPILED-CONSUMERS.md phase B): a flag-mode consumer whose
+     * evaluated coverage is dynamic (static licensing failed), or ANY list-mode
+     * consumer (list plans never static-license — see PlanOptions.output).
+     * `coverage` stays null; the unit's body threads a runtime coverage channel
+     * through its in-place closure (its {@link inRegion} members) and its
+     * consumer keywords read it. Never set together with {@link inRegion}
+     * (nested tracked consumers island).
+     */
+    tracking?: boolean;
+    /**
+     * A static unit in some tracked unit's in-place coverage region: reachable
+     * from a tracked (or region) unit via in-place edges. Emitted with a second
+     * calling convention (a trailing coverage channel) so its producers'
+     * post-success coverage flows to the consumer (COMPILED-CONSUMERS.md phase B).
+     */
+    inRegion?: boolean;
+    /** true when any apply path from this unit can reach an interpreted unit */
+    reachesInterpreted: boolean;
+    /** number of planned edges targeting this unit (D9 inline licensing) */
+    useCount: number;
+}
+export interface CompilationPlan {
+    rootKey: string;
+    units: Map<string, PlannedUnit>;
+    /** every regex source any static unit tests (pattern + coverage patterns) */
+    patterns: string[];
+    /** every format name any static unit's asserting `format` tests */
+    formats: string[];
+    /** interpreted units in stable order; index = target-table slot */
+    targets: PlannedUnit[];
+}
+/**
+ * Build the compilation plan for one registered root schema. The walk mirrors
+ * the registration walk's position logic by construction: descent uses the
+ * same analyze() facts and the same registry.child pointer navigation.
+ */
+/** Options for {@link buildPlan}. */
+export interface PlanOptions {
+    /**
+     * The artifact's output mode. Static-coverage licensing for unevaluated*
+     * consumers is sound for "flag" only: coverage models the parent-SUCCESS
+     * path, but when a contributor (e.g. prefixItems inside an allOf branch)
+     * FAILS, the interpreter drops its annotations and unevaluated* reports
+     * additional errors. That difference is verdict-invisible — the failing
+     * contributor already fails the parent — but list output must reproduce
+     * the interpreter's error units exactly. So "list" plans NEVER static-
+     * license a consumer: every consumer is compiled with runtime coverage
+     * tracking (`tracking`), which reproduces the drop-on-failure behavior by
+     * construction (a failed application's channel span truncates, so the sweep
+     * covers less). "flag" keeps the static-coverage fast path.
+     */
+    output?: "flag" | "list";
+}
+export declare function buildPlan(engine: Engine, schemaUri: string, options?: PlanOptions): CompilationPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAMA,OAAO,EAEL,KAAK,MAAM,EAEX,KAAK,SAAS,EAEd,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAElC,sDAAsD;AACtD,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,aAAa,GACb,OAAO,GACP,WAAW,CAAC;AAEhB,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,oBAAoB,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,SAAS,CAAC;IACf,IAAI,EAAE,QAAQ,GAAG,aAAa,CAAC;IAC/B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,kFAAkF;IAClF,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,kBAAkB,EAAE,OAAO,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,mEAAmE;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAOD;;;;GAIG;AACH,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,WAAgB,GACxB,eAAe,CA8QjB"}

package/dist/plan.js

@@ -0,0 +1,385 @@
+// Compilation planner (M6.2): classifies every reachable schema node as a
+// static (compilable) or interpreted (trampoline) unit, using ONLY public
+// core APIs and analyze() facts — never keyword names (D1). Conservative by
+// design: anything uncertain falls back to the interpreter, which is always
+// correct.
+import { UnresolvableRefError, } from "@json-schema-engine/core";
+const unitKey = (ref) => `${ref.baseUri}#${ref.pointer}`;
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function buildPlan(engine, schemaUri, options = {}) {
+    const registry = engine.registry;
+    const units = new Map();
+    const patterns = new Set();
+    const formats = new Set();
+    const rootRef = registry.rootRef(schemaUri);
+    // inPlaceChain: units connected to the current edge via consecutive
+    // in-place applications — a back-edge into this chain is an in-place
+    // cycle (same-cursor re-entry, InfiniteLoopError class) and its target
+    // must stay interpreted. A descending edge resets the chain.
+    const plan = (ref, inPlaceChain) => {
+        const key = unitKey(ref);
+        const existing = units.get(key);
+        if (existing)
+            return existing;
+        const unit = {
+            key,
+            ref,
+            kind: "static",
+            edges: [],
+            coverage: null,
+            reachesInterpreted: false,
+            useCount: 0,
+        };
+        units.set(key, unit);
+        const node = ref.node;
+        if (typeof node === "boolean")
+            return unit; // trivially static
+        if (!isObj(node)) {
+            unit.kind = "interpreted";
+            unit.cause = "nonSchema"; // interpreter D19 backstop reports it lazily
+            return unit;
+        }
+        // No dialect allowlist: keyword facts are the compiler's whole window
+        // into semantics (D1), so a dialect compiles exactly when every present
+        // keyword lowers — the per-keyword check below. That is what lets a
+        // dialect PACKAGE (draft-04, future OAS dialects) become compilable
+        // purely by shipping lower() on its behaviors; the only dialect-LEVEL
+        // semantic the planner must mirror is refIgnoresSiblings, handled
+        // generically here.
+        const dialect = registry.dialectFor(ref.baseUri);
+        // draft-07/06 (D18, engine.ts:397): a $ref makes every sibling keyword
+        // act as if absent — plan/lower ONLY $ref, exactly as applySchemaAtDepth
+        // skips every non-$ref entry when refOnly. Without this, a draft-07
+        // $ref-with-siblings unit would compile both the ref AND the siblings,
+        // a real divergence from the interpreter (unreachable before this
+        // milestone, since every legacy unit was interpreted regardless).
+        const refOnly = dialect.refIgnoresSiblings && Object.hasOwn(node, "$ref");
+        const present = [];
+        let consumerPresent = false;
+        for (const entry of dialect.ordered) {
+            if (refOnly && entry.name !== "$ref")
+                continue;
+            if (!Object.hasOwn(node, entry.name))
+                continue;
+            const behavior = entry.behavior;
+            const value = node[entry.name];
+            const facts = behavior.analyze?.(value, { schema: node }) ?? {};
+            if (facts.dynamicScopeSensitive) {
+                unit.kind = "interpreted";
+                unit.cause = "dynamic";
+                return unit;
+            }
+            if (typeof behavior.lower !== "function") {
+                unit.kind = "interpreted";
+                unit.cause = "unlowerable";
+                return unit;
+            }
+            // A coverage consumer (unevaluated*) declares `consumes` AND an
+            // evaluated-coverage fact; a keyword consuming other dependency data
+            // (then/else reading if's outcome) needs no channel.
+            if ((facts.consumes?.length ?? 0) > 0 &&
+                (facts.evaluatesNames !== undefined ||
+                    facts.evaluatesIndexes !== undefined)) {
+                consumerPresent = true;
+            }
+            for (const rx of facts.regexes ?? [])
+                patterns.add(rx);
+            for (const fmt of facts.formats ?? [])
+                formats.add(fmt);
+            present.push({ name: entry.name, facts });
+        }
+        // Unknown keywords: annotations, elided in flag mode.
+        // Consumer licensing (D9a): a consumer lowers only when its coverage
+        // kind is statically known — from this object's own contributors plus,
+        // transitively, unconditional asserting in-place applications (allOf
+        // conjuncts, $ref chains). Anything runtime-conditional (anyOf/oneOf/
+        // if/dependentSchemas branches, if's condition, dynamic references,
+        // cycles) makes that coverage kind dynamic and the node interpreted.
+        if (consumerPresent) {
+            if (options.output === "list") {
+                // See PlanOptions.output: list mode NEVER static-licenses. Static
+                // coverage models only the parent-SUCCESS path (the M6.6 finding) —
+                // a FAILING contributor's dropped annotations make the interpreter
+                // emit additional unevaluated* errors, verdict-invisible but list-
+                // visible. Runtime tracking reproduces that by construction: the
+                // failed application's channel span truncates and the consumer sweep
+                // then covers less. So every list consumer is tracked; the unit stays
+                // static and CONTINUES to edge resolution (its tracked body needs
+                // planned in-place edges to thread the channel), and the region
+                // fixpoint below threads its in-place closure.
+                unit.tracking = true;
+            }
+            else {
+                // Flag mode: static-coverage licensing is sound (verdict-only), so a
+                // consumer whose coverage kind is statically known keeps the fast path.
+                const halves = coverageHalves(registry, ref, new Set(), true);
+                const needsNames = present.some((k) => (k.facts.consumes?.length ?? 0) > 0 && k.facts.evaluatesNames);
+                const needsIndexes = present.some((k) => (k.facts.consumes?.length ?? 0) > 0 && k.facts.evaluatesIndexes);
+                if ((needsNames && halves.name === null) ||
+                    (needsIndexes && halves.index === null)) {
+                    // Static licensing failed. FLAG mode compiles the consumer anyway,
+                    // with runtime evaluated-set tracking (coverage stays null); the
+                    // unit stays static and CONTINUES to edge resolution / child
+                    // planning like any static unit — its tracked body needs planned
+                    // in-place edges to thread the coverage channel through. The region
+                    // membership of those edges is computed after the walk (below).
+                    unit.tracking = true;
+                }
+                else {
+                    unit.coverage = {
+                        names: halves.name ? [...halves.name.names] : [],
+                        patterns: halves.name ? halves.name.patterns : [],
+                        coversAllNames: halves.name?.all ?? false,
+                        prefixCount: halves.index?.prefix ?? 0,
+                        coversAllIndexes: halves.index?.all ?? false,
+                    };
+                    for (const pat of unit.coverage.patterns)
+                        patterns.add(pat);
+                }
+            }
+        }
+        // Resolve application edges; plan children.
+        for (const { name, facts } of present) {
+            for (const app of facts.applications ?? []) {
+                let target;
+                try {
+                    if (app.ref !== undefined) {
+                        target = registry.resolveRef(app.ref, ref.baseUri);
+                    }
+                    else if (app.sibling !== undefined) {
+                        target = registry.child(ref, [app.sibling, ...app.path]);
+                    }
+                    else {
+                        target = registry.child(ref, [name, ...app.path]);
+                    }
+                }
+                catch (err) {
+                    if (err instanceof UnresolvableRefError) {
+                        // Lazy-failure parity: the interpreter throws only when the
+                        // reference is actually followed, so the whole node falls back.
+                        unit.kind = "interpreted";
+                        unit.cause = "unlowerable";
+                        unit.edges = [];
+                        return unit;
+                    }
+                    throw err;
+                }
+                const targetKey = unitKey(target);
+                if (app.mode === "inPlace") {
+                    if (inPlaceChain.includes(targetKey) || targetKey === key) {
+                        // In-place cycle: same-cursor re-entry. The interpreter's
+                        // seen-set gives exact InfiniteLoopError parity.
+                        const t = units.get(targetKey) ?? plan(target, [...inPlaceChain, key]);
+                        t.kind = "interpreted";
+                        t.cause = "cycle";
+                        t.edges = [];
+                        unit.edges.push({ keyword: name, app, targetKey });
+                        continue;
+                    }
+                    plan(target, [...inPlaceChain, key]);
+                }
+                else {
+                    plan(target, []);
+                }
+                unit.edges.push({ keyword: name, app, targetKey });
+            }
+        }
+        return unit;
+    };
+    const root = plan(rootRef, []);
+    // Coverage-region fixpoint (COMPILED-CONSUMERS.md phase B). A tracked
+    // consumer's coverage comes from its own producers AND, recursively, its
+    // asserting in-place applications; each static unit in that in-place closure
+    // must report its post-success coverage through the runtime channel, so it
+    // gets the second (channel-threaded) calling convention (inRegion). Seeded
+    // by tracked units, propagated through in-place edges of static units.
+    //
+    // Exception — a nested tracked consumer reached inside the closure: threading
+    // one unit's channel through another's consumer is a v1 non-goal, so it is
+    // re-classified interpreted and becomes an ISLAND. The parent then trampolines
+    // it (fragCov) and folds its harvested root coverage — no nested channel.
+    // Islands and already-interpreted targets reached by region edges stay
+    // interpreted. A consumer-bearing STATIC-coverage unit stays a normal region
+    // member (its produces flow like any producer's).
+    const regionStack = [...units.values()]
+        .filter((u) => u.tracking)
+        .map((u) => u.key);
+    while (regionStack.length > 0) {
+        const u = units.get(regionStack.pop());
+        if (u.kind !== "static")
+            continue; // a seed islanded by another seed
+        for (const edge of u.edges) {
+            if (edge.app.mode !== "inPlace")
+                continue;
+            const m = units.get(edge.targetKey);
+            if (m.kind !== "static")
+                continue; // island target: stays interpreted
+            // Boolean subschemas contribute no coverage and fold to a literal at the
+            // call site — never a channel-threaded member.
+            if (typeof m.ref.node === "boolean")
+                continue;
+            if (m.tracking) {
+                // Nested tracked consumer: island it (v1 nested-channel simplification).
+                m.kind = "interpreted";
+                m.cause = "unlowerable";
+                m.edges = [];
+                delete m.tracking;
+                continue;
+            }
+            if (!m.inRegion) {
+                m.inRegion = true;
+                regionStack.push(m.key);
+            }
+        }
+    }
+    // reachesInterpreted fixpoint over the edge graph.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const unit of units.values()) {
+            if (unit.kind === "interpreted" || unit.reachesInterpreted)
+                continue;
+            for (const edge of unit.edges) {
+                const t = units.get(edge.targetKey);
+                if (t.kind === "interpreted" || t.reachesInterpreted) {
+                    unit.reachesInterpreted = true;
+                    changed = true;
+                    break;
+                }
+            }
+        }
+    }
+    for (const unit of units.values()) {
+        if (unit.kind !== "static")
+            continue;
+        for (const edge of unit.edges)
+            units.get(edge.targetKey).useCount++;
+    }
+    const targets = [...units.values()].filter((u) => u.kind === "interpreted");
+    return {
+        rootKey: root.key,
+        units,
+        patterns: [...patterns],
+        formats: [...formats],
+        targets,
+    };
+}
+/**
+ * The evaluated-coverage a schema node contributes at its own cursor (D9a),
+ * including — transitively — unconditional asserting in-place applications.
+ * `excludeConsumers` is true only for the licensing node itself: a
+ * consumer's own coverage fact describes the state AFTER it runs. Inside
+ * transitive targets, consumer facts count (post-success contribution).
+ * Facts come from analyze() and are valid regardless of which tier
+ * evaluates the target, so contribution is independent of compilability.
+ */
+function coverageHalves(registry, ref, visiting, excludeConsumers) {
+    const key = unitKey(ref);
+    if (visiting.has(key))
+        return { name: null, index: null }; // cycle
+    visiting.add(key);
+    try {
+        const node = ref.node;
+        if (typeof node === "boolean") {
+            // Contributes nothing; `false` fails the parent, making coverage moot.
+            return {
+                name: { names: new Set(), patterns: [], all: false },
+                index: { prefix: 0, all: false },
+            };
+        }
+        if (!isObj(node))
+            return { name: null, index: null };
+        // Coverage comes from analyze() facts alone, dialect-agnostic (D1) —
+        // the keyword-author contract is that evaluates* facts are complete.
+        const dialect = registry.dialectFor(ref.baseUri);
+        // Same $ref-only reading as buildPlan's refOnly (engine.ts:397): a
+        // draft-07/06 sibling contributes nothing when $ref is present.
+        const refOnly = dialect.refIgnoresSiblings && Object.hasOwn(node, "$ref");
+        const acc = {
+            name: { names: new Set(), patterns: [], all: false },
+            index: { prefix: 0, all: false },
+        };
+        const fold = (h) => {
+            if (acc.name && h.name) {
+                for (const n of h.name.names)
+                    acc.name.names.add(n);
+                acc.name.patterns.push(...h.name.patterns);
+                acc.name.all ||= h.name.all;
+            }
+            else
+                acc.name = null;
+            if (acc.index && h.index) {
+                acc.index.prefix = Math.max(acc.index.prefix, h.index.prefix);
+                acc.index.all ||= h.index.all;
+            }
+            else
+                acc.index = null;
+        };
+        for (const entry of dialect.ordered) {
+            if (refOnly && entry.name !== "$ref")
+                continue;
+            if (!Object.hasOwn(node, entry.name))
+                continue;
+            const value = node[entry.name];
+            const facts = entry.behavior.analyze?.(value, { schema: node }) ?? {};
+            if (facts.dynamicScopeSensitive)
+                return { name: null, index: null };
+            const isConsumer = (facts.consumes?.length ?? 0) > 0;
+            if (!(excludeConsumers && isConsumer)) {
+                if (acc.name && facts.evaluatesNames) {
+                    const c = facts.evaluatesNames;
+                    if (c.kind === "dynamic")
+                        acc.name = null;
+                    else if (c.kind === "all")
+                        acc.name.all = true;
+                    else if (c.kind === "names")
+                        for (const n of c.names)
+                            acc.name.names.add(n);
+                    else
+                        acc.name.patterns.push(...c.patterns);
+                }
+                if (acc.index && facts.evaluatesIndexes) {
+                    const c = facts.evaluatesIndexes;
+                    if (c.kind === "dynamic")
+                        acc.index = null;
+                    else if (c.kind === "prefix")
+                        acc.index.prefix = Math.max(acc.index.prefix, c.count);
+                    // allFrom's start is bounded by this node's own prefix
+                    // contribution (items starts after sibling prefixItems), so the
+                    // per-node union covers everything.
+                    else
+                        acc.index.all = true;
+                }
+            }
+            for (const app of facts.applications ?? []) {
+                if (app.mode !== "inPlace")
+                    continue; // child cursors: no contribution here
+                if (app.inverted)
+                    continue; // never survives the parent-success path
+                if (app.conditional || !app.asserts) {
+                    // Runtime-conditional contribution (branching, or if's condition
+                    // merging only on its own success): statically unknowable.
+                    return { name: null, index: null };
+                }
+                let target;
+                try {
+                    target =
+                        app.ref !== undefined
+                            ? registry.resolveRef(app.ref, ref.baseUri)
+                            : registry.child(ref, [app.sibling ?? entry.name, ...app.path]);
+                }
+                catch {
+                    return { name: null, index: null };
+                }
+                fold(coverageHalves(registry, target, visiting, false));
+            }
+            if (!acc.name && !acc.index)
+                return acc; // both dynamic already
+        }
+        return acc;
+    }
+    finally {
+        visiting.delete(key);
+    }
+}
+//# sourceMappingURL=plan.js.map