@texaryn/schema-json 0.3.0 → 0.4.0

package/dist/projection.js

@@ -1,3 +1,4 @@
+import { mergeNode } from 'json-schema-library';
 const VALID_TYPES = new Set([
     'string',
     'number',
@@ -13,7 +14,8 @@ function toPointer(value) {
 function escapeSegment(segment) {
     return segment.replace(/~/g, '~0').replace(/\//g, '~1');
 }
-function resolveType(schema) {
+/** The `type` the schema itself declares, and nothing else. */
+function resolveExplicitType(schema) {
     const type = schema.type;
     if (Array.isArray(type)) {
         return type.find((t) => VALID_TYPES.has(t));
@@ -23,6 +25,96 @@ function resolveType(schema) {
     }
     return undefined;
 }
+/**
+ * Keywords that apply to exactly one JSON type, grouped by that type.
+ *
+ * Two different jobs are done with these, and only one of them infers
+ * anything. Every family takes part in detecting a conflict, because a schema
+ * drawing keywords from two families implies no single shape. Only `object`
+ * and `array` are shapes a form can be given, so those are the only two ever
+ * inferred: `string` and `number` are here to be noticed, not chosen.
+ *
+ * Inferring a scalar would need a rule that is right rather than symmetrical,
+ * and there is not one. `minimum` cannot tell `number` from `integer`, and a
+ * wrong scalar guess selects the wrong widget, which is harder to notice than
+ * a field that never appeared at all.
+ *
+ * `format` is deliberately absent: it annotates a string's contents rather
+ * than describing structure, and schemas apply it to non-strings in practice.
+ */
+const KEYWORD_FAMILIES = {
+    object: [
+        'properties',
+        'patternProperties',
+        'additionalProperties',
+        'propertyNames',
+        'required',
+        'minProperties',
+        'maxProperties',
+        'dependentSchemas',
+        'dependentRequired',
+        // json-schema-library normalises draft-07 `dependencies` into the two
+        // above at parse time. Listed anyway, so the rule does not rely on that.
+        'dependencies',
+        'unevaluatedProperties',
+    ],
+    array: [
+        'items',
+        'prefixItems',
+        'additionalItems',
+        'contains',
+        'minItems',
+        'maxItems',
+        'uniqueItems',
+        'minContains',
+        'maxContains',
+        'unevaluatedItems',
+    ],
+    string: ['minLength', 'maxLength', 'pattern'],
+    number: ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf'],
+};
+/** Which families a schema draws keywords from, computed over all of them at once. */
+function projectionTypeFamilies(schema) {
+    const families = new Set();
+    for (const [family, keywords] of Object.entries(KEYWORD_FAMILIES)) {
+        if (keywords.some((keyword) => schema[keyword] !== undefined)) {
+            families.add(family);
+        }
+    }
+    return families;
+}
+/**
+ * Whether any branch of this node's `oneOf`/`anyOf` could be given a shape at
+ * all, for some value.
+ *
+ * This is what separates "the current value matches no branch" from "this
+ * composition is unrenderable whatever the value is". The first is validation's
+ * subject and transient; the second is a limitation of this adapter and worth
+ * reporting.
+ */
+function compositionHasRenderableAlternative(node) {
+    const branches = [...(node.oneOf ?? []), ...(node.anyOf ?? [])];
+    return branches.some((branch) => {
+        const resolved = dereference(branch);
+        const schema = resolved.schema;
+        if (!schema || typeof schema !== 'object')
+            return false;
+        if (resolveExplicitType(schema))
+            return true;
+        return inferProjectionShape(schema).kind === 'resolved';
+    });
+}
+function inferProjectionShape(schema) {
+    const families = projectionTypeFamilies(schema);
+    if (families.size > 1)
+        return { kind: 'ambiguous', families: [...families].sort() };
+    if (families.size === 1) {
+        const [family] = families;
+        if (family === 'object' || family === 'array')
+            return { kind: 'resolved', type: family };
+    }
+    return { kind: 'none' };
+}
 function extractConstraints(schema) {
     const constraints = {};
     if (typeof schema.minLength === 'number')
@@ -81,45 +173,244 @@ function dereference(node) {
     return node.$ref ? node.resolveRef() : node;
 }
 /**
- * Discovers every property key that could ever appear on this node, across every
- * conditional branch (if/then/else, dependentSchemas, oneOf, anyOf). draft-07
- * `dependencies` is normalized by json-schema-library into
- * `dependentSchemas`/`dependentRequired` at parse time, so it needs no separate
- * handling here.
+ * Every property key that could appear at this node's own instance location,
+ * across every branch that might apply to it.
+ *
+ * This is the static half of the inactive-node contract: a branch the data does
+ * not currently select still contributes its property pointers, which then
+ * project with `active: false`. The dynamic half is `reduceNode`, which decides
+ * which of them apply now, and the two must stay separate. Making the candidate
+ * set data-driven would delete a pointer the moment its branch stopped
+ * matching, which is exactly the flicker the contract exists to prevent.
+ *
+ * **Recursion is through applicators only, and only those acting on this same
+ * instance location**: `if`, `then`, `else`, `allOf`, `anyOf`, `oneOf`,
+ * `dependentSchemas`, and whatever a `$ref` resolves to. draft-07
+ * `dependencies` needs no separate handling, because json-schema-library
+ * normalises it into `dependentSchemas` at parse time.
+ *
+ * Three things are deliberately not followed:
  *
- * This is the "static" half of the inactive-node contract: a branch that is not
- * currently selected for the data still contributes its property pointers, just
- * with `active: false`.
+ * - **`not`**, because a subschema inside it describes a shape the instance
+ *   must *not* satisfy. Collecting its properties as candidates would invert
+ *   its meaning.
+ * - **the values of `properties`**, because those describe a child location,
+ *   not this one. `owner` is collected; the walk descends into `/owner`
+ *   separately and collects `name` there. Following it here would make `name` a
+ *   sibling of `owner`.
+ * - **`items` and `prefixItems`**, for the same reason: an array's items are
+ *   their own locations.
+ *
+ * The cycle guard keys on `schemaLocation` rather than on node identity, which
+ * was measured rather than assumed and is the opposite of what it looks like it
+ * should be: `resolveRef()` returns a fresh `SchemaNode` on every call, and the
+ * raw `schema` object it wraps is fresh too, so an identity `Set` never matches
+ * and a recursive `$ref` would not terminate. `schemaLocation` is stable, is
+ * distinct for each inline branch position, and repeats when a reference closes
+ * a cycle, which is precisely the three properties needed. The set is per call,
+ * because deduplicating a schema location is only sound while collecting names
+ * for one instance location; the same schema legitimately recurs at a deeper
+ * pointer, and `walk` visits it again there.
  */
 function collectCandidateProperties(node) {
-    const candidates = {};
-    const merge = (props) => {
-        if (!props)
+    const candidates = new Map();
+    const visited = new Set();
+    const record = (key, propNode, direct) => {
+        const entry = candidates.get(key) ?? { alternatives: [] };
+        if (direct)
+            entry.direct ??= propNode;
+        else
+            entry.alternatives.push(propNode);
+        candidates.set(key, entry);
+    };
+    const visit = (current, own) => {
+        const resolved = dereference(current);
+        // Keyed on `schemaLocation` where there is one, and on the node itself
+        // where there is not, which together cover every way the traversal can
+        // come back to where it started.
+        //
+        // Neither alone is sufficient and each covers what the other cannot. A
+        // cycle requires a `$ref`, because an inline schema cannot nest into
+        // itself, and `resolveRef()` returns a fresh `SchemaNode` on every call
+        // whose raw `schema` object is fresh too, so identity never matches across
+        // one; those nodes do carry a location. An inline branch is never resolved
+        // through a ref, so its identity is stable within one traversal.
+        //
+        // This deliberately replaced a depth cap. A cap terminates, but it does so
+        // by dropping candidates a valid schema declared, which is the silent
+        // disappearance the whole projection-diagnostic design exists to prevent:
+        // a field nested under 70 applicators is still a field.
+        const location = resolved.schemaLocation;
+        const key = typeof location === 'string' ? location : resolved;
+        if (visited.has(key))
             return;
-        for (const [key, propNode] of Object.entries(props)) {
-            if (!(key in candidates))
-                candidates[key] = propNode;
+        visited.add(key);
+        for (const [key, propNode] of Object.entries(resolved.properties ?? {})) {
+            record(key, propNode, own);
         }
-    };
-    merge(node.properties);
-    merge(node.if?.properties);
-    merge(node.then?.properties);
-    merge(node.else?.properties);
-    if (node.dependentSchemas) {
-        for (const dependency of Object.values(node.dependentSchemas)) {
+        for (const branch of [resolved.if, resolved.then, resolved.else]) {
+            if (branch)
+                visit(branch, false);
+        }
+        for (const branches of [resolved.allOf, resolved.anyOf, resolved.oneOf]) {
+            for (const branch of branches ?? [])
+                visit(branch, false);
+        }
+        for (const dependency of Object.values(resolved.dependentSchemas ?? {})) {
             if (dependency && typeof dependency === 'object') {
-                merge(dependency.properties);
+                visit(dependency, false);
             }
         }
-    }
-    for (const branch of node.allOf ?? [])
-        merge(branch.properties);
-    for (const branch of node.oneOf ?? [])
-        merge(branch.properties);
-    for (const branch of node.anyOf ?? [])
-        merge(branch.properties);
+    };
+    visit(node, true);
     return candidates;
 }
+/**
+ * The schema to project for a candidate when no branch is active.
+ *
+ * A hidden node is still compiled, so it needs some shape, and an inactive key
+ * defined differently by two branches has no single right answer. The rule is
+ * therefore stated rather than left to traversal order: the node's own
+ * declaration wins, and failing that the first branch the schema declares. It
+ * is a stable placeholder and deliberately not a claim that one branch matters
+ * more, which is why `CandidateProperty` keeps the alternatives instead of
+ * discarding them.
+ *
+ * Last of three, and only reached when no branch has claimed the location: an
+ * active branch gives `walk` the reduced node, and a provisionally selected one
+ * gives it `composeChild`, so this is consulted for neither.
+ */
+function candidatePrototype(candidate) {
+    return candidate.direct ?? candidate.alternatives[0];
+}
+/**
+ * The two statements that both apply to a child location, as one node.
+ *
+ * A selected branch beats an unselected sibling, and it does not beat the
+ * node's own unconditional declaration: in JSON Schema the two are conjunctive,
+ * so the instance has to satisfy both. Replacing in either direction is wrong,
+ * and visibly so from the form. Dropping the base constraint makes the form
+ * accept what the submission rejects. Dropping the branch's makes an unrelated
+ * limit appear from nowhere the moment the branch activates, when all the user
+ * supplied was the property that completed it.
+ *
+ * `mergeNode` is the library's own routine, the one `reduceNode` uses to fold a
+ * reducer's result into the node it is building, called here in that same order:
+ * base first, branch second, so the branch wins a keyword both sides declare.
+ * Matching it is the point. It makes the provisional projection *equal* the
+ * active projection of the same branch rather than merely resemble it, which is
+ * what a hand-written conjunction could not promise.
+ *
+ * Both sides are dereferenced first because `mergeNode` carries `$ref` over
+ * from the base, and `walk` dereferences whatever it is handed: an unresolved
+ * `$ref` on the result would resolve back to the base alone and discard the
+ * branch.
+ */
+function composeChild(base, branch) {
+    if (!base || !branch)
+        return base ?? branch;
+    return mergeNode(dereference(base), dereference(branch));
+}
+/**
+ * The `oneOf` branch the current data uniquely identifies, when the evaluator
+ * selected none.
+ *
+ * `oneOf` selects on full validity, so a branch the data plainly identifies
+ * stays unselected while one of its own required properties is absent, and
+ * hiding it leaves the user no way to supply the property that would make it
+ * apply. This picks that branch so a form can expose it, and the node it
+ * returns is reported `provisional` rather than `active`: JSON Schema still
+ * says the branch does not apply, and that fact is not this function's to
+ * overwrite.
+ *
+ * Deliberately narrow, because a form that guesses is worse than one that shows
+ * nothing:
+ *
+ * - only an explicit `const` or `enum` on a property discriminates, and both
+ *   together are conjunctive rather than alternatives
+ * - a discriminator has to be present in the data by own-property presence,
+ *   never read from a `default` annotation, since a declared default is not a
+ *   value anyone supplied
+ * - a key discriminates only if every branch constrains it, so branches that
+ *   simply differ in shape do not vote
+ * - every present discriminator has to agree on one branch
+ * - zero or several surviving branches select nothing
+ *
+ * `type` is excluded: it says almost nothing about intent when every branch is
+ * an object. `anyOf` is excluded because several of its branches may apply at
+ * once, which is a different question from which one the user means.
+ *
+ * Nothing else about a branch participates. A branch stays identified when some
+ * other constraint of its own fails, or selection would quietly become validity
+ * again and the field that completes the branch would stay hidden for a second
+ * reason.
+ */
+function selectProvisionalBranch(node, dataRecord) {
+    const branches = node.oneOf;
+    if (!branches || branches.length === 0 || dataRecord === undefined)
+        return undefined;
+    const resolvedBranches = branches.map(dereference);
+    const discriminators = [...discriminatorKeys(resolvedBranches)].filter((key) => Object.prototype.hasOwnProperty.call(dataRecord, key));
+    if (discriminators.length === 0)
+        return undefined;
+    const accepted = resolvedBranches.filter((branch) => discriminators.every((key) => branchAccepts(branch, key, dataRecord[key])));
+    return accepted.length === 1 ? accepted[0] : undefined;
+}
+/** Keys every branch constrains with `const` or `enum`. */
+function discriminatorKeys(branches) {
+    const first = branches[0];
+    if (!first)
+        return new Set();
+    const shared = new Set(Object.keys(first.schema.properties ?? {}).filter((key) => isDiscriminator(first, key)));
+    for (const branch of branches.slice(1)) {
+        for (const key of [...shared]) {
+            if (!isDiscriminator(branch, key))
+                shared.delete(key);
+        }
+    }
+    return shared;
+}
+function discriminatorSchema(branch, key) {
+    const property = branch.properties?.[key];
+    if (!property)
+        return undefined;
+    return dereference(property).schema;
+}
+function isDiscriminator(branch, key) {
+    const schema = discriminatorSchema(branch, key);
+    if (!schema)
+        return false;
+    return 'const' in schema || Array.isArray(schema.enum);
+}
+/** `const` and `enum` are separate constraints, so a value has to satisfy both. */
+function branchAccepts(branch, key, value) {
+    const schema = discriminatorSchema(branch, key);
+    if (!schema)
+        return false;
+    if ('const' in schema && !deepEqual(schema.const, value))
+        return false;
+    if (Array.isArray(schema.enum) && !schema.enum.some((member) => deepEqual(member, value))) {
+        return false;
+    }
+    return true;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((item, index) => deepEqual(item, b[index]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const left = Object.keys(a);
+        const right = Object.keys(b);
+        return (left.length === right.length &&
+            left.every((key) => Object.prototype.hasOwnProperty.call(b, key) && deepEqual(a[key], b[key])));
+    }
+    return false;
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * Computes the currently-required property keys for an object node given its data.
  *
@@ -158,35 +449,53 @@ function computeRequiredSet(resolved, reducedSchema, dataRecord) {
  * NodeProjection a form can render, with `active` reflecting whether that branch is
  * currently selected for `data`.
  */
-function walk(node, pointer, data, active, nodes) {
+function walk(node, pointer, data, active, 
+/**
+ * Whether an ancestor's provisionally selected branch exposes this node. A
+ * node is never both: `active` is what the schema says, and this is what the
+ * projection selected so the user can complete it.
+ */
+provisional, nodes, diagnostics) {
     const original = dereference(node);
     const originalSchema = original.schema;
     if (typeof originalSchema !== 'object' || originalSchema === null)
         return;
     let resolved = original;
     let schema = originalSchema;
-    let type = resolveType(schema);
+    let type = resolveExplicitType(schema);
     // Whether this node's own active branch could be determined. Stays true for every
     // node except a typeless oneOf/anyOf wrapper whose branch could not be resolved
-    // (see below) — that node's own existence in the projection is itself provisional,
-    // not just its children's.
+    // (see below), where the node's own presence in the projection is the thing in
+    // doubt rather than only its children's.
     let branchResolved = true;
     // A node whose own schema carries no `type` keyword, only `oneOf`/`anyOf` branches
     // (e.g. a property schema like `{ oneOf: [{ type: 'object', ... }, ...] }`), has no
     // type until its active branch is resolved against `data`. `original` is kept
     // separately so every branch's properties can still be collected below for the
     // inactive-node contract, even though only the matching branch's schema is used here.
+    // Whether a branch of this node's own `oneOf`/`anyOf` was resolved against
+    // `data`. Recorded so an unresolved shape can be attributed correctly below:
+    // on this path, "no shape" means the current value matches no branch, which
+    // is a fact about the data rather than about the schema.
+    let composedAgainstData = false;
+    /**
+     * Whether a typeless wrapper's branch was picked by the discriminator rather
+     * than by the evaluator. The wrapper is then shown provisionally: the schema
+     * still applies no branch, and that is what `active` reports.
+     */
+    let wrapperIdentified = false;
     if (!type && (original.oneOf || original.anyOf)) {
+        composedAgainstData = true;
         const { node: branchNode } = original.reduceNode(data);
         if (branchNode) {
             resolved = branchNode;
             schema = branchNode.schema;
-            type = resolveType(schema);
+            type = resolveExplicitType(schema);
         }
         else {
             // reduceNode() returned no node at all: this is oneOf's behavior when data
             // matches zero or multiple branches (anyOf instead returns a node with an
-            // empty merged schema in that case, which resolveType() also fails to type,
+            // empty merged schema in that case, which carries no explicit type either,
             // but which does not reach this branch). This test suite's oneOf wrappers put
             // an object schema on every branch, so 'object' is a safe stand-in type here:
             // it lets this pointer and every candidate branch property still appear in the
@@ -195,11 +504,102 @@ function walk(node, pointer, data, active, nodes) {
             // primitives (not objects) is not handled by this fallback.
             type = 'object';
             branchResolved = false;
+            // The wrapper's own branch could not be resolved, so the schema applies
+            // none of them. It may still be identifiable: a discriminator present in
+            // the data picks one, and the wrapper is then exposed provisionally
+            // rather than not at all. Without that, the same schema behaves
+            // differently for having declared `type` or not, since the typed path
+            // reaches the selector below and this one used to stop here.
+            //
+            // Only the flag is recorded, deliberately. Assigning the branch to
+            // `resolved` erases the difference between what the evaluator resolved
+            // and what this projection selected, and the object path reads `resolved`
+            // as the former: it would take the branch's `required` as active
+            // requiredness, find `nodeActive` false because no branch applies, and
+            // report the field as neither required nor provisionally required.
+            // Left alone, that path selects the same branch through
+            // `selectProvisionalBranch` and attributes it to the right one of the two.
+            //
+            // Gated on this node already being exposed, for the reason the object
+            // path is: selection is local, exposure is the ancestor's to grant.
+            wrapperIdentified =
+                (active || provisional) &&
+                    selectProvisionalBranch(original, typeof data === 'object' && data !== null ? data : undefined) !== undefined;
+        }
+    }
+    /**
+     * Whether the absence of a shape here is only the current value's fault.
+     *
+     * Two conditions, and both are needed. Nothing was merged in from a branch,
+     * which is what reducing against a value that satisfies none of them leaves
+     * behind; and some branch could have been rendered for a value that did
+     * satisfy it, so the composition is not unrenderable in itself.
+     *
+     * The first condition is what a coarser check missed. Entering the
+     * composition path says nothing on its own: a branch can be selected and
+     * still supply no shape, as `{ anyOf: [{ minLength: 1 }, { pattern: '^a' }] }`
+     * does for `"abc"`, where both branches match and neither describes anything
+     * this adapter renders, because scalar shapes are deliberately not inferred.
+     * That schema is genuinely unprojectable and has to be reported.
+     */
+    const isTransientBranchMiss = () => Object.keys(schema).length === 0 && compositionHasRenderableAlternative(original);
+    // Last resort, after the oneOf/anyOf branch above has had its chance: that
+    // path handles a typeless wrapper whose type only exists once a branch is
+    // chosen, and inferring first would take a schema carrying both `properties`
+    // and `oneOf` down the object path without ever resolving its branch.
+    if (!type) {
+        const shape = inferProjectionShape(schema);
+        if (shape.kind === 'resolved') {
+            type = shape.type;
+        }
+        else if (shape.kind === 'none' && composedAgainstData && isTransientBranchMiss()) {
+            // Deliberately silent, and only for this one case. A projection
+            // diagnostic describes a schema this adapter cannot turn into a shape,
+            // and a value that matches none of a composition's branches is not that:
+            // the same schema renders for a value that does match one. That is
+            // validation's subject, it is already reported there, and a form's data
+            // is in this state for most of the time someone is filling it in, so a
+            // diagnostic here would appear and disappear on each keystroke and train
+            // a caller to ignore the channel.
+        }
+        else {
+            // Reported rather than dropped in silence. The field cannot be drawn
+            // without a shape, so the caller is told which pointer was skipped and
+            // why, instead of finding out from a form that never collected the
+            // value.
+            diagnostics.push(shape.kind === 'ambiguous'
+                ? {
+                    pointer: toPointer(pointer),
+                    code: 'ambiguous-projection-shape',
+                    message: `No explicit "type", and keywords from more than one type apply ` +
+                        `(${shape.families.join(', ')}), so the shape to render is undecidable. ` +
+                        `Declare "type" on this schema to resolve it.`,
+                }
+                : {
+                    pointer: toPointer(pointer),
+                    code: 'unresolved-projection-shape',
+                    message: `No explicit "type", and no keyword that implies one, so there is no ` +
+                        `shape to render. Declare "type" on this schema.` +
+                        // Said only where it applies, because inferring `string` from
+                        // an enum is the tempting wrong rule and the reason deserves
+                        // to travel with the case rather than every message.
+                        (schema.enum !== undefined
+                            ? ` An "enum" alone does not imply a type, because its members may be of different types.`
+                            : ''),
+                });
         }
     }
     if (!type)
         return;
     const nodeActive = active && branchResolved;
+    // A node the schema applies is never also provisional; the two report
+    // different facts and only the second is a choice this projection made. The
+    // `!nodeActive` term is belt and braces: `provisional` only ever arrives true
+    // from a parent that computed `!childActive`, so no caller can reach here
+    // with both, and dropping the term changes no observable behaviour.
+    const nodeProvisional = !nodeActive && (provisional || wrapperIdentified) && (branchResolved || wrapperIdentified);
+    // Whether a form shows this node at all, which is what a descendant inherits.
+    const nodeExposed = nodeActive || nodeProvisional;
     if (type === 'object') {
         const dataRecord = typeof data === 'object' && data !== null ? data : undefined;
         // reduceNode() resolves if/then/else, dependentSchemas (which also covers
@@ -222,17 +622,45 @@ function walk(node, pointer, data, active, nodes) {
             {};
         const activeKeys = new Set(Object.keys(reducedProperties));
         const requiredSet = computeRequiredSet(resolved, reducedSchema, dataRecord);
+        // Two conditions, and they are not the same kind of condition.
+        //
+        // Exposure is load-bearing. Selection is local, but whether this node is
+        // shown at all is its ancestors' to decide, and a subtree nothing exposes
+        // must not select a branch off data it happens to retain: the compiler
+        // collapses `required || provisionalRequired` into the one flag a binding
+        // reads, so a hidden field would acquire a requirement.
+        //
+        // The evaluator having selected nothing is where provisional selection
+        // exists to help, and that half is unobservable rather than wrong: a
+        // resolved branch is fully valid, so it accepts every present discriminator
+        // and the selector would return that same branch, whose keys are already
+        // the active set. Kept because doing the work is pointless and the
+        // condition states the intent.
+        const provisionalBranch = nodeExposed && reducedNode === undefined
+            ? selectProvisionalBranch(original, dataRecord)
+            : undefined;
+        const provisionalSchema = provisionalBranch?.schema;
+        const provisionalKeys = new Set(Object.keys(provisionalSchema?.properties ?? {}));
+        const provisionalRequired = new Set(Array.isArray(provisionalSchema?.required) ? provisionalSchema.required : []);
         // Candidates are collected from `original`, not `resolved`, so every oneOf/anyOf
         // branch's properties are represented (the matching branch alone, via `resolved`,
         // would only expose its own properties).
         const candidateProps = collectCandidateProperties(original);
-        const propKeys = Object.keys(candidateProps);
+        const propKeys = [...candidateProps.keys()];
         const children = propKeys.length > 0
-            ? propKeys.map((key) => ({
-                pointer: toPointer(`${pointer}/${escapeSegment(key)}`),
-                key,
-                required: requiredSet.has(key),
-            }))
+            ? propKeys.map((key) => {
+                // Gated on the node applying at all. A branch that does not apply
+                // demands nothing, so reporting its `required` array as a
+                // requirement would attribute to the validator something it is not
+                // asking for.
+                const required = nodeActive && requiredSet.has(key);
+                return {
+                    pointer: toPointer(`${pointer}/${escapeSegment(key)}`),
+                    key,
+                    required,
+                    provisionalRequired: !required && provisionalRequired.has(key) ? true : undefined,
+                };
+            })
             : undefined;
         nodes.set(toPointer(pointer), {
             type,
@@ -241,14 +669,33 @@ function walk(node, pointer, data, active, nodes) {
             children,
             enumValues: extractEnumValues(schema),
             active: nodeActive,
+            provisional: nodeProvisional ? true : undefined,
             annotations: extractAnnotations(schema),
         });
         for (const key of propKeys) {
             const childPointer = `${pointer}/${escapeSegment(key)}`;
             const childActive = nodeActive && activeKeys.has(key);
+            // A descendant inherits exposure, not activity: under a provisionally
+            // selected ancestor its own locally applicable properties are
+            // provisional too, while a locally inactive one stays inactive.
+            const childProvisional = !childActive && nodeExposed && (activeKeys.has(key) || provisionalKeys.has(key));
             const reducedChildNode = reducedNode?.properties?.[key];
-            const childNode = reducedChildNode ?? candidateProps[key];
-            walk(childNode, childPointer, dataRecord?.[key], childActive, nodes);
+            // Precedence matters as much as the selection does. Marking the right
+            // branch provisional while taking its shape from `candidatePrototype`,
+            // which is first-wins across branches, would render another branch's
+            // widget and annotations under the selected branch's name, and would hand
+            // ADR-003's pass another branch's `default`.
+            const provisionalChildNode = provisionalBranch?.properties?.[key];
+            const candidate = candidateProps.get(key);
+            // Three states, in order of authority. What the evaluator reduced against
+            // the data is the schema as it actually applies. Failing that, the node's
+            // own declaration composed with the selected branch, which is what the
+            // reduction would have produced had the branch been complete. Failing
+            // both, a stated placeholder for a location no branch has claimed.
+            const childNode = reducedChildNode ??
+                composeChild(candidate.direct, provisionalChildNode) ??
+                candidatePrototype(candidate);
+            walk(childNode, childPointer, dataRecord?.[key], childActive, childProvisional, nodes, diagnostics);
         }
         return;
     }
@@ -259,6 +706,7 @@ function walk(node, pointer, data, active, nodes) {
         children: undefined,
         enumValues: extractEnumValues(schema),
         active: nodeActive,
+        provisional: nodeProvisional ? true : undefined,
         annotations: extractAnnotations(schema),
         itemAnnotations: type === 'array' && resolved.items
             ? extractAnnotations(dereference(resolved.items).schema)
@@ -266,7 +714,7 @@ function walk(node, pointer, data, active, nodes) {
     });
     if (type === 'array' && resolved.items && Array.isArray(data)) {
         data.forEach((item, index) => {
-            walk(resolved.items, `${pointer}/${index}`, item, nodeActive, nodes);
+            walk(resolved.items, `${pointer}/${index}`, item, nodeActive, nodeProvisional, nodes, diagnostics);
         });
     }
 }
@@ -282,7 +730,8 @@ function walk(node, pointer, data, active, nodes) {
  */
 export function buildProjection(root, data) {
     const nodes = new Map();
-    walk(root, '', data, true, nodes);
-    return { nodes };
+    const diagnostics = [];
+    walk(root, '', data, true, false, nodes, diagnostics);
+    return { nodes, diagnostics };
 }
 //# sourceMappingURL=projection.js.map