@ngis/plugin-sdk 0.4.0

package/dist/src/sdk/facets/types.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Stage 13 (capability contract) — the frozen type text for the four **core**
+ * 0.4 facets: `scene`, `resources`, `models`, `tasks`.
+ *
+ * Every interface below is **F13.2 verbatim**
+ * (`docs/capability_contract_stage/README.md` → "Frozen contracts (X0)").
+ * Signature text is the contract; the JSDoc here is richer than the frozen
+ * text, never narrower. A session that needs a change here stops and raises
+ * it — it does not diverge locally, because XB1's validator tests and X4's
+ * parser tests must round-trip the *same* fixtures.
+ *
+ * **Worker-readiness (L6, binding on every signature).** Every method is
+ * `async` and takes/returns JSON-serializable values; every observation is a
+ * subscription returning the existing synchronous `NgisUnsubscribe`. The one
+ * handle-returning method here (`tasks.watch`) returns an object whose members
+ * are themselves async — proxyable as an RPC handle. No facet ever returns a
+ * DOM node, a React element, a class instance, or a function other than
+ * `NgisUnsubscribe`.
+ *
+ * No runtime *imports*, so a worker/RPC tier can consume the contract without
+ * pulling the host's implementation in with it. Stage 14's W1 kickoff adds two
+ * runtime *exports* — `NGIS_DATA_TYPES` and `NGIS_DATA_TYPE_TO_RESOURCE_TYPES`
+ * (F14.1 puts them in this file by name) — which are self-contained frozen data
+ * and preserve that property.
+ *
+ * ## Stage 14 (F14.1, F14.3) — kickoff-authored, read-only to W1 sessions
+ *
+ * The canonical `NgisDataType` vocabulary and the three additive `models` legs
+ * plus `viz.chart` were authored at the **W1 kickoff**
+ * (`docs/components_flow_stage/README.md` → F14.24). **No F13.2 member
+ * changes.** A session that needs a change here stops and raises it.
+ */
+import type { AnalysisToolSchema } from "../../api/analysis";
+import type { SceneType } from "../../api/scenes";
+import type { NgisExecutionValidation, NgisToolUiSchema } from "../../types/analysis";
+import type { NgisBounds, NgisUnsubscribe } from "../map-api";
+export interface NgisSceneInfo {
+    id: string;
+    name: string;
+    /** `"MAP" | "ANALYSIS" | "GIS"` — `SceneType` from `src/api/scenes.ts`. */
+    type: SceneType;
+    ownerId: string | null;
+    /** Drives `storage.scene` writability and the `scene.isOwner` context key. */
+    isOwner: boolean;
+    resourceCount: number;
+    layerCount: number;
+}
+export interface NgisSceneFacet {
+    /** `null` on an unsaved scratch workspace — boot-payload plugins still run there. */
+    get(): Promise<NgisSceneInfo | null>;
+    onChange(listener: (scene: NgisSceneInfo | null) => void): NgisUnsubscribe;
+}
+/**
+ * XD7. `"table"` is in the union for forward compatibility and is **never
+ * emitted in v1** — see F13.6.
+ *
+ * Classification is `DatasetInfo.datasetType`: `VECTOR`→`vector`,
+ * `RASTER`→`raster`, everything else **including `GENERIC`**→`file`. Producing
+ * `"table"` would need `NgisFile.fileType`, i.e. a second
+ * `GET /api/files/{fileId}` per resource — an N+1 fan-out for a distinction no
+ * v1 consumer needs.
+ */
+export type NgisResourceType = "vector" | "raster" | "table" | "file";
+/**
+ * **The one wire vocabulary for port and parameter data types (F14.1).**
+ *
+ * Six vocabularies existed; this one is canonical from here on, and it is
+ * **lowercase** — which makes {@link NgisResourceType} a strict subset, so no
+ * shipped plugin, no shipped `when` expression and no shipped fixture changes.
+ * {@link NgisResourceType} is **not** widened: it classifies *scene resources*,
+ * and `DatasetInfo.datasetType` produces only `VECTOR`/`RASTER`/everything-else.
+ *
+ * Canonicalization is **case- and separator-insensitive**: lowercase, strip
+ * `_`, `-` and spaces, then match. `"Point Cloud"`, `"point_cloud"` and
+ * `"POINTCLOUD"` all canonicalize to `pointcloud`; `null`/absent → `file`.
+ *
+ * | canonical | BE `x-data-type` | binding-validation | classified as | workflow slot `dataType` |
+ * |---|---|---|---|---|
+ * | `raster` | `Raster` | `RASTER` | `raster` | `Raster` |
+ * | `vector` | `Vector` | `VECTOR` | `vector` | `Vector` |
+ * | `table` | `Table` | `TABLE` | `file` | `Table` |
+ * | `pointcloud` | `PointCloud` | `POINTCLOUD` | `file` | `PointCloud` |
+ * | `raster3d` | `Raster3D` | `RASTER` | `raster` \| `file` | `Raster3D` |
+ * | `file` | `File` (or absent) | `FILE` | any | `File` |
+ *
+ * **The last column is Pascal and that is not cosmetic.**
+ * `WorkflowTypeCheckService.compatible` is case-sensitive `String.equals`, so
+ * writing `"raster"` into a `ToolInputSlot.dataType` silently fails type-check
+ * against a builtin node's `"Raster"` and `400`s at workflow save. Y6 applies
+ * that column at, and **only** at, the `ngis-workflow` boundary. Nowhere else
+ * in either repo is Pascal correct.
+ */
+export type NgisDataType = "raster" | "vector" | "table" | "pointcloud" | "raster3d" | "file";
+export declare const NGIS_DATA_TYPES: readonly ["raster", "vector", "table", "pointcloud", "raster3d", "file"];
+/**
+ * **Frozen (F14.1).** How a requested data type resolves to the resource types
+ * v1 can actually classify.
+ *
+ * `table` stays reserved and **unemitted** in `resources.types` and in
+ * `NgisResourceSummary.type` through Stage 14 (XD7 unchanged) — producing it
+ * needs `NgisFile.fileType`, an N+1 `GET /api/files/{fileId}`, and the
+ * server-side alternative lives in `ngis-scene`/`ngis-file`, which no Stage 14
+ * backend session owns. So `'table' in resources.types` is permanently false
+ * and stays on the grep-proof list.
+ *
+ * **But `table` is legal in a `types={…}` prop**, because that prop speaks
+ * `NgisDataType`, not `NgisResourceType`. A widened request (`table`,
+ * `pointcloud`, `raster3d`) must be **surfaced, never silent**: `ResourceSelect`
+ * renders `GIS.pluginUi.pick.widened` naming the requested type and the types
+ * actually listed. Refusals and approximations are surfaced, not masked.
+ */
+export declare const NGIS_DATA_TYPE_TO_RESOURCE_TYPES: Readonly<Record<NgisDataType, readonly NgisResourceType[]>>;
+export interface NgisResourceSummary {
+    /** Scene-resource id (`SceneResourceDto.id`), not a file id. */
+    id: string;
+    sceneId: string;
+    name: string;
+    /** `SceneResourceDto.effectiveFileId` — the id every dataset API takes. */
+    fileId: string;
+    type: NgisResourceType;
+    /** `DatasetInfo.status` verbatim (`PENDING|PROCESSING|DONE|FAILED|NOT_REGISTERED|N/A`).
+     *  Passed through, never collapsed: a plugin must be able to tell "not ready"
+     *  from "failed". */
+    datasetStatus: string;
+    /**
+     * Whether the scene service could resolve the cached Dataset summary. A
+     * resource whose metadata is unavailable or missing is not type-matchable.
+     */
+    metadataState: NgisResourceMetadataState;
+    geometryType: string | null;
+    layerCount: number;
+    rendered: boolean;
+    /**
+     * Scene layers that render this resource, when the host can supply them.
+     *
+     * A resource is still the data identity and {@link fileId} is still the
+     * value tools submit.  These are deliberately a display projection so a
+     * picker can let a person choose the layer they recognise without leaking a
+     * layer id into a file-typed tool parameter.  `undefined` preserves the
+     * v0.4 source contract for hosts that cannot enumerate scene layers yet.
+     */
+    layers?: readonly NgisResourceLayer[];
+}
+/** A data-backed scene layer, projected for resource-picking UI. */
+export interface NgisResourceLayer {
+    /** `NgisSceneLayer.id`; unique even when several layers share one file. */
+    id: string;
+    name: string;
+    /** Scene render-layer type (for example `MAPLIBRE_FILL`), if known. */
+    layerType: string | null;
+    /** A hidden layer remains selectable, but is labelled honestly in the UI. */
+    visible: boolean;
+    /** Parent group names from root to leaf, when the host exposes groups. */
+    groupPath?: string | null;
+}
+/** Scene-resource summary freshness from `GET /api/scenes/{sceneId}/resources`. */
+export type NgisResourceMetadataState = "AVAILABLE" | "MISSING" | "UNAVAILABLE" | "UNKNOWN";
+export interface NgisResourceField {
+    name: string;
+    type: string;
+}
+export interface NgisResourceDetail extends NgisResourceSummary {
+    srid: number | null;
+    /** Vector only; `null` otherwise. */
+    featureCount: number | null;
+    /** Vector only; `[]` otherwise. */
+    fields: readonly NgisResourceField[];
+    /** Raster only; `null` otherwise. */
+    bandCount: number | null;
+    bbox: NgisBounds | null;
+}
+export interface NgisResourceValueCount {
+    value: string | number | boolean | null;
+    count: number;
+}
+/** A field's most frequent values, projected as plain worker-safe data. */
+export interface NgisResourceFieldValues {
+    field: string;
+    type: string;
+    totalCount: number;
+    uniqueCount: number;
+    truncated: boolean;
+    values: readonly NgisResourceValueCount[];
+}
+export interface NgisResourcesFacet {
+    list(filter?: {
+        types?: readonly NgisResourceType[];
+        /** Refresh the scene service's persisted, bounded resource summaries. */
+        refresh?: boolean;
+    }): Promise<NgisResourceSummary[]>;
+    get(resourceId: string): Promise<NgisResourceDetail | null>;
+    /** Read field frequencies for a dataset file. `resources:read`. */
+    fieldValues?(fileId: string, field: string, limit?: number): Promise<NgisResourceFieldValues>;
+    onChange(listener: () => void): NgisUnsubscribe;
+}
+export interface NgisModelSummary {
+    id: string;
+    name: string;
+    /** `"workflow"` selects the WORKFLOW branch inside `tasks.run`; anything else
+     *  (including `null`) is DIRECT. */
+    provider: string | null;
+    category: string | null;
+    description: string | null;
+    enabled: boolean;
+    modelboxId: string | null;
+    /** Stage 16. **Never** project id, revision id or any other runtime provenance —
+     *  the shared-consumer detail endpoint deliberately withholds those. */
+    compatibilityStatus: string | null;
+}
+export interface NgisModelboxNode {
+    id: string;
+    name: string;
+    provider: string | null;
+    parentId: string | null;
+    children: readonly NgisModelboxNode[];
+}
+/**
+ * `AnalysisToolSchema` passed through unmodified — including `x-role`,
+ * `x-data-type` and every other `x-` key. v1 does **not** normalize it;
+ * one normalized UI schema is Stage 14 Y1 (design-v2 §8 item 4).
+ *
+ * XD19 makes normalizing `tool_schema` a **prohibition** for this stage, not a
+ * deferral: the object handed to a plugin is the response body itself.
+ */
+export type NgisModelSchema = AnalysisToolSchema;
+/**
+ * `host.models.validate` request. Camel-cased at the facet boundary like every
+ * other F13.2 request type; the facade snake-cases it onto
+ * `POST /api/analysis/tools/{toolId}/validate-execution`.
+ *
+ * `ownerId` is deliberately absent: it comes from the authenticated caller and
+ * is **never** read from a body.
+ */
+export interface NgisModelValidateRequest {
+    toolId: string;
+    expectedToolVersion?: number;
+    bindings?: readonly {
+        portName: string;
+        fileIds: readonly string[];
+    }[];
+    params?: Readonly<Record<string, string>>;
+    sceneId?: string;
+    /** Lab-scene optimistic fence. Omitted for ordinary scenes. */
+    expectedSceneGeneration?: number;
+    outputMode?: "ADD_LAYER" | "UPDATE_RESOURCE";
+    targetResourceId?: string;
+    targetSrid?: number;
+}
+export interface NgisModelSearchRequest {
+    query?: string;
+    /** Server default 10, server maximum 50. */
+    limit?: number;
+    providers?: readonly string[];
+    kinds?: readonly string[];
+    inputTypes?: readonly NgisDataType[];
+    outputTypes?: readonly NgisDataType[];
+}
+/**
+ * One hit from `host.models.search` — the camel-cased facet projection of
+ * `ToolSearchResult`.
+ *
+ * **Note the deliberate asymmetry with `validate`,** which returns
+ * `NgisExecutionValidation` — the snake_case response DTO **verbatim**, because
+ * F14.3 says so: its field names are the client's contract with the proto and
+ * re-spelling them would be a second normalization of the very thing YB2 is
+ * projecting. `search` has no such constraint, so it follows F13.2's
+ * `NgisModelSummary` shape instead and stays a *summary*, not a wire echo.
+ *
+ * `inputTypes`/`outputTypes` are canonicalized to {@link NgisDataType} by the
+ * facade; the wire carries the search-meta strings.
+ */
+export interface NgisModelSearchResult {
+    toolId: string;
+    version: number;
+    kind: string;
+    name: string;
+    provider: string | null;
+    summary: string | null;
+    domains: readonly string[];
+    operationTypes: readonly string[];
+    inputTypes: readonly NgisDataType[];
+    outputTypes: readonly NgisDataType[];
+    modelboxPath: string | null;
+    score: number;
+}
+export interface NgisModelsFacet {
+    /** F13.2, unchanged. `query` filters the list responses client-side on
+     *  name/description; the facet-level {@link NgisModelsFacet.search} leg is
+     *  the server-side facet query and is what `ModelSelect` and Flow use, because
+     *  client-side filtering cannot express `inputTypes`/`outputTypes`. */
+    list(filter?: {
+        provider?: string;
+        category?: string;
+        modelboxId?: string;
+        query?: string;
+    }): Promise<NgisModelSummary[]>;
+    tree(): Promise<NgisModelboxNode[]>;
+    get(toolId: string): Promise<NgisModelSummary | null>;
+    schema(toolId: string): Promise<NgisModelSchema | null>;
+    /** The one normalized UI schema (F14.2). `null` when the tool or its schema
+     *  is absent. Scope `models:read`. */
+    uiSchema(toolId: string): Promise<NgisToolUiSchema | null>;
+    /** REST projection of `ValidateToolExecution`. Returns the response DTO
+     *  **verbatim**. Scope `models:read`, **not** `models:run` — it runs nothing,
+     *  and returns only registry facts plus dataset metadata the caller can
+     *  already read through `host.resources`. */
+    validate(request: NgisModelValidateRequest): Promise<NgisExecutionValidation>;
+    /** REST projection of `SearchTools`. Scope `models:read`. */
+    search(request: NgisModelSearchRequest): Promise<NgisModelSearchResult[]>;
+}
+export type NgisTaskStatus = "submitting" | "QUEUED" | "RUNNING" | "SUCCESS" | "FAILED" | "CANCELLED";
+/**
+ * Mirrors `AnalysisTaskLifecycleStage` (`src/store/analysis-scene.ts:52-61`) —
+ * the reason a plugin can tell **complete from integrated**. `status: "SUCCESS"`
+ * with `stage: "waiting_scene_integration"` is a real, common state.
+ */
+export type NgisTaskStage = "submitting" | "queued" | "running" | "waiting_output_datasets" | "waiting_scene_integration" | "refreshing_scene" | "success" | "failed" | "cancelled";
+export interface NgisTaskRunRequest {
+    toolId: string;
+    /** The analysis API takes string-valued params; the facade does not coerce. */
+    params: Record<string, string>;
+    sceneId?: string;
+    /** Lab-scene optimistic fence. Omitted for ordinary scenes. */
+    expectedSceneGeneration?: number;
+    outputMode?: "ADD_LAYER" | "UPDATE_RESOURCE";
+    targetResourceId?: string;
+}
+export interface NgisTaskHandle {
+    /** DIRECT: the analysis task id. WORKFLOW: the workflow instance id. */
+    id: string;
+    kind: "direct" | "workflow";
+}
+export interface NgisTaskOutput {
+    name: string | null;
+    fileId: string | null;
+    primary: boolean;
+}
+export interface NgisTaskState {
+    id: string;
+    kind: "direct" | "workflow";
+    toolId: string;
+    status: NgisTaskStatus;
+    stage: NgisTaskStage;
+    /** DIRECT only. Workflow tools have no log stream, so this is always `[]`
+     *  for `kind: "workflow"` — the facade does not fabricate one. */
+    logs: readonly string[];
+    error: string | null;
+    outputs: readonly NgisTaskOutput[];
+    startedAt: number;
+    updatedAt: number;
+    completedAt: number | null;
+}
+export interface NgisTaskWatcher {
+    close(): Promise<void>;
+}
+export interface NgisTasksFacet {
+    /** Branches on `NgisModelSummary.provider` inside the facade. The plugin sees
+     *  one API and must not branch itself. */
+    run(request: NgisTaskRunRequest): Promise<NgisTaskHandle>;
+    get(taskId: string): Promise<NgisTaskState | null>;
+    list(filter?: {
+        active?: boolean;
+    }): Promise<NgisTaskState[]>;
+    /** DIRECT → the existing `analysisApi.streamTask` fetch-reader SSE transport,
+     *  then `integration_status` polling. WORKFLOW → instance polling; **there is
+     *  no workflow SSE** and the facade must not pretend otherwise. */
+    watch(taskId: string, listener: (state: NgisTaskState) => void): NgisTaskWatcher;
+    cancel(taskId: string): Promise<void>;
+    outputs(taskId: string): Promise<NgisTaskOutput[]>;
+}

package/dist/src/sdk/host-api.d.ts

@@ -0,0 +1,256 @@
+/**
+ * `NgisHostAPI` — the 0.4 host facade (Stage 13, session X2).
+ *
+ * The 0.3 map facade **keeps its name and its position**: it stays at
+ * `host.api`, holding exactly today's `NgisMapAPI`, and is *not* re-exported
+ * facet-by-facet onto the root. `host.api.layers` remains the only spelling, so
+ * no shipped call site moves.
+ *
+ * **XD1, amendment on record.** design-v2 §4's table spells the map leg
+ * `host.map`. Renaming `api` → `map` would touch every first-party plugin, the
+ * E7 command executor and `useRemoteExtensionPlugins`, for zero capability.
+ * `host.api` is the locked spelling; design-v2 §4 is amended, not implemented
+ * as written.
+ *
+ * **Worker-readiness (L6).** Every facet method is `async` and
+ * takes/returns JSON-serializable values; every observation is a subscription
+ * returning the synchronous `NgisUnsubscribe`. The two handle-returning methods
+ * (`ui.progress`, `tasks.watch`) return objects whose members are themselves
+ * async — proxyable as RPC handles. No facet returns a DOM node, a React
+ * element, a class instance, or a function other than `NgisUnsubscribe`.
+ *
+ * ## What this file owns, and what it deliberately does not
+ *
+ * X2 (W1) implements `scene` / `resources` / `models` / `tasks`. The remaining
+ * five slots are typed here — verbatim from F13.2, so the facade is
+ * type-complete from W1 — and implemented by later sessions:
+ *
+ * | slot | implementer |
+ * |---|---|
+ * | `context` | X1 (W1), `src/sdk/context/**` |
+ * | `viz` · `storage` · `ui` | X3 (W2), `src/sdk/facets/{viz,storage,ui}.ts` |
+ * | `commands` | X4 (W2), over the E7 `gisCommandRegistry` seam |
+ *
+ * Those sessions should **import** these interfaces rather than redeclare them.
+ * Anything omitted at construction is filled with a facet whose every member
+ * rejects loudly (`pendingFacet`) — never with fake empty data, which per F13.5
+ * is indistinguishable from a real empty scene.
+ */
+import { type NgisMapAPI } from "./map-api";
+import type { NgisBounds, NgisUnsubscribe } from "./map-api";
+import type { NgisModelsFacet, NgisResourcesFacet, NgisSceneFacet, NgisTasksFacet } from "./facets/types";
+export type { NgisModelSchema, NgisModelSummary, NgisModelboxNode, NgisModelsFacet, NgisResourceDetail, NgisResourceField, NgisResourceFieldValues, NgisResourceSummary, NgisResourceValueCount, NgisResourceType, NgisResourcesFacet, NgisSceneFacet, NgisSceneInfo, NgisTaskHandle, NgisTaskOutput, NgisTaskRunRequest, NgisTaskStage, NgisTaskState, NgisTaskStatus, NgisTaskWatcher, NgisTasksFacet, } from "./facets/types";
+export type NgisChartKind = "bar" | "line" | "pie" | "scatter" | "histogram";
+export interface NgisChartSeries {
+    name: string;
+    values: readonly number[];
+}
+/**
+ * **Declarative only (F14.3).** No DOM, no React element, no function — L6's
+ * worker-readiness rule (F13.1) binds every member added here, and the host is
+ * what renders it. A spec that carried a formatter callback or an ECharts
+ * option object would not survive Stage 15's worker tier.
+ */
+export interface NgisChartSpec {
+    kind: NgisChartKind;
+    title?: string;
+    categories?: readonly string[];
+    series: readonly NgisChartSeries[];
+    xLabel?: string;
+    yLabel?: string;
+}
+/** F13.2 verbatim, plus F14.3's additive `chart` leg. Implemented by X3 (W2) in
+ *  `src/sdk/facets/viz.ts`; `chart` is Y4's (W2). */
+export interface NgisVizFacet {
+    /** Post-hoc add: registers a scene resource for `fileId` if absent, then adds a
+     *  layer. Submit-time integration is the better path and is reached by passing
+     *  `sceneId`/`outputMode` to `tasks.run` — this is for outputs produced without it. */
+    addResultLayer(options: {
+        fileId: string;
+        name?: string;
+    }): Promise<{
+        resourceId: string;
+        layerId: string;
+    }>;
+    /** Opens the existing attribute panel over the resource. */
+    openTable(resourceId: string): Promise<void>;
+    fit(target: {
+        resourceId: string;
+    } | {
+        bounds: NgisBounds;
+    }): Promise<void>;
+    /** F14.3, additive. **Ungated**, for the same reason `openTable`/`fit` are —
+     *  it mutates nothing. Y4 (W2) implements it over `StatChart`'s renderer. */
+    chart(spec: NgisChartSpec): Promise<void>;
+}
+/** F13.2 verbatim. Implemented by X3 (W2) in `src/sdk/facets/storage.ts`;
+ *  `NgisStorageError` is runtime code and ships with that session. */
+export type NgisStorageWriteFailure = "read-only" | "too-large" | "conflict";
+export interface NgisStorageLeg {
+    get(): Promise<unknown | null>;
+    /** Rejects with `NgisStorageError` (`read-only` · `too-large` · `conflict`) or
+     *  `NgisScopeError`. Never silently no-ops. */
+    set(value: unknown): Promise<void>;
+    /** Scene leg: `false` for a non-owner viewer. User leg: always `true` while
+     *  installed. Surfaced, never masked — a settings form must render read-only
+     *  rather than fail on submit. */
+    canWrite(): Promise<boolean>;
+    onChange(listener: (value: unknown | null) => void): NgisUnsubscribe;
+}
+export interface NgisStorageFacet {
+    /** Per (user, extension). XB2's install-row column. */
+    user: NgisStorageLeg;
+    /** Per (scene, extension) — `extension_config.plugins[].settings`, owner-write-only. */
+    scene: NgisStorageLeg;
+}
+/**
+ * F13.2's `NgisContextFacet`, declared here under an `NgisHost`-prefixed name.
+ *
+ * X1 is building `src/sdk/context/**` **concurrently** in this same wave and
+ * owns the canonical `NgisContextFacet` / `NgisContextValue` spelling. Naming
+ * the slot type differently is what lets X1 and X2 merge without touching the
+ * same declaration; the two are structurally identical by construction (both
+ * are F13.2 verbatim), so X1's facet satisfies this slot as-is.
+ *
+ * At the X1→X2 rebase these two lines may collapse to
+ * `export type NgisHostContextFacet = NgisContextFacet;` — a mechanical change
+ * with no behavioural effect.
+ */
+export type NgisHostContextValue = string | number | boolean | null | readonly (string | number)[];
+export interface NgisHostContextFacet {
+    get(key: string): Promise<NgisHostContextValue | undefined>;
+    getAll(): Promise<Readonly<Record<string, NgisHostContextValue>>>;
+    /** Auto-namespaced to `plugin:<pluginId>:<key>` — **F14.11, as amended by
+     *  F15.14**: the deprecated dotted `plugin.<pluginId>.<key>` spelling was
+     *  removed in Stage 15 (W1, Z10) and is now written by nothing, so an
+     *  expression against it names a key no publisher produces. A caller-supplied
+     *  namespace prefix is rejected, not silently re-prefixed. */
+    set(key: string, value: NgisHostContextValue): Promise<void>;
+    /** Compiles and evaluates a when-grammar v1 expression once. */
+    evaluate(expression: string): Promise<boolean>;
+    /** Fires when any listed key changes, batched per microtask. */
+    onChange(keys: readonly string[], listener: (changed: Readonly<Record<string, NgisHostContextValue>>) => void): NgisUnsubscribe;
+}
+/** F13.2 verbatim. Implemented by X3 (W2) in `src/sdk/facets/ui.ts`. */
+export interface NgisQuickPickItem {
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface NgisProgressHandle {
+    update(patch: {
+        percent?: number;
+        message?: string;
+    }): Promise<void>;
+    done(): Promise<void>;
+}
+export interface NgisUiFacet {
+    toast(options: {
+        message: string;
+        kind?: "info" | "success" | "warning" | "error";
+        description?: string;
+    }): Promise<void>;
+    confirm(options: {
+        title: string;
+        description?: string;
+        confirmLabel?: string;
+        cancelLabel?: string;
+        destructive?: boolean;
+    }): Promise<boolean>;
+    /** Resolves to the chosen item's `id`, or `null` if dismissed. */
+    quickPick(options: {
+        title?: string;
+        items: readonly NgisQuickPickItem[];
+    }): Promise<string | null>;
+    progress(options: {
+        title: string;
+    }): Promise<NgisProgressHandle>;
+}
+/** F13.2 verbatim. Implemented by X4 (W2) over the E7 `gisCommandRegistry`. */
+export interface NgisCommandSummary {
+    id: string;
+    title: string;
+    /** The declaring plugin — a plugin can see that a command is not its own. */
+    pluginId: string;
+}
+export interface NgisCommandsFacet {
+    list(): Promise<NgisCommandSummary[]>;
+    /** The E7 `gisCommandRegistry` seam. Cross-plugin invocation is allowed in v1
+     *  and is **not** ordered — `pluginDependencies` activation ordering is Stage 15
+     *  (XD15). A command whose plugin has not activated rejects. */
+    invoke(commandId: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export interface NgisHostAPI {
+    /** `NGIS_MAP_API_VERSION` — "0.4.0". */
+    readonly version: string;
+    /** The plugin this facade is bound to. Every facade is per-plugin: it is what
+     *  namespaces `storage`/`context.set` and what attributes audit events. */
+    readonly pluginId: string;
+    /** **FROZEN 0.3.0 surface, ungated.** `layers` · `camera` · `selection` ·
+     *  `draw` · `measure` · `panels` · `events` · `getMap()`. Not re-exported
+     *  facet-by-facet onto the root: `host.api.layers` stays the only spelling,
+     *  so no shipped call site moves. */
+    api: NgisMapAPI;
+    scene: NgisSceneFacet;
+    resources: NgisResourcesFacet;
+    models: NgisModelsFacet;
+    tasks: NgisTasksFacet;
+    viz: NgisVizFacet;
+    storage: NgisStorageFacet;
+    context: NgisHostContextFacet;
+    ui: NgisUiFacet;
+    commands: NgisCommandsFacet;
+}
+/**
+ * Back-compat alias — `activate(host: NgisPluginHost)` signatures do not change,
+ * and a 0.3-era plugin reading only `host.api` still type-checks and still runs.
+ *
+ * **Not yet re-exported from `@/sdk`.** `src/sdk/plugin.ts` still exports the
+ * 0.3 `NgisPluginHost = { api }`, and that is the name `@/sdk` re-exports today.
+ * Widening it is X4's atomic `NGIS_MAP_API_VERSION` → 0.4.0 flip in W2 (ED19):
+ * `plugin.ts`, `plugin-runtime.ts` and every host call site
+ * (`GisWorkspace.tsx:182` builds `{ api }`) are X4's files, and widening the
+ * type without them would break `tsc` across four modules X2 does not own.
+ */
+export type NgisPluginHost = NgisHostAPI;
+/**
+ * Thrown by every member of a facet slot that has not been wired yet. Loud on
+ * purpose: F13.5's refusal rule is "a typed error, never empty data", because a
+ * silent empty list is indistinguishable from a real empty scene.
+ */
+export declare class NgisFacetUnavailableError extends Error {
+    readonly facet: string;
+    readonly member: string;
+    constructor(facet: string, member: string, owner: string);
+}
+export interface NgisHostAPIOptions {
+    pluginId: string;
+    /** The 0.3 facade from `createNgisMapAPI(...).api` — kept at `host.api`. */
+    api: NgisMapAPI;
+    scene: NgisSceneFacet;
+    resources: NgisResourcesFacet;
+    models: NgisModelsFacet;
+    tasks: NgisTasksFacet;
+    /** X1 (W1). Omitted until the context store is wired. */
+    context?: NgisHostContextFacet;
+    /** X3 (W2). */
+    viz?: NgisVizFacet;
+    /** X3 (W2). */
+    storage?: NgisStorageFacet;
+    /** X3 (W2). */
+    ui?: NgisUiFacet;
+    /** X4 (W2). */
+    commands?: NgisCommandsFacet;
+    /** Defaults to `NGIS_MAP_API_VERSION`. F13.13 bumps that constant to
+     *  `"0.4.0"` in X4, atomically with its consumers (ED19) — this facade reads
+     *  it rather than hard-coding a version that would then disagree with the
+     *  runtime's negotiation. */
+    version?: string;
+}
+/**
+ * Assembles the 0.4 facade. Every facet is injected: `src/sdk/` sits below
+ * `src/store/`, `src/api/` and `src/features/`, so the wiring lives at the host
+ * call site — which is also what makes the facade worker-ready (a worker tier
+ * injects RPC-backed facets against the same interfaces).
+ */
+export declare function createNgisHostAPI(options: NgisHostAPIOptions): NgisHostAPI;