jsonisch 0.1.0

package/dist/react/index.js

@@ -0,0 +1,456 @@
+import { B as getFieldBool, F as createTracker, a as getFieldStore, f as createFormStore, n as validateFormInput, r as getFieldInput, v as dispatchFieldSnapshot } from "../form-ref-BEri3JKv.js";
+import { a as setFieldInput, n as setFieldBool, r as validateIfRequired, t as handleSubmit } from "../handle-submit-CD3WY9gW.js";
+import { useEffect, useLayoutEffect, useMemo, useSyncExternalStore } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/react/use-signal-snapshot.ts
+/**
+* Value-level equality for snapshot objects: top-level keys compared with
+* `Object.is`, with ONE extra level for plain arrays and plain objects —
+* computed results (a `DerivedState`, an errors array) are rebuilt with a
+* fresh identity on every recompute, and without the value compare every
+* notification would produce a render even when nothing visible changed.
+* Deeper nesting falls back to "not equal" (re-render), never the other
+* way — a false negative costs one render, a false positive would cost a
+* stale UI.
+*/
+function snapshotEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || a === null) return false;
+	if (typeof b !== "object" || b === null) return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((value, index) => valueEqual(value, b[index]));
+	}
+	if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) return false;
+	return aKeys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && valueEqual(a[key], b[key]));
+}
+/**
+* The one-level-down compare: `Object.is`, widened to a shallow compare for
+* plain arrays/objects (fresh-identity computed results).
+*/
+function valueEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || a === null) return false;
+	if (typeof b !== "object" || b === null) return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((value, index) => Object.is(value, b[index]));
+	}
+	if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) return false;
+	return aKeys.every((key) => Object.prototype.hasOwnProperty.call(b, key) && Object.is(a[key], b[key]));
+}
+/**
+* Creates the external store bridging the signal graph to React.
+*
+* Four load-bearing properties:
+*
+* - `getSnapshot` NEVER computes — it returns the cached reference. React
+*   calls it during render and after every notification; computing there
+*   would either violate render purity or clobber an outer listener. The
+*   tracked read lives in the tracker's invalidation callback instead.
+* - The invalidation callback re-reads ONLY while subscribed to React.
+*   One-shot core semantics make an unsubscribed store dormant after its
+*   first notification, so a render that never commits (StrictMode's
+*   discarded pass, a concurrent abort) cannot leak a live subscription —
+*   the signal graph drops its last reference to the tracker and the
+*   whole store is garbage.
+* - `subscribe` re-reads before installing the React callback: it may be
+*   re-establishing a store that went dormant (mount race) or was disposed
+*   (StrictMode's synthetic unmount/remount), and the value may have moved
+*   while nobody listened. React re-reads `getSnapshot` right after
+*   subscribing and re-renders on mismatch, so a change in the gap is
+*   caught by value, not by version bookkeeping.
+* - Equality is by VALUE (`isEqual`): a notification that changes nothing
+*   visible keeps the previous snapshot reference and produces no render.
+*/
+function createSnapshotStore(compute, isEqual) {
+	let notifyReact;
+	let snapshot;
+	const tracker = createTracker(() => {
+		if (notifyReact === void 0) return;
+		const next = tracker.read(compute);
+		if (isEqual(snapshot, next)) return;
+		snapshot = next;
+		notifyReact();
+	});
+	snapshot = tracker.read(compute);
+	return {
+		subscribe(onStoreChange) {
+			const next = tracker.read(compute);
+			if (!isEqual(snapshot, next)) snapshot = next;
+			notifyReact = onStoreChange;
+			return () => {
+				notifyReact = void 0;
+				tracker.dispose();
+			};
+		},
+		getSnapshot: () => snapshot
+	};
+}
+/**
+* Subscribes the component to exactly the signals `compute` reads and
+* returns the computed snapshot. THE reactive primitive of the react
+* adapter — every jsonisch hook reads through it, and it is the public
+* escape hatch for a component that needs a narrower subscription than
+* `useField` provides.
+*
+* React-Compiler-safe by construction: the tracked reads happen inside a
+* closure the library invokes — the compiler can only elide expressions
+* whose call sites it memoized, never a call made from a hook's internals —
+* and the returned snapshot is an immutable value whose identity changes
+* when any observed value changes, so compiler memo caches keyed on it
+* invalidate correctly instead of freezing.
+*
+* `useMemo` semantics apply to `deps`: the compute closure is captured when
+* `deps` change, so everything it reads must be a signal (tracked) or
+* listed in `deps` (recreates the store). `isEqual` gates re-renders by
+* value; it defaults to `snapshotEqual`.
+*
+* @param compute The tracked read producing the snapshot.
+* @param deps The non-signal inputs of `compute` (useMemo contract).
+* @param isEqual The snapshot equality gate.
+*
+* @returns The current snapshot.
+*/
+function useSignalSnapshot(compute, deps, isEqual = snapshotEqual) {
+	const store = useMemo(() => createSnapshotStore(compute, isEqual), deps);
+	return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+}
+
+//#endregion
+//#region src/react/use-field.ts
+/**
+* The snapshot member names owned by the adapter itself — no plugin's
+* `fieldSnapshot` may claim one (`dispatchFieldSnapshot` throws). Covers
+* the public `FieldStore` members plus the two internal tracked keys
+* (`hasValidationErrors`/`autoFocus`) that feed them.
+*/
+const RESERVED_SNAPSHOT_KEYS = new Set([
+	"path",
+	"name",
+	"schema",
+	"control",
+	"input",
+	"errors",
+	"isTouched",
+	"isEdited",
+	"isDirty",
+	"isValid",
+	"visible",
+	"onChange",
+	"props",
+	"hasValidationErrors",
+	"autoFocus"
+]);
+/**
+* Everything reactive about a field, read in one tracked pass owned by
+* `useSignalSnapshot` (never inline in a component body, so React Compiler
+* memoization cannot elide the reads). Plugin members merge in FLAT — at
+* the snapshot's top level, never nested under a sub-object — so the
+* one-extra-level value compare of `snapshotEqual` still reaches inside a
+* recomputed result object (a `DerivedState`) and gates the re-render.
+*/
+function readFieldSnapshot(internalFormStore, internalFieldStore, path) {
+	return {
+		input: getFieldInput(internalFieldStore),
+		errors: internalFieldStore.errors.value,
+		isTouched: getFieldBool(internalFieldStore, "isTouched"),
+		isEdited: getFieldBool(internalFieldStore, "isEdited"),
+		isDirty: getFieldBool(internalFieldStore, "isDirty"),
+		hasValidationErrors: getFieldBool(internalFieldStore, "validationErrors"),
+		visible: internalFieldStore.control === "hidden" ? false : internalFieldStore.visible?.value ?? true,
+		autoFocus: !!internalFieldStore.validationErrors.value,
+		...dispatchFieldSnapshot(internalFormStore, internalFieldStore, path, RESERVED_SNAPSHOT_KEYS)
+	};
+}
+/**
+* Creates a reactive field store for the field at the given path. Widgets
+* are controlled components: render `field.input`, call
+* `field.onChange(value)`, and spread `field.props` onto the DOM element so
+* focus/blur validation modes and focus-on-error work.
+*
+* The returned store is an immutable SNAPSHOT: its identity changes when
+* any observed value changes and is stable otherwise, so it composes with
+* React Compiler memoization instead of fighting it (the LOS-567/LOS-602
+* rewrite). Callbacks and DOM plumbing keep a stable identity for the
+* field's lifetime.
+*
+* @param form The form store the field belongs to.
+* @param path The path to the field.
+*
+* @returns The field store snapshot.
+*/
+function useField(form, path) {
+	const internalFormStore = form.internal;
+	const internalFieldStore = getFieldStore(internalFormStore, path);
+	useEffect(() => {
+		return () => {
+			const elements = internalFieldStore.elements.filter((element) => element.isConnected);
+			if (internalFieldStore.elements === internalFieldStore.initialElements) internalFieldStore.initialElements = elements;
+			else internalFieldStore.initialElements = internalFieldStore.initialElements.filter((element) => element.isConnected);
+			internalFieldStore.elements = elements;
+		};
+	}, [internalFieldStore]);
+	const reactive = useSignalSnapshot(() => readFieldSnapshot(internalFormStore, internalFieldStore, path), [internalFormStore, internalFieldStore]);
+	const stable = useMemo(() => ({
+		onChange(value) {
+			setFieldInput(internalFormStore, path, value);
+			validateIfRequired(internalFormStore, internalFieldStore, "input");
+			validateIfRequired(internalFormStore, internalFieldStore, "change");
+		},
+		props: {
+			name: internalFieldStore.name,
+			ref(element) {
+				if (element && !internalFieldStore.elements.includes(element)) internalFieldStore.elements.push(element);
+			},
+			onFocus() {
+				setFieldBool(internalFieldStore, "isTouched", true);
+				validateIfRequired(internalFormStore, internalFieldStore, "touch");
+			},
+			onBlur() {
+				validateIfRequired(internalFormStore, internalFieldStore, "blur");
+			}
+		}
+	}), [internalFormStore, internalFieldStore]);
+	return useMemo(() => {
+		const { hasValidationErrors, autoFocus, ...rest } = reactive;
+		return {
+			path,
+			name: internalFieldStore.name,
+			schema: internalFieldStore.schema,
+			control: internalFieldStore.control,
+			...rest,
+			isValid: !hasValidationErrors,
+			onChange: stable.onChange,
+			props: {
+				...stable.props,
+				autoFocus
+			}
+		};
+	}, [reactive, stable]);
+}
+
+//#endregion
+//#region src/react/use-field-array.ts
+/**
+* The array field's reactive state, read in one tracked pass.
+*/
+function readFieldArraySnapshot(internalFieldStore) {
+	return {
+		items: internalFieldStore.items.value,
+		errors: internalFieldStore.errors.value,
+		isTouched: getFieldBool(internalFieldStore, "isTouched"),
+		isEdited: getFieldBool(internalFieldStore, "isEdited"),
+		isDirty: getFieldBool(internalFieldStore, "isDirty"),
+		hasValidationErrors: getFieldBool(internalFieldStore, "validationErrors")
+	};
+}
+/**
+* Creates a reactive field array store for the array field at the given
+* path. Render one row per `items` entry and use the item ID as the React
+* key so row state and DOM follow their row across reorders.
+*
+* The returned store is an immutable SNAPSHOT (see `useField` for the
+* model).
+*
+* @param form The form store the array field belongs to.
+* @param path The path to the array field.
+*
+* @returns The field array store snapshot.
+*/
+function useFieldArray(form, path) {
+	const internalFieldStore = getFieldStore(form.internal, path);
+	if (internalFieldStore.kind !== "array") throw new Error(`Expected an array field at path ${JSON.stringify(path)}, got "${internalFieldStore.kind}"`);
+	const reactive = useSignalSnapshot(() => readFieldArraySnapshot(internalFieldStore), [internalFieldStore]);
+	return useMemo(() => ({
+		path,
+		items: reactive.items,
+		errors: reactive.errors,
+		isTouched: reactive.isTouched,
+		isEdited: reactive.isEdited,
+		isDirty: reactive.isDirty,
+		isValid: !reactive.hasValidationErrors
+	}), [reactive]);
+}
+
+//#endregion
+//#region src/react/components.tsx
+/**
+* Headless form component: a native `<form noValidate>` wired to
+* `handleSubmit` — an invalid submit blocks the handler and focuses the
+* first erroring field. The registry-aware `Form` from `createFormHook`
+* builds on this and adds whole-form auto-rendering.
+*
+* @param props The form component props.
+*
+* @returns A native form element.
+*/
+function Form({ of, onSubmit, ...other }) {
+	return /* @__PURE__ */ jsx("form", {
+		...other,
+		noValidate: true,
+		ref: (element) => {
+			if (element) of.internal.element = element;
+		},
+		onSubmit: handleSubmit(of, onSubmit)
+	});
+}
+/**
+* Headless field component — the escape hatch for custom layouts: takes a
+* form store and a path, and calls the render function with the reactive
+* field store.
+*
+* @param props The field component props.
+*
+* @returns The rendered field UI.
+*/
+function Field({ of, path, children }) {
+	return children(useField(of, path));
+}
+/**
+* Headless field array component: calls the render function with the
+* reactive field array store (stable item IDs for React keys).
+*
+* @param props The field array component props.
+*
+* @returns The rendered field array UI.
+*/
+function FieldArray({ of, path, children }) {
+	return children(useFieldArray(of, path));
+}
+
+//#endregion
+//#region src/react/use-form.ts
+/**
+* The form-level reactive state, read in one tracked pass. The whole-tree
+* walks behind `isTouched`/`isEdited`/`isDirty`/`isValid` are cached as
+* computeds on the internal store (`aggregates`), so a notification
+* re-reads four cache hits, not four tree walks.
+*/
+function readFormSnapshot(internal) {
+	return {
+		isSubmitting: internal.isSubmitting.value,
+		isSubmitted: internal.isSubmitted.value,
+		isValidating: internal.isValidating.value,
+		isTouched: internal.aggregates.isTouched.value,
+		isEdited: internal.aggregates.isEdited.value,
+		isDirty: internal.aggregates.isDirty.value,
+		isValid: internal.aggregates.isValid.value,
+		errors: internal.errors.value
+	};
+}
+/**
+* Creates a reactive form store from a form configuration. The store is
+* created once for the component's lifetime — config changes after mount
+* are ignored (`applyBaseline` rebases on a fresh server record; `reset`
+* with a new `initialInput` discards in-flight edits with it).
+*
+* The returned store is an immutable SNAPSHOT over the stable `internal`
+* store: its identity changes when any observed form-level value changes
+* (see `useField` for the model).
+*
+* @param config The form configuration.
+*
+* @returns The form store snapshot.
+*/
+function useForm(config) {
+	const internal = useMemo(() => createFormStore(config), []);
+	useLayoutEffect(() => {
+		if (config.validate === "initial") validateFormInput(internal);
+	}, []);
+	const reactive = useSignalSnapshot(() => readFormSnapshot(internal), [internal]);
+	return useMemo(() => ({
+		internal,
+		...reactive
+	}), [internal, reactive]);
+}
+
+//#endregion
+//#region src/react/create-form-hook.tsx
+/**
+* The built-in fallback for a widget kind without a registry entry: a
+* visible, explicit placeholder — silently dropping a field would make a
+* schema misconfiguration invisible.
+*/
+function UnsupportedWidget({ field }) {
+	return /* @__PURE__ */ jsxs("p", {
+		"data-slot": "jsonisch-unsupported",
+		role: "note",
+		children: [
+			"Unsupported field kind “",
+			field.control,
+			"” (",
+			field.name,
+			")"
+		]
+	});
+}
+/**
+* Creates the app's form API around a widget registry (the TanStack
+* `createFormHook` borrow): widgets are registered ONCE at module level,
+* and every form derives its fields from the schema through them.
+*
+* @param config The registry and injected validator compiler.
+*
+* @returns The bound `useAppForm`, `Form` and `Field`.
+*/
+function createFormHook(config) {
+	const Fallback = config.fallback ?? UnsupportedWidget;
+	function useAppForm(formConfig) {
+		const validator = useMemo(() => config.validate?.(formConfig.schema), []);
+		return useForm({
+			...formConfig,
+			validator
+		});
+	}
+	function AppField({ of, path, children }) {
+		if (children) return /* @__PURE__ */ jsx(Field, {
+			of,
+			path,
+			children
+		});
+		return /* @__PURE__ */ jsx(RegistryField, {
+			of,
+			path
+		});
+	}
+	function RegistryField({ of, path }) {
+		const field = useField(of, path);
+		if (!field.visible) return null;
+		return /* @__PURE__ */ jsx(config.widgets[field.control] ?? Fallback, {
+			field,
+			form: of
+		});
+	}
+	function AutoFields({ of }) {
+		const root = of.internal;
+		return /* @__PURE__ */ jsx(Fragment, { children: Object.entries(root.children).map(([key, child]) => child.control === "hidden" ? null : /* @__PURE__ */ jsx(AppField, {
+			of,
+			path: [key]
+		}, key)) });
+	}
+	function AppForm({ of, onSubmit, children, ...other }) {
+		return /* @__PURE__ */ jsx(Form, {
+			of,
+			onSubmit,
+			...other,
+			children: children ?? /* @__PURE__ */ jsx(AutoFields, { of })
+		});
+	}
+	return {
+		useAppForm,
+		Form: AppForm,
+		Field: AppField,
+		Fields: AutoFields
+	};
+}
+
+//#endregion
+export { Field, FieldArray, Form, createFormHook, snapshotEqual, useField, useFieldArray, useForm, useSignalSnapshot };

package/docs/decode-fork.md

@@ -0,0 +1,24 @@
+# The decode fork
+
+How a server record becomes form state: **one decode, then a fork** — the
+canonical prose lives atop `src/core/codec/decode-record.ts` (the ASCII
+version at the point of use); this page is the rendered view.
+
+```mermaid
+flowchart TD
+  PG["Postgres row<br/>{ …columns, data: { myField: { kind, value?, mode, … } } }"]
+  PG -->|"① decodeRecord — schema-declared keys only,<br/>envelopes pass through WHOLE<br/>(bag preferred over a column mirror)"| II["initialInput<br/>{ myField: { kind, value?, mode, … } }"]
+  II -->|"② createFormStore visits each declared field"| FORK{{"estimate / amount-or-percent leaf:<br/>the SAME raw envelope is read twice"}}
+  FORK -->|"value half<br/>unwrapLeafInput (core/plugin/driver.ts)"| INPUT["field input signal<br/>60000 — what you type over,<br/>what formulas read"]
+  FORK -->|"meta half<br/>envelopes() buildScope<br/>(plugins/envelopes/plugin.ts)"| SLOT["envelope slot<br/>mode: estimate/formula —<br/>what the toggle shows"]
+```
+
+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` (root and per row, after
+the value rebase), and array-row reuse — every path funnels through the same
+two readers. There is no envelope side-channel: `decodeCompanions` was
+deleted in LOS-603 because the envelope rides the field key itself, at every
+depth (a row's estimate decodes from its own row object identically).

package/docs/plugin-lifecycle.md

@@ -0,0 +1,44 @@
+# Plugin lifecycle
+
+Since LOS-603 everything computed on top of the base pipeline is a plugin
+(`src/core/plugin/{key,types,driver}.ts`). The standard trio a stage form
+registers: `envelopes()` → `derivation(engine)` → `visibility()` — array
+order is load-bearing (`derivation` declares `dependsOn: [envelopesKey]`;
+a missing/later dependency throws at `createFormStore`).
+
+**Core owns the phases** — every hook is a pinned call site in core; plugins
+only order among themselves within a hook.
+
+```mermaid
+flowchart TD
+  A["createFormStore(config)"] --> B["resolvePlugins:<br/>flatten, validate names/keys/hooks,<br/>dependsOn-throw, collect wire envelopes"]
+  B --> C["build (per plugin, array order):<br/>state container only — BEFORE the walk"]
+  C --> D["schema walk (initializeFieldStore)<br/>leaf inputs unwrap envelopes via unwrapLeafInput"]
+  D -- "each array-item object,<br/>AS the walk creates it" --> E["buildScope(rowStore, rawRow)"]
+  D --> F["root buildScope(form, rawInitialInput)<br/>envelopes → derivation → visibility"]
+  F --> G["aggregates (isDirty = field walk OR pluginsDirty —<br/>reads EVERY plugin, never short-circuits)"]
+```
+
+Later dispatches, each from its pinned core site:
+
+| Hook | Fires from | Purpose |
+|---|---|---|
+| `reseedScope` | `resetItemState` (row reuse/regrow) | re-seed slots in place — computeds keep tracking |
+| `rebase` | `applyBaseline` (root) + `rebaseFieldBaseline` (rows), AFTER the value rebase | baselines adopt fresh meta; live signals only when clean |
+| `resetField` | inside `reset`'s walk | restore slots to decode-time baseline (scoped resets free) |
+| `syncInput` | `setFieldInput` leaf write | plugin writes `store.input` + its slot (`writeEnvelope`); return true to skip core's write |
+| `syncInitial` | `reset({ initialInput })` via `setInitialFieldInput` | re-decode start envelope from the same raw |
+| `transferField` / `swapField` | `copyItemState` / `swapItemState` | per-field slots travel with rows (stores are position-fixed) |
+| `fieldIsDirty` / `isDirty` | dirty walks / the aggregate | payload emission + Save enablement |
+| `encodeValue` | dirty encoding (`getDirtyFieldInput`/`pickDirty`/`encodeScopeValues`) | wrap your own key — the LOS-573 envelope |
+
+State lives in `form.pluginState`, keyed by `PluginKey` identity; per-field
+slots (`FieldSlotKey`) are maps keyed by field-store identity. Cross-plugin
+reads go through exported keys only (derivation imports `envelopesKey`, never
+the envelopes implementation). The react surface reads slots via the same
+keys until slice 3 (LOS-604) moves it to `fieldSnapshot` contributions.
+
+Hard rule (spec D6): a plugin's `isDirty` runs inside a computed — it must
+read its signals unconditionally, and the aggregate never short-circuits
+between plugins; an unran handler contributes no signal reads and deafens the
+projection.

package/docs/rerender-history.md

@@ -0,0 +1,61 @@
+# A short history of the re-render problem
+
+Where jsonisch's reactivity engine comes from. This is lineage, not pitch —
+the re-render problem was solved by the signals generation (formisch and the
+SolidJS school); jsonisch inherits that answer rather than contributing one.
+It's recorded here because knowing which era a library belongs to tells you
+most of what you need to know about it.
+
+Every React form library is, underneath, an answer to one question: **when I
+type one character into a 60-field form, what re-renders?** The history is
+basically that answer getting better.
+
+| Era | Library | How it held form state | What re-rendered on a keystroke |
+|---|---|---|---|
+| ~2016 | **Redux-Form** | in the Redux store | the whole form subtree, from the store — correct, and famously slow |
+| ~2018 | **Formik** | one React state object at the top | all fields — the "everything re-renders" problem |
+| ~2018 | **React Final Form** | an observable form-state object + **per-field subscriptions** | only the field you typed in — hand-rolled fine-grained reactivity |
+| ~2019 | **react-hook-form** | **uncontrolled inputs + refs** (the DOM holds the value) | nothing, until you ask — fast by *dodging* React |
+| ~2020 | **TanStack Form** | a framework-agnostic store + **selector subscriptions** | only the subscribed slice — plus deep type inference and a composition API |
+| ~2024 | **Formisch** (and the SolidJS lineage) | **signals** | only the true dependents — reactivity at the *value* level, with computeds for free |
+
+React Final Form and TanStack Form both reach for **subscriptions**; signals
+are the same idea made automatic and general — read a value and you're
+subscribed, write it and only the readers re-run.
+
+## What's a signal, concretely?
+
+A signal is a value that tracks who reads it, so it can notify exactly those
+readers when it changes. The whole mechanism is small:
+
+```js
+let currentListener = null;                 // "who's reading right now?"
+
+function signal(value) {
+  const subs = new Set();
+  return {
+    get() { if (currentListener) subs.add(currentListener); return value; }, // read = subscribe
+    set(next) { value = next; subs.forEach((fn) => fn()); },                 // write = notify
+  };
+}
+
+function effect(fn) {                        // re-runs when any signal it read changes
+  const run = () => { currentListener = run; fn(); currentListener = null; };
+  run();
+}
+```
+
+The trick is the global `currentListener`: while a computation runs, any
+`signal.get()` it calls auto-subscribes it. No dependency arrays. A
+**computed** (e.g. a derived field) is just an `effect` that reads some
+signals and writes to its own. In React, a snapshot hook bridges the gap —
+it registers a subscriber that re-renders the component and collects which
+signals were read during render.
+
+## What jsonisch takes from this
+
+Signals as the reactivity engine (its own implementation, no external signal
+lib), so a keystroke re-renders only the fields that depend on it, and
+derived fields recompute automatically as computeds over the dependency
+graph. That's the formisch inheritance; the rest of jsonisch — deriving the
+whole form from a runtime schema value — is layered on top of it.

package/docs/wire-shapes.md

@@ -0,0 +1,70 @@
+# Wire shapes
+
+Estimate and amount-or-percent fields persist a **kind-discriminated
+envelope on their own key** — there are no `<key>Source`/`<key>Hybrid`
+sibling keys anywhere on the wire:
+
+```jsonc
+// estimate (control "estimate")
+"totalProjectBudget": {
+  "kind": "estimate",
+  "value": 60000,
+  "mode": "estimate",
+  "manualValue": 60000,
+  "lastFlippedAt": "…"
+}
+// formula-owned: NO value key — the server recompute authors it
+"totalProjectBudget": { "kind": "estimate", "mode": "formula" }
+
+// amount-or-percent (control "amount-or-percent")
+"initialDisbursement": {
+  "kind": "amount-or-percent",
+  "value": 12500,
+  "mode": "percent",
+  "basis": "total_commitment"
+}
+```
+
+Wire `mode` uses settled names (`estimate`/`formula`, `amount`/`percent`).
+Every other field persists bare. The shape is owned by ONE static
+descriptor — `envelopesWire` in `src/plugins/envelopes/wire.ts` — imported
+identically by the client plugin and the server codec (spec D7), so the
+halves cannot drift.
+
+## Encode: `encodeDirty(schema, dirty, { knownColumns, wire })`
+
+```mermaid
+flowchart TD
+  D["dirty values<br/>(pickDirty / getDirtyInput — envelope leaves already wrapped)"] --> K{"for each declared root key"}
+  K -- undeclared --> DROP["dropped (allow-list)"]
+  K -- declared --> SKIP{"wire.skipValue?"}
+  SKIP -- "formula (derivationWire)" --> DROP2["dropped — recompute is the author"]
+  SKIP -- no --> ENV{"envelope control?"}
+  ENV -- yes --> NORM["envelopesWire.encode:<br/>estimate not pinned estimate → strip value half;<br/>bare estimate value → dropped (LOS-461)"]
+  NORM --> BAG["data (envelope WHOLE)"]
+  NORM -- "x-column: true" --> MIRROR["columns (scalar value-half mirror)"]
+  ENV -- no --> COL{"x-column === true?"}
+  COL -- "yes, in knownColumns" --> C["columns"]
+  COL -- "yes, unknown column" --> DROP3["dropped (undeclared write path)"]
+  COL -- no --> BAG2["data"]
+```
+
+Key rules:
+
+- **The envelope is one bag key.** Partial writes clobber the other half, so
+  every emission is a COMPLETE envelope; whole-array posts wrap every
+  estimate/hybrid row leaf, dirty or not (`encodeScopeValues`).
+- **Column-backed envelope fields**: the bag holds the envelope (source of
+  truth); the column gets a mirrored scalar for SQL/list pages. Decode prefers
+  the bag.
+- The LOS-461 policy is unchanged, relocated: a formula value is always
+  server-recomputed; an estimate value persists exactly when its meta pins
+  `mode: "estimate"`.
+
+## Decode
+
+`decodeRecord(schema, record, { envelopes })` routes by `x-column` and passes
+envelopes through whole; the walk unwraps the value half at each leaf
+(`unwrapLeafInput`) and the envelopes plugin takes the meta half — see the
+fork diagram atop `src/core/codec/decode-record.ts` and
+[decode-fork.md](./decode-fork.md).