jsonisch 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,724 @@
+import { C as flattenSourceRow, D as derivation, F as AmountOrPercentEnvelope, G as CalcParseResult, H as EstimateMeta, K as DerivationMode, L as EntryMeta, M as ValidateFormInputConfig, N as ValidationResult, R as EntryMode, S as computeBag, V as EstimateEnvelope, W as CalcEngine, _ as bagger, b as ComputeBagOptions, c as CheckDefinition, d as ChecksConfig, f as Finding, h as SeverityConfig, i as formulaCheck, j as envelopes, l as CheckInstanceConfig, m as Severity, n as replaceCheckInstances, p as FormulaOptions, q as DerivedState, r as UNEVALUABLE_MESSAGE_ID, s as CheckContext, t as checks, u as CheckScope, w as visibility, x as collectionKeys, y as BaggerOptions, z as Envelope } from "./plugin-BCsAE8RK.js";
+import { A as VisibleWhen, C as FieldErrors, G as JsonSchema, K as Path, M as ControlKind, N as inferControl, _ as WireContract, a as InternalFormStore, g as PluginsInput, i as FormValidator, j as VisibleWhenOp, o as ValidationIssue, q as PathSegment, r as FormConfig, s as ValidationMode, t as FormRef, w as FieldKind, x as ContainerInput } from "./form-ref-D_xHSaqL.js";
+import { n as handleSubmit, t as SubmitHandler } from "./handle-submit-Dk7QW3_q.js";
+
+//#region src/core/form/create-form-store.d.ts
+/**
+ * The default empty input of a form. Required string fields start as an
+ * empty string, while every other type starts as `undefined`.
+ */
+declare const DEFAULT_EMPTY_INPUT: Record<string, unknown>;
+/**
+ * The default root-record alias (`FormConfig.rootRecordAlias`). The
+ * store's resolved value is the one home at runtime; this default
+ * exists so store-less readers (`computeBag`) resolve identically.
+ */
+declare const DEFAULT_ROOT_RECORD_ALIAS = "record";
+/**
+ * Creates a new internal form store from the provided configuration: walks
+ * the JSON-Schema once and builds the field-store tree (`kind:
+ * array|object|value`), with the schema as the allow-list — `initialInput`
+ * keys not declared in the schema never enter form state.
+ *
+ * Plugins are resolved and their state containers created BEFORE the walk,
+ * so the walk can dispatch `buildScope` for every array-item object it
+ * creates (a row wired by the walk behaves exactly like one built later by
+ * an insert). The ROOT scope is dispatched after the walk, in plugin array
+ * order — for the standard trio that means envelopes (the estimate pin's
+ * mode signal) before derivation before visibility.
+ *
+ * @param config The form configuration.
+ *
+ * @returns The internal form store.
+ */
+declare function createFormStore(config: FormConfig): InternalFormStore;
+//#endregion
+//#region src/methods/apply-baseline.d.ts
+/**
+ * Configuration for `applyBaseline`.
+ */
+interface ApplyBaselineConfig {
+  /**
+   * Fresh off-form values (canonical rows, the read-only eval scope) to
+   * adopt in the same batch as the baseline, so formula fields recompute
+   * once against a consistent snapshot. Omit to keep the current values.
+   */
+  readonly offFormValues?: Record<string, unknown> | undefined;
+}
+/**
+ * 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).
+ */
+declare function applyBaseline(form: FormRef, record: Record<string, unknown> | null | undefined, config?: ApplyBaselineConfig): void;
+//#endregion
+//#region src/methods/array-ops.d.ts
+/**
+ * Configuration for inserting an array item.
+ */
+interface InsertConfig {
+  /**
+   * The index to insert the new item at. Appends to the end when omitted.
+   */
+  readonly at?: number | undefined;
+  /**
+   * The initial input value for the new item.
+   */
+  readonly initialInput?: unknown;
+}
+/**
+ * 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.
+ */
+declare function insert(form: FormRef, path: Path, config?: InsertConfig): void;
+/**
+ * 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.
+ */
+declare function remove(form: FormRef, path: Path, at: number): void;
+/**
+ * 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.
+ */
+declare function move(form: FormRef, path: Path, from: number, to: number): void;
+/**
+ * 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.
+ */
+declare function swap(form: FormRef, path: Path, at: number, and: number): void;
+//#endregion
+//#region src/methods/errors.d.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).
+ */
+declare function setErrors(form: FormRef, errors: FieldErrors, path?: Path): void;
+/**
+ * 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`.
+ */
+declare function getErrors(form: FormRef, path?: Path): FieldErrors;
+/**
+ * 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.
+ */
+declare function getDeepErrors(form: FormRef, path?: Path): FieldErrors;
+/**
+ * One deep-error entry: the erroring field's path and its messages.
+ */
+interface DeepErrorEntry {
+  /**
+   * The path to the erroring field (`[]` for form-level errors).
+   */
+  readonly path: Path;
+  /**
+   * The error messages of the field.
+   */
+  readonly errors: [string, ...string[]];
+}
+/**
+ * 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).
+ */
+declare function getDeepErrorEntries(form: FormRef, path?: Path): DeepErrorEntry[];
+//#endregion
+//#region src/methods/focus.d.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.
+ */
+declare function focus(form: FormRef, path: Path): void;
+//#endregion
+//#region src/methods/get-dirty-input.d.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`.
+ */
+declare function getDirtyInput(form: FormRef, path?: Path): unknown;
+//#endregion
+//#region src/methods/get-dirty-paths.d.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.
+ */
+declare function getDirtyPaths(form: FormRef, path?: Path): Path[];
+//#endregion
+//#region src/methods/get-input.d.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.
+ */
+declare function getInput(form: FormRef, path?: Path): unknown;
+//#endregion
+//#region src/methods/pick-dirty.d.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`.
+ */
+declare function pickDirty(form: FormRef, from: Record<string, unknown>): Record<string, unknown> | undefined;
+//#endregion
+//#region src/methods/reset.d.ts
+/**
+ * Configuration for resetting a form or field.
+ */
+interface ResetConfig {
+  /**
+   * The path to the field to reset. Leave undefined to reset the entire
+   * form.
+   */
+  readonly path?: Path | undefined;
+  /**
+   * The new initial input to reset to. An EXPLICIT `undefined` resets the
+   * baseline to the empty input; an OMITTED key keeps the existing
+   * baseline — the two are distinguished by key presence.
+   */
+  readonly initialInput?: unknown;
+  /**
+   * Whether to keep the current input values. Defaults to `false`.
+   */
+  readonly keepInput?: boolean | undefined;
+  /**
+   * Whether to keep the touched state. Defaults to `false`.
+   */
+  readonly keepTouched?: boolean | undefined;
+  /**
+   * Whether to keep the edited state. Defaults to `false`.
+   */
+  readonly keepEdited?: boolean | undefined;
+  /**
+   * Whether to keep the error messages. Defaults to `false`.
+   */
+  readonly keepErrors?: boolean | undefined;
+  /**
+   * Whether to keep the submitted state (form reset only). Defaults to
+   * `false`.
+   */
+  readonly keepSubmitted?: boolean | undefined;
+}
+/**
+ * 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.
+ */
+declare function reset(form: FormRef, config?: ResetConfig): void;
+//#endregion
+//#region src/methods/set-entry.d.ts
+/**
+ * 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.
+ */
+declare function setEntryMode(form: FormRef, path: Path, mode: EntryMode): void;
+/**
+ * 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.
+ */
+declare function setPercentBasis(form: FormRef, path: Path, percentBasis: string): void;
+//#endregion
+//#region src/methods/set-input.d.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.
+ */
+declare function setInput(form: FormRef, path: Path, input: unknown): void;
+//#endregion
+//#region src/methods/set-mode.d.ts
+/**
+ * Options for `setMode`.
+ */
+interface SetModeOptions {
+  /**
+   * The flip timestamp (ISO-8601) stamped into the meta half's
+   * `lastFlippedAt`. Defaults to the current time; inject for
+   * deterministic tests.
+   */
+  readonly now?: string | undefined;
+}
+/**
+ * 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).
+ */
+declare function setMode(form: FormRef, path: Path, mode: DerivationMode, options?: SetModeOptions): void;
+//#endregion
+//#region src/methods/set-off-form-values.d.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.
+ */
+declare function setOffFormValues(form: FormRef, values: Record<string, unknown>): void;
+//#endregion
+//#region src/methods/validate.d.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.
+ */
+declare function validate(form: FormRef, config?: ValidateFormInputConfig): ValidationResult;
+//#endregion
+//#region src/core/codec/decode-record.d.ts
+/**
+ * Options for `decodeRecord`.
+ */
+interface DecodeRecordOptions {
+  /**
+   * Envelope wire contracts keyed by control kind — the form store's
+   * `pluginDriver.envelopes`, or `envelopeContracts([envelopesWire])` on
+   * the server. An envelope-control field reads its WHOLE envelope from
+   * the `data` bag (falling back to the bare column value for a field
+   * whose meta was never persisted); core unwraps the value half at the
+   * leaf, and the owning plugin re-reads the meta half from the same raw.
+   */
+  envelopes?: ReadonlyMap<string, WireContract>;
+}
+/**
+ * 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.
+ */
+declare function decodeRecord(schema: JsonSchema, record: Record<string, unknown> | null | undefined, options?: DecodeRecordOptions): Record<string, unknown> | undefined;
+//#endregion
+//#region src/core/codec/encode-dirty.d.ts
+/**
+ * The save payload partitioned by record geometry: real table columns and
+ * `data` JSONB bag entries. Envelope fields (kind-discriminated union)
+ * always land WHOLE in `data`; an `x-column: true` envelope field also
+ * mirrors its value half into `columns` (a write-through scalar for SQL
+ * and list pages — the bag stays the source of truth).
+ */
+interface EncodedDirty {
+  columns: Record<string, unknown>;
+  data: Record<string, unknown>;
+}
+/**
+ * Options for `encodeDirty`.
+ */
+interface EncodeDirtyOptions {
+  /**
+   * The real table columns that exist (server-side drizzle column keys).
+   * When provided, an `x-column: true` key with no matching real column is
+   * DROPPED instead of routed to `columns` — a schema declaring a column
+   * that does not exist is an undeclared write path, and one bad key must
+   * not fail the whole save (mirrors `partitionAssetRow`).
+   */
+  knownColumns?: ReadonlySet<string>;
+  /**
+   * The plugins' static wire contracts (`[envelopesWire, derivationWire]`
+   * for the standard trio). This function is isomorphic — the server
+   * assembles the same list from the same exported descriptors, with no
+   * form store anywhere (D7). Without contracts every declared value
+   * passes through bare.
+   */
+  wire?: readonly WireContract[];
+}
+/**
+ * Builds the envelope-control lookup from a wire list.
+ */
+declare function envelopeContracts(wire: readonly WireContract[] | undefined): ReadonlyMap<string, WireContract>;
+/**
+ * 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.
+ */
+declare function encodeDirty(schema: JsonSchema, dirty: Record<string, unknown> | null | undefined, options?: EncodeDirtyOptions): EncodedDirty | undefined;
+//#endregion
+//#region src/core/derivation/merge-collection-rows.d.ts
+/**
+ * Merge a collection's canonical rows (the read model — full server rows
+ * with calc fields pre-evaluated, delivered via `offFormValues`) with the
+ * live form rows (the write model the user edits) for formula evaluation.
+ *
+ * Membership comes from the LIVE rows, so rows added or removed during the
+ * form session are respected. Each live row is enriched from the canonical
+ * row with the same `id`: live keys win (an explicit `null` means the user
+ * cleared the field), canonical fills everything the live row doesn't
+ * carry — core columns the write model never holds.
+ *
+ * One home for collection overlay (app re-exports this). The merged result
+ * is for evaluation only; it is never written back into form state.
+ */
+declare function mergeCollectionRows(canonicalRows: ReadonlyArray<Record<string, unknown>>, liveRows: unknown): Array<Record<string, unknown>>;
+//#endregion
+//#region src/core/relation/relation-config.d.ts
+/**
+ * The relation config a select/multiselect control may carry. Read
+ * straight off the schema node at render time; jsonisch's `inferControl`
+ * already classified the node select/multiselect, so this only decides
+ * WHICH picker renders and with what search filters.
+ *
+ * Core home — bagger() classifies collections with this; host widgets
+ * import it from the package root.
+ */
+interface RelationConfig {
+  /**
+   * The related domain: `entity` | `contact` | `participant` | `party` |
+   * `asset` (from the `schema://<target>` ref or the `x-relation` target).
+   */
+  target: string;
+  /**
+   * Whether the field holds many rows. Explicit `multiple` wins over the
+   * node's type — legacy data has array-typed nodes that render a single
+   * picker (e.g. loan.assignee).
+   */
+  many: boolean;
+  /**
+   * The participant role the picker searches for (drives placeholder,
+   * trait filter fallback, and the add-button label).
+   */
+  role?: string | undefined;
+  /**
+   * The trait slugs filtering the search.
+   */
+  traits?: string[] | undefined;
+  /**
+   * Restricts search to entities that are members of the entity picked in
+   * this sibling field (e.g. closingContact within lendingBranch).
+   */
+  parent?: string | undefined;
+  /**
+   * Mock search data (docs/demo surfaces only).
+   */
+  useMockData?: boolean | undefined;
+  /**
+   * The per-row nested sub-schema (stage-configured "fields on this
+   * record"; the stage loader injects it into `items`).
+   */
+  items?: JsonSchema | undefined;
+}
+/**
+ * Reads a node's relation config, or `undefined` for a plain enum
+ * select/multiselect. Two schema forms:
+ *   1. Canonical — `$ref: schema://<target>` (one) or array of that ref
+ *      (many); widget extras ride as sibling keys.
+ *   2. Vendor — `x-relation` namespace or flat `x-relation-target`;
+ *      cardinality follows the node's `type` unless `multiple` overrides.
+ */
+declare function readRelationConfig(schema: JsonSchema): RelationConfig | undefined;
+/**
+ * Maps a relation target to the party autocomplete's kind hint. The widget
+ * only knows `entity` / `contact` / undefined (= search both); join-table
+ * targets (`participant`, `party`) stay open.
+ */
+declare function targetToKind(target: string): "entity" | "contact" | undefined;
+/**
+ * The sibling field a contact picker is scoped to (`memberOfEntityId`).
+ *
+ * Explicit `x-relation-parent` always wins. When it is missing — the live
+ * artifact schema never carried the key — a contact relation whose traits
+ * include exactly one sibling entity relation's role is scoped to that
+ * sibling (LOS-860: titleOfficer traits `["title-company"]` → titleCompany).
+ * Two matches is ambiguous, so no parent is invented.
+ */
+declare function relationParentFieldName(schema: JsonSchema, path: readonly (string | number)[], relation: RelationConfig): string | undefined;
+/**
+ * The row-identity contract for a relation target. A relation whose item
+ * schema declares NO properties never reaches `withRelationRowIdentity` —
+ * its rows are a value leaf holding the whole object, with no allow-list to
+ * thin them — so a host feeding such a relation from a canonical record
+ * must project the rows against this same set itself.
+ */
+declare function relationRowIdentityProps(target: string): Record<string, JsonSchema>;
+/**
+ * Returns a schema whose multi-row relation item schemas additionally
+ * declare the row-identity keys (stage-configured keys win on collision).
+ * Apply to the STORE schema only — rendering iterates the configured keys
+ * and skips hidden controls.
+ */
+declare function withRelationRowIdentity(schema: JsonSchema): JsonSchema;
+//#endregion
+//#region src/core/dirty.d.ts
+/**
+ * Returns whether a value is semantically empty: `undefined`, `null`, the
+ * empty string, or `NaN` (what a cleared number input parses to). These are
+ * all "no value entered" and must never make a field dirty against each
+ * other — the core semantic-dirty promise.
+ */
+declare function isEmptyish(value: unknown): boolean;
+/**
+ * Semantic, empty-aware equality between two leaf inputs: equal when both
+ * are semantically empty (`null` ≡ `undefined` ≡ `""` ≡ `NaN`) or deeply
+ * structurally equal.
+ */
+declare function isSemanticEqual(a: unknown, b: unknown): boolean;
+/**
+ * Semantic equality between two container presence sentinels: `true` only
+ * equals `true`; `null` and `undefined` (absent container) are equivalent.
+ */
+declare function isPresenceEqual(a: ContainerInput, b: ContainerInput): boolean;
+//#endregion
+//#region src/plugins/derivation/resolve-scope-value.d.ts
+/**
+ * Resolves a single scalar key through the canonical scope precedence —
+ * the same order the derivation plugin evaluates formula dependencies in:
+ * the form value wins (a formula field resolves through its derived
+ * signal, so the read is always fresh; an erroring formula resolves
+ * `undefined`, never a stale number), `offFormValues` fills what the form
+ * does not hold (an off-stage field still resolves from the canonical record).
+ *
+ * For widget-side scalar reads (e.g. an amount-or-percent field resolving
+ * its percent basis). Collection overlay semantics stay inside the
+ * derivation plugin — this helper is for scalars.
+ *
+ * @param internalFormStore The form store.
+ * @param key The root-level field key to resolve.
+ *
+ * @returns The resolved value, or `undefined`.
+ */
+declare function resolveScopeValue(internalFormStore: InternalFormStore, key: string): unknown;
+/**
+ * Resolves a single scalar key in the scope of the field at `path` — the
+ * path-aware sibling of `resolveScopeValue`, and the read a widget owned by
+ * a field should use:
+ *
+ * - inside an array row, the ROW's scope (live siblings in the same row →
+ *   the canonical row from `offFormValues` matched by `id` → the parent
+ *   root record under the form's `rootRecordAlias`), so a per-row formula's inputs are ITS
+ *   row's values;
+ * - anywhere else, the document scope (`resolveScopeValue`).
+ *
+ * The same precedence the derivation graph evaluates the field's own
+ * formula in, so a widget can never display an input the value was not
+ * computed from.
+ *
+ * @param internalFormStore The form store.
+ * @param path The path of the field whose scope to resolve in.
+ * @param key The identifier to resolve.
+ *
+ * @returns The resolved value, or `undefined`.
+ */
+declare function resolveScopeValueAt(internalFormStore: InternalFormStore, path: Path, key: string): unknown;
+//#endregion
+//#region src/plugins/envelopes/wire.d.ts
+/** Discriminator of a persisted estimate / amount-or-percent envelope. */
+type EnvelopeKind = "estimate" | "amount-or-percent";
+/**
+ * Returns whether a raw persisted entry is an envelope: an object whose
+ * `kind` is `estimate` or `amount-or-percent`. Anything else — including
+ * the bare scalars every non-envelope field persists — is a bare value.
+ */
+declare function isEnvelope(raw: unknown): raw is Record<string, unknown>;
+/**
+ * Wraps an estimate field's halves into its envelope. The value key is
+ * OMITTED when `value` is `undefined` (formula mode ships
+ * `{ kind: "estimate", mode: "formula" }` and lets the server recompute
+ * author the value half).
+ */
+declare function wrapEstimate(value: unknown, meta: EstimateMeta): unknown;
+/**
+ * Wraps an amount-or-percent field's halves into its envelope. Always
+ * complete — an envelope is one bag key, so a partial write would clobber
+ * the persisted other half.
+ */
+declare function wrapAmountOrPercent(value: unknown, meta: EntryMeta): unknown;
+/**
+ * The envelopes plugin's STATIC wire contract — isomorphic by
+ * construction: the server imports this same object for save routing
+ * (`encodeDirty`), the recompute pass, and engine-less readers
+ * (changelog, list pages), with no form store anywhere (D7).
+ *
+ * Envelope shape: estimate fields persist
+ * `{ kind: "estimate", value?, mode, manualValue?, lastFlippedAt? }`,
+ * amount-or-percent fields
+ * `{ kind: "amount-or-percent", value, mode, basis? }`.
+ * Wire `mode` uses settled names (`estimate`/`formula`, `amount`/`percent`).
+ * Only these two controls grow the envelope; scalars stay bare.
+ */
+declare const envelopesWire: WireContract;
+//#endregion
+//#region src/plugins/derivation/wire.d.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.)
+ */
+declare const derivationWire: WireContract;
+//#endregion
+export { type AmountOrPercentEnvelope, type ApplyBaselineConfig, type BaggerOptions, type CalcEngine, type CalcParseResult, type CheckContext, type CheckDefinition, type CheckInstanceConfig, type CheckScope, type ChecksConfig, type ComputeBagOptions, type ControlKind, DEFAULT_EMPTY_INPUT, DEFAULT_ROOT_RECORD_ALIAS, type DecodeRecordOptions, type DeepErrorEntry, type DerivationMode, type DerivedState, type EncodeDirtyOptions, type EncodedDirty, type EntryMeta, type EntryMode, type Envelope, type EnvelopeKind, type EstimateEnvelope, type EstimateMeta, type FieldErrors, type FieldKind, type Finding, type FormConfig, type FormRef, type FormValidator, type FormulaOptions, type InsertConfig, type JsonSchema, type Path, type PathSegment, type PluginsInput, type RelationConfig, type ResetConfig, type SetModeOptions, type Severity, type SeverityConfig, type SubmitHandler, UNEVALUABLE_MESSAGE_ID, type ValidateFormInputConfig, type ValidationIssue, type ValidationMode, type ValidationResult, type VisibleWhen, type VisibleWhenOp, 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 };