@ngis/plugin-ui 0.4.0

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

@@ -0,0 +1,320 @@
+/**
+ * A flow graph, serialized — **recipe JSON, the `{graph,view}` envelope, and the
+ * publish payloads** (Stage 14 Y6, W4 — F14.6).
+ *
+ * Pure: no React, no host, no `src/lib/api.ts`, no DOM. The seam this stage has
+ * now used four times, and here it is load-bearing rather than stylistic — *"a
+ * recipe is data and not code"* is a claim a React-free serializer proves and a
+ * component-entangled one only asserts. The DTO types below are imported with
+ * `import type`, which is erased, so this module has no runtime dependency on
+ * `src/api/**` while still keeping **one** source of truth per DTO. Everything
+ * that touches the wire is `recipe-data.ts`.
+ *
+ * ## The one thing to understand before reading further
+ *
+ * A `<Flow>` scope holds **more nodes than a recipe has**. Eleven components
+ * declare ports; only one of them runs a tool with inputs the server can bind —
+ * `RunButton`, whose out port is the sole `task`-kind port in F14.5's table. A
+ * `ResourceSelect` is an *interactive control*, not a computation: it has no
+ * graph node, so a reference to it can never be an edge. That single fact is
+ * where four of this session's corrections come from, and
+ * {@link recipeToolNodes} is where it is decided once.
+ *
+ * ## Where each of F14.6's four value forms ends up
+ *
+ * | flow binding | recipe | `{graph,view}` |
+ * |---|---|---|
+ * | `"@otherToolNode"` | kept verbatim (form 4) | `edges[]` |
+ * | `"@picker"` on a file port | `{ $input }` (form 3) | `inputs.<key>: ""` + an input slot |
+ * | `"@picker"` on an option port | the resolved value (form 1) | `params.<key>` |
+ * | unbound file port | `{ $input }` (form 3) | `inputs.<key>: ""` + an input slot |
+ * | anything else that resolved | the resolved value (form 1) | `params.<key>` |
+ *
+ * Contract: F14.1 (the Pascal boundary), F14.4 (value forms, `fieldMap` never),
+ * F14.5 (ports), F14.6 (recipe JSON, the mapping, the publish sequence), F14.19
+ * (review posture), F14.21 (`recipeColumns`, which stays in the seam).
+ * `w4-contracts.ts` is the kickoff seam and is read by relative path only —
+ * public recipe names come through this file, never through the seam, exactly as
+ * `flow-model.ts` publishes W3's.
+ */
+import type { CreateWorkflowToolPayload, InvokeWorkflowToolPayload } from "../../api/workflows";
+import type { NgisDataType } from "../../sdk/facets/types";
+import type { CreateReferenceVersionRequest } from "../../types/extensions";
+import type { WorkflowDagConfig } from "../../types/workflow";
+import { type NgisFlowNode, type NgisFlowSnapshot } from "./w3-contracts";
+import { type NgisRecipe, type NgisRecipeOutput, type NgisToolInputSlot, type NgisToolOutputSlot } from "./w4-contracts";
+export { NGIS_RECIPE_VERSION } from "./w4-contracts";
+export type { NgisRecipe, NgisRecipeInput, NgisRecipeNode, NgisRecipeOutput, NgisToolInputSlot, NgisToolOutputSlot, } from "./w4-contracts";
+export { recipeColumns } from "./w4-contracts";
+/**
+ * The `view` key the recipe JSON is stored under.
+ *
+ * **Not a preference — the only place it can go.** `normalizeNode` rebuilds
+ * every graph node from scratch and keeps exactly fifteen keys
+ * (`NGIS_GRAPH_NODE_KEYS`), and the lossless presentation capture that would
+ * otherwise stash the original runs **only for a non-envelope payload**
+ * (`WorkflowGraphNormalizer.java:70-77`). Y6 sends an envelope, so anything a
+ * recipe knows that the graph does not — `recipeVersion`, promoted-input ids,
+ * labels, declared `dataTypes` — is dropped on save with no error unless it is
+ * also in `view`, which the backend stores verbatim and never reads.
+ *
+ * `view` already carries `nodes`/`edges`/`viewport` for the Stage-11 canvas, so
+ * this is a sibling key rather than the whole object.
+ */
+export declare const NGIS_RECIPE_VIEW_KEY = "ngisRecipe";
+/**
+ * What a snapshot cannot tell you, and therefore what the author supplies.
+ *
+ * `outputs` is here rather than derived because a recipe output is a *decision*:
+ * F14.5 has no OUTPUT component, so no node in the scope corresponds to one, and
+ * its `outputMode` chooses what happens to a file after the run. {@link
+ * defaultRecipeOutputs} is the sane default the wizard starts from.
+ */
+export interface NgisRecipeMeta {
+    /** Stable across saves (F14.6). The wizard keeps the previous one. */
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string | null;
+    /** Defaults to {@link defaultRecipeOutputs}. Must be non-empty to publish. */
+    readonly outputs?: readonly NgisRecipeOutput[];
+    /**
+     * Node ids whose `toolId` names a **published workflow tool** rather than an
+     * analysis tool — F14.6's `kind: "recipe"`, i.e. a nested recipe.
+     *
+     * **CORRECTION — F14.6's `nodes[].kind` has no channel in the snapshot, and
+     * the kickoff's CORRECTION 2 widening does not supply one.**
+     * `NgisFlowNodeConfig` carries `toolId` and `toolVersion` and nothing else, so
+     * `tool` and `recipe` are indistinguishable from a graph alone: the only thing
+     * that separates them is the registry row's `provider`, which lives on
+     * `NgisModelSummary` and therefore behind a host read. Emitting the wrong one
+     * matters — it decides whether the node carries `modelToolId` or
+     * `workflowToolId`, and dispatch is unordered first-match over those very
+     * fields (CORRECTION 5). So it is an explicit input here, resolved through the
+     * facade by `resolveRecipeNodeKinds` in `recipe-data.ts`, and defaults to
+     * **none** — a plain `tool` node — because that is the answer for every
+     * non-nested recipe and a wrong `workflowToolId` is the more expensive
+     * mistake.
+     */
+    readonly nestedNodeIds?: readonly string[];
+}
+/**
+ * The nodes of a `<Flow>` scope that become graph nodes.
+ *
+ * **A node runs a tool iff it declares a `task` out port and carries a
+ * `config`.** Both halves are needed and neither is a component-identity check —
+ * the engine's own rule is that the registry knows nothing about a node beyond
+ * its `slot` and its ports, so the discriminator is drawn from F14.5's port
+ * table instead of from a slot allowlist:
+ *
+ *  - `<ParamForm>` also carries a `config` (it loads a UI schema, and YD49
+ *    populates the pair from it), but its out port is kind `record`. It renders a
+ *    form; it does not run anything, and a recipe with a node per form would
+ *    publish the same tool twice.
+ *  - A `<ResourceSelect>` / `<FieldSelect>` / `<ExtentPicker>` carries no config
+ *    at all.
+ *
+ * **This is the filter F14.6 needs and does not state, and without it publish
+ * fails in two different ways.** `promotableInputs` promotes any unbound
+ * `resource`-kind in-port, and two components other than `RunButton` declare
+ * one: `FieldSelect`'s `parent` and `ParamForm`'s hidden required inputs. Those
+ * would mint `ToolInputSlot`s whose `bindNodeId` names a node the graph does not
+ * contain, and `validateSlots` refuses with
+ * `"input slot <key> binds to unknown node <id>"`
+ * (`WorkflowToolSchemaService.java:187-192`) — for `ParamForm` — while
+ * `FieldSelect`'s would publish a slot that silently does nothing.
+ */
+export declare function recipeToolNodes(snapshot: NgisFlowSnapshot): readonly NgisFlowNode[];
+/**
+ * Every tool node no other tool node consumes — the terminal producers, which
+ * are exactly what `inferDraft` would have called output slots
+ * (`WorkflowToolSchemaService.java:60-68`).
+ *
+ * `ADD_LAYER` for all of them, because it is the only mode with no second
+ * required field: `UPDATE_RESOURCE` needs a `targetResourceId` **at definition
+ * save** (`WorkflowTypeCheckService.java:181-185`), so defaulting to it would
+ * produce a graph that cannot be saved.
+ */
+export declare function defaultRecipeOutputs(snapshot: NgisFlowSnapshot): readonly NgisRecipeOutput[];
+/**
+ * `NgisFlowSnapshot` → `NgisRecipe`.
+ *
+ * Two passes over each tool node, and the split is what keeps F14.4's
+ * precedence rule from being implemented twice:
+ *
+ *  1. **declared in-ports** decide promotion and edges — the only two things a
+ *     port's *binding* determines rather than its *value*;
+ *  2. **`snapshot.resolved`** bakes everything else, spread-contributed sibling
+ *     keys included. The engine already wrote that map with "later explicit keys
+ *     win over spread keys" applied (`flow-model.ts`, `V-224`), so reading it is
+ *     how this serializer avoids a second flattening rule that could disagree
+ *     with the run path. A spread that resolved and a spread that did not are
+ *     distinguishable there, which is the whole reason the directive entries
+ *     exist.
+ *
+ * **`V-224` is the reason the second pass reads resolutions rather than
+ * bindings.** `THRESHOLD` is never a declared port on a `RunButton` — F14.5
+ * gives it "one in port per bound tool *input*" and an option is not an input —
+ * so a serializer that walked `node.inputs` alone would emit no `params` at all
+ * and the published recipe would run on the schema's `default_value`. That is
+ * the wrong run, not a type error, and it is exactly what the fixture's
+ * `"THRESHOLD": "2.5"` pins.
+ */
+export declare function serializeRecipe(snapshot: NgisFlowSnapshot, meta: NgisRecipeMeta): NgisRecipe;
+/**
+ * `NgisRecipe` → the bare `{graph, view}` envelope
+ * `POST /api/workflows/definitions` takes as its **body**.
+ *
+ * `name` and `sceneId` are query parameters, not body fields (F14.6's own
+ * CORRECTION), so they are not here.
+ *
+ * Three properties of the emitted graph that are contract rather than style:
+ *
+ *  1. **Exactly one discriminator per node.** Dispatch is
+ *     `executors.stream().filter(supports).findFirst()` with no `@Order`
+ *     (`WorkflowTaskRunner.java:61-65`) and `checkAmbiguity` guards only the
+ *     `workflowToolId` combinations, so `modelToolId` **+** `type: "OUTPUT"` is
+ *     unguarded and would dispatch by classpath-scan order. A TASK node carries
+ *     `modelToolId` and no `workflowToolId`; a WORKFLOW_TOOL node the reverse; an
+ *     OUTPUT node neither.
+ *  2. **No `fieldMap`, ever** (F14.4). Despite the name it is a flat *string* —
+ *     a server-side path+pipeline expression over a task's output JSON — and the
+ *     flow layer has no model of that shape.
+ *  3. **The recipe rides in `view`.** See {@link NGIS_RECIPE_VIEW_KEY}.
+ */
+export declare function recipeEnvelope(recipe: NgisRecipe): WorkflowDagConfig;
+/**
+ * What `view` held. A reader that does not know the version **refuses** — it
+ * never best-efforts, exactly as `ui_schema_version` does not (F14.2, F14.6).
+ */
+export type NgisRecipeRead = 
+/** No recipe in this definition — a hand-built or canvas-authored DAG. */
+{
+    readonly kind: "absent";
+} | {
+    readonly kind: "unsupported-version";
+    readonly version: number;
+}
+/** Present but not the frozen shape. Reported, never silently repaired. */
+ | {
+    readonly kind: "malformed";
+    readonly reason: string;
+} | {
+    readonly kind: "ready";
+    readonly recipe: NgisRecipe;
+};
+/**
+ * Read a recipe back out of a definition's `{graph, view}`.
+ *
+ * The backend stores `view` **verbatim and never reads it**, so this is a pure
+ * round-trip of what {@link recipeEnvelope} wrote — which is what makes the
+ * envelope leg of the publish chain assertable offline without a database.
+ */
+export declare function readRecipe(config: unknown): NgisRecipeRead;
+/**
+ * Per-output publish enrichment.
+ *
+ * **CORRECTION — the kickoff's CORRECTION 8 cannot be satisfied from the recipe
+ * JSON, because F14.6's `outputs[]` has no type field.** The correction is right
+ * that an unenriched output slot serves `data_type: "file"` and makes the
+ * generated dialog show a file picker where the author declared a raster; but the
+ * frozen `NgisRecipeOutput` is `{id, label, from, outputMode, targetResourceId?}`
+ * and the seam is read-only, so there is nowhere in a recipe to record the answer.
+ * It is therefore a **publish-time** input, offered by the wizard, keyed by
+ * recipe-output id and defaulting to the `File` wildcard — which is honest
+ * (`File` really is what an unenriched slot means) rather than a guess.
+ */
+export interface NgisRecipePublishOptions {
+    readonly definitionId: string;
+    readonly name: string;
+    readonly description?: string | null;
+    /** Recipe-output id → canonical data type (F14.1). Absent ⇒ `File`. */
+    readonly outputDataTypes?: Readonly<Record<string, NgisDataType>>;
+    readonly summary?: string;
+    readonly useCases?: readonly string[];
+    readonly synonyms?: readonly string[];
+    readonly domain?: readonly string[];
+    readonly operationType?: readonly string[];
+}
+/**
+ * The explicit `inputSlots` / `outputSlots` F14.6 publishes instead of relying on
+ * `getDraft`.
+ *
+ * **Serialized by name, never positionally.** `ToolInputSlot` is
+ * `(slotKey, name, description, dataType, bindNodeId, bindInputKey, optional)`
+ * and `ToolOutputSlot` is `(slotKey, name, description, bindNodeId, dataType)` —
+ * `dataType` and `bindNodeId` are *transposed* between them, and `ToolOutputSlot`
+ * keeps a 4-arg secondary constructor so a 4-tuple compiles and yields
+ * `dataType: null`.
+ *
+ * `bindInputKey` is the field F14.6 omits and the one publish actually dies on:
+ * the record is `@JsonIgnoreProperties(ignoreUnknown = true)`, so the six-field
+ * shape posts with **no error** and fails at
+ * `WorkflowToolSchemaService.java:193-196` with `"input slot <key> is missing
+ * bindInputKey"` — and at invoke it is the key the caller's file id is injected
+ * under (`WorkflowToolService.java:421-423`), so a wrong value would put a real
+ * file under the wrong parameter.
+ *
+ * An output slot's `slotKey` is the **recipe output's id**, not the producing
+ * node's id as `inferDraft` mints it. `compileToolSchema` keys the schema's
+ * `properties` by `slotKey` and `mapOutputs` keys a nested invocation's result by
+ * it too, so two outputs off one producer would collide under `inferDraft`'s
+ * convention; `bindNodeId` still names the producer, which is what
+ * `validateSlots` and `outputNodeIds` read.
+ */
+export declare function recipeSlots(recipe: NgisRecipe, options?: Pick<NgisRecipePublishOptions, "outputDataTypes">): {
+    readonly inputSlots: readonly NgisToolInputSlot[];
+    readonly outputSlots: readonly NgisToolOutputSlot[];
+};
+/**
+ * Inputs whose declared types were **widened to the `File` wildcard** at the slot
+ * boundary.
+ *
+ * A slot carries one `dataType` and a port may declare several, so
+ * `ngisSlotDataType` widens a multi-type or untyped declaration to `File` — the
+ * only spelling that is compatible on both sides of
+ * `WorkflowTypeCheckService.compatible` and therefore the only one that preserves
+ * `types={["table","raster"]}`. The widening is lossy, so the wizard says so
+ * rather than applying it silently.
+ */
+export declare function recipeSlotWidenings(recipe: NgisRecipe): readonly {
+    readonly inputId: string;
+    readonly dataTypes: readonly NgisDataType[];
+}[];
+/** `POST /api/workflows/tools` — `PublishToolRequest`, in full. */
+export declare function recipePublishPayload(recipe: NgisRecipe, options: NgisRecipePublishOptions): CreateWorkflowToolPayload;
+/**
+ * `POST /api/workflows/tools/{toolId}/invoke` — the headless run.
+ *
+ * `inputs` is `slotKey → fileId` and a published workflow tool's whole invocable
+ * surface: `compileToolSchema` emits `x-role` of only `"input"` and `"output"`
+ * and **never `"option"`**, so there are no knobs to pass. Every option the
+ * author chose is already baked into the published snapshot's node `params`.
+ *
+ * `LIBRARY` is legal here and **illegal at definition save** — the two
+ * `outputMode` enums are different sets (CORRECTION 4) — which is why this
+ * function's mode is widened beyond `NgisRecipeOutput`'s.
+ */
+export declare function recipeInvokePayload(options: {
+    readonly inputs: Readonly<Record<string, string>>;
+    readonly sceneId?: string | null;
+    readonly outputMode?: "ADD_LAYER" | "UPDATE_RESOURCE" | "LIBRARY";
+    readonly targetResourceId?: string | null;
+}): InvokeWorkflowToolPayload;
+/**
+ * `POST /api/extensions/{extId}/versions/reference` — the `tool`-kind listing.
+ *
+ * `provider` is `"workflow"` because a published recipe lands in the shared
+ * `ngis_model_tool` id space with `provider = "workflow"` and
+ * `modelbox_id = "workflow-tools"`, which is also why `GetToolSchema(toolId)` and
+ * YB1's ui-schema endpoint resolve it exactly like a builtin.
+ *
+ * `toolVersion` is an `Integer` here while `ngis-workflow`'s node pin is a
+ * `long`, and this endpoint answers **`200`, not `201`**.
+ */
+export declare function recipeReferenceRequest(options: {
+    readonly version: string;
+    readonly minNgisVersion: string;
+    readonly toolId: string;
+    readonly toolVersion: number;
+    readonly changelog?: string | null;
+}): CreateReferenceVersionRequest;

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

@@ -0,0 +1,112 @@
+/**
+ * The host reads behind `<ResultActions>` and `<AttributeTable>` (Stage 14 Y4b).
+ *
+ * Same discipline as Y2's `picker-data.ts`: every function takes the 0.4 facade
+ * and returns plain data, so the wave's real exit criterion — "these work
+ * **through `createGisPluginHostFactory`**" — is asserted offline. A node test
+ * builds the real, scope-enforced facade and calls these, so a scope refusal or
+ * a facet stub surfaces here exactly as it would in a browser. A facade
+ * assembled anywhere else is an ungated 0.4 surface every unit test calls green.
+ *
+ * **The scopes each read needs, on record**, because a refusal has to be
+ * legible: `tasks.get`/`tasks.outputs`/`tasks.watch` are `tasks:read`,
+ * `resources.list` is `resources:read`, `viz.addResultLayer` is `viz:write`, and
+ * `viz.openTable` / `viz.chart` are **ungated** (they mutate nothing — F14.3's
+ * amendment to F13.5, already on `NGIS_UNGATED_MEMBERS`).
+ */
+import type { NgisTaskState } from "../../sdk/facets/types";
+import type { NgisChartSpec, NgisHostAPI } from "../../sdk/host-api";
+import { joinOutputs, projectResult, type NgisResultOutput, type NgisResultView } from "./result-model";
+/**
+ * The scene's `fileId → resourceId` map.
+ *
+ * The join exists because the two vocabularies really are different: a task
+ * output is addressed by **file** id (F14.4, `output-files[].file_id`) while
+ * `host.viz.openTable` takes a **scene-resource** id, and `viz.ts` rejects a
+ * file id passed in its place rather than guessing. `NgisResourceSummary.fileId`
+ * is the only bridge, and it is a `resources:read` call.
+ */
+export declare function loadResourceIdsByFileId(host: NgisHostAPI): Promise<ReadonlyMap<string, string>>;
+/**
+ * One coherent read of "where is this run, and what can be done with it".
+ *
+ * The output fallback is the interesting half. `NgisTaskState.outputs` is
+ * populated from the tracked task's `outputFiles`, which the DIRECT runtime
+ * fills after the run succeeds — but a component that attached to an
+ * already-finished task (or a WORKFLOW run whose instance was polled before its
+ * outputs were fetched) can legitimately see `SUCCESS` with `outputs: []`. So a
+ * terminal-success state with no outputs asks `host.tasks.outputs` once. It is
+ * **not** treated as "this run produced nothing": that conflation is what would
+ * make a real result look like an empty one, which is the failure mode F13.5's
+ * refusal rule exists to prevent.
+ */
+export declare function readResultView(host: NgisHostAPI, taskId: string | null, state?: NgisTaskState | null): Promise<NgisResultView>;
+/**
+ * The post-hoc path (`viz:write`). Registers a scene resource for the output's
+ * file id when absent, then adds a layer — which is precisely what the
+ * submit-time path would have done, and the reason `ResultActions` only offers
+ * this in the `detached` and `integration-failed` phases.
+ */
+export declare function addResultOutputLayer(host: NgisHostAPI, output: NgisResultOutput, name?: string): Promise<{
+    resourceId: string;
+    layerId: string;
+}>;
+/**
+ * Ungated. Rejects with a named message when the resource has no layer in the
+ * scene — the attribute panel targets the *selected layer's* dataset, so the
+ * resource must be rendered first. Surfaced, never swallowed.
+ */
+export declare function openResultTable(host: NgisHostAPI, output: NgisResultOutput): Promise<void>;
+/** Ungated (F14.3). The host renders the declarative spec; the plugin ships no
+ *  chart code, which is what keeps this survivable into Stage 15's worker tier. */
+export declare function renderResultChart(host: NgisHostAPI, spec: NgisChartSpec): Promise<void>;
+/**
+ * Public default for ResultActions' field chart. The data read stays behind the
+ * resource facet, so a plugin gets the same scope enforcement and lab-scene
+ * isolation as every other smart component instead of importing an app API.
+ */
+export declare function buildResultFieldChart(host: NgisHostAPI, output: {
+    fileId: string;
+    name: string | null;
+}, field: string): Promise<NgisChartSpec>;
+/**
+ * What `<AttributeTable>` can learn about the file id on its `resource` in-port.
+ *
+ * Four arms rather than "a name or nothing", for the same reason
+ * `NgisFieldLoad` has four: each is a state an author has to be able to tell
+ * apart, and collapsing "not in this scene" into "no name" would hide a resource
+ * that was removed.
+ */
+export type NgisTableTarget = 
+/** The in-port is unsatisfied. */
+{
+    readonly kind: "no-resource";
+}
+/** The file id matches no resource in the open scene. */
+ | {
+    readonly kind: "unresolved";
+    readonly fileId: string;
+}
+/** Resolved, but attributes are vector-only. */
+ | {
+    readonly kind: "not-vector";
+    readonly type: string;
+} | {
+    readonly kind: "ready";
+    readonly fileId: string;
+    readonly resourceId: string;
+    readonly name: string;
+};
+/**
+ * `resources:read`. Resolves the parent exactly the way `FieldSelect` does —
+ * through `resources.list()` keyed on `fileId` — because `resources.get` takes a
+ * scene-resource id and the port carries a file id (F14.5).
+ *
+ * The `not-vector` arm matters: `GisAttributeTable` queries
+ * `datasets/{fileId}/attributes/*`, which only a vector dataset answers. Handing
+ * it a raster would render an error inside the wrapped grid instead of a reason
+ * beside the control.
+ */
+export declare function loadTableTarget(host: NgisHostAPI, fileId: string | null): Promise<NgisTableTarget>;
+/** Re-exported so a caller can build a view from outputs it already holds. */
+export { joinOutputs, projectResult };

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

@@ -0,0 +1,96 @@
+/**
+ * `<ResultActions>`'s whole decision, as one pure projection (Stage 14 Y4b,
+ * **F14.5** / **F14.10**).
+ *
+ * ## The distinction this module exists to keep visible: complete ≠ integrated
+ *
+ * `NgisTaskStatus` is the *run*. `NgisTaskStage` is the *lifecycle including
+ * scene integration*. `status: "SUCCESS"` with `stage:
+ * "waiting_scene_integration"` is a real and common state, and it is why
+ * `analysis-task-runtime.ts` runs an integration poll **alongside** the SSE
+ * stream rather than trusting the stream's terminal write. `integration_status`
+ * is a separate axis, so a result surface that collapsed the two would offer a
+ * post-hoc "add to map" the instant a task went `SUCCESS` — racing the
+ * submit-time integration that is already on its way and producing a duplicate
+ * layer.
+ *
+ * That is the whole reason {@link NgisResultPhase} has six terminal-ish arms
+ * instead of `succeeded | failed`:
+ *
+ * | phase | `status` / `stage` | what it means for the actions |
+ * |---|---|---|
+ * | `no-task` | the `taskId` in-port is unsatisfied | nothing to act on; a reason, not a dead control (F14.10) |
+ * | `running` | `submitting` / `QUEUED` / `RUNNING` | the run is still going |
+ * | `integrating` | `SUCCESS` + `waiting_output_datasets` \| `waiting_scene_integration` \| `refreshing_scene` | **complete, not integrated.** No post-hoc add — submit-time integration owns this |
+ * | `integrated` | `SUCCESS` + `success`, every output resolved to a scene resource | the scene has it; open the table, chart it |
+ * | `detached` | `SUCCESS` + `success`, ≥1 output is not a scene resource | this is what `host.viz.addResultLayer` is *for* |
+ * | `integration-failed` | `SUCCESS` + `failed` | the computation happened, the lifecycle did not — post-hoc add is the recovery |
+ * | `failed` / `cancelled` | `FAILED` / `CANCELLED` | there is no output |
+ *
+ * **Submit-time integration is the preferred path** and is reached by passing
+ * `sceneId`/`outputMode` to `tasks.run` (Y4a's `RunButton`). `addResultLayer` is
+ * the post-hoc path, and `detached` / `integration-failed` are the only two
+ * phases where offering it is honest.
+ *
+ * ## No `disabled`, anywhere
+ *
+ * F14.10: enablement is derived, and a nothing-to-show state renders a *reason*
+ * rather than a dead control. So this module returns which actions are
+ * *available* plus the phase that explains the rest, and `ResultActions` renders
+ * the reason through `PickerField`'s notice slot. Nothing here produces text —
+ * the component translates the phase under `GIS.pluginUi.run.result.*`.
+ */
+import type { NgisTaskOutput, NgisTaskState } from "../../sdk/facets/types";
+export type NgisResultPhase = "no-task" | "running" | "integrating" | "integrated" | "detached" | "integration-failed" | "failed" | "cancelled";
+/**
+ * One task output, joined to the scene. `resourceId` is the join `host.viz`
+ * needs and `NgisTaskOutput` does not carry: outputs are addressed by **file**
+ * id (F14.4), while `viz.openTable` takes a **scene-resource** id, and the join
+ * is `NgisResourceSummary.fileId`.
+ */
+export interface NgisResultOutput {
+    readonly fileId: string;
+    /** The declared output parameter's name (DIRECT) or the producing node id
+     *  (WORKFLOW). `null` when the wire carried none. */
+    readonly name: string | null;
+    readonly primary: boolean;
+    /** `null` when this output is not (yet) a resource in the open scene. */
+    readonly resourceId: string | null;
+}
+export interface NgisResultView {
+    readonly phase: NgisResultPhase;
+    /** File-id-bearing outputs only. An output row with no `file_id` cannot be
+     *  added, opened or charted, so carrying it would only produce dead controls. */
+    readonly outputs: readonly NgisResultOutput[];
+    /** Post-hoc `host.viz.addResultLayer` would do something. */
+    readonly canAddLayer: boolean;
+    /** At least one output is a scene resource, so `host.viz.openTable` resolves. */
+    readonly canOpenTable: boolean;
+    /** The run produced something, so charting a spec over it is meaningful. */
+    readonly canChart: boolean;
+    /** The run's or the integration's own message, verbatim. Never invented. */
+    readonly error: string | null;
+}
+export declare function joinOutputs(outputs: readonly NgisTaskOutput[], resourceIdByFileId: ReadonlyMap<string, string>): readonly NgisResultOutput[];
+/**
+ * The projection. `resourceIdByFileId` is the scene's `fileId → resourceId` map
+ * (`host.resources.list()`); an empty map is a scene with no resources, not a
+ * missing read, and it correctly yields `detached` for a successful run — which
+ * is exactly the state post-hoc add exists for.
+ */
+export declare function projectResult(state: NgisTaskState | null, resourceIdByFileId: ReadonlyMap<string, string>): NgisResultView;
+/**
+ * The one output a bare `"@run"` reference resolves to: `primary === true`, else
+ * the first (F14.4, and `executors/base.py` guarantees at most one `primary`).
+ * `ResultActions` acts on this by default so the common single-output case needs
+ * no picking.
+ *
+ * **Delegates to the canonical rule (`V-127`, YD45)**, generically, because
+ * `NgisResultOutput` is assignable to `NgisTaskOutput` and not the reverse.
+ * Behaviour is unchanged: every caller reaches this through {@link joinOutputs},
+ * which has already dropped the file-id-less rows, so the canonical rule's
+ * decision *not* to filter is a no-op on this path.
+ */
+export declare function primaryOutput(outputs: readonly NgisResultOutput[]): NgisResultOutput | null;
+/** A stable, human-ish name for an output row. Never a key — see F13.11. */
+export declare function outputLabel(output: NgisResultOutput): string;

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

@@ -0,0 +1,118 @@
+/**
+ * The host calls behind `RunButton` / `TaskStatus` / `TaskList` (Stage 14 Y4a).
+ *
+ * Every function takes the 0.4 facade and returns plain data, for the same reason
+ * `picker-data.ts` does: the wave's real exit criterion is "these components work
+ * **through `createGisPluginHostFactory`**", and that is only assertable offline
+ * if the host reads live above the components rather than inside a `useEffect`.
+ * A scope refusal (`NgisScopeError`) or a facet stub therefore surfaces here
+ * exactly as it would in a browser, and nothing below swallows one.
+ *
+ * ## The DIRECT/WORKFLOW branch is not here, and must never be
+ *
+ * F13.2 puts the fork inside `host.tasks` — `run()` branches on the resolved
+ * model's `provider` and `watch()` attaches to the store-backed SSE pipeline for
+ * DIRECT or starts a poll timer for WORKFLOW. This module calls one API and does
+ * not know which branch it got. The one place the difference is *visible* is
+ * {@link hasLogStream}, which reads the `kind` the facet already reported rather
+ * than re-deciding it.
+ *
+ * ## The order of operations, which is F14.9 and not a preference
+ *
+ * `validate` **always runs once before submit**. {@link runSubmission} is the
+ * only sanctioned path for that reason: it validates, refuses on a blocking
+ * verdict, and submits only afterwards. A caller that has already validated on
+ * change still goes through it — a debounced validation can be stale by the time
+ * the button is pressed, and the final call is the one that counts.
+ */
+import type { NgisHostAPI } from "../../sdk/host-api";
+import type { NgisModelValidateRequest, NgisTaskHandle, NgisTaskState, NgisTaskWatcher } from "../../sdk/facets/types";
+import type { NgisExecutionValidation } from "../../types/analysis";
+import { type NgisRunGate } from "./run-model";
+import { type NgisRunSubmission } from "./w2-contracts";
+/** Run-shaping options a submission does not carry (they are the caller's, not
+ *  the generated form's). Mirrors `NgisTaskRunRequest` plus `targetSrid`, which
+ *  only the validate leg takes. */
+export interface NgisRunOptions {
+    sceneId?: string;
+    /** Lab-scene optimistic fence. Ordinary scene runs leave this absent. */
+    expectedSceneGeneration?: number;
+    outputMode?: "ADD_LAYER" | "UPDATE_RESOURCE";
+    targetResourceId?: string;
+    /** `validate-execution` only — `POST /api/analysis/tasks` has no such field. */
+    targetSrid?: number;
+}
+/**
+ * The `host.models.validate` request for one submission.
+ *
+ * Note what is **absent**: `owner_id`. F14.3 is explicit that it comes from the
+ * authenticated caller and is never read from a body, which is why
+ * `NgisModelValidateRequest` has no such member to fill in.
+ */
+export declare function validateRequestOf(submission: NgisRunSubmission, options?: NgisRunOptions): NgisModelValidateRequest;
+/** F14.9's server-validation leg. `models:read` — it runs nothing. */
+export declare function validateRun(host: NgisHostAPI, submission: NgisRunSubmission, options?: NgisRunOptions): Promise<NgisExecutionValidation>;
+/**
+ * `host.tasks.run`, with the bindings folded into `params`.
+ *
+ * `models:run` — running a model is the privileged act (F13.5). The handle's
+ * `kind` tells the caller which branch the facade took, and that is the only
+ * place the fork is observable from out here.
+ */
+export declare function submitRun(host: NgisHostAPI, submission: NgisRunSubmission, options?: NgisRunOptions): Promise<NgisTaskHandle>;
+/** What one press of a run action produced. Exactly one of the three arms. */
+export type NgisRunOutcome = 
+/** Validation answered, and it blocks. Nothing was submitted. */
+{
+    readonly kind: "blocked";
+    readonly validation: NgisExecutionValidation;
+    readonly gate: NgisRunGate;
+} | {
+    readonly kind: "submitted";
+    readonly validation: NgisExecutionValidation;
+    readonly gate: NgisRunGate;
+    readonly handle: NgisTaskHandle;
+}
+/** The validate or the run call itself rejected — a scope refusal, a transport
+ *  failure, a facet stub. Surfaced, never folded into `blocked`: "the server
+ *  says no" and "we could not ask" are different things to tell an author. */
+ | {
+    readonly kind: "error";
+    readonly error: unknown;
+    readonly phase: "validate" | "submit";
+};
+/**
+ * **F14.9's "always once before submit", implemented once.**
+ *
+ * The whole sequence lives in one function so the guarantee is a property of the
+ * code rather than of a component remembering to call two things in order. A
+ * `RunButton` that validated in an effect and submitted in a click handler would
+ * satisfy the letter of the clause only as long as nobody reordered the handler.
+ */
+export declare function runSubmission(host: NgisHostAPI, submission: NgisRunSubmission, options?: NgisRunOptions): Promise<NgisRunOutcome>;
+/**
+ * **F14.10's single sanctioned publication out of a flow scope.**
+ *
+ * Flow state is component-local; every `host.context.set` notifies the
+ * dependency index and re-evaluates every compiled expression whose read-set
+ * intersects, so publishing per-port values would put per-keystroke traffic
+ * through the global index. Exactly one value leaves: the task id, and only so a
+ * plugin can gate a status-bar badge on it.
+ *
+ * **The key is bare.** `host.context.set` auto-namespaces (F14.11), and passing
+ * a prefixed key is rejected rather than re-prefixed — a component that wrote
+ * `plugin:<id>:taskId` itself would double-prefix or throw
+ * `NgisContextKeyError`, depending on which spelling the store is on. Writing
+ * `"taskId"` is correct under both.
+ */
+export declare function publishTaskId(host: NgisHostAPI, taskId: string): Promise<void>;
+/**
+ * `host.tasks.watch`, unwrapped.
+ *
+ * Thin on purpose — the branch, the equality guard and the "no workflow SSE"
+ * decision all live in the facet, and a wrapper that added its own would be a
+ * second notion of when a task changed. `tasks:read`.
+ */
+export declare function watchTask(host: NgisHostAPI, taskId: string, listener: (state: NgisTaskState) => void): NgisTaskWatcher;
+/** `tasks:cancel`. Resolves; the state change arrives through the watcher. */
+export declare function cancelTask(host: NgisHostAPI, taskId: string): Promise<void>;