@ngis/plugin-ui 0.4.0

package/dist/src/components/plugin-ui/w4-contracts.d.ts

@@ -0,0 +1,510 @@
+/**
+ * W4 shared contracts — authored at the **W4 kickoff**, read-only to Y6 and Y7.
+ *
+ * Stage 14's wave rule, fourth application. The three previous seams froze
+ * *types*; this one froze types and **behaviour**, and the reason is the W3 merge:
+ * `w3-contracts.ts` pinned every data type the two Y5 halves exchanged and none
+ * of the functions, so the stub and the real core agreed on every shape and
+ * disagreed on four behaviours — one of which (`V-224`) submitted a **wrong run**
+ * rather than failing to compile. A signature is not a seam. So where W4's two
+ * sessions would otherwise each write the same rule, **the rule is implemented
+ * here once, with tests**, and neither session owns a copy:
+ *
+ *   {@link ngisWorkflowDataType}  — the Pascal boundary spelling (F14.1)
+ *   {@link promotableInputs}      — which in-ports become slots / columns (F14.6)
+ *   {@link recipeColumns}         — a published recipe's batch columns (F14.21)
+ *
+ * Ownership:
+ *
+ *   Y6 owns the recipe serializer, the `{graph,view}` mapping, the six-leg
+ *       publish chain and the wizard: `recipe-model.ts`, `recipe-data.ts`,
+ *       `RecipeWizard.tsx`, plus the `workflowApi` visibility leg.
+ *   Y7 owns the batch table: `batch-model.ts`, `BatchTable.tsx`, and the
+ *       `ModelSelect`-onto-`models.search` upgrade inherited from YD46.
+ *
+ * Nothing here imports React, a host, or `src/api/**`. That is what keeps the
+ * recipe layer **host-renderable from declarative data** — the property Stage 15's
+ * worker tier depends on, and the reason a recipe is data and not code.
+ *
+ * **Not re-exported from either barrel**, exactly as `w2-contracts.ts` and
+ * `w3-contracts.ts` are not: consumers import it by relative path. Public rows
+ * come through the owning session's model file, never through the seam.
+ *
+ * Contract: F14.1 (types), F14.4 (value forms), F14.5 (ports), F14.6 (recipe
+ * schema, the `{graph,view}` mapping, the publish sequence), F14.19 (review
+ * posture), F14.21 (batch). **Eleven kickoff corrections to that text are marked
+ * `KICKOFF CORRECTION` where they occur**; all eleven were verified against
+ * backend source, and each is recorded in the plan-of-record's Decisions table.
+ * None changes a clause's intent; every one is a place where following the frozen
+ * text literally produces something that does not publish, or publishes wrongly
+ * in silence.
+ */
+import type { NgisDataType } from "../../sdk/facets/types";
+import type { NgisFlowNode, NgisFlowNodeConfig, NgisFlowSnapshot, NgisInputBinding, NgisPortKind } from "./w3-contracts";
+/** F14.6. A reader that does not know the version **refuses**; it never
+ *  best-efforts, exactly as `ui_schema_version` does not (F14.2). */
+export declare const NGIS_RECIPE_VERSION: 1;
+/** F14.21, same rule. */
+export declare const NGIS_BATCH_VERSION: 1;
+/**
+ * W4's `data-slot` additions. The eight W2 names live in `w2-contracts.ts` and
+ * W3's two in `w3-contracts.ts`; these four extend the same table, and the same
+ * rule applies — a duplicate makes `verify-externals.mjs`'s plugin-ui
+ * fingerprint ambiguous.
+ */
+export declare const NGIS_W4_DATA_SLOTS: {
+    readonly recipe: "ngis-recipe";
+    readonly recipeWizard: "ngis-recipe-wizard";
+    readonly batchTable: "ngis-batch-table";
+    readonly batchRow: "ngis-batch-row";
+};
+/**
+ * The canonical → **Pascal** spelling for `ToolInputSlot.dataType` /
+ * `ToolOutputSlot.dataType` and for a graph node's declared slot types.
+ *
+ * **KICKOFF CORRECTION 1 — F14.1 documents this column in prose and ships no
+ * map, and the failure is silent in both directions.**
+ * `WorkflowTypeCheckService.compatible` is
+ * `a.equals(b) || "File".equals(a) || "File".equals(b)`
+ * (`WorkflowTypeCheckService.java:103-105`) — case-sensitive `String.equals`, with
+ * Pascal `"File"` as the hardcoded wildcard. So writing `"raster"` into a slot
+ * does **not** raise "unknown type": it compares unequal to a builtin node's
+ * `"Raster"`, is not the wildcard either, and the edge is rejected as
+ * *incompatible* with a `400` at workflow save that names the wrong problem.
+ * Writing `"file"` is worse — it loses wildcard status and starts rejecting
+ * bindings that should warn.
+ *
+ * **`ToolInputSlot`'s own Java comment is wrong** and says lowercase
+ * (`ToolInputSlot.java:11`, `// raster | vector | table | file ...`). The
+ * ui-schema layer is immune because it squashes to lowercase on read
+ * (`ui_schema.py:41-48`) and the checked-in workflow fixture is Pascal
+ * (`tests/fixtures/ui_schema/us7-workflow.json:30`), so the two halves of the
+ * backend disagree about which spelling is canonical and only one of them is
+ * enforced. Pascal is the enforced one.
+ *
+ * Applied at, and **only** at, the `ngis-workflow` boundary (YD3) — never in a
+ * recipe's own `dataTypes`, which stay canonical lowercase.
+ */
+export declare const NGIS_WORKFLOW_DATA_TYPES: Readonly<Record<NgisDataType, string>>;
+/** The Pascal spelling for one canonical type. Total over `NgisDataType`. */
+export declare function ngisWorkflowDataType(type: NgisDataType): string;
+/**
+ * The slot spelling for a port that declares several types, or none.
+ *
+ * A slot carries **one** `dataType`, a port may declare many (F14.5's
+ * `dataTypes?: readonly NgisDataType[]`). F14.6 says "`dataTypes[0]` becomes
+ * `ToolInputSlot.dataType`", which is right for the single-type case and wrong
+ * for the rest: taking the first of `["table","raster"]` publishes a slot that
+ * type-checks against `Table` only and rejects the raster the author explicitly
+ * allowed. **A multi-type or absent declaration widens to `File`**, which is the
+ * wildcard on both sides of `compatible` and is therefore the only spelling that
+ * preserves the author's intent. The widening is lossy and deliberate; Y6
+ * surfaces it in the wizard rather than applying it silently.
+ */
+export declare function ngisSlotDataType(dataTypes: readonly NgisDataType[] | undefined): string;
+/**
+ * `NgisFlowNodeConfig` — the tool a node runs, and the version it was authored
+ * against. Declared in `w3-contracts.ts` because it is a member of
+ * `NgisFlowNode` and the alternative is a circular import; re-exported here so
+ * W4's two sessions read it from their own seam, like every other W4 name.
+ *
+ * **KICKOFF CORRECTION 2 — the W3 snapshot cannot express F14.6's recipe nodes,
+ * and this is the wave's load-bearing finding.** `NgisFlowNode` is
+ * `{id, slot, ports, inputs}` (`w3-contracts.ts:103-113`): there is **no
+ * `toolId` and no `toolVersion` anywhere in the snapshot graph**, while F14.6
+ * requires `nodes[].toolId` + `nodes[].toolVersion` and F14.21 requires the same
+ * two on a batch config. `flowSnapshot` is asserted *closed* against exactly this
+ * (`flow-model.test.ts:512-514` pins the absence of a `params` key;
+ * `flow-host.test.ts:801` pins the snapshot's key set), so Y6 and Y7 would each
+ * have had to reach around the snapshot for information W3 never put in it — and
+ * would each have invented a different way to do it.
+ *
+ * It is a *widening*, not a redesign, because the information is already in scope
+ * at the declaration sites and was simply never given a channel: `paramFormPorts`
+ * and `runButtonPorts` both take the full `NgisToolUiSchema`
+ * (`flow-ports.ts:178-182`, `:236-242`), which carries `tool_id` and
+ * `tool_version` (`src/types/analysis.ts:126-128`). The kickoff threads it
+ * through `NgisFlowPortDeclaration` → the registry → the snapshot, and populates
+ * it at `ParamForm.tsx` and `RunButton.tsx`. Optional, because nine of the eleven
+ * components run no tool.
+ *
+ * **`toolVersion` is what the author saw, not a guarantee about the run.** The
+ * server re-resolves and *overwrites* every node's version at publish —
+ * `pinToolVersions` (`WorkflowToolService.java:389-408`) calls `GetToolSchema`
+ * per node and does `((ObjectNode) n).put("toolVersion", resolvedVersion)` at
+ * `:406`. So the pin is authoritative in the recipe JSON and in the saved
+ * definition, and **advisory** on the published snapshot. A test asserting the
+ * pinned version survives into the published tool asserts the opposite of what
+ * the server does.
+ */
+export type { NgisFlowNodeConfig } from "./w3-contracts";
+/** A node's tool, or `null` for the nine components that run none. */
+export declare function nodeConfigOf(node: NgisFlowNode): NgisFlowNodeConfig | null;
+/**
+ * Build a node's `config` from whatever the component has to hand, or
+ * `undefined` when it has neither.
+ *
+ * One derivation in one place, because the two producers read the pair from two
+ * differently-spelled sources — `ParamForm` from its loaded
+ * `NgisToolUiSchema` (`tool_id` / `tool_version`, snake_case on the wire per
+ * YD6) and `RunButton` from the `NgisRunSubmission` it is about to submit
+ * (`toolId` / `toolVersion`, camelCase). Returning `undefined` rather than `null`
+ * is deliberate: `JSON.stringify` drops an `undefined` value, so a node with no
+ * tool stringifies in `useFlowPort`'s memo exactly as it did before W4 and does
+ * not re-register.
+ */
+export declare function ngisNodeConfig(toolId: string | null | undefined, toolVersion: number | null | undefined): NgisFlowNodeConfig | undefined;
+/**
+ * An in-port that becomes a recipe input, a published `ToolInputSlot`, and a
+ * batch column — the three names for one thing.
+ */
+export interface NgisPromotableInput {
+    readonly nodeId: string;
+    /** The in-port member name. */
+    readonly portId: string;
+    /**
+     * `ToolInputSlot.bindInputKey` — always equal to {@link portId}, and carried
+     * as its own field anyway. **This is the field F14.6 omits** (CORRECTION 7),
+     * and omitting it cannot fail at compile time on the wire, so it is spelled
+     * once here where a publisher cannot miss it rather than left as a fact about
+     * `portId` that a reader has to know.
+     */
+    readonly bindInputKey: string;
+    /**
+     * `"<nodeId>.<portId>"` — `ToolInputSlot.slotKey`, and the key the caller
+     * supplies a file id under in `InvokeToolRequest.inputs`. The format is not a
+     * choice: `inferDraft` mints exactly `node.id + "." + key`
+     * (`WorkflowToolSchemaService.java:57`) and the checked-in workflow ui-schema
+     * fixture carries `clip.input` / `fill.dem`.
+     */
+    readonly slotKey: string;
+    /** F14.5's `label`, the generated-reason source. Never a message key. */
+    readonly label: string;
+    readonly kind: "resource" | "resources";
+    /** Canonical (F14.1). The Pascal spelling is applied only at publish. */
+    readonly dataTypes: readonly NgisDataType[];
+    readonly required: boolean;
+}
+/**
+ * Which of a flow graph's in-ports promote out of the recipe.
+ *
+ * **F14.6's rule, in one implementation.** *"Only file inputs promote"*, and a
+ * promoted input serializes as a **present but empty** `inputs.<key>` with no
+ * incoming edge — that absence of an edge is precisely what makes it a slot,
+ * because `inferDraft` derives one for *every unbound key of every node's
+ * `inputs` object* (`WorkflowToolSchemaService.java:43-71`). So "promotable"
+ * means exactly: a `resource`/`resources` in-port with **no upstream reference
+ * bound to it**.
+ *
+ * Three exclusions, each for a different reason:
+ *
+ *   - **kind not `resource`/`resources`** — an option. `compileToolSchema` emits
+ *     `x-role` of only `"input"` or `"output"` and **never `"option"`**
+ *     (`WorkflowToolSchemaService.java:74-98`, verified verbatim), so a published
+ *     workflow tool has no knobs at all; its whole invocable surface is
+ *     `Map<String,String> inputs`. Option values therefore bake into node
+ *     `params` at serialization or they are lost.
+ *   - **bound to an `"@ref"`** — fed by an upstream node, so it is an edge, not a
+ *     slot. `..."@ref"` spread directives are skipped for the same reason and are
+ *     never ports at all (`isNgisFlowSpreadKey`).
+ *   - **a `{$input}` binding** — already promoted; re-promoting it would mint a
+ *     second slot for one input.
+ *
+ * A static (form 1) or `{$context}` (form 2) value on a *file* input is a real
+ * ambiguity that F14.6 does not address, and it is resolved in the safe
+ * direction: **it still promotes**, because a recipe's whole purpose is to run
+ * against fresh inputs and baking one authoring session's file id into a
+ * published tool would produce a tool that always reads the author's data. Y6
+ * surfaces the overridden value in the wizard as the slot's default.
+ *
+ * Order is declaration order — node order in the registry, then port order
+ * within a node — so the generated column order and the generated slot order are
+ * the same order the author wrote, and are stable across saves.
+ */
+export declare function promotableInputs(snapshot: NgisFlowSnapshot): readonly NgisPromotableInput[];
+/**
+ * Whether a promotable input carries an authored value that the wizard should
+ * offer as the slot's default. Kept next to {@link promotableInputs} because the
+ * two decisions are one rule read from opposite ends, and because
+ * `isNgisUnbound` is the single boundness predicate (the W2 `toWireParams`
+ * lesson: a satisfaction check that disagrees with a render check is a control
+ * that is enabled and then refuses).
+ */
+export declare function promotedDefaultOf(node: NgisFlowNode, portId: string): string | null;
+/**
+ * F14.6's promoted input, as it appears in recipe JSON.
+ *
+ * `kind` is `NgisPortKind` minus `task` and `record`, per F14.6 — but only
+ * `resource`/`resources` can actually arrive here, because the other three are
+ * options and options do not promote (see {@link promotableInputs}). The wider
+ * type is kept so a future clause can widen the *rule* without a schema change.
+ */
+export interface NgisRecipeInput {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: Exclude<NgisPortKind, "task" | "record">;
+    /** Canonical lowercase (F14.1). */
+    readonly dataTypes: readonly NgisDataType[];
+    readonly required: boolean;
+    readonly default: string | null;
+}
+/**
+ * A recipe node. `kind: "recipe"` is a nested recipe and is **IN for v1** — the
+ * whole substrate exists server-side and none of it is Y6's to build:
+ * `validateAtPublish` computes cross-tool depth against
+ * `workflow.nested.max-depth` (default **3**) and caps
+ * `max-nodes-per-dag` (default **10**), `checkAmbiguity` rejects a node carrying
+ * `workflowToolId` beside another discriminator, and `invokeNested` re-checks at
+ * runtime. **Y6 adds no client-side depth guard**; it surfaces the server's
+ * message, which is why nested recipes need `readApiErrorMessage`.
+ *
+ * **SCRIPT nodes are OUT of v1 recipes** — a recipe is the data tier and carries
+ * no code. (Independently, nothing in the workflow canvas emits them either.)
+ */
+export interface NgisRecipeNode {
+    readonly id: string;
+    readonly kind: "tool" | "recipe";
+    /** An analysis tool id, or a published workflow tool id. */
+    readonly toolId: string;
+    /** See {@link NgisFlowNodeConfig} — advisory once published. */
+    readonly toolVersion: number;
+    /** Param name → one of F14.4's four value forms. */
+    readonly bindings: Readonly<Record<string, NgisInputBinding>>;
+}
+/**
+ * A recipe output.
+ *
+ * **KICKOFF CORRECTION 3 — `outputMode` and `targetResourceId` belong here, and
+ * F14.6's own JSON example puts them in the wrong place.** The clause's mapping
+ * table is right (*"each `outputs[]` entry → `{id, type:"OUTPUT", outputMode,
+ * targetResourceId?}`"*) and its JSON snippet contradicts it by hanging both
+ * fields off the **tool** node, where they are inert:
+ * `validateOutputNodes` only inspects nodes whose `type` is `OUTPUT`
+ * (`WorkflowTypeCheckService.java:166-186`), and no executor reads `outputMode`
+ * off a TASK node.
+ *
+ * **KICKOFF CORRECTION 4 — the recipe-level and invoke-level `outputMode` enums
+ * are different sets, and nothing in F14.6 says so.** An OUTPUT node accepts
+ * `ADD_LAYER` / `SCENE_LAYER` / `UPDATE_RESOURCE` / `SCENE_RESOURCE` and nothing
+ * else (`:174-180`); `LIBRARY` — perfectly legal in `InvokeToolRequest`
+ * (`InvokeToolRequest.java:8`) — is a **`400` at definition save**. And
+ * `UPDATE_RESOURCE` **requires** a non-null `targetResourceId` *at save time*
+ * (`:181-185`), not at run time, which is why it is a discriminated union here:
+ * the illegal combination should not be constructible.
+ */
+export type NgisRecipeOutput = {
+    readonly id: string;
+    readonly label: string;
+    /** A reference form (F14.4) naming the producing node. */
+    readonly from: string;
+    readonly outputMode: "ADD_LAYER";
+    readonly targetResourceId?: never;
+} | {
+    readonly id: string;
+    readonly label: string;
+    readonly from: string;
+    readonly outputMode: "UPDATE_RESOURCE";
+    /** Required at *save*, not at run. */
+    readonly targetResourceId: string;
+};
+/** F14.6's recipe JSON, exactly. */
+export interface NgisRecipe {
+    readonly recipeVersion: typeof NGIS_RECIPE_VERSION;
+    /** Stable across saves. */
+    readonly id: string;
+    readonly name: string;
+    readonly description: string | null;
+    readonly inputs: readonly NgisRecipeInput[];
+    readonly nodes: readonly NgisRecipeNode[];
+    readonly outputs: readonly NgisRecipeOutput[];
+}
+/**
+ * The `type` values a recipe maps onto in the `{graph,view}` envelope, and the
+ * field that actually dispatches each one.
+ *
+ * **KICKOFF CORRECTION 5 — dispatch is unordered first-match, so a node carrying
+ * two discriminators is undefined behaviour rather than an error.**
+ * `WorkflowTaskRunner.java:61-65` takes `executors.stream().filter(supports).findFirst()`
+ * and **no executor carries `@Order`**. `NestedToolGuardService.checkAmbiguity`
+ * guards the `workflowToolId` combinations only, so `modelToolId` **+**
+ * `type:"OUTPUT"` is unguarded and dispatches by Spring's classpath-scan order.
+ * A serializer must therefore emit **exactly one** discriminator per node —
+ * which is a property of the mapping, not something the server will catch.
+ *
+ * `type` is display-only for TASK/WORKFLOW_TOOL (dispatch reads the *fields*),
+ * but Y6 emits it anyway so a persisted graph reads correctly, and it is
+ * matched case-insensitively for OUTPUT (`equalsIgnoreCase`).
+ */
+export declare const NGIS_RECIPE_NODE_TYPES: {
+    readonly tool: {
+        readonly type: "TASK";
+        readonly discriminator: "modelToolId";
+    };
+    readonly recipe: {
+        readonly type: "WORKFLOW_TOOL";
+        readonly discriminator: "workflowToolId";
+    };
+    readonly output: {
+        readonly type: "OUTPUT";
+        readonly discriminator: "type";
+    };
+};
+/**
+ * **KICKOFF CORRECTION 6 — the fifteen keys that survive a save, and why the
+ * list is a contract rather than trivia.**
+ *
+ * `WorkflowGraphNormalizer.normalizeNode` (`:81-113`) rebuilds every node from
+ * scratch and copies exactly these fifteen keys. Everything else is dropped. The
+ * part that matters: the lossless presentation capture (`buildViewFromRaw`,
+ * `:136-151`, which stashes a whole original node under `view.nodes[id]`) runs
+ * **only when the payload is not already an envelope** (`:70-77`). Once a client
+ * sends `{graph, view}` — which Y6 does — any node key outside this list that is
+ * not *also* duplicated into `view` is **permanently lost on save**, with no
+ * error. A recipe's own fields (`recipeVersion`, promoted-input ids, labels) are
+ * not on this list, so **the recipe JSON must be persisted in `view`**, which the
+ * backend stores verbatim and never reads.
+ *
+ * Also: a blank string is dropped rather than stored as `null` (`putText`
+ * `:245-247`), a non-numeric `toolVersion` is silently discarded (`:99-102`), and
+ * an edge missing either endpoint is **silently discarded** (`normalizeEdge`
+ * returns `null`, consumed at `:66-68`) — so a mis-spelled node id in an edge is
+ * a missing dependency, not a refusal.
+ */
+export declare const NGIS_GRAPH_NODE_KEYS: readonly ["id", "type", "params", "inputs", "outputs", "options", "modelToolId", "toolType", "workflowToolId", "toolVersion", "inputFileKey", "outputMode", "targetResourceId", "name", "script"];
+/**
+ * An edge, after normalization. **Output keys are `from`/`to`/`fromOutput`/
+ * `toInput`/`fieldMap` and never `source`/`target`** — those are accepted as
+ * *input* aliases only, with `fromNodeId` beating `source` beating `from`
+ * (`normalizeEdge`, `:115-129`).
+ *
+ * **`fieldMap` is never emitted and never parsed** (F14.4). Despite the name it
+ * is a single flat *string*, not a map — a server-side path+pipeline expression
+ * over a task's output JSON, a shape the flow layer has no model of.
+ */
+export declare const NGIS_GRAPH_EDGE_KEYS: readonly ["from", "to", "fromOutput", "toInput"];
+/**
+ * `ToolInputSlot`, as the server actually declares it.
+ *
+ * **KICKOFF CORRECTION 7 — F14.6 omits `bindInputKey`, and the omission cannot
+ * fail at compile time. This is the single most expensive defect the kickoff
+ * found.** F14.6 freezes the input slot as
+ * `(slotKey, name, description, dataType, bindNodeId, optional)` — six
+ * components. `ToolInputSlot.java:8-15` is a **seven**-component record with
+ * `bindInputKey` between `bindNodeId` and `optional`. Because the record carries
+ * `@JsonIgnoreProperties(ignoreUnknown = true)`, posting the six-field shape
+ * raises **no** error: `bindInputKey` deserializes to `null`, publish proceeds
+ * as far as `validateSlots`, and dies at `WorkflowToolSchemaService.java:193-196`
+ * with `"input slot <slotKey> is missing bindInputKey"` — a `400` naming a field
+ * the frozen contract never mentions. A client built exactly to F14.6 cannot
+ * publish anything.
+ *
+ * It is not a cosmetic omission either: `bindInputKey` is the key the caller's
+ * file id is injected under at invoke time —
+ * `inputsNode.put(slot.bindInputKey(), fileId)`
+ * (`WorkflowToolService.java:421-423`) — so a wrong value would inject a real
+ * file under the wrong parameter.
+ *
+ * **Serialize by name, never positionally.** Both are Java records and their
+ * component orders are *transposed*: `dataType` is 4th on input and 5th on
+ * output, `bindNodeId` is 5th on input and 4th on output. `ToolOutputSlot`
+ * additionally keeps a 4-arg secondary constructor for pre-S11b rows
+ * (`ToolOutputSlot.java:15-17`), so a 4-tuple compiles and silently yields
+ * `dataType: null`.
+ */
+export interface NgisToolInputSlot {
+    readonly slotKey: string;
+    readonly name: string;
+    readonly description: string | null;
+    /** **Pascal** (F14.1). See {@link ngisSlotDataType}. */
+    readonly dataType: string;
+    readonly bindNodeId: string;
+    /** The node-`inputs` key the file id is injected under. Never omit it. */
+    readonly bindInputKey: string;
+    readonly optional: boolean;
+}
+/**
+ * `ToolOutputSlot` (`ToolOutputSlot.java:8-18`).
+ *
+ * **KICKOFF CORRECTION 8 — publish `dataType` explicitly or the recipe's own
+ * generated dialog is wrong.** `inferDraft` builds output slots through the
+ * 4-arg constructor (`WorkflowToolSchemaService.java:67`), so every *inferred*
+ * slot has `dataType: null`; `compileToolSchema` then omits `x-data-type`
+ * entirely, and `ui_schema.py`'s `_resolve_data_type` falls back to
+ * `canonical_data_type(None) == "file"` (`:59-68`). An unenriched recipe
+ * therefore serves `data_type: "file"` for its outputs, and the generated dialog
+ * (F14.6's own exit criterion, backlog `V-12`) shows a file picker where the
+ * author declared a raster. Y6 publishes explicit `outputSlots` — which F14.6
+ * already requires for a different reason — and this is the second reason.
+ */
+export interface NgisToolOutputSlot {
+    readonly slotKey: string;
+    readonly name: string;
+    readonly description: string | null;
+    readonly bindNodeId: string;
+    /** **Pascal** (F14.1), and never `null` from Y6. */
+    readonly dataType: string;
+}
+/**
+ * The hand-rolled refusals `POST /api/workflows/tools` raises, verbatim.
+ *
+ * **KICKOFF CORRECTION 9 — `PublishToolRequest` carries zero validation
+ * annotations and the controller does not `@Valid` it.** Every check is
+ * hand-written in `WorkflowToolService.publish` / `validateSlots`, so these
+ * messages *are* the contract, and they only reach a client at all because YB2
+ * set `include-message: always` for this service. Frozen here so Y6's tests
+ * assert the real strings and so the wizard can map them to a field.
+ */
+export declare const NGIS_PUBLISH_REFUSALS: {
+    readonly missingDefinitionId: "definitionId is required";
+    readonly missingName: "name is required";
+    readonly noOutputSlot: "at least one output slot is required";
+    /** `+ " <slotKey> is missing bindInputKey"` — see the correction above. */
+    readonly missingBindInputKey: "is missing bindInputKey";
+    readonly unknownInputNode: "binds to unknown node";
+};
+/** F14.21's batch config, exactly. Saved and loaded as JSON. */
+export interface NgisBatchConfig {
+    readonly batchVersion: typeof NGIS_BATCH_VERSION;
+    readonly toolId: string;
+    readonly toolVersion: number;
+    /** UI-schema param names, in display order. */
+    readonly columns: readonly string[];
+    /** One run per row. Values are the wire spelling — always strings. */
+    readonly rows: readonly Readonly<Record<string, string>>[];
+    readonly outputMode: "ADD_LAYER" | "UPDATE_RESOURCE";
+    readonly sceneId: string | null;
+}
+/**
+ * F14.21's concurrency cap. **Not a tuning knob.** The task fabric and the
+ * `UsageLimiter` windows are shared, and there is no global concurrency limit
+ * anywhere below this line — `analysis-task-runtime.ts`'s `taskControllers` map
+ * is keyed by task id and bounds nothing — so a 50-row batch fired at once is a
+ * self-inflicted outage.
+ */
+export declare const NGIS_BATCH_CONCURRENCY = 3;
+/**
+ * A batch cell's DOM/node id.
+ *
+ * **KICKOFF CORRECTION 10 — a batch table inside a `<Flow>` needs per-(row,param)
+ * ids or it silently loses cells.** Four of the twelve widgets delegate to
+ * components that are themselves flow nodes (`resource-select` and
+ * `resource-multi` → `ResourceSelect`, `field-select` → `FieldSelect`, `extent`
+ * → `ExtentPicker`), and each uses its `id` prop **as the flow node id**
+ * (`ResourceSelect.tsx:90-105`). The registry is **last-wins on id**
+ * (`w3-contracts.ts:99-102`), so N rows rendering the same param would collapse
+ * to one node — a `console.error` in development and, in production, N-1 cells
+ * bound to nothing. `ParamForm` already avoids this with
+ * `` `${scopeId}-${param.name}` `` (`ParamForm.tsx:493`); batch needs the row in
+ * the key too.
+ */
+export declare function ngisBatchCellId(scopeId: string, rowIndex: number, paramName: string): string;
+/**
+ * A published recipe's batch columns.
+ *
+ * F14.21: *"Batch works over a published recipe too: its promoted inputs are the
+ * columns."* This is the one function both sessions read — Y6 produces the
+ * recipe, Y7 consumes it — so it exists once. Column order is the recipe's own
+ * input order, which is {@link promotableInputs}' declaration order, which is
+ * the order the author wrote.
+ */
+export declare function recipeColumns(recipe: NgisRecipe): readonly string[];

package/dist/src/components/ui/button.d.ts

@@ -0,0 +1,12 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | null | undefined;
+    size?: "default" | "xs" | "sm" | "lg" | "icon" | "icon-xs" | "icon-sm" | "icon-lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type ButtonProps = React.ComponentProps<"button"> & VariantProps<typeof buttonVariants> & {
+    asChild?: boolean;
+};
+declare function Button({ className, variant, size, asChild, ...props }: ButtonProps): import("react/jsx-runtime").JSX.Element;
+export { Button, buttonVariants };
+export type { ButtonProps };

package/dist/src/components/ui/checkbox.d.ts

@@ -0,0 +1,4 @@
+import * as React from "react";
+import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
+declare function Checkbox({ className, ...props }: React.ComponentProps<typeof CheckboxPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+export { Checkbox };

package/dist/src/components/ui/column-resize-handle.d.ts

@@ -0,0 +1,23 @@
+import type { PointerEvent } from "react";
+/**
+ * The draggable boundary at the trailing edge of a resizable column header.
+ *
+ * Sits absolutely inside a header cell marked `data-column-cell` (which
+ * {@link useColumnResize} measures at drag start), so the cell must be
+ * `relative` and must not clip its overflow — put `truncate` on an inner span,
+ * never on the cell itself. Straddles the boundary via `translate-x-1/2`: the
+ * grab target is wider than the hairline it paints, and lands in the gutter
+ * rather than eating the neighbour's padding.
+ */
+export declare function ColumnResizeHandle({ label, active, onStart, onNudge, onReset, className, }: {
+    /** Accessible name — the column being sized, not the word "handle". */
+    label: string;
+    /** This column is the one currently being dragged. */
+    active?: boolean;
+    onStart: (event: PointerEvent<HTMLElement>) => void;
+    /** Keyboard resize by `delta` px, relative to the current rendered width. */
+    onNudge: (delta: number, from: HTMLElement) => void;
+    /** Restore the column's default width (double-click / Escape-free reset). */
+    onReset: () => void;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/src/components/ui/dropdown-menu.d.ts

@@ -0,0 +1,25 @@
+import * as React from "react";
+import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
+declare function DropdownMenu({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuPortal({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuTrigger({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuContent({ className, sideOffset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Group>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuItem({ className, inset, variant, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+    inset?: boolean;
+    variant?: "default" | "destructive";
+}): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuCheckboxItem({ className, children, checked, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuRadioGroup({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuRadioItem({ className, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuLabel({ className, inset, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+    inset?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuSeparator({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuShortcut({ className, ...props }: React.ComponentProps<"span">): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuSubTrigger({ className, inset, children, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+    inset?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+declare function DropdownMenuSubContent({ className, ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>): import("react/jsx-runtime").JSX.Element;
+export { DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, };

package/dist/src/components/ui/input.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+declare function Input({ className, type, ...props }: React.ComponentProps<"input">): import("react/jsx-runtime").JSX.Element;
+export { Input };

package/dist/src/components/ui/label.d.ts

@@ -0,0 +1,4 @@
+import * as React from "react";
+import * as LabelPrimitive from "@radix-ui/react-label";
+declare function Label({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+export { Label };

package/dist/src/components/ui/popover.d.ts

@@ -0,0 +1,10 @@
+import * as React from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+declare function Popover({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+declare function PopoverTrigger({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Trigger>): import("react/jsx-runtime").JSX.Element;
+declare function PopoverContent({ className, align, sideOffset, ...props }: React.ComponentProps<typeof PopoverPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+declare function PopoverAnchor({ ...props }: React.ComponentProps<typeof PopoverPrimitive.Anchor>): import("react/jsx-runtime").JSX.Element;
+declare function PopoverHeader({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+declare function PopoverTitle({ className, ...props }: React.ComponentProps<"h2">): import("react/jsx-runtime").JSX.Element;
+declare function PopoverDescription({ className, ...props }: React.ComponentProps<"p">): import("react/jsx-runtime").JSX.Element;
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor, PopoverHeader, PopoverTitle, PopoverDescription, };

package/dist/src/components/ui/select.d.ts

@@ -0,0 +1,15 @@
+import * as React from "react";
+import * as SelectPrimitive from "@radix-ui/react-select";
+declare function Select({ ...props }: React.ComponentProps<typeof SelectPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+declare function SelectGroup({ ...props }: React.ComponentProps<typeof SelectPrimitive.Group>): import("react/jsx-runtime").JSX.Element;
+declare function SelectValue({ ...props }: React.ComponentProps<typeof SelectPrimitive.Value>): import("react/jsx-runtime").JSX.Element;
+declare function SelectTrigger({ className, size, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+    size?: "sm" | "default";
+}): import("react/jsx-runtime").JSX.Element;
+declare function SelectContent({ className, children, position, align, ...props }: React.ComponentProps<typeof SelectPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+declare function SelectLabel({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Label>): import("react/jsx-runtime").JSX.Element;
+declare function SelectItem({ className, children, ...props }: React.ComponentProps<typeof SelectPrimitive.Item>): import("react/jsx-runtime").JSX.Element;
+declare function SelectSeparator({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.Separator>): import("react/jsx-runtime").JSX.Element;
+declare function SelectScrollUpButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>): import("react/jsx-runtime").JSX.Element;
+declare function SelectScrollDownButton({ className, ...props }: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>): import("react/jsx-runtime").JSX.Element;
+export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, };

package/dist/src/components/ui/switch.d.ts

@@ -0,0 +1,6 @@
+import * as React from "react";
+import * as SwitchPrimitive from "@radix-ui/react-switch";
+declare function Switch({ className, size, ...props }: React.ComponentProps<typeof SwitchPrimitive.Root> & {
+    size?: "sm" | "default";
+}): import("react/jsx-runtime").JSX.Element;
+export { Switch };