jsonisch 0.1.0

package/dist/index.js

@@ -0,0 +1,1521 @@
+import { A as unwrapLeafInput, B as getFieldBool, C as dispatchSyncInitial, D as fieldPluginDirty, E as encodeFieldValue, L as untrack, M as batch, N as computed, O as hasPluginDirtyField, P as createSignal, S as dispatchSwapField, T as dispatchTransferField, V as walkFieldStore, _ as resolveValueInput, a as getFieldStore, c as isPresenceEqual, d as DEFAULT_ROOT_RECORD_ALIAS, f as createFormStore, g as readOwn, h as isSafeKey, i as focusFieldElement, j as createId, l as isSemanticEqual, m as containerPresence, n as validateFormInput, o as getFieldStoreChain, p as initializeFieldStore, r as getFieldInput, s as isEmptyish, t as internalOf, u as DEFAULT_EMPTY_INPUT, x as dispatchResetField, y as dispatchRebase, z as inferControl } from "./form-ref-BEri3JKv.js";
+import { a as setFieldInput, i as computeContainerDirty, o as resetItemState, r as validateIfRequired, t as handleSubmit } from "./handle-submit-CD3WY9gW.js";
+import { A as bindAdopted, B as wrapEstimate, C as withRelationRowIdentity, E as envelopesKey, F as syncEstimateInput, H as getDirtyFieldInput, I as writeEnvelope, L as envelopesWire, M as decodeEstimateEnvelope, N as resolveEstimateMode, P as syncAmountOrPercentInput, R as isEnvelope, S as targetToKind, T as derivationKey, V as encodeScopeValues, _ as resolveRowFallback, b as relationParentFieldName, c as collectionKeys, d as visibility, i as formulaCheck, j as decodeAmountOrPercentEnvelope, k as adoptEnvelope, l as computeBag, m as resolveScopeValueAt, n as replaceCheckInstances, o as bagger, p as resolveScopeValue, r as UNEVALUABLE_MESSAGE_ID, t as checks, u as flattenSourceRow, w as mergeCollectionRows, x as relationRowIdentityProps, y as readRelationConfig, z as wrapAmountOrPercent } from "./plugin-Qka-vaO1.js";
+
+//#region src/core/codec/decode-record.ts
+/**
+* How a server record becomes form state — one decode, then a fork:
+*
+*   Postgres row { …columns, data: { myField: { kind, value?, mode, … } } }
+*        │
+*        │  ① decodeRecord (this file): schema-declared keys only,
+*        │     envelopes pass through WHOLE
+*        ▼
+*   initialInput { myField: { kind, value?, mode, … } }
+*        │
+*        │  ② createFormStore visits each declared field; an
+*        │     estimate/amount-or-percent field's envelope is read TWICE,
+*        │     once per half — both readers take the SAME raw object:
+*        ├──────────────────────────┬─────────────────────────────┐
+*        ▼                          ▼                             │
+*   value half → field input   meta half → envelope slot         │
+*   (`unwrapLeafInput`,        (`envelopes()` buildScope,        │
+*    core/plugin/driver.ts)     plugins/envelopes/plugin.ts)     │
+*
+* It is a FORK, not a chain: the meta reader consumes the original raw,
+* never the value reader's output, so the value a user sees and the mode
+* state next to it can never derive from different data. The same fork
+* re-runs on reset, `applyBaseline`, and array-row reuse — every path
+* funnels through the same two readers.
+*/
+/**
+* Decodes a nested server record into the form's `initialInput` shape,
+* routing each declared root property by its `x-column` geometry:
+* `x-column: true` fields read from a real record column (a top-level
+* record key), everything else reads from the record's `data` JSONB bag.
+*
+* The schema is the allow-list — only declared property keys are read, so
+* undeclared record keys (including prototype-pollution keys) never enter
+* the result. Nested values pass through as-is; the store walk applies the
+* allow-list recursively when the result becomes `initialInput`, and
+* unwraps envelope leaves (`{ kind, value?, mode, … }`) through the
+* registered wire contracts.
+*
+* For flat-JSONB surfaces without column routing (e.g. workflow form
+* tasks), pass the bag as `{ data: bag }`.
+*
+* @param schema The form's JSON-Schema (object schema with properties).
+* @param record The server record (`{ …columns, data? }`).
+* @param options Decode options (envelope wire contracts).
+*
+* @returns The decoded initial input, or `undefined` for a nullish record.
+*/
+function decodeRecord(schema, record, options = {}) {
+	if (record == null) return void 0;
+	const properties = schema.properties ?? {};
+	const data = record.data && typeof record.data === "object" ? record.data : void 0;
+	const input = {};
+	for (const key of Object.keys(properties)) {
+		if (!isSafeKey(key)) continue;
+		const isColumn = properties[key]["x-column"] === true;
+		let value;
+		if (isColumn && options.envelopes?.has(inferControl(properties[key]))) {
+			const bagValue = readOwn(data, key);
+			value = bagValue !== void 0 ? bagValue : readOwn(record, key);
+		} else value = isColumn ? readOwn(record, key) : readOwn(data, key);
+		if (value !== void 0) input[key] = value;
+	}
+	return input;
+}
+
+//#endregion
+//#region src/core/field/align-rows.ts
+/**
+* Non-empty identity: `null`, `undefined`, and `""` do not join.
+*/
+function isUsableId(id) {
+	return id != null && id !== "";
+}
+/**
+* For each server index, the local row that supplies live state. Server
+* order is the result order. A local index is used at most once — two
+* server rows with the same id must not share one live store. Match only
+* when both sides have a usable id.
+*
+* The caller must not invoke this when the item schema has no `id`; those
+* arrays stay positional.
+*/
+function alignRows(localIds, serverRows) {
+	const used = /* @__PURE__ */ new Set();
+	return serverRows.map((row) => {
+		const serverId = readOwn(row, "id");
+		if (!isUsableId(serverId)) return { fromLocalIndex: null };
+		for (let index = 0; index < localIds.length; index++) {
+			if (used.has(index) || localIds[index] !== serverId) continue;
+			used.add(index);
+			return { fromLocalIndex: index };
+		}
+		return { fromLocalIndex: null };
+	});
+}
+
+//#endregion
+//#region src/core/field/copy-item-state.ts
+/**
+* Copies the deeply nested state (signal values) from one field store to
+* another: `elements`, `errors`, `startInput`, `input`, `isTouched`,
+* `isEdited`, `isDirty`, and for arrays `startItems` and `items`. This is
+* the state-transfer engine under `insert`, `remove` and `move` — errors
+* and dirty/touched flags travel with their row. `initialInput`,
+* `initialItems` and `initialElements` stay put: the reset target belongs
+* to the position, not the moving item.
+*
+* @param internalFormStore The form store providing the empty input config.
+* @param fromInternalFieldStore The source field store to copy from.
+* @param toInternalFieldStore The destination field store to copy to.
+*/
+function copyItemState(internalFormStore, fromInternalFieldStore, toInternalFieldStore) {
+	batch(() => {
+		untrack(() => {
+			toInternalFieldStore.elements = fromInternalFieldStore.elements;
+			toInternalFieldStore.validationErrors.value = fromInternalFieldStore.validationErrors.value;
+			toInternalFieldStore.startInput.value = fromInternalFieldStore.startInput.value;
+			toInternalFieldStore.input.value = fromInternalFieldStore.input.value;
+			toInternalFieldStore.isTouched.value = fromInternalFieldStore.isTouched.value;
+			toInternalFieldStore.isEdited.value = fromInternalFieldStore.isEdited.value;
+			toInternalFieldStore.isDirty.value = fromInternalFieldStore.isDirty.value;
+			if (fromInternalFieldStore.kind === "value" && toInternalFieldStore.kind === "value") dispatchTransferField(internalFormStore, fromInternalFieldStore, toInternalFieldStore);
+			if (fromInternalFieldStore.kind === "array" && toInternalFieldStore.kind === "array") {
+				const fromItems = fromInternalFieldStore.items.value;
+				toInternalFieldStore.startItems.value = fromInternalFieldStore.startItems.value;
+				toInternalFieldStore.items.value = fromItems;
+				for (let index = 0; index < fromItems.length; index++) {
+					if (!toInternalFieldStore.children[index]) {
+						toInternalFieldStore.children[index] = {};
+						initializeFieldStore(internalFormStore, toInternalFieldStore.children[index], toInternalFieldStore.itemSchema, void 0, [...toInternalFieldStore.path, index]);
+					}
+					copyItemState(internalFormStore, fromInternalFieldStore.children[index], toInternalFieldStore.children[index]);
+				}
+			} else if (fromInternalFieldStore.kind === "object" && toInternalFieldStore.kind === "object") for (const key in fromInternalFieldStore.children) copyItemState(internalFormStore, fromInternalFieldStore.children[key], toInternalFieldStore.children[key]);
+		});
+	});
+}
+
+//#endregion
+//#region src/core/field/park-item-state.ts
+/**
+* Path must be the item path or envelope slots are not built (LOS-596).
+*/
+function parkItemState(form, array, source, sourceIndex) {
+	const parked = {};
+	initializeFieldStore(form, parked, array.itemSchema, void 0, [...array.path, sourceIndex]);
+	copyItemState(form, source, parked);
+	return parked;
+}
+
+//#endregion
+//#region src/core/field/rebase-field-baseline.ts
+/**
+* Rebases the live state of a field store and all its children onto a new
+* baseline value — the live half of `applyBaseline` (`setInitialFieldInput`
+* is the reset-target half and must run first): the dirty baseline
+* (`startInput`/`startItems`) always moves to the new value; the current
+* input moves with it only when the field was clean, so an in-flight edit
+* survives and is re-diffed against the new baseline (an edit equal to the
+* fresh server value becomes clean — semantic dirty rules apply).
+*
+* Callers must wrap in `batch` + `untrack` (like the reset internals).
+*
+* @param internalFormStore The form store providing the empty input config.
+* @param internalFieldStore The field store to rebase.
+* @param input The new baseline value.
+*/
+function rebaseFieldBaseline(internalFormStore, internalFieldStore, input) {
+	if (internalFieldStore.kind === "array") rebaseArrayBaseline(internalFormStore, internalFieldStore, input);
+	else if (internalFieldStore.kind === "object") {
+		const presence = containerPresence(internalFieldStore.isNullish, input);
+		const presenceClean = isPresenceEqual(internalFieldStore.startInput.value, internalFieldStore.input.value);
+		internalFieldStore.startInput.value = presence;
+		if (presenceClean) internalFieldStore.input.value = presence;
+		for (const key in internalFieldStore.children) rebaseFieldBaseline(internalFormStore, internalFieldStore.children[key], readOwn(input, key));
+		if (typeof internalFieldStore.path[internalFieldStore.path.length - 1] === "number") dispatchRebase(internalFormStore, internalFieldStore, input);
+		internalFieldStore.isDirty.value = computeContainerDirty(internalFieldStore);
+	} else {
+		const newValue = resolveValueInput(internalFormStore.emptyInput, internalFieldStore.schema, internalFieldStore.isNullish, unwrapLeafInput(internalFormStore, internalFieldStore.control, input));
+		const wasClean = isSemanticEqual(internalFieldStore.input.value, internalFieldStore.startInput.value);
+		internalFieldStore.startInput.value = newValue;
+		if (wasClean) internalFieldStore.input.value = newValue;
+		internalFieldStore.isDirty.value = !isSemanticEqual(internalFieldStore.input.value, newValue);
+	}
+}
+/**
+* The array half of the rebase. Membership (item identity) follows the same
+* clean-vs-dirty rule as values: unchanged membership adopts the server
+* rows — by `id` when the item schema has usable ids, otherwise
+* positionally — KEEPING surviving item IDs so mounted rows preserve their
+* identity (react keys). Unmatched clean locals drop; unmatched dirty
+* locals append after the server prefix. Locally changed membership
+* (insert, remove, reorder, presence flip) wins wholesale — the array
+* stays dirty and only rows matchable by a server `id` still rebase their
+* content.
+*/
+function rebaseArrayBaseline(internalFormStore, internalArrayStore, input) {
+	const presence = containerPresence(internalArrayStore.isNullish, input);
+	const presenceClean = isPresenceEqual(internalArrayStore.startInput.value, internalArrayStore.input.value);
+	internalArrayStore.startInput.value = presence;
+	if (presenceClean) internalArrayStore.input.value = presence;
+	const serverRows = Array.isArray(input) ? input : [];
+	const items = internalArrayStore.items.value;
+	const membershipClean = presenceClean && internalArrayStore.startItems.value.join() === items.join();
+	const serverRowsById = indexServerRowsById(internalArrayStore.itemSchema, serverRows);
+	if (membershipClean && serverRowsById) rebaseCleanMembershipById(internalFormStore, internalArrayStore, items, serverRows);
+	else if (membershipClean) rebaseCleanMembershipPositional(internalFormStore, internalArrayStore, items, serverRows);
+	else if (serverRowsById) for (let index = 0; index < items.length; index++) {
+		const serverRow = serverRowsById.get(readItemId(internalArrayStore.children[index]));
+		if (serverRow === void 0) continue;
+		rebaseFieldBaseline(internalFormStore, internalArrayStore.children[index], serverRow);
+	}
+	internalArrayStore.isDirty.value = !isPresenceEqual(internalArrayStore.startInput.value, internalArrayStore.input.value) || internalArrayStore.startItems.value.join() !== internalArrayStore.items.value.join();
+}
+/**
+* Clean membership, no usable ids: adopt server rows by index. Grown
+* slots are fresh baseline rows; surviving item IDs stay on their index.
+*/
+function rebaseCleanMembershipPositional(internalFormStore, internalArrayStore, items, serverRows) {
+	for (let index = items.length; index < serverRows.length; index++) if (internalArrayStore.children[index]) resetItemState(internalFormStore, internalArrayStore.children[index], serverRows[index]);
+	else {
+		internalArrayStore.children[index] = {};
+		initializeFieldStore(internalFormStore, internalArrayStore.children[index], internalArrayStore.itemSchema, serverRows[index], [...internalArrayStore.path, index]);
+	}
+	const shared = Math.min(items.length, serverRows.length);
+	for (let index = 0; index < shared; index++) rebaseFieldBaseline(internalFormStore, internalArrayStore.children[index], serverRows[index]);
+	const newItems = [...items.slice(0, serverRows.length), ...Array.from({ length: Math.max(0, serverRows.length - items.length) }, () => createId())];
+	internalArrayStore.items.value = newItems;
+	internalArrayStore.startItems.value = newItems;
+}
+/**
+* Clean membership with usable ids: grow/shrink to the server list, move
+* live row state onto the aligned indices, then rebase each child onto
+* that server row. Unmatched dirty locals append after that prefix;
+* unmatched clean locals drop. Stores are position-fixed (`path` stays on
+* the store) — never `children[i] = oldChildren[j]`.
+*/
+function rebaseCleanMembershipById(internalFormStore, internalArrayStore, items, serverRows) {
+	const alignment = alignRows(items.map((_, index) => readItemId(internalArrayStore.children[index])), serverRows);
+	const usedLocal = /* @__PURE__ */ new Set();
+	for (const { fromLocalIndex } of alignment) if (fromLocalIndex != null) usedLocal.add(fromLocalIndex);
+	const leftoverDirty = [];
+	for (let index = 0; index < items.length; index++) {
+		if (usedLocal.has(index)) continue;
+		const child = internalArrayStore.children[index];
+		if (child && (getFieldBool(child, "isDirty") || hasPluginDirtyField(internalFormStore, child))) leftoverDirty.push(index);
+	}
+	const parked = /* @__PURE__ */ new Map();
+	for (const fromLocalIndex of [...usedLocal, ...leftoverDirty]) {
+		if (parked.has(fromLocalIndex)) continue;
+		parked.set(fromLocalIndex, parkItemState(internalFormStore, internalArrayStore, internalArrayStore.children[fromLocalIndex], fromLocalIndex));
+	}
+	for (let index = 0; index < serverRows.length; index++) {
+		ensureItemStore(internalFormStore, internalArrayStore, index, serverRows[index]);
+		const fromLocalIndex = alignment[index].fromLocalIndex;
+		if (fromLocalIndex == null) resetItemState(internalFormStore, internalArrayStore.children[index], serverRows[index]);
+		else copyItemState(internalFormStore, parked.get(fromLocalIndex), internalArrayStore.children[index]);
+		rebaseFieldBaseline(internalFormStore, internalArrayStore.children[index], serverRows[index]);
+	}
+	const leftoverIds = [];
+	for (let n = 0; n < leftoverDirty.length; n++) {
+		const fromLocalIndex = leftoverDirty[n];
+		const dest = serverRows.length + n;
+		ensureItemStore(internalFormStore, internalArrayStore, dest, void 0);
+		copyItemState(internalFormStore, parked.get(fromLocalIndex), internalArrayStore.children[dest]);
+		leftoverIds.push(items[fromLocalIndex]);
+	}
+	const newItems = [...alignment.map(({ fromLocalIndex }) => fromLocalIndex != null ? items[fromLocalIndex] : createId()), ...leftoverIds];
+	internalArrayStore.items.value = newItems;
+	internalArrayStore.startItems.value = newItems;
+}
+/**
+* Reads the live `id` of an object row, or `undefined` when the store has
+* no value-leaf `id` child.
+*/
+function readItemId(store) {
+	if (store?.kind !== "object") return void 0;
+	const idStore = store.children.id;
+	return idStore?.kind === "value" ? idStore.input.value : void 0;
+}
+/**
+* Ensures a child store exists at `index` so a dest write has a home.
+* Existing stores are left as-is (live state is transferred or reset next).
+*/
+function ensureItemStore(internalFormStore, internalArrayStore, index, input) {
+	if (internalArrayStore.children[index]) return;
+	internalArrayStore.children[index] = {};
+	initializeFieldStore(internalFormStore, internalArrayStore.children[index], internalArrayStore.itemSchema, input, [...internalArrayStore.path, index]);
+}
+/**
+* Indexes server rows by their `id` value when the item schema declares an
+* `id` property. Returns `undefined` when rows have no usable identity
+* (no declared `id`, or no row carries one) — clean membership stays
+* positional; dirty membership skips the id join.
+*/
+function indexServerRowsById(itemSchema, serverRows) {
+	if (!itemSchema.properties || itemSchema.properties.id === void 0) return;
+	const index = /* @__PURE__ */ new Map();
+	for (const row of serverRows) {
+		const id = readOwn(row, "id");
+		if (id != null && id !== "" && !index.has(id)) index.set(id, row);
+	}
+	return index.size > 0 ? index : void 0;
+}
+
+//#endregion
+//#region src/core/field/set-initial-field-input.ts
+/**
+* Sets the initial input (the reset target) for a field store and all its
+* children recursively, initializing missing array children as needed.
+* Updates only `initialInput` and `initialItems` — `reset` moves them into
+* the live state. This is half of `applyBaseline`.
+*
+* @param internalFormStore The form store providing the empty input config.
+* @param internalFieldStore The field store to update.
+* @param initialInput The new initial input value.
+*/
+function setInitialFieldInput(internalFormStore, internalFieldStore, initialInput, options) {
+	batch(() => {
+		if (internalFieldStore.kind === "array") {
+			internalFieldStore.initialInput.value = containerPresence(internalFieldStore.isNullish, initialInput);
+			const initialArrayInput = Array.isArray(initialInput) ? initialInput : [];
+			for (let index = internalFieldStore.children.length; index < initialArrayInput.length; index++) {
+				internalFieldStore.children[index] = {};
+				initializeFieldStore(internalFormStore, internalFieldStore.children[index], internalFieldStore.itemSchema, initialArrayInput[index], [...internalFieldStore.path, index]);
+			}
+			internalFieldStore.initialItems.value = Array.from({ length: initialArrayInput.length }, () => createId());
+			for (let index = 0; index < internalFieldStore.children.length; index++) setInitialFieldInput(internalFormStore, internalFieldStore.children[index], initialArrayInput[index], options);
+		} else if (internalFieldStore.kind === "object") {
+			internalFieldStore.initialInput.value = containerPresence(internalFieldStore.isNullish, initialInput);
+			for (const key in internalFieldStore.children) setInitialFieldInput(internalFormStore, internalFieldStore.children[key], readOwn(initialInput, key), options);
+		} else {
+			internalFieldStore.initialInput.value = resolveValueInput(internalFormStore.emptyInput, internalFieldStore.schema, internalFieldStore.isNullish, unwrapLeafInput(internalFormStore, internalFieldStore.control, initialInput));
+			if (options?.syncInitial) dispatchSyncInitial(internalFormStore, internalFieldStore, initialInput);
+		}
+	});
+}
+
+//#endregion
+//#region src/methods/apply-baseline.ts
+/**
+* Rebases a live form on a fresh server-loaded record — after a save or a
+* revalidate, the store adopts the record as its new baseline instead of
+* being torn down and rebuilt: the record decodes through the `x-column`
+* codec (envelope fields keep their kind-discriminated shape for
+* the plugin rebase), clean fields
+* take the new server value, dirty fields keep the user's in-flight edit
+* re-diffed against the new baseline (an edit equal to the fresh server
+* value becomes clean), and a later `reset()` returns to the NEW baseline.
+* Array membership follows the same rule: unchanged membership adopts the
+* server rows — by `id` when the item schema has usable ids, otherwise
+* positionally — and surviving rows keep their identity. Unmatched clean
+* locals drop; unmatched dirty locals append after the server prefix
+* (field-level dirty still enables Save). Locally changed membership wins,
+* with rows still rebasing content by server `id` where ids exist.
+*
+* It is NOT conflict resolution — two people editing the same field stays
+* last-write-wins. A nullish record is a no-op (nothing to rebase on).
+*
+* For flat-JSONB surfaces without column routing, pass the bag as
+* `{ data: bag }` (the `decodeRecord` convention).
+*
+* @param form The form store to rebase.
+* @param record The fresh server record (`{ …columns, data? }`).
+* @param config Rebase options (e.g. fresh off-form values).
+*/
+function applyBaseline(form, record, config) {
+	const internalFormStore = internalOf(form);
+	const decoded = decodeRecord(internalFormStore.schema, record, { envelopes: internalFormStore.pluginDriver.envelopes });
+	if (decoded === void 0) return;
+	batch(() => {
+		untrack(() => {
+			setInitialFieldInput(internalFormStore, internalFormStore, decoded);
+			rebaseFieldBaseline(internalFormStore, internalFormStore, decoded);
+			dispatchRebase(internalFormStore, internalFormStore, decoded);
+			if (config?.offFormValues) internalFormStore.offFormValues.value = config.offFormValues;
+			if (internalFormStore.validate === "initial") validateFormInput(internalFormStore);
+		});
+	});
+}
+
+//#endregion
+//#region src/core/field/swap-item-state.ts
+/**
+* Swaps the deeply nested state (signal values) between two field stores:
+* `elements`, `errors`, `startInput`, `input`, `isTouched`, `isEdited`,
+* `isDirty`, and for arrays `startItems` and `items`. The state-transfer
+* engine under `swap` — errors and dirty/touched flags travel with their
+* row. `initialInput`, `initialItems` and `initialElements` stay put: the
+* reset target belongs to the position, not the moving item.
+*
+* @param internalFormStore The form store providing the empty input config.
+* @param firstInternalFieldStore The first field store to swap.
+* @param secondInternalFieldStore The second field store to swap.
+*/
+function swapItemState(internalFormStore, firstInternalFieldStore, secondInternalFieldStore) {
+	batch(() => {
+		untrack(() => {
+			const tempElements = firstInternalFieldStore.elements;
+			firstInternalFieldStore.elements = secondInternalFieldStore.elements;
+			secondInternalFieldStore.elements = tempElements;
+			const tempErrors = firstInternalFieldStore.validationErrors.value;
+			firstInternalFieldStore.validationErrors.value = secondInternalFieldStore.validationErrors.value;
+			secondInternalFieldStore.validationErrors.value = tempErrors;
+			const tempStartInput = firstInternalFieldStore.startInput.value;
+			firstInternalFieldStore.startInput.value = secondInternalFieldStore.startInput.value;
+			secondInternalFieldStore.startInput.value = tempStartInput;
+			const tempInput = firstInternalFieldStore.input.value;
+			firstInternalFieldStore.input.value = secondInternalFieldStore.input.value;
+			secondInternalFieldStore.input.value = tempInput;
+			const tempIsTouched = firstInternalFieldStore.isTouched.value;
+			firstInternalFieldStore.isTouched.value = secondInternalFieldStore.isTouched.value;
+			secondInternalFieldStore.isTouched.value = tempIsTouched;
+			const tempIsEdited = firstInternalFieldStore.isEdited.value;
+			firstInternalFieldStore.isEdited.value = secondInternalFieldStore.isEdited.value;
+			secondInternalFieldStore.isEdited.value = tempIsEdited;
+			const tempIsDirty = firstInternalFieldStore.isDirty.value;
+			firstInternalFieldStore.isDirty.value = secondInternalFieldStore.isDirty.value;
+			secondInternalFieldStore.isDirty.value = tempIsDirty;
+			if (firstInternalFieldStore.kind === "value" && secondInternalFieldStore.kind === "value") dispatchSwapField(internalFormStore, firstInternalFieldStore, secondInternalFieldStore);
+			if (firstInternalFieldStore.kind === "array" && secondInternalFieldStore.kind === "array") {
+				const firstItems = firstInternalFieldStore.items.value;
+				const secondItems = secondInternalFieldStore.items.value;
+				const tempStartItems = firstInternalFieldStore.startItems.value;
+				firstInternalFieldStore.startItems.value = secondInternalFieldStore.startItems.value;
+				secondInternalFieldStore.startItems.value = tempStartItems;
+				firstInternalFieldStore.items.value = secondItems;
+				secondInternalFieldStore.items.value = firstItems;
+				const maxLength = Math.max(firstItems.length, secondItems.length);
+				for (let index = 0; index < maxLength; index++) {
+					if (!firstInternalFieldStore.children[index]) {
+						firstInternalFieldStore.children[index] = {};
+						initializeFieldStore(internalFormStore, firstInternalFieldStore.children[index], firstInternalFieldStore.itemSchema, void 0, [...firstInternalFieldStore.path, index]);
+					}
+					if (!secondInternalFieldStore.children[index]) {
+						secondInternalFieldStore.children[index] = {};
+						initializeFieldStore(internalFormStore, secondInternalFieldStore.children[index], secondInternalFieldStore.itemSchema, void 0, [...secondInternalFieldStore.path, index]);
+					}
+					swapItemState(internalFormStore, firstInternalFieldStore.children[index], secondInternalFieldStore.children[index]);
+				}
+			} else if (firstInternalFieldStore.kind === "object" && secondInternalFieldStore.kind === "object") for (const key in firstInternalFieldStore.children) swapItemState(internalFormStore, firstInternalFieldStore.children[key], secondInternalFieldStore.children[key]);
+		});
+	});
+}
+
+//#endregion
+//#region src/methods/array-ops.ts
+/**
+* Resolves the array store at a path, marking every container between the
+* root and the array as present (an insert into a nullish ancestor is a
+* real change), and throws when the path does not resolve to an array
+* field.
+*/
+function resolveArrayStore(internalFormStore, path) {
+	const chain = getFieldStoreChain(internalFormStore, path);
+	const target = chain[chain.length - 1];
+	if (target.kind !== "array") throw new Error(`Expected an array field at path ${JSON.stringify(path)}, got "${target.kind}"`);
+	for (let index = 1; index < chain.length - 1; index++) {
+		const ancestor = chain[index];
+		if (ancestor.kind === "value") continue;
+		ancestor.input.value = true;
+		ancestor.isDirty.value = computeContainerDirty(ancestor);
+	}
+	return target;
+}
+/**
+* Inserts a new item into the array field at the given path. All items at
+* or after the insertion point shift up by one index, and their full state
+* (values, errors, touched/dirty flags, elements) shifts with them.
+*
+* @param form The form store containing the array field.
+* @param path The path to the array field.
+* @param config The insert configuration.
+*/
+function insert(form, path, config) {
+	batch(() => {
+		untrack(() => {
+			const internalFormStore = internalOf(form);
+			const internalArrayStore = resolveArrayStore(internalFormStore, path);
+			const items = internalArrayStore.items.value;
+			const insertIndex = config?.at ?? items.length;
+			if (insertIndex < 0 || insertIndex > items.length) return;
+			const newItems = [...items];
+			newItems.splice(insertIndex, 0, createId());
+			internalArrayStore.items.value = newItems;
+			for (let index = items.length; index > insertIndex; index--) {
+				if (!internalArrayStore.children[index]) {
+					internalArrayStore.children[index] = {};
+					initializeFieldStore(internalFormStore, internalArrayStore.children[index], internalArrayStore.itemSchema, void 0, [...internalArrayStore.path, index]);
+				}
+				copyItemState(internalFormStore, internalArrayStore.children[index - 1], internalArrayStore.children[index]);
+			}
+			if (!internalArrayStore.children[insertIndex]) {
+				internalArrayStore.children[insertIndex] = {};
+				initializeFieldStore(internalFormStore, internalArrayStore.children[insertIndex], internalArrayStore.itemSchema, config?.initialInput, [...internalArrayStore.path, insertIndex]);
+			} else resetItemState(internalFormStore, internalArrayStore.children[insertIndex], config?.initialInput);
+			internalArrayStore.input.value = true;
+			internalArrayStore.isTouched.value = true;
+			internalArrayStore.isEdited.value = true;
+			internalArrayStore.isDirty.value = true;
+			validateIfRequired(internalFormStore, internalArrayStore, "input");
+		});
+	});
+}
+/**
+* Removes the item at the given index from the array field at the given
+* path. All items after it shift down by one index with their full state.
+*
+* @param form The form store containing the array field.
+* @param path The path to the array field.
+* @param at The index of the item to remove.
+*/
+function remove(form, path, at) {
+	batch(() => {
+		untrack(() => {
+			const internalFormStore = internalOf(form);
+			const internalArrayStore = resolveArrayStore(internalFormStore, path);
+			const items = internalArrayStore.items.value;
+			if (at < 0 || at > items.length - 1) return;
+			const newItems = [...items];
+			newItems.splice(at, 1);
+			internalArrayStore.items.value = newItems;
+			for (let index = at; index < items.length - 1; index++) copyItemState(internalFormStore, internalArrayStore.children[index + 1], internalArrayStore.children[index]);
+			internalArrayStore.isTouched.value = true;
+			internalArrayStore.isEdited.value = true;
+			internalArrayStore.isDirty.value = internalArrayStore.startItems.value.join() !== newItems.join();
+			validateIfRequired(internalFormStore, internalArrayStore, "input");
+		});
+	});
+}
+/**
+* Moves the item at one index to another within the array field at the
+* given path. All items between the two indices shift accordingly with
+* their full state.
+*
+* @param form The form store containing the array field.
+* @param path The path to the array field.
+* @param from The index of the item to move.
+* @param to The index to move the item to.
+*/
+function move(form, path, from, to) {
+	batch(() => {
+		untrack(() => {
+			const internalFormStore = internalOf(form);
+			const internalArrayStore = resolveArrayStore(internalFormStore, path);
+			const items = internalArrayStore.items.value;
+			if (from < 0 || from > items.length - 1 || to < 0 || to > items.length - 1 || from === to) return;
+			const newItems = [...items];
+			newItems.splice(to, 0, newItems.splice(from, 1)[0]);
+			internalArrayStore.items.value = newItems;
+			const tempStore = parkItemState(internalFormStore, internalArrayStore, internalArrayStore.children[from], from);
+			if (from < to) for (let index = from; index < to; index++) copyItemState(internalFormStore, internalArrayStore.children[index + 1], internalArrayStore.children[index]);
+			else for (let index = from; index > to; index--) copyItemState(internalFormStore, internalArrayStore.children[index - 1], internalArrayStore.children[index]);
+			copyItemState(internalFormStore, tempStore, internalArrayStore.children[to]);
+			internalArrayStore.isTouched.value = true;
+			internalArrayStore.isEdited.value = true;
+			internalArrayStore.isDirty.value = internalArrayStore.startItems.value.join() !== newItems.join();
+			validateIfRequired(internalFormStore, internalArrayStore, "input");
+		});
+	});
+}
+/**
+* Swaps two items in the array field at the given path by exchanging their
+* positions and their full state.
+*
+* @param form The form store containing the array field.
+* @param path The path to the array field.
+* @param at The index of the first item.
+* @param and The index of the second item.
+*/
+function swap(form, path, at, and) {
+	batch(() => {
+		untrack(() => {
+			const internalFormStore = internalOf(form);
+			const internalArrayStore = resolveArrayStore(internalFormStore, path);
+			const items = internalArrayStore.items.value;
+			if (at < 0 || at > items.length - 1 || and < 0 || and > items.length - 1 || at === and) return;
+			const newItems = [...items];
+			const tempItemId = newItems[at];
+			newItems[at] = newItems[and];
+			newItems[and] = tempItemId;
+			internalArrayStore.items.value = newItems;
+			swapItemState(internalFormStore, internalArrayStore.children[at], internalArrayStore.children[and]);
+			internalArrayStore.isTouched.value = true;
+			internalArrayStore.isEdited.value = true;
+			internalArrayStore.isDirty.value = internalArrayStore.startItems.value.join() !== newItems.join();
+			validateIfRequired(internalFormStore, internalArrayStore, "input");
+		});
+	});
+}
+
+//#endregion
+//#region src/methods/errors.ts
+/**
+* Sets or clears the error messages of the field at the given path, or the
+* form-level (root) errors when no path is given. Useful for custom errors
+* that do not come from schema validation (e.g. a failed server action).
+*
+* @param form The form store to set errors on.
+* @param errors The error messages, or `null` to clear.
+* @param path The path to the field (omit for form-level errors).
+*/
+function setErrors(form, errors, path) {
+	const internal = internalOf(form);
+	(path ? getFieldStore(internal, path) : internal).validationErrors.value = errors;
+}
+/**
+* Retrieves the error messages of the field at the given path, or the
+* form-level (root) errors when no path is given. Does NOT include
+* descendants — use `getDeepErrors` for a subtree.
+*
+* @param form The form store to read errors from.
+* @param path The path to the field (omit for form-level errors).
+*
+* @returns The error messages, or `null`.
+*/
+function getErrors(form, path) {
+	const internal = internalOf(form);
+	return (path ? getFieldStore(internal, path) : internal).errors.value;
+}
+/**
+* Retrieves every error message of the field at the given path and all its
+* descendants (the entire form when no path is given), in depth-first
+* order. Form-level errors are included. This is what a checks panel sits
+* on — it surfaces errors of fields that are not currently rendered.
+*
+* @param form The form store to read errors from.
+* @param path The path to scope to (omit for the whole form).
+*
+* @returns The error messages, or `null` if none exist.
+*/
+function getDeepErrors(form, path) {
+	const internal = internalOf(form);
+	let deepErrors = null;
+	walkFieldStore(path ? getFieldStore(internal, path) : internal, (internalFieldStore) => {
+		const errors = internalFieldStore.errors.value;
+		if (errors) if (deepErrors) deepErrors.push(...errors);
+		else deepErrors = [...errors];
+	});
+	return deepErrors;
+}
+/**
+* Retrieves every erroring field of the subtree at the given path (the
+* entire form when no path is given) as `{ path, errors }` entries in
+* depth-first order.
+*
+* @param form The form store to read errors from.
+* @param path The path to scope to (omit for the whole form).
+*
+* @returns The deep error entries (empty when none exist).
+*/
+function getDeepErrorEntries(form, path) {
+	const internal = internalOf(form);
+	const entries = [];
+	walkFieldStore(path ? getFieldStore(internal, path) : internal, (internalFieldStore) => {
+		const errors = internalFieldStore.errors.value;
+		if (errors) entries.push({
+			path: [...internalFieldStore.path],
+			errors
+		});
+	});
+	return entries;
+}
+
+//#endregion
+//#region src/methods/focus.ts
+/**
+* Focuses the first focusable element of the field at the given path.
+* Detached, disabled or hidden elements are skipped.
+*
+* @param form The form store containing the field.
+* @param path The path to the field to focus.
+*/
+function focus(form, path) {
+	focusFieldElement(getFieldStore(internalOf(form), path));
+}
+
+//#endregion
+//#region src/methods/get-dirty-input.ts
+/**
+* Retrieves only the dirty input values of the field at the given path, or
+* the entire form when no path is given. Arrays are treated as atomic and
+* returned in full if any item is dirty, while object keys without a dirty
+* descendant are omitted. Returns `undefined` if nothing in the inspected
+* subtree is dirty.
+*
+* @param form The form store to retrieve dirty input from.
+* @param path The path to the field (omit for the whole form).
+*
+* @returns The dirty input, or `undefined`.
+*/
+function getDirtyInput(form, path) {
+	const internal = internalOf(form);
+	return getDirtyFieldInput(internal, path ? getFieldStore(internal, path) : internal);
+}
+
+//#endregion
+//#region src/methods/get-dirty-paths.ts
+/**
+* Returns the paths to the dirty fields of the form (or of the subtree at
+* the given path). Arrays are treated as atomic and contribute only their
+* own path if any item is dirty; object branches are recursed into, and a
+* container that flipped dirty itself (e.g. nullish → present) emits its
+* own path only when no descendant already covers it.
+*
+* @param form The form store to inspect.
+* @param path The path to scope to (omit for the whole form).
+*
+* @returns The list of paths to the dirty fields.
+*/
+function getDirtyPaths(form, path) {
+	const internal = internalOf(form);
+	const paths = [];
+	collectDirtyPaths(path ? getFieldStore(internal, path) : internal, paths);
+	return paths;
+}
+function collectDirtyPaths(internalFieldStore, paths) {
+	if (internalFieldStore.kind === "object" && internalFieldStore.input.value) {
+		const lengthBefore = paths.length;
+		for (const key in internalFieldStore.children) collectDirtyPaths(internalFieldStore.children[key], paths);
+		if (paths.length === lengthBefore && internalFieldStore.isDirty.value && internalFieldStore.path.length > 0) paths.push([...internalFieldStore.path]);
+	} else if (internalFieldStore.kind === "value") {
+		if (internalFieldStore.isDirty.value && internalFieldStore.path.length > 0) paths.push([...internalFieldStore.path]);
+	} else if (getFieldBool(internalFieldStore, "isDirty") && internalFieldStore.path.length > 0) paths.push([...internalFieldStore.path]);
+}
+
+//#endregion
+//#region src/methods/get-input.ts
+/**
+* Retrieves the current input value of the field at the given path, or the
+* entire form when no path is given. The tree is the allow-list, so the
+* result only ever contains declared fields.
+*
+* @param form The form store to retrieve input from.
+* @param path The path to the field (omit for the whole form).
+*
+* @returns The input value.
+*/
+function getInput(form, path) {
+	const internal = internalOf(form);
+	return getFieldInput(path ? getFieldStore(internal, path) : internal);
+}
+
+//#endregion
+//#region src/methods/pick-dirty.ts
+/**
+* Picks only the dirty parts of the given value, using the form's dirty
+* fields as a structural mask while reading from the SUPPLIED value (e.g. a
+* validated output), not the form's own input. Arrays are treated as atomic
+* and object keys without a dirty descendant are omitted. Returns
+* `undefined` if no field is dirty or no dirty key is present in the value.
+*
+* Envelope leaves (estimate/amount-or-percent) emit their COMPLETE
+* kind envelope — the plugin wraps the supplied
+* value with its meta half, and a leaf whose only change is plugin state
+* (a mode flip) still emits.
+*
+* @param form The form store providing the dirty mask.
+* @param from The value to filter down to its dirty parts.
+*
+* @returns The dirty parts of the value, or `undefined`.
+*/
+function pickDirty(form, from) {
+	const internal = internalOf(form);
+	if (!getFieldBool(internal, "isDirty") && !hasPluginDirtyField(internal, internal)) return;
+	const result = pickFieldValue(internal, internal, from);
+	return result && typeof result === "object" && Object.keys(result).length ? result : void 0;
+}
+/**
+* Recursively picks the dirty parts of a value using the field store as a
+* structural mask. Objects with present input recurse into their dirty
+* children that exist in the value; arrays, leaves, nullish-cleared
+* containers and shape-diverging values are returned as-is (arrays with
+* their envelope leaves wrapped).
+*/
+function pickFieldValue(internalFormStore, internalFieldStore, value) {
+	if (internalFieldStore.kind === "object" && internalFieldStore.input.value && value && typeof value === "object" && !Array.isArray(value)) {
+		const result = {};
+		for (const key in internalFieldStore.children) {
+			const child = internalFieldStore.children[key];
+			const present = Object.prototype.hasOwnProperty.call(value, key);
+			if (child.kind === "value") {
+				const valueDirty = getFieldBool(child, "isDirty");
+				const pluginDirty = fieldPluginDirty(internalFormStore, child);
+				if (!(valueDirty && present) && !pluginDirty) continue;
+				const encoded = encodeFieldValue(internalFormStore, child, valueDirty && present ? value[key] : void 0);
+				if (valueDirty && present || encoded !== void 0) result[key] = encoded;
+			} else if ((getFieldBool(child, "isDirty") || hasPluginDirtyField(internalFormStore, child)) && present) result[key] = pickFieldValue(internalFormStore, child, value[key]);
+		}
+		return result;
+	}
+	if (internalFieldStore.kind === "array") return encodeScopeValues(internalFormStore, internalFieldStore, value);
+	return value;
+}
+
+//#endregion
+//#region src/methods/reset.ts
+/**
+* Resets a specific field or the entire form to its initial state, with
+* fine-grained control over which state to preserve via the `keep*` flags.
+* When `initialInput` is provided it replaces the reset baseline first.
+*
+* @param form The form store to reset.
+* @param config The reset configuration.
+*/
+function reset(form, config) {
+	batch(() => {
+		untrack(() => {
+			const internalFormStore = internalOf(form);
+			const internalFieldStore = config?.path ? getFieldStore(internalFormStore, config.path) : internalFormStore;
+			if (config && "initialInput" in config) setInitialFieldInput(internalFormStore, internalFieldStore, config.initialInput, { syncInitial: true });
+			walkFieldStore(internalFieldStore, (fieldStore) => {
+				fieldStore.elements = fieldStore.initialElements;
+				if (!config?.keepErrors) fieldStore.validationErrors.value = null;
+				if (!config?.keepTouched) fieldStore.isTouched.value = false;
+				if (!config?.keepEdited) fieldStore.isEdited.value = false;
+				fieldStore.startInput.value = fieldStore.initialInput.value;
+				if (!config?.keepInput) fieldStore.input.value = fieldStore.initialInput.value;
+				if (fieldStore.kind === "array") {
+					fieldStore.startItems.value = fieldStore.initialItems.value;
+					if (!config?.keepInput || fieldStore.startItems.value.length === fieldStore.items.value.length) fieldStore.items.value = fieldStore.initialItems.value;
+					fieldStore.isDirty.value = computeContainerDirty(fieldStore);
+				} else if (fieldStore.kind === "object") fieldStore.isDirty.value = computeContainerDirty(fieldStore);
+				else {
+					fieldStore.isDirty.value = !isSemanticEqual(fieldStore.input.value, fieldStore.startInput.value);
+					dispatchResetField(internalFormStore, fieldStore);
+					for (const element of fieldStore.elements) if (element instanceof HTMLInputElement && element.type === "file") element.value = "";
+				}
+			});
+			if (!config?.path) {
+				if (!config?.keepSubmitted) internalFormStore.isSubmitted.value = false;
+				if (internalFormStore.validate === "initial") validateFormInput(internalFormStore);
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/methods/set-entry.ts
+function amountOrPercentOf(form, path) {
+	const internalFormStore = internalOf(form);
+	const store = getFieldStore(internalFormStore, path);
+	const slot = store.kind === "value" ? envelopesKey.get(internalFormStore, store) : void 0;
+	if (store.kind !== "value" || slot?.family !== "amount-or-percent") throw new Error(`Not an amount-or-percent field (at ${JSON.stringify(path)}) — needs a field with an amount-or-percent envelope slot`);
+	return {
+		form: internalFormStore,
+		store,
+		slot
+	};
+}
+/**
+* Sets the entry mode of an amount-or-percent field (enter a dollar
+* amount, or a percent of the percent basis). Dirties the meta half; the
+* field's own value — always the resolved dollar amount — is the widget's
+* to convert and write.
+*
+* @param form The form store containing the field.
+* @param path The path to the amount-or-percent field.
+* @param mode The entry mode.
+*/
+function setEntryMode(form, path, mode) {
+	const target = amountOrPercentOf(form, path);
+	batch(() => {
+		untrack(() => {
+			writeEnvelope(target.form, target.store, target.slot, {
+				...target.slot.envelope.value,
+				mode
+			});
+		});
+	});
+}
+/**
+* Sets the percent basis of an amount-or-percent field (the root-level field key
+* the percent is taken of). Dirties the meta half; keeping the resolved
+* dollar amount constant against the new basis is the widget's job.
+*
+* @param form The form store containing the field.
+* @param path The path to the amount-or-percent field.
+* @param percentBasis The basis field key.
+*/
+function setPercentBasis(form, path, percentBasis) {
+	const target = amountOrPercentOf(form, path);
+	batch(() => {
+		untrack(() => {
+			writeEnvelope(target.form, target.store, target.slot, {
+				...target.slot.envelope.value,
+				basis: percentBasis
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/methods/set-input.ts
+/**
+* Sets the input value of the field at the given path (or the entire form
+* for an empty path), updating touched, edited and dirty state, and
+* triggers validation when the form's validation mode requires it. Throws
+* on a path not declared in the schema.
+*
+* @param form The form store to set input on.
+* @param path The path to the field (`[]` for the whole form).
+* @param input The new input value.
+*/
+function setInput(form, path, input) {
+	batch(() => {
+		const internalFormStore = internalOf(form);
+		setFieldInput(internalFormStore, path, input);
+		validateIfRequired(internalFormStore, path.length ? getFieldStore(internalFormStore, path) : internalFormStore, "input");
+	});
+}
+
+//#endregion
+//#region src/methods/set-mode.ts
+/**
+* Flips an estimate field between its two modes — the ONLY supported mode
+* writer (a raw `mode` signal write skips value seeding and the flip
+* timestamp):
+*
+* - `estimate` → `formula`: the current input is preserved as the meta
+*   half's `manualValue` and the field computes again. The derived value
+*   is NOT written into the input — derived values are outputs; the
+*   server recompute pass is their author.
+* - `formula` → `estimate`: the manual value is seeded from the last
+*   formula result (estimate-first chronology: when you stop trusting the
+*   formula you start from its current value and adjust), which marks the
+*   value dirty like any user edit.
+*
+* Either flip dirties the meta half (`lastFlippedAt` stamped), so a flip
+* with no other edit still produces a payload.
+*
+* Works at any depth: an estimate field inside an array row has its own
+* envelope slot, built from the row's envelope. The throw is reserved
+* for a field that genuinely has none — a non-estimate control, or a form
+* without the envelopes plugin.
+*
+* @param form The form store containing the field.
+* @param path The path to the estimate field.
+* @param mode The target mode (a no-op when already current).
+* @param options Flip options (e.g. an injected timestamp).
+*/
+function setMode(form, path, mode, options = {}) {
+	const internalFormStore = internalOf(form);
+	const store = getFieldStore(internalFormStore, path);
+	const slot = store.kind === "value" ? envelopesKey.get(internalFormStore, store) : void 0;
+	if (store.kind !== "value" || slot?.family !== "estimate") throw new Error(`Not an estimate field (at ${JSON.stringify(path)}) — setMode needs a field with an estimate envelope slot`);
+	batch(() => {
+		untrack(() => {
+			const live = slot.envelope.value;
+			if (resolveEstimateMode(live, store.schema) === mode) return;
+			const now = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+			if (mode === "formula") {
+				const manualValue = store.isDirty.value ? isEmptyish(store.input.value) ? null : store.input.value : live.manualValue ?? null;
+				writeEnvelope(internalFormStore, store, slot, {
+					...live,
+					mode: "formula",
+					manualValue,
+					lastFlippedAt: now
+				});
+				return;
+			}
+			const candidate = derivationKey.get(internalFormStore, store)?.formulaValue.value;
+			const seeded = candidate && candidate.error === null && candidate.value !== void 0 ? candidate.value : live.value;
+			writeEnvelope(internalFormStore, store, slot, {
+				...live,
+				mode: "estimate",
+				value: seeded,
+				lastFlippedAt: now
+			});
+			if (candidate && candidate.error === null && candidate.value !== void 0) {
+				store.isTouched.value = true;
+				store.isEdited.value = true;
+			}
+		});
+	});
+}
+
+//#endregion
+//#region src/methods/set-off-form-values.ts
+/**
+* Replaces the form's off-form values (the read-only eval scope formula
+* resolution falls back to). One signal write: every formula field reading
+* off-form values re-resolves once — the LOS-470 `BpsBaseSync` behavior as
+* a store property. `applyBaseline` performs the same
+* write on reconcile, batched with the value rebase.
+*
+* @param form The form store.
+* @param values The new off-form values.
+*/
+function setOffFormValues(form, values) {
+	internalOf(form).offFormValues.value = values;
+}
+
+//#endregion
+//#region src/methods/validate.ts
+/**
+* Validates the entire form input with the injected validator, routing each
+* issue to its field's `errors` signal. Optionally focuses the first field
+* with an error.
+*
+* @param form The form store to validate.
+* @param config The validation configuration.
+*
+* @returns The validation result.
+*/
+function validate(form, config) {
+	return validateFormInput(internalOf(form), config);
+}
+
+//#endregion
+//#region src/core/codec/encode-dirty.ts
+/**
+* Builds the envelope-control lookup from a wire list.
+*/
+function envelopeContracts(wire) {
+	const map = /* @__PURE__ */ new Map();
+	for (const contract of wire ?? []) for (const control of contract.envelopeControls ?? []) map.set(control, contract);
+	return map;
+}
+/**
+* Encodes a dirty-values object (the `pickDirty`/`getDirtyInput` result)
+* into the save payload, partitioning each root key by its `x-column`
+* geometry: `x-column: true` fields become column updates, everything else
+* lands in the `data` bag. Undeclared keys — including prototype-pollution
+* keys — are dropped: the schema is the allow-list at the write boundary
+* too.
+*
+* Wire contracts carry each plugin's persistence policy (behavior
+* relocated verbatim from LOS-461, not redesigned): `skipValue` drops a
+* formula value (the server recompute is its only author), and an
+* envelope contract's `encode` normalizes the outgoing envelope (an
+* estimate value persists exactly when its meta pins `mode: "estimate"`).
+*
+* @param schema The form's JSON-Schema (object schema with properties).
+* @param dirty The dirty values, or `undefined` when nothing is dirty.
+* @param options Encoding options (column set, wire contracts).
+*
+* @returns The partitioned payload, or `undefined` when nothing survives.
+*/
+function encodeDirty(schema, dirty, options = {}) {
+	if (dirty == null) return void 0;
+	const properties = schema.properties ?? {};
+	const envelopes$1 = envelopeContracts(options.wire);
+	const columns = {};
+	const data = {};
+	let hasEntries = false;
+	for (const key of Object.keys(dirty)) {
+		if (!isSafeKey(key)) continue;
+		if (!Object.prototype.hasOwnProperty.call(properties, key)) continue;
+		const property = properties[key];
+		const control = inferControl(property);
+		if (options.wire?.some((w) => w.skipValue?.(control, dirty, key))) continue;
+		const isColumn = property["x-column"] === true;
+		const contract = envelopes$1.get(control);
+		if (contract) {
+			const encoded = contract.encode ? contract.encode(control, dirty[key]) : dirty[key];
+			if (encoded === void 0) continue;
+			data[key] = encoded;
+			if (isColumn && (!options.knownColumns || options.knownColumns.has(key))) {
+				const value = contract.unwrap ? contract.unwrap(encoded).value : void 0;
+				if (value !== void 0) columns[key] = value;
+			}
+			hasEntries = true;
+			continue;
+		}
+		if (isColumn) {
+			if (options.knownColumns && !options.knownColumns.has(key)) continue;
+			columns[key] = dirty[key];
+		} else data[key] = dirty[key];
+		hasEntries = true;
+	}
+	return hasEntries ? {
+		columns,
+		data
+	} : void 0;
+}
+
+//#endregion
+//#region src/plugins/envelopes/plugin.ts
+/**
+* Builds (or re-seeds) the slots of ONE object scope — the document root
+* or a single array row. Idempotent: called again on a REUSED store (an
+* array shrink-then-regrow, a rebuilt row) it re-seeds the existing
+* signals in place instead of replacing them, so computeds already wired
+* to the mode signal keep tracking it.
+*/
+function buildScopeSlots(form, state, scope, raw) {
+	for (const key of Object.keys(scope.children)) {
+		const child = scope.children[key];
+		if (child.kind !== "value") continue;
+		if (child.control === "estimate") buildEstimateSlot(form, state, child, readOwn(raw, key));
+		else if (child.control === "amount-or-percent") buildAmountOrPercentSlot(form, state, child, readOwn(raw, key));
+	}
+}
+function estimateDirty(live, start, schema) {
+	return resolveEstimateMode(live, schema) !== resolveEstimateMode(start, schema) || resolveEstimateMode(live, schema) === "estimate" && !isSemanticEqual(live.value, start.value);
+}
+function buildEstimateSlot(form, state, store, raw) {
+	const decoded = decodeEstimateEnvelope(form, store, raw);
+	const existing = state.get(store);
+	if (existing?.family === "estimate") {
+		existing.startEnvelope.value = decoded;
+		writeEnvelope(form, store, existing, decoded);
+		return;
+	}
+	const envelope = createSignal(decoded);
+	const startEnvelope = createSignal(decoded);
+	const slot = {
+		family: "estimate",
+		envelope,
+		startEnvelope,
+		mode: computed(() => resolveEstimateMode(envelope.value, store.schema)),
+		manualValue: computed(() => envelope.value.manualValue ?? null),
+		lastFlippedAt: computed(() => envelope.value.lastFlippedAt),
+		isDirty: computed(() => estimateDirty(envelope.value, startEnvelope.value, store.schema))
+	};
+	state.set(store, slot);
+}
+function buildAmountOrPercentSlot(form, state, store, raw) {
+	const decoded = decodeAmountOrPercentEnvelope(form, store, raw);
+	const existing = state.get(store);
+	if (existing?.family === "amount-or-percent") {
+		existing.startEnvelope.value = decoded;
+		writeEnvelope(form, store, existing, decoded);
+		return;
+	}
+	const envelope = createSignal(decoded);
+	const startEnvelope = createSignal(decoded);
+	const slot = {
+		family: "amount-or-percent",
+		envelope,
+		startEnvelope,
+		entryMode: computed(() => envelope.value.mode),
+		percentBasis: computed(() => envelope.value.basis),
+		isDirty: computed(() => envelope.value.mode !== startEnvelope.value.mode || envelope.value.basis !== startEnvelope.value.basis)
+	};
+	state.set(store, slot);
+}
+/**
+* Rebases one scope's slots onto fresh raw data — the meta half of
+* `applyBaseline`. `adoptEnvelope` keeps per-channel clean-vs-dirty, then
+* `writeEnvelope` runs once.
+*/
+function rebaseScopeSlots(form, state, scope, raw) {
+	for (const key of Object.keys(scope.children)) {
+		const child = scope.children[key];
+		if (child.kind !== "value") continue;
+		const slot = state.get(child);
+		if (!slot) continue;
+		if (slot.family === "estimate") {
+			const incoming = decodeEstimateEnvelope(form, child, readOwn(raw, key));
+			bindAdopted(form, child, slot, adoptEnvelope(slot.envelope.value, slot.startEnvelope.value, incoming, child.schema));
+		} else {
+			const incoming = decodeAmountOrPercentEnvelope(form, child, readOwn(raw, key));
+			bindAdopted(form, child, slot, adoptEnvelope(slot.envelope.value, slot.startEnvelope.value, incoming, child.schema));
+		}
+	}
+}
+/**
+* Serializes an estimate slot's meta half. In estimate mode an EDITED input
+* is the manual value (keystrokes mirror into the meta — never the loaded
+* column value); an unedited one carries the decoded `manualValue`
+* forward. In formula mode the value preserved at flip time carries
+* forward.
+*/
+function encodeEstimateMeta(store, slot) {
+	const live = slot.envelope.value;
+	const start = slot.startEnvelope.value;
+	const mode = resolveEstimateMode(live, store.schema);
+	const meta = {
+		mode,
+		manualValue: mode === "estimate" ? store.isDirty.value ? isEmptyish(store.input.value) ? null : store.input.value : start.manualValue ?? null : live.manualValue ?? null
+	};
+	const flippedAt = live.lastFlippedAt ?? start.lastFlippedAt;
+	if (flippedAt !== void 0) meta.lastFlippedAt = flippedAt;
+	return meta;
+}
+/**
+* Whether any LIVE value leaf in the subtree carries a dirty slot. Walks
+* the tree (not the slot map): stale child stores past an array shrink
+* keep their slots, and those must never phantom-dirty the form. Reads
+* array `items`, so a reactive caller subscribes to structural changes.
+* Never short-circuits — this runs inside the `isDirty` aggregate
+* computed, and an unread branch would deafen the projection.
+*/
+function hasDirtySlot(state, store) {
+	if (store.kind === "value") return state.get(store)?.isDirty.value ?? false;
+	let dirty = false;
+	if (store.kind === "array") {
+		const length = store.items.value.length;
+		for (let index = 0; index < length; index++) {
+			const child = store.children[index];
+			if (child && hasDirtySlot(state, child)) dirty = true;
+		}
+		return dirty;
+	}
+	for (const key in store.children) if (hasDirtySlot(state, store.children[key])) dirty = true;
+	return dirty;
+}
+/**
+* The envelopes plugin: owns the meta half of estimate and
+* amount-or-percent fields — mode/entry state decoded from the kind
+* envelope, dirty-tracked, and serialized by wrapping the field's own
+* payload entry. No factory arguments: the envelope rides the field key,
+* so every scope's raw value already carries the meta half (no envelope
+* side-channel to decode).
+*/
+function envelopes() {
+	return {
+		name: "envelopes",
+		key: envelopesKey,
+		wire: envelopesWire,
+		build: () => /* @__PURE__ */ new Map(),
+		buildScope(ctx, scope, raw) {
+			buildScopeSlots(ctx.form, ctx.state, scope, raw);
+		},
+		reseedScope(ctx, scope, raw) {
+			buildScopeSlots(ctx.form, ctx.state, scope, raw);
+		},
+		resetField(ctx, store) {
+			if (store.kind !== "value") return;
+			const slot = ctx.state.get(store);
+			if (!slot) return;
+			if (slot.family === "estimate") writeEnvelope(ctx.form, store, slot, {
+				...slot.startEnvelope.value,
+				value: store.input.value
+			});
+			else writeEnvelope(ctx.form, store, slot, {
+				...slot.startEnvelope.value,
+				value: store.input.value
+			});
+		},
+		rebase(ctx, scope, raw) {
+			rebaseScopeSlots(ctx.form, ctx.state, scope, raw);
+		},
+		syncInput(ctx, store, input) {
+			if (store.kind !== "value") return false;
+			const slot = ctx.state.get(store);
+			if (!slot) return false;
+			if (slot.family === "estimate") syncEstimateInput(ctx.form, store, slot, input);
+			else syncAmountOrPercentInput(ctx.form, store, slot, input);
+			return true;
+		},
+		syncInitial(ctx, store, raw) {
+			if (store.kind !== "value") return;
+			const slot = ctx.state.get(store);
+			if (!slot) return;
+			if (slot.family === "estimate") slot.startEnvelope.value = decodeEstimateEnvelope(ctx.form, store, raw);
+			else slot.startEnvelope.value = decodeAmountOrPercentEnvelope(ctx.form, store, raw);
+		},
+		transferField(ctx, from, to) {
+			const source = ctx.state.get(from);
+			const target = ctx.state.get(to);
+			if (!source || !target || source.family !== target.family) return;
+			if (source.family === "estimate" && target.family === "estimate") {
+				target.startEnvelope.value = source.startEnvelope.value;
+				target.envelope.value = source.envelope.value;
+			} else if (source.family === "amount-or-percent" && target.family === "amount-or-percent") {
+				target.startEnvelope.value = source.startEnvelope.value;
+				target.envelope.value = source.envelope.value;
+			}
+		},
+		swapField(ctx, first, second) {
+			const a = ctx.state.get(first);
+			const b = ctx.state.get(second);
+			if (!a || !b || a.family !== b.family) return;
+			if (a.family === "estimate" && b.family === "estimate") {
+				swapSignals(a.startEnvelope, b.startEnvelope);
+				swapSignals(a.envelope, b.envelope);
+			} else if (a.family === "amount-or-percent" && b.family === "amount-or-percent") {
+				swapSignals(a.startEnvelope, b.startEnvelope);
+				swapSignals(a.envelope, b.envelope);
+			}
+		},
+		fieldIsDirty(ctx, store) {
+			return ctx.state.get(store)?.isDirty.value ?? false;
+		},
+		encodeValue(ctx, store, valueOut) {
+			const slot = ctx.state.get(store);
+			if (!slot) return void 0;
+			if (!slot.isDirty.value && valueOut === void 0) return void 0;
+			if (slot.family === "estimate") {
+				if (!slot.isDirty.value) {
+					const persisted = slot.startEnvelope.value.mode;
+					if (persisted === void 0) return void 0;
+					const start = slot.startEnvelope.value;
+					const meta$1 = {
+						mode: persisted,
+						manualValue: start.manualValue ?? null
+					};
+					if (start.lastFlippedAt !== void 0) meta$1.lastFlippedAt = start.lastFlippedAt;
+					return persisted === "estimate" ? wrapEstimate(valueOut, meta$1) : wrapEstimate(void 0, meta$1);
+				}
+				const meta = encodeEstimateMeta(store, slot);
+				return resolveEstimateMode(slot.envelope.value, store.schema) === "estimate" ? wrapEstimate(valueOut !== void 0 ? valueOut : store.input.value, meta) : wrapEstimate(void 0, meta);
+			}
+			return wrapAmountOrPercent(valueOut !== void 0 ? valueOut : store.input.value, {
+				mode: slot.entryMode.value,
+				basis: slot.percentBasis.value ?? ""
+			});
+		},
+		isDirty(ctx) {
+			return hasDirtySlot(ctx.state, ctx.form);
+		},
+		fieldSnapshot(ctx, store, path) {
+			const slot = ctx.state.get(store);
+			if (!slot) return {};
+			if (slot.family === "estimate") {
+				slot.callbacks ??= { setMode: (mode) => setMode(ctx.form, path, mode) };
+				return {
+					mode: slot.mode.value,
+					setMode: slot.callbacks.setMode
+				};
+			}
+			slot.callbacks ??= {
+				setEntryMode: (mode) => setEntryMode(ctx.form, path, mode),
+				setPercentBasis: (percentBasis) => setPercentBasis(ctx.form, path, percentBasis)
+			};
+			return {
+				entryMode: slot.entryMode.value,
+				percentBasis: slot.percentBasis.value,
+				setEntryMode: slot.callbacks.setEntryMode,
+				setPercentBasis: slot.callbacks.setPercentBasis
+			};
+		}
+	};
+}
+function swapSignals(first, second) {
+	const value = first.value;
+	first.value = second.value;
+	second.value = value;
+}
+
+//#endregion
+//#region src/plugins/derivation/plugin.ts
+/**
+* Key for a directed dep-graph edge (`from` reads `to`).
+*/
+function edgeKey(from, to) {
+	return `${from}\u0000${to}`;
+}
+/**
+* Extracts a human-readable message from a thrown evaluation error.
+*/
+function messageOf(error) {
+	return error instanceof Error && error.message ? error.message : String(error);
+}
+/**
+* The derivation plugin: parses every `x-formula` once per scope (the
+* document root and each array row — it is scope, not machinery, that
+* differs; LOS-596), breaks dependency cycles deterministically, and gives
+* each formula field its `formulaValue`/`derived` slot plus the composed
+* `errors` channel.
+*
+* Scope resolution lives HERE and only here (the LOS-514 closure — no
+* other read path exists): per dependency, the form value wins (a formula
+* dep resolves through its own derived signal, chaining fresh values),
+* `offFormValues` fills only `undefined`, and when both sides are arrays
+* the canonical rows merge with the live form rows (the collection
+* overlay for aggregate refs).
+*
+* Declares `dependsOn: [envelopesKey]` — the estimate pin reads the mode
+* signal the envelopes plugin creates; without it the pin would silently
+* never engage and a manually pinned value would be overwritten by the
+* next recompute (the D2 data-loss scenario), so a missing envelopes
+* plugin is a startup error instead.
+*/
+function derivation(engine) {
+	return {
+		name: "derivation",
+		key: derivationKey,
+		dependsOn: [envelopesKey],
+		build: () => /* @__PURE__ */ new Map(),
+		buildScope(ctx, scope) {
+			const form = ctx.form;
+			if (scope === form) {
+				wireFormulaGraph(form, ctx.state, engine, scope.children, (dep, formValue) => {
+					const offValue = readOwn(form.offFormValues.value, dep);
+					if (Array.isArray(offValue) && Array.isArray(formValue)) return mergeCollectionRows(offValue, formValue);
+					return formValue === void 0 ? offValue : formValue;
+				});
+				return;
+			}
+			wireFormulaGraph(form, ctx.state, engine, scope.children, (dep, formValue) => resolveRowFallback(form, scope, dep, formValue));
+		},
+		fieldSnapshot(ctx, store) {
+			const slot = ctx.state.get(store);
+			if (!slot) return {};
+			return {
+				derived: slot.derived.value,
+				formulaValue: slot.formulaValue.value
+			};
+		}
+	};
+}
+/**
+* Wires the formula fields of ONE scope (the document root or a single
+* array row): collects the scope's parseable `x-formula` fields, breaks
+* cycles among them, and gives each one its slot. Everything
+* scope-specific enters through `resolveOutside`.
+*/
+function wireFormulaGraph(form, state, engine, children, resolveOutside) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const key of Object.keys(children)) {
+		const child = children[key];
+		if (child.kind !== "value") continue;
+		if (child.control !== "formula" && child.control !== "estimate") continue;
+		if (child.schema["x-server-maintained"] === true) {
+			const passthrough = computed(() => ({
+				value: getFieldInput(child),
+				error: null
+			}));
+			state.set(child, {
+				derived: passthrough,
+				formulaValue: passthrough,
+				isRollup: false
+			});
+			continue;
+		}
+		const formula = child.schema["x-formula"];
+		if (typeof formula !== "string" || formula.trim() === "") continue;
+		const parsed = engine.parse(formula);
+		entries.set(key, {
+			store: child,
+			node: parsed.ok ? parsed.node : void 0,
+			deps: parsed.ok ? engine.extractDependencies(parsed.node) : [],
+			parseError: parsed.ok ? null : parsed.error
+		});
+	}
+	if (entries.size === 0) return;
+	const brokenEdges = /* @__PURE__ */ new Set();
+	const cycleErrors = /* @__PURE__ */ new Map();
+	const dfsState = /* @__PURE__ */ new Map();
+	const visit = (key) => {
+		dfsState.set(key, "visiting");
+		for (const dep of entries.get(key).deps) {
+			if (!entries.has(dep)) continue;
+			if (dep === key || dfsState.get(dep) === "visiting") {
+				brokenEdges.add(edgeKey(key, dep));
+				cycleErrors.set(key, `Circular reference: "${key}" reads "${dep}"`);
+				continue;
+			}
+			if (dfsState.get(dep) !== "done") visit(dep);
+		}
+		dfsState.set(key, "done");
+	};
+	for (const key of entries.keys()) if (!dfsState.has(key)) visit(key);
+	const resolveDep = (fromKey, dep) => {
+		const child = children[dep];
+		let formValue;
+		if (child) {
+			const depEntry = child.kind === "value" ? entries.get(dep) : void 0;
+			if (depEntry && depEntry.store === child && !brokenEdges.has(edgeKey(fromKey, dep))) {
+				const depState = state.get(child).derived.value;
+				if (depState.error !== null) throw new Error(`Upstream formula error: "${dep}"`);
+				formValue = depState.value;
+			} else formValue = getFieldInput(child);
+		}
+		return resolveOutside(dep, formValue);
+	};
+	for (const [key, entry] of entries) {
+		const { store } = entry;
+		const isRollup = entry.parseError === null && (engine.extractPathRefs?.(entry.node)?.length ?? 0) > 0;
+		const cycleError = cycleErrors.get(key) ?? null;
+		const formulaValue = computed(() => {
+			if (entry.parseError !== null) return {
+				value: void 0,
+				error: entry.parseError
+			};
+			try {
+				const scope = Object.create(null);
+				for (const dep of entry.deps) scope[dep] = resolveDep(key, dep);
+				return {
+					value: engine.evaluate(entry.node, scope),
+					error: cycleError
+				};
+			} catch (error) {
+				return {
+					value: void 0,
+					error: cycleError ?? messageOf(error)
+				};
+			}
+		});
+		const derived = store.control === "estimate" ? computed(() => {
+			const envelope = envelopesKey.get(form, store);
+			return envelope?.family === "estimate" && envelope.mode.value === "estimate" && !isEmptyish(store.input.value) ? {
+				value: store.input.value,
+				error: null
+			} : formulaValue.value;
+		}) : formulaValue;
+		state.set(store, {
+			derived,
+			formulaValue,
+			isRollup
+		});
+		store.errors = computed(() => {
+			const validation = store.validationErrors.value;
+			const calc = derived.value.error;
+			if (calc === null) return validation;
+			return validation ? [...validation, calc] : [calc];
+		});
+	}
+}
+
+//#endregion
+//#region src/plugins/derivation/wire.ts
+/**
+* The derivation plugin's STATIC wire contract: a `formula` value is
+* ALWAYS server-recomputed — a client payload only carries a stale echo of
+* the last-rendered result, so `encodeDirty` drops it. (The estimate-pin
+* policy lives on `envelopesWire.encode` — the envelope owns it.)
+*/
+const derivationWire = { skipValue: (control) => control === "formula" };
+
+//#endregion
+export { DEFAULT_EMPTY_INPUT, DEFAULT_ROOT_RECORD_ALIAS, UNEVALUABLE_MESSAGE_ID, applyBaseline, bagger, checks, collectionKeys, computeBag, createFormStore, decodeRecord, derivation, derivationWire, encodeDirty, envelopeContracts, envelopes, envelopesWire, flattenSourceRow, focus, formulaCheck, getDeepErrorEntries, getDeepErrors, getDirtyInput, getDirtyPaths, getErrors, getInput, handleSubmit, inferControl, insert, isEmptyish, isEnvelope, isPresenceEqual, isSemanticEqual, mergeCollectionRows, move, pickDirty, readRelationConfig, relationParentFieldName, relationRowIdentityProps, remove, replaceCheckInstances, reset, resolveScopeValue, resolveScopeValueAt, setEntryMode, setErrors, setInput, setMode, setOffFormValues, setPercentBasis, swap, targetToKind, validate, visibility, withRelationRowIdentity, wrapAmountOrPercent, wrapEstimate };