@honua/mcp-server 0.1.13 → 0.1.15

package/README.md

@@ -113,6 +113,15 @@ The tool requires `confirm: true`. Stop and remove this bootstrap server from
 the MCP client configuration after installation; the normal platform-free
 server remains read-only and cannot invoke the installer.
 
+Choose a new directory for each installation. The installer checks Docker Engine
+and Compose before writing files, refuses existing compose/bootstrap files it
+cannot recognize, and preserves unrelated keys in an installer-owned private
+`.env`. New installations keep an isolated Compose project identity in that file;
+keep `.env` with the installation to retain its credentials and volumes. Existing
+legacy installations keep their original project after verifying that its
+containers belong to the chosen directory. Restore the original files when that
+check refuses a conflicting or incomplete legacy installation.
+
 ## Environment Variables
 
 - `HONUA_BASE_URL` (required in normal mode): absolute base URL — a public ArcGIS folder
@@ -136,12 +145,12 @@ All read-only:
 - `honua_list_sources` — **protocol-neutral discovery.** Returns `<protocol>:<address>` source references plus each source's real capabilities. Every protocol family degrades independently with a reason.
 - `honua_list_services` — GeoServices-specific service catalog (prefer `honua_list_sources`)
 - `honua_describe_layer` — source schema, protocol, and advertised capabilities
-- `honua_query_features`
+- `honua_query_features` — includes geometry by default; `resultOffset` and `outSrid` are aliases for `offset` and `outSr`. Pass one spelling of each field. Count-only and geometry-precision inputs are refused; use `honua_count_features` for counts.
 - `honua_count_features`
 - `honua_get_extent`
 - `honua_statistics`
 - `honua_explain_capability_gap`
-- `honua_get_style`, `honua_apply_style_preset` — structured-unavailable on a plain FeatureServer
+- `honua_get_style`, `honua_apply_style_preset` — structured-unavailable on a plain FeatureServer. Preset resolution is read-only and returns a stylesheet for client-side application; persisted `serviceId`/`layerId` binding arguments are refused.
 - `honua_docs_search` — answer a Honua documentation question from the local versioned docs corpus (`llms-full.txt`), with a source-file and release-version citation per hit. Each citation is pinned to the exact commit the corpus bytes come from, so it keeps naming the text that was searched after `trunk` moves; when that commit cannot be established (an installed package with no checkout, or a locally regenerated corpus) the citation reports `sourceRevision: null` and links to `trunk` rather than claiming a pin it cannot back. Offline: reads committed files, never the network, and reports structured-unavailable when the corpus is not present in the installation. Point `HONUA_DOCS_CORPUS_PATH` at a corpus file (any name) or at a directory holding `llms-full.txt` to supply the corpus explicitly; `HONUA_SOURCE_REVISION` declares the commit when git is unavailable.
 
 ### Protocol-neutral tool contract
@@ -346,6 +355,7 @@ cd honua-sdk-js
 npm ci
 ```
 
+<!-- doc-run: checkout -->
 ```bash
 npm run build   # the SDK that mcp/ links to; takes a few minutes
 cd mcp
@@ -354,6 +364,7 @@ npm ci
 
 From `mcp/`:
 
+<!-- doc-run: checkout=mcp -->
 ```bash
 # Run the certifier against the offline fixture backend and write artifacts:
 npm run certify
@@ -384,6 +395,7 @@ skip-with-reason. Fixture-backed and deterministic — no network — as long as
 instead (the scheduled live variant). Unset it if you exported it for `honua-mcp`
 above:
 
+<!-- doc-run: checkout=mcp -->
 ```bash
 unset HONUA_BASE_URL
 npm run certify:standalone            # platform-free cert (plain FeatureServer fixture)
@@ -406,6 +418,7 @@ in `config/live-conformance-endpoints.v1.json`). Nothing Esri exists there: the
 GeoServices entry points all reject, so a tool that still secretly required
 `serviceId`/`layerId` fails loudly instead of passing by accident.
 
+<!-- doc-run: checkout=mcp -->
 ```bash
 npm run certify:standalone-ogc            # non-GeoServices cert (OGC API Features fixture)
 npm run test:certification:standalone-ogc # CI gate variant
@@ -521,6 +534,7 @@ honua-io/honua-server#1956.)
   dependencies); keys come from the environment and are never hardcoded. Set
   `HONUA_MCP_REMOTE_URL` to drive a live remote `/mcp` instead of the fixture.
 
+<!-- doc-run: checkout=mcp -->
 ```bash
 npm run eval            # run the eval (live models join if their keys are set)
 npm run eval:offline    # force the deterministic control + fixture surface
@@ -546,6 +560,7 @@ guards. Because the fixture replays real recorded data, a wrong number or a
 hallucinated place name fails. The grading taxonomy is documented in
 [`evals/README.md`](evals/README.md).
 
+<!-- doc-run: checkout=mcp -->
 ```bash
 npm run eval:standalone       # deterministic control over the census fixture (offline)
 ```
@@ -564,6 +579,7 @@ an extent that came from the declared collection extent must say so, and a CQL2
 spatial predicate the endpoint does not publish must come back as a structured
 capability refusal — never as an empty result set.
 
+<!-- doc-run: checkout=mcp -->
 ```bash
 npm run eval:ogc              # deterministic control over the OGC API Features fixture (offline)
 ```

package/certification/geospatial-mcp-schemas/PROVENANCE.md

@@ -5,16 +5,22 @@ machine-readable schemas from the open **geospatial-mcp** standard.
 
 - **Source repo:** https://github.com/honua-io/geospatial-mcp
 - **Source path:** `spec/schemas/`
-- **Source commit:** `eb53989cc61c856261cf017b4b5a8e721317dc41`
-  (`feat: direct geoprocessing verbs (analysis profile) + geometryPrecision/maxInlineBytes (#55)`)
-- **Schema index date:** `2026-07-06`
+- **Source commit:** `4fac81c2f93a110921bb62638bc5ab599ef5e626`
+  (`Declare release component versions for the nightly resolver (#92)`, trunk HEAD on 2026-10-08)
+- **Schema index date:** `2026-08-12`
 - **Dialect:** JSON Schema draft 2020-12
 
-> The pin is deliberately held at `eb53989` (pre geospatial-mcp#58): the #58
-> platform-ops schemas are marked implemented in the manifest but honua-server
-> does not serve those tools yet, so re-vendoring past #58 would introduce
-> conformance failures. The post-#58 bump is owned by honua-server#2555/#2566,
-> which implement the new tools and vendor their schemas together.
+> Re-vendored at trunk HEAD for the 2026.1 rc.3 certification fix (unit K2).
+> The earlier hold at `eb53989` (pre geospatial-mcp#58) is over: honua-server
+> now serves the #58 platform-ops tools (`honua_ops_health`, `honua_ops_findings`,
+> `honua_alert_events`, `honua_operate_events`, `honua_platform_release_status`,
+> `honua_deploy_operations`, `honua_propose_rollback`).
+>
+> Known upstream lag: this index still maps `propose_operation` to the retired
+> `honua_propose_operation` as `implemented`. Marking it `known-gap` is
+> geospatial-mcp unit K4, which had not landed at this commit. Until it does, the
+> certifier records `propose_operation` as a standard-tool known gap (reference
+> tool not advertised), which is recorded, not failed. Re-pin once K4 merges.
 
 ## Why vendored
 

package/certification/geospatial-mcp-schemas/common/controls.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/common/controls.schema.json",
+  "title": "Composition controls",
+  "description": "Standard-owned `controls` collection for composition documents (MapPackage/AppPackage). A control is an input affordance the user operates; it emits the `change` event of the ADR-0030 interaction vocabulary and is the target a `control:{id}` reference resolves against. The kind vocabulary is closed — extending it requires a standard ADR — and deliberately excludes a feature-editing draw control (ADR-0028). Controls declare presentation and data binding only; behaviour is wired declaratively through the `interactions` block (common/interactions.schema.json). Controls never appear in `layout`: grid placement is restricted to `map` and `widget:{id}` by that schema's layoutRef. See docs/adr/0031-composition-controls.md.",
+  "type": "object",
+  "$defs": {
+    "controlKind": {
+      "type": "string",
+      "enum": [
+        "navigation",
+        "scale",
+        "fullscreen",
+        "geolocate",
+        "search",
+        "measure",
+        "timeSlider",
+        "filterSelect",
+        "filterSlider",
+        "filterDateRange",
+        "bookmarks",
+        "opacity",
+        "attribution",
+        "basemapSwitcher"
+      ],
+      "description": "Closed control vocabulary. Map affordances: navigation (zoom/pan/compass), scale, fullscreen, geolocate, attribution, basemapSwitcher, bookmarks, measure, search. Data-binding affordances that emit `change`: timeSlider, filterSelect, filterSlider, filterDateRange, opacity. There is deliberately no feature-editing draw kind — autonomous agent mutation of source records stays excluded (ADR-0028); an annotation-only draw control may be admitted later by its own ADR. Extending this set requires a standard ADR (ADR-0031)."
+    },
+    "control": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Stable identifier, unique within the document's controls block. `control:{id}` references in the **interactions** block resolve against this value; add_control replaces an existing control with the same id. Controls are deliberately NOT layout grammar — ADR-0031 treats them as chrome the host positions, and `layoutItem.ref` is constrained to `map` and `widget:{id}` so a control can never claim a grid cell."
+        },
+        "kind": {
+          "$ref": "#/$defs/controlKind",
+          "description": "What the control is. The kind fixes the affordance's semantics, not its skin — hosts render each kind in their own idiom."
+        },
+        "title": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "Human-readable label shown by the host. Optional; hosts fall back to a per-kind default label."
+        },
+        "sourceId": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Identifier of the layer or datasource the control reads its domain from (e.g. the layer whose field values populate a filterSelect, or the layer a timeSlider ranges over). Data-binding kinds normally set it; presentation-only kinds (navigation, scale, fullscreen, attribution) omit it. Resolution of the identifier within the document is a validation-gate responsibility, as for layer references."
+        },
+        "config": {
+          "type": "object",
+          "description": "Per-kind configuration (e.g. the field a filterSelect filters on, a slider's bounds and step, a bookmark list). Host-interpreted and intentionally open, matching the widget entry's `config`; it carries no expression language and grants no capability the composition surface does not already have."
+        },
+        "explorationContextId": {
+          "$ref": "exploration.schema.json#/$defs/componentBinding/properties/explorationContextId",
+          "description": "Exploration context this control joins (ADR-0032). A data-binding control bound to a context contributes its state to every component in that context, which is how a filter dropdown narrows peer widgets without an interactions edge per target."
+        },
+        "role": {
+          "$ref": "exploration.schema.json#/$defs/componentBinding/properties/role",
+          "description": "Role this control plays in its exploration context (ADR-0032); data-binding kinds normally bind as `filter`."
+        }
+      },
+      "description": "One control entry. The shape mirrors the composition widget entry ({ id, kind, title?, sourceId?, config? }) so agents author both collections the same way."
+    }
+  },
+  "properties": {
+    "controls": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/control"
+      },
+      "description": "Input affordances declared by this composition document. Optional and additive: a document without controls is valid. Ids must be unique within the collection (validation-gate check)."
+    }
+  }
+}

package/certification/geospatial-mcp-schemas/common/exploration.schema.json

@@ -0,0 +1,165 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/common/exploration.schema.json",
+  "title": "Composition exploration contexts",
+  "description": "Standard-owned `explorationContexts` collection for composition documents (MapPackage/AppPackage). An exploration context is a named unit of shared interaction state — filters, spatial filter, extent, selection, sort, page, visible fields, grouping, aggregation — that components bind to. Components that name the same context share that state, so cross-filtering is context membership rather than an event→action edge; this is the primary interaction model, and the `interactions` block (common/interactions.schema.json) is retained for one-shot gestures. Propagation between bound components is governed by a closed preset vocabulary keyed on the component's role. Contexts are data, never code: there is no expression language and no $event.* substitution here, because a context's state is not produced by an event. Reference resolution (context ids, source ids) is a validation-gate responsibility. See docs/adr/0032-shared-exploration-contexts.md.",
+  "type": "object",
+  "$defs": {
+    "presetName": {
+      "type": "string",
+      "enum": [
+        "globalLinked",
+        "mapDriven",
+        "gridDriven",
+        "chartDriven",
+        "decoupled"
+      ],
+      "description": "Closed linked-view preset vocabulary, naming which bound components propagate state outward. globalLinked: every bound component contributes and receives every shared slice. mapDriven: only the map's extent and selection propagate outward, though filter components still contribute filter state. gridDriven: only the grid's selection, sort, and page propagate outward. chartDriven: only the chart's grouping, aggregation, and selection propagate outward. decoupled: nothing propagates and each component is independent. Extending this set requires a standard ADR (ADR-0032)."
+    },
+    "viewRole": {
+      "type": "string",
+      "enum": [
+        "map",
+        "grid",
+        "chart",
+        "filter",
+        "detail",
+        "form",
+        "custom"
+      ],
+      "description": "Coarse role a bound component plays in its context. The preset's propagation policy is keyed on this value, not on the component's kind, so two chart widgets of different kinds behave identically when both are bound as `chart`. `form` is retained for compatibility with older detail/filter integrations; new documents should prefer the more precise `filter` and `detail` roles."
+    },
+    "explorationStateSnapshot": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "version"
+      ],
+      "properties": {
+        "version": {
+          "type": "integer",
+          "const": 1,
+          "description": "Snapshot format version. Pinned to 1: this ADR defines only the initial format and gives implementations no semantics for any later value, so admitting `version: 2` would produce a schema-valid document no runtime could interpret portably. Later versions join through explicit versioned branches in a follow-on ADR."
+        },
+        "filters": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Shared filter clauses keyed by clause id."
+        },
+        "spatialFilter": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Shared spatial filter (geometry plus relationship)."
+        },
+        "extent": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Shared viewport extent."
+        },
+        "selection": {
+          "type": "array",
+          "items": {
+            "type": [
+              "string",
+              "number",
+              "object"
+            ]
+          },
+          "description": "Shared feature selection. Raw ids are permitted for single-source documents; multi-source documents should use source-qualified targets."
+        },
+        "sort": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "description": "Shared sort order."
+        },
+        "page": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Shared pagination offset and limit."
+        },
+        "visibleFields": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Shared field visibility for tabular and form components. An empty array means all fields."
+        },
+        "grouping": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Shared group-by keys for chart and pivot components."
+        },
+        "aggregation": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Shared aggregation specification."
+        }
+      },
+      "description": "Optional versioned snapshot of a context's shared state at document load. Static JSON only — the same data-never-code posture ADR-0030 established for interaction arguments, minus the $event.* substitution, which has no meaning outside an event payload."
+    },
+    "explorationContext": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Stable identifier, unique within the document's explorationContexts block. A component's explorationContextId resolves against this value; create_exploration_context replaces an existing context with the same id."
+        },
+        "sourceIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Identifiers of the sources whose records this context's shared state addresses. Each must resolve within the document; resolution is a validation-gate responsibility, as for layer references."
+        },
+        "preset": {
+          "$ref": "#/$defs/presetName",
+          "default": "globalLinked",
+          "description": "Propagation policy for components bound to this context. Defaults to globalLinked, which is the behaviour an author means by 'link these together'."
+        },
+        "initialState": {
+          "$ref": "#/$defs/explorationStateSnapshot",
+          "description": "Optional starting shared state. Omit it and the context starts empty."
+        }
+      },
+      "description": "One exploration context. Components bind to it by id; components sharing an id share its state."
+    },
+    "componentBinding": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "explorationContextId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Identifier of the exploration context this component binds to. It must resolve against the document's explorationContexts block (validation-gate check). A component binds to at most one context; omitting the property leaves the component unbound and independent."
+        },
+        "role": {
+          "$ref": "#/$defs/viewRole",
+          "description": "The role this component plays in its context, which the preset's propagation policy is keyed on. Meaningful only alongside explorationContextId."
+        }
+      },
+      "description": "The two optional properties a bindable component (the map, or an entry in layers, widgets, or controls) carries to join an exploration context. Cross-filtering is identity of explorationContextId: there is no edge to author, no ordering between bindings, and no fan-out to cap."
+    }
+  },
+  "properties": {
+    "explorationContexts": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/explorationContext"
+      },
+      "description": "Units of shared interaction state declared by this composition document. Optional and additive: a document without exploration contexts is valid, and one whose components are all unbound behaves exactly as it did before this block existed. Ids must be unique within the collection, and a declared context with no bound components is valid but should warn (validation-gate checks)."
+    }
+  }
+}

package/certification/geospatial-mcp-schemas/common/interactions.schema.json

@@ -0,0 +1,263 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://geospatial-mcp.honua.io/spec/schemas/common/interactions.schema.json",
+  "title": "Composition interactions and layout",
+  "description": "Standard-owned declarative blocks for composition documents (MapPackage/AppPackage): `interactions` wires component events to bounded action verbs; `layout` places widgets on a grid. Bindings are data, never code: the only dynamic element is $event.* path substitution in string argument values. Actions never emit events (only user gestures do), so binding graphs cannot cycle by construction. Reference resolution and the per-(ref,event) fan-out cap (recommended 8) are validation-gate responsibilities. See docs/adr/0030-declarative-interactions-and-layout.md.",
+  "type": "object",
+  "$defs": {
+    "componentRef": {
+      "type": "string",
+      "pattern": "^(map|layer:.+|widget:.+|control:.+)$",
+      "description": "Reference to a component declared in the same composition document: `map`, `layer:{id}`, `widget:{id}`, or `control:{id}`. Must resolve within the document (validation-gate check, not a schema check)."
+    },
+    "eventName": {
+      "type": "string",
+      "enum": [
+        "featureSelect",
+        "featureHover",
+        "selection",
+        "change",
+        "viewportChange"
+      ],
+      "description": "Closed event set: featureSelect/featureHover (layer sources), selection (widget sources), change (control sources), viewportChange (map source). Extending the set requires a standard ADR (ADR-0030)."
+    },
+    "actionVerb": {
+      "type": "string",
+      "enum": [
+        "setFilter",
+        "setViewport",
+        "selectFeature",
+        "runWidgetQuery",
+        "setVisibility"
+      ],
+      "description": "Closed verb set drawn from the existing composition vocabulary. Verbs mutate presentation/exploration state only, never source records (ADR-0028 unaffected). Extending the set requires a standard ADR (ADR-0030)."
+    },
+    "interaction": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "on",
+        "do"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Stable identifier, unique within the document's interactions block. bind_interaction replaces an existing interaction with the same id."
+        },
+        "on": {
+          "$ref": "#/$defs/interactionEvent"
+        },
+        "do": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ref",
+            "verb"
+          ],
+          "properties": {
+            "ref": {
+              "$ref": "#/$defs/componentRef"
+            },
+            "verb": {
+              "$ref": "#/$defs/actionVerb"
+            },
+            "args": {
+              "type": "object",
+              "description": "Static JSON arguments for the verb. A string value beginning with `$event.` is replaced at dispatch time by the value at that path in the event payload (e.g. $event.featureId, $event.value, $event.bbox). No expression language: no arithmetic, no conditionals, no function calls."
+            }
+          },
+          "description": "The action. Verb-driven state changes MUST NOT re-enter the interaction dispatcher (actions never emit events)."
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Authored-but-inactive binding; retained in the document, skipped at dispatch."
+        }
+      }
+    },
+    "layoutItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ref",
+        "x",
+        "y",
+        "w",
+        "h"
+      ],
+      "properties": {
+        "ref": {
+          "$ref": "#/$defs/layoutRef"
+        },
+        "x": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Grid column of the item's left edge (0-based)."
+        },
+        "y": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Grid row of the item's top edge (0-based)."
+        },
+        "w": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Width in grid columns."
+        },
+        "h": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Height in grid rows."
+        }
+      },
+      "description": "Grid placement for one widget (or the map). The ref must resolve within the document — same validation gate as interactions."
+    },
+    "layoutRef": {
+      "type": "string",
+      "pattern": "^(map|widget:.+)$",
+      "description": "Reference to a component that can be placed on the layout grid: `map` or `widget:{id}`. Layers and controls are deliberately excluded — a layer is drawn inside the map and a control is an affordance the host positions, so neither has grid placement. This is narrower than `componentRef` on purpose; reusing that definition would let `layer:parcels` validate into a grid cell whose rendering is undefined."
+    },
+    "interactionEvent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ref",
+        "event"
+      ],
+      "properties": {
+        "ref": {
+          "$ref": "#/$defs/componentRef"
+        },
+        "event": {
+          "$ref": "#/$defs/eventName"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "ref": {
+                "const": "map"
+              }
+            },
+            "required": [
+              "ref"
+            ]
+          },
+          "then": {
+            "properties": {
+              "event": {
+                "const": "viewportChange"
+              }
+            }
+          },
+          "description": "The map emits only viewportChange."
+        },
+        {
+          "if": {
+            "properties": {
+              "ref": {
+                "pattern": "^layer:"
+              }
+            },
+            "required": [
+              "ref"
+            ]
+          },
+          "then": {
+            "properties": {
+              "event": {
+                "enum": [
+                  "featureSelect",
+                  "featureHover"
+                ]
+              }
+            }
+          },
+          "description": "Layers emit only featureSelect and featureHover."
+        },
+        {
+          "if": {
+            "properties": {
+              "ref": {
+                "pattern": "^widget:"
+              }
+            },
+            "required": [
+              "ref"
+            ]
+          },
+          "then": {
+            "properties": {
+              "event": {
+                "const": "selection"
+              }
+            }
+          },
+          "description": "Widgets emit only selection."
+        },
+        {
+          "if": {
+            "properties": {
+              "ref": {
+                "pattern": "^control:"
+              }
+            },
+            "required": [
+              "ref"
+            ]
+          },
+          "then": {
+            "properties": {
+              "event": {
+                "const": "change"
+              }
+            }
+          },
+          "description": "Controls emit only change."
+        }
+      ],
+      "description": "The event-source half of an interaction. The allOf branches encode the normative source mapping so a schema-valid binding cannot name an event its component kind never emits — previously `{ \"ref\": \"map\", \"event\": \"featureSelect\" }` validated despite having no defined dispatch semantics."
+    }
+  },
+  "properties": {
+    "interactions": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/interaction"
+      },
+      "description": "Declarative event→action bindings between components of this composition document."
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "grid": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "columns": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 24,
+              "default": 12,
+              "description": "Number of grid columns; 12 is the default."
+            }
+          },
+          "description": "Grid geometry. Rows grow as needed; only columns are declared."
+        },
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/layoutItem"
+          },
+          "description": "Widget placements. A composition with widgets and no layout is valid; hosts choose a default flow."
+        }
+      },
+      "description": "Presentation-only grid placement for the document's widgets."
+    }
+  }
+}