ng-form-foundry-transformers 0.5.0 → 0.5.2

package/dist/transformers/json/json-transformer.js

@@ -5,18 +5,24 @@ const thesaurus_1 = require("../../core/thesaurus");
 const infer_1 = require("../../core/infer");
 const json_schema_1 = require("../../core/json-schema");
 const bigint_1 = require("../../core/bigint");
+const schema_keys_1 = require("../../core/schema-keys");
+const merge_inferred_1 = require("../../core/merge-inferred");
+const shape_check_1 = require("../../core/shape-check");
 /**
  * A JSON {@link Transformer}: turn a JSON config document into a form and write
  * the edited value back to JSON. The form is built by the same format-agnostic
  * `core` builders the YAML transformer uses — only parsing (`JSON.parse`) and
  * serialization (`JSON.stringify`) are JSON-specific.
  *
- * Standard JSON has no comments, so revert re-serializes the edited value,
- * preserving the source's indent width and trailing newline. Key order follows
- * the form value (which follows the schema, derived from the original), so it is
- * preserved for untouched keys. For JSON **with comments** (JSONC), parse and
- * edit it as YAML with {@link import('../yaml/yaml-transformer').yamlTransformer}
- * instead — `JSON.parse` rejects comments.
+ * Standard JSON has no comments, so revert re-serializes, preserving the
+ * source's indent width and trailing newline. In schema-driven mode with
+ * `unknownKeys: 'preserve'` or `'edit'` the value is merged over the original
+ * data at schema-born paths ({@link mergeSchemaBorn}), so uncovered keys and
+ * the original key order survive; otherwise the edited value is serialized
+ * as-is, key order following the form value. For JSON **with comments**
+ * (JSONC), parse and edit it as YAML with
+ * {@link import('../yaml/yaml-transformer').yamlTransformer} instead —
+ * `JSON.parse` rejects comments.
  *
  * Integers beyond 2^53 can't survive a `number` round-trip, so they are carried
  * as strings in the form value and re-emitted verbatim as unquoted numbers (the
@@ -28,26 +34,84 @@ exports.jsonTransformer = {
         const bigInts = [];
         const parsed = JSON.parse(source, bigIntReviver);
         const data = collectBigInts(parsed ?? {}, [], bigInts);
-        const schema = options?.schema
+        const unknownKeys = options?.unknownKeys ?? 'preserve';
+        const fromJsonSchema = options?.schema
             ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
-            : (0, infer_1.inferNodeGroup)(data, options?.rootName);
+            : undefined;
+        const schema = fromJsonSchema && unknownKeys === 'edit'
+            ? (0, merge_inferred_1.mergeInferred)(fromJsonSchema, (0, infer_1.inferNodeGroup)(data, options?.rootName))
+            : fromJsonSchema ?? (0, infer_1.inferNodeGroup)(data, options?.rootName);
+        // A container-shape disagreement between document and schema would erase
+        // the section on save: refuse up front (see assertSchemaShapes).
+        if (fromJsonSchema)
+            (0, shape_check_1.assertSchemaShapes)(data, fromJsonSchema);
         const labeled = options?.thesaurus ? (0, thesaurus_1.applyThesaurus)(schema, options.thesaurus) : schema;
+        // 'preserve' gates the revert on the JSON Schema's NodeGroup; 'edit' on
+        // the merged one (schema-born ≈ everything, but keys no form field can
+        // carry stay protected); 'drop' and inferred mode leave the value
+        // authoritative for the whole document.
+        const preserveUnknown = fromJsonSchema != null && unknownKeys !== 'drop';
         const binding = {
             indent: detectIndent(source),
             trailingNewline: source.endsWith('\n'),
             bigInts,
+            original: preserveUnknown ? data : undefined,
+            schema: preserveUnknown ? schema : undefined,
         };
         return { schema: labeled, binding, initialValue: data };
     },
     toSource(value, binding) {
+        const merged = binding.schema && binding.original !== undefined
+            ? mergeSchemaBorn(binding.original, value, (0, schema_keys_1.childrenOf)(binding.schema))
+            : value;
         const paths = new Set(binding.bigInts);
-        const prepared = paths.size ? markBigInts(value, [], paths) : value;
+        const prepared = paths.size ? markBigInts(merged, [], paths) : merged;
         let text = JSON.stringify(prepared, null, binding.indent);
         if (paths.size)
             text = text.replace(BIGINT_MARK_RE, '$1');
         return binding.trailingNewline ? text + '\n' : text;
     },
 };
+/**
+ * Merge the edited value over the original data, value-authoritative for
+ * schema-born keys only: an uncovered key keeps its original value and its
+ * position in the key order; a covered key takes the edited value (recursing
+ * where both sides are objects, and per index into arrays of groups); a
+ * covered key absent from the value is omitted (a presence toggle off);
+ * covered keys new to the document append after the originals.
+ */
+function mergeSchemaBorn(original, value, schema) {
+    if (!isPlainObject(original) || !isPlainObject(value) || !schema)
+        return value;
+    // Null-prototype output and own-key checks: document keys are arbitrary, so
+    // `__proto__` must stay a data key and `toString`/`constructor` must not
+    // resolve through the prototype chain (which would drop or fabricate keys).
+    const out = Object.create(null);
+    for (const key of Object.keys(original)) {
+        if (!schema.has(key)) {
+            out[key] = original[key]; // not schema-born: verbatim, in place
+        }
+        else if (hasOwn(value, key)) {
+            out[key] = mergeChild(original[key], value[key], schema.get(key));
+        } // covered + absent: deleted
+    }
+    for (const key of Object.keys(value)) {
+        if (!(key in out) && !hasOwn(original, key) && schema.has(key))
+            out[key] = value[key];
+    }
+    return out;
+}
+/** Per-key recursion: objects merge by their child schema, group arrays per index. */
+function mergeChild(original, value, schema) {
+    if (schema && isPlainObject(original) && isPlainObject(value)) {
+        return mergeSchemaBorn(original, value, (0, schema_keys_1.childrenOf)(schema));
+    }
+    const itemSchema = (0, schema_keys_1.itemSchemaOf)(schema);
+    if (itemSchema && Array.isArray(original) && Array.isArray(value)) {
+        return value.map((item, i) => i < original.length ? mergeChild(original[i], item, itemSchema) : item);
+    }
+    return value;
+}
 /** Indent width (in spaces) of the first indented line, or 2 if none/tabs. */
 function detectIndent(source) {
     const match = source.match(/\n( +)\S/);
@@ -102,7 +166,8 @@ function collectBigInts(node, path, out) {
     if (Array.isArray(node))
         return node.map((v, i) => collectBigInts(v, [...path, i], out));
     if (isPlainObject(node)) {
-        const res = {};
+        // Null prototype: a `__proto__` document key must stay a data key.
+        const res = Object.create(null);
         for (const key of Object.keys(node))
             res[key] = collectBigInts(node[key], [...path, key], out);
         return res;
@@ -121,7 +186,7 @@ function markBigInts(node, path, paths) {
     if (Array.isArray(node))
         return node.map((v, i) => markBigInts(v, [...path, i], paths));
     if (isPlainObject(node)) {
-        const res = {};
+        const res = Object.create(null);
         for (const key of Object.keys(node))
             res[key] = markBigInts(node[key], [...path, key], paths);
         return res;
@@ -131,3 +196,7 @@ function markBigInts(node, path, paths) {
 function isPlainObject(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
+/** Own-key membership, immune to `Object.prototype` members and null-prototype objects. */
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}

package/dist/transformers/libconfig/index.d.ts

@@ -1,2 +1,3 @@
 export { libconfigTransformer, type LibconfigBinding, type LibconfigOptions, } from './libconfig-transformer';
 export { parseLibconfig, LibconfigParseError } from './parser';
+export { SchemaShapeError } from '../../core/shape-check';

package/dist/transformers/libconfig/index.js

@@ -1,8 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LibconfigParseError = exports.parseLibconfig = exports.libconfigTransformer = void 0;
+exports.SchemaShapeError = exports.LibconfigParseError = exports.parseLibconfig = exports.libconfigTransformer = void 0;
 var libconfig_transformer_1 = require("./libconfig-transformer");
 Object.defineProperty(exports, "libconfigTransformer", { enumerable: true, get: function () { return libconfig_transformer_1.libconfigTransformer; } });
 var parser_1 = require("./parser");
 Object.defineProperty(exports, "parseLibconfig", { enumerable: true, get: function () { return parser_1.parseLibconfig; } });
 Object.defineProperty(exports, "LibconfigParseError", { enumerable: true, get: function () { return parser_1.LibconfigParseError; } });
+// Thrown by schema-driven toSchema; re-exported so browser consumers of this
+// subpath can catch it by instance.
+var shape_check_1 = require("../../core/shape-check");
+Object.defineProperty(exports, "SchemaShapeError", { enumerable: true, get: function () { return shape_check_1.SchemaShapeError; } });

package/dist/transformers/libconfig/libconfig-transformer.d.ts

@@ -12,7 +12,7 @@
  * are then shown read-only. A JSON Schema in the options unlocks typed empty
  * collections, presence toggles for optional settings, enums, and ranges.
  */
-import type { FormValue, Thesaurus } from '../../core/schema';
+import type { FormValue, NodeGroup, Thesaurus } from '../../core/schema';
 import type { TransformResult } from '../../core/transformer';
 import { type JsonSchema, type JsonSchemaOptions } from '../../core/json-schema';
 import { type CfgGroup } from './parser';
@@ -34,6 +34,20 @@ export interface LibconfigOptions {
      * line verbatim and edits only this file's own settings.
      */
     includes?: 'reject' | 'opaque';
+    /**
+     * Schema-driven mode only: what happens to settings the JSON Schema does
+     * not cover. `'preserve'` (default) keeps them byte-verbatim in place —
+     * the form never carried them, so a partial schema edits its slice without
+     * erasing the rest. `'drop'` makes the edited value authoritative for the
+     * whole document, deleting uncovered settings — for consumers whose schema
+     * is intentionally complete (sanitizing a config, enforcing a strict
+     * template). `'edit'` surfaces them instead: uncovered settings render as
+     * editable fields typed by the document's own literals (the inferred
+     * schema merged under the JSON Schema — see `mergeInferred`), so nothing
+     * is invisible and the value covers the whole document. Ignored without a
+     * `schema`, where the inferred value covers every setting anyway.
+     */
+    unknownKeys?: 'preserve' | 'drop' | 'edit';
     /**
      * Display metadata (`label`/`description`/choice `caseLabels`) injected into
      * the produced schema, schema-driven or inferred alike — see
@@ -42,10 +56,22 @@ export interface LibconfigOptions {
      */
     thesaurus?: Thesaurus;
 }
-/** The revert context: the original text and its positioned AST. */
+/**
+ * The revert context: the original text, its positioned AST, and — in
+ * schema-driven mode with `unknownKeys: 'preserve'` or `'edit'` — the
+ * NodeGroup the form was built from (the JSON Schema's own under
+ * `'preserve'`, the inferred-merged one under `'edit'`), so `toSource` knows
+ * which paths are schema-born. Settings outside those paths were never
+ * carried by the form and survive verbatim; under `'edit'` that is only the
+ * keys no form field can carry (e.g. a key inside a covered choice's group
+ * that no case names). Absent `schema` (inferred mode, or
+ * `unknownKeys: 'drop'`), the value covers the whole document and is
+ * authoritative everywhere.
+ */
 export interface LibconfigBinding {
     source: string;
     root: CfgGroup;
+    schema?: NodeGroup;
 }
 export declare const libconfigTransformer: {
     id: string;

package/dist/transformers/libconfig/libconfig-transformer.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.libconfigTransformer = void 0;
 const thesaurus_1 = require("../../core/thesaurus");
 const json_schema_1 = require("../../core/json-schema");
+const merge_inferred_1 = require("../../core/merge-inferred");
+const schema_keys_1 = require("../../core/schema-keys");
+const shape_check_1 = require("../../core/shape-check");
 const parser_1 = require("./parser");
 const schema_1 = require("./schema");
 const revert_1 = require("./revert");
@@ -10,14 +13,44 @@ exports.libconfigTransformer = {
     id: 'libconfig',
     toSchema(source, options) {
         const root = (0, parser_1.parseLibconfig)(source, { includes: options?.includes });
-        const schema = options?.schema
+        const unknownKeys = options?.unknownKeys ?? 'preserve';
+        const fromJsonSchema = options?.schema
             ? (0, json_schema_1.jsonSchemaToNodeGroup)(options.schema, options.rootName, options.schemaOptions)
-            : (0, schema_1.libconfigToNodeGroup)(root, source, options?.rootName ?? '__root__');
+            : undefined;
+        const schema = fromJsonSchema && unknownKeys === 'edit'
+            ? (0, merge_inferred_1.mergeInferred)(fromJsonSchema, (0, schema_1.libconfigToNodeGroup)(root, source, options?.rootName ?? '__root__'))
+            : fromJsonSchema ?? (0, schema_1.libconfigToNodeGroup)(root, source, options?.rootName ?? '__root__');
+        // Schema-driven leaves display in the base the document wrote them in —
+        // the JSON Schema cannot know it, the document does (see annotateSchemaRadix).
+        if (fromJsonSchema)
+            (0, schema_1.annotateSchemaRadix)(root, schema);
         const labeled = options?.thesaurus ? (0, thesaurus_1.applyThesaurus)(schema, options.thesaurus) : schema;
         const initialValue = (0, schema_1.extractValue)(root, source, options?.schema != null);
-        return { schema: labeled, binding: { source, root }, initialValue };
+        // A container-shape disagreement (group vs list vs scalar) produces a
+        // form that cannot carry the section and would erase it on save: refuse
+        // up front so the consumer can fall back to inferred editing.
+        if (fromJsonSchema)
+            (0, shape_check_1.assertSchemaShapes)(initialValue, fromJsonSchema);
+        if (fromJsonSchema && unknownKeys === 'edit') {
+            // Uncovered empty collections merged as read-only carries: their value
+            // must be the verbatim slice, not the typed [] the extraction produced.
+            (0, schema_1.carryUncoveredEmpties)(root, source, initialValue, (0, schema_keys_1.childrenOf)(fromJsonSchema));
+        }
+        return {
+            schema: labeled,
+            binding: {
+                source,
+                root,
+                // 'preserve' gates the revert on the JSON Schema's NodeGroup; 'edit'
+                // on the merged one (schema-born ≈ everything, but settings no form
+                // field can carry stay protected); 'drop' and inferred mode leave
+                // the value authoritative for the whole document.
+                schema: fromJsonSchema && unknownKeys !== 'drop' ? schema : undefined,
+            },
+            initialValue,
+        };
     },
     toSource(value, binding) {
-        return (0, revert_1.applyValueToSource)(binding.source, binding.root, value);
+        return (0, revert_1.applyValueToSource)(binding.source, binding.root, value, binding.schema);
     },
 };

package/dist/transformers/libconfig/revert.d.ts

@@ -13,6 +13,18 @@
  * literal re-emits in hex at its original digit width, an int64 keeps its
  * `L`/`LL` suffix, and values beyond 2^53 travel as exact decimal strings.
  */
+import type { NodeGroup } from '../../core/schema';
 import type { CfgGroup } from './parser';
-/** Apply `value` onto the parsed `root` of `source`, returning the new text. */
-export declare function applyValueToSource(source: string, root: CfgGroup, value: Record<string, unknown>): string;
+/**
+ * Apply `value` onto the parsed `root` of `source`, returning the new text.
+ *
+ * Without `schema` (inferred mode) the value is authoritative for the whole
+ * document: it was extracted from every setting, so a key it lacks is a
+ * deletion. With `schema` (the NodeGroup the form was built from) the value
+ * is authoritative for **schema-born paths only** — the form never carried
+ * the other settings, so they survive byte-verbatim in their original
+ * positions. A partial schema thus edits its slice of an OAI/srsRAN config
+ * without erasing keys the schema does not enumerate; absence of a
+ * schema-born key still deletes (a presence toggle turned off).
+ */
+export declare function applyValueToSource(source: string, root: CfgGroup, value: Record<string, unknown>, schema?: NodeGroup): string;

package/dist/transformers/libconfig/revert.js

@@ -1,33 +1,50 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyValueToSource = applyValueToSource;
+const schema_keys_1 = require("../../core/schema-keys");
 const schema_1 = require("./schema");
-/** Apply `value` onto the parsed `root` of `source`, returning the new text. */
-function applyValueToSource(source, root, value) {
+/**
+ * Apply `value` onto the parsed `root` of `source`, returning the new text.
+ *
+ * Without `schema` (inferred mode) the value is authoritative for the whole
+ * document: it was extracted from every setting, so a key it lacks is a
+ * deletion. With `schema` (the NodeGroup the form was built from) the value
+ * is authoritative for **schema-born paths only** — the form never carried
+ * the other settings, so they survive byte-verbatim in their original
+ * positions. A partial schema thus edits its slice of an OAI/srsRAN config
+ * without erasing keys the schema does not enumerate; absence of a
+ * schema-born key still deletes (a presence toggle turned off).
+ */
+function applyValueToSource(source, root, value, schema) {
     const edits = [];
-    patchGroup(source, root, value, edits);
+    patchGroup(source, root, value, edits, schema && (0, schema_keys_1.childrenOf)(schema));
     edits.sort((a, b) => b.start - a.start);
     let out = source;
     for (const e of edits)
         out = out.slice(0, e.start) + e.text + out.slice(e.end);
     return out;
 }
-function patchGroup(src, group, value, edits) {
+function patchGroup(src, group, value, edits, schema) {
     for (const setting of group.settings) {
-        if (!value || !(setting.name in value)) {
+        if (schema && !schema.has(setting.name))
+            continue; // not schema-born: verbatim
+        // Own-key check: `in` would resolve setting names like `toString` through
+        // the prototype chain, making them undeletable (and their "value" a function).
+        if (!value || !Object.prototype.hasOwnProperty.call(value, setting.name)) {
             edits.push(deleteSetting(src, setting));
             continue;
         }
-        patchValue(src, setting.value, value[setting.name], edits);
+        patchValue(src, setting.value, value[setting.name], edits, schema?.get(setting.name));
     }
     const known = new Set(group.settings.map((s) => s.name));
-    // null/undefined means "absent", never a value: such keys are not added.
-    const added = Object.keys(value ?? {}).filter((k) => !known.has(k) && value[k] != null);
+    // null/undefined means "absent", never a value: such keys are not added —
+    // and under a schema, only schema-born keys may be added at all.
+    const added = Object.keys(value ?? {}).filter((k) => !known.has(k) && value[k] != null && (!schema || schema.has(k)));
     if (added.length) {
         edits.push(insertionEdit(src, group, added.map((k) => `${k} = ${serialize(value[k], '')};`)));
     }
 }
-function patchValue(src, node, value, edits) {
+function patchValue(src, node, value, edits, schema) {
     switch (node.kind) {
         case 'scalar': {
             if (node.value === value)
@@ -41,7 +58,7 @@ function patchValue(src, node, value, edits) {
         }
         case 'group': {
             if (isRecord(value))
-                return patchGroup(src, node, value, edits);
+                return patchGroup(src, node, value, edits, schema && (0, schema_keys_1.childrenOf)(schema));
             edits.push({ ...node.span, text: serialize(value, '') }); // shape change: regenerate
             return;
         }
@@ -61,7 +78,7 @@ function patchValue(src, node, value, edits) {
         case 'list': {
             const shape = (0, schema_1.listShape)(node);
             if (shape === 'groups' && Array.isArray(value)) {
-                return patchElements(src, node.elements, node, value, edits);
+                return patchElements(src, node.elements, node, value, edits, (0, schema_keys_1.itemSchemaOf)(schema));
             }
             if (shape === 'scalars' && Array.isArray(value)) {
                 return patchElements(src, node.elements, node, value, edits);
@@ -89,10 +106,10 @@ function patchValue(src, node, value, edits) {
     }
 }
 /** Element-wise patch of an array/list: edit in place, then grow or shrink. */
-function patchElements(src, elements, collection, value, edits) {
+function patchElements(src, elements, collection, value, edits, itemSchema) {
     const shared = Math.min(elements.length, value.length);
     for (let i = 0; i < shared; i++)
-        patchValue(src, elements[i], value[i], edits);
+        patchValue(src, elements[i], value[i], edits, itemSchema);
     if (value.length > elements.length) {
         const items = value.slice(elements.length).map((v) => serialize(v, ''));
         const at = elements.length ? elements[elements.length - 1].span.end : collection.innerSpan.start;
@@ -180,7 +197,10 @@ function emitScalar(value, node) {
         if ((node.type === 'int' || node.type === 'int64') && Number.isInteger(value)) {
             return intLiteral(value, node.int);
         }
-        return floatLiteral(value); // a fractional edit into an int slot: emit honestly
+        // A type-changing edit (e.g. a quoted "0xe00" slot edited to a number
+        // under an integer schema): integral values emit an int literal —
+        // float form is reserved for genuinely fractional values.
+        return Number.isInteger(value) ? String(value) : floatLiteral(value);
     }
     return serialize(value, '');
 }

package/dist/transformers/libconfig/schema.d.ts

@@ -18,7 +18,8 @@
  *   transformer options) replaces this inference entirely and makes typed
  *   empty collections editable.
  */
-import type { NodeGroup } from '../../core/schema';
+import type { NodeGroup, NodeType } from '../../core/schema';
+import { type SchemaKeys } from '../../core/schema-keys';
 import { type CfgGroup, type CfgList, type CfgValue } from './parser';
 /** Infer the root NodeGroup for a parsed document. */
 export declare function libconfigToNodeGroup(root: CfgGroup, source: string, name: string): NodeGroup;
@@ -36,4 +37,27 @@ type ListShape = 'groups' | 'scalars' | 'empty' | 'heterogeneous';
 export declare function listShape(list: CfgList): ListShape;
 /** The verbatim source slice of a node. */
 export declare function raw(value: CfgValue, source: string): string;
+/**
+ * Stamp the document's non-decimal integer presentation onto a
+ * **schema-driven** NodeGroup as `radix` display hints — the JSON Schema has
+ * no radix vocabulary, so the document is the only authority on how a value
+ * is written. Covered number/string leaves whose literal is hex/octal/binary
+ * (and homogeneous collections thereof) display in that base in every
+ * `unknownKeys` mode, matching what inference does for uncovered fields.
+ * Fills gaps only: a `radix` already on the leaf (e.g. carried by
+ * `mergeInferred` under `'edit'`) wins. Keyed containers — groups, choices,
+ * maps — resolve through {@link childrenOf}, so case fields and map entries
+ * annotate too.
+ */
+export declare function annotateSchemaRadix(node: CfgValue, schema: NodeType): void;
+/**
+ * `unknownKeys: 'edit'` extraction fixup. The whole-document extraction runs
+ * with `emptyAsArrays` (schema-covered empty collections are typed and
+ * editable), but collections the JSON Schema does **not** cover merge as
+ * read-only raw-carry leaves — their value must be the verbatim source
+ * slice, not `[]`. Walks the document alongside the original (pre-merge)
+ * schema coverage and restores the carry on every uncovered empty
+ * collection, at any depth.
+ */
+export declare function carryUncoveredEmpties(group: CfgGroup, source: string, value: unknown, keys: SchemaKeys): void;
 export {};

package/dist/transformers/libconfig/schema.js

@@ -4,6 +4,9 @@ exports.libconfigToNodeGroup = libconfigToNodeGroup;
 exports.extractValue = extractValue;
 exports.listShape = listShape;
 exports.raw = raw;
+exports.annotateSchemaRadix = annotateSchemaRadix;
+exports.carryUncoveredEmpties = carryUncoveredEmpties;
+const schema_keys_1 = require("../../core/schema-keys");
 const parser_1 = require("./parser");
 /** Digits only — the constraint for int64 values carried as strings. */
 const INTEGER_STRING_PATTERN = '^[-+]?[0-9]+$';
@@ -184,3 +187,118 @@ function rawLeaf(name, why) {
 function raw(value, source) {
     return source.slice(value.span.start, value.span.end);
 }
+/**
+ * Stamp the document's non-decimal integer presentation onto a
+ * **schema-driven** NodeGroup as `radix` display hints — the JSON Schema has
+ * no radix vocabulary, so the document is the only authority on how a value
+ * is written. Covered number/string leaves whose literal is hex/octal/binary
+ * (and homogeneous collections thereof) display in that base in every
+ * `unknownKeys` mode, matching what inference does for uncovered fields.
+ * Fills gaps only: a `radix` already on the leaf (e.g. carried by
+ * `mergeInferred` under `'edit'`) wins. Keyed containers — groups, choices,
+ * maps — resolve through {@link childrenOf}, so case fields and map entries
+ * annotate too.
+ */
+function annotateSchemaRadix(node, schema) {
+    switch (schema.kind) {
+        case 'leaf': {
+            // Only number/string leaves render radix; a boolean/enum leaf covering
+            // an int literal is a scalar-type mismatch the form handles otherwise.
+            if (schema.type !== 'number' && schema.type !== 'string')
+                return;
+            if (node.kind === 'scalar' && node.int && node.int.radix !== 10 && !schema.radix) {
+                schema.radix = node.int.radix;
+            }
+            return;
+        }
+        case 'leafList': {
+            if (schema.radix)
+                return;
+            if ((node.kind === 'array' || node.kind === 'list') && node.elements.every((e) => e.kind === 'scalar')) {
+                const radix = sharedRadix(node.elements);
+                if (radix)
+                    schema.radix = radix;
+            }
+            return;
+        }
+        case 'nodeGroupList': {
+            if (node.kind !== 'list')
+                return;
+            for (const el of node.elements)
+                annotateSchemaRadix(el, schema.type);
+            return;
+        }
+        default: {
+            // nodeGroup / choice / map — keyed containers over a document group.
+            if (node.kind !== 'group')
+                return;
+            const keys = (0, schema_keys_1.childrenOf)(schema);
+            if (!keys)
+                return;
+            for (const setting of node.settings) {
+                const child = keys.get(setting.name);
+                if (child)
+                    annotateSchemaRadix(setting.value, child);
+            }
+            return;
+        }
+    }
+}
+/**
+ * `unknownKeys: 'edit'` extraction fixup. The whole-document extraction runs
+ * with `emptyAsArrays` (schema-covered empty collections are typed and
+ * editable), but collections the JSON Schema does **not** cover merge as
+ * read-only raw-carry leaves — their value must be the verbatim source
+ * slice, not `[]`. Walks the document alongside the original (pre-merge)
+ * schema coverage and restores the carry on every uncovered empty
+ * collection, at any depth.
+ */
+function carryUncoveredEmpties(group, source, value, keys) {
+    if (!isRecord(value))
+        return;
+    for (const setting of group.settings) {
+        if (keys && !keys.has(setting.name)) {
+            restoreEmptyCarries(setting.value, source, value, setting.name);
+            continue;
+        }
+        const child = keys?.get(setting.name);
+        const v = value[setting.name];
+        if (setting.value.kind === 'group' && child) {
+            carryUncoveredEmpties(setting.value, source, v, (0, schema_keys_1.childrenOf)(child));
+        }
+        else if (setting.value.kind === 'list' && Array.isArray(v)) {
+            const itemSchema = (0, schema_keys_1.itemSchemaOf)(child);
+            if (!itemSchema)
+                continue;
+            const itemKeys = (0, schema_keys_1.childrenOf)(itemSchema);
+            setting.value.elements.forEach((el, i) => {
+                if (el.kind === 'group')
+                    carryUncoveredEmpties(el, source, v[i], itemKeys);
+            });
+        }
+    }
+}
+/** In a fully uncovered subtree, every empty collection reverts to its carry. */
+function restoreEmptyCarries(node, source, parent, key) {
+    if ((node.kind === 'array' || node.kind === 'list') && node.elements.length === 0) {
+        parent[key] = raw(node, source);
+        return;
+    }
+    if (node.kind === 'group') {
+        const v = parent[key];
+        if (!isRecord(v))
+            return;
+        for (const s of node.settings)
+            restoreEmptyCarries(s.value, source, v, s.name);
+        return;
+    }
+    if (node.kind === 'list') {
+        const v = parent[key];
+        if (!Array.isArray(v))
+            return;
+        node.elements.forEach((el, i) => restoreEmptyCarries(el, source, v, i));
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist/transformers/yaml/index.d.ts

@@ -7,5 +7,6 @@
  * `core` — they are format-agnostic and shared with the JSON transformer.
  */
 export { yamlTransformer } from './yaml-transformer';
-export type { YamlOptions } from './yaml-transformer';
+export type { YamlOptions, YamlBinding } from './yaml-transformer';
 export { applyValueToDocument } from './revert';
+export { SchemaShapeError } from '../../core/shape-check';

package/dist/transformers/yaml/index.js

@@ -8,8 +8,12 @@
  * `core` — they are format-agnostic and shared with the JSON transformer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyValueToDocument = exports.yamlTransformer = void 0;
+exports.SchemaShapeError = exports.applyValueToDocument = exports.yamlTransformer = void 0;
 var yaml_transformer_1 = require("./yaml-transformer");
 Object.defineProperty(exports, "yamlTransformer", { enumerable: true, get: function () { return yaml_transformer_1.yamlTransformer; } });
 var revert_1 = require("./revert");
 Object.defineProperty(exports, "applyValueToDocument", { enumerable: true, get: function () { return revert_1.applyValueToDocument; } });
+// Thrown by schema-driven toSchema; re-exported so subpath consumers can
+// catch it by instance.
+var shape_check_1 = require("../../core/shape-check");
+Object.defineProperty(exports, "SchemaShapeError", { enumerable: true, get: function () { return shape_check_1.SchemaShapeError; } });

package/dist/transformers/yaml/revert.d.ts

@@ -1,4 +1,5 @@
 import { type Document } from 'yaml';
+import type { NodeGroup } from '../../core/schema';
 /**
  * Apply an edited form value onto a parsed YAML {@link Document} in place,
  * preserving comments and formatting on every node that survives the edit.
@@ -10,9 +11,15 @@ import { type Document } from 'yaml';
  * {@link import('./json-schema')}. Callers should clone the document first if the
  * original must be preserved.
  *
+ * With `schema` (the NodeGroup the form was built from) the
+ * value is authoritative for **schema-born paths only**: keys the schema does
+ * not cover — at any depth — are preserved verbatim, their comments included.
+ * Without it the value covers the whole document and a key it lacks is a
+ * deletion.
+ *
  * Map keys are matched by the *same string form* `doc.toJS()` produced when the
  * form value was built, so non-string keys (a `80:` port map, a `true:` flag)
  * reconcile against their original typed key nodes instead of being appended as
  * duplicate string-keyed pairs.
  */
-export declare function applyValueToDocument(doc: Document, value: unknown): void;
+export declare function applyValueToDocument(doc: Document, value: unknown, schema?: NodeGroup): void;