@ngis/plugin-ui 0.4.0

package/dist/src/components/plugin-ui/flow-model.d.ts

@@ -0,0 +1,303 @@
+/**
+ * The flow engine's **React-free core** (Stage 14 Y5a — **F14.4**, **F14.5**,
+ * **F14.10**, **F14.1**).
+ *
+ * No React, no host, no clock, no API client, no DOM. That is not the house
+ * style repeated for a fourth time; it is the load-bearing claim of this wave.
+ * F14.10's semantics — a node is enabled iff every required in-port is
+ * satisfied, the reason is generated from the unsatisfied port's label, and
+ * there are exactly three disclosure states — are **entirely decidable from
+ * declarative data**. A core that needed React to decide them would make
+ * "every plugin-ui component stays host-renderable from declarative data" an
+ * assertion instead of a proof, and Stage 15's worker tier is the boundary that
+ * would eventually collect on the difference. So: `<Flow>` (Y5b) holds the
+ * React state and calls this module; this module decides everything.
+ *
+ * ## What this module decides, and the three questions behind it
+ *
+ * 1. **What is bound.** {@link resolveFlow} walks F14.4's four value forms
+ *    (static literal, `{$context}`, `{$input}`, `"@ref"`) and three reference
+ *    forms (`"@id"`, `"@id.member"`, `...ngisFlowSpread("@id")`) and answers one
+ *    {@link NgisPortResolution} per in-port.
+ * 2. **What is enabled.** Satisfaction of the *required* in-ports, in
+ *    declaration order, yields {@link NgisNodeEnablement} — the boolean, the
+ *    disclosure state and the generated reason, as data.
+ * 3. **What is broken.** Anything F14.4 calls a *compile error* is a
+ *    {@link NgisFlowDefect}: a developer-facing sentence, never a rendered
+ *    string. See "Defects are data" below for why they are not thrown here.
+ *
+ * ## Why `{$context}` does not go through `compileWhenExpression`
+ *
+ * F14.10 says evaluator reuse is mandatory and names `compileWhenExpression`.
+ * It cannot apply to *value* resolution, and the reason is in the signature:
+ * `CompiledWhenExpression.evaluate(read)` returns a **`boolean`**
+ * (`src/sdk/context/when.ts:44`). There is no value channel to reuse. F14.4's
+ * own text is the resolution — form 2's payload is a *key*, not an expression
+ * ("the same `key := ident ("." ident)*` production `when` already lexes"), and
+ * a key is read, not evaluated. So this module adds **no grammar at all**: it
+ * hands the key to a reader. The clause's intent (there is no third grammar) is
+ * kept exactly; the named mechanism is simply the wrong shape for the job, and
+ * a `when`-shaped wrapper around a key read would have been the third grammar
+ * the clause forbids.
+ *
+ * The reader is a **function, not a store** (`(key) => unknown`), and that is
+ * what keeps this module pure. An unknown key is `undefined`, per F14.4.
+ *
+ * ## Defects are data, and the dev-mode throw is a separate call
+ *
+ * F14.4 calls an ambiguous `"@id"`, a non-`record` spread source and a
+ * duplicated spread key *compile errors*, and F14.5 calls a duplicate node id a
+ * development-mode error. All four are authoring mistakes with no honest
+ * end-user rendering: {@link NgisFlowReason} is a frozen two-arm union and
+ * neither arm can say "this reference is ambiguous". Throwing from inside
+ * resolution would also make the model partial, which a pure core that Y5b
+ * calls during render cannot afford. So resolution is **total** and collects
+ * {@link NgisFlowDefect}s; {@link assertFlowIsWellFormed} is the dev-gated
+ * throw, and its message is where F14.4's "lists the available members" lives.
+ *
+ * ## The two reconciliations worth reading before changing anything below
+ *
+ * **`"@run"` has two meanings in F14.4 and the destination decides which.** The
+ * general rule makes `"@id"` the node's *default output port* — for a
+ * `RunButton` that is `taskId: task`, so `"@run"` is a task handle. The
+ * "named outputs of a task node" bullet makes `"@run"` *the `NgisTaskOutput`
+ * with `primary === true`, else the first* — a file. Both are frozen text and
+ * they are not the same value. They are reconciled by the **destination port's
+ * kind**: a `task` in-port receives the handle, any other kind receives the
+ * primary output's `fileId` through {@link ngisPrimaryTaskOutput}. That is the
+ * only reading under which both sentences are true, and it is also what an
+ * author means by binding `"@run"` to an `AttributeTable`'s `resource` port.
+ *
+ * **Port ids are the member namespace — except where a reserved task member
+ * shadows one.** YD41 froze a port id as a *member name*, and `RunButton`'s out
+ * port is named `taskId`, which is also the first of F14.4's four reserved
+ * members. **Amended at the W3 merge (`V-226`):** the reserved member wins, so
+ * `"@run.taskId"` is the **id string**, not the handle. This paragraph
+ * previously said the opposite and it was the reading under which F14.22's
+ * `<TaskStatus taskId="@run.taskId">` received an object where both F14.4
+ * ("`taskId` **(string)**") and the seam (port kind `task` is "a task handle
+ * **id**") promise a string. The whole handle is still what a bare `"@run"`
+ * yields to a `task`-kind in-port, `.outputs.<name>` and named outputs are
+ * unchanged, and a colliding output stays reachable as `"@run.outputs.<name>"`.
+ */
+import type { NgisDataType, NgisTaskOutput } from "../../sdk/facets/types";
+import { type NgisFlowNode, type NgisFlowRef, type NgisNodeEnablement, type NgisPortKind, type NgisPortResolution, type NgisPortSpec, type NgisResolvedValue, type NgisTaskRefValue, type NgisTypeVerdict } from "./w3-contracts";
+/**
+ * F14.14's public rows for this session, and **exactly** those. Every one is
+ * *declared* in the kickoff seam `w3-contracts.ts` and *published* from here,
+ * so the barrels never import the seam and the seam stays a wave artifact
+ * (`packages/plugin-ui/src/index.ts`'s "W3 note"). A consumer that needs a seam
+ * name which is not a public row — `isNgisUnbound`, `NgisPortResolution`,
+ * `NGIS_PORT_ATTRIBUTES` — imports it from `./w3-contracts` by relative path,
+ * exactly as W2's consumers import `w2-contracts.ts`.
+ */
+export { ngisFlowSpread, ngisTypeVerdict } from "./w3-contracts";
+export type { NgisDisclosureState, NgisFlowNode, NgisFlowReason, NgisFlowRef, NgisFlowSnapshot, NgisInputBinding, NgisNodeEnablement, NgisPortDirection, NgisPortKind, NgisPortSpec, NgisTypeVerdict, } from "./w3-contracts";
+import type { NgisFlowSnapshot } from "./w3-contracts";
+/**
+ * The scope's nodes, keyed. **Last-wins on `id`** (F14.5): the surviving node is
+ * the last declaration, held at the position of the *first*, so re-declaring a
+ * node does not reorder the scope and the generated-reason order stays stable
+ * across a re-render. A collision is recorded rather than swallowed —
+ * {@link resolveFlow} turns each into a `duplicate-node-id` defect and
+ * {@link assertFlowIsWellFormed} throws on it outside production.
+ */
+export interface NgisFlowRegistry {
+    readonly nodes: readonly NgisFlowNode[];
+    readonly byId: ReadonlyMap<string, NgisFlowNode>;
+    /** Ids declared more than once, in first-collision order. */
+    readonly duplicateIds: readonly string[];
+}
+export declare function createFlowRegistry(declared: readonly NgisFlowNode[]): NgisFlowRegistry;
+export type NgisFlowDefectCode = 
+/** F14.5: two nodes claim one `id` in a scope. */
+"duplicate-node-id"
+/** A reference names a node the scope does not hold. */
+ | "unknown-node"
+/** A reference names neither an out port, a reserved task member nor a task
+ *  output name. `members` lists what exists. */
+ | "unknown-member"
+/** F14.4: `"@id"` on a node with several out ports and no `"value"` port.
+ *  `members` lists the available ones — never a guess. */
+ | "ambiguous-default-output"
+/** F14.4: a spread whose source port is not kind `record`. */
+ | "spread-source-not-record"
+/** F14.4: two spreads contributing the same record key. */
+ | "spread-key-conflict"
+/** The verdict does not cover this: a `task` out bound to a `resource` in. */
+ | "port-kind-mismatch"
+/** `ngisTypeVerdict === "fail"` (F14.1). Also an `invalid` resolution. */
+ | "type-mismatch"
+/** A value arrived in a shape `NgisResolvedValue` cannot hold. */
+ | "unsupported-value"
+/** F14.4 cuts ordering edges, so a data cycle is always an authoring bug. */
+ | "cycle";
+/**
+ * One authoring mistake. `message` is a **developer-facing English sentence**,
+ * never a message key and never rendered to an end user — F13.11 keeps plugin
+ * strings literal and F14.10 requires user-facing reasons to be *generated*, so
+ * these two channels stay apart on purpose. The user-facing consequence of a
+ * defect is whatever {@link NgisNodeEnablement} says.
+ */
+export interface NgisFlowDefect {
+    readonly code: NgisFlowDefectCode;
+    readonly nodeId: string;
+    /** The in-port the defect was found resolving, or `null` for a scope-level one. */
+    readonly portId: string | null;
+    readonly message: string;
+    /** For `unknown-member` / `ambiguous-default-output`: what does exist. */
+    readonly members: readonly string[];
+}
+/**
+ * A task handle, structurally. Checked rather than assumed because the out-port
+ * value arrives from Y5b's React state, i.e. from a component, i.e. from data
+ * this module did not build.
+ */
+export declare function isNgisTaskRefValue(value: unknown): value is NgisTaskRefValue;
+/**
+ * Whether an arbitrary value is one `NgisResolvedValue` can hold.
+ *
+ * The array arm needs both readings and they are distinguishable: F14.5's
+ * `resources` kind is `readonly string[]` and its `extent` kind is a
+ * four-number tuple, so an all-string array is the former and a four-number
+ * array the latter. Anything else — a mixed array, a five-number array, a
+ * nested record — is **not** representable, and `NgisContextValue` really can
+ * produce one (`readonly (string | number)[]`, `src/sdk/context/keys.ts:20`).
+ * That is why this is a guard and not a cast.
+ */
+export declare function isNgisResolvedValue(value: unknown): value is NgisResolvedValue;
+/**
+ * F14.4's default output port: the one whose id is `"value"` if the node
+ * declares it, otherwise its **single** out port. `null` means the reference is
+ * ambiguous (or the node publishes nothing) and F14.4 forbids guessing.
+ *
+ * The `"value"` literal comes from `NGIS_W2_PORT_IDS`, not from a second copy —
+ * a W3 module re-declaring the reserved member vocabulary is the defect class
+ * `V-127` names, and the seam test guards it.
+ */
+export declare function defaultOutputPort(ports: readonly NgisPortSpec[]): NgisPortSpec | null;
+export declare function portKindsCompatible(into: NgisPortKind, from: NgisPortKind): boolean;
+/**
+ * The client-side binding check over two *declared* type sets (F14.1/F14.5).
+ *
+ * Empty or absent on either side means "any type" and therefore `"pass"` —
+ * F14.5's own rule, and the reason YD44's bidirectional wildcard matters.
+ *
+ * When both sides declare several types the verdict is the **most permissive**
+ * over the cross product, and that is a deliberate asymmetry with the server:
+ * a `"fail"` here must mean *no* value the source can hold is acceptable,
+ * because `host.models.validate` is the authority on the actual dataset type
+ * and blocking a binding that could legitimately resolve would reject real
+ * graphs offline. `"warn"` never blocks either way.
+ */
+export declare function bindingDataTypeVerdict(expected: readonly NgisDataType[] | undefined, actual: readonly NgisDataType[] | undefined): NgisTypeVerdict;
+/**
+ * **F14.4's one `"@run"` rule, canonically (`V-127`, YD45).** The output with
+ * `primary === true`, else the first, else `null`.
+ *
+ * Generic over the row shape so the two host helpers delegate without a cast:
+ * `NgisResultOutput` is assignable to `NgisTaskOutput`, not the reverse.
+ *
+ * **The `fileId === null` case is decided here, explicitly, because the three
+ * pre-existing implementations disagreed about it.** This rule does **not**
+ * filter. F14.4 says "the `NgisTaskOutput` with `primary === true`; if none, the
+ * first" and says of the sibling `"@run.<name>"` rule that an absent name is
+ * unsatisfied "never silently the primary" — the whole section's principle is
+ * *never substitute*. Filtering first would silently return a **non-primary**
+ * output whenever the primary's file id has not been written yet, which is a
+ * real and common intermediate state (`fileId` fills in as a task integrates),
+ * so the substitution would be both invisible and transient. Selecting the
+ * primary and letting a `null` file id read as *unsatisfied, awaiting upstream*
+ * says the true thing: the right output is known and its file is not ready.
+ *
+ * Consequence, recorded rather than glossed: `first-party-plugins/`
+ * `terrain-quick-look/src/results.ts:62` filters *before* selecting, so making
+ * it delegate would change a shipping behaviour. It does not delegate and
+ * `V-127` stays open for that one call site — see the session note.
+ */
+export declare function ngisPrimaryTaskOutput<T extends NgisTaskOutput>(outputs: readonly T[]): T | null;
+/**
+ * Split `"@dem"` / `"@run.taskId"` into a node id and a member — **the one
+ * implementation of the rule** (`V-262`, closed by F15.14's sibling work).
+ *
+ * A node id **may** contain dots (it is an author-supplied `id` prop), which
+ * makes `"@a.b"` ambiguous in exactly the way `X9-I-5` described for context
+ * keys. The tie is broken deterministically and in the author's favour: a body
+ * that names a node **exactly** is that node with no member, and only otherwise
+ * does the first `.` split. A node literally named `a.b` sitting beside a node
+ * `a` with a member `b` is therefore addressable, and the dotted node wins.
+ *
+ * `isKnownNode` rather than a registry, so `recipe-model.ts` — which holds a
+ * plain `Map` and used to mirror this by hand — delegates instead of copying.
+ * Callers that must reject an unknown source check `isKnownNode(sourceId)`
+ * themselves; this function reports what the reference *says*, and reporting
+ * "unknown node" with the candidate list is the caller's job.
+ */
+export declare function ngisSplitFlowRef(ref: NgisFlowRef, isKnownNode: (id: string) => boolean): {
+    sourceId: string;
+    member: string;
+};
+/** F14.4 form 2's reader. A function, not a store — that is the purity seam. */
+export type NgisFlowContextReader = (key: string) => unknown;
+/**
+ * Everything outside the graph that resolution reads. Y5b owns all three and
+ * this module owns none of them.
+ */
+export interface NgisFlowState {
+    /**
+     * Out-port values, keyed by {@link ngisPortRef}. An absent key is a port that
+     * **has not produced yet**, which is what separates F14.10's `pending` from
+     * its `blocked`; a present-but-unbound value (`null`, `""`, `[]`) is the user
+     * having cleared a control, and {@link isNgisUnbound} treats the two alike.
+     *
+     * **`null` is in the type because the doc above requires it, and only the
+     * merged tree showed that it was not** (W3 merge, `V-223`). Y5a's type read
+     * `NgisResolvedValue | undefined`, which cannot hold the `null` this very
+     * comment describes, while Y5b's `<Flow>` `publish` writes exactly that `null`
+     * when a control is cleared. Neither branch could fail on its own: Y5a never
+     * built a scope and Y5b resolved against a stub whose type admitted `null`.
+     * Widened here rather than narrowing `publish`, because collapsing "cleared"
+     * onto "never produced" is what turns `blocked` into `pending` and stops the
+     * graph dimming.
+     */
+    readonly outputs: Readonly<Record<string, NgisResolvedValue | null | undefined>>;
+    /** F14.4 form 2. Absent ⇒ every `{$context}` reads `undefined`. */
+    readonly context?: NgisFlowContextReader;
+    /** F14.4 form 3. **Recipe-only, and enforcing that is Y6's** — this module
+     *  resolves `{$input}` against whatever map it is handed. */
+    readonly promoted?: Readonly<Record<string, NgisResolvedValue>>;
+}
+/** What one pass over a scope answers. */
+export interface NgisFlowResolution {
+    readonly registry: NgisFlowRegistry;
+    /** One entry per **in**-port, keyed by {@link ngisPortRef}. Out ports hold
+     *  values rather than resolutions, and `NgisPortResolution` is defined by the
+     *  seam as "what binding resolution answers for one in-port". */
+    readonly resolved: Readonly<Record<string, NgisPortResolution>>;
+    /** Registry order. */
+    readonly enablement: readonly NgisNodeEnablement[];
+    readonly enablementByNode: ReadonlyMap<string, NgisNodeEnablement>;
+    readonly defects: readonly NgisFlowDefect[];
+}
+/**
+ * Resolve a whole scope: every in-port, every node's enablement, every defect.
+ *
+ * **Total — it never throws.** A malformed graph produces defects and disabled
+ * nodes, and {@link assertFlowIsWellFormed} is the dev-mode escalation.
+ */
+export declare function resolveFlow(nodes: readonly NgisFlowNode[], state: NgisFlowState): NgisFlowResolution;
+/**
+ * The serialization hook Y6 consumes (F14.6's input, not F14.6's schema).
+ *
+ * Deliberately the graph **as declared** plus the resolutions at snapshot time.
+ * It is not pre-shaped into recipe fields: F14.6 owns the recipe schema, and a
+ * snapshot that already spoke it would put half of Y6's mapping in W3, where no
+ * clause authorizes it. Everything Y6 needs to derive promoted inputs, node
+ * `params` and the `{graph,view}` envelope is present, and nothing more.
+ *
+ * The result is plain JSON — no `Map`, no `undefined`, no function — so it
+ * round-trips through `JSON.stringify`/`parse` unchanged. That is the property
+ * Y6 and Y7 actually depend on and it is asserted, not assumed.
+ */
+export declare function flowSnapshot(resolution: NgisFlowResolution): NgisFlowSnapshot;
+export declare function assertFlowIsWellFormed(resolution: NgisFlowResolution): void;

package/dist/src/components/plugin-ui/flow-ports.d.ts

@@ -0,0 +1,155 @@
+/**
+ * **F14.5's per-component port table, as data** (Stage 14 Y5b, W3).
+ *
+ * One builder per shipped component, pure and React-free, for the reason every
+ * other model/data split in this package exists: the table is frozen, Y2–Y4 may
+ * add a port but never remove or retype one, and a test that reads the table
+ * without a DOM is what makes that claim checkable. `Flow.tsx` calls these; no
+ * component hand-writes an `NgisPortSpec`.
+ *
+ * ## What a port id is, and what a node id is (YD41)
+ *
+ * A port id is a **member name, unique within its node** — which is why four
+ * components can all publish `value` and four can all read `taskId`. The
+ * component's `id` prop is the **node** id and is scope-unique. The reserved
+ * member vocabulary is `NGIS_W2_PORT_IDS` in `w2-contracts.ts`, used here and
+ * **not re-declared**: a second copy of `value`/`taskId`/`parent`/`resource` is
+ * the `V-127` defect class.
+ *
+ * ## Labels, and why the fallback is the node id
+ *
+ * `NgisPortSpec.label` is the **generated-reason text source** (F14.10) and is
+ * never a message key — a literal plugin string or the UI schema's `label`,
+ * whose provenance is `x-display-name` → `title` → `name`. Every component takes
+ * an optional `label` prop, so when an author omits it the port still needs
+ * something a sentence can be built from; the node id is the only other thing
+ * the author actually wrote (`<ResourceSelect id="dem"/>` → *"Choose dem
+ * first"*). Falling back to the port id would produce *"Choose value first"* for
+ * every picker in the flow, which names nothing.
+ */
+import type { NgisDataType } from "../../sdk/facets/types";
+import type { NgisToolUiSchema } from "../../types/analysis";
+import type { NgisPortSpec } from "./w3-contracts";
+/**
+ * The `data-slot` each node reports.
+ *
+ * **CORRECTION.** `NgisFlowNode.slot` is documented as "from
+ * `NGIS_W2_DATA_SLOTS` or `NGIS_W3_DATA_SLOTS`", but **four of the eleven
+ * components render no component-specific `data-slot` at all**:
+ * `ResourceSelect`, `ModelSelect`, `FieldSelect` and `ExtentPicker` render only
+ * `PickerField`'s shared `ngis-picker-field` (`ExtentPicker` adds
+ * `ngis-extent-value` to an inner `<p>`), and `NGIS_W2_DATA_SLOTS` has no entry
+ * for any of them. So those four report the slot they really render. Minting
+ * four new slot names is *not* the fix: `verify-externals.mjs` fingerprints
+ * plugin-ui by these strings, W3's declared slots are `flow` and
+ * `flowInspector`, and the engine never branches on `slot` anyway — it is
+ * descriptive, and an honest description beats an invented table entry.
+ */
+export declare const NGIS_PICKER_SLOT = "ngis-picker-field";
+export declare const NGIS_FLOW_SLOTS: {
+    readonly resourceSelect: "ngis-picker-field";
+    readonly modelSelect: "ngis-picker-field";
+    readonly fieldSelect: "ngis-picker-field";
+    readonly extentPicker: "ngis-picker-field";
+    readonly paramForm: "ngis-param-form";
+    readonly runButton: "ngis-run-button";
+    readonly taskStatus: "ngis-task-status";
+    readonly taskList: "ngis-task-list";
+    readonly resultActions: "ngis-result-actions";
+    readonly attributeTable: "ngis-attribute-table";
+    readonly statChart: "ngis-stat-chart";
+};
+export interface ResourcePortOptions {
+    readonly nodeId: string;
+    readonly label?: string;
+    readonly multiple?: boolean;
+    readonly types?: readonly NgisDataType[];
+}
+/** `value: resource`, or `resources` when `multiple` (F14.5). */
+export declare function resourceSelectPorts(options: ResourcePortOptions): readonly NgisPortSpec[];
+/** `value: value`, `valueType: "string"` — the tool id (F14.5). */
+export declare function modelSelectPorts(options: {
+    readonly nodeId: string;
+    readonly label?: string;
+}): readonly NgisPortSpec[];
+/**
+ * `value: value` out, `parent: resource` in — and `parentPortId` names that
+ * **sibling in-port on the same node** (YD41), not a port on another node. The
+ * parent's value therefore arrives through one binding and one resolution path,
+ * which is what stops a `FieldSelect` having two notions of its parent.
+ */
+export declare function fieldSelectPorts(options: {
+    readonly nodeId: string;
+    readonly label?: string;
+    /** Whether the parent must be bound for this node to be enabled. */
+    readonly parentRequired?: boolean;
+}): readonly NgisPortSpec[];
+/** `value: extent` (F14.5). `NgisBounds` is `[west, south, east, north]`. */
+export declare function extentPickerPorts(options: {
+    readonly nodeId: string;
+    readonly label?: string;
+}): readonly NgisPortSpec[];
+/**
+ * `value: record` out, plus **one `in` port per required UI-schema param not
+ * satisfied internally** (F14.5).
+ *
+ * "Not satisfied internally" is the `hide` list: F14.22 writes
+ * `hide={["ELEV"]}` precisely because that param is bound by a flow port
+ * instead of rendered as a field. A param the form *renders* is satisfied by the
+ * user inside the form, so it is not an in port — otherwise every generated form
+ * would report itself blocked on its own fields, and F14.9's client validation
+ * already owns that verdict.
+ */
+export declare function paramFormPorts(options: {
+    readonly nodeId: string;
+    readonly label?: string;
+    readonly schema: NgisToolUiSchema | null;
+    readonly hide?: readonly string[];
+}): readonly NgisPortSpec[];
+/**
+ * `taskId: task` out, plus **one `in` port per bound tool input** (F14.5).
+ *
+ * "Bound" is literal: the ports are the keys of the author's `inputs`, minus the
+ * spread directives. A spread contributes *values* at resolve time and its
+ * record's keys are not known until then, so it cannot contribute a declared
+ * port — and inventing one per required schema param whenever a spread is
+ * present would give the button in ports the author never wrote.
+ *
+ * Everything about a bound input other than its name comes from the tool's UI
+ * schema, which is F14.10's provenance chain (`NgisToolUiParam.label` =
+ * `x-display-name` → `title` → `name`) reaching the reason unchanged. A name the
+ * schema does not know still gets a port — **surfaced, never dropped**, the
+ * `ExtensionSettingsForm` rule — as an optional `value` port, so it cannot
+ * silently block a run.
+ */
+export declare function runButtonPorts(options: {
+    readonly nodeId: string;
+    readonly label?: string;
+    readonly schema: NgisToolUiSchema | null;
+    /** `inputs` keys with the spread directives already removed. */
+    readonly inputNames: readonly string[];
+}): readonly NgisPortSpec[];
+/** `taskId: task` in — `TaskStatus`, `TaskList` and `ResultActions` (F14.5). */
+export declare function taskIdInPorts(options: {
+    readonly nodeId: string;
+    readonly label?: string;
+}): readonly NgisPortSpec[];
+/** `resource: resource` in (F14.5). The value is a **file** id. */
+export declare function attributeTablePorts(options: {
+    readonly nodeId: string;
+    readonly label?: string;
+}): readonly NgisPortSpec[];
+/**
+ * `taskId: task` **or** `resource: resource` in (F14.5) — whichever the author
+ * declared, which for this component is "passed the prop at all".
+ *
+ * Declaring neither is legal and means the spec is the only gate: nothing on the
+ * 0.4 surface can derive an `NgisChartSpec` from a task or a resource, so the
+ * port is a satisfaction gate rather than a data source (`statChartGate`).
+ */
+export declare function statChartPorts(options: {
+    readonly nodeId: string;
+    readonly label?: string;
+    readonly hasTaskPort: boolean;
+    readonly hasResourcePort: boolean;
+}): readonly NgisPortSpec[];

package/dist/src/components/plugin-ui/param-form-data.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `<ParamForm>`'s host reads (Stage 14 Y3 — F14.2, F14.3, F14.9).
+ *
+ * Every function takes the 0.4 facade and returns plain data, for the same
+ * reason Y2's `picker-data.ts` does: the wave's real exit criterion is that the
+ * form works **through the facade `createGisPluginHostFactory` mints**, and that
+ * is only assertable offline if the host calls are functions a node test can
+ * call. A facade assembled anywhere else is an ungated 0.4 surface every unit
+ * test calls green.
+ *
+ * ## `ParamForm` reads `uiSchema`, never `schema`
+ *
+ * `host.models.schema()` is the raw, un-normalized passthrough of
+ * `GET /api/analysis/tools/{id}/schema` and F14.2 keeps it byte-verbatim — but
+ * **ParamForm must never call it**, because a client-side re-derivation of
+ * widgets from `x-*` keys is exactly the second normalizer this stage exists to
+ * kill. `legacy-normalizer.test.ts` proves the absence rather than asserting it
+ * in prose.
+ *
+ * ## `models.validate` is Y4a's leg, and it throws on this branch
+ *
+ * F14.9's `validate-server` phase calls `host.models.validate`. That leg is
+ * wired by Y4 in the same wave; until then the facet's guard throws
+ * `NgisFacetUnavailableError` — **deliberately, because a stub that resolved
+ * empty would be indistinguishable from a clean validation**. So
+ * {@link validateSubmission} tolerates the rejection as a *surfaced notice* and
+ * never as a crash, and never as a pass: `kind: "unavailable"` is its own arm,
+ * and the form says server validation did not run.
+ */
+import { type NgisHostAPI } from "../../sdk/host-api";
+import { type NgisExecutionValidation, type NgisToolUiParam, type NgisToolUiSchema } from "../../types/analysis";
+import { type NgisParamFormState } from "./param-form-model";
+import { type NgisRunSubmission } from "./w2-contracts";
+/**
+ * Why a union rather than `NgisToolUiSchema | null`: each arm is a state the
+ * author has to be able to tell apart, and collapsing "you were refused" into
+ * "this tool has no schema" is the silent-empty-state failure the stage's stub
+ * rule exists to prevent.
+ */
+export type NgisUiSchemaLoad = 
+/** The tool, or its schema, does not exist. */
+{
+    readonly kind: "missing";
+    readonly toolId: string;
+}
+/**
+ * `ui_schema_version` is not the one this build understands. **A reader that
+ * does not know the version refuses; it never best-efforts a newer shape**
+ * (F14.2, and the same rule `recipeVersion` carries in F14.6).
+ */
+ | {
+    readonly kind: "unsupported-version";
+    readonly version: number;
+}
+/** A scope refusal, a transport failure, or the W1 stub before Y3 wired it. */
+ | {
+    readonly kind: "refused";
+    readonly message: string;
+} | {
+    readonly kind: "ready";
+    readonly schema: NgisToolUiSchema;
+};
+export declare function loadToolUiSchema(host: NgisHostAPI, toolId: string): Promise<NgisUiSchemaLoad>;
+/**
+ * The param a `field-select` follows — QGIS's `parentLayerParameterName`, whose
+ * UI-schema spelling is the passthrough extension `x-parent-param`.
+ *
+ * F14.2 emits `field-select` for no builtin, so this is only ever reached by an
+ * author's `widgets` override or a recipe's promoted input. When the extension
+ * is absent, the parent is the schema's **first `role: "input"` param**, which
+ * is the only defensible guess: a form with one dataset input has exactly one
+ * candidate, and a form with several is told to name it. `null` when there is no
+ * input param at all — reported, never guessed at.
+ */
+export declare function parentParamNameFor(schema: NgisToolUiSchema, param: NgisToolUiParam): string | null;
+/**
+ * The runtime option lists F14.9's *mutate* phase repopulates from — today only
+ * `field-select`'s. Keyed by param name, so `mutateParamForm` stays pure and the
+ * fetch stays here.
+ *
+ * A parent that cannot be resolved yields **no entry** rather than an empty
+ * list. An empty list would mean "this parent has no fields", which `mutate`
+ * would honour by clearing every unaltered value — so the difference between
+ * *unknown* and *empty* is a data-loss difference, not a cosmetic one.
+ */
+export declare function loadDependentOptionLists(host: NgisHostAPI, schema: NgisToolUiSchema, state: NgisParamFormState, widgetOf: (param: NgisToolUiParam) => NgisToolUiParam["widget"]): Promise<Readonly<Record<string, readonly string[]>>>;
+export type NgisServerValidation = {
+    readonly kind: "ok";
+    readonly validation: NgisExecutionValidation;
+}
+/**
+ * `host.models.validate` is not implemented on this facade. **Not a pass.**
+ * The form renders the reason and the submit stays governed by the client
+ * rules alone — which is the honest position, because nothing was checked.
+ */
+ | {
+    readonly kind: "unavailable";
+    readonly message: string;
+}
+/** The call was made and failed — a scope refusal, a 4xx, a transport error. */
+ | {
+    readonly kind: "failed";
+    readonly message: string;
+};
+export interface NgisValidateOptions {
+    readonly sceneId?: string;
+    readonly outputMode?: "ADD_LAYER" | "UPDATE_RESOURCE";
+    readonly targetResourceId?: string;
+}
+/**
+ * F14.9's `validate-server`. The request is built from the **same**
+ * `NgisRunSubmission` Y4 will submit, coerced through the **same**
+ * `toWireParams`, so a validate that passes cannot be followed by a run that
+ * fails on a differently-spelled `false`.
+ *
+ * `outputNames` ride in `params`: the analysis API takes an output name as an
+ * ordinary parameter key (`execution_validation.py` auto-fills a missing one),
+ * and `validate-execution` has no separate slot for them.
+ */
+export declare function validateSubmission(host: NgisHostAPI, submission: NgisRunSubmission, options?: NgisValidateOptions): Promise<NgisServerValidation>;
+/** The whole of `validate-server`'s input, derived in one place. */
+export declare function submissionOf(schema: NgisToolUiSchema, state: NgisParamFormState): NgisRunSubmission;