Standard: capability-surface tools + session/streaming transport contract

AGENTS.md

@@ -117,6 +117,7 @@ referenced by name in these specs, not redefined here.
     ├── taxonomy.md           # Vocabulary baseline, v1 capability matrix, MCP-vs-gRPC boundary, non-goals
     ├── resources.md          # Per-family resource URIs (honua:// grammar), inspection fields, lifecycle, relationship graph
     ├── planning.md           # Clarification, elicitation, planning, and handoff semantics
+    ├── transport.md          # Session/streaming transport: protocol revision, Mcp-Session-Id, SSE, progress + list_changed notifications
     ├── corpus.md             # Canonical dataset corpus, fixture conventions, scenario-pack taxonomy
     ├── conformance.md        # Conformance fixtures, evaluation rubric, pass/fail, runtime portability
     └── schemas/              # JSON Schemas + index.json vocabulary map

README.md

@@ -25,6 +25,7 @@ conformance strategy established; downstream consumer work tracked in
 | [Taxonomy, Capability Matrix, and Non-Goals](spec/taxonomy.md) | Vocabulary baseline, v1 coverage matrix, MCP vs gRPC boundary, explicit non-goals |
 | [MCP Resource Contracts](spec/resources.md) | Per-family resource URIs, inspection fields, lifecycle visibility, relationship graph for results, maps, apps, styles, themes, templates, and promotion surfaces |
 | [Clarification, Elicitation, Planning, and Handoff Semantics](spec/planning.md) | Clarification and elicitation semantics, assumption policies, per-family planning step kinds, boundary-crossing handoff contract |
+| [Session and Streaming Transport](spec/transport.md) | Supported protocol revision (2025-06-18), `Mcp-Session-Id` sessions, streamable-HTTP/SSE and stdio transports, `notifications/progress`, and `notifications/*/list_changed` capability notifications |
 | [Canonical Dataset Corpus and Scenario Packs](spec/corpus.md) | Corpus layout, fixture descriptor conventions, canonical synthetic pack, publishing source packs, protocol mirrors, dirty-data packs, expected scenario shapes, and scenario-pack taxonomy |
 | [JSON Schemas](spec/schemas/README.md) | Machine-readable JSON Schema (draft 2020-12) bindings for each core tool `inputSchema` and resource payload shape, plus a `index.json` vocabulary map. Makes the prose implementable. |
 | [Conformance Fixtures and Evaluation](spec/conformance.md) | Fixture layout, operator-workflow scenario model, pass/fail rubric, runtime portability guidance, scenario coverage matrix |

conformance/fixtures/tools/list_capabilities/list_capabilities.json

@@ -0,0 +1,13 @@
+{
+  "id": "list_capabilities.analyze",
+  "schemaRef": "tools/list_capabilities.schema.json",
+  "validates": "inputs",
+  "inputs": {
+    "workflowFamilies": ["Analyze"],
+    "includeResources": true,
+    "includeGrounding": true,
+    "includeAnnotations": true
+  },
+  "expected": "tool_result",
+  "canonicalRefs": ["CapabilityCatalog"]
+}

conformance/fixtures/tools/resolve_entity/resolve_entity.json

@@ -0,0 +1,16 @@
+{
+  "id": "resolve_entity.layer",
+  "schemaRef": "tools/resolve_entity.schema.json",
+  "validates": "inputs",
+  "inputs": {
+    "text": "the parcels layer for the county",
+    "entityKinds": ["Layer", "Dataset"],
+    "limit": 5,
+    "context": {
+      "areaOfInterest": "named:Travis County",
+      "spatialReferenceId": 4326
+    }
+  },
+  "expected": "tool_result",
+  "canonicalRefs": ["CapabilityCatalog", "DatasetRef", "LayerRef"]
+}

spec/conformance.md

@@ -129,7 +129,7 @@ A fixture's `expected` value is exactly one of:
 |---|---|---|
 | `emit_plan` | Tool fixtures for the named plan-emitting MCP tool: `plan_analysis` (Analyze). Publish Data, Build App, and Automate / Deploy do not define a plan-emitting MCP tool in [taxonomy.md §MCP Tools to Workflow Family Mapping](taxonomy.md#mcp-tools-to-workflow-family-mapping); their plans surface to MCP through `validate_plan` or direct family tools (per [planning.md §2](planning.md#2-clarification-and-elicitation-semantics) and the per-family handoff model in [planning.md §5](planning.md#5-plan-handoff-semantics)) until upstream names additional plan-emitting MCP tools. A harness MUST NOT fixture an `emit_plan` shape under a tool name the taxonomy does not define; if upstream later names per-family plan-emitting tools, this row and the taxonomy tool matrix update together | Canonical `AnalysisPlan`, expected `outputs` declaration per [planning.md §5.4](planning.md#54-boundary-crossing-fields); no validation verdict is asserted |
 | `plan_validation` | Tool fixtures for `validate_plan` (Analyze, Publish Data, Build App per [taxonomy.md §MCP Tools to Workflow Family Mapping](taxonomy.md#mcp-tools-to-workflow-family-mapping)) | Canonical `PlanValidationResult` (upstream: [`DETERMINISTIC_OPERATOR_WORKFLOW_RESULTS.md` §Stage Model](https://github.com/honua-io/honua-server/blob/main/docs/developer/DETERMINISTIC_OPERATOR_WORKFLOW_RESULTS.md#stage-model) and [`AI_OPERATOR_CONTRACT.md` §ValidatePlan](https://github.com/honua-io/honua-server/blob/main/docs/developer/AI_OPERATOR_CONTRACT.md)) asserted over a supplied canonical plan; the fixture asserts structural validation, capability preview, authorization preview, and policy preview outcomes without emitting a new plan |
-| `tool_result` | Tool fixtures that return a canonical resource object or assert a boundary-crossing handoff rather than a plan (`ground_candidates` → a candidate grounding result over `CapabilityCatalog` plus a draft family intent (`AnalysisIntent` / `PublishingIntent`), emitting an `emit_clarification` shape instead when grounding surfaces ambiguity; `get_style` → a read-only `StyleRef` projection (canonical per [resources.md §`honua://styles/{style_id}`](resources.md#honuastylesstyle_id)); `execute_plan` → `ExecutionJob` reference for Analyze; Publish Data `execute_plan` asserts submission into `PipelineService` with **no MCP-owned return object** — `PipelineService`-owned internal execution state (publication-state read, refresh-run identity) is not an MCP resource in this version of the standard and cannot be expressed through `resource_projection`; post-handoff promotion-surface state (`PublishedService`, `Deployment`) is expressed through a `resource_projection` fixture against the stable `honua://` URI and responsibility-level projection per §3.1/§3.2, and only truly non-constructible reserved routes (for example `PublishingResultPackage`) remain deferred-shape fixtures per §2.4; `create_app_package` → `AppPackage`; `preview_app_package` → preview `ArtifactRef` (canonical per [resources.md §`honua://apps/{app_package_id}`](resources.md#honuaappsapp_package_id) and the Reserved `honua://results/{id}` — Builder Result section in the same document); `create_map_package`, `refine_map_package`, `apply_style_preset`, `compose_mixed_protocol_map` → `MapPackage`; `preview_map_package` → preview `ArtifactRef`; `publish_result` → canonical promotion-surface target per family: `PublishedService` for Analyze and Publish Data and `Deployment` for Build App, bound at the stable `honua://services/{published_service_id}` / `honua://deployments/{deployment_id}` URI and responsibility-level projection defined in [resources.md §Promotion-Surface Resources](resources.md#promotion-surface-resources); only concrete field spellings still finalizing in `honua-server#730` / `honua-server#732` stay deferred per §2.4) | For canonical-return tools, the returned object by name and, where defined in [resources.md](resources.md), the `honua://` URI under which it is addressable. For `ground_candidates`, the bound `CapabilityCatalog`-derived candidate set and the draft family intent (`AnalysisIntent` / `PublishingIntent`); no plan or handoff is asserted, and an ambiguous grounding uses an `emit_clarification` fixture instead. For `get_style`, the resolved `StyleRef` bound at its `honua://styles/{style_id}` URI. For Publish Data `execute_plan`, the fixture binds the handoff boundary only: it MUST NOT invent a local job/result noun, and the enclosing scenario MUST NOT require a `resource_projection` fixture against a non-MCP `PipelineService`-owned surface. Any post-handoff state the scenario wants to assert against a promotion-surface resource (`PublishedService`, `Deployment`) is expressed as a `resource_projection` fixture bound to the stable `honua://` URI and responsibility-level projection from [resources.md](resources.md); only assertions that depend on the still-finalizing concrete field set follow §2.4. Truly non-constructible reserved routes (for example `PublishingResultPackage`, which has no stable shared identifier yet) remain name-only deferred shapes per §2.4 |
+| `tool_result` | Tool fixtures that return a canonical resource object or assert a boundary-crossing handoff rather than a plan (`list_capabilities` → an MCP-owned capability-surface projection per [taxonomy.md §Grounding-as-Tools](taxonomy.md#grounding-as-tools), validated against [`tools/list_capabilities.output.schema.json`](schemas/tools/list_capabilities.output.schema.json) and asserting no plan or handoff; `resolve_entity` → ranked, evidence-backed canonical entity references over `CapabilityCatalog` / `honua://catalog/features` (validated against [`tools/resolve_entity.output.schema.json`](schemas/tools/resolve_entity.output.schema.json)), emitting an `emit_clarification` shape instead when the text is too ambiguous to ground; `ground_candidates` → a candidate grounding result over `CapabilityCatalog` plus a draft family intent (`AnalysisIntent` / `PublishingIntent`), emitting an `emit_clarification` shape instead when grounding surfaces ambiguity; `get_style` → a read-only `StyleRef` projection (canonical per [resources.md §`honua://styles/{style_id}`](resources.md#honuastylesstyle_id)); `execute_plan` → `ExecutionJob` reference for Analyze; Publish Data `execute_plan` asserts submission into `PipelineService` with **no MCP-owned return object** — `PipelineService`-owned internal execution state (publication-state read, refresh-run identity) is not an MCP resource in this version of the standard and cannot be expressed through `resource_projection`; post-handoff promotion-surface state (`PublishedService`, `Deployment`) is expressed through a `resource_projection` fixture against the stable `honua://` URI and responsibility-level projection per §3.1/§3.2, and only truly non-constructible reserved routes (for example `PublishingResultPackage`) remain deferred-shape fixtures per §2.4; `create_app_package` → `AppPackage`; `preview_app_package` → preview `ArtifactRef` (canonical per [resources.md §`honua://apps/{app_package_id}`](resources.md#honuaappsapp_package_id) and the Reserved `honua://results/{id}` — Builder Result section in the same document); `create_map_package`, `refine_map_package`, `apply_style_preset`, `compose_mixed_protocol_map` → `MapPackage`; `preview_map_package` → preview `ArtifactRef`; `publish_result` → canonical promotion-surface target per family: `PublishedService` for Analyze and Publish Data and `Deployment` for Build App, bound at the stable `honua://services/{published_service_id}` / `honua://deployments/{deployment_id}` URI and responsibility-level projection defined in [resources.md §Promotion-Surface Resources](resources.md#promotion-surface-resources); only concrete field spellings still finalizing in `honua-server#730` / `honua-server#732` stay deferred per §2.4) | For canonical-return tools, the returned object by name and, where defined in [resources.md](resources.md), the `honua://` URI under which it is addressable. For `ground_candidates`, the bound `CapabilityCatalog`-derived candidate set and the draft family intent (`AnalysisIntent` / `PublishingIntent`); no plan or handoff is asserted, and an ambiguous grounding uses an `emit_clarification` fixture instead. For `get_style`, the resolved `StyleRef` bound at its `honua://styles/{style_id}` URI. For Publish Data `execute_plan`, the fixture binds the handoff boundary only: it MUST NOT invent a local job/result noun, and the enclosing scenario MUST NOT require a `resource_projection` fixture against a non-MCP `PipelineService`-owned surface. Any post-handoff state the scenario wants to assert against a promotion-surface resource (`PublishedService`, `Deployment`) is expressed as a `resource_projection` fixture bound to the stable `honua://` URI and responsibility-level projection from [resources.md](resources.md); only assertions that depend on the still-finalizing concrete field set follow §2.4. Truly non-constructible reserved routes (for example `PublishingResultPackage`, which has no stable shared identifier yet) remain name-only deferred shapes per §2.4 |
 | `emit_clarification` | Tool fixtures for `clarify_intent` and any planning or validation tool when reason codes apply | `ClarificationRequest` with `reasonCodes[]` (subset of [planning.md §2.1](planning.md#21-trigger-conditions)) and per-question `kind` drawn from `ClarificationQuestionKind` |
 | `resource_projection` | Resource fixtures | For resource families defined in [resources.md §Resource URI Conventions](resources.md#resource-uri-conventions): a `honua://` URI matching that section and the per-family responsibilities enumerated in the same document. For planning-stage families referenced by [planning.md §3](planning.md#3-planning-stage-resources) that use the open-core data-access surface (per §2.1): the open-core `honua://services/{encodedServiceId}/layers/{layerId}` route per [MCP_SERVER.md](https://github.com/honua-io/honua-server/blob/main/docs/developer/MCP_SERVER.md) for dataset/layer reads, or a canonical-object-name binding (`CapabilityCatalog`, `ProcessDefinition`) for families that do not carry an MCP inspection URI in this version of the standard. A fixture MUST NOT mint a new `honua://` route for a family this spec does not define |
 | `metadata_cache_state` | Metadata-read fixtures that assert the cache-state projection on a metadata-oriented surface (catalog, dataset/layer, process, style, theme, template, or published-service metadata) | The `cache` projection defined in [resources.md §Metadata Cache State](resources.md#metadata-cache-state): `cache.state` drawn from the upstream five-state set (`hit`, `miss`, `stale`, `refreshed`, `bypass`) and the visibility fields available to the read (`keyFingerprint`, `age`, `ttl`, `revalidatedAt`, `validators`, `invalidationReason`, `refreshErrorId`). A failed revalidation pairs a `stale`-or-last-known `cache.state` carrying a `refreshErrorId` with a `geoprocessing_error` fixture whose canonical `GeoprocessingError` correlates to that id; the fixture MUST NOT mint an MCP-local cache state or cache error code. Feature/query/non-materialized result fixtures MUST NOT carry this projection (per [resources.md §Feature, Query, and Result Reads Are Not Default-Cached](resources.md#feature-query-and-result-reads-are-not-default-cached)) |

spec/planning.md

@@ -199,7 +199,10 @@ indefinitely.
 prompts render the questions to the client and carry answers back as
 `ClarificationResponse`. The transport does not own the reason codes, the
 question kinds, or the assumption policy; those are protocol semantics defined
-here and reused from the upstream contract.
+here and reused from the upstream contract. The concrete transport realization
+of this mapping — MCP-native `elicitation/create` on revision `2025-06-18`, with
+the `emit_clarification` tool-result fallback on older revisions — is specified
+in [transport.md §Elicitation Transport](transport.md#6-elicitation-transport).
 
 A transport MAY batch multiple `ClarificationRequest`s before returning to the
 planner, but MUST preserve `questionId` identity so answers remain bindable.

spec/schemas/README.md

@@ -87,4 +87,18 @@ prefix-independent.
 | [`index.json`](index.json) | Machine-readable tool/resource → schema map |
 | [`common/geoprocessing-error.schema.json`](common/geoprocessing-error.schema.json) | The canonical `GeoprocessingError` envelope (shared) |
 | [`tools/*.schema.json`](tools/) | One `inputSchema` per core tool family |
+| [`tools/*.output.schema.json`](tools/) | The MCP 2025-06-18 `outputSchema` for the tools whose return shape the standard owns (`list_capabilities`, `resolve_entity`) |
 | [`resources/*.schema.json`](resources/) | One payload schema per core resource family |
+
+## Output schemas
+
+MCP revision `2025-06-18` (see [transport.md](../transport.md)) adds tool
+`outputSchema` / `structuredContent`. The standard publishes an `outputSchema`
+only where it **owns** the return shape — currently the capability-surface
+introspection tools `list_capabilities` and `resolve_entity`, whose outputs are
+MCP-owned projections rather than upstream canonical objects. Every other tool's
+return is asserted through the conformance expected-behavior shapes
+([`spec/conformance.md` §2.3](../conformance.md#23-expected-behavior-shapes)),
+which bind the canonical object by name; that pattern is unchanged. Where an
+`outputSchema` exists, `index.json` records it on the tool entry under
+`outputSchema`, and the tool's safety annotations under `annotations`.