@pipelex/mthds-form 0.3.0 → 0.5.0

package/dist/core/contracts.d.ts

@@ -0,0 +1,114 @@
+import { PresenceMarker, PipeIOContracts, PipeIOContract, PipeInputContract } from 'mthds/protocol';
+export { IOMultiplicity, PipeIOContract, PipeIOContracts, PipeInputContract, PipeOutputContract } from 'mthds/protocol';
+
+/**
+ * The `pipe_io_contracts` types and the kernel's gating predicates over them.
+ *
+ * The types are the STANDARD'S, imported from `mthds/protocol` and re-exported
+ * under the names this package has always exported. `pipe_io_contracts` is an
+ * MTHDS artifact - the standard specifies it (the "Pipe I/O Contracts" page)
+ * and its TypeScript client declares it - so this module states no shape of its
+ * own any more. What it keeps is the half that is genuinely the kernel's: the
+ * predicates that turn a declared slot into a gating answer, and the lookup
+ * that tolerates both key conventions a real payload arrives with.
+ *
+ * `mthds` is a TYPES-ONLY peer dependency: every import here is `import type`,
+ * so nothing survives into `dist/` and no consumer ships the standard's CLI.
+ * `scripts/assert-bundle.mjs` holds that on the built graph and lint holds it
+ * on the source. See docs/dependency-budget.md.
+ *
+ * The map itself is keyed by namespaced pipe ref (`<domain>.<pipe_code>`),
+ * NOT bare pipe code - use `getPipeIOContract` to look entries up by the bare
+ * codes the UI tracks.
+ */
+
+/**
+ * The authored presence marker on an input slot, verbatim - the standard's
+ * `PresenceMarker` under the name this package exports.
+ *
+ * - `plain` - no marker: the caller must supply the input.
+ * - `optional` (`?`) - the caller may omit it and the pipe handles the absence
+ *   itself.
+ * - `force` (`!`) - a use-site assertion that the value IS present. It must be
+ *   supplied, exactly like `plain`; the distinction is the authored assertion,
+ *   which lint and graph surfaces read and a form does not.
+ *
+ * Kept as an alias rather than renamed because a consumer imports it by this
+ * name; a host that would rather read the standard's spelling has `mthds`
+ * installed through this package's peer and can import `PresenceMarker`
+ * straight from `mthds/protocol`.
+ */
+type InputPresence = PresenceMarker;
+/** Namespaced pipe ref (`<domain>.<pipe_code>`) - the identity convention the
+ *  validate artifacts key on. */
+declare function buildPipeRef(domain: string, pipeCode: string): string;
+/**
+ * Look up a pipe's IO contract by pipe code, tolerant of both key conventions.
+ *
+ * The map may be keyed by namespaced `pipe_ref` (`<domain>.<code>`, the
+ * canonical convention) OR by bare pipe code - the current hosted `/validate`
+ * keys `pipe_structures` by bare code, and methods persisted before the
+ * pipe_ref re-keying also carry bare-code keys. Try the namespaced ref first
+ * (when the caller supplies a domain), then fall back to the bare code.
+ * Returns `undefined` (never crashes) when neither matches.
+ *
+ * Both lookups read OWN properties only. A bare index returned the inherited
+ * `Object` constructor for a pipe code named `constructor` (or `toString`, …) -
+ * a truthy non-contract that sailed straight through the `if (!contract)` guard
+ * hosts are shown writing, so a pipe that does not exist rendered as one taking
+ * no inputs instead of reaching the host's not-found path. See `ownProp`.
+ */
+declare function getPipeIOContract(pipeIoContracts: PipeIOContracts | null | undefined, domain: string | null | undefined, pipeCode: string | null | undefined): PipeIOContract | undefined;
+/**
+ * True when the method declared the input omittable (`?`).
+ *
+ * The ONE reader of `presence` in the package: everything that asks "may this
+ * be absent?" - the descriptor's `required`, the gate's `required` list, the
+ * payload builders that omit an unfilled input - goes through here, so a
+ * marker the wire adds later cannot mean one thing on one surface and another
+ * elsewhere. `force` (`!`) reads as NOT optional, like `plain`.
+ */
+declare function isOptionalInput(input: PipeInputContract): boolean;
+/**
+ * True when the input carries a plural concept (`Image[]`, `Image[3]`): its
+ * JSON Schema is an array wrapper.
+ *
+ * Deliberately a SCHEMA test rather than a read of the declared `multiplicity`,
+ * even though the wire now states both. The schema is what `buildRunFields`
+ * maps and therefore what the user is shown; a predicate reading the other
+ * field could disagree with the rendered control, which is the exact failure
+ * mode `mustBeFilled` (readiness.ts) exists to prevent. The two agree by
+ * construction upstream - the engine wraps the schema in an array exactly when
+ * it reports `variable` or `fixed`.
+ */
+declare function isPluralInput(input: PipeInputContract): boolean;
+/**
+ * True when the slot declares an EXACT number of items (`Concept[N]`), whose
+ * count is `item_count`.
+ *
+ * The distinction that matters to the gate: a variable list can legitimately be
+ * empty, a fixed one cannot.
+ */
+declare function isFixedCountInput(input: PipeInputContract): boolean;
+/**
+ * True when the user MUST put a value in before a run can start.
+ *
+ * Two declarations relieve an input of that duty, for different reasons:
+ * - **optional (`?`)** - the method itself states the caller may omit it;
+ * - **variable-plural (`[]`)** - the empty list is a legitimate value and the
+ *   language cannot declare "at least one", so gating on it would invent a
+ *   constraint the method never made.
+ *
+ * Everything else gates: `plain`, `force` (`!`), and a **fixed-count** list
+ * (`[N]`), which is a list whose empty form the method has explicitly ruled out.
+ * This is the derivation the input-form descriptor spec states for `gating`.
+ *
+ * Emptiness is all this predicate answers for - WHETHER a slot gates, never how
+ * much it needs. A fixed-count list that holds fewer items than it declares
+ * gates here and is refused by `fieldFilled`, which reads the declared count off
+ * the descriptor's `itemCount`, and by the gate's ajv pass on the schema's
+ * `minItems`. All three read the one number the method stated.
+ */
+declare function inputMustBeFilled(input: PipeInputContract): boolean;
+
+export { type InputPresence, buildPipeRef, getPipeIOContract, inputMustBeFilled, isFixedCountInput, isOptionalInput, isPluralInput };

package/dist/core/contracts.js

@@ -0,0 +1,4 @@
+export { buildPipeRef, getPipeIOContract, inputMustBeFilled, isFixedCountInput, isOptionalInput, isPluralInput } from '../chunk-XYQ7NXQZ.js';
+import '../chunk-V3OV2XQT.js';
+//# sourceMappingURL=contracts.js.map
+//# sourceMappingURL=contracts.js.map

package/dist/core/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"contracts.js"}

package/dist/core/date-format.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure conversions between a stored date value and what a native `<input
+ * type="date">` shows, plus the leniency rules our schema validation uses.
+ * Kept React-free so both the runner's `DateField` and the RJSF `DateWidget`
+ * share one source of truth (and it's trivially unit-tested).
+ *
+ * Two schema shapes reach us, and they are NOT interchangeable:
+ *   - an MTHDS `type = "date"` structure field compiles to `format: date-time`,
+ *     so its value round-trips as a full RFC 3339 timestamp;
+ *   - `native.Date`'s own `date` field is a python `datetime.date`, i.e.
+ *     `format: date` - a bare `YYYY-MM-DD`.
+ *
+ * ## Why these rules exist
+ *
+ * The runtime (pydantic) is LENIENT in both directions, and our client used to
+ * be stricter than the contract it was enforcing: `ajv`'s stock `format: "date"`
+ * accepts a bare `YYYY-MM-DD` and nothing else, so a hand-written
+ * `"2026-07-06T00:00:00Z"` in an `inputs.json` was rejected here even though
+ * pydantic accepts it happily and coerces it to `date(2026, 7, 6)`. The run
+ * never even reached the runner. These predicates mirror pydantic exactly
+ * (measured, not assumed):
+ *
+ *   format: date       "2026-07-06"                -> date(2026, 7, 6)
+ *                      "2026-07-06T00:00:00Z"      -> date(2026, 7, 6)
+ *                      "2026-07-06T00:00:00+02:00" -> date(2026, 7, 6)   (literal date, no UTC shift)
+ *                      "2026-07-06T15:40:00Z"      -> REJECTED "should have zero time"
+ *   format: date-time  "2026-07-06"                -> datetime(2026, 7, 6, 0, 0)
+ *                      "2026-07-06T00:00:00Z"      -> datetime(2026, 7, 6, 0, 0, tz)
+ *
+ * A midnight-padded timestamp is unambiguously "just a day", so take it. A real
+ * time is data - refusing it is the point (`DateContentError`: "no silent
+ * midnight"), because silently dropping 15:40 corrupts the value. And an
+ * ambiguous `06/07/2026` is never accepted by anyone: 6 July or June 7 depends
+ * on who's reading, and guessing wrong fails silently.
+ */
+/**
+ * The calendar day a value denotes, or `null` when it doesn't denote one.
+ * Accepts a bare date or a midnight-padded timestamp; the day is taken
+ * LITERALLY from the string (never shifted through a timezone), matching
+ * pydantic - `2026-07-06T00:00:00+02:00` is 2026-07-06, not the 5th.
+ */
+declare function asCalendarDate(value: string): string | null;
+/**
+ * The calendar day inside a value that carries a REAL time - precisely the case
+ * `asCalendarDate` refuses. `null` when the value isn't a timestamp at all, or
+ * when it IS already an acceptable day (nothing to report).
+ *
+ * This exists to EXPLAIN, never to coerce. `2026-07-06T14:30:00+02:00` is
+ * rejected for a `format: date` field, and the rejection is right (DT3, "no
+ * silent midnight" - dropping 14:30 corrupts the value). But telling the user
+ * "pick a valid date" while the picker shows them a perfectly good 06/07/2026
+ * reads as a lie: `toDateInputValue` renders the day, the stored value carries
+ * the time, and only one of those is what gets validated. Naming both the value
+ * we hold and the day it would have to become is what makes the error legible.
+ */
+declare function dayWithinDateTime(value: string): string | null;
+/**
+ * What `format: "date"` accepts: a bare `YYYY-MM-DD`, and nothing else.
+ *
+ * DO NOT relax this to take a midnight-padded timestamp. `DateContent` in
+ * pipelex carries a `mode="before"` field validator (`_reject_lax_temporal`)
+ * that deliberately CLOSES pydantic's lax coercion for exactly this case:
+ *
+ *   "A Date's `date` field takes a calendar date alone; a string carrying a
+ *    time (e.g. '2026-07-07T00:00:00') would drop it - put the time and offset
+ *    in `time` instead."
+ *
+ * That rule (DT3, "no silent midnight") is the concept's whole point, so a
+ * lenient client here does not help anyone: it just forwards the value and the
+ * runner answers with a 500 instead of the field saying so up front.
+ *
+ * The leniency belongs in `asCalendarDate` - normalize the pasted timestamp to
+ * the day it denotes, then this passes. Accept-and-fix, not accept-and-forward.
+ */
+declare function isAcceptableDate(value: string): boolean;
+/** What `format: "date-time"` should accept - a bare day is midnight. */
+declare function isAcceptableDateTime(value: string): boolean;
+/** The `YYYY-MM-DD` a native date input shows, from any stored date/date-time. */
+declare function toDateInputValue(value: string | undefined): string;
+/**
+ * The value to store for a picked day. A `date-time` field becomes midnight-UTC
+ * (`2026-07-06T00:00:00Z`); a plain `date` field keeps the bare `YYYY-MM-DD`.
+ * An empty day clears the value.
+ */
+declare function toStoredDateValue(day: string, datetime: boolean): string | undefined;
+
+export { asCalendarDate, dayWithinDateTime, isAcceptableDate, isAcceptableDateTime, toDateInputValue, toStoredDateValue };

package/dist/core/date-format.js

@@ -0,0 +1,3 @@
+export { asCalendarDate, dayWithinDateTime, isAcceptableDate, isAcceptableDateTime, toDateInputValue, toStoredDateValue } from '../chunk-GKV77RAS.js';
+//# sourceMappingURL=date-format.js.map
+//# sourceMappingURL=date-format.js.map

package/dist/core/date-format.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"date-format.js"}

package/dist/core/derive.d.ts

@@ -0,0 +1,55 @@
+import { PipeInputFormDescriptor, PipeInputContract, InputForm } from 'mthds/protocol';
+import { RunField } from './descriptor.js';
+import './contracts.js';
+
+/**
+ * The ONE derivation function: wire input-form descriptor → `RunField[]`.
+ *
+ * `buildRunFields` maps the standard's per-pipe descriptor STRUCTURALLY onto
+ * the kernel's `RunField` shape. It decides nothing: what a field IS - its
+ * kind, its constraints, its refinement chain, whether Run gates on it - is
+ * stated by the wire, derived by the engine from the resolved library. The
+ * heuristics that used to live here (native-concept sets, the url-bearing
+ * object test, the depth-based prose/label rule) are deleted, not bypassed;
+ * docs/derivation-swap.md is the record of that swap and of every behaviour
+ * that moved with it.
+ *
+ * The contract is still consulted, for exactly two facts the wire deliberately
+ * does not carry:
+ *
+ * - **`contentKey`** - the single property a native scalar's value sits inside
+ *   on the wire (`TextContent {text}`, `NumberContent {number}`). A renderer
+ *   holds the bare scalar; the value bridge wraps by this name. It is read off
+ *   the contract's `json_schema` because it is a fact about the PAYLOAD shape,
+ *   which is the schema's job - the descriptor describes the form, never the
+ *   payload.
+ * - **Nested list bounds** - the wire puts `item_count` only on a top-level
+ *   fixed `[N]` slot, but the model behind a structured concept may state
+ *   `minItems`/`maxItems` on an array property of its own, and ajv enforces
+ *   them. Reading them off the schema is what keeps readiness from being more
+ *   permissive than the gate.
+ *
+ * Both are structural reads (a property count, two keywords ajv itself
+ * enforces), not judgements - the mapper stays honest about owning no taxonomy.
+ */
+
+/**
+ * Look up a pipe's input-form descriptor by pipe code, tolerant of both key
+ * conventions - the exact mirror of `getPipeIOContract`, because the standard
+ * keys `input_form` by the same `pipe_ref` set as `pipe_io_contracts` and a
+ * host tracks the same bare codes either way.
+ */
+declare function getPipeInputForm(inputForm: InputForm | null | undefined, domain: string | null | undefined, pipeCode: string | null | undefined): PipeInputFormDescriptor | undefined;
+/**
+ * Map a pipe's wire input-form descriptor onto the kernel's field descriptors,
+ * with the pipe's input contracts beside it for the two schema-derived facts.
+ *
+ * The order is the DESCRIPTOR's - authored input order, the fact the contract's
+ * `inputs` map deliberately does not carry. `required`, `presence` and `gating`
+ * are taken from the wire verbatim: the standard's top-level type ties
+ * `required` to the presence marker, and `gating` is the producer-derived
+ * answer `mustBeFilled` reads - the kernel re-derives none of them.
+ */
+declare function buildRunFields(descriptor: PipeInputFormDescriptor, inputs: Record<string, PipeInputContract>): RunField[];
+
+export { buildRunFields, getPipeInputForm };

package/dist/core/derive.js

@@ -0,0 +1,6 @@
+export { buildRunFields, getPipeInputForm } from '../chunk-IIJRJGZQ.js';
+import '../chunk-OD3VYXUY.js';
+import '../chunk-XYQ7NXQZ.js';
+import '../chunk-V3OV2XQT.js';
+//# sourceMappingURL=derive.js.map
+//# sourceMappingURL=derive.js.map

package/dist/core/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"derive.js"}

package/dist/core/descriptor.d.ts

@@ -0,0 +1,172 @@
+import { InputPresence } from './contracts.js';
+import 'mthds/protocol';
+
+/**
+ * The `RunField` descriptor - the consumer-facing currency of the form kernel.
+ *
+ * A method's inputs arrive from the API as two sibling artifacts: the wire
+ * input-form descriptor (`input_form`, the ordered presentation view the MTHDS
+ * standard specifies) and the `pipe_io_contracts` entry whose `json_schema`
+ * stays the validation contract. `buildRunFields` (in `derive.ts`) maps the
+ * wire descriptor structurally onto this `RunField[]` shape - so the
+ * presentational field components never touch either wire artifact directly,
+ * and stories can describe any input shape declaratively.
+ *
+ * Pure module: no React, no API calls. Trivially unit-testable.
+ */
+
+type RunFieldKind = 'text' | 'prose' | 'date' | 'number' | 'boolean' | 'enum' | 'document' | 'image' | 'object' | 'list' | 'unknown';
+interface RunFieldCommon {
+    /** The variable identifier as written in the method (rendered in mono). */
+    name: string;
+    /** Human label; falls back to `name` when absent. */
+    title?: string;
+    /** The concept this input carries, e.g. `native.Document`, `demo.Invoice`. */
+    conceptRef?: string;
+    /**
+     * The concept's refinement chain, immediate parent first, walked to its end
+     * (`['legal.BaseClause', 'native.Text']`). Straight off the wire descriptor;
+     * absent when the concept refines nothing. "Does this refine `native.X`?" is
+     * a membership test on this list, never shape sniffing.
+     */
+    refines?: string[];
+    /** One-line helper text shown under the label. */
+    description?: string;
+    /** Required inputs always show; optional ones can collapse. */
+    required: boolean;
+    /**
+     * The authored presence marker of the pipe's input slot, verbatim - set on
+     * TOP-LEVEL fields only, like `gating`. `required` is its two-valued
+     * projection (`presence !== 'optional'`); the marker itself is carried so a
+     * renderer can distinguish the authored `!` assertion from a plain slot.
+     */
+    presence?: InputPresence;
+    /**
+     * The value applied when the caller omits the field - present only when a
+     * default was AUTHORED, never the `null` a schema projection attaches to an
+     * optional field. A defaulted field always arrives `required: false`.
+     */
+    defaultValue?: unknown;
+    /** Example values for the field, when the wire carries any. */
+    examples?: unknown[];
+    /**
+     * The node's effective intent hints - the flat `string → string` merge the
+     * language defines, carried verbatim. Non-normative: a renderer that ignores
+     * them stays correct, and nothing in the kernel's gating reads them.
+     */
+    hints?: Record<string, string>;
+    /**
+     * Whether Run waits for this input - set on TOP-LEVEL fields only, straight
+     * from `inputMustBeFilled` (see `mustBeFilled` in `readiness.ts` for why this
+     * is not the same question as `required`). Nested fields leave it undefined;
+     * they are gated through their parent's `fieldFilled`.
+     */
+    gating?: boolean;
+    /**
+     * The single property this field's value sits inside on the wire, when its
+     * concept declares a scalar content model: `native.Text` is `TextContent
+     * {text}`, `native.Number` is `NumberContent {number}`, `native.YesNo` is
+     * `YesNoContent {yes_no}`. The control still holds the plain scalar; the
+     * value bridge wraps into this property on the way out and unwraps on the way
+     * back in.
+     *
+     * A property NAME, never a schema - the descriptor stays the only currency
+     * and `buildRunFields` stays the only reader of JSON Schema. Absent whenever
+     * the value is already the whole content (a structured concept, a file, a
+     * child property of a structure): wrapping those would double-nest them.
+     */
+    contentKey?: string;
+}
+/**
+ * The constraint slots the two text kinds share, mapped from the wire's
+ * `min_length` / `max_length` / `pattern` / `format`. `format` is the open
+ * string set carrying schema formats the `date` kind does not absorb
+ * (`'time'`, `'uri'`, …); a renderer may hint on it and ignore it safely.
+ */
+interface TextConstraints {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+}
+interface TextRunField extends RunFieldCommon, TextConstraints {
+    kind: 'text';
+    placeholder?: string;
+}
+interface ProseRunField extends RunFieldCommon, TextConstraints {
+    kind: 'prose';
+    placeholder?: string;
+}
+interface DateRunField extends RunFieldCommon {
+    kind: 'date';
+    /**
+     * The wire's `datetime` flag - true when the value carries a time of day
+     * (the backing schema is `format: date-time`): the stored value is a full
+     * RFC 3339 timestamp (`2026-07-06T00:00:00Z`) so it passes the API's
+     * `date-time` validation, even though the control only asks for a day. False
+     * for a bare calendar date, where the value stays `YYYY-MM-DD`.
+     */
+    datetime: boolean;
+}
+interface NumberRunField extends RunFieldCommon {
+    kind: 'number';
+    integer: boolean;
+    min?: number;
+    max?: number;
+}
+interface BooleanRunField extends RunFieldCommon {
+    kind: 'boolean';
+}
+interface EnumRunField extends RunFieldCommon {
+    kind: 'enum';
+    options: string[];
+}
+interface FileRunField extends RunFieldCommon {
+    kind: 'document' | 'image';
+    /** Accept hint shown to the user, e.g. "PDF, PNG, JPG". */
+    accept?: string;
+}
+interface ObjectRunField extends RunFieldCommon {
+    kind: 'object';
+    fields: RunField[];
+}
+interface ListRunField extends RunFieldCommon {
+    kind: 'list';
+    /** The element descriptor (its `name` is unused; the index labels items). */
+    item: RunField;
+    /**
+     * The FEWEST items the slot accepts. Absent for a variable `Concept[]` list,
+     * which demands none.
+     *
+     * On a top-level slot this is the wire descriptor's `item_count` (present
+     * exactly on a fixed `[N]` slot); an engine emits `minItems`/`maxItems` = N
+     * on the same slot's schema, so the number `fieldFilled` gates on and the
+     * keyword ajv reads agree by construction.
+     *
+     * The wire never puts `item_count` on a NESTED list, but the model behind a
+     * structured concept may state `minItems` on an array property of its own -
+     * so on nested nodes this is read off the schema, which is the direction
+     * that cannot leave readiness more permissive than the gate.
+     */
+    itemCount?: number;
+    /**
+     * The MOST items the slot accepts, off the schema's `maxItems` (which a
+     * fixed `[N]` slot also states as N).
+     *
+     * A separate field because it is a separate fact, and conflating them is a
+     * bug that hides: `itemCount` was read as a minimum by readiness and as a
+     * maximum by the control that stops offering `Add`, which agree only while
+     * a contract states both bounds equal. A list told "at least two" was then
+     * presented as a list of exactly two.
+     */
+    maxItemCount?: number;
+}
+interface UnknownRunField extends RunFieldCommon {
+    kind: 'unknown';
+}
+type RunField = TextRunField | ProseRunField | DateRunField | NumberRunField | BooleanRunField | EnumRunField | FileRunField | ObjectRunField | ListRunField | UnknownRunField;
+/** The short, friendly category label for a concept_ref (drives the pill dot). */
+type ConceptCategory = 'text' | 'date' | 'document' | 'image' | 'number' | 'boolean' | 'choice' | 'structured' | 'list';
+declare function conceptCategory(field: RunField): ConceptCategory;
+
+export { type BooleanRunField, type ConceptCategory, type DateRunField, type EnumRunField, type FileRunField, type ListRunField, type NumberRunField, type ObjectRunField, type ProseRunField, type RunField, type RunFieldCommon, type RunFieldKind, type TextConstraints, type TextRunField, type UnknownRunField, conceptCategory };

package/dist/core/descriptor.js

@@ -0,0 +1,3 @@
+export { conceptCategory } from '../chunk-25I6JDIK.js';
+//# sourceMappingURL=descriptor.js.map
+//# sourceMappingURL=descriptor.js.map

package/dist/core/descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"descriptor.js"}

package/dist/core/gate-validator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One validation error, in the shape hosts read (`property`, `message`,
+ * `name`, `stack`, `params.format`). Structurally a superset-compatible twin of
+ * RJSF's `RJSFValidationError`, so a host surface still holding RJSF form errors
+ * (an RJSF-based inputs panel) can hand them to the same message renderer.
+ */
+interface RunInputError {
+    /** The ajv keyword that failed (`required`, `format`, `type`, …). */
+    name?: string;
+    /** Dotted path into the form data (`.quote_date.date`); for a `required`
+     *  error the missing property name is appended (top-level: no leading dot). */
+    property?: string;
+    message?: string;
+    params?: Record<string, unknown>;
+    /** The human line: `property message`, or `'title' message` when the parent
+     *  schema titles the field. */
+    stack: string;
+    schemaPath?: string;
+}
+/**
+ * Validate `data` against `schema`, returning mapped errors (empty = valid).
+ * MUTATES `data` where ajv coerces (`"20"` → `20`) - deliberate and relied on:
+ * the string the user typed is stored as a number going forward.
+ */
+declare function validateRunInputsSchema(data: unknown, schema: object): RunInputError[];
+
+export { type RunInputError, validateRunInputsSchema };

package/dist/core/gate-validator.js

@@ -0,0 +1,4 @@
+export { validateRunInputsSchema } from '../chunk-VTPUDBSJ.js';
+import '../chunk-GKV77RAS.js';
+//# sourceMappingURL=gate-validator.js.map
+//# sourceMappingURL=gate-validator.js.map

package/dist/core/gate-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"gate-validator.js"}

package/dist/core/gate.d.ts

@@ -0,0 +1,144 @@
+import { RunInputError } from './gate-validator.js';
+import { PipeInputContract, PipeIOContract } from 'mthds/protocol';
+
+type Dict = Record<string, unknown>;
+/**
+ * Combine the per-input schemas into one object schema.
+ *
+ * Each input variable becomes a property, titled with the variable name and
+ * described with the concept code. Only the inputs the method actually demands
+ * land in `required` - an optional (`?`) or variable-plural (`[]`) input must
+ * not block the form (see `inputMustBeFilled`).
+ *
+ * The per-input schema travels verbatim, which is how a fixed-count (`[N]`)
+ * list's declared count reaches ajv: pipelex states it as `minItems`/`maxItems`
+ * on the array wrapper, so the count is enforced here without the kernel
+ * restating it.
+ */
+declare function buildRunInputsSchema(inputs: Record<string, PipeInputContract>): Dict;
+/**
+ * Last-gate repair, in two passes against the exact schema ajv validates.
+ *
+ * 1. **HEAL** - persisted `inputData` may still carry the legacy double-wrapped
+ *    `{ text: { text } }` shape (or a form's state may lag a store fix).
+ * 2. **PRUNE** - RJSF fills every unset string with `""` on mount, which an
+ *    optional CONSTRAINED field rejects (`DateContent.time` is `format: "time"`)
+ *    - blocking a run on a field the user never opened. An absent optional field
+ *    is what pipelex means by `None` anyway, so dropping it is the semantically
+ *    correct repair, not a validation dodge.
+ */
+declare function prepareRunInputs(data: Dict, schema: Dict): Dict;
+interface RunInputsVerdict {
+    isValid: boolean;
+    /** Variable names the scan could pin a missing required field on. */
+    missingInputs: string[];
+    /** Raw ajv errors, for when the scan cannot name anything. */
+    errors: RunInputError[];
+}
+/**
+ * Validate PREPARED data against the combined schema.
+ *
+ * `missingInputs` is reported by VARIABLE NAME - the name on the node the user
+ * clicks - never by `concept_ref`, which used to produce "Missing required
+ * fields in: native.Text" and named neither the input at fault nor, when several
+ * inputs share a concept, which of them. Inputs the method declared omittable
+ * are skipped: an empty `?` input is not a missing one.
+ *
+ * The scan can come up empty even on an invalid form (a wrong value shape, a
+ * nested mismatch); `errors` is what the caller falls back to then, so a failure
+ * is never undiagnosable.
+ *
+ * `preparedData` is `unknown` for the same reason `gateRunInputs`' `data` is: on
+ * a public endpoint the body is whatever was sent, and ajv must be shown that
+ * rather than a repair of it, or `must be object` is a verdict no caller can
+ * ever receive. The name-the-variable scan below needs something indexable, so
+ * a body that is not a record scans against nothing and names every input the
+ * method demands - which is the honest answer for a body that carried none.
+ */
+declare function validateRunInputs(preparedData: unknown, inputs: Record<string, PipeInputContract>, schema: Dict): RunInputsVerdict;
+/**
+ * Build the `{ concept, content }` map a run expects, from PREPARED data.
+ *
+ * The two ways a method says "this may be nothing" land differently on the wire:
+ * - an **optional (`?`)** input left blank is OMITTED, so the runtime records a
+ *   real absence the method can branch on - sending `{ text: "" }` would look
+ *   like the caller supplied an empty string;
+ * - a **plural (`[]`)** input keeps its key, because a plural slot is never
+ *   absent - its empty form IS the empty list, and the runtime requires the key.
+ *   When that list is EMPTY it is sent BARE, without the envelope: the envelope
+ *   is the runtime's "explicit form", which bypasses the top-down shaper and
+ *   hands the value to the bottom-up factory, and that factory types a list from
+ *   its first item - so an empty list there raises "Cannot create Stuff from
+ *   empty list in content". The bare form keeps the shaper, which reads the
+ *   DECLARED concept and builds the empty list correctly. (pipelex/#1096 makes
+ *   the envelope agree; the bare form runs today and stays correct after.)
+ *
+ * A fixed-count (`[N]`) list takes that same empty-list path, and an empty one
+ * is not a payload the method can accept. It is unreachable through the gate,
+ * which demands the input and rejects a short list on `minItems`; building the
+ * payload straight from unvalidated data is what would reach it, and inventing
+ * a different absence here would only hide that.
+ */
+declare function apiInputsFromSchemaData(preparedData: Dict, inputs: Record<string, PipeInputContract>): Dict;
+/** The gate's verdict: the payload to send, or why the run may not start. */
+type RunInputsGateResult = {
+    ok: true;
+    inputs: Dict;
+} | {
+    ok: false;
+    /** Variable names the caller left empty or short. */
+    missingInputs: string[];
+    /** Raw ajv errors, for when the scan cannot name anything. */
+    errors: RunInputError[];
+    /** The repaired data the verdict was reached on - what
+     *  `describeValidationError` needs to quote the value it received. */
+    preparedData: Dict;
+};
+/**
+ * Gate a run: repair the caller's data, validate it against the contract,
+ * refuse anything the Run button would have refused, and build the payload.
+ *
+ * Returns a verdict rather than throwing. A server endpoint must not throw
+ * across the boundary to its client - frameworks routinely strip the message to
+ * an opaque digest in a production build - and a rejection here is an ordinary
+ * outcome, not an exceptional one.
+ *
+ * **`data` is `unknown` because that is what it is.** A run endpoint is public
+ * and no framework enforces a declared parameter type, so the argument is
+ * whatever the caller put in the body. The chain indexes the payload by
+ * variable name without first checking it is indexable, so a `null` body would
+ * throw *after* ajv had already reported `must be object` and before any
+ * verdict came back.
+ *
+ * So the two uses are separated rather than collapsed into one repair. **ajv
+ * judges the value the caller actually sent**, which is what makes `must be
+ * object` the verdict for a body that is not one; the indexing that follows
+ * uses a safe `{}` stand-in, which is what keeps the gate from throwing. Repair
+ * FIRST - coercing a non-object to `{}` before validating - is the shape that
+ * looks equivalent and is not: a contract whose inputs are all optional has an
+ * empty `required` list, so `{}` validates, and `gateRunInputs("garbage", …)`
+ * came back `ok: true` on a body the caller never meant as a run. Fail-closed
+ * costs a malformed caller an error it earned; the other direction bills a run.
+ *
+ * **The schema alone is not the rule.** ajv's `required` asserts only that a
+ * key is PRESENT, and a content model carries no `minLength` - so a required
+ * input that arrived empty (`{document: {url: ""}}`, `{text: {text: ""}}`)
+ * satisfies the schema. That is the natural payload, not a contrived one:
+ * `rjsfDataFromRunValues({}, fields)` emits exactly that when nothing is
+ * selected. So the gate re-applies the emptiness rule using
+ * `computeReadiness`'s OWN two functions over the same derived fields, which is
+ * the only way to be sure the two sides cannot disagree.
+ *
+ * Picking a pair that merely looks equivalent is not enough, and this is the
+ * whole reason the assembly lives here rather than in each host: the obvious
+ * choice, `inputMustBeFilled` + `isFilled`, agrees on every leaf kind and
+ * diverges on a structured concept in BOTH directions - `isFilled` on an object
+ * is `some(child filled)` where `fieldFilled` is `every(required child
+ * filled)`. That accepts a half-filled struct the browser refuses (a paid run
+ * past a disabled button) and rejects a filled all-optional struct the browser
+ * accepts. A host whose methods happen to use only native concepts has no test
+ * that can catch either.
+ */
+declare function gateRunInputs(contract: PipeIOContract, data: unknown): RunInputsGateResult;
+
+export { type RunInputsGateResult, type RunInputsVerdict, apiInputsFromSchemaData, buildRunInputsSchema, gateRunInputs, prepareRunInputs, validateRunInputs };