# @honua/sdk-js — full documentation corpus > One TypeScript/JavaScript geospatial client for Esri GeoServices, OGC API (Features/Tiles/Maps/Processes), STAC, WMS/WMTS, WFS 2.0, and OData v4 — a single protocol-neutral Dataset → Source → Query → Result contract, a MapLibre-first map runtime, and a drop-in ArcGIS migration codemod. This file concatenates the documents indexed in `llms.txt` for single-fetch ingestion. --- # File: README.md # Honua JS SDK [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/honua-io/honua-sdk-js/badge)](https://scorecard.dev/viewer/?uri=github.com/honua-io/honua-sdk-js) [![npm](https://img.shields.io/npm/v/@honua/sdk-js?color=2b6cb0&label=%40honua%2Fsdk-js)](https://www.npmjs.com/package/@honua/sdk-js) [![types](https://img.shields.io/npm/types/@honua/sdk-js?color=3178c6)](https://www.npmjs.com/package/@honua/sdk-js) [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE) [![node](https://img.shields.io/node/v/@honua/sdk-js?color=43853d)](./package.json) [![docs](https://img.shields.io/badge/docs-honua--io.github.io-2b6cb0)](https://honua-io.github.io/honua-sdk-js/) > **MapLibre gives you the map. Honua gives you everything else.** `@honua/sdk-js` is the integration layer for the open map stack: typed clients for the protocols your data already speaks (Esri GeoServices, OGC API Features / Tiles / Maps / Processes, STAC, WMS, WMTS, WFS 2.0, OData v4), a one-call data→map bridge and MapLibre runtime, provider-pluggable geocoding and routing, and a drop-in ArcGIS compatibility layer with a codemod — everything around the renderer, so MapLibre (2D) and Cesium (3D) can do what they do best. **Leaving ArcGIS?** Every classic Esri widget was deprecated at ArcGIS JS SDK 5.0 and is removed at 6.0 — planned for **Q1 2027**. If your app constructs one, that code stops compiling and running when you take the 6.0 upgrade. Run `npm run scan:arcgis:widgets -- ./src` for a per-file readiness report, then read the [widget-removal survival guide](./docs/widget-survival-guide.md) — every deprecated widget mapped to its Honua/MapLibre disposition. ## A public endpoint to a styled map Nine application lines. No Honua server, no API key, no account — a public Esri Living Atlas FeatureServer becomes a styled, interactive MapLibre map: ```ts doc-test=compile import { connect } from "@honua/sdk-js"; import { mountSource } from "@honua/sdk-js/map"; import maplibregl from "maplibre-gl"; const endpoint = "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/2020_Census_State_Apportionment/FeatureServer/0"; const map = new maplibregl.Map({ container: "map", style: "https://demotiles.maplibre.org/style.json", center: [-98, 39], zoom: 3 }); await map.once("load"); const data = await connect({ endpoint, protocol: "auto", authorizationScopeFingerprint: "public" }); await mountSource(map, data.source(), { popup: { factory: () => new maplibregl.Popup(), fields: ["NAME", "Seats_2020"] }, hover: true, fitBounds: true, }); ``` For those nine lines the bridge selected a materialization strategy from the source's declared capabilities, installed geometry-appropriate default styling, wired click popups and hover feature-state, fit the map to the data, and returned one owned handle (`setFilter()` diff-updates in place; `dispose()` removes everything the bridge added). Run it locally with `npm run demo:endpoint-to-map` ([`examples/endpoint-to-map/`](./examples/endpoint-to-map/README.md)); the full cookbook is [`docs/data-to-map-bridge.md`](./docs/data-to-map-bridge.md). **Release status: beta** (`0.1.0-beta.0`). The 22-entrypoint stable tier is frozen and guarded by an API-surface gate; 11 experimental subpaths may change before 1.0, and 18 deprecated compatibility subpaths have explicit removal versions. See [`config/support-manifest.v1.json`](./config/support-manifest.v1.json) for the versioned support truth, [`config/public-surface.json`](./config/public-surface.json) for its generated package projection, [`support/projections/sdk-support.v1.json`](./support/projections/sdk-support.v1.json) for the generic site/sample consumer contract, and [the scope decision](./docs/decisions/scope-split-and-1.0.md). 📚 **Hosted docs:** [honua-io.github.io/honua-sdk-js](https://honua-io.github.io/honua-sdk-js/) — quickstart, the full guide corpus, the [TypeDoc API reference](https://honua-io.github.io/honua-sdk-js/api/), and the [demo gallery](https://honua-io.github.io/honua-sdk-js/gallery.html). ## Pick your path | | 🗺️ **Building on MapLibre** | 🚦 **Leaving ArcGIS** | | --- | --- | --- | | **You are…** | adding typed data access, styling, and interactions to a MapLibre (or brand-new) app | facing the classic-widget removal at ArcGIS JS 6.0 (planned Q1 2027) | | **Start** | [Standalone quickstart](./docs/standalone-quickstart.md) — the SDK against any public endpoint, no Honua server | `npm run scan:arcgis:widgets -- ./src` — per-file 6.0 readiness report from the migration scanner | | **Then** | [Data-to-map bridge cookbook](./docs/data-to-map-bridge.md) — `connect()` → `mountSource()` strategies, styling, filters | [Widget survival guide](./docs/widget-survival-guide.md) — all 38 deprecated widgets mapped to automated / assisted / manual dispositions | | **Go deeper** | [MapLibre runtime](./docs/maplibre-runtime.md) · [React bindings](./docs/react.md) · [geometry ops](./docs/geometry.md) · [geocoding & routing providers](./docs/geocoding-routing-providers.md) | [`esri-compat`](./docs/migration-honua-maplibre.md) drop-ins + the `honua-migrate` codemod · [migration punch list](./docs/migration-punch-list.md) | | **Runnable proof** | [`examples/endpoint-to-map/`](./examples/endpoint-to-map/README.md) — the headline above, live | [`migration-workbench`](./docs/migration-honua-maplibre.md) (`npm run demo:migration-workbench`) — scan → codemod → run, end to end | ## Where it fits The rendering war is settled — MapLibre is the open 2D engine of record and Cesium owns open 3D. What the open stack has been missing is the layer *above* the renderer: service clients, styling, interactions, editing, geocoding, migration tooling — the glue every team hand-rolls. That integration layer is what `@honua/sdk-js` owns: - **Protocol-neutral data access.** One `Source.query(...)` call works against GeoServices, OGC, WFS, OData and friends. Capability misses throw `HonuaCapabilityNotSupportedError` instead of returning empty results. - **Data to map in one call.** `connect()` + `mountSource()` turn a bare endpoint into a styled, interactive MapLibre layer; `loadMapPackage(...)` + `HonuaMapRuntime` render server-authored `MapPackage`s. Cesium, kepler.gl, and OGC web-map sources are first-class. - **TypeScript first.** `strict` + `verbatimModuleSyntax`, exported types for every public symbol, declaration maps, and JSDoc on the public client surface. - **Migrate, don't rewrite.** `FeatureLayerCompat`, `MapImageLayerCompat`, `MapViewCompat`, `SceneViewCompat`, `WebMapCompat`, and a safe codemod (`honua-migrate`) keep existing ArcGIS code running while you cut over. - **No provider lock-in for the extras.** Geocoding and routing are provider-pluggable interfaces with open-source adapters, not a facade for one vendor's API ([`docs/geocoding-routing-providers.md`](./docs/geocoding-routing-providers.md)). The honest comparisons are the service-client libraries, not the renderers: - vs **`@esri/arcgis-rest-js`** — that's Esri's own client for Esri services only. Honua speaks GeoServices *plus* OGC API / WFS / WMS / WMTS / STAC / OData under one typed contract, with a capability model that throws instead of returning silently-empty results. - vs **`esri-leaflet`** — dormant (no release since September 2025) and Leaflet-bound. Honua's esri-compat + `honua-migrate` codemod is an actively maintained migration path that targets MapLibre. - vs **`openlayers` / `maplibre-gl` directly** — pick those when you need a renderer and are happy hand-rolling service calls; pick Honua *on top of* MapLibre when you want the typed client, the ArcGIS migration path, or the server-authored `MapPackage` runtime. The numbers behind those claims — generated bundle sizes, a protocol-coverage matrix against raw MapLibre / `@esri/arcgis-rest-js` / OpenLayers, and a scripted time-to-first-map benchmark with a runnable repro (`npm run bench:ttfm`) — live in [`docs/comparison.md`](./docs/comparison.md). **Honua Server is optional for standards clients.** Supported GeoServices, OGC API Features, WFS 2.0, STAC, and OData claims work against raw standards-speaking endpoints. OGC API Tiles (`beta`), Maps (`beta`), and Records (`beta`) also discover and use raw advertised paths. OGC API Processes keeps two honest lanes: raw discovery is `experimental`, while typed execution is `facade-required`. A [Honua Server](https://github.com/honua-io/honua-server) adds server-authored `MapPackage`s, realtime, collaboration, MCP/AI execution, compatibility metadata, and the facade-required execution paths. See the generated [backend-agnostic capability matrix](./docs/standalone-capability-matrix.md) for every claim, execution mode, and evidence link. ## What Honua does not do In the spirit of the [migration punch list](./docs/migration-punch-list.md), the non-goals are explicit rather than implied: - **It is not a rendering engine, on purpose.** 2D rendering rides [MapLibre GL JS](https://maplibre.org/) and 3D rides [CesiumJS](https://cesium.com/platform/cesiumjs/); Honua does not fork, wrap-and-hide, or compete with either. If you need renderer features (custom shaders, globe projections, visual effects), take them from the renderer directly — Honua stays out of the way. - **No 3D parity with ArcGIS SceneView.** Esri's 3D moat is real and we say so. Honua's `SceneViewCompat` covers 2D-safe behavior only, and 3D-only widgets (e.g. `Daylight`) are honestly marked `no-equivalent` in the [widget survival guide](./docs/widget-survival-guide.md). For SceneView-class 3D, use [CesiumJS](https://cesium.com/platform/cesiumjs/) or stay on the [ArcGIS Maps SDK](https://developers.arcgis.com/javascript/latest/) for that part of your app. - **Offline is experimental.** The `/offline` subpath is a replica-sync specification without a production storage engine; it is excluded from the 1.0 narrative until a real engine ships. ## Install ```bash npm install @honua/sdk-js ``` Everything documented here ships in `@honua/sdk-js` as subpath entrypoints (see [`INSTALL.md`](./INSTALL.md)). Focused standalone packages are also published from this repository for consumers who only want a subset: | Package | What it is | |---------|------------| | [`@honua/sdk-js`](https://www.npmjs.com/package/@honua/sdk-js) | **The canonical install** — full SDK with all subpath entrypoints + the `honua` CLI | | [`@honua/mcp-server`](https://www.npmjs.com/package/@honua/mcp-server) | Platform-free geospatial MCP server (`honua-mcp`, `honua-mcp-proxy`) — see [`mcp/`](./mcp/README.md) | | [`@honua/react`](https://www.npmjs.com/package/@honua/react) | React provider, hooks, and map components ([`docs/react.md`](./docs/react.md)) | | [`@honua/geometry`](https://www.npmjs.com/package/@honua/geometry) | Curated turf/proj4 geometry ops + reprojection ([`docs/geometry.md`](./docs/geometry.md)) | | [`@honua/sdk`](https://www.npmjs.com/package/@honua/sdk) | Core client + contract only (split build) | | [`@honua/sdk-esri-compat`](https://www.npmjs.com/package/@honua/sdk-esri-compat) | ArcGIS JS compatibility layer (split build) | | [`@honua/honua-migrate`](https://www.npmjs.com/package/@honua/honua-migrate) | Migration codemod + scanner (split build) | | [`@honua/app-platform`](https://www.npmjs.com/package/@honua/app-platform) | Application-platform surfaces extracted from the SDK (own pre-1.0 cadence) | The split builds exist for packaging workflows and subset consumers; details in [`docs/split-packages.md`](./docs/split-packages.md). ### Build-less / CDN usage For static sites, prototypes, or CSP-strict pages that can't run a bundler, a prebuilt browser bundle is published under `dist/browser/`. Drop in the minified IIFE build and use the global `window.HonuaSDK`: ```html ``` Or, for native ES module imports via an ESM CDN: ```html ``` The runtime peers (`maplibre-gl`, `cesium`, `@bufbuild/*`, `@connectrpc/*`) are kept external — load them yourself when you need map rendering or gRPC transport. See [`docs/browser-bundle.md`](./docs/browser-bundle.md) for details. ## Bundle size Small and honest about size: every subpath entrypoint carries a min+gzip byte budget that CI enforces on every PR (`npm run verify:bundle-budgets`), so drift fails the build instead of shipping. Sizes are measured the way a consumer builds — esbuild `--bundle --minify`, runtime peers external. A tree-shake guard proves that importing a single symbol from the root doesn't drag the whole SDK in. | Entrypoint (gzip) | Size | | --- | ---: | | `@honua/sdk-js/geocoding` | 1.9 KiB | | `@honua/sdk-js/expr` | 2.4 KiB | | `@honua/sdk-js/webmap` | 5.9 KiB | | `@honua/sdk-js/style` | 8.4 KiB | | `@honua/sdk-js/map` | 31.2 KiB | | `@honua/sdk-js` (root) | 94.9 KiB | | `{ HonuaClient }` only (tree-shake guard) | 48.6 KiB | Full per-entrypoint table (min + gzip, generated, not hand-written): [`docs/bundle-sizes.md`](./docs/bundle-sizes.md). Refresh it with `npm run report:bundle-sizes`. For how these sizes stack up against `@arcgis/core` and friends, see the generated [comparison page](./docs/comparison.md). ## 60-second quickstart **No Honua server required.** The first block below runs against a *public* Esri GeoServices endpoint — no API key, no account, no infrastructure. The canonical surface is protocol-neutral: build a `Dataset` over one or more `Source`s, then call `queryAll()` (or `query()` / `stream()`). ```ts doc-test=compile import { createDataset, HonuaClient, PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js"; // A public Esri Living Atlas FeatureServer — nothing of Honua's is running. const client = new HonuaClient({ baseUrl: "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis", }); const dataset = createDataset({ id: "states", client, sources: [ { id: "apportionment", protocol: "geoservices-feature-service", locator: { url: "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis", serviceId: "2020_Census_State_Apportionment", layerId: 0, }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"], }, ], }); const states = dataset.source("apportionment")!; const result = await states.queryAll({ where: "Seats_2020 > 10", outFields: ["NAME", "Total_Pop_2020", "Seats_2020"], returnGeometry: true, pagination: { limit: 100 }, }); console.log(`Loaded ${result.features.length} states`); ``` The same code works against any GeoServices, OGC API Features, WFS, OData, or STAC endpoint. Migrating from `esri-leaflet`? The raw GeoServices shape and the `esri-compat` drop-in point at `services.arcgis.com`-style URLs unchanged: ```ts doc-test=skip reason="partial excerpt requires application host context" const { features } = await client.queryFeatures({ serviceId: "2020_Census_State_Apportionment", layerId: 0, where: "1=1", outFields: ["*"], returnGeometry: true, resultRecordCount: 25, }); ``` Run the complete standalone app locally — public endpoint in, MapLibre map out: ```bash npm install npm run demo:standalone:mock # deterministic fixture lane (what CI runs) npm run demo:standalone # live lane against the public Esri endpoint ``` See [`docs/standalone-quickstart.md`](./docs/standalone-quickstart.md) for the guided server-optional walkthrough, [`docs/standalone-capability-matrix.md`](./docs/standalone-capability-matrix.md) for the backend-agnostic vs server-enhanced breakdown, and [`examples/standalone-quickstart/`](./examples/standalone-quickstart/README.md) for the committed source. ### Add a Honua Server A [Honua Server](https://github.com/honua-io/honua-server) unlocks server-authored `MapPackage`s (`loadMapPackage()`), realtime subscriptions, collaboration / saved maps, and the MCP + AI surfaces. Point the same code at a local server (`docker compose up` in a honua-server checkout), and gate production reads on the compatibility check: ```ts doc-test=skip reason="partial excerpt requires application host context" const { supported, reasons } = await client.checkCompatibility(); if (!supported) throw new Error(`Unsupported Honua server: ${reasons.join("; ")}`); ``` The server-connected lane is the [`maplibre-quickstart`](./examples/maplibre-quickstart/README.md) example (`npm run demo:quickstart:mock`); see [`docs/quickstart.md`](./docs/quickstart.md) and [`docs/quickstart-troubleshooting.md`](./docs/quickstart-troubleshooting.md). ## Command-line client (`honua`) Installing the SDK also installs a first-class **`honua` CLI** — the same querying and catalog browsing without writing code. It wraps the SDK (no raw HTTP, no URL-encoding, no `f=json`), prints readable tables by default, and adds `--json` / `--format geojson` for machine output. ```bash npm i -g @honua/sdk-js # or: npx @honua/sdk-js honua export HONUA_BASE_URL=https://demo.honua.io # anonymous reads on the public demo honua services # list published services honua layers maui-parcels # list a service's layers honua query maui-parcels/1 --count honua query maui-parcels/1 --where "tmk_txt LIKE '2%'" --limit 5 honua query maui-parcels/1 --bbox -156.7,20.7,-156.3,21.0 --format geojson honua stac collections honua geocode "1 Honolulu Pl, HI" honua map export maui-parcels --bbox -156.7,20.7,-156.3,21.0 --size 800x600 -o maui.png ``` Authentication resolves from `--api-key`, `HONUA_API_KEY`, or a saved `honua login`. Run `honua --help` for the full command surface. This is the recommended replacement for `curl` in docs and demos. For support-safe interoperability evidence, `honua doctor` emits a local, schema-validated diagnostic bundle with explicit classification/consent, credential and PII redaction, bounded previews, and original-byte SHA-256 metadata. `honua doctor --replay` permits only one bounded, abortable `GET`/`HEAD` and fails closed before network access for mutations, subscriptions, unsafe paths, credentials, malformed schemas, or hash drift. It never uploads. See [`docs/diagnostic-bundles.md`](./docs/diagnostic-bundles.md). ## What you can build The versioned [SDK sample catalog](./docs/generated/sample-catalog.md) tracks all 34 executable examples: 0 qualified golden samples, 15 recipes, 17 labs, and 2 fixtures. Seven journey IDs are reserved; 7 remain explicitly planned candidates. The catalog is the source of truth for track, support, lifecycle, fixture/live evidence, quality profiles, and the honua.io projection. Linking to Honua from a plugin directory or ecosystem list? Point at the [server-optional standalone quickstart](./docs/standalone-quickstart.md) ([hosted walkthrough](https://honua-io.github.io/honua-sdk-js/guides/standalone-quickstart.html), [source](./examples/standalone-quickstart/README.md)) — CI keeps it green with a Playwright browser smoke on every PR. Prepared directory entries live in [`docs/listings/maplibre-plugin-directory.md`](./docs/listings/maplibre-plugin-directory.md). ## Mental model: `Dataset` → `Source` → `Query` → `Result` Every Honua SDK — JavaScript, Python, .NET — speaks the same canonical vocabulary. A `Dataset` groups one or more `Source`s. Each `Source` accepts a protocol-neutral `Query` and returns a protocol-neutral `Result`. Operations the canonical surface does not cover stay reachable through the typed `source.protocol(...)` escape hatch. Method casing differs by language (`queryAll()` / `query_all()` / `QueryAllAsync()`), the semantics do not. Capability misses throw `HonuaCapabilityNotSupportedError` (under the default `strict` policy) rather than silently returning empty results. See the [60-second quickstart](#60-second-quickstart) above for the runnable shape; the cross-language semantics, protocol/capability identifiers, language-binding tables, and backwards-compatibility policy live in: - [`docs/sdk-surface-alignment.md`](./docs/sdk-surface-alignment.md) — cross-language naming + semver - [`docs/shared-client-contract.md`](./docs/shared-client-contract.md) — contract design - [`docs/protocol-capability-matrix.md`](./docs/protocol-capability-matrix.md) — what each protocol supports ## Documentation - [`docs/generated/learning-paths.md`](./docs/generated/learning-paths.md) — task-oriented progression backed by runnable examples and checked SDK imports - [`docs/quickstart.md`](./docs/quickstart.md) — guided quickstart walkthrough - [`docs/guide.md`](./docs/guide.md) — long-form reference (server compatibility, subpath entrypoints, OGC / WFS / OData cookbooks, MapLibre runtime, migration CLI, request/auth bridge) - [`docs/errors.md`](./docs/errors.md) — error class reference + retry policy - [`docs/shared-client-contract.md`](./docs/shared-client-contract.md) — `Dataset` / `Source` / `Query` / `Result` design - [`docs/protocol-capability-matrix.md`](./docs/protocol-capability-matrix.md) — what each protocol supports - [`docs/sdk-surface-alignment.md`](./docs/sdk-surface-alignment.md) — cross-language naming & semver policy - [`docs/maplibre-runtime.md`](./docs/maplibre-runtime.md) — `loadMapPackage()` / `HonuaMapRuntime` - [`docs/data-to-map-bridge.md`](./docs/data-to-map-bridge.md) — `connect()` → `mountSource()` standalone bridge cookbook - [`docs/react.md`](./docs/react.md) — React bindings (`@honua/react`): provider, hooks, and map components - [`docs/geometry.md`](./docs/geometry.md) — `@honua/sdk-js/geometry` curated turf/proj4 ops (buffer/area/measure/simplify/reproject) + the `geometryEngine` compat shim - [`docs/geocoding-routing-providers.md`](./docs/geocoding-routing-providers.md) — provider-pluggable geocoding & routing adapters - [`docs/studio-package-contracts.md`](./docs/studio-package-contracts.md) — Studio package-family projections, validation envelope, capability manifest (`@honua/app-platform/studio`) - [`docs/features/README.md`](./docs/features/README.md) — capability snapshot - [`docs/docs-samples-ownership.md`](./docs/docs-samples-ownership.md) — SDK/site ownership boundary for versioned docs and executable samples - [`docs/documentation-snippets.md`](./docs/documentation-snippets.md) — supported code-fence validation and explicit pseudocode directives - [`INSTALL.md`](./INSTALL.md) — install + subpath entrypoint table Platform-wide documentation (server concepts, deployment, Esri migration) lives at [honua.gitbook.io/honuaio](https://honua.gitbook.io/honuaio/). Run `npm run docs:learning:verify` from a fresh checkout to build the SDK and validate learning-path metadata, internal links, generated Markdown, and runtime imports. CI reuses its existing build with the internal `npm run docs:learning:check` command, then separately compiles every selected example through `npm run docs:learning:typecheck`. Run `npm run docs:snippets:verify` to build the public declarations and validate all supported JavaScript and TypeScript documentation fences. ## AI assistants Coding agents (Claude Code, Cursor, and compatible assistants) can discover and correctly use this SDK: - **[`llms.txt`](./llms.txt)** — a curated [llms.txt](https://llmstxt.org/) index of the docs, plus **[`llms-full.txt`](./llms-full.txt)** with the full corpus concatenated for single-fetch ingestion. Both are generated from `docs/` + `README.md` + entrypoint JSDoc by `npm run docs:llms` (freshness-checked in CI via `npm run verify:llms`). - **Agent skills** under [`skills/`](./skills/README.md) — `honua-sdk-quickstart`, `honua-arcgis-migration`, and `honua-mcp-setup` load procedural instructions into Claude Code and compatible agents. See [`skills/README.md`](./skills/README.md) for installation. - **MCP server** — [`@honua/mcp-server`](./mcp/README.md) is the **platform-free** geospatial MCP server: point `honua-mcp` at **any** public ArcGIS FeatureServer or OGC API endpoint (no Honua server required) and it exposes discovery, query, and analysis tools to assistants over the Model Context Protocol. Tools that need a Honua-only surface degrade gracefully with a structured "not available on this target" result. A Honua deployment's richer `/mcp` catalog is the upgrade path via `honua-mcp-proxy`. - **NL map control** — [`@honua/sdk-js/nl-map-control`](./docs/nl-map-control.md) compiles natural-language instructions into serializable, inspectable plans (query-planner IR plus agent-tool invocations) through a **caller-provided LLM callback** — no model-vendor SDK. Execution accepts plans only: read-only plans may auto-execute under policy, anything mutating or viewport-changing requires a signed agent-safety approval envelope, and every execution emits a receipt. The same tool surface is published in MCP and OpenAI function formats. - **Context7** — [`context7.json`](./context7.json) registers the library so [Context7](https://context7.com) serves current docs to coding agents; the submission steps are in [`skills/README.md`](./skills/README.md). - **Coding-agent evals** — a scheduled harness measures whether coding agents can use the SDK correctly on the first try: a 16-task golden-workflow corpus scored objectively (typecheck + runtime against deterministic fixtures + expected-output assertions). Methodology in [`docs/coding-agent-evals.md`](./docs/coding-agent-evals.md); latest results in [`docs/generated/coding-agent-scorecard.md`](./docs/generated/coding-agent-scorecard.md). ## Stability and versioning - The package root is intentionally the small, reviewed `connect → query → explain → mount` workflow. Protocol-specific clients, renderers, app state, styling, migration, realtime, offline, and analytics APIs remain supported from focused subpaths; no advanced API was deleted. The exact root inventory and every former-root replacement are published in [`config/root-surface.json`](./config/root-surface.json) and the generated [`root import migration table`](./docs/root-surface-migration.md). - Hosted guides and API pages display their exact release and expose validated current/archived navigation. See [documentation versions and compatibility](./docs/documentation-versions.md); the selector is generated from package, release-manifest, and changelog data. - The SDK follows [Semantic Versioning](https://semver.org/). The public contract is the set of symbols reachable from the documented subpath entrypoints in [`INSTALL.md`](./INSTALL.md). - Symbols marked `@experimental` in JSDoc may change in any minor release. The full table of stable and experimental subpaths lives in [`INSTALL.md`](./INSTALL.md). The short version: - **Stable** (semver-protected): `@honua/sdk-js`, `@honua/sdk-js/browser`, `@honua/sdk-js/honua`, `@honua/sdk-js/auth`, `@honua/sdk-js/contract`, `@honua/sdk-js/esri-compat`, `@honua/sdk-js/migration`, `@honua/sdk-js/runtime`, `@honua/sdk-js/expr`, `@honua/sdk-js/webmap`, `@honua/sdk-js/geocoding`, `@honua/sdk-js/exploration`, `@honua/sdk-js/interactions`, `@honua/sdk-js/filter-registry`, `@honua/sdk-js/style`, `@honua/sdk-js/map`, `@honua/sdk-js/realtime`, `@honua/sdk-js/react`, `@honua/sdk-js/geometry`, `@honua/sdk-js/cli`, `@honua/sdk-js/agent-tools`, `@honua/sdk-js/agent-safety`. The agent surface's security posture is documented in the [agent-safety threat model](./docs/agent-safety-threat-model.md). - **Experimental subpath-only APIs** (not re-exported from the root barrels): `/nl-map-control`, `/geoparquet`, `/source-schema`, `/source-capabilities`, `/source-capability-discovery`, `/plugin`, `/deckgl`, `/offline`, `/diagnostics`, `/routing` — with `/query-planner` below, 11 experimental subpaths in total. - The complete `/query-planner` subpath remains **experimental**. The stable root promotes a reviewed query-planner subset: `explainQuery`, `executeQueryPlan`, `hashQueryPlan`, the plan errors/version constants, and the types required to name the common explain/mount workflow. - **Application-platform surfaces** (`/app`, `/app-controller`, `/app-workspace`, `/scene-workspace`, `/collaboration`, `/control-plane`, `/replica-sync`, `/share`, `/operate`, `/generated-app`, `/studio`, `/controls`, `/web-components`, `/operator`, `/operator/*`) have **moved to the separate `@honua/app-platform` package**; the old 18 deprecated compatibility subpaths remain through `0.1.x` and are removed in `0.2.0`. The `/console` entrypoint was removed outright (no shim). ## Support and lifecycle We publish a lifecycle because a library you build on should tell you what it promises. `esri-leaflet` never did, and "will this break under me?" is the question that decides adoption. - **Today (pre-1.0, `0.x`).** The **stable tier** — the subpath entrypoints listed under "Stable subpath entrypoints" in [`INSTALL.md`](./INSTALL.md) — is where we invest compatibility effort, and it is guarded in CI by a public-API report (`npm run verify:api-report`): no symbol leaves or changes shape by accident. While we are on `0.x` a minor _may_ still change a stable symbol, but only as a reviewed, called-out change — never silently. Symbols marked `@experimental` in JSDoc may change in any minor. - **At 1.0.** The stable tier freezes under [Semantic Versioning](https://semver.org/): breaking or removing a stable symbol requires a major version; minors are additive. Major versions are coordinated across the Honua SDK family (JavaScript, Python, .NET) so one semver line describes the contract on every platform. - **Application-platform surfaces move separately.** App-shell, builder, and hosted-product entrypoints are being extracted to a separate `@honua/app-platform` package that versions at its own pre-1.0 cadence, so the client SDK can reach a frozen 1.0 without waiting on them. Their old `@honua/sdk-js/*` subpaths remain as `@deprecated` re-export shims through `0.1.x` and are removed in `0.2.0`. See [`docs/decisions/scope-split-and-1.0.md`](./docs/decisions/scope-split-and-1.0.md). - **What we don't promise.** No security-backport window or LTS branch pre-1.0; fixes land on the current line. We will publish that policy when we cut 1.0. ## More guides Long-form reference material now lives in [`docs/guide.md`](./docs/guide.md): - Demo apps in depth (each example's env contract, browser hooks, run lanes) - Server compatibility baseline + `checkCompatibility()` contract - Subpath entrypoints and the `@experimental` tier - Protocol cookbooks — OGC Features / Tiles / Maps / Processes / STAC, WMS / WMTS, WFS 2.0, OData v4 - Mixed Esri + OGC composition, streaming pagination, event lifecycle - MapLibre `MapPackage` runtime + Generated App preview runtime - Request/Auth bridge (interceptors, ArcGIS token + esri-request interop) - `honua-migrate` CLI, admin scanner, parity matrix, sample-corpus harness Protocol-specific deep dives also live alongside the guide: see [`docs/wfs.md`](./docs/wfs.md), [`docs/ogc-api.md`](./docs/ogc-api.md), [`docs/maplibre-runtime.md`](./docs/maplibre-runtime.md), [`docs/webmap-json-compatibility.md`](./docs/webmap-json-compatibility.md), [`docs/protocol-capability-matrix.md`](./docs/protocol-capability-matrix.md), [`docs/migration-punch-list.md`](./docs/migration-punch-list.md), and [`docs/widget-survival-guide.md`](./docs/widget-survival-guide.md) (every ArcGIS widget deprecated at 5.0 mapped to its Honua/MapLibre disposition ahead of the 6.0 removal — run `npm run scan:arcgis:widgets -- ./src` for a per-file readiness report). ## Related Honua repositories | Repo | What it is | |------|------------| | [honua-server](https://github.com/honua-io/honua-server) | Flagship multi-protocol geospatial server (ELv2 open core) | | [honua-console](https://github.com/honua-io/honua-console) | Unified web console — Studio, Catalog, Operate, Share | | [honua-sdk-python](https://github.com/honua-io/honua-sdk-python) | Python SDK (same `Dataset`/`Source`/`Query`/`Result` contract) | | [honua-sdk-dotnet](https://github.com/honua-io/honua-sdk-dotnet) | .NET SDKs (same contract) | | [honua-esri-assess](https://github.com/honua-io/honua-esri-assess) | Esri footprint assessment CLI for migration discovery | | [geospatial-mcp](https://github.com/honua-io/geospatial-mcp) | Open, vendor-neutral geospatial MCP standard | ## Contributing This SDK ships from a single repository: the canonical package is `@honua/sdk-js` (all subpath entrypoints in [`INSTALL.md`](./INSTALL.md) live under that name), with the standalone packages in the table above built from the same source tree. The MCP server lives in [`mcp/`](./mcp/README.md). See [`AGENTS.md`](./AGENTS.md) for contributor instructions and the Specifica issue format used for backlog items. ## Security Report vulnerabilities to [security@honua.io](mailto:security@honua.io) — see the [org security policy](https://github.com/honua-io/.github/blob/main/SECURITY.md). Please do not open public issues for security reports. ## License [Apache 2.0](./LICENSE) --- # File: INSTALL.md # Installing the Honua JavaScript SDK The Honua JavaScript SDK ships as a single npm package — **`@honua/sdk-js`** — with multiple subpath entrypoints. The core client, the Esri compatibility layer, the migration helpers, and the protocol-neutral contract are all reachable from this one install. ## Generated support status The versioned source of truth is [`config/support-manifest.v1.json`](./config/support-manifest.v1.json). It projects 22 supported (documented below as stable), 11 experimental, and 18 deprecated package entrypoints. Protocol status is independent of package lifecycle: raw endpoint support, facade requirements, execution mode, and evidence are listed in the generated [backend-agnostic capability matrix](./docs/standalone-capability-matrix.md). The generic [support projection](./support/projections/sdk-support.v1.json) carries explicit contracts for both honua.io and the canonical `samples/catalog.v2.json` inventory. ## Stable subpath entrypoints Subpaths covered by the SDK's semver contract. Symbols reachable from these entrypoints are stable across minor versions. | Subpath | What it gives you | |---------|-------------------| | `@honua/sdk-js` | Reviewed common `connect → query → explain → mount` surface (37 runtime / 123 declarations) | | `@honua/sdk-js/browser` | Prebuilt browser ESM build of the default barrel (same API as `@honua/sdk-js`) | | `@honua/sdk-js/honua` | `HonuaClient` (the raw GeoServices/OGC client) | | `@honua/sdk-js/auth` | OAuth2/PKCE, client credentials, static providers, and credential stores | | `@honua/sdk-js/contract` | Protocol-neutral `Dataset` / `Source` / `Query` / `Result` + `createDataset` | | `@honua/sdk-js/esri-compat` | Esri ArcGIS JS-API compatibility layer for migration | | `@honua/sdk-js/migration` | Programmatic migration helpers (codemod runner, scan reports) | | `@honua/sdk-js/runtime` | MapLibre `MapPackage` runtime (`loadMapPackage`, `HonuaMapRuntime`) | | `@honua/sdk-js/expr` | Honua expression builder | | `@honua/sdk-js/webmap` | WebMap JSON load/save helpers | | `@honua/sdk-js/geocoding` | Geocoding adapters | | `@honua/sdk-js/exploration` | Linked-view exploration state + presets | | `@honua/sdk-js/interactions` | Hit-test + pointer normalization + chart/map bindings | | `@honua/sdk-js/filter-registry` | Shared filter clause registry + projections | | `@honua/sdk-js/style` | Honua style spec + source parsers/validators | | `@honua/sdk-js/map` | `HonuaMap` programmatic map container | | `@honua/sdk-js/realtime` | Realtime transport adapters (SSE) — a client-transport primitive | | `@honua/sdk-js/react` | React provider, hooks, and map components (optional `react` / `react-dom` peers; published standalone as `@honua/react`) | | `@honua/sdk-js/geometry` | Curated turf/proj4 client-side geometry ops (buffer/area/simplify/reproject) | | `@honua/sdk-js/cli` | Programmatic `run()` entrypoint for the `honua` command-line client | | `@honua/sdk-js/agent-tools` | Agent-facing JSON Schema tool definitions and the bounded tool executor (MCP/OpenAI compatible); the in-repo `@honua/mcp-server` consumes it. See the [agent-safety threat model](./docs/agent-safety-threat-model.md). | | `@honua/sdk-js/agent-safety` | Bounded runtime validation, effect budgets, signed approval envelopes, authenticated single-use consumption, context revalidation, and deterministic execution-receipt verification for JSON-compatible plans ([threat model](./docs/agent-safety-threat-model.md)). | ## Experimental subpath entrypoints Subpaths marked `@experimental` in JSDoc. Useful today; the shape may change in any minor release prior to `1.0.0`. The stable root promotes a reviewed query-planner subset: `explainQuery`, `executeQueryPlan`, `hashQueryPlan`, the plan errors/version constants, and the types required to name the common explain/mount workflow. The complete `@honua/sdk-js/query-planner` subpath remains experimental. Every other experimental subpath is subpath-only and is not re-exported from `@honua/sdk-js` or `@honua/sdk-js/honua`. | Subpath | What it gives you | |---------|-------------------| | `@honua/sdk-js/geoparquet` | GeoParquet / DuckDB-WASM–backed protocol-neutral `Source`; the optional DuckDB peer loads lazily. | | `@honua/sdk-js/query-planner` | Deterministic query IR, side-effect-free explain plans, GeoServices compilation, and explicitly bounded local execution. | | `@honua/sdk-js/source-schema` | Focused experimental SourceSchemaV2 validation, GeoServices/OData/GeoParquet normalization, and one-pass opt-in `connectWithSourceSchemaV2()` discovery. | | `@honua/sdk-js/source-capabilities` | SourceSchemaV2-bound static evidence/CRS validation plus lightweight claimed/observed/effective evaluation, current-source cache checks, bounded strict transport, and dynamic policy/peer/authorization gates; serialized caller data remains potentially sensitive ([guide](./docs/source-capabilities.md)). | | `@honua/sdk-js/source-capability-discovery` | Focused GeoServices/OData `connectWithSourceCapabilities()` integration with canonical descriptor replay binding and fresh policy/environment/peer/authorization evaluation. | | `@honua/sdk-js/plugin` | Versioned, data-only plugin manifests plus deterministic compatibility and authority-boundary certification reports. | | `@honua/sdk-js/deckgl` | Bounded, zero-copy typed-array projection into an optional deck.gl peer, with stable picking identity and deterministic disposal. | | `@honua/sdk-js/offline` | [Versioned downloadable-region manifests](./docs/offline-regions.md) plus storage-neutral quota, integrity, cancellation, and atomic commit contracts. | | `@honua/sdk-js/diagnostics` | Dependency-free diagnostic-bundle validation, sanitization, integrity pinning, and bounded read-only replay used by `honua doctor`. | | `@honua/sdk-js/nl-map-control` | Natural-language map control ([safety model + walkthrough](./docs/nl-map-control.md)): compiles NL instructions into serializable, inspectable plans (query-planner IR + agent-tool invocations) via a caller-provided LLM callback; execution accepts plans only, gates mutations behind agent-safety envelopes, and emits receipts. | | `@honua/sdk-js/routing` | Provider-pluggable routing: typed `RoutingProvider` contract, OSRM and Valhalla adapters, the Honua facade bridge, and per-provider attribution/usage-policy metadata ([provider cookbook](./docs/geocoding-routing-providers.md)). | ## Deprecated compatibility entrypoints These temporary `@honua/sdk-js` shims were introduced in `0.1.0-beta.0` when the application platform moved. They remain available throughout `0.1.x` and are removed in `0.2.0`; new code must import the replacement directly. | Deprecated subpath | Replacement | Remove in | |--------------------|-------------|-----------| | `@honua/sdk-js/app` | `@honua/app-platform/app` | `0.2.0` | | `@honua/sdk-js/app-controller` | `@honua/app-platform/app-controller` | `0.2.0` | | `@honua/sdk-js/app-workspace` | `@honua/app-platform/app-workspace` | `0.2.0` | | `@honua/sdk-js/scene-workspace` | `@honua/app-platform/scene-workspace` | `0.2.0` | | `@honua/sdk-js/collaboration` | `@honua/app-platform/collaboration` | `0.2.0` | | `@honua/sdk-js/control-plane` | `@honua/app-platform/control-plane` | `0.2.0` | | `@honua/sdk-js/replica-sync` | `@honua/app-platform/replica-sync` | `0.2.0` | | `@honua/sdk-js/share` | `@honua/app-platform/share` | `0.2.0` | | `@honua/sdk-js/operate` | `@honua/app-platform/operate` | `0.2.0` | | `@honua/sdk-js/generated-app` | `@honua/app-platform/generated-app` | `0.2.0` | | `@honua/sdk-js/studio` | `@honua/app-platform/studio` | `0.2.0` | | `@honua/sdk-js/operator` | `@honua/app-platform/operator` | `0.2.0` | | `@honua/sdk-js/operator/controllers` | `@honua/app-platform/operator/controllers` | `0.2.0` | | `@honua/sdk-js/operator/workspace` | `@honua/app-platform/operator/workspace` | `0.2.0` | | `@honua/sdk-js/operator/theming` | `@honua/app-platform/operator/theming` | `0.2.0` | | `@honua/sdk-js/operator/i18n` | `@honua/app-platform/operator/i18n` | `0.2.0` | | `@honua/sdk-js/controls` | `@honua/app-platform/controls` | `0.2.0` | | `@honua/sdk-js/web-components` | `@honua/app-platform/web-components` | `0.2.0` | ## Application-platform entrypoints (`@honua/app-platform`) App-shell, app-builder, and hosted-product surfaces have moved out of the client SDK into the separate **`@honua/app-platform`** package, which versions at its own pre-1.0 cadence so `@honua/sdk-js` can reach a frozen 1.0 without waiting on them (see [`docs/decisions/scope-split-and-1.0.md`](./docs/decisions/scope-split-and-1.0.md)). | `@honua/app-platform` subpath | What it gives you | |-------------------------------|-------------------| | `@honua/app-platform/app` | App bootstrap helper for browser shells | | `@honua/app-platform/app-controller` | `HonuaController` — renderer-neutral app controller | | `@honua/app-platform/app-workspace` | Framework-neutral workspace state orchestration | | `@honua/app-platform/scene-workspace` | 3D scene workspace + MapLibre/Cesium adapters (optional `cesium` peer) | | `@honua/app-platform/collaboration` | Saved-map collaboration client | | `@honua/app-platform/control-plane` | Hosted-product / admin client | | `@honua/app-platform/replica-sync` | Offline-replica sync client | | `@honua/app-platform/share` | Embed-token + DCAT sharing helpers | | `@honua/app-platform/operate` | Operations/observability client | | `@honua/app-platform/generated-app` | Manifest projection + preview runtime for generated apps | | `@honua/app-platform/studio` | Studio package-family projections, validation/preview envelopes, capability manifest, publish/share/embed contracts (MCP/QGIS-safe) | | `@honua/app-platform/controls` | Native UI control kit (``) for MapLibre maps | | `@honua/app-platform/web-components` | Framework-neutral custom elements | | `@honua/app-platform/operator` | Operator-native chat/plan-review/approval controllers | | `@honua/app-platform/operator/controllers` | Framework-neutral controllers behind `/operator` | | `@honua/app-platform/operator/workspace` | Operator workspace state container | | `@honua/app-platform/operator/theming` | Operator design-system theme provider + tokens | | `@honua/app-platform/operator/i18n` | Operator message catalog + resolution | During the transition, the deprecated imports listed above keep working through `0.1.x`; they are removed in `0.2.0`. Update imports to `@honua/app-platform/`. The `@honua/sdk-js/console` entrypoint was removed outright (its projection helpers are owned by the `@honua/console` application) and has no shim. ## Prerequisites - Node.js 20 or later - A Honua Server instance only for capabilities marked `facade-required`; standalone protocol clients do not require one ## Install ```bash npm install @honua/sdk-js ``` ### Optional peer dependencies A few integration paths are gated behind **optional peer dependencies** so a Node-only or REST-only consumer never pays the install cost: | Integration | Peer to install | |-------------|-----------------| | MapLibre `MapPackage` runtime (`@honua/sdk-js/runtime`) | `npm install maplibre-gl` | | deck.gl binary projection (`@honua/sdk-js/deckgl`) | `npm install @deck.gl/layers` | | Cesium 3D adapters (`@honua/app-platform/scene-workspace`) | `npm install cesium` | | gRPC-Web transport (`new HonuaClient({ transport: "grpc-web" })`) | `npm install @connectrpc/connect @connectrpc/connect-web @bufbuild/protobuf` | | Geometry ops (`@honua/sdk-js/geometry`) | `npm install proj4 @turf/buffer @turf/area …` (only the ops you import) — or use the `@honua/geometry` split package | | Migration API (`@honua/sdk-js/migration`) | `npm install typescript` | If you stay on the default REST transport with no MapLibre/Cesium scene work, no extra installs are required. ## Quick Start ```typescript doc-test=compile import { HonuaClient } from "@honua/sdk-js"; const client = new HonuaClient({ baseUrl: "https://your-honua-server.com", }); const compatibility = await client.checkCompatibility(); if (!compatibility.supported) { throw new Error( `Unsupported Honua server. Minimum supported version: ${HonuaClient.minimumSupportedServerVersion}. ` + `Reasons: ${compatibility.reasons.join("; ")}`, ); } const result = await client.queryFeatures({ serviceId: "natural-earth", layerId: 0, where: "1=1", returnGeometry: true, outFields: ["*"], outSr: 4326, resultRecordCount: 25, }); const featureCount = result.features?.length ?? 0; console.log(`Found ${featureCount} feature(s)`); ``` Use focused stable subpaths for advanced APIs. The generated [`root import migration table`](./docs/root-surface-migration.md) maps every symbol removed from the transition-era root to its supported replacement; the machine-readable source is [`config/root-surface.json`](./config/root-surface.json). `checkCompatibility()` reads the parsed `data.compatibility` contract from `GET /api/v1/admin/capabilities`. For a runnable browser example from this repo, including the renderable-geometry checks used by the committed MapLibre quickstart, see [`examples/maplibre-quickstart/README.md`](./examples/maplibre-quickstart/README.md). ## Canonical Contract And Exploration The SDK exposes a protocol-neutral client contract and exploration state module that wrap the existing `HonuaFeatureLayer` / `HonuaMapService` / `HonuaOgcFeatureCollection` classes. These are reachable via the `@honua/sdk-js/contract` and `@honua/sdk-js/exploration` subpaths: - [`docs/shared-client-contract.md`](./docs/shared-client-contract.md) — `Dataset`, `Source`, `Capabilities`, `Query`, `Result`, `MapBinding`, and `createDataset(...)`. - [`docs/exploration-context.md`](./docs/exploration-context.md) — `createExplorationContext(...)` with linked-view presets (`globalLinked`, `mapDriven`, `gridDriven`, `chartDriven`, `decoupled`). - [`docs/protocol-capability-matrix.md`](./docs/protocol-capability-matrix.md) — capability coverage per protocol (`geoservices-feature-service`, `geoservices-map-service`, `geoservices-image-service`, `geoservices-geometry-service`, `geoservices-gp-service`, `ogc-features`, `ogc-tiles`, `ogc-maps`, `stac`, `wfs`, `wms`, `odata`). - [`docs/wfs.md`](./docs/wfs.md) — first-party WFS 2.0 adapter, FES filter translation, content-type negotiation, transactions, stored queries, and the `Source.protocol("wfs")` escape hatch. - [`docs/source-binding-alignment.md`](./docs/source-binding-alignment.md) — round-trip mapping between `SourceDescriptor` and the server `SourceBinding` document. - [`docs/maplibre-runtime.md`](./docs/maplibre-runtime.md) — `loadMapPackage(...)` and `HonuaMapRuntime` for the MapLibre GL JS-first `MapPackage` runtime. ## Esri Migration The migration helpers live behind the `@honua/sdk-js/migration` subpath. They power the same codemod that the standalone CLI runs: ```typescript doc-test=compile import { runEsriCompatCodemod, scanArcGisUsage } from "@honua/sdk-js/migration"; const report = scanArcGisUsage("./src"); const migration = runEsriCompatCodemod({ rootDir: "./src", write: true }); ``` ## Version Policy - **Documentation version:** Hosted guides and API entrypoints identify their exact SDK release. Use the generated [documentation version selector](./docs/documentation-versions.md) for tagged archived guides, compatibility ranges, and migration links. - **Pre-release** (`-alpha.*`, `-beta.*`): Published to npm with `@alpha` / `@beta` dist-tags. - **Stable** (`1.0.0+`): Published to npm as `@latest`. - **Semver:** All releases follow [Semantic Versioning](https://semver.org/). Public symbols reachable from the documented subpaths above are covered by the contract; symbols marked `@experimental` in JSDoc may change in any minor release. - **Cross-language alignment:** Major versions are coordinated across the Honua SDK family (JavaScript, Python, .NET) so a single semver line tells you what the contract is on every platform. > **Advanced packaging.** Downstream packagers can also produce a three-package > split (`@honua/sdk` / `@honua/sdk-esri-compat` / `@honua/honua-migrate`) via > `npm run build:split-packages`. This is an opt-in build target, not the default > consumer install. See [`docs/split-packages.md`](./docs/split-packages.md) if you > are integrating with a downstream registry that needs the smaller surfaces. Maintainers can verify the artifact consumers actually install with `npm run verify:packed-sdk` after the library and browser builds. The gate packs the root package, installs it offline into an isolated ESM project, imports every stable and experimental subpath, typechecks every shipped declaration target, and runs the packaged `honua --help` command. Temporary package and consumer directories are removed after both successful and failed runs. --- # File: docs/documentation-versions.md # Documentation versions and compatibility You are reading the documentation for `@honua/sdk-js` **trunk development (package baseline 0.1.0-beta.0)**. Hosted pages are development documentation built from `trunk`, not immutable documentation for the package baseline. Every built page and the deployed `versions.json` identify the exact 40-character source commit. The version navigation in every hosted guide is generated from [`docs/versions.json`](https://honua-io.github.io/honua-sdk-js/versions.json), which is derived from `package.json`, `.release-please-manifest.json`, and released `CHANGELOG.md` entries. A version cannot appear in the selector unless those authoritative sources agree and the release tag exists in the authoritative GitHub repository. ## Release documentation | Version | Status | Channel | Documentation | | --- | --- | --- | --- | | `0.1.0-beta.0` | latest-prerelease | beta | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.1.0-beta.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.20-alpha.0...js-sdk-v0.1.0-beta.0) | | `0.0.20-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.20-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.19-alpha.0...js-sdk-v0.0.20-alpha.0) | | `0.0.19-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.19-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.18-alpha.0...js-sdk-v0.0.19-alpha.0) | | `0.0.18-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.18-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.17-alpha.0...js-sdk-v0.0.18-alpha.0) | | `0.0.17-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.17-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.16-alpha.0...js-sdk-v0.0.17-alpha.0) | | `0.0.16-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.16-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.15-alpha.0...js-sdk-v0.0.16-alpha.0) | | `0.0.15-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.15-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.14-alpha.0...js-sdk-v0.0.15-alpha.0) | | `0.0.14-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.14-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.13-alpha.0...js-sdk-v0.0.14-alpha.0) | | `0.0.13-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.13-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.12-alpha.0...js-sdk-v0.0.13-alpha.0) | | `0.0.12-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.12-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.11-alpha.0...js-sdk-v0.0.12-alpha.0) | | `0.0.11-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.11-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.10-alpha.0...js-sdk-v0.0.11-alpha.0) | | `0.0.10-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.10-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.9-alpha.0...js-sdk-v0.0.10-alpha.0) | | `0.0.9-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.9-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.8-alpha.0...js-sdk-v0.0.9-alpha.0) | | `0.0.8-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.8-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.7-alpha.0...js-sdk-v0.0.8-alpha.0) | | `0.0.7-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.7-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.6-alpha.0...js-sdk-v0.0.7-alpha.0) | | `0.0.6-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-v0.0.6-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-v0.0.5-alpha.0...js-sdk-v0.0.6-alpha.0) | | `0.0.5-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-vv0.0.5-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-vv0.0.4-alpha.0...js-sdk-vv0.0.5-alpha.0) | | `0.0.4-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-vv0.0.4-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-vv0.0.3-alpha.0...js-sdk-vv0.0.4-alpha.0) | | `0.0.3-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-vv0.0.3-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-vv0.0.2-alpha.0...js-sdk-vv0.0.3-alpha.0) | | `0.0.2-alpha.0` | archived | alpha | [Tagged README fallback](https://github.com/honua-io/honua-sdk-js/blob/js-sdk-vv0.0.2-alpha.0/README.md) · [release notes](https://github.com/honua-io/honua-sdk-js/compare/js-sdk-vv0.0.1-alpha.0...js-sdk-vv0.0.2-alpha.0) | The hosted guides and generated TypeDoc API are the development channel. The released prereleases did not publish immutable TypeDoc sites, so every release destination is explicitly labelled a source fallback: it opens the README at the exact release tag and links to canonical release evidence. Released code is never silently redirected to today's development API. ## Compatibility and migration - The exact Node and optional-peer ranges are published in [`versions.json`](https://honua-io.github.io/honua-sdk-js/versions.json) from the current package metadata. - There is no supported-prior line while the SDK has no GA stable release. The machine manifest records that state as `not-applicable`; the first stable line will establish a supported-prior designation policy. - Stable and experimental entrypoint policy is defined in [Install and choose an entrypoint](../INSTALL.md) and checked against the package exports. - Breaking ArcGIS-to-Honua changes and replacement imports are documented in [Migrate ArcGIS applications to Honua + MapLibre](./migration-honua-maplibre.md). - Release-level changes are recorded in the tagged [changelog](../CHANGELOG.md). When an archived guide lacks an equivalent page, use its tagged repository source and release notes. Do not combine code from an archived guide with the current API reference without following the migration notes. --- # File: docs/generated/sample-catalog.md # SDK sample catalog This inventory is generated from [`samples/catalog.v2.json`](../../samples/catalog.v2.json). Do not edit it by hand. Catalog contract: `honua.sdk.sample-catalog.v2` · SDK: `@honua/sdk-js` (effective version derived from `package.json`) · 34 executable examples ## Golden journey readiness Journey IDs are stable roadmap slots. `planned` candidates remain recipes or labs until their golden quality profile and evidence are satisfied; only `qualified` candidates use the golden track. | Journey | Status | Candidate sample | | --- | --- | --- | | `first-map` | planned | [`maplibre-quickstart`](#maplibre-quickstart) | | `service-explorer` | planned | [`service-explorer`](#service-explorer) | | `planning-permitting` | planned | [`planning-permitting-workbench`](#planning-permitting-workbench) | | `incident-operations` | planned | [`realtime-incident-dashboard`](#realtime-incident-dashboard) | | `imagery-terrain` | planned | [`imagery-cog-quickstart`](#imagery-cog-quickstart) | | `cloud-native-analysis` | planned | [`spatial-analytics-workbench`](#spatial-analytics-workbench) | | `arcgis-migration` | planned | [`migration-workbench`](#migration-workbench) | ## Executable samples | Sample | Track | Journey candidate | Support | Lifecycle | Quality profile | Data | Configuration | Demonstration | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | [`ai-spatial-app-builder`](../../examples/ai-spatial-app-builder/README.md) | lab | - | experimental | active | browser-lab | hybrid | approved | Proves typed proposals, shared policy validation, signed single-use approval, bounded execution, refusal, and verified receipt states. | | [`app-bootstrap-basic`](../../examples/app-bootstrap-basic/README.md) | lab | - | deprecated | retire | browser-lab | fixture | not-required | Bootstraps a minimal application through the legacy app-platform compatibility surface. | | [`arcgis-source-app`](../../examples/arcgis-source-app/README.md) | fixture | - | internal | active | internal-fixture | fixture | not-required | Provides the ArcGIS JavaScript source application used by the migration end-to-end harness. | | [`automatic-source-workflow`](../../docs/examples/automatic-source-workflow/README.md) | fixture | - | internal | active | browser-fixture | fixture | not-required | Exercises automatic MapLibre strategy selection, interaction state, refresh, and disposal against deterministic browser fixtures. | | [`cesium-route-playback`](../../docs/examples/cesium-route-playback/README.md) | lab | - | experimental | rework | browser-lab | hybrid | legacy-unsafe | Explores bounded route playback and elevation context through an optional Cesium consumer integration. | | [`edit-workflow-demo`](../../examples/edit-workflow-demo/README.md) | recipe | - | supported | rework | browser-recipe | fixture | not-required | Demonstrates optimistic edits, attachments, conflicts, and safe recovery. | | [`endpoint-to-map`](../../examples/endpoint-to-map/README.md) | recipe | - | experimental | active | browser-recipe | hybrid | approved | mountSource() turns a public FeatureServer into a styled, interactive MapLibre map in four statements. | | [`geocoding-quickstart`](../../examples/geocoding-quickstart/README.md) | recipe | - | supported | rework | browser-recipe | hybrid | legacy-unsafe | Runs forward, reverse, and suggestion workflows with map feedback. | | [`geoprocessing-job-runner`](../../examples/geoprocessing-job-runner/README.md) | recipe | - | supported | merge | browser-recipe | hybrid | legacy-unsafe | Submits, polls, cancels, and inspects asynchronous geoprocessing jobs. | | [`imagery-cog-quickstart`](../../examples/imagery-cog-quickstart/README.md) | recipe | imagery-terrain | supported | rework | browser-recipe | hybrid | legacy-unsafe | Compares WMS imagery, COG-backed ImageServer tiles, and export previews. | | [`kepler-analytics`](../../examples/kepler-analytics/README.md) | lab | - | experimental | rework | browser-lab | hybrid | legacy-unsafe | Replays operations data through kepler.gl with linked filters and KPI evidence. | | [`maplibre-quickstart`](../../examples/maplibre-quickstart/README.md) | recipe | first-map | supported | rework | browser-recipe | hybrid | legacy-unsafe | Connects, discovers, explains, queries, and mounts one source with linked views and inspectable evidence. | | [`mcp-gis-assistant`](../../examples/mcp-gis-assistant/README.md) | lab | - | experimental | rework | browser-lab | fixture | not-required | Demonstrates assistant tool discovery and safe SDK-backed spatial operations. | | [`migration-workbench`](../../docs/migration-honua-maplibre.md) | lab | arcgis-migration | supported | rework | browser-lab | fixture | legacy-unsafe | Scans and transforms ArcGIS application source with auditable compatibility results. | | [`nl-map-control`](../../examples/nl-map-control/README.md) | lab | - | experimental | active | browser-lab | fixture | not-required | A recorded fixture LLM compiles a canned instruction into an inspectable plan; read-only plans auto-execute, mutating plans require a signed agent-safety approval, and every execution emits a receipt beside the live map effects. | | [`node-backend-quickstart`](../../examples/node-backend-quickstart/README.md) | recipe | - | supported | active | headless-recipe | hybrid | approved | Uses the protocol-neutral client from a Node service without browser dependencies. | | [`oauth-signin`](../../examples/oauth-signin/README.md) | recipe | - | supported | active | browser-recipe | fixture | not-required | Demonstrates browser authentication and session lifecycle without embedding credentials. | | [`overture-geoparquet`](../../examples/overture-geoparquet/README.md) | lab | - | experimental | active | browser-lab | hybrid | not-required | Plans and executes bounded Overture GeoParquet queries with truthful worker, range, memory, and pruning evidence. | | [`planning-permitting-workbench`](../../examples/planning-permitting-workbench/README.md) | lab | planning-permitting | supported | rework | browser-lab | fixture | not-required | Combines parcels, hazards, sketching, editing, and export in a task-oriented application. | | [`pmtiles-static`](../../examples/pmtiles-static/README.md) | recipe | - | supported | active | browser-recipe | fixture | not-required | Loads a static PMTiles archive without a Honua server. | | [`react-quickstart`](../../examples/react-quickstart/README.md) | recipe | - | supported | active | browser-recipe | hybrid | approved | Uses the React provider, hooks, and map component over the same quickstart contract. | | [`realtime-incident-dashboard`](../../examples/realtime-incident-dashboard/README.md) | lab | incident-operations | supported | active | browser-lab | hybrid | approved | Runs live-first incident command with observable reconciliation and a guarded, resettable edit lab. | | [`runtime-parity-showcase`](../../examples/runtime-parity-showcase/README.md) | lab | - | experimental | replace | browser-lab | fixture | not-required | Compares supported rendering paths and makes fidelity differences explicit. | | [`service-explorer`](../../examples/service-explorer/README.md) | lab | service-explorer | supported | rework | browser-lab | hybrid | legacy-unsafe | Browses heterogeneous spatial services with capability and cache diagnostics. | | [`shared-renderer-state`](../../docs/examples/shared-renderer-state/README.md) | lab | - | experimental | active | browser-lab | fixture | not-required | Exercises loop-safe camera, selection, filter, and time synchronization across MapLibre and Cesium. | | [`sketch-editing`](../../examples/sketch-editing/README.md) | recipe | - | experimental | active | browser-recipe | fixture | not-required | terra-draw draw modes drive the edit-sketch workflow: undo/redo, snapping, and applyEdits submission. | | [`spatial-analytics-workbench`](../../examples/spatial-analytics-workbench/README.md) | lab | cloud-native-analysis | experimental | rework | browser-lab | hybrid | approved | Explains and accepts one plan linking AOI, map, table, chart, provenance, and reusable output. | | [`stac-imagery-browser`](../../examples/stac-imagery-browser/README.md) | recipe | - | supported | merge | browser-recipe | fixture | not-required | Discovers STAC collections and previews supported imagery assets. | | [`standalone-quickstart`](../../examples/standalone-quickstart/README.md) | recipe | - | supported | merge | browser-recipe | hybrid | approved | Connects a public Esri service directly to MapLibre without a Honua server. | | [`storytelling-25d-map`](../../examples/storytelling-25d-map/README.md) | lab | - | supported | merge | browser-lab | hybrid | legacy-unsafe | Combines terrain, extrusion, OGC overlays, and route playback in a guided story. | | [`temporal-playback`](../../examples/temporal-playback/README.md) | recipe | - | experimental | active | browser-recipe | fixture | not-required | Animates a month of seeded synthetic seismic events with createTemporalPlayback, styled by a first-class classBreaksRenderer whose legend derives from renderer.legendItems(). | | [`terrain-rgb-elevation`](../../examples/terrain-rgb-elevation/README.md) | recipe | - | supported | merge | browser-recipe | hybrid | legacy-unsafe | Reads Terrain-RGB tiles for point elevation and route profiles. | | [`unified-ops-workspace`](../../examples/unified-ops-workspace/README.md) | lab | - | deprecated | retire | browser-lab | fixture | not-required | Composes incident command, analysis, and shared workspace state. | | [`web-components-basic`](../../examples/web-components-basic/README.md) | lab | - | deprecated | retire | browser-lab | fixture | not-required | Demonstrates the SDK custom-element controls against a map. | The catalog also carries fixture/live evidence, evidence expiry, endpoint configuration names, provenance, attribution, freshness, lifecycle targets, validation profiles, and the complete 21-route honua.io migration mapping. The presentation-safe projection is [`samples/dist/honua-site-samples.v2.json`](../../samples/dist/honua-site-samples.v2.json). --- # File: docs/quickstart.md # Five-minute quickstart: endpoint to linked MapLibre map The canonical server-connected browser workflow is the tested app in [`examples/maplibre-quickstart`](../examples/maplibre-quickstart/README.md). It makes the SDK's five-stage journey visible instead of hiding network and fallback decisions: ```text connect → discover → explain → query → mount ``` If you do not need a Honua server, start with the [`standalone quickstart`](./standalone-quickstart.md). It connects directly to a public GeoServices endpoint. This page covers the protocol-neutral Honua lane with compatibility, discovery, planning, evidence, and linked views. ## Run the deterministic lane ```bash npm ci npm run demo:quickstart:mock ``` Open the printed `quickstartMockUrl`. No account, credential, or network-hosted basemap is required. The app: 1. checks SDK/server compatibility; 2. discovers layer metadata and constructs the protocol capability contract; 3. explains a deterministic query plan before fetching rows; 4. executes that accepted plan through `Dataset → Source → Query → Result`; 5. mounts the result in MapLibre and links map, table, filter, detail, and popup state. The page also exposes provenance, capture/observation time, auth mode, SDK/server/data versions, metadata cache state, plan fingerprint, pushdown, fidelity, and degradation. Fixture replay is labeled explicitly and never presented as live data. ### What the five-minute claim measures Required CI sets up the pinned Node runtime, then starts a monotonic clock before `npm ci`, provisions Chromium, builds this fixture app, and stops only after all five stages complete with renderable features and a mounted MapLibre canvas. The 300-second ceiling is enforced by: ```bash npm run docs:quickstart:time-to-map ``` CI uploads `quickstart-time-to-map.json` on success or failure. It records the actual elapsed duration, fixture mode, completed stages, renderable feature count, package version, and revision; it never substitutes a configured or estimated duration. A local invocation measures script-to-map because dependencies and the browser are already installed. Only CI evidence with `cleanInstallIncluded: true` covers runtime setup and a clean install. This automated gate proves the documented path is reproducible within the budget on a fresh runner. It is not evidence of a first-time human usability study; that separate observation remains required before claiming the broader learning architecture acceptance criterion is complete. ## Use an anonymous live endpoint Copy [`.env.example`](../examples/maplibre-quickstart/.env.example), point it at a public CORS-enabled Honua layer, then run the same app: ```bash cp examples/maplibre-quickstart/.env.example examples/maplibre-quickstart/.env npm run demo:quickstart ``` The required live values are: - `VITE_HONUA_QUICKSTART_BASE_URL` - `VITE_HONUA_QUICKSTART_SERVICE_ID` - `VITE_HONUA_QUICKSTART_LAYER_ID` - `VITE_HONUA_QUICKSTART_DATA_VERSION` The filter, bounded record count, basemap style, and optional snapshot timestamp are documented in the [sample README](../examples/maplibre-quickstart/README.md#secret-free-live-run). The browser quickstart rejects API keys and bearer tokens because Vite embeds environment values in public JavaScript. Use an anonymous endpoint or a server-side proxy/session. Protected server-only staging validation remains separate. ## The SDK shape The sample uses stable subpath imports and the explicitly experimental planner: ```ts doc-test=compile import { PROTOCOL_DEFAULT_CAPABILITIES, createDataset } from "@honua/sdk-js/contract"; import { HonuaClient } from "@honua/sdk-js/honua"; import { executeQueryPlan, explainQuery } from "@honua/sdk-js/query-planner"; const client = new HonuaClient({ baseUrl: "https://your-public-honua.example" }); const metadata = await client.getLayerMetadata("public-service", 0); const descriptor = { id: "public-features", protocol: "geoservices-feature-service" as const, locator: { url: "https://your-public-honua.example", serviceId: "public-service", layerId: 0 }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"], schema: { fields: metadata.fields }, }; const dataset = createDataset({ id: "public-map", client, sources: [descriptor] }); const source = dataset.source("public-features"); if (!source) throw new Error("Source resolution failed"); const query = { where: "1=1", outFields: ["*"], returnGeometry: true, pagination: { limit: 25 } }; const plan = explainQuery({ descriptor, query, sourceVersion: "public-service-2026-07" }); const execution = await executeQueryPlan(plan, source, { sourceVersion: "public-service-2026-07" }); console.log(execution.result.features); ``` Planning is synchronous and side-effect free. Execution validates plan integrity and source context before invoking the accepted step. Capability gaps and unsafe fallback bounds throw structured errors; they do not become silent empty maps. ## Requests and validation A healthy startup performs three Honua requests before the basemap's own assets: 1. `GET /api/v1/admin/capabilities` 2. `GET /rest/services/{serviceId}/FeatureServer/{layerId}?f=json` 3. `GET /rest/services/{serviceId}/FeatureServer/{layerId}/query?...` The required CI lane is fixture-only: ```bash npm run demo:quickstart:typecheck npx vitest run test/quickstart-config.test.ts test/quickstart-data.test.ts test/quickstart-linked-exploration.test.ts npm run demo:quickstart:build npm run test:playwright:quickstart ``` See [`quickstart-troubleshooting.md`](./quickstart-troubleshooting.md) for compatibility, discovery, configuration, geometry, plan, CORS, and staging diagnostics. --- # File: docs/generated/learning-paths.md # Learn the Honua SDK by task Choose the outcome you need, then follow the linked guide and runnable implementation. The examples are the canonical executable source; this guide deliberately contains no copied implementation snippets. API reference is SDK-owned at [https://honua-io.github.io/honua-sdk-js/api/](https://honua-io.github.io/honua-sdk-js/api/); the task narrative and deployed sample catalog are site-owned at [https://honua.io/samples](https://honua.io/samples). These paths describe the SDK version in [`package.json`](../../package.json). Sample track, support, lifecycle, data, provenance, freshness, and degradation metadata comes from the [versioned sample catalog](../../samples/contract/v2/README.md); use the [installation and compatibility guide](../../INSTALL.md) when reading docs for another release. ## Execution labels - **Fixture** (`fixture`): Deterministic committed data; no live-service claim. - **Public live** (`public-live`): Reads a public standards endpoint without a Honua account. - **Demo live** (`demo-live`): Can read the deployed demo.honua.io service when configured and reports availability and freshness. - **Authenticated** (`authenticated`): Requires caller-supplied credentials; documentation never embeds a secret. - **Degraded** (`degraded`): A reduced capability remains visible with a structured reason and recovery path. - **Experimental** (`experimental`): Uses a pre-1.0 surface that may change in a minor release. ## Learning paths ### 1. Start with a public map Open a public GeoServices endpoint and render useful data without an account. Labels: `fixture` · `public-live` - Guide: [docs/standalone-quickstart.md](../standalone-quickstart.md) - Runnable example: [standalone-quickstart](../../examples/standalone-quickstart) - Executable entry: [examples/standalone-quickstart/src/main.ts](../../examples/standalone-quickstart/src/main.ts) - Example notes: [examples/standalone-quickstart/README.md](../../examples/standalone-quickstart/README.md) - Compile check: `npm run demo:standalone:typecheck` - Sample contract: `recipe` · `supported` · `merge` - Data and auth: `hybrid` · `anonymous` - Provenance: Committed public-response fixture or public Esri endpoint. - Freshness: Fixture retrieval metadata or live response time. - Catalog degradation: Protocol capability gaps are surfaced without requiring a Honua facade. - Live sample: [sample-expr-builder.html](https://honua.io/sample-expr-builder.html) - Supported API imports: `@honua/sdk-js/esri-compat` (`FeatureLayerCompat`); `@honua/sdk-js/honua` (`HonuaClient`); `@honua/sdk-js/map` (`loadHonuaFeatureServiceGeoJson`) - honua.io journey: `connect-existing-gis` ### 2. Connect and inspect sources Discover services, layers, schemas, and capability gaps before choosing a workflow. Labels: `fixture` · `demo-live` · `authenticated` · `degraded` - Guide: [docs/shared-client-contract.md](../shared-client-contract.md) - Runnable example: [service-explorer](../../examples/service-explorer) - Executable entry: [examples/service-explorer/src/data.ts](../../examples/service-explorer/src/data.ts) - Example notes: [examples/service-explorer/README.md](../../examples/service-explorer/README.md) - Compile check: `npm run demo:service-explorer:typecheck` - Sample contract: `lab` · `supported` · `rework` - Data and auth: `hybrid` · `api-key` - Provenance: Committed multi-protocol catalog or configured Honua catalog. - Freshness: Metadata cache and live observation timestamps. - Catalog degradation: Unavailable admin metadata falls back to service discovery with a visible diagnostic. - Live sample: [sample-service-explorer.html](https://honua.io/sample-service-explorer.html) - Supported API imports: `@honua/sdk-js/contract` (`createDataset`); `@honua/sdk-js/honua` (`HonuaClient`) - honua.io journey: `connect-existing-gis` - Degradation: The current shell still uses the 0.1.x app-workspace compatibility shim; #399 owns its supported-import migration. ### 3. Query from Node or browser code Issue bounded queries, inspect typed results, and keep capability failures explicit. Labels: `fixture` · `demo-live` · `authenticated` · `degraded` - Guide: [docs/composition.md](../composition.md) - Runnable example: [node-backend-quickstart](../../examples/node-backend-quickstart) - Executable entry: [examples/node-backend-quickstart/src/server.ts](../../examples/node-backend-quickstart/src/server.ts) - Example notes: [examples/node-backend-quickstart/README.md](../../examples/node-backend-quickstart/README.md) - Compile check: `npm run demo:node-backend:typecheck` - Sample contract: `recipe` · `supported` · `active` - Data and auth: `hybrid` · `api-key` - Provenance: Committed mock responses or configured Honua endpoint. - Freshness: Fixture replay or live query observation time. - Catalog degradation: The recipe fails explicitly when required server capabilities are absent. - Supported API imports: `@honua/sdk-js/honua` (`HonuaClient`, `QueryBuilder`) - honua.io journey: `query-map-style` - Degradation: The live endpoint may omit requested query capabilities; the sample keeps the typed capability error visible. ### 4. Connect, explain, and map query results Connect, discover, explain, query, and mount one source with linked MapLibre views and visible runtime evidence. Labels: `fixture` · `demo-live` · `experimental` - Guide: [docs/quickstart.md](../quickstart.md) - Runnable example: [maplibre-quickstart](../../examples/maplibre-quickstart) - Executable entry: [examples/maplibre-quickstart/src/main.ts](../../examples/maplibre-quickstart/src/main.ts) - Example notes: [examples/maplibre-quickstart/README.md](../../examples/maplibre-quickstart/README.md) - Compile check: `npm run demo:quickstart:typecheck` - Sample contract: `recipe` · `supported` · `rework` - Data and auth: `hybrid` · `anonymous` - Provenance: Versioned Honolulu fixture replay or an anonymous configured Honua source, identified in runtime evidence. - Freshness: Fixture capture time and data version, or live response observation time. - Catalog degradation: Capability misses, plan warnings, and bounded fallback are shown rather than silently returning an empty map. - Live sample: [demo.html](https://honua.io/demo.html) - Supported API imports: `@honua/sdk-js/contract` (`createDataset`); `@honua/sdk-js/exploration` (`createExplorationContext`); `@honua/sdk-js/honua` (`HonuaClient`); `@honua/sdk-js/query-planner` (`executeQueryPlan`, `explainQuery`) - honua.io journey: `query-map-style` ### 5. Analyze linked spatial views Keep map, table, chart, and spatial aggregation state aligned with visible fallback evidence. Labels: `fixture` · `experimental` · `degraded` - Guide: [docs/warehouse-analytics-sources.md](../warehouse-analytics-sources.md) - Runnable example: [spatial-analytics-workbench](../../examples/spatial-analytics-workbench) - Executable entry: [examples/spatial-analytics-workbench/src/main.ts](../../examples/spatial-analytics-workbench/src/main.ts) - Example notes: [examples/spatial-analytics-workbench/README.md](../../examples/spatial-analytics-workbench/README.md) - Compile check: `npm run demo:spatial-analytics:typecheck` - Sample contract: `lab` · `experimental` · `rework` - Data and auth: `hybrid` · `anonymous` - Provenance: Committed analysis fixtures or a configured public GeoServices source. - Freshness: Fixture replay uses a fixed observation; configured live execution records its observation time. - Catalog degradation: Remote fixtures are labeled replayed, bounded-local execution is capped, unsafe materialization is rejected, and OGC/DuckDB planner execution is a structured #389 follow-on. - Live sample: [demo-analyst-workbench.html](https://honua.io/demo-analyst-workbench.html) · [sample-spatial-analytics.html](https://honua.io/sample-spatial-analytics.html) - Supported API imports: `@honua/sdk-js/contract` (`resolveSpatialAggregationWidgetSummary`); `@honua/sdk-js/exploration` (`createExplorationContext`) - honua.io journey: `linked-large-data-analysis` - Degradation: The current shell still uses the 0.1.x app-workspace compatibility shim; #399 owns its supported-import migration. ### 6. Edit with recovery and capability checks Apply optimistic edits, attachments, and conflict recovery without hiding unsupported mutations. Labels: `fixture` · `degraded` - Guide: [docs/shared-client-contract.md](../shared-client-contract.md) - Runnable example: [edit-workflow-demo](../../examples/edit-workflow-demo) - Executable entry: [examples/edit-workflow-demo/src/main.ts](../../examples/edit-workflow-demo/src/main.ts) - Example notes: [examples/edit-workflow-demo/README.md](../../examples/edit-workflow-demo/README.md) - Compile check: `npm run demo:edit-workflow:typecheck` - Sample contract: `recipe` · `supported` · `rework` - Data and auth: `fixture` · `none` - Provenance: Committed deterministic edit fixture. - Freshness: Deterministic fixture replay time. - Catalog degradation: Editing is read-only when the service does not advertise mutation capability. - Live sample: [demo-editing.html](https://honua.io/demo-editing.html) - Supported API imports: `@honua/sdk-js/contract` (`createEditSession`); `@honua/sdk-js/honua` (`HonuaCapabilityNotSupportedError`) - honua.io journey: `realtime-operations` - Degradation: The current shell still uses the 0.1.x app-workspace compatibility shim, and mutations become read-only when capability or auth is absent. ### 7. Operate through realtime and offline transitions Reconcile snapshots and deltas while showing reconnect, staleness, and deterministic fixture fallback. Labels: `fixture` · `demo-live` · `degraded` - Guide: [docs/realtime-subscriptions.md](../realtime-subscriptions.md) - Runnable example: [realtime-incident-dashboard](../../examples/realtime-incident-dashboard) - Executable entry: [examples/realtime-incident-dashboard/src/realtime-transport.ts](../../examples/realtime-incident-dashboard/src/realtime-transport.ts) - Example notes: [examples/realtime-incident-dashboard/README.md](../../examples/realtime-incident-dashboard/README.md) - Compile check: `npm run demo:incident:typecheck` - Sample contract: `lab` · `supported` · `active` - Data and auth: `hybrid` · `anonymous` - Provenance: Deployed demo stream when advertised; otherwise visibly labeled deterministic replay. Edits are limited to an isolated resettable fixture profile. - Freshness: Snapshot, observation, and event times plus cursor, sequence, lag, reconnect, deduplication, and reconciliation outcomes. - Catalog degradation: Unavailable live capability becomes a visibly labeled read-only replay; stale/offline state disables mutation, and live writes fail closed without an isolated resettable profile. - Live sample: [demo-public-safety.html](https://honua.io/demo-public-safety.html) - Supported API imports: `@honua/sdk-js/realtime` (`createRealtimeServerSentEventsTransport`) - honua.io journey: `realtime-operations` - Degradation: The production offline persistence path is not complete; reconnect and stale-state behavior remains explicit while fixture replay stays deterministic. ### 8. Add terrain and 3D context Progress from stable 2D map primitives to an explicitly experimental 2.5D/3D experience. Labels: `fixture` · `authenticated` · `experimental` · `degraded` - Guide: [docs/scene-workspace.md](../scene-workspace.md) - Runnable example: [storytelling-25d-map](../../examples/storytelling-25d-map) - Executable entry: [examples/storytelling-25d-map/src/map.ts](../../examples/storytelling-25d-map/src/map.ts) - Example notes: [examples/storytelling-25d-map/README.md](../../examples/storytelling-25d-map/README.md) - Compile check: `npm run demo:25d:typecheck` - Sample contract: `lab` · `supported` · `merge` - Data and auth: `hybrid` · `api-key` - Provenance: Committed Oahu story fixtures or configured Honua services. - Freshness: Fixture capture or live layer observation time. - Catalog degradation: Terrain and live overlays fail independently with structured status. - Live sample: [demo-maui-3d.html](https://honua.io/demo-maui-3d.html) - Supported API imports: `@honua/sdk-js/map` (`HonuaMap`); `@honua/sdk-js/runtime` (`HonuaMapRuntime`) - honua.io journey: `imagery-terrain-3d` - Degradation: The runnable 2.5D shell still reaches the scene-workspace compatibility surface; stable map/runtime imports are the taught foundation until #399 migrates it. ### 9. Migrate an ArcGIS application Scan and transform one file at a time with explicit compatibility evidence and manual gaps. Labels: `fixture` · `public-live` · `degraded` - Guide: [docs/migration-honua-maplibre.md](../migration-honua-maplibre.md) - Runnable example: [migration-workbench](../../examples/migration-workbench) - Executable entry: [examples/migration-workbench/src/main.ts](../../examples/migration-workbench/src/main.ts) - Example notes: [docs/migration-honua-maplibre.md](../migration-honua-maplibre.md) - Compile check: `npm run demo:migration-workbench:typecheck` - Sample contract: `lab` · `supported` · `rework` - Data and auth: `fixture` · `none` - Provenance: Committed ArcGIS source fixtures and migration reports. - Freshness: Versioned with the migration corpus. - Catalog degradation: Unsupported ArcGIS modules are reported as manual work, never silently removed. - Live sample: [sample-codemod.html](https://honua.io/sample-codemod.html) - Supported API imports: `@honua/sdk-js/migration` (`runEsriCompatCodemod`, `scanArcGisUsage`) - honua.io journey: `migrate-arcgis` - Degradation: Unsupported ArcGIS modules remain manual migration work and are reported rather than removed silently. ### 10. Automate safely with agent tools Expose bounded map actions with capability explanations while keeping writes behind host approval. Labels: `fixture` · `experimental` · `degraded` - Guide: [docs/ai-map-kit.md](../ai-map-kit.md) - Runnable example: [mcp-gis-assistant](../../examples/mcp-gis-assistant) - Executable entry: [examples/mcp-gis-assistant/src/assistant.ts](../../examples/mcp-gis-assistant/src/assistant.ts) - Example notes: [examples/mcp-gis-assistant/README.md](../../examples/mcp-gis-assistant/README.md) - Compile check: `npm run demo:mcp-gis-assistant:typecheck` - Sample contract: `lab` · `experimental` · `rework` - Data and auth: `fixture` · `none` - Provenance: Committed MCP response fixture. - Freshness: Deterministic fixture replay time. - Catalog degradation: Write tools are unavailable without host policy and explicit approval. - Supported API imports: `@honua/sdk-js/agent-tools` (`HONUA_AGENT_TOOL_DEFINITIONS`, `createHonuaAgentToolExecutor`) - honua.io journey: `safe-agent-automation` - Degradation: The current assistant shell still uses the app-workspace compatibility surface, and write execution stays disabled without explicit host approval. ## Publication boundary - Guides link to runnable example source and never maintain a copied implementation snippet. - Repository documentation uses relative links; canonical API and site narrative links use the declared owners. - Site consumers join the [learning navigation manifest](../learning-paths.v1.json) to the [static sample projection](../../samples/dist/honua-site-samples.v2.json) by `sampleId`; catalog-owned metadata is not copied into another source file. - Sample metadata and evidence are owned by [SDK issue #540](https://github.com/honua-io/honua-sdk-js/issues/540); the generated consumer projection is coordinated by [SDK issue #550](https://github.com/honua-io/honua-sdk-js/issues/550). --- # File: docs/standalone-quickstart.md # Standalone Quickstart: The SDK Against Any Public Endpoint `@honua/sdk-js` is a typed geospatial service client first and a Honua client second. Its protocol clients speak raw **Esri GeoServices**, so they work against *any* ArcGIS Server / ArcGIS Online endpoint with **no Honua server, no API key, and no account**. This is the maintained, MapLibre-targeting successor to `esri-leaflet`. Start here. A [Honua Server](https://github.com/honua-io/honua-server) is the *upgrade path* (authored MapPackages, realtime, collaboration, MCP) — not the entry fee. The [capability matrix](./standalone-capability-matrix.md) draws the honest line between what is backend-agnostic and what needs a Honua Server. ## The first code block runs with zero Honua infrastructure Point the SDK at a public FeatureServer and get typed query results: ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; // A public Esri Living Atlas FeatureServer — no key, no account, no Honua server. const url = "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/2020_Census_State_Apportionment/FeatureServer/0"; const client = new HonuaClient({ baseUrl: "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis" }); const { features } = await client.queryFeatures({ serviceId: "2020_Census_State_Apportionment", layerId: 0, where: "1=1", outFields: ["NAME", "Total_Pop_2020", "Seats_2020"], returnGeometry: false, resultRecordCount: 5, }); console.log(`Loaded ${features?.length ?? 0} states`); ``` `HonuaClient` builds the standard GeoServices request path (`/rest/services/{serviceId}/FeatureServer/{layerId}/query`) and joins it to whatever origin you pass as `baseUrl`, so `services.arcgis.com`, `sampleserver6.arcgisonline.com`, or your own ArcGIS Server all work unchanged. ### Render it on MapLibre in one call `@honua/sdk-js/map` turns a public FeatureServer URL straight into a MapLibre `geojson` source: ```ts doc-test=skip reason="partial excerpt requires application host context" import { HonuaClient } from "@honua/sdk-js/honua"; import { loadHonuaFeatureServiceGeoJson } from "@honua/sdk-js/map"; import maplibregl from "maplibre-gl"; const client = new HonuaClient({ baseUrl: "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis" }); const source = await loadHonuaFeatureServiceGeoJson(client, url, { outFields: ["NAME"] }); const map = new maplibregl.Map({ container: "map", style: "https://demotiles.maplibre.org/style.json" }); map.on("load", () => { map.addSource("states", source); map.addLayer({ id: "states-fill", source: "states", type: "fill", paint: { "fill-color": "#0f766e" } }); }); ``` ### The esri-leaflet migration path works standalone too Pointing `FeatureLayerCompat` (and the rest of `@honua/sdk-js/esri-compat`) at a `services.arcgis.com`-style URL Just Works — it parses the URL, derives the origin, and constructs its own client. Existing ArcGIS-shaped code migrates file-by-file without standing up any Honua infrastructure: ```ts doc-test=skip reason="partial excerpt requires application host context" import { FeatureLayerCompat } from "@honua/sdk-js/esri-compat"; // Same familiar shape as esri-leaflet / arcgis-rest — no server required. const layer = new FeatureLayerCompat({ url }); const { features } = await layer.queryFeatures({ where: "Seats_2020 > 10", outFields: ["NAME"] }); ``` ## Run the committed example The [`examples/standalone-quickstart/`](../examples/standalone-quickstart/README.md) app does exactly the above — public GeoServices query → MapLibre render → the `FeatureLayerCompat` drop-in proof — and ships two lanes: ```bash npm install # Live lane: hits the pinned public Esri endpoint. npm run demo:standalone # Deterministic lane: replays recorded fixtures on same-origin paths (what CI runs). npm run demo:standalone:mock # prints standaloneMockUrl=http://127.0.0.1:PORT ``` CI only ever runs the fixture lane, so it never depends on a third party. Refresh the recordings from the live endpoints on demand with `npm run demo:standalone:refresh-fixtures`. A scheduled, non-blocking workflow (`.github/workflows/standalone-live-smoke.yml`) probes the live endpoints weekly and never gates a PR. ## Documented public endpoints These are the pinned, stable public services the docs and example use. All are anonymous, read-only, and permitted for demonstration use. | Endpoint | Protocol | Provider / license note | | --- | --- | --- | | `https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/2020_Census_State_Apportionment/FeatureServer/0` | GeoServices FeatureServer | Esri Living Atlas; US Census apportionment (public-domain data), publicly shared by Esri. | | `https://sampleserver6.arcgisonline.com/arcgis/rest/services/SampleWorldCities/MapServer/0` | GeoServices MapServer | Esri's public sample server, hosted expressly for samples/demos. | | `https://demo.pygeoapi.io/master/collections` | OGC API Features | pygeoapi's official public demo (MIT project); Natural Earth (public-domain) data. | > **OGC endpoints and the typed surface.** The GeoServices client is the fully > backend-agnostic lane today: it targets raw ArcGIS request paths. The SDK's > *typed* OGC API / WFS / STAC surfaces currently address the Honua server's OGC > facade paths — see the [capability matrix](./standalone-capability-matrix.md) > for the honest, per-capability breakdown and roadmap. ## Add a Honua Server (the upgrade path) When you want more than reads against open services, a [Honua Server](https://github.com/honua-io/honua-server) unlocks: - **Authored `MapPackage`s** — `loadMapPackage()` + `HonuaMapRuntime` render a server-authored map with styles, layer order, and metadata baked in. - **Realtime** — subscription-backed feature updates (`@honua/sdk-js/realtime`). - **Collaboration** — shared/saved maps and multi-user sessions. - **MCP + AI** — the `@honua/mcp-server` and agent tools surface. Spin one up locally and point the same code at it: ```bash # From a honua-server checkout: docker compose up # then set baseUrl to your local server, e.g. http://127.0.0.1:8080 ``` See the [maplibre-quickstart](../examples/maplibre-quickstart/README.md) for the server-connected lane, [`docs/maplibre-runtime.md`](./maplibre-runtime.md) for the `MapPackage` runtime, and [`docs/realtime-subscriptions.md`](./realtime-subscriptions.md) for realtime. --- # File: docs/quickstart-troubleshooting.md # Quickstart Troubleshooting Use this guide when the committed quickstart app at [`examples/maplibre-quickstart/`](../examples/maplibre-quickstart/README.md) does not load as expected. ## Unsupported Compatibility Baseline Symptoms: - the app stops before querying data - the overlay shows an unsupported compatibility message - `window.__HONUA_QUICKSTART_RUNTIME__.serverVersion` or `releaseChannel` is missing or below the SDK baseline - the app reports `Server does not expose GET /api/v1/admin/capabilities.` Checks: - confirm `GET /api/v1/admin/capabilities` is reachable from the browser - confirm the endpoint responds with a JSON object containing `success` and `data.compatibility` - confirm the server reports version `>= 1.0.0` - confirm `data.compatibility.controlPlaneApi.major` is integer `1` with base path `/api/v1/admin` - confirm `data.compatibility.controlPlaneApi.deprecated` is `false` - confirm `data.compatibility.metadataSchemas[]` entries include `version` and `deprecated` - confirm `data.compatibility.features` includes the expected boolean flags - confirm the release channel is `preview` or newer The quickstart app intentionally fails before the feature query when this contract is not satisfied. ## Protected Endpoint Or Invalid Auth Symptoms: - `401` or `403` responses on compatibility or feature-query requests - browser console shows a request error before the map becomes ready Checks: - use a CORS-enabled endpoint that permits anonymous reads for the browser flagship - do not add browser API keys or bearer tokens; the app rejects them because Vite would publish their values - put protected browser traffic behind an application backend or session flow - for server-only staging CI, set `HONUA_STAGING_API_KEY` or `HONUA_STAGING_BEARER_TOKEN` when required The page always reports its auth mode. It never renders credential values. ## CORS Or Browser Network Failures Symptoms: - the browser reports `TypeError: Failed to fetch` - requests work from server-side tools but fail from the browser app Checks: - confirm the Honua server allows the browser origin used by Vite or preview - confirm preflight responses allow the headers your auth mode sends - use the same-origin fixture lane first: ```bash npm run demo:quickstart:mock ``` If the fixture lane works but the live lane fails, the problem is likely environment or browser policy rather than the example code. ## Invalid Quickstart Config Symptoms: - the app fails before the compatibility check runs - the overlay or inline status reports `A quickstart layer id must be an integer.` - the overlay or inline status reports `A quickstart result record count must be greater than zero.` - the overlay reports that the browser quickstart is intentionally secret-free - local staging runs fail with `HONUA_STAGING_BASE_URL is required.` or the matching `HONUA_STAGING_*` required-variable message - the staging workflow fails during its validation step with `Missing HONUA_STAGING_BASE_URL`, `Missing HONUA_STAGING_SERVICE_ID`, or `Missing HONUA_STAGING_LAYER_ID` - `npm run test:quickstart:staging` fails before issuing any network requests when staging env values are malformed Checks: - set `VITE_HONUA_QUICKSTART_LAYER_ID` to an integer - set `VITE_HONUA_QUICKSTART_RESULT_RECORD_COUNT` to a positive integer - remove `VITE_HONUA_QUICKSTART_API_KEY` and `VITE_HONUA_QUICKSTART_BEARER_TOKEN`; use an anonymous endpoint or proxy - set `HONUA_STAGING_BASE_URL`, `HONUA_STAGING_SERVICE_ID`, and `HONUA_STAGING_LAYER_ID` for local or CI staging runs - for staging CI, keep `HONUA_STAGING_LAYER_ID` integer-valued and `HONUA_STAGING_RESULT_RECORD_COUNT` positive when overridden These validation failures happen before the app or staging integration issues `GET /api/v1/admin/capabilities`. ## Empty Feature Queries Symptoms: - the app reports `The feature query returned no features...` - staging integration fails with `featureCount` equal to `0` Checks: - confirm `VITE_HONUA_QUICKSTART_SERVICE_ID` and `VITE_HONUA_QUICKSTART_LAYER_ID` - confirm the configured `where` clause matches seeded data - reduce filter complexity and retry with `1=1` - keep `resultRecordCount` bounded but non-zero The quickstart app expects at least one feature because it fits the map and drives an inspection popup from the query result. ## Unsupported Or Missing Geometry Symptoms: - the app reports `none included renderable geometry` - the feature query succeeds but the map never renders data Checks: - confirm the layer returns geometry-bearing features - confirm the quickstart query keeps `returnGeometry: true` - confirm the requested layer returns geometry that converts into the app's point, line, or polygon render buckets - keep `outSr: 4326` so MapLibre receives browser-safe coordinates The app filters out non-renderable records and only creates render layers for returned points, lines, or polygons. That means `featureCount` can be greater than `renderableFeatureCount` when the server returns mixed-quality data. ## Basemap Style Load Failures Symptoms: - the overlay reports `Failed to load the basemap style "..."` - Honua requests succeed but the map never initializes Checks: - confirm `VITE_HONUA_QUICKSTART_BASEMAP_STYLE` is reachable from the browser - confirm the style JSON and its dependent assets are public or otherwise accessible - use the fixture lane to remove basemap-network variability from the initial debug loop The fixture lane serves `/__honua-quickstart__/basemap-style.json` locally to keep smoke coverage deterministic. ## Staging CI Config Drift The live staging suite is triggered by `npm run test:quickstart:staging` and `.github/workflows/quickstart-staging.yml`. The deterministic browser smoke lane runs from `.github/workflows/ci.yml` on `trunk` plus `release/**` pushes and pull requests. Required environment variables: - `HONUA_STAGING_BASE_URL` - `HONUA_STAGING_SERVICE_ID` - `HONUA_STAGING_LAYER_ID` Optional environment variables: - `HONUA_STAGING_WHERE` - `HONUA_STAGING_RESULT_RECORD_COUNT` - `HONUA_STAGING_API_KEY` - `HONUA_STAGING_BEARER_TOKEN` - `HONUA_QUICKSTART_STAGING_SUMMARY_FILE` If staging CI starts failing after an environment change: - confirm the configured service and layer still exist - confirm the environment still exposes non-empty geometry-bearing data - confirm the auth policy still matches the configured secret or public access path - remember the staging suite reuses the shared quickstart data loader only; it does not open the browser app or fetch the basemap style - review the workflow step summary for `serverVersion`, `releaseChannel`, `featureCount`, `renderableFeatureCount`, `geometryTypes`, and `queryDurationMs` ## Inspecting Runtime State For browser debugging and Playwright smoke assertions, inspect: - `window.__HONUA_QUICKSTART_EVENTS__` - `window.__HONUA_QUICKSTART_RUNTIME__` - `window.__HONUA_QUICKSTART_DISPOSE__()` Useful fields: - `baseUrl`, `serviceId`, `layerId` - `serverVersion`, `releaseChannel` - `sdkVersion`, `dataVersion`, `planId`, `planFingerprint`, `planPushdown` - `featureCount`, `renderableFeatureCount`, `geometryTypes` - `queryDurationMs` - `layerIds`, `mapReady`, `selectedFeatureId`, `popupOpen`, `lastError` - `journeyComplete`, `disposed` Every telemetry event is also dispatched as `CustomEvent("honua:quickstart")`. ## External Follow-on This repo still depends on one bounded external child ticket for long-term staging stability: - `honua-server`: expose and document a stable staging quickstart dataset for JS SDK CI, including the canonical service, layer, auth policy, and non-empty geometry contract. --- # File: docs/comparison.md # How Honua compares **MapLibre gives you the map. Honua gives you everything else.** `@honua/sdk-js` is a typed, protocol-neutral geospatial *service client* and migration toolkit that rides open renderers — it is **not** a rendering engine, so this page does not compare rendering. It compares the things Honua actually claims: the bytes you ship, the protocols you get a real client for, and how fast a new project reaches a working map. Three ground rules keep this page honest: 1. **Every Honua number is generated, never hand-edited.** This whole file is produced by `npm run docs:comparison` from committed, regenerable inputs; CI fails when it drifts (`npm run docs:comparison:check`). See [Methodology](#methodology-and-freshness). 2. **Every external number carries a source URL and an as-of date.** 3. **Non-goals are stated.** Esri's 3D/SceneView stack and MapLibre's rendering quality are not competitions we enter; see the [three-lanes strategy](./decisions/market-strategy-2026-three-lanes.md). ## Bundle size Honua per-entrypoint sizes below are projected from the generated [`docs/bundle-sizes.md`](./bundle-sizes.md) (measured 2026-07-16 at commit `10fe4df`; esbuild `--bundle --minify`, target `es2020`, runtime peers external — the way a real consumer builds). CI enforces a byte budget on every entrypoint (`npm run verify:bundle-budgets`). | What you import | Minified | Gzip | | --- | ---: | ---: | | Full root entrypoint: connect → query → explain → mount workflow | 422.9 KiB | 110.6 KiB | | Importing only `HonuaClient` (tree-shake guard) | 210.5 KiB | 53.2 KiB | | Data→map bridge only: `mountSourceToMapLibre` from `/map` | 33.3 KiB | 10.8 KiB | | Protocol-neutral contract (`Dataset`/`Source`/`Query`/`Result`) | 258.8 KiB | 68.3 KiB | | ArcGIS compatibility layer (drop-in migration surface) | 978.1 KiB | 243.2 KiB | | Geocoding client | 25.1 KiB | 7.3 KiB | | Routing client | 18.7 KiB | 6.0 KiB | For context, the rendering engine itself — `maplibre-gl` 5.21.1, measured locally from this repo's pinned dependency (`dist/maplibre-gl.js`) — is 1024.9 KiB minified / **267.9 KiB gzip**. A complete Honua + MapLibre app therefore ships roughly the engine plus whichever Honua entrypoints it imports. ### Against the alternatives **`@arcgis/core` 4.30 (ArcGIS Maps SDK for JavaScript).** Esri's own automated build metrics for its minimal `@arcgis/core` map samples (esbuild, Angular, React, Vue, Rollup, Webpack lanes). As of 2024-06-27 (4.30, the last core-sample metrics Esri published in jsapi-resources): the main bundle alone is 1.31–1.49 MB minified (0.36–0.42 MB gzip), a simple map view loads **3.5–4.1 MB of JavaScript** at startup, and the on-disk build output is 8.3–10 MB across ~300–740 files. Source (pinned, retrieved 2026-07-13): . To be fair in both directions: `@arcgis/core` bundles its own renderer, so the honest apples-to-apples is *Honua + MapLibre* against `@arcgis/core`. Compared conservatively — our **uncompressed minified** bytes (engine 1024.9 KiB + Honua root 422.9 KiB ≈ 1.41 MB) against Esri's reported startup JavaScript total (3.5–4.1 MB) — the open stack ships roughly a third of the JavaScript, and 0.37 MB over the wire with gzip. Esri's totals also grow with widgets; these figures are its *minimal* samples. **`@esri/arcgis-rest-js`** (, retrieved 2026-07-13). Esri's lightweight REST client family. Small per-package footprint; speaks ArcGIS services only, no map runtime. If all you need is small requests against ArcGIS-only services, it is a fine, lighter choice — the comparison that matters is protocol coverage (below), not bytes. **OpenLayers (`ol`)** (, retrieved 2026-07-13). A full renderer + formats library, not a typed multi-protocol service client; size depends heavily on tree-shaken imports. ## Protocol coverage What you get a first-party, *typed* client for — versus what you hand-roll. Honua's column is derived from the maintained [protocol × capability matrix](./protocol-capability-matrix.md) (per-operation detail lives there; capability misses throw `HonuaCapabilityNotSupportedError` instead of returning empty results). Competitor columns are deliberately coarse: ✓ first-party support, ◐ partial or manual assembly, — not provided. | Protocol lane | Honua SDK | raw `maplibre-gl` | `@esri/arcgis-rest-js` | OpenLayers | | --- | --- | --- | --- | --- | | Esri GeoServices (FeatureServer query/edit) | ✓ typed client | — | ✓ | ◐ (a) | | Esri GeoServices (MapServer / ImageServer render) | ✓ typed client | ◐ (b) | — | ✓ | | OGC API Features (query/edit) | ✓ typed client | ◐ (c) | — | ◐ (d) | | OGC API Tiles / Maps | ✓ typed client | ◐ (b) | — | ✓ | | OGC API Records (catalog search) | ✓ typed client | — | — | — | | STAC (cross-collection search) | ✓ typed client | — | — | ◐ (e) | | WFS 2.0 (typed filters, transactions) | ✓ typed client | — | — | ◐ (f) | | WMS (GetMap + typed GetFeatureInfo) | ✓ typed client | ◐ (b) | — | ✓ | | WMTS (capabilities-driven tiles) | ✓ typed client | ◐ (b) | — | ✓ | | OData v4 (tabular + spatial query, edits) | ✓ typed client | — | — | — | | GeoParquet (client-side SQL via DuckDB-WASM) | ✓ typed client (lazy peer) | — | — | — | | PMTiles archives | ✓ auto-registered protocol | ◐ (g) | — | ◐ (h) | | Geocoding (provider-pluggable) | ✓ Nominatim / Photon / Pelias / Honua | ◐ (i) | ✓ (j) | — | | Routing (provider-pluggable) | ✓ OSRM / Valhalla / Honua | — | ✓ (j) | — | | ArcGIS migration codemod | ✓ `honua-migrate` + esri-compat | — | — | — | Notes: - (a) OpenLayers ships an `EsriJSON` format; service discovery, paging, auth, and edits are hand-rolled requests. - (b) Raw MapLibre renders XYZ/raster endpoints you template by hand; there is no capabilities negotiation, feature query, or typed error surface. - (c) Point a MapLibre GeoJSON source at an `items` URL; paging, filters, CRS negotiation, and edits are yours to build. - (d) OpenLayers parses GeoJSON and has OGC API tile sources, but has no OGC API Features items client (paging, filters, transactions). - (e) Via the third-party `ol-stac` package, not OpenLayers itself. - (f) OpenLayers ships `ol/format/WFS` (GML parsing, filter builders); request orchestration, paging, and transaction bookkeeping are manual. - (g) Via the official `pmtiles` JS package: install it and call `maplibregl.addProtocol` yourself. Honua auto-registers the protocol on map attach. - (h) Via the third-party `ol-pmtiles` package. - (i) Via the `maplibre-gl-geocoder` control plugin, which needs a geocoding API adapter you supply. - (j) `@esri/arcgis-rest-geocoding` / `-routing` speak Esri's ArcGIS location services only (token/credit metering applies); Honua's providers are pluggable across open services. ## Time to first map One scripted, reproducible measurement — from *nothing installed* to a working map against the deterministic fixture lane (mock GeoServices server; **no live endpoints**): | Phase | What is measured | Time | | --- | --- | ---: | | Cold install | `npm install @honua/sdk-js` (v0.1.0-beta.0) into a fresh temp project with an empty npm cache | 14.0 s | | First map | rendered-map-ready in headless Chromium (all five quickstart journey stages complete and a MapLibre canvas mounted) | 7.5 s | | **Total** | | **21.4 s** | Reference run: 2026-07-13, Node v24.7.0, win32/x64, 22 logical CPUs, lane `browser-first-map`. Exact definition of the measured signal: > Cold `npm install @honua/sdk-js` (empty npm cache) in a fresh temp project, plus: build the deterministic maplibre-quickstart fixture-lane example, serve it with the mock GeoServices server, and wait in headless Chromium for the rendered-map-ready signal (all five journey stages complete and a MapLibre canvas mounted). No live endpoints. Reproduce on your machine from a clean checkout: ```bash npm ci npm run bench:ttfm # prints install / first-map / total; evidence JSON in test-results/ ``` **Caveats, stated plainly.** The figure is machine-, network-, and registry-dependent — treat it as a reference point and rerun it locally, not as a guarantee. The mock lane deliberately excludes live-service latency (that is the point: it measures the SDK + toolchain path, not someone's server). When Chromium is unavailable the script falls back to the `node-first-query` lane and the evidence says exactly that — install + fixture-server ready + first successful query, with no browser rendering claimed. ## Methodology and freshness Every number on this page is regenerable from a clean checkout with one command: | Figure | Regenerate with | | --- | --- | | Honua per-entrypoint sizes | `npm run report:bundle-sizes` (budgets enforced in CI by `npm run verify:bundle-budgets`) | | `maplibre-gl` engine size | measured from the pinned `node_modules/maplibre-gl` during `npm run docs:comparison` | | Protocol lanes (Honua column) | derived from [`docs/protocol-capability-matrix.md`](./protocol-capability-matrix.md) during `npm run docs:comparison` | | Time to first map | `npm run bench:ttfm -- --write-reference` | | This page | `npm run docs:comparison` | This file is **generated** (`scripts/generate-comparison-page.mjs`) and CI fails when it is hand-edited or stale (`npm run docs:comparison:check`), mirroring the README's generated-bundle-table discipline. External figures are cited claims with pinned source URLs and retrieval dates in the generator source — update them there, with a new date, or not at all. ## Try it - [60-second quickstart](../README.md#60-second-quickstart) — public endpoint in, typed features out. - [`standalone-quickstart`](./standalone-quickstart.md) — the CI-kept-green, server-optional example: any public GeoServices endpoint → styled MapLibre map. - [Demo gallery](https://honua-io.github.io/honua-sdk-js/gallery.html) — all runnable examples. --- # File: docs/shared-client-contract.md # Shared Client Contract Status: implemented in `src/contract/` (ticket `honua-sdk-js-23`). The shared contract is the protocol-neutral vocabulary every Honua data adapter speaks. It exists so cross-protocol code — exploration views, visual builders, and the server `SourceBinding`/`MapPackage` exporters — can be written once against `Dataset` / `Source` / `Query` / `Result` / `MapBinding` rather than re-litigating the surface in each ticket. ## Goals (and non-goals) - **Goal:** one canonical name for "the dataset", "the source", "the capability", "the query", "the result", "the map binding", and "the exploration state" across `HonuaFeatureLayer`, `HonuaMapService`, `HonuaOgcFeatures`, first-party OGC render/search adapters, first-party WMS / WMTS adapters, the first-party WFS 2.0 adapter, and the first-party OData adapter. - **Goal:** wrap (do not replace) the existing runtime classes in `src/core/surfaces.ts`. Existing callers continue to work; adapter tickets opt in to the canonical surface. - **Goal:** stable serialization shape that survives a round-trip with the server `SourceBinding` / `MapPackage` documents (see [`source-binding-alignment.md`](./source-binding-alignment.md)). - **Non-goal:** a runtime rewrite. The contract is a typed surface plus thin adapter functions — one per built-in protocol (`geoServicesFeatureSource`, `geoServicesMapServiceSource`, `geoServicesImageSource`, `geoServicesGeometryServiceSource`, `geoServicesGPServiceSource`, `ogcFeaturesSource`, `ogcTilesSource`, `ogcMapsSource`, `stacSearchSource`, `wmsSource`, `wmtsSource`, `wfsSource`, `odataSource`). - **Non-goal:** replacing the v1 `Query` envelope while protocol compilers migrate. `Query.where` is a deprecated, source-native compatibility string; new filters use the typed semantic AST from `@honua/sdk-js/query-planner`. ## Module layout ``` src/contract/ ├── index.ts # barrel — re-exports types and source factories ├── spatial-aggregation.ts # indexed aggregation request/response metadata ├── tiles.ts # dynamic query tile descriptors, cache keys, identity ├── types.ts # protocol, capability, source, dataset, query, result └── source.ts # createDataset + built-in adapters ``` Public entrypoint: `@honua/sdk-js/contract` (also re-exported from the top-level `@honua/sdk-js` and `@honua/sdk-js/honua` barrels). ## Cross-SDK binding policy This JS contract is also the draft semantic anchor for the Python and .NET SDKs. The SDKs should align behavior and vocabulary while keeping language-native names and casing. For example, the same operation may surface as `queryAll()` in TypeScript, `query_all()` in Python, and `QueryAllAsync()` in .NET. The binding policy and cross-SDK fixture pack are documented in [`sdk-surface-alignment.md`](./sdk-surface-alignment.md). The JSON fixture pack lives under `test/fixtures/sdk-contract/`; it is intentionally language-neutral so downstream SDKs can consume the same protocol, capability, result, unsupported-capability, and degraded-result scenarios. ## Canonical nouns | Type | What it is | | --- | --- | | `Protocol` | One of twenty identifiers — shared canonical gRPC FeatureService transport (`grpc`), five GeoServices service types (`geoservices-feature-service`, `geoservices-map-service`, `geoservices-image-service`, `geoservices-geometry-service`, `geoservices-gp-service`), OGC API + STAC adapters (`ogc-features`, `ogc-tiles`, `ogc-maps`, `ogc-records`, `stac`), `wfs`, `wms`, `wmts`, `odata`, static-data adapters (`pmtiles`, `geoparquet`), plus three MapLibre-native sources (`maplibre-vector`, `maplibre-raster`, `maplibre-geojson`). | | `Capability` | A coarse-grained per-source operation capability (`query`, `queryAggregate`, `spatialAggregate`, `queryExtent`, `queryObjectIds`, `queryRelated`, `applyEdits`, `attachments`, `render`, `tiles`, `sql`, `stream`, `pbf`, `image`, `geometry`, `geoprocess`, `processes`). The canonical `Source` surface standardizes the query / edit / related / attachment / object-id subset today; `spatialAggregate`, `image` / `geometry` / `geoprocess` / `processes` are negotiated for indexed analytics, `Source.protocol()` escape hatches, and for the `IJobRun`-based OGC API Processes runner because their request shapes are too protocol-specific to belong on the unified query envelope. Top-level `connect()` is product discovery, not an operation on one `Source`, and is tracked as a `discovery` support claim instead. | | `Capabilities` | `ReadonlySet`. Set membership = first-party protocol support, whether the caller consumes it through a canonical `Source` method or the typed protocol escape hatch. Under `strict` (default) a missing capability throws `HonuaCapabilityNotSupportedError`. Under `degraded` only call sites with a defined fallback proceed (today: OGC `queryAggregate` and `queryExtent`); every other missing capability still throws. | | `SourceLocator` | Protocol-specific endpoint info (`url`, `serviceId`, `layerId`, `collectionId`, `tileMatrixSetId`, `styleId`, `typeName`, `entitySet`, `taskName`). Field-compatible with the server `SourceBinding.locator`; `tileMatrixSetId` / `styleId` carry OGC API Tiles / Maps route hints for downstream `SourceBinding` work tracked in [`source-binding-alignment.md`](./source-binding-alignment.md). | | `SourceDescriptor` | `{ id, protocol, locator, capabilities, schema?, attribution? }`. The serializable identity of one source. | | `Source` | Runtime handle. Methods: `query`, `queryAll`, `queryAggregate`, `queryExtent`, `stream`, `queryObjectIds`, `applyEdits`, `queryRelated`, `attachments` (namespace), `protocol` (typed escape hatch; `adapter` is the legacy alias). | | `Dataset` | Logical grouping of sources sharing identity. Methods: `source(id)`, `sourceIds()`, `isCompatible()`, `supportsFeature()`. | | `Query` | The v1 compatibility envelope `{ where?, spatialFilter?, outFields?, orderBy?, pagination?, aggregation?, returnGeometry?, outSr?, signal? }`; `where` is deprecated and source-native. New filters use the typed query-planner AST. | | `Result` | `{ features, exceededTransferLimit, totalCount?, aggregateRows?, extent?, fields?, degraded? }`. | | `SpatialAggregationRequest` / `SpatialAggregationResult` | Indexed spatial aggregation contract for large result sets. Requests carry `where`, `spatialFilter`, `viewport`, zoom/index-resolution hints, opaque index selection, summary specs (`category`, `histogram`, `range`, `count`, `sum`, `avg`, `min`, `max`), and optional `groupBy`. Results carry opaque indexed cells, grouped/totals summaries, backend index metadata, widget metadata, and progressive loading state. | | `EditEnvelope` | `{ adds?, updates?, deletes?, rollbackOnFailure?, signal? }`. Each add / update is a `CanonicalFeature` (attributes + optional geometry + optional id). | | `EditResult` | `{ added, updated, deleted, degraded? }` — one `EditOutcome` per requested operation. | | `EditWorkflowSession` | Form/edit session over one `Source`: projects field metadata and domains, exposes relationship / attachment capability states, stages feature and attachment edits, runs optimistic hooks, and returns a normalized `EditWorkflowSubmitResult`. | | `RelatedQuery` / `RelatedResult` | Canonical related-records request and response. Adapters that lack relationships (OGC, OData, ImageServer) throw rather than return empty groups. | | `AttachmentApi` | Namespace returned by `Source.attachments`. Methods: `query`, `list`, `add`, `update`, `delete`. Adapters that do not advertise `attachments` throw `HonuaCapabilityNotSupportedError` from each method so the namespace property is always present and capability negotiation stays uniform. | | `MapBinding` | `{ sourceId, layerIds, style?, minzoom?, maxzoom? }`. Maps onto `MapPackage.sourceBindings` + `MapPackage.mapSpec` server-side. The `@honua/sdk-js/runtime` module consumes a full `MapPackage` on the client — see [`maplibre-runtime.md`](./maplibre-runtime.md). | | `QueryTileSourceDescriptor` | Typed dynamic vector/query tile descriptor. It binds a canonical `Source` or source id to tile endpoint metadata, query/projection cache identity, fallback policy, and feature identity hooks. Runtime MapLibre helpers and the canonical `/query-tiles` server contract live in [`dynamic-query-tiles.md`](./dynamic-query-tiles.md). | ## Dynamic query tile server contract Dynamic query tiles have a server-side contract in addition to the client descriptor. The canonical route prefix is `/query-tiles`, with TileJSON, vector tile, and feature-detail routes under `/query-tiles/sources/{sourceId}`. The contract defines request parameters for filters, projection fields, output spatial reference, tile matrix set, extent, simplification tolerance, max features, cache partitioning, and cache busting. `@honua/sdk-js/contract` exports route builders, parser helpers, response types, and the `QUERY_TILE_SERVER_CONTRACT_VERSION` constant. The reusable fixture lives at `test/fixtures/sdk-contract/query-tile-server.v1.json` and is intended for Honua server implementation repos to consume in their own conformance tests. ## Capability negotiation Two policies, declared at `createDataset({ capabilityPolicy })`: - `strict` (default): `Source` operations whose required capability is missing throw `HonuaCapabilityNotSupportedError`. Callers can branch on `error.capability` and `error.protocol` to swap protocols, fall back, or surface the limitation to the user. - `degraded`: `Source` operations attempt a client-side fallback when the server cannot serve the capability natively. The result envelope carries `degraded: DegradedReason[]` documenting what was approximated and why. The capability matrix lives in [`protocol-capability-matrix.md`](./protocol-capability-matrix.md). Callers must pass the capability set they want enforced via `SourceDescriptor.capabilities` — per-source overrides (e.g. downgrading `queryAggregate` on a Feature Service whose metadata reports `supportsStatistics: false`) are the caller's responsibility for the GeoServices, OGC, STAC, WFS, and WMS adapters today. **OData is the first adapter to implement automatic metadata-driven downgrades**: the entity-set adapter lazily fetches `$metadata` on the first capability-gated method, parses `Capabilities.*` annotations, and intersects the declared capability set with what the server advertises. See [`protocol-capability-matrix.md`](./protocol-capability-matrix.md) under *OData* for the implementation details. Other adapters (GeoServices `supportsStatistics`, OGC `conformsTo`) follow the same pattern as follow-up work. The registry is intentionally broader than the current `Source` method list so downstream adapter tickets can negotiate `render` / `tiles` / `sql` / `queryObjectIds` / `spatialAggregate` / etc. without inventing a second capability vocabulary. `spatialAggregate` has no default protocol support today; sources should advertise it only when source-specific metadata confirms an indexed aggregation backend. Apps must treat returned cell ids and `index.model.id` as opaque, so H3, Quadbin, or a provider-specific grid can drive the same widgets. For multi-source compositions, use `intersectCapabilities` from `@honua/sdk-js/contract` to compute the **weakest** capability set across the participating sources before fanning a call out — the rule plus the partition-then-intersect pattern for per-operation reasoning lives in [`composition.md`](./composition.md). Adapters that emit `Result.degraded[]` populate `DegradedReason.sourceId` from `descriptor.id` so a fan-out can attribute each degradation back to the exact source that triggered it. ## Source factory ```ts doc-test=skip reason="partial excerpt requires application host context" import { createDataset, type SourceDescriptor } from "@honua/sdk-js/contract"; const dataset = createDataset({ id: "parcels", client, capabilityPolicy: "strict", sources: [ { id: "parcels-fs", protocol: "geoservices-feature-service", locator: { url: "...", serviceId: "Parcels", layerId: 0 }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"], }, ] satisfies SourceDescriptor[], }); const parcels = dataset.source("parcels-fs")!; // Deprecated source-native compatibility text during semantic compiler adoption. const result = await parcels.query({ where: "STATE = 'CA'", pagination: { limit: 100 } }); ``` The built-in resolver handles `geoservices-feature-service`, `geoservices-map-service`, `geoservices-image-service`, `geoservices-geometry-service`, `geoservices-gp-service`, `ogc-features`, `ogc-tiles`, `ogc-maps`, `stac`, `wfs`, `wms`, `wmts`, and `odata`. MapLibre-native sources register through `CreateDatasetOptions.resolveSource`. OGC API Processes is a job runner rather than a queryable source — reach it through `HonuaClient.ogcProcesses().execute(...)` (returns the canonical `IJobRun`) instead of `Dataset.source()`. The five GeoServices factories cover the surface published in `honua-server/docs/gis/geoservices-rest-parity.md`: - `geoServicesFeatureSource` — FeatureServer (query, edits, related, attachments, object ids, replica/calculate/validateSQL/append/bins/estimate via `protocol()`). - `geoServicesMapServiceSource` — MapServer (read-only query family, related records; export/identify/find/legend/tile via `protocol()`). - `geoServicesImageSource` — ImageServer (raster catalog query, exportImage / identify / tile / legend via `protocol()`). - `geoServicesGeometryServiceSource` — Geometry Service (utility-only; query family throws, operations live behind `protocol()`). - `geoServicesGPServiceSource` — GP Service (utility-only; submitJob / jobStatus / cancelJob / jobResult via `protocol()`). The OGC API and STAC factories cover `docs/ogc-api.md`: - `ogcFeaturesSource` — OGC API Features (query, edits, object ids, stream; `queryAggregate` / `queryExtent` degrade client-side). - `ogcTilesSource` — OGC API Tiles (render-only; query family throws, `HonuaOgcTileset` / `HonuaOgcTiles` reachable via `protocol()`). - `ogcMapsSource` — OGC API Maps (render-only; same shape as Tiles). - `ogcRecordsSource` — OGC API Records metadata catalog search (`/collections/{catalogId}/items`, queryObjectIds, stream; Records-specific `q` / `type` / `externalIds` and raw response access via `protocol()`). - `stacSearchSource` — STAC API search (`/search` query, queryObjectIds, stream; cross-collection scope via `locator.collectionId`). The WMS / WMTS factories cover the OGC web-map services per `docs/protocol-capability-matrix.md`: - `wmsSource` — WMS 1.3.0 (render + tiles via `GetMap`; `query` via point-only `GetFeatureInfo`; raw multi-pixel `featureInfo()` and the per-layer service handles reachable via `Source.protocol("wms" | "wms-layer")`). - `wmtsSource` — WMTS 1.0.0 (render + tiles via RESTful tiles; query family throws; service / layer / tileset handles reachable via `Source.protocol("wmts" | "wmts-layer" | "wmts-tileset")`). `docs/wfs.md` documents the WFS 2.0 factory in the same shape: - `wfsSource` — WFS 2.0 (query, queryAll, queryExtent, queryObjectIds, applyEdits, stream; FES 2.0 emission for `Query.where` / `Query.spatialFilter`; raw GML / `` payloads via `protocol("wfs")`). The OData factory wraps an OData v4 entity set behind the canonical surface: - `odataSource` — query / queryObjectIds / stream / applyEdits first-party (POST/PATCH/DELETE; PUT is unsupported per the parity matrix and addressed by `PATCH` with the full canonical body). Dialect-specific `$batch` / `$apply` / `$search` / `$deltatoken` reach `HonuaOdataEntitySet` through `Source.protocol("odata")`. OData is the **first adapter** to lazily fetch service metadata (`$metadata`) and intersect the declared `Capabilities` set with what the server advertises through `Capabilities.*` annotations — see [`protocol-capability-matrix.md`](./protocol-capability-matrix.md) for the precedent and [`decisions/odata-library-selection.md`](./decisions/odata-library-selection.md) for the runtime-library posture. ## Edit Workflow Sessions `createEditSession({ source, kind, feature, metadata, optimistic })` is the SDK-level workflow contract for form and editor surfaces. It is intentionally layered over `Source.applyEdits`, `Source.queryRelated`, and `Source.attachments` rather than replacing the protocol adapters. The session resolves fields from `source.descriptor.schema.fields` plus caller-supplied domains, validates required / read-only / length / coded-value / range constraints before submit, and exposes `capabilities()` so unsupported `applyEdits`, `attachments`, and `queryRelated` states are explicit and testable. Relationship reads use `session.queryRelated(...)`; attachment reads and staged add / update / delete mutations use the same source attachment namespace. `submit()` sends the feature edit envelope first, then applies staged attachment mutations against the committed feature id when the backend returns one. Optimistic hooks run in this order: `optimistic.apply` before the remote edit, `optimistic.commit` on full success, and `optimistic.rollback` for failed or partial feature / attachment results. `EditWorkflowSubmitResult.failures` normalizes per-row errors from GeoServices, OGC Features, WFS, and OData into `validation`, `conflict`, `capability`, `transport`, `server`, or `partial-failure`. When a version / ETag / updated-at field is present (or supplied in `metadata.conflict`), conflict failures carry that information so hosts can present reload / merge / overwrite workflows without parsing protocol-specific error text. `createEditSketchWorkflow(...)` wraps the same session contract with UI-independent sketch state. It exposes explicit support for point, line, polygon, rectangle, circle, and buffer tools; dirty state; undo / redo / discard; attachment staging; validation; submit; and an optional annotation persistence hook that runs only after a successful edit commit. Unsupported sketch, attachment, relationship, conflict, or annotation persistence capabilities remain visible in the returned snapshot instead of being hidden by component state. `Source.queryAll()` and `Source.stream()` drain every page the server returns — the built-in adapters override the core helpers' 100-page default so a large `queryAll()` is not silently truncated. Callers who want a hard cap should paginate with `Query.pagination` (`offset` skips ahead; `limit` clips, and its meaning depends on the method): - `query()` — `limit` is the single-page record count. - `queryAll()` — `limit` is the total-row cap on the materialized result. The adapter sizes `pageSize` and `maxPages` from `limit` so the paging loop fetches at most `limit + 1` rows; the extra row lets the result stamp `exceededTransferLimit: true` when more records exist. - `stream()` — `limit` is the per-batch page size (not a global cap). Each yielded `Result` carries up to `limit` features; callers that want a global cap must stop iterating explicitly. ## Compatibility gating `Dataset.isCompatible()` calls `HonuaClient.checkCompatibility()` once and caches the result. `Dataset.supportsFeature(feature)` proxies to `HonuaClient.supportsFeature` for fine-grained checks. Both reuse the existing compatibility-gate workflow — no new wire calls were introduced. ## Protocol escape hatch `Source.protocol("geoservices-feature-service")` returns the underlying `HonuaFeatureLayer` instance (or `undefined` for the wrong kind). The accessor name is `protocol` because it surfaces protocol-specific operations — raw `where`, raw `outFields`, GeoServices `calculate` / `validateSQL` / replica / `queryBins` / `getEstimates` — that the canonical `Source` surface intentionally does not expose. The `adapter()` method is preserved as a legacy alias for callers written against the original ticket-23 surface; it returns the same instance. The `AdapterTypeMap` interface uses TypeScript declaration merging so adapter tickets can plug in their own kind → instance type mapping without touching this file. `grpc` is a canonical protocol id for the shared FeatureService transport and fixture pack; it is consumed through the client gRPC-Web transport rather than a `Source.protocol("grpc")` adapter handle in this package. ```ts doc-test=skip reason="partial excerpt requires application host context" declare module "@honua/sdk-js/contract" { interface AdapterTypeMap { "my-protocol": MyProtocolLayer; } } ``` The shipped map covers `geoservices-feature-service` → `HonuaFeatureLayer`, `geoservices-map-service` → `HonuaMapService`, `geoservices-map-layer` → `HonuaMapLayer`, `geoservices-image-service` → `HonuaImageService`, `geoservices-geometry-service` → `HonuaGeometryService`, `geoservices-gp-service` → `HonuaGeoprocessingService`, `ogc-features` → `HonuaOgcFeatureCollection`, `ogc-tiles` → `HonuaOgcTileset | HonuaOgcTiles`, `ogc-maps` → `HonuaOgcMaps | HonuaOgcCollectionMap`, `ogc-processes` → `HonuaOgcProcesses`, `stac` → `HonuaStacSearch`, `wms` → `HonuaWms`, `wms-layer` → `HonuaWmsLayer`, `wmts` → `HonuaWmts`, `wmts-layer` → `HonuaWmtsLayer`, `wmts-tileset` → `HonuaWmtsTileset`, `wfs` → `HonuaWfsFeatureType`, and `odata` → `HonuaOdataEntitySet`. The WFS root handle (capabilities cache, stored-query discovery) is reachable through `Source.protocol("wfs").root`. ## What downstream tickets must consume 1. New protocol adapters must implement `Source` and register either as a built-in `case` in `buildBuiltInSource` (the precedent followed by `wmsSource` / `wmtsSource` / `wfsSource` / `odataSource`) or through `CreateDatasetOptions.resolveSource`. They must declare their default capability set in `PROTOCOL_DEFAULT_CAPABILITIES` (this file owns that table — adapter PRs extend it). 2. Visual builder, exploration, and server-export tickets must consume `Dataset` / `Source` / `Query` / `Result` / `MapBinding` rather than the per-class request shapes (`QueryFeaturesRequest`, etc.). Per-class shapes are still available via `Source.adapter()` for legacy paths. 3. New error types must flow through `HonuaError` and `isHonuaError`. This ticket added `HonuaCapabilityNotSupportedError` and `HonuaExplorationContextError`. The first-party WMS / WMTS adapter ticket extended the union with `HonuaWmsCapabilitiesParseError` and `HonuaWmtsCapabilitiesParseError` so callers can classify XML parser failures through the same guard. ## Async operations: `IJobRun` Long-running server-side operations surface through the canonical `IJobRun` interface in `@honua/sdk-js/contract`. OGC API Processes, GeoServices REST GPServer, and the open `honua-io/geospatial-grpc` `ProcessService` all normalize onto the same lifecycle vocabulary: ```ts doc-test=skip reason="partial excerpt requires application host context" import type { IJobRun } from "@honua/sdk-js/contract"; const job: IJobRun = await client.ogcProcesses().execute({ processId: "buffer", inputs: { feature: someGeoJson }, mode: "async", }); const unwatch = job.watch((snap) => { console.log(snap.status, snap.progress); }); const { outputs } = await job.results(); unwatch(); ``` For app code that should not know which protocol is behind a workflow, use `HonuaProcessRunner`: ```ts doc-test=skip reason="partial excerpt requires application host context" const ogc = client.ogcProcessRunner(); const gp = client.geoprocessingRunner("Analysis", "OverlayFacilities"); const grpc = client.geospatialGrpcProcessRunner(processServiceClient); await ogc.execute({ processId: "buffer", inputs }); await gp.execute({ inputs: gpParameters, resultNames: ["outputLayer"] }); await grpc.execute({ plan: executionPlan, context: executionContext }); ``` `createOgcProcessesAdapter`, `createGeoServicesGpAdapter`, and `createGeospatialGrpcProcessAdapter` expose the same adapter contract for callers that construct protocol handles outside `HonuaClient`. The geospatial-grpc adapter is structural: it expects a generated `ProcessService` client with `validatePlan`, `dryRunPlan`, `submitJob`, `getJob`, `getJobResult`, and `cancelJob`, but this package does not vendor the `honua-io/geospatial-grpc` generated process proto directly. `IJobRun` exposes `id`, `type`, `status`, `progress`, `poll()`, `watch()`, `results()`, and `cancel()`. The OGC API Processes 1.0 status vocabulary (`accepted`, `running`, `successful`, `failed`, `dismissed`) is canonical. GeoServices `esriJobSubmitted` / `esriJobExecuting` / `esriJobSucceeded` / `esriJobFailed` / `esriJobCancelled` and geospatial-grpc `JobState` values (`JOB_STATE_RUNNING`, `JOB_STATE_COMPLETED`, `JOB_STATE_FAILED`, `JOB_STATE_CANCELLED`, etc.) translate onto it. Failed OGC runs reject `results()` with `HonuaJobFailedError`, whose `message` is populated from the server's `statusInfo.exception.message` when present and falls back to `statusInfo.message` otherwise (to match honua-server's `StatusInfo` DTO, which exposes only `message`). `cancel()` is idempotent against the two documented benign paths: "job gone" (404) returns the cached status, and the terminal race (409 "Cannot dismiss completed job" from honua-server) triggers a follow-up GET and returns the authoritative terminal status — but only if the poll confirms a terminal state. honua-server also emits 409 for "Dismiss could not be confirmed" (backend dismissal unconfirmed) and "Cancellation not supported" (backend lacks cancel support); both rethrow as `HonuaHttpError` so callers can branch or retry instead of seeing a fabricated success. Submitted processes are typed as `IJobRun`; `HonuaOgcProcessJobRun` is the implementation behind that interface and should not be the caller-facing contract. ## OGC API Tiles / Maps / Records / Processes / STAC The first-party OGC adapters live alongside `HonuaOgcFeatures`: | Conformance area | Entry point | Source protocol | Contract capabilities | | --- | --- | --- | --- | | OGC API Features | `client.ogcFeatures()` / `HonuaOgcFeatures` | `ogc-features` | `query`, `queryObjectIds`, `applyEdits`, `stream` | | OGC API Tiles | `client.ogcTiles()` / `HonuaOgcTiles`, `HonuaOgcTileset` | `ogc-tiles` | `render`, `tiles` (tileset-bound when locator includes `tileMatrixSetId`; root discovery handle otherwise) | | OGC API Maps | `client.ogcMaps()` / `HonuaOgcMaps`, `HonuaOgcCollectionMap` | `ogc-maps` | `render` | | OGC API Records | `client.ogcRecords()` / `HonuaOgcRecords`, `HonuaOgcRecordCollection` | `ogc-records` | `query`, `queryObjectIds`, `stream` | | OGC API Processes | `client.ogcProcesses()` / `HonuaOgcProcesses` | (no source — job runner) | `processes` from conformance negotiation, not `PROTOCOL_DEFAULT_CAPABILITIES` | | STAC API | `client.stac()` / `HonuaStacSearch` | `stac` | `query`, `queryObjectIds`, `stream` | OGC API Tiles and OGC API Maps are render-only — their `Source.query*` methods throw, and renderers reach the underlying class through `Source.adapter("ogc-tiles")` / `Source.adapter("ogc-maps")`. OGC API Records and STAC both flow through the canonical `Source.query()` path, but Records is metadata catalog search and STAC is asset/item search. OGC API Processes does not register as a `Source` because its inputs are not queryable; it produces `IJobRun` from `execute(...)`. ## WMS / WMTS web-map services The first-party OGC web-map adapters share the contract surface: | Service | Entry point | Source protocol | Contract capabilities | | --- | --- | --- | --- | | WMS 1.3.0 | `client.wms(serviceId)` / `HonuaWms`, `HonuaWmsLayer` | `wms` | `render`, `tiles`, `query` (point-only `GetFeatureInfo`) | | WMTS 1.0.0 | `client.wmts(serviceId)` / `HonuaWmts`, `HonuaWmtsLayer`, `HonuaWmtsTileset` | `wmts` | `render`, `tiles` | `Source.protocol("wms")` returns the service handle and `Source.protocol("wms-layer")` a layer-bound handle (when `locator.typeName` is set). WMTS exposes three handles — `Source.protocol("wmts")` (service), `"wmts-layer"` (layer-bound), and `"wmts-tileset"` (layer × style × tile-matrix-set bound). MapLibre integration ships through the runtime helpers `buildWmsRasterSourceSpec(descriptor)` / `buildWmtsRasterSourceSpec(descriptor)` from `@honua/sdk-js/runtime` — they emit a `raster` source spec without forcing callers to hand-assemble a `GetMap` URL or RESTful tile template. The style-spec resolver `createSources(client, style)` (from `@honua/sdk-js`) and `HonuaMap.getSource(name)` both produce the same `HonuaWms` / `HonuaWmsLayer` / `HonuaWmts` / `HonuaWmtsTileset` handles when a style declares a `honua-wms` / `honua-wmts` source type — the shared `src/style/wms-wmts-resolvers.ts` module owns the URL parsing and layer / tileset selection rules so the two surfaces never diverge. The WMS `LAYERS=` / `locator.typeName` / `spec.layers` value is parsed through the canonical `parseWmsLayerNames` helper (in `src/core/wms.ts`); the layer-bound `HonuaWmsLayer` handle is only returned for a single non-empty token, while multi-layer composites (`"a,b"`) stay on the service-level `HonuaWms` handle. See [`docs/protocol-capability-matrix.md`](./protocol-capability-matrix.md) for axis-order, dimension, legend, and TileMatrixSet notes. OGC conformance class identifiers are intentionally kept *internal*. `negotiateOgcCapabilities(protocol, conformsTo)` from `@honua/sdk-js/honua` translates a server-advertised `conformsTo[]` list into a canonical `Capabilities` set; downstream callers that want to gate on a specific extension (CQL2, transactions, etc.) use `hasOgcConformanceClass(...)` with a substring match. No OGC conformance class name appears as a primary SDK type, per the ticket constraint. ## Test coverage Conformance fixtures under `test/contract/` exercise the canonical surface against mock adapters for each protocol. Adding a new protocol adapter means adding a fixture there; the parametrized scenarios run unchanged. - `test/contract/conformance.test.ts` — cross-protocol parametric scenarios. Each new adapter registers a harness; the suite runs the same query / queryExtent / queryAggregate / stream cases against every harness. - `test/contract/odata-conformance.test.ts` — adapter-specific translation rules and escape-hatch surface (`metadata`, `batch`, `apply`, `search`, `delta`, `raw`). - `test/contract/ogc-conformance.test.ts` — the conformance-class → capability negotiation translation table. --- # File: docs/query-planner.md # Deterministic query planner `@honua/sdk-js/query-planner` is the first production slice of the execution planner described by the [north-star application-kernel decision](./decisions/north-star-sdk-application-kernel.md). It turns the current protocol-neutral `Query` plus an already-discovered `SourceDescriptor` into a versioned, serializable IR and an immutable explain plan. Explaining is synchronous and side-effect free: it does not fetch metadata or rows, mutate a renderer, or execute the query. The subpath is experimental while the remaining compiler and columnar slices land. It is intentionally not exported from the root barrel. ## Typed semantic query AST The experimental planner subpath also exposes the first typed semantic-query surface. It is additive: existing v1 plans and protocol compilers continue to consume the compatibility `Query.where` path until the compiler migration lands. New code can build immutable property/literal, comparison, boolean, null, list, range, pattern, spatial, and temporal nodes without choosing a wire dialect: ```ts doc-test=compile import { createSemanticQueryBuilder, defineSemanticQuery } from "@honua/sdk-js/query-planner"; interface Incident { id: number; status: string; score: number; } const q = createSemanticQueryBuilder(); const semanticQuery = defineSemanticQuery( q.features({ select: ["id", "status"] as const, filter: q.and( q.comparison("eq", q.property("status"), q.literal("active")), q.between(q.property("score"), 50, 100), ), sort: [{ field: "score", direction: "desc" }], page: { kind: "first", limit: 100 }, }), ); console.log(semanticQuery.filter); ``` `parseSemanticQuery(untrusted, { schema, protocol })` is the JavaScript and JSON boundary. It reparses the supplied `SourceSchemaV2`, validates field existence, operator/type compatibility, closed domains, declared ranges, geometry and temporal eligibility, safe length and `multiple-of` constraints, projection/sort/group/metric fields, native payload form, and native dialect compatibility. Literal type admission reuses the canonical `SourceSchemaV2` value semantics, including binary encodings, numeric precision, and temporal precision. Source-provided ECMA-262 field patterns remain metadata and are not executed at this untrusted boundary. Parsed queries are deeply frozen, with equivalent omitted defaults (case-sensitive patterns and native null ordering) normalized before hashing or interchange. Parsing is bounded by byte, node, depth, collection, and text limits; cyclic values, accessors, non-JSON prototypes, unknown members, blank identifiers or native text/XML payloads, invalid protocol options, and non-finite numbers fail closed. Protocol-native filters remain explicit and dialect tagged. For example, an OGC source may carry `cql2-json` or `cql2-text`; it cannot carry `geoservices-sql92`. A native expression is an escape hatch, not a claim that the expression is protocol neutral. This semantic surface does not change compilation or execution. Protocol compiler adoption remains in #527-#529. ### Canonical bytes and query identity `canonicalSemanticQueryBytes()` and `hashSemanticQuery()` first run the same bounded runtime/schema validation, then encode a versioned envelope with sorted object keys. Array order remains significant. The identity envelope always contains schema fingerprint, protocol, CRS-registry version, and policy version slots; unavailable values are explicit `null`, not omitted. Cancellation, realtime cursors, observation timestamps, and other volatile execution state are not members of the semantic AST. ```ts doc-test=compile import { canonicalSemanticQueryBytes, createSemanticQueryBuilder, hashSemanticQuery, } from "@honua/sdk-js/query-planner"; interface Parcel { id: number; status: string; } const query = createSemanticQueryBuilder(); const request = query.features({ select: ["id"] as const, filter: query.comparison("eq", query.property("status"), "active"), }); const identity = { protocol: "ogc-features" as const, crsVersion: "epsg-db:2026.1", policyVersion: "query-policy:7", }; console.log(canonicalSemanticQueryBytes(request, identity).byteLength); console.log(hashSemanticQuery(request, identity)); ``` Equivalent validated inputs produce identical UTF-8 bytes and a domain-separated SHA-256 hash. Changing schema, CRS, policy, protocol, field order, sort precedence, or another semantic member changes identity. ### CQL2 JSON interchange `semanticFilterToCql2Json()` and `semanticFilterFromCql2Json()` implement a strict, lossless supported subset of the [OGC CQL2 JSON encoding](https://docs.ogc.org/is/21-065r2/21-065r2.html). Import uses the same byte/node/depth/collection bounds and duplicate-name rejection as `parseSemanticQuery`; imported filters are runtime validated and deeply frozen. ```ts doc-test=compile import { createSemanticQueryBuilder, semanticFilterFromCql2Json, semanticFilterToCql2Json, } from "@honua/sdk-js/query-planner"; interface Road { roadClass: string; } const query = createSemanticQueryBuilder(); const filter = query.like(query.property("roadClass"), "primary%", { caseSensitive: false, }); const cql2 = semanticFilterToCql2Json(filter, { protocol: "ogc-features" }); const restored = semanticFilterFromCql2Json(cql2, { protocol: "ogc-features" }); console.log(cql2, restored); ``` The supported subset includes property/literal comparisons, `and`/`or`/`not`, null tests, lists, numeric ranges, case-sensitive and `casei` patterns, standard topological/non-wrapping-bbox predicates, and the four semantic temporal predicates. CQL2 carries spatial CRS outside its JSON expression, so spatial import/export requires an explicit executable `filterCrs` binding and verifies every operand against it. JSON-number-encoded decimal fields preserve their supported CQL2 scalar representation; string-encoded high-precision numbers remain unsupported. Both import and export enforce the normative CQL2 JSON schema's two-member minimum for `GeometryCollection`. Distance extensions, native expressions, property-property comparisons, arithmetic/custom functions, measured geometry layouts, and wrapping bounding boxes fail closed rather than being weakened. ### Deprecated raw `where` compatibility The v1 `Query.where` member remains operational but is deprecated and explicitly source-native. `legacyWhereToNativeFilter()` is the migration bridge for text whose dialect is losslessly known: GeoServices SQL-92, CQL2 text, OData 4.0, or DuckDB SQL. WFS's parsed legacy grammar and Honua gRPC's JSON dialect are not mislabelled as raw text. ```ts doc-test=compile import { legacyWhereToNativeFilter } from "@honua/sdk-js/query-planner"; const compatibilityFilter = legacyWhereToNativeFilter( "geoservices-feature-service", "STATUS = 'OPEN'", ); console.log(compatibilityFilter.dialect); // geoservices-sql92 ``` Existing v1 planning still serializes `where` as `{ kind: "source-native", expression }`, preserving compatibility until #527-#529 adopt semantic nodes. New code should use typed builders instead of the bridge. ## Remote pushdown The remote compilers target existing GeoServices FeatureServer, OGC API Features `/items`, WFS 2.0 GetFeature, OData v4 entity-set query, DuckDB SQL over GeoParquet, and Honua gRPC `FeatureService/QueryFeatures` paths. The compiled request is included in the plan so diagnostics, CLIs, agents, and renderers can inspect the same decision before execution. ```ts doc-test=skip reason="partial excerpt requires application host context" import { PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { executeQueryPlan, explainQuery } from "@honua/sdk-js/query-planner"; const descriptor = { id: "incidents", protocol: "geoservices-feature-service", locator: { url: "https://demo.honua.io", serviceId: "incidents", layerId: 0 }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"], } as const; const plan = explainQuery({ descriptor, sourceVersion: "2026-07-10", authorizationScope: ["data:read"], query: { where: "status = 'open'", aggregation: { groupBy: ["severity"], metrics: [{ fn: "count", field: "OBJECTID", alias: "incidents" }], }, }, }); console.log(plan.fingerprint, plan.steps[0]?.compiled); // `source` is the matching Source from Dataset.source(...). Version and scope // are repeated so execution can reject a stale or differently-authorized plan. const execution = await executeQueryPlan(plan, source, { sourceVersion: "2026-07-10", authorizationScope: ["data:read"], }); console.log(execution.result.aggregateRows); ``` For an OGC API Features source, the same `explainQuery()` call selects `ogc-api-features-query-v1` from the descriptor protocol. Source-native `Query.where` is identified as CQL2 text; projection, sorting, pagination, CRS, and envelope-intersects filters compile to `properties`, `sortby`, `limit`/`offset`, `crs`, and `bbox` respectively: ```ts doc-test=compile import { PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { explainQuery } from "@honua/sdk-js/query-planner"; const ogcPlan = explainQuery({ descriptor: { id: "parcels", protocol: "ogc-features", locator: { url: "https://example.test/ogc", collectionId: "parcels" }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["ogc-features"], }, query: { where: "status = 'active'", outFields: ["parcel_id", "owner"], orderBy: [{ field: "updated_at", direction: "desc" }], spatialFilter: { geometryType: "esriGeometryEnvelope", geometry: { xmin: -158.4, ymin: 20.5, xmax: -157.6, ymax: 21.8 }, }, pagination: { limit: 100 }, }, }); const firstStep = ogcPlan.steps[0]; if (!firstStep || firstStep.engine !== "remote") throw new Error("Expected a remote query step"); console.log(firstStep.compiled); // { compiler: "ogc-api-features-query-v1", collectionId: "parcels", // filter: "status = 'active'", filterLang: "cql2-text", ... } ``` The OGC compiler rejects non-envelope spatial filters, relationships other than envelope-intersects/intersects, non-EPSG:4326 or malformed bounds, portable geometry-suppression claims, and claimed remote aggregation. It never weakens those requests to a broader bbox query. Aggregation remains available through the explicit bounded-local policy below: the CQL2 filter and required-field projection stay remote while the exact aggregate runs only after the materialization ceilings pass. WFS plans compile the supported SQL-92 subset and spatial predicates to FES 2.0 XML, and expose `propertyName`, `sortBy`, `startIndex`, `count`, and `srsName`. XML literals and identifiers go through the same escaping compiler used by the WFS adapter; the portable compiler deliberately retains that adapter's reviewed `the_geom` default. OData plans translate the canonical predicate to `$filter`, including supported `geo.intersects` geometry, and expose `$select`/`$expand`, `$orderby`, `$skip`, and `$top`. Both compilers fail closed when exact translation is impossible. In particular, metadata-free planning requires explicit `outFields` before it can prove geometry suppression, and a descriptor geometry field before it can compile an OData spatial predicate. OData output-CRS requests, untranslatable SQL predicates, unterminated literals, contradictory WFS geometry projections, and WFS spatial filters that would misuse response `outSr` as an input-geometry label also fail closed. The planner never claims exact execution based on guessed or silently ignored protocol behavior. A descriptor WFS `srsName` remains transaction metadata and is not invented as a GetFeature response CRS. `Query.signal` never enters the IR or fingerprint. Supply cancellation only to `executeQueryPlan`. Network-protocol source URLs in plan identity are stripped of credentials, query strings, and fragments. GeoParquet v1 planning rejects a credential-bearing locator entirely; use the opaque v2 path below. Pass stable authorization scope identifiers, not tokens. ## Opaque GeoParquet resource identity `GeoParquetResourceHandleV1` is a versioned JSON value containing only a resolver namespace, logical resource id, stable non-secret authorization partition, and optional data revision. `explainQuery()` emits a `2.0` IR/plan and `duckdb-sql-v2` template when `geoparquetResource` is present. Raw paths, globs, signed URLs, and expiry remain private to a lifecycle-scoped resolver registry and are injected only while the accepted plan executes: ```ts doc-test=skip reason="partial excerpt requires application private locator and execution host" import { createGeoParquetResourceRegistry, executeQueryPlan, explainQuery, queryPlanCacheKey, serializeQueryPlan, } from "@honua/sdk-js/query-planner"; const resources = createGeoParquetResourceRegistry({ resolver: "io.honua.app-assets" }); const handle = resources.register({ id: "parcels:current", authorizationContextId: "tenant:alpha/role:analyst", resourceVersion: "snapshot:42", sources: [privateSignedGeoParquetUrl], expiresAt: privateSignedGeoParquetExpiryMs, }); const plan = explainQuery({ descriptor: source.descriptor, geoparquetResource: handle, authorizationScope: ["data:read"], sourceVersion: "source:9", query: { where: "population > 10", pagination: { limit: 100 } }, }); // Both projections contain only the stable handle and placeholder SQL. const persistedPlan = serializeQueryPlan(plan); const cacheKey = queryPlanCacheKey(plan); // The resolver's private source crosses directly into the GeoParquet adapter. // Repeat the planning context so execution can reject drift. const execution = await executeQueryPlan(plan, source, { authorizationContextId: "tenant:alpha/role:analyst", geoParquetResourceResolver: resources.resolver, authorizationScope: ["data:read"], sourceVersion: "source:9", signal, }); // Clears all private locator material when the owning client/session ends. resources.dispose(); ``` Re-registering the same resolver/id/authorization-context/resource-version atomically rotates private credentials without changing the handle or its fingerprint. Resolution compares authorization context before invoking the resolver, enforces exact expiry at `now >= expiresAt`, supports pre-flight and in-flight cancellation, and copies resolver output through fixed source-count and UTF-8 size ceilings. Unknown, revoked, closed, or cross-context resources fail closed. Foreign resolver failures are rebuilt as fixed-message SDK errors; their messages, causes, contexts, and raw locators are never retained. GeoParquet adapter failures are likewise rebuilt as `query.execution.resource-execution-failed`. Cancellation remains an `HonuaAbortError` before, during, and after resolution. `resource.id`, `resourceVersion`, and `authorizationContextId` are identity-bearing. Derive them only from stable, non-secret facts such as dataset revision, tenant, and role ids—never from a bearer token, API key, signed query string, or a hash of credential material. Their validators enforce bounded syntax, not arbitrary secret detection, so callers remain responsible for this boundary. The registry is ephemeral in-memory isolation, not encrypted storage. Resolved `sources` cross the redaction boundary and must never be logged, persisted, fingerprinted, placed in telemetry, or sent over a network API. `serializeQueryPlan()`, `parseQueryPlan()`, `hashQueryPlan()`, and `queryPlanCacheKey()` validate the persistence boundary before returning. A v2 cache identity binds the resolver/id, authorization partition, data revision, scope, schema/source versions, query, and planner policy. Credential rotation does not change it, and no secret value is hashed. Serialization is synchronous and performs no resolver, filesystem, network, or DuckDB I/O. Validation does not treat the public SHA-256 fingerprint as authentication: it reconstructs the complete canonical v2 plan through the pure planner and compares every field, including the derived id, IR, steps, compiled template, warnings, and exact nested keys. A re-signed non-canonical projection is rejected with the same fixed redacted `invalid-plan` error. Existing `1.0` GeoParquet IR and `duckdb-sql-v1` artifacts remain supported only when every locator is credential-free. Query strings, fragments, user-info, and credential-bearing legacy addresses are rejected before planning, hashing, parsing, or migration. Upgrade an accepted v1 plan explicitly with `migrateGeoParquetQueryPlanV1(legacyPlan, handle)`; migration reconstructs a v2 plan and does not copy the old locator. There is no implicit v1 rewrite. ## DuckDB SQL and gRPC compilers Opaque `geoparquet` sources compile through `compileDuckDbQueryV2` to a deterministic `duckdb-sql-v2` template over the fixed `honua-resource://resolve-at-execution` placeholder. The trusted GeoParquet adapter recompiles the same canonical query against the ephemeral resolved sources and consumes them without placing them in its metadata/profile cache. Credential-free legacy sources continue to use `compileDuckDbQuery` and `duckdb-sql-v1`. Both compilers reuse the same dependency-free, injection-safe SQL builder. Envelope spatial filters push down as `ST_Intersects(..., ST_MakeEnvelope(...))` (or a GeoParquet 1.1 `bbox`-covering column when declared); non-envelope geometries are reduced to their bounding box and reported with `bboxApproximated: true`. Geometry is projected as GeoJSON via `ST_AsGeoJSON`. Output-CRS requests fail closed (no portable DuckDB reprojection), and a spatial filter without a resolvable geometry column is rejected. The geometry column and encoding come from `locator.geoparquet.geometryColumn` / `geometryEncoding` (default `wkb`) or a descriptor geometry field, so planning never needs a profiling round-trip. `grpc` sources compile to `honua-grpc-query-features-v1`, a faithful, protobuf-free description of the `honua.v1.FeatureService/QueryFeatures` unary request. Field names and proto enum *value names* (`SPATIAL_RELATIONSHIP_*`, `STATISTIC_TYPE_*`) mirror the generated message, so the plan is a hashable pre-image of the wire request without importing the protobuf runtime. ## Spatial aggregation Spatial aggregation — grouped statistics constrained by a spatial predicate — has both a server-pushdown path and a bounded local/columnar path. GeoServices (`outStatistics` + `groupByFieldsForStatistics` + geometry) and gRPC (`outStatistics` + `groupBy` + `spatialFilter`) push the whole aggregation to the server (`pushdown: "full"`); DuckDB pushes it to the columnar engine as a `GROUP BY` with the spatial predicate in the `WHERE` clause. When a source cannot push aggregation down at all, the bounded degraded path (below) computes it locally after enforcing a row/byte ceiling. Histogram and time-series aggregation remain rejected rather than silently ignored. ## Plan consumers The plan is consumed, not re-derived. `honua explain ` (CLI) builds a `SourceDescriptor` from flags and calls `explainQuery`, printing the stages, pushdown, per-protocol compiled request, fidelity, warnings, and fingerprint — with no server call, since planning is side-effect free. `executeQueryPlan` consumes the accepted plan for execution after verifying its fingerprint and source context. For GeoParquet, the positional CLI value is an opaque resource id, never a locator: ```sh honua explain parcels:current --protocol geoparquet \ --resolver io.honua.app-assets \ --authorization-context tenant:alpha/role:analyst \ --resource-version snapshot:42 --json ``` ## Bounded degraded execution Fallback is disabled by default. When a source can query features but cannot push down aggregation, local execution requires both `capabilityPolicy: "degraded"` and an explicit `bounded-local` budget: ```ts doc-test=skip reason="partial excerpt requires application host context" const plan = explainQuery({ descriptor, capabilityPolicy: "degraded", fallback: { mode: "bounded-local", maxRows: 5_000, maxBytes: 8_000_000 }, estimates: { rows: 3_200, bytes: 4_100_000 }, query: { where: "status = 'open'", aggregation: { metrics: [{ fn: "count", field: "OBJECTID" }] }, }, }); ``` The plan pushes filters and required-field projection to the server. Its logical input limit is `maxRows`; the compiled wire request exposes the adapter-owned `maxRows + 1` overflow sentinel. Aggregation runs locally only after the row and byte ceilings pass. Planning rejects a known over-budget estimate. Execution rejects an overflow sentinel or transfer-limit response; it never silently reports a partial aggregate. `maxRows` is also capped by the SDK at `MAX_LOCAL_MATERIALIZATION_ROWS`. ## Determinism and plan validity - `QUERY_IR_VERSION` / `QUERY_PLAN_VERSION` remain `1.0` for compatible plans; `QUERY_IR_V2_VERSION` / `QUERY_PLAN_V2_VERSION` are `2.0` for opaque GeoParquet resources. - Objects serialize with sorted keys; array order remains semantically significant. SHA-256 fingerprints are identical in browsers, workers, and Node for the same descriptor, query, policy, versions, scope, and estimates. - Capabilities, authorization scopes, source/schema versions, CRS/query fields, and fallback budgets participate in the fingerprint. - `executeQueryPlan` verifies the complete canonical v2 projection, its fingerprint, and the current source context. A changed plan, stable source identity, version, capability set, or scope is rejected; the executor does not re-plan. Opaque GeoParquet credential rotation is intentionally outside that identity. - Feature/query/result caching remains bypassed. Opt-in materialization is a separate workflow. ## Deliberate first-slice boundaries This foundation does not close the full planner workstream. The typed semantic AST, temporal values, canonical identity, and CQL2 JSON interchange are now available, while the existing v1 compilers remain on their compatibility path. Follow-on slices must adopt the AST in those compilers, negotiate richer OGC filter support, and add spatial-binning aggregation (grid/hex), joins/composition, cache/freshness decisions, cost models, realtime snapshot/delta plans, receipts, and richer renderer/MCP consumption. Histogram and time-series aggregation are rejected by the current compiler rather than silently ignored. The GeoServices, OGC API Features, WFS, OData, credential-free and opaque DuckDB SQL, gRPC, bounded columnar/worker paths, spatial-aggregation pushdown, and CLI plan consumer are now delivered. --- # File: docs/columnar-data-plane.md # Columnar batch transfer contract `@honua/sdk-js/query-planner` includes the first bounded data-plane slice for large query results. It defines a dependency-free Honua batch envelope, an ownership transfer primitive, and a lazy bounded worker-session protocol. Arrow/GeoArrow adapters may populate its buffers and metadata, but the envelope does not define a standalone Arrow layout and is not independently interoperable without the originating adapter's layout contract. It does not decode Arrow or ship built-in filter/reprojection/aggregation operators. Applications register those operations in their worker module. The entrypoint is experimental while the broader planner, streaming, renderer, and realtime work in issue #394 is completed. ## Create a batch without copying payload bytes ```ts doc-test=skip reason="partial excerpt requires application host context" import { createColumnarBatch, leaseColumnarBatch } from "@honua/sdk-js/query-planner"; const coordinates = new Float64Array([21.31, -157.86, 21.44, -157.77]); const batch = createColumnarBatch({ id: "places:0", sequence: 0, rowCount: 2, schema: { id: "places-schema-v1", fields: [ { name: "geometry", type: { name: "geoarrow.point", parameters: { dimensions: 2 } }, nullable: false, metadata: { "ARROW:extension:name": "geoarrow.point" }, }, ], metadata: { crs: "EPSG:4326" }, }, buffers: [ { id: "geometry.values", field: "geometry", role: "geometry", data: coordinates.buffer, byteOffset: coordinates.byteOffset, byteLength: coordinates.byteLength, }, ], }); const lease = leaseColumnarBatch(batch); const receipt = await lease.transfer((message, transfer) => { worker.postMessage(message, { transfer: [...transfer] }); }); console.log(receipt.metrics); // { rows: 2, logicalBytes: 32, backingBytes: 32, // transferBytes: 32, copiedBytes: 0, ... } ``` Payload bytes are never copied. Schema and metadata descriptors are normalized and frozen, while batch creation retains each caller-provided `ArrayBuffer`. Multiple views over one buffer produce one transfer-list entry. Zero-byte backing buffers are valid; detached buffers are rejected using an attachment check that distinguishes the two cases. ## Memory ceilings Creation and transfer default to at most 1,000,000 rows and 64 MiB of unique backing allocations per batch. Descriptor normalization also defaults to at most 4,096 total schema fields, 8,192 metadata/type-parameter entries, 16,384 buffer views, and 1 MiB of UTF-8 descriptor identifiers, keys, and string values. The corresponding `maxRows`, `maxBackingBytes`, `maxSchemaNodes`, `maxMetadataEntries`, `maxBufferViews`, and `maxStringBytes` limits may be lowered or explicitly raised; there is no unbounded mode. Array widths are checked from one captured length before element access, and metadata keys are accumulated only to the configured bound. Normalization therefore fails before copying an oversized schema or descriptor list. Empty views and many views sharing one small backing allocation still count against `maxBufferViews`; they cannot bypass the CPU/heap ceiling by keeping `backingBytes` low. Limits supplied when a lease is created remain its transfer defaults, so a deliberately raised ceiling is not accidentally replaced by the global default. A transfer may tighten either ceiling; a pre-handoff limit failure leaves the lease owned and invokes no target. `backingBytes` sums `ArrayBuffer.byteLength` for every unique backing allocation. It does not claim operating-system resident or physical memory usage. This intentionally rejects a tiny view backed by an unexpectedly large buffer. `logicalBytes` is the sum of described view lengths and can differ when views overlap or share memory. `copiedBytes` is always zero for this API. ## Ownership, cancellation, and acknowledgement A `ColumnarBatchLease` starts in `owned` and can be transferred once. Live leases reserve their unique backing buffers, so the same batch—or another batch sharing one buffer—cannot be leased concurrently. Disposal releases the reservation. The SDK checks an `AbortSignal`, then performs a structured-clone ownership transfer itself before invoking the consumer. The original buffers are detached, the lease becomes `transferred`, and the consumer receives the SDK-owned clone plus its exact transfer list for an optional subsequent worker/port handoff. The optional promise returned by the consumer is an acknowledgement and backpressure boundary. Cancellation only applies before ownership handoff. If the consumer throws or acknowledgement fails, the error is `transport-failed`, but the lease stays `transferred`: the original buffers are already detached and retrying them would be unsafe. A limit or structured-clone failure before handoff leaves the lease owned. `dispose()` is idempotent for an owned or transferred lease and releases the lease's references. It cannot revoke other references held by the caller. ## Lazy worker execution `createColumnarWorkerSession()` supplies the lifecycle missing from a raw `postMessage` call: lazy worker creation, a bounded serial queue, exact request correlation, monotonic progress, cross-thread cancellation, returned-batch validation, typed failures, and deterministic teardown. The SDK does not import or construct a browser or Node worker. The application injects a small `ColumnarWorkerTransport`, so its worker URL, CSP policy, credentials, module type, and bundler remain explicit. ```ts doc-test=skip reason="browser Worker URL and worker module are application-owned" import { createColumnarWorkerSession } from "@honua/sdk-js/query-planner"; const session = createColumnarWorkerSession({ maxPendingRequests: 8, createWorker: () => { const worker = new Worker(new URL("./columnar.worker.js", import.meta.url), { type: "module", }); return { postMessage: (message, transfer) => worker.postMessage(message, [...transfer]), addEventListener: worker.addEventListener.bind(worker), removeEventListener: worker.removeEventListener.bind(worker), dispose: () => worker.terminate(), }; }, }); const result = await session.execute("filter-active", batch, { signal: abortController.signal, onProgress: ({ fraction, stage }) => updateProgress(fraction, stage), }); // result.batch now owns the buffers returned by the worker. session.dispose(); ``` The worker module registers application-owned operations against its transport: ```ts doc-test=skip reason="worker global transport wrapper is application-owned" import { startColumnarWorkerHost } from "@honua/sdk-js/query-planner"; startColumnarWorkerHost({ transport: wrapDedicatedWorkerGlobal(self), operations: { async "filter-active"(input, { signal, reportProgress }) { signal.throwIfAborted(); reportProgress(0.25, "filter"); const output = await filterActiveRows(input, { signal }); reportProgress(1, "complete"); return output; }, }, }); ``` Only one request is transferred to a session worker at a time. Queued batches remain owned by the caller until dispatch, and `maxPendingRequests` (16 by default) includes the active request. There is no unbounded mode. An acknowledged result is validated against the same batch ceilings before the next request starts. Cancellation before dispatch removes the request without transferring its buffers. Cancellation after dispatch sends the versioned cancel message and retires the worker transport; queued work resumes on a newly created worker. This makes cancellation deterministic even when an application operator fails to observe its `AbortSignal`. Worker operators should still poll the signal so worker-local resources are released promptly. Late or duplicate messages from a retired worker cannot settle another request. The main session and worker host both fail closed on protocol-version drift, unknown operations, batch/metric disagreement, invalid or decreasing progress, transport faults, and malformed results. Progress callbacks are observational: an exception thrown by a callback cannot corrupt ownership or settlement. Worker factories and hosts snapshot transport methods and batch ceilings before the first asynchronous boundary; later mutation of the caller-owned options object cannot redirect transferred buffers. Abort signals are accessed through a failure-contained listener/read seam, so a throwing foreign signal settles the request instead of losing it. A closed host transport can prevent a response from being delivered, but that delivery failure is contained and the host still releases its active-request slot without an unhandled rejection. ## Typed errors `HonuaColumnarTransferError.code` is one of: - `invalid-batch` - `row-limit-exceeded` - `memory-limit-exceeded` - `schema-limit-exceeded` - `metadata-limit-exceeded` - `buffer-view-limit-exceeded` - `string-limit-exceeded` - `already-leased` - `aborted` - `already-transferred` - `disposed` - `transport-failed` `HonuaColumnarWorkerError.code` is one of: - `invalid-request` - `invalid-response` - `unknown-operation` - `queue-full` - `aborted` - `operation-failed` - `worker-failed` - `disposed` ## Deliberate remaining scope This slice does not claim the full #394 workstream. Arrow IPC decoding, built-in filter/projection/reprojection/aggregation operators, multi-batch streaming across more than one in-flight worker, planner integration, renderer consumption, batch cache identity, realtime patches, application-specific CSP worker URL policy, and bounded conversion back to feature objects remain separate work. --- # File: docs/realtime-resume.md # Resumable realtime delivery The `@honua/sdk-js/realtime` subpath includes an opt-in, transport-neutral delivery gate for snapshot-plus-delta streams. It sits between a transport and the existing realtime reducer/store. The gate does not open or reconnect a network transport; it decides whether an event is safe to apply and whether a durable cursor can resume the exact accepted subscription. ```ts doc-test=skip reason="partial excerpt requires application host context" import { createRealtimeFeatureStore, createResumableRealtimeSubscription, } from "@honua/sdk-js/realtime"; const featureStore = createRealtimeFeatureStore(); const delivery = await createResumableRealtimeSubscription({ context: { kind: "honua.realtime-resume-context", version: 1, sourceId: "incidents", queryFingerprint: acceptedPlan.fingerprint, sourceVersion: "incident-snapshot-v7", schemaVersion: "incident-schema-v3", authorizationScopeFingerprint: aclFingerprint, }, checkpointStore: durableCheckpointStore, apply: (event, signal) => { if (signal.aborted) return; featureStore.apply(event); }, }); transportObserver.next = (event) => { if (event.type === "snapshot" || event.type === "delta" || event.type === "upsert" || event.type === "delete") { void delivery.enqueue(event); } }; ``` ## Safety model A `honua.realtime-checkpoint@1` binds all resume positions to: - source identity and source version; - accepted query/plan fingerprint; - schema version; - an opaque authorization-scope fingerprint; - the last contiguous sequence plus available cursor, watermark, timestamp, and delta-token positions; - a bounded recent event-id window. Changing any bound identity produces `resnapshot-required`; the SDK never silently reuses the cursor. A new subscription without a compatible checkpoint also requires a replacement snapshot before deltas can apply. Adapters project a server-expired cursor, an unsupported resume mode, or a transport-detected gap through `delivery.requireResnapshot(...)`. That method invalidates queued work and accepts only a replacement snapshot next; it does not silently restart from the newest delta. After a baseline exists, only the next contiguous safe-integer sequence can advance it. Older sequences are reported as duplicates. Missing sequences, conflicting top-level/nested checkpoint fields, or reuse of a recent event id at a new sequence stop delivery and require a replacement snapshot. A replacement snapshot received during ordinary live delivery must advance the existing sequence; a stale or equal snapshot cannot regress the baseline. A replacement snapshot may establish a lower sequence only after an explicit `requireResnapshot(...)` transition, which marks a deliberate new recovery epoch. Accepted replacement snapshots reset the bounded event-id window. `enqueue` treats transport input as untrusted at runtime. Only snapshot, upsert, delete, and delta discriminators reach the consumer. The SDK captures event identity and resume metadata synchronously, projects only cursor, watermark, timestamp, sequence, and delta-token fields into the versioned checkpoint envelope, and drops unrelated fields before application or persistence. Caller mutation after enqueue therefore cannot change durable deduplication identity, and credentials or adapter metadata cannot hitchhike inside a saved checkpoint. The persisted recent-event-id history defaults to 256 entries and has an absolute 4,096-entry safety ceiling. Oversized loaded histories are rejected before their elements are scanned; accepted histories are copied directly from their configured bounded tail. This first gate requires a trustworthy monotonic sequence on every snapshot or delta. Cursor-only and delta-token-only protocols are not silently assigned a client sequence: their future adapters must obtain an ordering guarantee from the server or report resume as unsupported and resnapshot. ## Backpressure and cancellation `maxPendingEvents` bounds the applying event plus queued data events (default 64). Overflow aborts the active delivery, resolves queued work as `resnapshot-required`, and refuses more deltas. One replacement snapshot may wait behind an abort-ignoring consumer because it is the only recovery path; ordinary data remains bounded. Consumers should honor the supplied `AbortSignal` and make application idempotent, because JavaScript cannot undo a side effect already performed by a callback that ignores cancellation. Closing or aborting the gate prevents any later result from advancing its checkpoint. Consumer errors leave the prior checkpoint unchanged. Checkpoint save errors are explicit: the in-memory accepted position remains visible with `checkpointPersisted: false`, phase becomes `error`, and no further events are accepted by that gate. Without a `checkpointStore`, accepted checkpoints remain available in memory but `checkpointPersisted` stays false. Callers may persist them as part of their own atomic application transaction; the SDK does not claim durability it did not observe. Checkpoint persistence occurs after successful consumer application. This is an at-least-once boundary, not a transaction spanning an arbitrary application store and checkpoint database. Applications that require atomic exactly-once effects must persist their materialized state and checkpoint transactionally, or use event ids/versions to make replay idempotent. ## Scope and remaining work This is the first production slice of issue [#393](https://github.com/honua-io/honua-sdk-js/issues/393), not completion of the full workstream. It does not claim: - automatic SSE, WebSocket, OData-delta, or protocol-feed reconnection; - cursor-only protocol adaptation where no trustworthy ordering sequence is available; - server support for cursor retention or expiry negotiation; - renderer, cache, columnar-batch, or offline-store patch integration; - lag/retry transport telemetry or a shared transport conformance suite. Adapters should declare unsupported resume behavior before subscription when the protocol can determine it. Expired server cursors must be projected as an explicit replacement-snapshot transition rather than fixture fallback or an unverified continuation. --- # File: docs/plugin-manifest-certification.md # Plugin manifest and certification contract The experimental `@honua/sdk-js/plugin` entrypoint is the first bounded slice of the plugin SDK tracked by [issue #392](https://github.com/honua-io/honua-sdk-js/issues/392). It lets a third-party package describe its compatibility and authority boundary as inert JSON, then produces a deterministic report for a specific host. The SDK does **not** import plugin code, install packages, or maintain a global registry. A certified manifest means only that its declaration is well formed and compatible with the supplied host snapshot. Applications explicitly import factories and may run them through the application-local lifecycle described below. A separate, deterministic behavioral-conformance harness then proves a certified plugin's runtime behavior (retries, performance bounds, and bundle metadata) against committed golden reports, and a machine-readable support-status program records each plugin's lifecycle stage. ## Authoring a manifest ```ts doc-test=compile import { HONUA_PLUGIN_API_VERSION, HONUA_PLUGIN_MANIFEST_VERSION, certifyHonuaPluginManifest, type HonuaPluginManifest, } from "@honua/sdk-js/plugin"; const manifest = { manifestVersion: HONUA_PLUGIN_MANIFEST_VERSION, id: "com.example.cloud-tiles", version: "1.0.0", kind: "protocol", package: { name: "@example/honua-cloud-tiles", entrypoint: "./plugin.js" }, compatibility: { pluginApi: HONUA_PLUGIN_API_VERSION, minimumSdk: "0.1.0-beta.0", maximumSdkExclusive: "0.2.0", environments: ["browser", "worker"], }, capabilities: ["tiles"], requestedGrants: { networkOrigins: ["https://tiles.example.com"] }, data: { cache: "memory", freshness: "ttl", authentication: "none", provenance: "preserved", mutation: "none", realtime: "none", }, lifecycle: { initialization: "explicit", disposal: "required" }, support: "community", } as const satisfies HonuaPluginManifest<"protocol">; const host = { pluginApi: HONUA_PLUGIN_API_VERSION, sdkVersion: "0.1.0-beta.0", environment: "browser", grants: { networkOrigins: ["https://tiles.example.com"] }, }; // The trust boundary accepts JSON text, never executable object values. const report = certifyHonuaPluginManifest(JSON.stringify(manifest), JSON.stringify(host)); ``` `JSON.stringify` is appropriate for trusted application-owned literals like the example above. Do not import an untrusted plugin module and stringify its exports: serialization itself can run getters or Proxy traps before the SDK is called. Read third-party manifest bytes as text (for example, from the package file or an HTTP response) and pass that text directly to the validator. The report contains no time, machine path, or random identifier, so the same manifest and host snapshot serialize identically. Its `manifest` and `host` blocks contain the complete canonical snapshots plus SHA-256 fingerprints; changing an entrypoint, capability, data semantic, requested authority, peer, grant, environment, API version, or SDK version changes the corresponding fingerprint. CI can reject when `status` is `"rejected"` and archive the deeply frozen JSON as certification evidence without permitting manifest/host swaps. The top-level `sha256` covers every other report field, including both complete snapshots, their hashes, status, checks, and diagnostics. It is an integrity receipt for externally archived evidence, not a signature or proof of issuer. ## Compatibility policy - `manifestVersion` and `pluginApi` are exact versions. Unknown versions fail closed; consumers must not guess how to reinterpret them. - SDK and peer bounds use exact SemVer values rather than arbitrary range expressions. `minimumSdk` is inclusive and `maximumSdkExclusive` is optional. - Prerelease ordering follows SemVer, so `0.1.0-beta.2` satisfies a `0.1.0-beta.0` minimum but does not satisfy `0.1.0`. - SemVer parsing is linear-time over ASCII input and comparison uses SemVer's deterministic ASCII identifier order rather than the process locale. - Environment and peer checks use only the explicit host snapshot. A missing required peer rejects certification; a missing optional peer is a warning. - This experimental API is not yet the GA compatibility promise requested by #392. Promotion requires the remaining runtime and independent-kit phases. ## Security boundary - Network grants are exact HTTPS origins. Wildcards, paths, embedded credentials, and non-TLS origins are rejected. - Credential grants contain scope identifiers only—never tokens, passwords, headers, environment-variable names, or credential values. - Persistent data requires scoped storage. Declared mutation requires an explicit mutation grant. Authenticated access requires credential scopes. - Capability semantics also fail closed. `protocol:edit` and `source-format:write` require both `data.mutation: "explicit"` and a mutation grant; `cache:write` and `cache:invalidate` require persistent-cache semantics and scoped storage. The full machine-readable mapping is exported as `HONUA_PLUGIN_CAPABILITY_REQUIRED_GRANTS`. - Certification fails if the application grant set is weaker than the plugin request. A report is not itself an enforcement mechanism; the future host runtime must inject only the certified grants and must never expose ambient credentials or mutation authority. - The package entrypoint is repeatedly percent-decoded to a stable form before validation, normalized in the certified snapshot, and rejected on encoded or literal traversal, absolute escape, backslashes, query/fragment suffixes, or malformed/excessive encoding. This API never resolves or executes it. - Manifest and host inputs must be JSON text. Raw objects—including accessors, proxies, custom prototypes, symbols, functions, and other executable or noncloneable values—are rejected from their primitive `typeof` result before any reflection or user code can run. A side-effect-free lexical pass enforces text, depth, and node-count bounds before `JSON.parse` materializes values. Validation and fingerprinting then use only the parser-created, detached, deeply frozen snapshot; caller objects are never reflected on or returned. ## Extension inventory The closed `HONUA_PLUGIN_KINDS` and `HONUA_PLUGIN_CAPABILITIES` registries cover protocol, source/format, renderer, auth, geocoder/routing, analysis, style, cache, and realtime declarations. Capability names are kind-specific so a manifest cannot inflate its advertised surface with unknown strings. The manifest also records support status and cache, freshness, auth, provenance, mutation, realtime, peer, environment, and disposal semantics for inventory tools. ## Application-local registry and lifecycle `HonuaPluginRegistry` turns certified declarations into explicit application instances without adding plugins to root SDK workflows: ```ts doc-test=compile import { HonuaPluginRegistry, type HonuaPluginFactory, type HonuaPluginManifest, } from "@honua/sdk-js/plugin"; declare const manifest: HonuaPluginManifest<"style">; declare const host: unknown; const stylePlugin: HonuaPluginFactory<"style"> = { manifest: JSON.stringify(manifest), initialize(context) { return { extension: { id: context.manifest.id, kind: "style" }, start() {}, stop() {}, dispose() {}, }; }, }; const registry = new HonuaPluginRegistry({ host: JSON.stringify(host), services: {}, }); await registry.register([stylePlugin]); const extension = registry.get("style", manifest.id); await registry.dispose(); ``` - A factory carries inert manifest JSON plus an optional exact dependency list. The registry certifies every declaration, builds a stable id-sorted topological order, and certifies again immediately before `initialize`. `context.resolve()` exposes only dependencies named by that factory; it cannot discover another plugin merely because both share an application registry. - `initialize`, `start`, `stop`, and `dispose` are typed by all nine extension kinds. Only `initialize` is universally required; `dispose` is also required when the certified manifest declares required disposal, while inert plugins that declare no disposal pay for no empty hooks. - Factories, callbacks, dependencies, host services, and registration options are captured before an asynchronous boundary. Registration operations on one registry are serialized; separate registries have no shared state and may run concurrently in browsers, workers, Node, or SSR. - Context exposes only services supplied to that registry and allowed by the certified declaration. Network calls are origin-restricted, credential lookups are scope-restricted, and mutation/storage/realtime services appear only when their matching grants and data semantics permit them. No ambient credential, environment variable, fetch override, or global cache is used. - Batch registration is transactional. Cancellation or a hook failure stops and disposes initialized plugins in reverse order. Cleanup continues after a cleanup failure; `HonuaPluginRegistryError.cleanupErrors` preserves those failures separately, so the primary `cause` is not hidden. Cleanup receives a fresh non-aborted signal even when the registration signal caused rollback. - `HonuaPluginRegistryError` participates in the common tagged SDK error envelope while preserving its existing `PLUGIN_*` `.code`, message, `instanceof`, primary `cause`, and frozen cleanup aggregate. Its grouped `.sdkCode` is always non-retryable. Serialization reports only a fixed known reason code plus safe cause classification; manifests, configuration/plugin identifiers, cause payloads, and cleanup failures stay local. Unknown runtime codes fail closed as `plugin.internal` / `PLUGIN_UNKNOWN` without coercion. - `dispose()` is idempotent, returns the same promise to concurrent callers, and performs reverse stop/dispose exactly once. Duplicate ids prevent implicit upgrades or state migration; because manifest v1 has no state-migration declaration, replacement is refused rather than guessed. - `diagnostics` returns immutable, sequence-stable machine events with codes, phases, statuses, and certified identities. Thrown error messages are not copied into diagnostics, preventing accidental credential/PII persistence. Plugin modules remain external to SDK core. Merely importing the root SDK or an unrelated subpath does not import a plugin factory, initialize a registry, or pull mapping/database peers into the bundle. ## Reference plugins for every kind Every declared kind ships a minimal, external-style reference implementation so authors can copy a working shape rather than a bare interface. Each is a small factory carrying inert manifest JSON, a typed extension, and lifecycle hooks; none of them are imported by SDK core. They live beside the tests at `test/fixtures/plugins/` (`external-style.ts` plus `reference/`) and are exercised end to end — certification, registration, extension call, and disposal — in `test/plugin-reference-samples.test.ts`. | Kind | Reference plugin | Capabilities | What it demonstrates | | --- | --- | --- | --- | | `protocol` | `referenceProtocolPlugin` | `query` | Bounding-box feature count over the origin-restricted network service | | `source-format` | `referenceSourceFormatPlugin` | `read` | Read-only `lng,lat` text parsing with no requested authority | | `renderer` | `referenceRendererPlugin` | `2d` | Pure point-to-draw-command translation | | `auth` | `referenceAuthPlugin` | `authorize` | Header resolution from a scope-restricted credential service | | `geocoder-routing` | `referenceGeocoderPlugin` | `geocode` | Offline gazetteer lookup | | `analysis` | `referenceAnalysisPlugin` | `execute`, `cancel` | Cancellable reduction honouring an `AbortSignal` | | `cache` | `referenceCachePlugin` | `read`, `write`, `invalidate` | Persistent cache over granted scoped storage | | `realtime` | `referenceRealtimePlugin` | `subscribe` | Push subscription through the realtime service | | `style` | `externalStylePlugin` | `validate` | The original external-style sample (issue #424/#466) | Each manifest certifies against one shared host that grants exactly the authorities the samples request, so the security boundary stays honest: the `auth` sample only ever receives the `reference.read` scope identifier, the `cache` sample only writes through scoped storage, and the `protocol` sample's network calls are restricted to its declared origin. ## Running the certification kit independently The certification logic is also exposed as a runnable kit so a third party can validate their own plugin outside this repository. Installing the SDK provides the `honua-plugin-certify` bin, which reads a manifest and a host snapshot as inert JSON text, certifies one against the other, prints the deterministic report to stdout (or `--out`), and resolves an exit code: ```sh # 0 = certified, 1 = rejected, 2 = usage/input error npx honua-plugin-certify --manifest ./manifest.json --host ./host.json --pretty ``` The bin never resolves or executes the plugin entrypoint; it only reads the two JSON documents. The same logic is available programmatically through the `certifyHonuaPluginManifest` public API shown above, and the CLI core (`runPluginCertificationCli`) takes an injected I/O boundary so it can run in any host, not just Node. This makes the harness suitable for a plugin author's own CI: fail the build when `status` is `"rejected"`, and archive the frozen report — bound to both canonical snapshots by SHA-256 — as certification evidence. ## Signed reports and tamper-evident verification Every certification report carries a top-level `sha256` receipt over all its other fields (including both canonical snapshots and their fingerprints). The kit re-checks that receipt so an archived report is verifiably tamper-evident: ```sh # 0 = verified intact, 1 = tampered, 2 = usage/input error npx honua-plugin-certify --verify ./report.json ``` The same check is available programmatically as `verifyHonuaPluginCertificationReport(reportText)`. It reads the report as inert JSON text and recomputes every stored digest — the top-level receipt plus the `manifest.sha256` and `host.sha256` snapshot fingerprints — from the report's own content. Any altered field, swapped snapshot, or edited diagnostic changes a recomputed digest and yields a structured `REPORT_SIGNATURE_MISMATCH` or `REPORT_FINGERPRINT_MISMATCH` diagnostic. This is a deterministic in-repo integrity proof, not a public-key signature: it proves a report is internally self-consistent and unmodified since issue, not which authority issued it. A trusted-issuer signing authority (which key, which registry) is a product decision and is deliberately out of scope here. ## Support-status program `support` records who backs a plugin (`community`, `partner`, or `honua`). The optional, machine-readable `supportStatus` attestation records the plugin's lifecycle stage so applications and agents can act on it without loading code: - `state` is `supported`, `experimental`, or `deprecated`. - `since` and `removedIn` are exact SemVer values; `replacement` is a plugin id. - Certification fails closed when `state` is `deprecated` but the manifest names neither a `removedIn` version nor a `replacement` id, so a deprecation always carries an actionable migration path. Support findings are reported under a dedicated `support` certification check. The state vocabulary is exported as `HONUA_PLUGIN_SUPPORT_STATES`. The broader governance program (who may set `partner`/`honua` tiers, security-review sign-off, naming policy) is a process decision layered on top of this schema. ## Behavioral conformance and golden reports `runHonuaPluginConformance(spec, host)` runs a certified plugin through a deterministic behavioral suite and returns a frozen, digest-sealed `HonuaPluginConformanceReport`. The harness registers the plugin in an application-local registry with instrumented host services and counts integer observations only — no wall-clock time, randomness, or host path — so the report serializes identically on every run and is committed as a golden report (`test/fixtures/plugins/golden/conformance-report.json`) and asserted byte-for-byte in `test/plugin-conformance.test.ts`. Three scenarios are covered, each an observation compared against a declared bound: | Scenario | What it proves | | --- | --- | | `retries` | The plugin recovers from injected transient host failures within its declared attempt budget (`hostAttempts <= maxAttempts`, `recovered`). | | `performance` | One operation's host-interaction cost stays within bound and is identical across runs (`serviceCalls <= maxServiceCalls`, `deterministic`). | | `bundle-metadata` | The declared bundle footprint stays within budget with complete inventory metadata (`minifiedBytes`, `gzipBytes`, `metadataComplete`). | The report binds the certification digest it was run against, so a conformance result cannot be replayed against a different manifest or host. The reference retry-capable plugin exercised end to end lives at `test/fixtures/plugins/reference/conformance.ts`. ## Remaining governance decisions in #392 The code-buildable core of every named criterion is delivered above. What remains is process, not code: a trusted third-party signing authority and key distribution for reports, and the certification governance policy (who grants `partner`/`honua` support tiers, security-review sign-off, and naming rules). --- # File: docs/deckgl-adapter.md # deck.gl binary adapter (experimental) `@honua/sdk-js/deckgl` is a renderer-neutral boundary between Honua plan/source identity and deck.gl binary layer data. It is an experimental first slice of [#388](https://github.com/honua-io/honua-sdk-js/issues/388), not the complete GPU analytics workstream. The adapter currently projects scatterplot data from caller-owned typed arrays. It does not convert to GeoJSON or create one object per feature. Array views are forwarded to deck.gl unchanged and `projection.metrics.copiedBytes` is always zero. Default ceilings reject more than 1,000,000 rows, 32 attributes, 64 forwarded properties, or 256 MiB of unique backing allocations before a deck.gl layer is constructed. The adapter reads foreign request, data, identity, attribute, and property descriptors once into a bounded frozen snapshot. Typed-array byte length, offset, component width, and backing allocation metrics come from JavaScript intrinsics rather than overridable getters. Attribute offsets and strides must be component-aligned, and `normalized`, when present, must be boolean. ## Optional peer deck.gl is not part of the root SDK dependency graph: ```sh npm install @deck.gl/layers ``` Load the peer lazily or inject the constructor from an existing deck.gl install: ```ts doc-test=compile import { createDeckGlAdapter, loadDeckGlPeers } from "@honua/sdk-js/deckgl"; const adapter = createDeckGlAdapter({ peers: await loadDeckGlPeers() }); ``` Injecting peers is useful for import maps, custom builds, and tests. The lazy loader never chooses a CDN and reports `HonuaDeckGlAdapterError` with code `missing-peer` when the package or required export is unavailable. ## Binary projection and picking identity ```ts doc-test=skip reason="partial excerpt requires application host context" const positions = new Float32Array([157.85, 21.3, 157.86, 21.31]); const featureIds = new Uint32Array([301, 302]); const projection = adapter.project({ layer: "scatterplot", layerId: "incidents", data: { length: 2, attributes: { getPosition: { value: positions, size: 2 }, }, }, identity: { sourceId: "incidents-live", planId: "plan:sha256:…", sourceVersion: "42", featureIds, }, props: { radiusUnits: "meters" }, }); projection.selectionForPick(1); // { sourceId, planId, sourceVersion, featureId: 302, rowIndex: 1 } ``` `featureIds` is copied once into a private bounded scalar array at projection construction. Picks never reread caller-owned identity or row-count objects, so later caller mutation cannot change selection identity. This identity copy is separate from the binary payload; geometry and attribute buffers remain zero-copy. A caller can map the pick result into exploration/selection state without relying on unstable deck.gl object identity. Mounting uses a small host contract so standalone Deck instances and MapLibre overlay owners can retain control of their own layer collections: ```ts doc-test=skip reason="partial excerpt requires application host context" const mounted = projection.mount(host); // host implements addLayer/removeLayer mounted.dispose(); adapter.dispose(); // also disposes every still-owned mount ``` Successful removal is idempotent. If a host removal throws, the handle stays owned and reports `dispose-failed`; calling `mounted.dispose()` or `adapter.dispose()` again retries it. Mount registration happens before the foreign `addLayer` callback, so synchronous adapter disposal rolls the newly added layer back before `mount()` returns. ## Diagnostics and boundaries `DECK_GL_CAPABILITIES` is the capability truth for this contract version. Scatterplot is `gpu-binary`; feature path/polygon, vector tile, H3, Quadbin, heatmap, cluster, contour, and trips are explicitly `not-implemented`. The projection diagnostic reports the chosen strategy, input-array precision, fidelity, and absence of an implicit fallback. Unsupported or malformed paths throw a typed error rather than materializing feature objects or silently downgrading. Remaining #388 work includes normative Arrow/GeoArrow mappings after the columnar data-plane contract lands, indexed and aggregate layer families, realtime buffer patch/rebuild rules, direct MapLibre overlay and standalone Deck hosts, WebGPU boundaries, and the million-feature browser benchmark against [#387](https://github.com/honua-io/honua-sdk-js/issues/387). --- # File: docs/cesium-entity-adapter.md # Experimental Cesium entity adapter `@honua/sdk-js/scene-workspace` exposes an experimental accepted-plan workflow for projecting a canonical `Source` query into a Cesium `EntityCollection`: ```ts doc-test=skip reason="partial excerpt requires application host context" import { explainQuery } from "@honua/sdk-js/query-planner"; import { mountSourceToCesium } from "@honua/sdk-js/scene-workspace"; const plan = explainQuery({ descriptor: source.descriptor, query: { pagination: { limit: 5_000 }, returnGeometry: true, outSr: 4326, }, sourceVersion, schemaVersion, authorizationScope, }); const mounted = await mountSourceToCesium(viewer.entities, source, plan, { sourceVersion, schemaVersion, authorizationScope, time: { startField: "observed_at", endField: "expires_at" }, verticalDatum: "ellipsoidal-wgs84", }); await mounted.refresh(); mounted.dispose(); ``` The core projection (`projectSourceToCesium`) does not import Cesium. Mounting accepts either a minimal injected Cesium module or async loader; if neither is provided, the optional `cesium` peer is imported lazily. Importing the entrypoint in Node/SSR therefore does not initialize a browser or WebGL runtime. ## Supported slice - One accepted, remote `query` step whose executable query exactly matches the canonical IR, with explicit geometry and a positive row limit no greater than `maxEntities` (10,000 by default). - Explicit WGS84 output (`outSr: 4326`). Coordinates are never silently reinterpreted or reprojected. - Point, single-part line, and single-ring polygon geometries in GeoJSON or common Esri shapes. Finite Z values require an explicit `verticalDatum: "ellipsoidal-wgs84"`; otherwise the feature is omitted with a stable fidelity diagnostic. - Stable entity identity from `featureIdField` or the source primary key. - Attributes are copied into deeply frozen JSON-like scalar, dense-array, and plain-object snapshots. Dates, class instances, sparse arrays, accessors, and other non-JSON values omit the feature with an unsupported-fidelity diagnostic rather than retaining mutable caller-owned objects. - Optional offset-bearing ISO instants with at most millisecond precision, or integer Unix epoch-millisecond start/end attributes, mapped to Cesium availability intervals. Ambiguous local-time strings and precision-losing timestamps are omitted with a fidelity diagnostic. - Serialized snapshot refresh, cancellation checks before renderer mutation, reentrant-disposal guards, rollback attempts, deterministic cleanup, and retryable failed disposal. - Stable diagnostics for transfer-limited results, source degradation, missing identity, unsupported geometry, invalid time intervals, and snapshot rebuilds. Unsupported features are omitted with `fidelity: "unsupported"`; they are not rendered as plausible substitutes. Invalid plans, CRS, limits, and adapter options fail before mounting. ## Deliberate non-goals for this slice This is not completion of issue #395 and is not yet a beta Cesium adapter. Terrain and imagery providers, glTF/models, point clouds and 3D Tiles continue through the existing scene primitive adapter. Multi-part geometry and polygon holes, vertical datum transforms, styling, clustering, streaming/tiled execution, live deltas, camera/selection/filter synchronization, attribution UI, asset authorization/caching, browser examples, and WebGL leak/performance certification remain future work. Refresh currently declares an `entity-snapshot` rebuild boundary. Stable IDs are preserved across rebuilds, but this first slice does not claim fine-grained property or sampled-position delta application. --- # File: docs/offline-regions.md # Downloadable offline regions (experimental) `@honua/sdk-js/offline` is the first bounded slice of issue [#396](https://github.com/honua-io/honua-sdk-js/issues/396). It defines a versioned manifest and a storage-neutral download coordinator. It does not make the broader local-first feature complete. ```ts doc-test=skip reason="partial excerpt requires application host context" import { createOfflineRegionManifest, downloadOfflineRegion, } from "@honua/sdk-js/offline"; const manifest = await createOfflineRegionManifest({ name: "Field area", sourceId: "incidents", endpoint: "https://example.test/FeatureServer/0", authorizationScopeFingerprint: currentAclFingerprint, bounds: { minX: -158.3, minY: 21.4, maxX: -157.6, maxY: 21.8, crs: "EPSG:4326" }, minZoom: 8, maxZoom: 14, sourceVersion: "source-v3", schemaVersion: "schema-v7", planVersion: "plan-v2", observation: { state: "live", observedAt: "2026-07-10T10:00:00Z" }, resources: plannedResources, }); const receipt = await downloadOfflineRegion(manifest, { store: applicationStore, load: applicationResourceLoader, logicalQuotaBytes: 512 * 1024 * 1024, signal: abortController.signal, onProgress: renderProgress, }); ``` ## Contract guarantees - Manifest identity is deterministic over normalized content. Resource ids, attribution ids, and object keys use locale-independent code-unit ordering. - URL credentials and recognized signed/auth query parameters are removed. Only a domain-separated SHA-256 digest of the caller's authorization scope fingerprint is persisted. - Every resource has an exact logical byte length and required SHA-256 digest. Loader output is copied into coordinator-owned memory before hashing, progress, or writing, so later loader mutation cannot alter committed bytes. Each resource also carries source, schema, plan, and attribution identities inherited from the manifest unless the planner supplies more specific versions. Snapshot observation, validity, expiration, and HTTP validators remain explicit instead of making cached bytes appear live. - Untrusted manifests are synchronously normalized into an owned snapshot before any hash or adapter await. Plain shapes, dense arrays, resource/attribution/ metadata counts, logical bytes, and incremental UTF-8 string bytes are bounded before copying, sorting, or canonical JSON construction. - Quota is explicitly **logical payload-byte quota**: it sums declared resource payload lengths and does not claim physical disk occupancy, unique backing bytes, compression, deduplication, or store overhead. Admission is deterministic: expired regions, then least-recently-used regions, then code-unit id order. Pinned regions are never automatically evicted. - The injected transaction stages evictions and writes, then publishes them atomically with the manifest and receipt. Commit compares the inventory revision used for planning and independently enforces logical quota in the same atomic mutation; a concurrent winner makes the loser return typed `inventory-changed` and roll back. Storage implementations must copy bytes before `write()` resolves and satisfy this CAS/atomicity contract. - Progress is explicit across planning, download, write, commit, and completion. A successful receipt reports `integrity: "verified"` and `quotaAccounting: "logical-payload-bytes"`. The manifest contains logical resource ids, not request URLs. The injected loader may resolve short-lived signed URLs or authorization at download time; those values never cross the persistent-store boundary. ## Non-goals and remaining work This slice intentionally provides no IndexedDB or service-worker adapter, no network reachability policy, no resumable partial transaction, no encryption policy, no storage schema migration, no cached query/read integration, and no local edit queue or replica conflict replay. Those remain required before issue #396 can satisfy its GA acceptance criteria. This entrypoint is `@experimental` and subpath-only so the root and browser bundles do not absorb it. --- # File: docs/agent-safety.md # Safe agent plan boundary `@honua/sdk-js/agent-safety` is a deterministic trust boundary between untrusted plan proposals and host-owned effect execution. It is part of the SDK's stable tier (semver-protected; see [`docs/decisions/agent-surface-stabilization.md`](./decisions/agent-surface-stabilization.md)), and its security posture — envelope forgery, replay, effect-budget bypass, receipt tampering, plan-fingerprint mismatch — is documented with per-threat conformance tests in the [agent-safety threat model](./agent-safety-threat-model.md). It validates JSON-compatible structured data, produces an immutable dry run and effect budget, binds a reviewer signature to the exact plan and policy, revalidates current source context, executes an exact approved operation through a host-supplied adapter, and signs/verifies execution evidence. Plan normalization, dry run, approval, and verification never invoke a model, tool, source, renderer, subscription, or job. `executeAgentPlanStep` is the explicit effect boundary; it invokes only a matching host executor after authorization, single-use consumption, and a durable start audit. `@honua/sdk-js/agent-tools` remains the runtime action adapter, and `@honua/sdk-js/query-planner` remains the source of query-plan fingerprints. ## Plan and policy Every step declares its tool, effect, fields, row and byte ceilings, exact query plan fingerprint, canonical parameters digest, canonical operation-input digest, and source binding. The operation digest is recomputed from the visible tool, effect, source ID, query-plan identity, fields, and parameters digest, so those claims cannot disagree. The source binding includes schema/source versions, stable authorization-scope identifiers, data mode, observation time, attribution, and credential-free citations. The plan also identifies its actor and can identify the proposing provider/model. Do not put prompts, credentials, tokens, or tool arguments in this envelope. ```ts doc-test=skip reason="partial excerpt requires application host context" import { dryRunAgentPlan, issueAgentApproval, executeAgentPlanStep, } from "@honua/sdk-js/agent-safety"; const policy = { allowedTools: ["query"], // Omission is deliberately read-only. Other effects require explicit opt-in. allowedEffects: ["read"], sources: { incidents: { fields: ["OBJECTID", "status"], authorizationScope: ["incidents:read"], schemaVersions: ["schema-7"], sourceVersions: ["snapshot-9"], dataModes: ["live"], maxProvenanceAgeMs: 60_000, citationOrigins: ["https://data.example.test"], citationResourcePrefixes: ["/incidents"], }, }, maxSteps: 1, maxRows: 500, maxBytes: 2_000_000, maxFieldsPerStep: 16, maxAuthorizationScopesPerSource: 8, maxCitationsPerSource: 4, maxOperationParameterBytes: 16_384, maxOperationParameterNodes: 256, maxOperationParameterDepth: 8, }; const dryRun = dryRunAgentPlan(untrustedPlan, policy, { now: "2026-07-10T20:00:00.000Z", }); // The signer is supplied by a trusted host. Keep keys out of browser bundles. const approval = await issueAgentApproval( dryRun, policy, { id: "approval-42", approver: "reviewer@example.test", issuedAt: "2026-07-10T20:00:00.000Z", expiresAt: "2026-07-10T20:05:00.000Z", maxRows: 100, // single-step shorthand; may narrow, never widen }, hostSigner, { now: "2026-07-10T20:00:00.000Z", maxClockSkewMs: 5_000 }, ); const execution = await executeAgentPlanStep({ dryRun, policy, approval, approvalVerifier: hostVerifier, context: { sources: { incidents: currentIncidentSourceBinding } }, stepId: "query-incidents", operation: exactQueryPlanInput, useConsumer: hostAtomicApprovalUseStore, executor: hostQueryExecutor, auditSink: hostDurableAuditSink, receiptSigner: hostReceiptSigner, executionId: "execution-42", }); // execution.value is an owned frozen JSON snapshot; execution.receipt binds it. ``` `dryRunAgentPlan` rejects unknown properties, accessors, non-plain objects, invalid or duplicate values, non-canonical timestamps, credentials in citation URLs, conflicting bindings, unknown tools/sources, operation-input drift, disallowed effects or fields, scope/version/data-mode drift, stale provenance, and row/byte overflow. Its default effect allowlist is only `read`. Foreign policy data is descriptor-snapshotted and frozen exactly once per public operation. That same snapshot supplies the signed policy digest, dry-run revalidation, freshness check, and parameter limits. Reflection errors are reported as `HonuaAgentSafetyError`; a raw Proxy trap error is not exposed. Policy ceilings are themselves capped by `AGENT_SAFETY_HARD_LIMITS`. Collection lengths are rejected before indexed descriptors are read, and operation JSON is bounded by node count, depth, object/array count, and cumulative UTF-8 bytes. The same cumulative pre-signature budget applies to dry runs, approval requests, approval step arrays, current contexts/source maps, execution evidence, consumption records, and receipts—including both property-key and value bytes. ## Signatures, cancellation, and receipts Signer/verifier interfaces carry an algorithm and key ID and receive canonical JSON. Hosts can back them with WebCrypto, KMS, HSM, or a remote same-origin signing service. Approval and receipt verifiers require the configured algorithm/key ID to match the envelope. Signatures cover the canonical payload; SHA-256 envelope digests provide deterministic identity and diagnostics. All operations accept `AbortSignal`. Cancellation is checked before validation, across awaited signer/verifier boundaries, and before a successful value is returned. Aborted work cannot return a usable approval or receipt. Approval envelopes are explicitly single-use per step. The required `AgentApprovalUseConsumer` must atomically consume the approval-digest/step key and return an unforgeable host record containing a nonce, consumption time, opaque authentication token, and exact approval/step/input binding. The SDK immediately asks the same store to verify that record. This host-owned replay store is the concurrency boundary that prevents duplicate mutation, publish, share, subscription, and job effects. Signed approvals contain a row/byte allocation for every step. Multi-step approvals must use `stepLimits` when narrowing; an ambiguous aggregate-only narrowing is rejected. Step authorization returns a copy with those narrowed limits, not the wider proposed limits. After a separately authorized host executor finishes, it can call `issueAgentExecutionReceipt` with bounded outcome evidence. The helper first re-verifies approval and current context, refuses evidence beyond approved row/byte ceilings, and signs the plan, policy, source bindings, approval, step ID, operation-input digest, atomic-use digest, outcome, result digest, and completion time. `verifyAgentExecutionReceipt` repeats those checks deterministically and rejects any modified field. Receipt issuance and verification require a host consumption verifier; public digests alone cannot create a receipt. The authenticated consumption record and token are included under the receipt signature. Receipt verification evaluates the historical approval at the signed completion time, so an authentic receipt remains verifiable after approval expiry. Supply the bound historical source context, not newly discovered current metadata. ## Approved execution and audit `executeAgentPlanStep` composes the authorization and receipt primitives. It requires an executor with one exact `tool` and `effect`, rejects mismatches before consuming the approval, and passes only the frozen operation and narrowed approval limits. All host data descriptors and bound callbacks are captured once before the first await; later caller mutation cannot replace the executor, approval store, verifier, signer, audit sink, clock, or operation. Executor output must be a bounded plain JSON value. Arrays use one captured length and objects stop discovery at the width ceiling before reading excess values. The SDK snapshots data descriptors without invoking accessors, derives the canonical UTF-8 byte count and SHA-256 digest, and refuses row or byte overflow. The audit sink must durably append a `started` event before execution and a `completed` event after every observed success, failure, or cancellation. Audit events carry pseudonymous digests for plan/actor/provider/model/step/tool/source/ schema/source-version identity, the finite effect and data mode, observation time, and plan/policy/binding/approval/input/use/result/receipt digests. They deliberately omit raw free-text identity, parameters, results, citations, authorization scopes, signatures, consumption nonce/token, and thrown error messages. A failed start audit prevents execution but deliberately leaves the already-consumed approval unusable; retry requires a new approval so a host cannot mistake an uncertain persistence boundary for an unused grant. A failed terminal audit is a typed `HonuaAgentExecutionError` carrying the signed receipt so a host can reconcile it without pretending persistence succeeded. `@honua/mcp-server/agent-execution` provides `createReadOnlyMcpAgentExecutor`. It binds one named standalone MCP read tool to this same SDK execution contract; it does not create a parallel approval model or enable mutation tools. Names must be bounded exact identifiers—wildcards and patterns are rejected—and every adapter must provide a deterministic `countRows(result)` callback. An uncounted result cannot silently produce a zero-row receipt. The API precondition is JSON-compatible structured data produced by JSON parsing or an equivalent structured clone. Indexed and object accessors are rejected without invocation. JavaScript `Proxy` traps are executable by language-level reflection itself and cannot be made side-effect free by a portable library; do not pass Proxies across this boundary. When reflection nevertheless fails, the failure is typed and no partially normalized authority escapes. Citation URLs must be HTTPS and contain no user info, query, or fragment. Paths are repeatedly percent-decoded within a fixed bound, Unicode-normalized, checked for traversal, and canonicalized before identity hashing. Every citation must match the source policy's exact origin and decoded resource-prefix allowlist. The SDK does not claim to recognize secrets embedded in arbitrary opaque path text; hosts prevent those paths by choosing narrow resource IDs or prefixes. ## Deliberate boundaries This is one production vertical slice of #397, not completion of that XL workstream. It does not translate natural language, provide a model adapter, manage signing keys or audit persistence, parse query predicates to infer field use, perform compensating actions, or establish CLI/renderer/mutation execution parity. Hosts must declare every field a step may read or write; query compiler integration can automate that declaration in a later slice. --- # File: docs/agent-safety-threat-model.md # Agent-safety threat model `@honua/sdk-js/agent-safety` is the deterministic trust boundary between untrusted agent plan proposals and host-owned effect execution, and `@honua/sdk-js/agent-tools` is the bounded runtime-action surface those plans ultimately drive. Both entrypoints are in the SDK's **stable tier** (see [`docs/decisions/agent-surface-stabilization.md`](./decisions/agent-surface-stabilization.md)), so the contracts described here are semver-protected: security reviews may cite this document knowing a breaking change to any envelope or verification step requires a major version. This document enumerates the threats the surface is designed to stop, the mechanism that stops each one, and the conformance test that exercises it. Companion reference: [`docs/agent-safety.md`](./agent-safety.md) (full API walkthrough) and [`docs/nl-map-control.md`](./nl-map-control.md) (the NL layer that consumes this boundary end to end). ## Trust boundaries and assumptions - **The plan proposer is untrusted.** Plans, operations, approvals, contexts, evidence, and receipts all enter as `unknown` and are descriptor-snapshotted, bounded (`AGENT_SAFETY_HARD_LIMITS`), and frozen before any digest or signature check. Accessors are rejected without invocation; `Proxy` inputs are out of contract. - **Key custody and persistence are host-owned.** `AgentEnvelopeSigner` / `AgentEnvelopeVerifier` and the atomic `AgentApprovalUseConsumer` replay store are host callbacks. The SDK guarantees *what* is signed and verified, not *where* keys live. - **The SDK never invokes an effect on its own.** Dry runs are side-effect free; `executeAgentPlanStep` is the single explicit effect boundary and only runs a host executor after authorization, single-use consumption, and a durable start audit. ## Threats and mitigations Every threat below is exercised by a committed conformance test; the tests run in the default `npm test` suite. ### 1. Envelope forgery **Threat.** An attacker fabricates or alters an approval envelope (or the dry run it binds to) to authorize a plan no reviewer signed — forging digests, swapping the approver, or presenting an approval for a different plan/policy. **Mitigation.** An approval binds `planDigest`, `policyDigest`, `bindingsDigest`, and `evaluatedAt` to one exact dry run, which is itself recomputed (`revalidateDryRun`) from the supplied plan and policy — a forged dry run cannot digest-match. The envelope digest is recomputed over the canonical unsigned payload, the signer identity (algorithm + key ID) must match the configured verifier, and the host `verifier.verify` must return exactly `true`. Any mutated field fails `integrity-failed` or `signature-invalid` before an effect is possible. **Tests.** - `test/agent-safety.test.ts` — "rejects forged dry runs, signature tampering, expiry, and context drift" - `test/agent-safety.test.ts` — "binds the exact plan/policy/context and permits only budget narrowing" - `test/agent-safety.test.ts` — "cannot issue a receipt from public digests without host-authenticated consumption evidence" ### 2. Replay (single-use consumption) **Threat.** A valid, signed approval is presented twice — concurrently or sequentially — to run the same approved step more than once (duplicate mutation, publish, job, …). **Mitigation.** Approvals are `use: "single"` per step. Authorization requires the host `AgentApprovalUseConsumer` to *atomically* consume the (approval digest, step ID, input digest) key and return an authenticated consumption record (nonce, consumption time, opaque token), which the SDK immediately re-verifies with the same store. A second consumption attempt returns nothing and fails `policy-denied`; the consumption record is bound into the receipt so post-hoc verification also proves single use. Expiry (`expiresAt`, bounded `maxClockSkewMs`) limits the replay window of any stolen envelope. **Tests.** - `test/agent-safety.test.ts` — "binds exact operation input and atomically consumes each approved step once" - `test/agent-execution.test.ts` — "does not invoke an effect after start-audit failure, executor mismatch, or replay" - `test/agent-safety.test.ts` — "rejects forged dry runs, signature tampering, expiry, and context drift" (expiry arm) ### 3. Effect-budget bypass **Threat.** A plan, approval, or execution result exceeds the reviewed row/byte/step/effect budget — a widened approval, an aggregate that hides a per-step overrun, an oversized operation payload, or an executor returning more data than approved. **Mitigation.** `dryRunAgentPlan` computes a frozen `AgentEffectBudgetV1` and rejects plans over policy ceilings (which are themselves capped by `AGENT_SAFETY_HARD_LIMITS`). Approvals may only *narrow* step limits — widening fails `policy-denied`, multi-step narrowing requires explicit `stepLimits`, and aggregate `approvedRows`/`approvedBytes` must equal the per-step sums. Operation parameters are bounded by policy byte/node/depth budgets before the replay store is touched. Execution evidence and receipts exceeding the approved per-step rows/bytes are refused before signing and on verification. **Tests.** - `test/agent-safety.test.ts` — "binds the exact plan/policy/context and permits only budget narrowing" - `test/agent-safety.test.ts` — "requires explicit per-step allocation when narrowing a multi-step approval" - `test/agent-safety.test.ts` — "enforces the policy operation-parameter budget before replay-store consumption" - `test/agent-safety.test.ts` — "rejects over-budget evidence before receipt signing and detects receipt tampering" (over-budget arm) - `test/agent-execution.test.ts` — "bounds wide results before reading excess values and uses one captured array length" ### 4. Receipt tampering **Threat.** An execution receipt is altered after signing — rows, result digest, approval binding, step ID, or use digest — to misrepresent what was executed or how much data was returned; or a receipt is minted from publicly visible digests without a real authenticated consumption. **Mitigation.** `issueAgentExecutionReceipt` signs the canonical union of evidence and the plan/policy/bindings/approval digests; the receipt digest is recomputed on verification and the receipt signer identity must match the verifier. `verifyAgentExecutionReceipt` deterministically repeats every issuance check (budget, binding, consumption authentication via the host `verify` callback, approval signature, digest equality) and rejects any modified field. Receipts are append-only evidence: nothing in the SDK mutates or re-issues one. **Tests.** - `test/agent-safety.test.ts` — "rejects over-budget evidence before receipt signing and detects receipt tampering" - `test/agent-safety.test.ts` — "cannot issue a receipt from public digests without host-authenticated consumption evidence" - `test/agent-safety-evidence.test.ts` — "fails closed on plan, discovery, capability, and receipt substitution" ### 5. Plan-fingerprint mismatch **Threat.** The operation a host is about to execute quietly differs from what the reviewer approved: same step ID and tool but a substituted query-plan body, different fields, a different source, or drifted parameters — including a "fingerprint-consistent" forgery where the attacker recomputes content hashes over altered content. **Mitigation.** Every plan step carries `queryPlan.fingerprint` (from `@honua/sdk-js/query-planner`), a canonical `parametersDigest`, and an `inputDigest` recomputed from the visible tool/effect/source/query-plan/fields identity — the claims cannot disagree at parse time. At authorization, `digestAgentOperationInput` recomputes the digest from the *proposed* operation and requires exact equality with the approved step's digest before the replay store is consumed; any divergence (id, fingerprint, fields, parameters) fails `integrity-failed`. The same binding is revalidated when receipts are issued and verified. In the NL layer, plan execution additionally re-derives effects and tool identity from plan content, so recomputed-fingerprint forgeries are rejected there too. **Tests.** - `test/agent-safety.test.ts` — "rejects an operation whose query-plan fingerprint differs from the approved step" - `test/agent-safety.test.ts` — "binds exact operation input and atomically consumes each approved step once" (query-plan id divergence arm) - `test/nl-map-control.test.ts` — "rejects a fingerprint-consistent plan whose executed call differs from its declared tool" / "…that launders action effects as read-only" / "…whose step names an unknown tool" ## Adjacent hardening (context, not primary threats) - **Context drift** — approvals are re-verified against the *current* source bindings (schema/source versions, data mode, provenance freshness); drift fails `context-mismatch` ("rejects forged dry runs, signature tampering, expiry, and context drift", "rechecks provenance freshness at the execution clock"). - **Secret exfiltration through tool results** — the `/agent-tools` executor deeply redacts credential-bearing metadata before results reach a model (`test/agent-tools.test.ts`), and audit events carry pseudonymous digests only (`test/agent-execution.test.ts` — "persists only digests for every free-text plan and source identity"). - **Hostile host-callback shapes** — accessors on executors, stores, and callbacks are rejected without invocation (`test/agent-execution.test.ts`). ## What this model does not cover The SDK does not manage signing keys, persist the replay store or audit log, authenticate approvers, or constrain what a *host-authorized* executor does with data it legitimately received. Prompt-injection resistance of any LLM driving the surface is out of scope here; the mitigation posture is that a compromised model can only propose plans, and every effect still requires a signed, budgeted, single-use, context-checked approval. --- # File: docs/nl-map-control.md # Natural-language map control (`@honua/sdk-js/nl-map-control`) > **Experimental.** Symbols on this subpath are `@experimental` and may change > in any minor release before `1.0.0`. `@honua/sdk-js/nl-map-control` turns a natural-language instruction into a typed, serializable, inspectable plan over the existing [`agent-tools`](../src/agent-tools/index.ts) surface, and executes only reviewed plans. It composes three things the SDK already ships: - **agent-tools** — the ten bounded JSON-Schema map/runtime tools (`inspectMap`, `listSources`, `setViewport`, `addLayer`, `setFilter`, `selectFeature`, `runWidgetQuery`, `explainCapabilityGap`, …), - **query-planner** — the canonical query IR that data operations are expressed in, and - **agent-safety** — signed approval envelopes, effect budgets, and receipts. There is intentionally **no opaque NL execution path**: per the [north-star ADR](./decisions/north-star-sdk-application-kernel.md), an agent prompt must compile to the same typed, inspectable plan that human-authored code uses. ## Safety model 1. **Plan-first.** `propose(instruction)` returns a serializable `NlMapPlan` — ordered agent-tool invocations for map operations, with query-planner IR attached to data operations — and never executes anything. The plan is content-addressed: `fingerprint` is the SHA-256 of its canonical JSON, and `execute()` recomputes it, so a plan edited after review is rejected (`plan-invalid`). 2. **Plans only.** `execute()` is the single execution path and accepts plans only. Passing raw natural language (or anything that is not a `honua.nl-map-plan`) throws a typed `plan-required` error. 3. **Policy-gated read auto-execution.** A plan whose every step is `read` may auto-execute when `policy.autoExecuteReadOnly` allows it (the default). Set it to `false` to require approval for everything. 4. **Envelopes for effects.** Any plan containing a `viewport` or `mutation` step requires a signed agent-safety approval envelope. The envelope is a real `agent-safety` approval: the plan is deterministically projected into an `AgentPlanV1`, dry-run against a policy, signed by a host-owned signer, and verified (signature, expiry, policy, bindings, and per-step parameter digests) before anything runs. An approval issued for one plan does not verify against another. 5. **Receipts.** Every execution — auto or approved — emits an `NlMapPlanReceipt` recording the plan identity, mode, per-step tool status, and outcome. Receipts are content-addressed (`receiptDigest`) and optionally signed with a host-provided `receiptSigner`. 6. **BYO LLM.** The model transport is a caller-provided callback `(request: NlCompletionRequest) => Promise`. The SDK depends on no model-vendor SDK, sends the model only the bounded tool schemas plus the semantic map context, and persists no NL or model output. ## API walkthrough ```ts doc-test=skip reason="requires a live map host and an LLM callback" import { approveNlMapPlan, createNlMapControl, nlMapRuntimeBinding, } from "@honua/sdk-js/nl-map-control"; const nl = createNlMapControl({ // Any HonuaAgentRuntime adapter: a HonuaController, a MapPackage runtime, // or your own object over a MapLibre map. tools: { runtime }, // Bring your own model. Any provider, any transport. llm: async (request) => callMyModel(request), policy: { autoExecuteReadOnly: true, maxSelfCorrections: 2, actor: "app@example" }, approvalVerifier, // host-owned envelope verifier (agent-safety) }); // 1. Compile NL into an inspectable plan. Nothing executes here. const plan = await nl.propose("zoom to downtown and only show open incidents"); console.log(JSON.stringify(plan, null, 2)); // render for human review // 2. Read-only plans can run directly; effectful plans need an envelope. if (plan.readOnly) { const { receipt } = await nl.execute(plan); } else { const approval = await approveNlMapPlan({ plan, actor: "app@example", approver: "operator@example", signer, // host-owned envelope signer bindings: { map: nlMapRuntimeBinding({ observedAt: new Date().toISOString() }), incidents: incidentsSourceBinding, // agent-safety source binding }, issuedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 300_000).toISOString(), }); const { receipt } = await nl.execute(plan, { approval }); console.log(receipt.outcome, receipt.approvalDigest); } ``` ### The completion contract `NlCompletionRequest` carries everything a provider adapter needs: the `system` prompt (semantic map context from agent-tools), the user `messages`, and the tool schemas in provider-neutral MCP-compatible shape (`{ name, description, inputSchema }`). Adapters map those onto their provider's native function-calling API and return `{ toolCalls: [{ name, arguments }] }` — `arguments` may be a parsed object or a raw JSON string. A provider refusal is returned as `{ refusal }` and surfaces as a typed `refusal` error. ### Self-correction When a completion fails validation — an unknown tool, arguments that fail the JSON schema, an invalid canonical query, or a **capability miss** — the layer sends a structured retry (`purpose: "self-correct"`) containing the previous tool calls and typed `issues`. Capability misses embed the full `explainCapabilityGap` output (supported flag, declared capabilities, and a suggested action) so the model can re-plan against a source that actually supports the operation. Retries are bounded (`maxSelfCorrections`, default 2); exhaustion throws `retries-exhausted` carrying the final issues. ### Deterministic replay `createRecordedNlLlm(exchanges)` replays committed request/response fixtures in order and fails loudly on drift. The SDK's own test lane (`test/nl-map-control.test.ts` + `test/fixtures/nl-map-control/`) replays recorded completions to byte-identical plans, effects, and receipts against a mock runtime host; the gallery demo (`npm run demo:nl-map-control`) uses the same fixtures so it is deterministic with no API key. ## The MCP path The NL layer's tool surface is published through the same agent-tools exporters used by `@honua/mcp-server`, so the capability works in-app and over the Model Context Protocol: ```ts doc-test=skip reason="illustrative tool publication snippet" import { toNlMapControlMcpToolDefinitions, toNlMapControlOpenAiToolDefinitions, } from "@honua/sdk-js/nl-map-control"; // proposeMapPlan + executeMapPlan + the ten agent tools const mcpTools = toNlMapControlMcpToolDefinitions(); const openAiTools = toNlMapControlOpenAiToolDefinitions(); ``` `proposeMapPlan` is a read tool (planning only); `executeMapPlan` is an action tool that requires opt-in and accepts a serialized plan plus an optional approval bundle — the same plan-only, envelope-gated contract as the in-app API. MCP servers hosting these tools keep the identical safety semantics because they delegate to `createNlMapControl`. ## Errors All failures are typed `HonuaNlMapControlError`s with a `code`: | Code | Meaning | |------|---------| | `refusal` | The model declined the instruction. Not retried. | | `retries-exhausted` | No valid plan within the self-correction budget; `issues` carries the typed reasons (including `explainCapabilityGap` output). | | `plan-required` | `execute()` received something other than a proposed plan (for example raw NL). | | `plan-invalid` | Plan content does not match its fingerprint, or is structurally invalid. | | `approval-required` | The plan has `viewport`/`mutation` effects and no envelope was supplied (or read auto-execution is disabled). | | `approval-invalid` | Envelope verification failed, or the envelope does not bind to this plan. | | `fixture-mismatch` | A recorded-replay LLM saw a request that drifted from the recording. | | `invalid-options` | Missing runtime, LLM callback, or source binding. | Approval issuance itself uses `agent-safety` and throws `HonuaAgentSafetyError` (for example `policy-denied` when the policy forbids the plan's effects). ## See also - [`docs/agent-safety.md`](./agent-safety.md) — the envelope, budget, audit, and receipt contracts this layer builds on. - [`docs/agent-safety-threat-model.md`](./agent-safety-threat-model.md) — the threat model for the (stable) `agent-tools`/`agent-safety` surface underneath this layer: envelope forgery, replay, effect-budget bypass, receipt tampering, and plan-fingerprint mismatch, each with its conformance test. - [`examples/nl-map-control/`](../examples/nl-map-control/) — deterministic MapLibre demo with a fixture LLM, plan/receipt JSON panes, and an approve button. - [North-star ADR](./decisions/north-star-sdk-application-kernel.md) — why NL must compile to the same plan human code uses. --- # File: docs/decisions/north-star-sdk-application-kernel.md # North-star SDK application-kernel contract Status: **accepted for review** on 2026-07-10 for [`honua-sdk-js#386`](https://github.com/honua-io/honua-sdk-js/issues/386). Merging this decision accepts the product boundary and TypeScript direction; it does not claim that the proposed facade is implemented. ## Decision summary Honua will be a **universal geospatial application kernel**, not a proprietary renderer and not an application shell: > Connect to a spatial source, understand it automatically, explain and execute > the best available plan, render it through an interchangeable engine, and > automate the same plan under explicit policy. The small front-door vocabulary is: 1. `createHonua()` creates one resource owner and policy boundary. 2. `honua.connect(locator)` discovers an endpoint or static asset and returns a connection. 3. `connection.inspect()` returns schema, effective capabilities, diagnostics, freshness, and provenance. 4. `connection.explain(query)` returns a serializable execution plan without reading result data. 5. `connection.query(queryOrPlan)` executes either a query or a previously inspected plan. 6. `connection.mount(target, options)` projects the same source/plan and linked state through an optional renderer adapter. 7. Every owned handle has idempotent `dispose()` and `Symbol.asyncDispose`. `Dataset -> Source -> Query -> Result` remains the protocol-neutral semantic contract. The kernel is an orchestration facade over it, not a replacement. Focused subpaths remain the advanced API and escape hatch. ## Product boundary ### The kernel owns - URL and static-asset classification, endpoint-layout discovery, metadata caching, and effective capability negotiation. - Resource ownership, cancellation, diagnostics, provenance, and operation IDs. - A protocol-neutral query intermediate representation, plan selection, and execution receipts. - Renderer adapter lifecycle and renderer-fidelity reporting. - Policy hooks used by people, applications, and agents to execute the same plans. - Stable extension seams for protocol, loader, renderer, auth, cache, realtime, and analysis plugins. ### The kernel does not own - Raster/vector/3D rendering engines. MapLibre, deck.gl, and Cesium remain optional peers maintained by their respective projects. - Application shells, dashboards, widget libraries, Studio, Operator, or hosted-product administration. Those remain in `@honua/app-platform` or product repositories, consistent with the accepted [1.0 scope split](./scope-split-and-1.0.md). - An opaque AI execution path. Agent prompts must compile to the same typed, inspectable plan used by human-authored code. - Silent protocol emulation. Fallback and fidelity loss are plan steps and diagnostics; unsupported operations remain typed failures. - Ownership of sample-gallery prose or a second copy of example code in the website repository. ## Public TypeScript shape This section fixes names, ownership, and behavior. Exact helper overloads can be refined in implementation issues only when they preserve these invariants. The compile-only contract is committed under [`test/design/north-star-api/`](../../test/design/north-star-api/). ### Kernel and connection ```ts doc-test=skip reason="partial excerpt requires application host context" interface HonuaKernel extends AsyncDisposable { readonly diagnostics: DiagnosticChannel; connect>( locator: string | URL | ConnectLocator, options?: ConnectOptions, ): Promise>; dispose(): Promise; } interface HonuaConnection extends AsyncDisposable { readonly id: string; readonly dataset: Dataset; readonly sourceDescriptors: readonly SourceDescriptor[]; readonly diagnostics: DiagnosticChannel; inspect(options?: { refresh?: boolean; signal?: AbortSignal }): Promise; source(id?: SourceId): Source; explain( query: Readonly>, options?: ExplainOptions, ): Promise>; query( queryOrPlan: Readonly> | ExecutionPlan, options?: QueryOptions, ): Promise>; mount( target: string | Element | object, options: MountOptions, ): Promise>; dispose(): Promise; } ``` `createHonua({ plugins })` accepts versioned lightweight plugin descriptors. Static/analytics engines such as GeoParquet/DuckDB are activated by importing a focused plugin factory and injecting its peer module; `connect()` never reaches out to a CDN or loads a heavy engine by surprise. The complete plugin lifecycle and certification metadata are owned by #392. `connect()` completes baseline discovery before resolving. A layer/collection URL has one default source. A service/catalog root may discover many; calling `source()`, `query()`, `explain()`, or `mount()` without a source then throws a typed ambiguity error listing valid source IDs and recovery guidance. It never chooses the first collection silently. `connection.source(id)` returns the existing `Source`. Advanced callers keep `Source.protocol(kind)` for typed raw protocol access. The legacy `Source.adapter()` alias is not promoted into the facade. ### Inspection ```ts doc-test=skip reason="partial excerpt requires application host context" interface ConnectionInspection { readonly id: string; readonly endpoint: string; readonly defaultSourceId?: SourceId; readonly sources: readonly SourceInspection[]; readonly observation: Observation; readonly diagnostics: readonly KernelDiagnostic[]; } interface SourceInspection extends SourceDescriptor { readonly discovery: "metadata" | "declared" | "inferred" | "unavailable"; readonly title?: string; readonly geometryType?: string; readonly crs?: string; readonly observation: Observation; } ``` The snapshot is immutable. `inspect()` uses the metadata snapshot established by `connect()`; `{ refresh: true }` conditionally revalidates it. Discovery failure is explicit (`discovery: "unavailable"` plus a diagnostic), not fabricated protocol defaults presented as observed server truth. ### Explain and query An execution plan includes: - a stable ID and deterministic fingerprint; - connection/source identity and the canonical query; - ordered remote, worker, renderer, or client steps; - pushdown degree and reason for each step; - expected requests, rows, and bytes where estimable; - cache decision and freshness policy; - required authorization scopes; - exact/equivalent/approximate/unsupported fidelity; - provenance, expiry, and structured diagnostics. `explain()` may refresh metadata under the caller's freshness policy but must not fetch result rows or mutate application/renderer state. `query(plan)` executes the reviewed plan only when its fingerprint, source version, policy, and validity window still match. Otherwise it throws `plan-stale` with a replacement plan; it does not silently re-plan. Feature output is additive to today's result contract: ```ts doc-test=skip reason="partial excerpt requires application host context" type FeatureQueryResult = Result & { readonly format: "features"; readonly execution: ExecutionReceipt; }; ``` Columnar output is a distinct result so a million-row path does not materialize JavaScript feature objects: ```ts doc-test=skip reason="partial excerpt requires application host context" interface ColumnarQueryResult { readonly format: "columnar"; readonly schema: readonly { name: string; type: string }[]; readonly batches: AsyncIterable>; readonly execution: ExecutionReceipt; } ``` Cancellation is end-to-end. Aborting a query stops page fetches, worker work, and renderer ingestion. A partial stream carries a terminal diagnostic and is never represented as a complete `Result`. ### Mount and renderer escape hatches ```ts doc-test=skip reason="partial excerpt requires application host context" type BuiltInRendererKind = "maplibre" | "deckgl" | "cesium"; type RendererKind = BuiltInRendererKind | (string & {}); interface RendererAdapter { readonly kind: TKind; readonly environments: readonly ("browser" | "node" | "worker")[]; readonly peer: unknown; // caller-injected module; never a core import } interface MountedMap extends AsyncDisposable { readonly id: string; readonly renderer: TKind; readonly ready: Promise; readonly diagnostics: DiagnosticChannel; raw(kind: TKind): TRaw | undefined; dispose(): Promise; } ``` The three built-in identifiers are convenience literals, not a closed renderer vocabulary. A third-party renderer declares a stable namespaced identifier in its plugin manifest, registers it explicitly, and receives the same typed raw handle through the generic adapter. Registration rejects unknown or API-incompatible adapters with structured diagnostics; core never infers a renderer merely from an arbitrary string. Certification is independent evidence, not a hard-coded runtime allowlist. The kit in #392 must prove this seam with an external-style renderer that is not imported by SDK core. `mount()` resolves after the adapter accepts the source/layer plan. `ready` resolves after the first usable frame and rejects with render diagnostics. Automatic styles are deterministic schema/geometry projections and include a fidelity report; `"auto"` is never a remote generative call. When passed a selector or element, the SDK owns the renderer it creates. When passed an existing renderer host, it borrows the host by default and removes only Honua-owned sources, layers, listeners, workers, and requests. `raw(kind)` is the renderer-specific escape hatch; renderer methods do not leak into the kernel contract. MapLibre adapter construction lives under `@honua/sdk-js/runtime`; deck.gl and Cesium adapters may use focused subpaths decided by their implementation issues. Importing `@honua/sdk-js` must not load any renderer, DuckDB, Arrow, Cesium, or model-provider code. ### Diagnostics, freshness, and provenance Diagnostics use one channel at kernel, connection, execution, and mounted-map scope. `snapshot()` supports post-failure inspection; `subscribe()` supports live developer tooling. Every diagnostic has an ID, stage, severity, operation ID, optional source ID, remediation, and preserved cause. ```ts doc-test=skip reason="partial excerpt requires application host context" interface Observation { readonly state: "live" | "cached" | "replayed" | "pending-local"; readonly observedAt: string; readonly validAt?: string; readonly expiresAt?: string; readonly cursor?: string; readonly provenance: readonly ProvenanceRecord[]; } ``` - `live`: read from the addressed service during this operation. - `cached`: served from a cache and accompanied by observation/expiry time. - `replayed`: deterministic fixture, offline log, or resumed cursor replay. - `pending-local`: an optimistic local edit not yet accepted upstream. Signed URLs and credentials never appear in provenance or diagnostics. The canonical source URL drops query credentials and records a stable asset ID or origin/path. Receipts distinguish the metadata observation from the result-data observation so fresh metadata cannot make replayed rows appear live. ### Agent proposal contract Agent planning stays in `@honua/sdk-js/agent-tools` and requires a caller-owned model/provider. No provider SDK enters the root bundle. ```ts doc-test=skip reason="partial excerpt requires application host context" const proposal = await agent.propose(instruction, { connections: [incidents], policy: { allow: ["data:read", "map:write"], deny: ["data:write", "publish"] }, }); const preview = await proposal.dryRun(); const grant = preview.allowed ? await host.requestApproval(proposal.approval) : undefined; if (grant) await proposal.execute({ approval: grant }); ``` `dryRun()` performs validation and estimates but no data or renderer mutation. Every agent-generated execution requires a host-issued, opaque approval grant bound to the proposal ID and plan fingerprint. A changed plan invalidates the grant. Read-only is the default policy; data edits and publish are denied unless independently granted. Every attempt, denial, execution, and compensating action emits an audit diagnostic and execution receipt. ## Lifecycle and ownership ```mermaid stateDiagram-v2 [*] --> Kernel: createHonua Kernel --> Discovering: connect(locator) Discovering --> Connected: metadata + capability snapshot Discovering --> Kernel: typed connect failure Connected --> Connected: inspect / explain Connected --> Executing: query(query or reviewed plan) Executing --> Connected: result + receipt Connected --> Mounted: mount(adapter) Mounted --> Connected: mountedMap.dispose() Connected --> Disposed: connection.dispose() Kernel --> Disposed: kernel.dispose() cascades Disposed --> [*] ``` Disposal rules: - Every `dispose()` is idempotent and awaits in-flight cancellation/worker shutdown. - `MountedMap.dispose()` disposes its owned renderer session, not the connection or borrowed host. - `HonuaConnection.dispose()` aborts its executions and disposes mounted maps, metadata watches, loader workers, and source-local caches it owns. - `HonuaKernel.dispose()` disposes all connections and kernel-owned auth/cache resources. Caller-supplied providers and renderer hosts remain caller-owned. - Any operation after disposal throws the existing typed `disposed` pattern. ## Dependency direction ```mermaid flowchart TD Apps[Applications / @honua/react / app-platform] --> Kernel[Small kernel facade] Agents[@honua/sdk-js/agent-tools] --> Planner[Query IR + execution planner] Kernel --> Planner Kernel --> Contract[Dataset / Source / Query / Result] Planner --> Contract Contract --> Protocols[First-party protocol adapters] Kernel --> RenderContract[Renderer adapter contract] MapLibre[MapLibre adapter] --> RenderContract Deck[deck.gl adapter] --> RenderContract Cesium[Cesium adapter] --> RenderContract MapLibre -. optional peer .-> MLPeer[maplibre-gl] Deck -. optional peer .-> DeckPeer[deck.gl / Arrow] Cesium -. optional peer .-> CesiumPeer[cesium] Plugins[Certified third-party plugins] --> Contract Plugins --> RenderContract ``` The arrows are dependencies. Core never points to React, app-platform, renderer peers, DuckDB, or model providers. A renderer adapter may depend on the kernel contract; the kernel refers only to the adapter interface. ## Golden workflows The authoritative compile fixtures are: 1. [`public-url-to-map.ts`](../../test/design/north-star-api/public-url-to-map.ts) 2. [`large-data-linked-analysis.ts`](../../test/design/north-star-api/large-data-linked-analysis.ts) 3. [`safe-agent-proposal.ts`](../../test/design/north-star-api/safe-agent-proposal.ts) 4. [`third-party-renderer.ts`](../../test/design/north-star-api/third-party-renderer.ts) They are checked by `npm run verify:north-star-api`. They import a design-only contract under `test/design`; no production API was added for this ADR. ### 1. Public URL to useful map This is the normative basic workflow: nine application lines including imports, inspection, first-frame readiness, and cleanup; no key or Honua account. ```ts doc-test=skip reason="normative future API; compile fixture lives under test/design" import maplibregl from "maplibre-gl"; import { createHonua } from "@honua/sdk-js"; import { maplibreRenderer } from "@honua/sdk-js/runtime"; const honua = createHonua(); const data = await honua.connect(PUBLIC_FEATURE_LAYER_URL); const info = await data.inspect(); const map = await data.mount("#map", { renderer: maplibreRenderer(maplibregl), style: "auto" }); await map.ready; await honua.dispose(); ``` ### 2. Large-data linked analysis The workflow connects an AWS-hosted GeoParquet/PMTiles asset, requests columnar or tiled display execution, reuses the stable `ExplorationContext` for map, table, chart, filter, and selection state, and pushes an aggregate summary to DuckDB or the remote service. The plan must prove that the display path does not materialize unbounded feature objects. `deck.gl` and DuckDB are injected optional peers. A viewport/filter change creates a new fingerprinted plan; it does not mutate the reviewed plan in place. ### 3. Safe agent-proposed plan The workflow connects the deployed `demo.honua.io` feature surface, compiles a prompt into the same execution-plan type, dry-runs it, requests approval, and executes only with a plan-bound grant. The fixture proves at compile time that `proposal.execute()` cannot be called without an `ApprovalGrant`. ### DX review | Workflow | Application lines / introduced concepts | Required configuration | Cleanup contract | | --- | --- | --- | --- | | Public URL -> map | 9 lines including imports; kernel, connection, renderer adapter, mounted handle | Public URL only; no account/key | One awaited `honua.dispose()` cascades connection and owned map | | Large-data linked analysis | 1 connection, 2 reviewed plans, 1 existing exploration context, 2 optional peer factories | AWS asset locator supplied by public config or runner; never an embedded signed URL | Kernel disposes worker/connection/map; caller disposes its exploration context | | Safe agent proposal | 1 connection, proposal, dry run, approval grant, receipt | Caller-owned model provider and host approval callback | Kernel disposal plus provider lifecycle retained by caller | Only the first workflow is constrained to ten application lines. Advanced workflows deliberately expose plans, peers, and ownership rather than hiding cost or authority behind defaults. ## Deterministic and live validation lanes Each golden workflow has two evidence lanes; neither substitutes for the other. | Lane | Trigger | Inputs | Required evidence | | --- | --- | --- | --- | | Deterministic | Every pull request, offline | Committed metadata/result/columnar fixtures and a deterministic agent provider | Typecheck, semantic assertions, recorded provenance sidecar, replayed freshness state, disposal/leak assertions | | Public live | Scheduled and manual | Public AWS assets, public endpoints, and deployed `https://demo.honua.io` | Discovery/query/render or headless-plan success, live provenance/freshness, latency/bytes, explicit endpoint/version report | | Authenticated live | Scheduled/manual when configured | Private AWS objects or protected demo capabilities | GitHub OIDC or repository secrets supplied only to the runner; explicit executed/credential-unavailable status; no silent green skip | Credential rules: - Example source, HTML, browser bundles, fixture metadata, logs, diagnostics, snapshots, and PR artifacts contain no secret, bearer token, access key, signed-URL query, or credential-bearing source URL. - Prefer public read-only AWS sample assets. Authenticated AWS CI uses short-lived OIDC credentials and resolves private locators inside the runner. - Browser examples never receive CI secrets through `VITE_*` variables. - Fixture refresh is a reviewed script that strips credentials, records source identity/version/retrieval time/license, and produces a deterministic digest. - A live-lane result reports `executed`, `failed`, or `credential-unavailable`; missing credentials do not masquerade as execution. The SDK repository owns executable samples and tests. Each flagship example will expose a small, versioned catalog manifest containing slug, title, capabilities, protocols, renderer, fixture command, live command, screenshot, and provenance metadata. The `honua-site` samples directory/gallery consumes a generated projection of that manifest and links to or embeds the deployed SDK artifact. It must not fork `src/`, mock servers, fixtures, or workflow logic. Changes flow SDK example -> validated catalog artifact -> site projection. The site may own narrative/marketing copy and ordering, but not a second executable implementation. The current sample inventory is evidence, not a preservation constraint. The program optimizes for compelling task journeys, time to first success, and clear proof of differentiated capability. During curation, each current sample receives an explicit **keep, rework, merge, replace, or retire** disposition; legacy URLs get redirects where appropriate, but weak examples are not retained solely to avoid change. SDK-side execution is tracked by #398 (modernization epic), #399 (flagship migrations), #400 (generated learning/docs), and #401 (versioned manifest/artifact/evidence contract). The site-side catalog projection is [honua-site#120](https://github.com/honua-io/honua-site/issues/120) and the task-journey experience redesign is [honua-site#121](https://github.com/honua-io/honua-site/issues/121). This decision PR intentionally does not edit `honua-site`. ## Environment and distribution compatibility | Environment | Supported kernel operations | Constraints | | --- | --- | --- | | Node 20+ | `connect`, `inspect`, `explain`, `query`, streaming, agent planning | No DOM `mount`; a headless adapter must explicitly advertise Node support. Browser auth stores are unavailable. | | Browser ESM/bundler | All operations | Renderer/analytics peers are explicit imports; workers obey CSP and are disposable. | | Web Worker | `connect`, `inspect`, `explain`, `query`, columnar processing | No element/selector mount. `OffscreenCanvas` requires an adapter that advertises worker support. Auth/cache implementations are injected. | | React 18/19 | Same kernel through `HonuaProvider` and hooks | StrictMode cannot duplicate connections/subscriptions; component unmount disposes only resources it owns. | | Build-less ESM | Root/browser kernel plus URL-imported focused adapters | Import maps resolve optional peers; no implicit bare import or dynamic CDN dependency. | The root stays ESM-only, NodeNext-compatible, strict, and side-effect free. Renderer and analytics adapters declare peers and carry their own bundle budgets. `createHonua()` and built-in lightweight discovery must preserve the one-lightweight-runtime-dependency posture established by #357. ## Mapping to the current SDK | North-star concept | Existing symbol(s) | Disposition | | --- | --- | --- | | `createHonua()` | `new HonuaClient()`, `createDataset()` | Add a thin owner/facade after discovery/planner contracts land; retain both low-level APIs. | | `connect()` | `createDataset`, `SourceLocator.layout`, URL parsers, OGC/STAC landing-page discovery, GeoParquet/PMTiles resolvers | Compose and generalize. Do not add another protocol-specific constructor. Tracked by #391. | | `HonuaConnection` | `Dataset` plus owned metadata/worker/runtime handles | New orchestration handle; its `dataset` exposes the existing contract. | | `inspect()` | `SourceDescriptor`, `SourceSchema`, `Capabilities`, `Source.protocol(...).describe()`, metadata cache docs | Normalize into immutable observed metadata; distinguish discovered vs declared defaults. | | `query()` | `Source.query`, `queryAll`, `stream`, `queryAggregate` | Reuse adapter execution. The facade adds plan/receipt/format; direct `Source` calls remain valid. | | `explain()` / `ExecutionPlan` | Per-adapter compilers, `DegradedReason`, query-tile diagnostics | New shared planner contract, not a wrapper around log strings. Tracked by #389. | | Feature results | `Result` | Preserve fields; add mandatory execution receipt only on the facade result. | | Columnar results | GeoParquet/DuckDB runtime and row mapping | Replace row-object default for large paths with batches; tracked by #394. | | `mount()` | `loadMapPackage`, `HonuaMapRuntime`, `HonuaMap`, source bridge | Adapt behind renderer contract; do not add renderer methods to `Dataset`/`Source`. | | MapLibre adapter | `HonuaMapRuntime`, `MaplibreMap`, `loadHonuaFeatureServiceGeoJson` | Productionize automatic source/style projection under #390. | | deck.gl adapter | No stable production adapter | New optional adapter under #388. | | Cesium adapter | App-platform scene adapters and compatibility examples | New stable renderer adapter without moving scene-workspace back into core; #395. | | Linked state | `ExplorationContext`, view controllers, interaction bindings | Reuse unchanged; `mount`/planner accept snapshots and bindings. | | Diagnostics | typed error hierarchy, `Result.degraded`, runtime diagnostics/events, request/runtime telemetry | Unify through a scoped channel while preserving typed errors. | | Freshness/provenance | `SourceFreshnessContract`, cache diagnostics, realtime cursors | Keep declared freshness and add observed state/receipts; #393 and #396 implement storage/stream semantics. | | Agent proposal | `createHonuaAiMapKit`, tool executor, audit events, MCP evals | Reuse tools/audit; add provider-neutral proposal -> plan -> grant flow under #397. | | Plugin | `resolveSource`, declaration-merging adapter map, auth/GeoParquet/PMTiles injection seams | Converge on one versioned plugin lifecycle and certification contract under #392. | | Disposal | `HonuaMapRuntime.dispose`, `ExplorationContext.dispose`, `GeoparquetRuntime.dispose`, React cleanup | Compose under kernel ownership; retain leaf disposal methods. | | React | `HonuaProvider`, `useDataset`, `useQuery`, `HonuaMap` | Evolve bindings to accept kernel/connection; no second cache or planner. | | Raw escape hatch | `Source.protocol()`, runtime `.map`, protocol clients | Keep `Source.protocol`; replace direct runtime leakage in the facade with typed `MountedMap.raw(kind)`. | ## Name collisions and migration rules - `HonuaClient` remains the raw transport/service client. It is not renamed to `HonuaKernel`; `createHonua()` owns one or more clients as discovery requires. - `HonuaMap` remains a programmatic source/layer model. The mounted resource is named `MountedMap`, avoiding a third `HonuaMap` class. - `loadMapPackage()` remains the explicit saved-package path. `mount()` may compile a transient package internally but must not hide hosted-package fetch or validation semantics. - `inspect()` is normalized kernel metadata. Protocol-specific `describe()`, `getCapabilities()`, and layer-metadata calls remain raw escape hatches. - `ExecutionPlan` is distinct from app-platform Operator/Studio plans. The latter may reference an execution-plan fingerprint but do not define SDK execution semantics. - React's `` is a component, while `MountedMap` is its owned/borrowed imperative handle. The component delegates to `mount()`. - No existing stable symbol is deprecated by this ADR. Low-level contracts are essential advanced APIs. Deprecation may begin only after the facade has equivalent conformance and migration documentation. - Expired app-platform shims remain governed by #385; this design does not use them or move app-shell concepts back into the stable package. ## Follow-on contract The implementation issues must reference and preserve this decision: - #391: `connect`, discovery, inspection, and effective capabilities. - #389: query IR, plan fingerprint, explain semantics, and receipts. - #390, #388, #395: MapLibre, deck.gl, and Cesium adapters. - #394: columnar result and worker semantics. - #393 and #396: observed freshness, cursors, persistent caches, and pending local edits. - #397: agent proposal, policy, approval grant, audit, and provenance. - #392: plugin lifecycle and certification. - #385 and #387: stable surface/bundle reconciliation and measurable DX gates. - #398, #399, #400, and #401: compelling flagship journeys, generated learning material, and the SDK-owned sample artifact/evidence projection contract. - [honua-site#120](https://github.com/honua-io/honua-site/issues/120) and [honua-site#121](https://github.com/honua-io/honua-site/issues/121): consume the SDK projection and redesign the samples/docs experience without copying executable implementations. An implementation may extend a focused option type, but changing ownership, silent-fallback rules, plan review semantics, observed-state vocabulary, or dependency direction requires a superseding ADR. ## Consequences Positive: - The common path is materially smaller without hiding the existing powerful contract. - Protocols, renderers, human-authored queries, and agent actions converge on one explainable execution model. - Optional peers and app-platform separation remain enforceable. - Live AWS/demo evidence and deterministic CI prove different failure classes while sharing provenance semantics. Costs: - `connect()` cannot ship honestly until metadata discovery is consistent. - Plans and receipts become versioned public contracts requiring conformance fixtures across every adapter. - Renderer adapters must expose fidelity differences instead of promising impossible parity. - Resource ownership and live-lane evidence add work to every new plugin. ## Acceptance evidence for #386 - Product boundary and API/lifecycle/dependency decisions: this ADR. - Three compile-tested workflows: `test/design/north-star-api/*.ts`. - Current-symbol collision and migration inventory: mapping sections above. - Node/browser/worker/React/build-less and optional-peer rules: compatibility sections above. - No production API: the proposed declarations live only under `test/design`. - Follow-on traceability: issue list above; each implementation ticket receives a link to this accepted-for-review contract. --- # File: docs/geocoding-routing-providers.md # Provider-pluggable geocoding and routing > Status: **experimental** (`@experimental` JSDoc). Shapes may change in any > minor release prior to `1.0.0`. `@honua/sdk-js/geocoding` and `@honua/sdk-js/routing` expose provider-neutral contracts — `GeocodingProvider` (`geocode` / `reverse` / `suggest`) and `RoutingProvider` (`route`) — with first-party adapters for open-source services. No Honua server is required: the Honua facade is just one provider among several, and the same typed calls work against every adapter. Three rules apply to every adapter: 1. **Explicit endpoints only.** Every third-party adapter requires a `baseUrl`. The SDK never bakes in a default third-party endpoint, so you cannot accidentally send production traffic to a community service whose usage policy you have not read. 2. **Declared capabilities.** Capability differences are declared on the provider and enforced by the SDK's existing capability policy: an unsupported operation throws `HonuaCapabilityNotSupportedError` under the default `"strict"` policy (or resolves empty under `"degraded"`). 3. **Attribution travels with results.** Every provider exposes `attribution` / `usagePolicyUrl`, and every result carries a `provenance` object identifying the provider and repeating those obligations, so hosts can render attribution wherever results surface. ## Capability matrix | Provider | geocode | reverse | suggest | route | Notes | |----------|---------|---------|---------|-------|-------| | `honua` (facade) | ✓ | ✓ | ✓ | ✓ | Wraps `HonuaGeocodingClient` / the esri-compat route solver | | `nominatim` | ✓ | ✓ | — (throws typed error) | | No typeahead endpoint; the OSMF policy forbids autocomplete traffic | | `photon` | ✓ | ✓ | ✓ | | Typeahead-first engine | | `pelias` | ✓ | ✓ | ✓ (`/v1/autocomplete`) | | Hosted instances usually need an `apiKey` | | `osrm` | | | | ✓ | OSRM HTTP API v1, GeoJSON geometry | | `valhalla` | | | | ✓ | 1e-6 encoded polylines, decoded for you | ## Geocoding ### Nominatim (geocode + reverse; no suggest) ```ts doc-test=compile import { nominatimGeocodingProvider } from "@honua/sdk-js/geocoding"; const geocoder = nominatimGeocodingProvider({ baseUrl: "https://nominatim.example.org", // your instance userAgent: "my-app/1.0 (ops@example.org)", // REQUIRED by the OSMF policy on the public instance email: "ops@example.org", // public-instance etiquette }); const [best] = await geocoder.geocode("530 South King Street, Honolulu", { limit: 1 }); console.log(best.latitude, best.longitude, best.provenance.attribution); const here = await geocoder.reverse(21.3059, -157.858); // latitude first ``` Capability miss, by declaration rather than by surprise: ```ts doc-test=skip reason="partial excerpt requires application host context" import { HonuaCapabilityNotSupportedError } from "@honua/sdk-js"; try { await geocoder.suggest("honol"); } catch (error) { if (error instanceof HonuaCapabilityNotSupportedError) { // error.capability === "suggest", error.protocol === "nominatim" } } // Or opt into degraded mode: suggest() resolves to [] instead of throwing. nominatimGeocodingProvider({ baseUrl, capabilityPolicy: "degraded" }); ``` **Usage policy** (public `nominatim.openstreetmap.org`): absolute maximum of 1 request/second, a real `User-Agent` identifying your application, no autocomplete traffic, and results must credit OpenStreetMap. Read before pointing at the public instance; self-host for anything heavier. **Attribution**: `Data © OpenStreetMap contributors, ODbL 1.0`. ### Photon (geocode + reverse + suggest) ```ts doc-test=compile import { photonGeocodingProvider } from "@honua/sdk-js/geocoding"; const photon = photonGeocodingProvider({ baseUrl: "https://photon.example.org" }); const hints = await photon.suggest("honol", { limit: 5 }); // typeahead-first engine ``` **Usage policy**: the komoot-operated `photon.komoot.io` is fair-use for moderate volumes (see ); self-host for production. **Attribution**: OpenStreetMap (ODbL), as above. ### Pelias (geocode + reverse + suggest via autocomplete) ```ts doc-test=compile import { peliasGeocodingProvider } from "@honua/sdk-js/geocoding"; const pelias = peliasGeocodingProvider({ baseUrl: "https://pelias.example.org", apiKey: process.env.PELIAS_API_KEY, // hosted instances (e.g. geocode.earth) attribution: "© OpenStreetMap contributors; © OpenAddresses; Who's On First", }); const hints = await pelias.suggest("honol"); // dedicated /v1/autocomplete endpoint ``` **Usage policy / attribution**: depends on the datasets your instance is built from (OSM, OpenAddresses, Who's On First, geonames, …) and on your hosting provider's terms. Override `attribution` / `usagePolicyUrl` to match; see . ### Honua facade ```ts doc-test=compile import { HonuaGeocodingClient, honuaGeocodingProvider } from "@honua/sdk-js/geocoding"; const client = new HonuaGeocodingClient({ baseUrl: "https://your-honua-server.example" }); const provider = honuaGeocodingProvider(client); // geocode + reverse + suggest ``` Existing `HonuaGeocodingClient` code keeps working unchanged; the provider wrapper exists so provider-neutral hosts (search UIs, the CLI, agents) can treat Honua like any other provider. ## Routing ### OSRM ```ts doc-test=compile import { osrmRoutingProvider } from "@honua/sdk-js/routing"; const router = osrmRoutingProvider({ baseUrl: "https://osrm.example.org", profile: "driving", // or "foot", "bicycle", … as exposed by your instance }); const route = await router.route([ { longitude: -157.858, latitude: 21.306 }, { longitude: -157.802, latitude: 21.262 }, ]); // route.geometry: [lon, lat][] route.distanceMeters route.durationSeconds route.legs ``` **Usage policy**: the public demo (`router.project-osrm.org`) and the FOSSGIS instances (`routing.openstreetmap.de`) are for light, non-commercial use — see . Self-host for production. **Attribution**: `Route data © OpenStreetMap contributors, ODbL 1.0`. ### Valhalla ```ts doc-test=compile import { valhallaRoutingProvider } from "@honua/sdk-js/routing"; const router = valhallaRoutingProvider({ baseUrl: "https://valhalla.example.org", costing: "auto", // or "bicycle", "pedestrian", … }); ``` Leg shapes (Valhalla's 1e-6 encoded polylines) are decoded into plain `[longitude, latitude]` geometry for you; `decodePolyline` is exported if you need it directly. **Usage policy**: the FOSSGIS community instance (`valhalla1.openstreetmap.de`) expects fair use; self-host for production. **Attribution**: OpenStreetMap (ODbL), as above. ### Honua facade + esri-compat bridge ```ts doc-test=skip reason="partial excerpt requires application host context" import { honuaRoutingProvider, osrmRoutingProvider, routingProviderToCompatRouteProvider, } from "@honua/sdk-js/routing"; import { RouteTaskCompat } from "@honua/sdk-js/esri-compat"; // Wrap the existing Honua facade solver (the esri-compat routeProvider shape) // in the provider contract: const honua = honuaRoutingProvider(myExistingRouteSolver); // Or drive esri-compat widgets (RouteTaskCompat / RouteLayerCompat / // DirectionsCompat) with any RoutingProvider: const task = new RouteTaskCompat({ routeProvider: routingProviderToCompatRouteProvider( osrmRoutingProvider({ baseUrl: "https://osrm.example.org" }), ), }); ``` ## CLI ```bash # Default behavior (Honua locator) is unchanged: honua geocode "530 South King Street" --limit 3 # Third-party provider — endpoint is always explicit: honua geocode --provider nominatim --base-url https://nominatim.example.org "530 South King Street" honua geocode --provider photon --base-url https://photon.example.org "Honolulu" --json honua geocode --provider pelias --base-url https://pelias.example.org --api-key $PELIAS_KEY "Honolulu" # Nominatim public-instance policy compliance: honua geocode --provider nominatim --base-url https://nominatim.openstreetmap.org \ --user-agent "my-app/1.0 (ops@example.org)" "Honolulu Hale" ``` Table output prints the provider's attribution and usage-policy URL after the results; `--json` emits the normalized results with `provenance` stamped on each row. ## Caching and rate limits Suggest paths should debounce in the UI (see the typeahead example in the `/geocoding` package docs). The SDK deliberately does **not** persist provider results: most community usage policies (Nominatim in particular) prohibit systematic caching/bulk harvesting, and provenance is recorded per result so downstream stores can honor per-provider terms. ## Testing Unit tests run against recorded fixtures (`test/fixtures/providers/`) and never touch the network. The live smoke lane (`test/provider-live-smoke.test.ts`) is opt-in via `HONUA_PROVIDER_LIVE_SMOKE=1`, sends exactly one request per test, and sets a real `User-Agent` for Nominatim. --- # File: docs/protocol-capability-matrix.md # Protocol × Capability Matrix Status: generated from [`config/support-manifest.v1.json`](../config/support-manifest.v1.json); do not edit this section by hand. Native (`✓`) claims mirror the default capability set per protocol; per-source metadata may narrow them at runtime. Client-fallback (`◐`) claims are explicit opt-in paths and are not protocol defaults. An absent operation is explicitly `unsupported`; capability misses throw `HonuaCapabilityNotSupportedError` rather than returning empty data. - `✓` supported with native execution - `◐` supported through an explicit client fallback - `β` beta - `◇` experimental - `†` deprecated - `F` facade-required - `—` unsupported | Capability | gRPC | GS Feature | GS Map | GS Image | GS Geometry | GS GP | OGC Features | OGC Tiles | OGC Maps | OGC Records | STAC | WFS | WMS | WMTS | OData | PMTiles | GeoParquet | MapLibre vector | MapLibre raster | MapLibre GeoJSON | | --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: | | `query` | ✓ | ✓ | ✓ | ✓ | — | — | ✓ | — | — | ✓ | ✓ | ✓ | ✓ | — | ✓ | — | ◇ | — | — | — | | `queryAggregate` | ✓ | ✓ | ✓ | — | — | — | ◐ | — | — | — | — | — | — | — | — | — | ◇ | — | — | — | | `spatialAggregate` | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | | `queryExtent` | ✓ | ✓ | ✓ | ✓ | — | — | ◐ | — | — | — | — | ✓ | — | — | — | — | — | — | — | — | | `queryObjectIds` | ✓ | ✓ | ✓ | ✓ | — | — | ✓ | — | — | ✓ | ✓ | ✓ | — | — | ✓ | — | — | — | — | — | | `queryRelated` | — | ✓ | ✓ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | | `applyEdits` | ✓ | ✓ | — | — | — | — | ✓ | — | — | — | — | ✓ | — | — | ✓ | — | — | — | — | — | | `attachments` | — | ✓ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | | `render` | — | — | ✓ | ✓ | — | — | — | ✓ | ✓ | — | — | — | ✓ | ✓ | — | — | — | ✓ | ✓ | — | | `tiles` | — | ◐ | ✓ | ✓ | — | — | — | ✓ | — | — | — | — | ✓ | ✓ | — | ✓ | — | ✓ | ✓ | — | | `sql` | — | ✓ | ✓ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | | `stream` | ✓ | ✓ | ✓ | — | — | — | ✓ | — | — | ✓ | ✓ | ✓ | — | — | ✓ | — | ◇ | — | — | — | | `pbf` | — | ✓ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | | `image` | — | — | — | ✓ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | | `geometry` | — | — | — | — | ✓ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | | `geoprocess` | — | — | — | — | — | ✓ | — | — | — | — | — | — | — | — | — | — | — | — | — | — | | `processes` | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | ### Generated claim evidence Every non-unsupported operation claim maps to executable evidence and a freshness policy in the manifest. | Protocol | Operations | Status | Environment | Execution mode | Evidence | | --- | --- | --- | --- | --- | --- | | `grpc` | `query`, `queryAggregate`, `queryExtent`, `queryObjectIds`, `applyEdits`, `stream` | `supported` | `honua-facade` | `native` | [fixture: contract-conformance](../test/contract/conformance.test.ts)
[conformance: grpc-conformance](../test/conformance/feature-service.conformance.ts) | | `geoservices-feature-service` | `query`, `queryAggregate`, `queryExtent` | `supported` | `protocol-adapter` | `native` | [fixture: contract-conformance](../test/contract/conformance.test.ts) | | `geoservices-feature-service` | `queryObjectIds`, `queryRelated`, `applyEdits`, `attachments` | `supported` | `protocol-adapter` | `native` | [fixture: geoservices-conformance](../test/contract/geoservices-conformance.test.ts) | | `geoservices-feature-service` | `sql` | `supported` | `protocol-adapter` | `native` | [fixture: core-client-fixtures](../test/core-client.test.ts) | | `geoservices-feature-service` | `stream` | `supported` | `protocol-adapter` | `native` | [fixture: contract-conformance](../test/contract/conformance.test.ts)
[fixture: honua-surface-fixtures](../test/honua-surface.test.ts) | | `geoservices-feature-service` | `pbf` | `supported` | `protocol-adapter` | `native` | [fixture: core-client-fixtures](../test/core-client.test.ts) | | `geoservices-feature-service` | `tiles` | `supported` | `protocol-adapter` | `client-fallback` | [fixture: query-tiles-fixtures](../test/contract/query-tiles.test.ts) | | `geoservices-map-service` | `query`, `queryAggregate`, `queryExtent` | `supported` | `protocol-adapter` | `native` | [fixture: contract-conformance](../test/contract/conformance.test.ts)
[fixture: honua-surface-fixtures](../test/honua-surface.test.ts) | | `geoservices-map-service` | `queryObjectIds`, `queryRelated` | `supported` | `protocol-adapter` | `native` | [fixture: geoservices-conformance](../test/contract/geoservices-conformance.test.ts)
[fixture: honua-surface-fixtures](../test/honua-surface.test.ts) | | `geoservices-map-service` | `render` | `supported` | `protocol-adapter` | `native` | [fixture: honua-surface-fixtures](../test/honua-surface.test.ts) | | `geoservices-map-service` | `tiles` | `supported` | `protocol-adapter` | `native` | [fixture: connect-fixtures](../test/connect.test.ts)
[fixture: tile-layer-fixtures](../test/tile-layer-compat.test.ts) | | `geoservices-map-service` | `sql` | `supported` | `protocol-adapter` | `native` | [fixture: honua-surface-fixtures](../test/honua-surface.test.ts) | | `geoservices-map-service` | `stream` | `supported` | `protocol-adapter` | `native` | [fixture: contract-conformance](../test/contract/conformance.test.ts)
[fixture: honua-surface-fixtures](../test/honua-surface.test.ts) | | `geoservices-image-service` | `query`, `queryExtent`, `queryObjectIds` | `supported` | `protocol-adapter` | `native` | [fixture: geoservices-conformance](../test/contract/geoservices-conformance.test.ts) | | `geoservices-image-service` | `image`, `render` | `supported` | `protocol-adapter` | `native` | [fixture: geoservices-conformance](../test/contract/geoservices-conformance.test.ts) | | `geoservices-image-service` | `tiles` | `supported` | `protocol-adapter` | `native` | [fixture: geoservices-conformance](../test/contract/geoservices-conformance.test.ts) | | `geoservices-geometry-service` | `geometry` | `supported` | `protocol-adapter` | `native` | [fixture: geoservices-conformance](../test/contract/geoservices-conformance.test.ts) | | `geoservices-gp-service` | `geoprocess` | `supported` | `protocol-adapter` | `native` | [fixture: geoservices-conformance](../test/contract/geoservices-conformance.test.ts)
[fixture: geoprocessing-job-run-fixtures](../test/contract/geoprocessing-job-run.test.ts)
[fixture: process-runner-fixtures](../test/process-runner.test.ts) | | `ogc-features` | `query`, `queryObjectIds`, `applyEdits`, `stream` | `supported` | `protocol-adapter` | `native` | [fixture: ogc-features-fixtures](../test/contract/ogc-features-backend-agnostic.test.ts) | | `ogc-features` | `queryAggregate`, `queryExtent` | `supported` | `protocol-adapter` | `client-fallback` | [fixture: contract-conformance](../test/contract/conformance.test.ts) | | `ogc-tiles` | `render`, `tiles` | `supported` | `protocol-adapter` | `native` | [fixture: ogc-tiles-fixtures](../test/connect-ogc-tiles.test.ts) | | `ogc-maps` | `render` | `supported` | `protocol-adapter` | `native` | [fixture: ogc-maps-fixtures](../test/connect-ogc-maps.test.ts) | | `ogc-records` | `query`, `queryObjectIds`, `stream` | `supported` | `protocol-adapter` | `native` | [fixture: ogc-records-fixtures](../test/connect-ogc.test.ts) | | `stac` | `query`, `queryObjectIds`, `stream` | `supported` | `protocol-adapter` | `native` | [fixture: stac-fixtures](../test/contract/stac-backend-agnostic.test.ts) | | `wfs` | `query`, `queryExtent`, `queryObjectIds`, `applyEdits`, `stream` | `supported` | `protocol-adapter` | `native` | [fixture: wfs-fixtures](../test/contract/wfs-backend-agnostic.test.ts) | | `wms` | `render`, `tiles`, `query` | `supported` | `protocol-adapter` | `native` | [fixture: wms-fixtures](../test/contract/wms.test.ts) | | `wmts` | `render`, `tiles` | `supported` | `protocol-adapter` | `native` | [fixture: wmts-fixtures](../test/contract/wmts.test.ts) | | `odata` | `query`, `queryObjectIds`, `stream`, `applyEdits` | `supported` | `protocol-adapter` | `native` | [fixture: odata-fixtures](../test/contract/odata-backend-agnostic.test.ts) | | `pmtiles` | `tiles` | `supported` | `client-only` | `native` | [fixture: pmtiles-fixtures](../test/pmtiles-contract.test.ts) | | `geoparquet` | `query`, `queryAggregate`, `stream` | `experimental` | `client-only` | `native` | [fixture: geoparquet-fixtures](../test/geoparquet-source.test.ts) | | `maplibre-vector` | `render` | `supported` | `client-only` | `native` | [fixture: maplibre-automatic-source-fixtures](../test/automatic-source-strategy.test.ts)
[integration: maplibre-automatic-browser](../test/playwright/automatic-source-workflow.spec.mjs) | | `maplibre-vector` | `tiles` | `supported` | `client-only` | `native` | [fixture: maplibre-automatic-source-fixtures](../test/automatic-source-strategy.test.ts) | | `maplibre-raster` | `render` | `supported` | `client-only` | `native` | [fixture: maplibre-raster-source-fixtures](../test/raster-source-strategy.test.ts)
[integration: maplibre-automatic-browser](../test/playwright/automatic-source-workflow.spec.mjs) | | `maplibre-raster` | `tiles` | `supported` | `client-only` | `native` | [fixture: maplibre-raster-source-fixtures](../test/raster-source-strategy.test.ts) | MapLibre-native and PMTiles sources are included in the generated table even though they do not flow through the `Source.query` path. GeoParquet is the experimental DuckDB-WASM-backed `Source` from `@honua/sdk-js/geoparquet`; envelope filters push down to `ST_Intersects`, while non-envelope filters reduce to their bounding box and are reported through `Result.degraded`. `maplibre-vector` and `maplibre-raster` are executable descriptor strategies with release-gated renderer coverage. `maplibre-geojson` remains a reserved protocol identifier with no positive default capability: the runtime can load an inline MapLibre `type: "geojson"` source, but the automatic/app descriptor path does not implement that protocol today. `spatialAggregate` is an indexed analytics capability rather than the field-statistics `queryAggregate` path. No protocol receives it by default. A source may advertise it only after backend metadata confirms an indexed aggregation implementation for that source. ## Notes by protocol ### gRPC FeatureService Canonical transport shared across the SDKs and generated from the `geospatial-grpc` FeatureService definitions. The default capability set is `query`, `queryAggregate`, `queryExtent`, `queryObjectIds`, `applyEdits`, and `stream`. In JS, gRPC-Web is selected on `HonuaClient` with `transport: "grpc-web"`; it is not exposed as a `Source.protocol("grpc")` adapter handle. ### GeoServices Feature Service First-class. Aggregations set `outStatistics`, `groupByFieldsForStatistics`, and `returnGeometry=false` as top-level fields on the translated `QueryFeaturesRequest` so both the REST serializer and the gRPC-Web adapter pick them up (they are not stashed in `extraParams`, which the gRPC path would silently drop). Pagination uses `resultOffset` / `resultRecordCount`. Streaming wraps `HonuaFeatureLayer.queryFeaturesStream`; the adapter derives `pageSize` from `Query.pagination.limit` so `source.stream({ pagination: { limit } })` yields pages of at most `limit` rows instead of the core helper's default 2000. `pbf` is supported when the server returns `f=pbf`; the contract accepts both encodings transparently. ### GeoServices Map Service / Map Layer Same query semantics as Feature Service for the layers it exposes (including the root-level aggregation encoding and `pagination.limit` → `pageSize` bridge for `stream()`). `render` and `tiles` come from the service-level export endpoints. `applyEdits` and `attachments` are not supported because the Map Service endpoint is read-only — `Source.applyEdits()` and `Source.attachments.*` throw `HonuaCapabilityNotSupportedError` so a mixed-source app does not silently drop the edits. `Source.queryObjectIds()` and `Source.queryRelated()` round-trip through the same canonical envelopes as the FeatureServer adapter. ### GeoServices Image Service The Image Service adapter wraps Honua Server's ImageServer endpoints (see `feature-server-matrix.md`'s sibling `image-server-matrix.md`). `Source.query()` returns the raster catalog as canonical features (one row per raster, footprint geometry on each). `Source.queryAll()` drains pages from the catalog endpoint internally (`resultOffset` / `resultRecordCount`) and uses a `limit + 1` lookahead row to stamp `exceededTransferLimit: true` when the cap is hit, mirroring the FeatureServer / OGC `queryAll` semantics. `Source.queryExtent()` and `Source.queryObjectIds()` reuse the same catalog endpoint with the standard GeoServices shaping flags (`returnExtentOnly`, `returnIdsOnly`). Tile URLs come from `Source.protocol("geoservices-image-service").tileUrl(level, row, col)`. `exportImage`, `identify`, `legend` live on the same `HonuaImageService` typed escape hatch — these protocol-specific operations are not on the canonical `Source` because their request shapes (mosaic rule, rendering rule, pixel size, raster function chains) are ImageServer-specific. The wrapper accepts both `GET` (params on the query string) and `POST` (form-encoded body) per request; `POST` is the correct mode when payload size or proxy URL limits would truncate a `GET` URL. The catalog endpoint does not honor `Query.spatialFilter`, `Query.orderBy`, or `Query.outFields`, so the adapter rejects those fields explicitly rather than silently widening the result; use `Query.where` to constrain the catalog or move to a FeatureServer source for richer query semantics. `applyEdits`, `attachments`, `queryRelated`, `queryAggregate`, and `stream` are intentionally absent from the default capability set; the canonical methods throw `HonuaCapabilityNotSupportedError` rather than silently no-op. ### GeoServices Geometry Service Geometry Service is a stateless utility — it does not host features — so the canonical query family throws on every method. The default capabilities advertise only `geometry`. Operations (`buffer`, `simplify`, `project`, `intersect`, `union`, `clip`, `difference`) live behind `Source.protocol("geoservices-geometry-service")` on a `HonuaGeometryService` instance whose request shapes match the routes in `honua-server/docs/gis/geometry-service-matrix.md`. The wrapper targets the `EndpointRegistry` prefix `/rest/services/Utilities/Geometry/GeometryServer/` (the canonical Esri Utilities path); `POST` requests submit form-encoded bodies (the default), `GET` keeps params in the query string. Operations the server does not implement (`autoComplete`, `convexHull`, `cut`, `densify`, etc.) intentionally have no wrapper. ### GeoServices GP Service GP Services run async tasks rather than hosting features. The default capabilities advertise only `geoprocess`; the canonical query family throws. Task lifecycle — `submitJob`, `jobStatus`, `cancelJob`, `jobResult` — lives behind `Source.protocol("geoservices-gp-service")` on a `HonuaGeoprocessingService` instance. The service id and task name come from `SourceLocator.serviceId` / `SourceLocator.taskName` so a single descriptor uniquely identifies a task without leaking task parameters into the canonical descriptor shape. `createDataset` rejects descriptors that advertise `geoprocess` without a `locator.taskName` because Honua Server publishes the lifecycle routes only under `/rest/services//GPServer//...`. GeoServices GPServer also participates in the unified process runner: `client.geoprocessingRunner(serviceId, taskName)` returns a `HonuaProcessRunner` that submits GP parameters and exposes the same `IJobRun` lifecycle as OGC API Processes and geospatial-grpc ProcessService clients. ### Geospatial gRPC Process Service The open `honua-io/geospatial-grpc` protocol defines `geospatial.v1.ProcessService` with `ValidatePlan`, `DryRunPlan`, `ExecutePlan`, `ExecutePlanStream`, `SubmitJob`, `GetJob`, `GetJobResult`, and `CancelJob`. The JS SDK keeps the adapter structural because generated process proto lives outside this package today: `client.geospatialGrpcProcessRunner(processServiceClient)` accepts a generated Connect client and normalizes `JobState` values onto `IJobRun`. `JOB_STATE_COMPLETED` maps to `successful`, `JOB_STATE_FAILED` to `failed`, `JOB_STATE_CANCELLED` to `dismissed`, and draft/clarification/validated/approval states map to `accepted`. ### OGC API Tiles Render-only adapter. `tiles` and `render` are the first-party capabilities; the canonical `Source.query*` family throws `HonuaCapabilityNotSupportedError` because the conformance class is tile-fetch, not feature-query. The canonical tile path is `/collections/{id}/tiles/{tms}/{z}/{y}/{x}`; tile-matrix-set discovery uses `/tileMatrixSets` and `/tileMatrixSets/{id}`. Styled-tile access (OGC `/styles/{styleId}/tiles/...`) is part of the standard but is not exposed by honua-server today, so the SDK does not synthesize that route. `Source.adapter("ogc-tiles")` returns a `HonuaOgcTileset` bound to `(collectionId, tileMatrixSetId)` when both are set in the locator; when only `collectionId` is set, the adapter falls back to the root `HonuaOgcTiles` handle so callers can discover which tile-matrix-sets the server advertises before rebinding. ### OGC API Maps Render-only adapter. `render` is the first-party capability; same escape-hatch model as Tiles. `Source.adapter("ogc-maps")` returns either the dataset-level `HonuaOgcMaps` (when `locator.collectionId` is unset) or a `HonuaOgcCollectionMap` bound to the descriptor's collection + optional style. The wire path is `/maps[/collections/{id}][/styles/{styleId}]/map`; bbox / crs / format flow through query parameters. The `format` field is normalized to the server's short-name token (`png`, `jpeg`, `jpg`, `tiff`, `tif`) before it is written to `f=`; media-type aliases (`image/png`, etc.) are accepted for ergonomics and translated. The public request envelope has no `filter` field because honua-server's Maps request model has none. ### OGC API Processes No `Source` adapter — Processes is a job runner, not a queryable source. `HonuaClient.ogcProcesses().execute(...)` returns the canonical `IJobRun` (the same interface every other long-running operation in the SDK speaks). The implementation polls `/jobs/{jobId}` until terminal, fetches `/jobs/{jobId}/results` on `successful`, and maps failure terminals onto `JobSnapshot.error`: it prefers `statusInfo.exception` (OGC Processes Part 1 vocabulary) and falls back to `statusInfo.message` so honua-server's single-`message` failure text still surfaces through `HonuaJobFailedError.message`. `cancel()` issues `DELETE /jobs/{jobId}` and is idempotent only on the documented benign paths: 404 (job gone) returns the cached status; 409 with problem-details title `"Cannot dismiss completed job"` triggers a follow-up GET and returns the authoritative terminal status — but only if the poll confirms a terminal state, otherwise the original 409 is rethrown. The non-benign 409 titles `"Dismiss could not be confirmed"` (backend dismissal unconfirmed) and `"Cancellation not supported"` (backend lacks dismissal capability) are rethrown verbatim. The canonical `processes` capability is part of `CAPABILITIES` and is returned by `negotiateOgcCapabilities("ogc-processes", conformance)`; it is intentionally absent from `PROTOCOL_DEFAULT_CAPABILITIES` because there is no `ogc-processes` `Source` protocol. ### OGC API Records Metadata-catalog adapter. `query`, `queryObjectIds`, and `stream` are first-party capabilities over `/ogc/records/collections/{catalogId}/items`. The direct `client.ogcRecords()` surface exposes Records-specific query parameters (`q`, `type`, `externalIds`, `datetime`, `bbox`, `ids`, `profile`) and raw response access for HTML/JSON/profile negotiation. The canonical `Source.query` path maps `Query.where` to CQL2 `filter` and `spatialFilter` envelopes to Records `bbox`; aggregation, edits, attachments, related records, and extent-only queries are not advertised. Records describes metadata about resources and remains separate from STAC asset search and Honua admin/control-plane metadata APIs. ### STAC API STAC piggy-backs on OGC API Features for items but adds a cross-collection `/search` endpoint. The canonical `Source.query` uses `/search` (GET by default; opt into POST with `usePost: true`). Both the GET and POST paths serialize `intersects` (as JSON on GET, raw on POST) and `fields` (as a CSV with `-` prefixes on GET, structured on POST) so caller-supplied geometry constraints and selections are not silently dropped. `spatialFilter` translates to STAC `bbox` only — `intersects` geometry support requires CQL2 and is left to a downstream extension. Paging follows the server's `rel=next` link: honua-server emits `?offset=N` on the href and the adapter parses that numeric offset; non-Honua STAC servers that emit an opaque `?next=…` token remain supported as a fallback. `Query.pagination.offset` propagates through to the STAC `offset` parameter on the initial request. `queryAggregate` and `queryExtent` are not advertised. STAC's collection-scoping is handled via `locator.collectionId`; the adapter forwards it as the `collections=[id]` parameter on the wire. ### OGC API Features `query`, `queryObjectIds`, `applyEdits`, `stream` are first-party. OGC has no batch edit endpoint, so `applyEdits` fans out to per-item `createItem` / `replaceItem` / `deleteItem` calls and forwards `EditEnvelope.signal` to every request — aborting the signal cancels every operation that has not yet been issued, while operations already in flight resolve into per-item failures on the returned `EditResult`. `queryAll()` requests `limit + 1` rows from `itemsAll()` when the caller caps the result with `Query.pagination.limit` so the adapter can stamp `exceededTransferLimit: true` when more records exist (mirroring the GeoServices lookahead-row pattern). `queryAggregate` is degraded — `Source.query({ aggregation })` aggregates client-side over the returned page, while `Source.queryAggregate()` drains every page first and then aggregates. Both stamp a `queryAggregate` `DegradedReason` on the `Result` so downstream views can flag the number as non-authoritative. `queryExtent` is also degraded: an unfiltered `queryExtent()` with no `outSr` returns the collection metadata's `extent.spatial.bbox[0]` shortcut, while a filtered request (`where` or `spatialFilter`) — or any request that sets `outSr` — drains `itemsAll()` and computes the bbox client-side over matching features. The `outSr` carve-out exists because the metadata bbox is frozen in the collection's native CRS (typically CRS84) and the OGC `/collections/{id}` endpoint does not accept a target CRS, so reusing the shortcut when the caller asked for a different CRS would silently return the wrong coordinates. `queryExtent` returns `{ extent, count? }` and does not carry a `degraded` array. Only `spatialFilter.geometryType = "esriGeometryEnvelope"` is translated (to the OGC `bbox` query param); other geometry types would require CQL2, which the adapter does not yet emit, so they throw rather than silently drop the constraint. Likewise, only `spatialRel` values of `esriSpatialRelIntersects` or `esriSpatialRelEnvelopeIntersects` are accepted — the OGC `bbox` parameter is defined as an envelope-intersects predicate (OGC 17-069r4 §7.15.3), so `contains`/`within`/`crosses`/etc. throw rather than silently widen to bbox semantics. `queryRelated`, `attachments`, and `pbf` are out-of-scope for the OGC standard. ### WFS First-party WFS 2.0 adapter (`wfsSource`); see [`wfs.md`](./wfs.md) for the full reference. `query` / `queryAll` / `stream` all route through `GetFeature` after a one-time `GetCapabilities` negotiation; `Query.where` compiles to FES 2.0 (comparison, `IN`, `BETWEEN`, `LIKE`, `IS NULL`, boolean combinators, parenthesization), and `Query.spatialFilter` becomes either a KVP `bbox=` for envelope-only requests or a `` for everything else (envelope, point, polygon, polyline). Filters longer than ~7 KB switch to POST GetFeature with the `` body. Anything richer than the supported subset (subqueries, function calls, vendor extensions, curves / surfaces) throws `HonuaCapabilityNotSupportedError("query")` rather than ship a silent partial filter — callers reach the wire through `Source.protocol("wfs")`. WFS `propertyName=` drops every property the caller does not list, including the geometry column, so `Query.outFields` and `Query.returnGeometry` are resolved together: an `outFields` list with `returnGeometry !== false` appends the geometry property (`the_geom` by default) before the projection lands on the wire so geometry survives; `returnGeometry === false` paired with an `outFields` list emits exactly the requested fields (no geometry); a `returnGeometry === false` request without an `outFields` list throws `HonuaCapabilityNotSupportedError("query")` because WFS cannot suppress geometry without enumerating non-geometry properties. `queryExtent` prefers the per-feature-type `WGS84BoundingBox` from `GetCapabilities` for unfiltered requests so no extra HTTP traffic is issued; filtered or `outSr`-bearing requests drain every matching page (2000 features per page) and compute the bbox client-side, ignoring caller pagination, `Query.outFields`, and `Query.returnGeometry` so geometry is preserved on every drained page and the returned extent covers the full matching set. `queryObjectIds` has no interoperable server-side ids-only mode, so the adapter drains the matching set in 2000-feature pages and projects each GeoJSON `id`. The drain strips `Query.outFields` and `Query.returnGeometry` (the GeoJSON `id` is read from each feature's top-level field, so neither knob affects the result) so the request cannot push the geometry property onto the wire and a caller-supplied `returnGeometry: false` cannot trip the field-projection guard. `Query.pagination.limit` caps the global id count (callers can stop the drain without learning the server's page size) and `Query.pagination.offset` chooses where the drain starts. `pagination.limit === 0` is treated as an explicit zero cap across `query`, `stream`, and `queryObjectIds` (each short-circuits before the wire call); `queryAll` still issues a single 1-row lookahead so `exceededTransferLimit` can flip when more records exist — matching the `withPagingBounds` / `applyQueryAllLimit` semantics shared with GeoServices and OGC Features. Content negotiation prefers `application/geo+json` / `application/json` when the server's `OperationsMetadata` advertises it; if only GML is offered the canonical `query()` throws and callers reach the GML payload through `Source.protocol("wfs")`. GML decoding is intentionally out of scope. `applyEdits` builds a single `` POST body (`` / `` / ``) and surfaces the per-handle `InsertResults` IDs onto `EditOutcome.id`. Each `` is stamped with a stable `handle="add-N"` (1-based, matching `envelope.adds` order) and the returned `` buckets are indexed by that handle, so reordered or omitted (`releaseAction="SOME"` partial failure) buckets never misassign IDs to the wrong `envelope.adds[i]`; inserts whose handle is missing from the response surface as `{ success: false }`. The handle attribute is informational in WFS 2.0, so when no `` carries one the adapter falls back to the legacy positional pairing rather than dropping every id. `rollbackOnFailure` drives the transaction `releaseAction` (`ALL` vs `SOME`). Updates whose `id` is `undefined` / `null` are filtered out before the transaction body is built and surface as per-item failures (`{ success: false, error: { code: 400, description: "update.id is required" } }`) so an unaddressed `` can never reach the server; if every operation in the envelope is absent or malformed the wire round-trip is skipped. Stored-query discovery (`ListStoredQueries`) and execution (`GetFeature?storedquery_id=...`) are reachable through `Source.protocol("wfs")!.root.storedQuery(id).execute({ parameters })`. Stored queries that advertise only GML (e.g. Honua Server's `urn:ogc:def:query:OGC-WFS::GetFeatureById`) cannot be projected onto the canonical `Source.query()` envelope; the canonical surface throws `HonuaCapabilityNotSupportedError("query")` and points the caller at the protocol escape hatch. Locking (`LockFeature` / `GetFeatureWithLock`) is not exposed in the canonical surface; callers that need it reach the wire through `Source.protocol("wfs")`. The capabilities XML walker refuses any document declaring `` or `` to defend against XXE-class attacks. WFS `Result.totalCount` populates from the `numberMatched` GeoJSON field; `exceededTransferLimit` is set when `numberMatched > features.length`. ### WMS First-party WMS 1.3.0 adapter. `render` and `tiles` come from `GetMap`; `query` is supported through `GetFeatureInfo` with a point spatial filter (`Query.spatialFilter.geometryType === "esriGeometryPoint"`). The adapter constructs a 1×1 render envelope around the requested point, asks for `INFO_FORMAT=application/json`, and decodes the JSON response into the canonical `Result` envelope. The wire CRS is derived from the spatial filter geometry's `spatialReference` (`latestWkid` first, then `wkid`, then `wkt`) and falls back to `CRS:84` (the WMS 1.3.0 longitude/latitude code that preserves the canonical `(x, y)` axis order). `Query.outSr` is intentionally not consulted on this path because it is the **output** spatial reference, not the input CRS for GetFeatureInfo. Non-point queries throw `HonuaCapabilityNotSupportedError("query", "wms", id)` because WMS has no spatial-rel semantics for envelopes / polygons; raw multi-pixel GetFeatureInfo lives behind `Source.protocol("wms").featureInfo()`. Other canonical `Query` fields that GetFeatureInfo cannot honor are rejected up front rather than silently dropped: `query({ aggregation })` throws `HonuaCapabilityNotSupportedError("queryAggregate", ...)`, and `Query.where` / `Query.outFields` / `Query.orderBy` / `Query.pagination.offset` / `Query.returnGeometry === false` / `Query.outSr` throw typed `Error` messages so a mixed-source caller cannot get an unfiltered, reprojected, or differently-shaped result. `Query.outSr` fails fast because honua-server's WMS GetFeatureInfo projects the response in the request CRS itself and exposes no separate output-SR knob — callers that need a specific projection must stamp the spatial filter geometry's `spatialReference` with the desired CRS (the wire CRS is derived from there) or reproject the result client-side. `Query.pagination.limit` is honored — it maps to `FEATURE_COUNT` on the wire. `Source.protocol("wms-layer")` is registered only when `locator.typeName` parses to a single non-empty layer token because `HonuaWmsLayer` is a single-layer handle (its `describe()` resolves exactly one `` from the parsed Capabilities). Multi-layer composites (`typeName: "a,b"`) keep `Source.protocol("wms-layer")` unset and route through the service-level `Source.protocol("wms")` handle, which can target the composite verbatim via `featureInfo()` / `map()`. Styled-map selection enumerates per-layer styles from `HonuaWms.capabilities()` and is bound on the layer handle (`layer.map`, `layer.featureInfo`) via the `style` parameter or descriptor `locator.styleId`. Dimension handling (`TIME` / `ELEVATION`) flows through the typed `WmsMapRequest` envelope; defaults come from `Capabilities`, request overrides go on the wire. honua-server does not implement `GetLegendGraphic` today, so the adapter raises `HonuaCapabilityNotSupportedError` from `legend()` when the parsed Capabilities advertise no `` request element. The gating always runs: when the caller does not pre-supply `options.capabilities`, the handle lazy-loads them once via `getWmsCapabilities` and caches the in-flight promise on the instance so repeat `legend()` calls reuse the same fetch (transient failures clear the cache so the next call retries). The `HonuaWms` parser extracts each ``'s own ``, ``, `<CRS>`, `<BoundingBox>`, `<Style>`, and `<Dimension>` from the layer's direct children only — descendant `<Layer>` subtrees are stripped before metadata reads so child fields never leak upward into the parent (or, through ancestor-merge, sideways into sibling layers). CRS axis order is honored per WMS 1.3 §6.7.3.2 — `EPSG:4326` is swapped to (lat, lon) on the wire while `CRS:84` and `EPSG:3857` keep canonical (x, y) tuples. MapLibre integration ships through `buildWmsRasterSourceSpec(descriptor)`, which emits a `raster` source spec with a pre-baked KVP `tiles` template using MapLibre's runtime `{bbox-epsg3857}` / `{width}` / `{height}` placeholders. ### WMTS First-party WMTS 1.0.0 adapter. Render-only — `Source.query()` throws because WMTS GetFeatureInfo is keyed on tile pixels (which doesn't fit the canonical `Query.spatialFilter`). Capabilities expose advertised TileMatrixSets through the typed surface; honua-server only advertises `WebMercatorQuad` today and the parser-driven design tolerates additional sets without a client refactor. Protocol escape hatches: `Source.protocol("wmts")` returns the service handle, `Source.protocol("wmts-layer")` a layer-bound handle, and `Source.protocol("wmts-tileset")` a (layer × style × TMS) tileset handle. `fetchWmtsTile` defaults to the RESTful route (`{layer}/{style}/{tms}/{z}/{y}/{x}.{ext}`) because it is a single string substitution per tile and skips `URLSearchParams`; `mode: "kvp"` is opt-in for KVP-only proxies. The `Format` MIME → RESTful `.ext` mapping is canonical and shared between the wire client and the MapLibre helper via `wmtsExtensionForFormat` (`src/core/wms-types.ts`): `image/png` → `png`, `image/jpeg` / `image/jpg` → `jpeg`, `image/webp` → `webp`; unknown formats fall back to `png`. The same caller-supplied `format` therefore lands on the same path extension whether the URL is composed by `fetchWmtsTile` or `buildWmtsRasterSourceSpec`. `request.extraParams` is honored on both routing modes — under `mode: "kvp"` keys are merged into the query string verbatim; under the default RESTful route the path-encoded WMTS keys (`LAYER`, `STYLE`, `TILEMATRIXSET`, `TILEMATRIX`, `TILEROW`, `TILECOL`, `FORMAT`, `INFOFORMAT`, `I`, `J`, plus `SERVICE` / `VERSION` / `REQUEST`) take precedence and any conflicting `extraParams` keys (case-insensitive) are dropped so the same URL never carries the value twice. `buildWmtsRasterSourceSpec(descriptor)` emits a MapLibre `raster` source spec using the same RESTful path with `{z}/{y}/{x}` placeholders. ### OData First-party adapter: `query`, `queryObjectIds`, `stream`, `applyEdits`. Tabular query with `$filter`, `$select`, `$orderby`, `$top`, `$skip`, `$expand` maps cleanly onto `Query.where`, `outFields`, `orderBy`, `pagination`. `Query.where` accepts SQL-92 / OData `$filter` text; the adapter rewrites a small intersection (`IS NULL` → `eq null`, `<>` → `ne`, `=` → `eq`, plus the SQL comparison operators `>=` / `<=` / `>` / `<` → `ge` / `le` / `gt` / `lt`) and rejects operators the parity matrix documents as unsupported (`has`, `in`, `any`, `all`, `cast`, `isof`) rather than letting them reach the wire. The rewrite tokenizes single-quoted string literals (with `''` escape sequences preserved) so values like `NAME = 'A=B'` or `NAME = 'has'` or `NAME = 'A>B'` round-trip unchanged — rewrites and unsupported-operator detection only run against non-literal spans. `Query.outFields` lowers onto OData's `$select` for plain field names and `$expand` for navigation paths. Plain entries (`["STATE", "ACRES"]`) become `$select=STATE,ACRES`. Dotted entries identify a navigation property and a sub-field — `["Owner.name"]` becomes `$expand=Owner($select=name)`, multiple sub-fields under the same navigation share one expand entry (`$expand=Owner($select=name,email)`), and multi-level dotted paths nest as `$expand=Owner($expand=address($select=street))`. The same `outFields` list can mix plain and dotted entries; each goes to the matching query option so a server that distinguishes `$select` from `$expand` honors both. The descriptor locator resolves to the entity-set request path one of two ways. SDK callers that pass `locator.entitySet` (e.g. `"Parcels"` or the navigation path `"Layers(1)/Features"`) win unchanged. Bindings produced by Honua Server only carry `url`, `serviceId`, and `layerId`, so when `entitySet` is absent the adapter derives the canonical layer-scoped path `Layers(<layerId>)/Features` from `locator.layerId`. A descriptor that has neither field is rejected with `createDataset: source "<id>" (odata) requires locator.entitySet or locator.layerId`. The resolved token is the wire path used for entity requests; CSDL metadata lookups (capabilities, key fields, schema) key on the **unqualified entity-set name** instead — for navigation paths that is the trailing segment, exposed as `HonuaOdataEntitySet.entitySetName` so the lookup still hits the `<EntitySet Name="…">` entry the server emits. `Query.spatialFilter` translates to a `geo.intersects` / `geo.distance` predicate against the geometry column. Only `esriSpatialRelIntersects` / `esriSpatialRelEnvelopeIntersects` (intersects) and `esriSpatialRelDistance` (distance, requires `spatialFilter.distance`) are accepted; other relations throw rather than silently widen. The WKT literal carries the **input** geometry's SRID (resolved from `spatialFilter.geometry.spatialReference.{wkid|latestWkid}` first, then the metadata-declared SRID on the *selected* geometry column — matched by name when the descriptor or metadata pinned a column, never borrowed across columns when an entity type declares more than one spatial field); `Query.outSr` is a request for the *output* CRS and is not stamped onto the input WKT (the OData server has no request-side output-CRS knob — output geometry comes back in the column's declared SRID). The geometry column resolves from `SourceDescriptor.schema.fields` first (prefers a field whose canonical `type === "esriFieldTypeGeometry"`), otherwise from the lazy `$metadata` probe (the first property typed `Edm.Geography` / `Edm.Geometry` per CSDL parsing). For spatial filters the adapter throws when neither declares one rather than guess at the column name; the same resolved name is reused by `returnGeometry === false` $select trimming and the row-to-feature geometry split, so a schema-declared spatial column named anything other than `Geometry` / `Geography` / `Shape` is honored end-to-end. `Query.returnGeometry === false` keeps the geometry column off the wire: when `outFields` is set the resolved geometry column is filtered out of `$select`; when `outFields` is unset the adapter derives `$select` from `$metadata` to include only non-spatial columns. The canonical name guesses (`Geometry` / `Geography` / `Shape`) are kept as a fallback for the `$select` filter only when neither the descriptor schema nor `$metadata` declares a spatial column. As a defensive backstop, the canonical `Result` drops geometry from each feature even if the server still emitted it. Server-driven pagination (`$skiptoken` via `@odata.nextLink`) is consumed transparently inside `queryAll()` and `stream()`. `queryAll` honors `Query.pagination.limit` with the GeoServices/OGC `limit + 1` lookahead pattern (sent on the wire as `$top = limit + 1`) so `exceededTransferLimit: true` is stamped accurately when the cap is hit. As a belt-and-braces signal, `@odata.count > limited.length` also sets the flag for servers that respect `$top` exactly but report a higher matched-row total. The lookahead is added by the canonical `Source.queryAll` only — the lower-level `HonuaOdataEntitySet.queryAll` treats `params.top` as an exact hard cap (including `top === 0`, which collects zero rows) so callers that already added a lookahead row do not double-count. `queryObjectIds` projects the metadata key field through `$select`, drains the matching set, and slices the resulting id list to `Query.pagination.limit` (no lookahead row is needed because the result is ids, not features, and there is no `exceededTransferLimit` flag to stamp on `FeatureId[]`); a `pagination.limit === 0` cap collapses to an empty array. `applyEdits` routes adds → `POST /<entitySet>`, updates → `PATCH /<entitySet>(<key>)` with the full canonical body, deletes → `DELETE /<entitySet>(<key>)`. PUT is not issued — Honua Server's OData v4 parity matrix lists PUT as unsupported (PATCH-only); the documented `PATCH with full body` path matches `PUT` replacement semantics on the canonical surface. Composite-key entities address rows by passing the pre-formatted key expression on `deletes: FeatureId[]` (e.g. `"LayerId=1,ObjectId=3"`) or by populating each key field on `updates[].attributes`. Layer-scoped paths (`Layers(<n>)/Features`) carry the parent key (`LayerId`) in the URL itself, so callers can — and should — pass a bare ObjectId on `feature.id` or `deletes: FeatureId[]`; the adapter strips `LayerId` from the entity-set key parens to produce `/odata/Layers(<n>)/Features(<objectId>)` directly. When `EditEnvelope.rollbackOnFailure === true` AND `$metadata` advertises `Capabilities.BatchSupported`, the adapter collapses the envelope into a single `$batch` request whose every operation carries the same `atomicityGroup` token. Honua Server's `ODataBatchHandler` groups requests by `request.AtomicityGroup` and rolls the entire group back when any operation fails. The per-operation outcomes are threaded back into the canonical `EditOutcome` buckets in the original order. When `$batch` is not advertised, the adapter degrades to per-call edits and stamps a `degraded[]` entry citing `applyEdits` so downstream views can flag the result as non-atomic. `queryAggregate`, `queryExtent`, `queryRelated`, and `attachments` are intentionally absent from the canonical surface. Aggregation lives behind `Source.protocol("odata").apply(...)` (`$apply` driver), extent computation is a caller-side concern when the entity exposes `Edm.Geography`, related navigation goes through `$expand` on the escape-hatch `query()` (or `protocol("odata").raw(...)`), and attachments are not in the parity matrix. OData is the **first adapter** to implement automatic metadata-driven capability intersection. The lazy `$metadata` fetch on first method call parses `Capabilities.*` annotations and intersects against the descriptor's declared `Capabilities`; declared capabilities the service explicitly advertises as `false` raise `HonuaCapabilityNotSupportedError` with both protocol and reason in the message. The CSDL parser accepts both annotation shapes — inline inside `<EntitySet>` *and* sibling `<Annotations Target="<schema>.<container>/<entitySet>">` blocks (the form Honua Server emits next to the `EntityContainer`) — and parses the OData v4 capability vocabulary including `Insertable` / `Updatable` / `Deletable` / `Searchable` / `Filterable` / `Selectable` / `Expandable` / `Countable` plus the generic `Supported` property records use for `ChangeTracking`. Other adapters (GeoServices `supportsStatistics`, OGC `conformsTo`) follow the same pattern but currently rely on caller-supplied caps; the contract doc tracks this as the precedent for that future work. Dialect-specific `$batch`, `$apply`, `$search`, and `$deltatoken` operations live behind `Source.protocol("odata")` on a `HonuaOdataEntitySet` instance: - `metadata({ refresh? })` — cached, SDK-shaped projection of `$metadata` (`entitySets`, `keys`, `fields`, `capabilities`). - `batch(operations, { atomicity })` — JSON `$batch` envelope. Pass `atomicity: "all"` to stamp the same `atomicityGroup` token on every request item so the server runs them as one change-set with rollback on any failure (per OData v4 §11.7.7.3 and Honua Server's `ODataBatchHandler`, which groups by `request.AtomicityGroup`). Default behavior (`"none"`) leaves the field unset so each request runs independently. - `apply(transformations)` — `$apply` driver (`aggregate` / `groupby` / `filter` / `compute`) returning `{ rows, totalCount? }`. - `search(text, params)` — `$search` driver returning a `HonuaOdataPage<T>`. - `delta({ since? })` — async-iterable `$deltatoken` change feed; the final page carries `deltaLink` for the caller to persist. - `raw(method, path, init?)` — last-resort passthrough that still flows through `HonuaClient.pipelineFetch` (auth headers, retry, timeout, interceptors, telemetry, normalized `HonuaHttpError`, `init.signal` propagation for caller-driven cancellation). All HTTP traffic — including `$metadata` discovery and `raw()` passthrough — is routed through `HonuaClient.pipelineFetch` / `pipelineRequestJson` rather than the GeoServices-shaped `HonuaClient.request()` helper, so the OData wire request never carries the `f=json` parameter (Honua Server's OData validators reject it as `InvalidQueryOption`). Auth headers, interceptors, retry, timeout, and normalized error mapping all apply to OData the same way they do to every other adapter. Library posture is recorded in [`decisions/odata-library-selection.md`](./decisions/odata-library-selection.md). ### PMTiles Tiles-only. A PMTiles archive is a single immutable file (raster or vector tile pyramid) on any static host or object storage. The default capability set is `{ tiles }`, so the entire canonical query family (`query` / `queryAll` / `queryExtent` / `queryObjectIds` / `applyEdits` / `stream`) throws `HonuaCapabilityNotSupportedError` — an archive has no feature-query surface. Archive metadata (bounds, min/max zoom, and vector layer names) is inspected through the typed escape hatch: `Source.protocol("pmtiles").describe()` (or the standalone `describePmtilesArchive(url)` helper), which returns a normalized `PmtilesArchiveDescription`. The `pmtiles` package is an optional peer dependency imported lazily — a build that never inspects or renders a PMTiles archive pays no cost. The MapLibre runtime auto-registers the `pmtiles://` protocol on map attach (`loadMapPackage`), so a `pmtiles` MapPackage source binding renders with no manual `addProtocol` wiring; see [`pmtiles.md`](./pmtiles.md). ## Multi-source negotiation When more than one source participates in a composition, the composition supports a capability **only when every participating source supports it**. Use `intersectCapabilities` from `@honua/sdk-js/contract` to compute that weakest set: ```ts doc-test=compile import { PROTOCOL_DEFAULT_CAPABILITIES, intersectCapabilities, } from "@honua/sdk-js/contract"; const weakest = intersectCapabilities([ { capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"] }, { capabilities: PROTOCOL_DEFAULT_CAPABILITIES.wms }, ]); weakest.has("query"); // true weakest.has("applyEdits"); // false — WMS lacks edits ``` The helper is structurally typed on `{ capabilities }` so it accepts both `SourceDescriptor[]` (declared capabilities) and live `Source[]` (post-metadata-negotiation capabilities — the OData adapter, for example, intersects the descriptor's declared set with `$metadata` flags on first capability-gated method). Promising a capability the weakest source lacks is the worst possible mixed-source failure mode (silent wrong result). The full guide and the per-operation partitioning pattern live in [`composition.md`](./composition.md). ## Maintaining the matrix When you add or remove a capability for any protocol: 1. Update `PROTOCOL_DEFAULT_CAPABILITIES` in `src/contract/types.ts`. 2. Update this table. 3. Update the conformance scenario in `test/contract/` so the canonical tests fail the right way for the new shape. 4. Per-source downgrades are the caller's responsibility today: pass an intersected `Capabilities` set on `SourceDescriptor.capabilities`. When automatic metadata-driven downgrades land in the adapter constructors, document the override in the adapter's source file and add a unit test covering the intersected set. 5. Adapters that emit `Result.degraded[]` should populate `DegradedReason.sourceId` with `descriptor.id` so mixed-source fan-outs can attribute the degradation back to the source that emitted it. --- # File: docs/standalone-capability-matrix.md # Backend-Agnostic vs Honua-Server-Enhanced Capability Matrix <!-- support-manifest:standalone-matrix:start --> This is the generated, evidence-linked line between capabilities that work against raw standards-speaking endpoints and capabilities that require the Honua facade. The source of truth is [`config/support-manifest.v1.json`](../config/support-manifest.v1.json). See the [standalone quickstart](./standalone-quickstart.md) for the runnable path. ## Status vocabulary - `supported` — release-gated implementation with linked evidence - `beta` — implemented and evidenced, but still in pre-GA hardening - `experimental` — usable evidence-backed preview whose shape may change - `deprecated` — compatibility-only surface with a named replacement - `unsupported` — no implementation claim - `facade-required` — typed capability exists but execution requires Honua Server Environment and execution mode are separate from status: `standalone` tells you where a claim works, while `discovery`, `native`, `client-fallback`, and `facade` tell you how it works. ## Matrix | Capability | Status | Environment | Execution | Backend needed | API | Evidence | Notes | | --- | --- | --- | --- | --- | --- | --- | --- | | GeoServices FeatureServer query | `supported` | `standalone` | `native` | Any ArcGIS Server or ArcGIS Online endpoint | connect(), HonuaClient.queryFeatures, Source | [fixture: connect-fixtures](../test/connect.test.ts)<br>[fixture: contract-conformance](../test/contract/conformance.test.ts)<br>[fixture: geoservices-conformance](../test/contract/geoservices-conformance.test.ts)<br>[live: standalone-live](../scripts/standalone-live-smoke.mjs) | Discovers and uses the raw FeatureServer query path; fixture- and live-proven without a Honua account or server. | | GeoServices MapServer reads | `supported` | `standalone` | `native` | Any ArcGIS Server or ArcGIS Online endpoint | connect(), HonuaClient.mapService, Source | [fixture: connect-fixtures](../test/connect.test.ts)<br>[fixture: honua-surface-fixtures](../test/honua-surface.test.ts)<br>[fixture: tile-layer-fixtures](../test/tile-layer-compat.test.ts)<br>[integration: map-service-integration](../test/integration/surfaces/map-server.integration.ts)<br>[live: standalone-live](../scripts/standalone-live-smoke.mjs) | Discovers and uses raw MapServer paths for layer queries, export, identify, legend, find, and cached tiles. | | GeoServices ImageServer reads | `supported` | `standalone` | `native` | Any ArcGIS Server or ArcGIS Online endpoint | HonuaClient.imageService, Source.protocol() | [fixture: geoservices-conformance](../test/contract/geoservices-conformance.test.ts)<br>[integration: image-service-integration](../test/integration/surfaces/image-server.integration.ts) | Uses raw ImageServer paths for raster-catalog queries, export, identify, and cached tiles. | | Esri compatibility layer | `supported` | `standalone` | `native` | Any ArcGIS Server or ArcGIS Online endpoint | @honua/sdk-js/esri-compat | [fixture: esri-compat-fixtures](../test/feature-layer-compat.test.ts) | Compatibility classes parse public GeoServices URLs and create their own client. | | ArcGIS scanner and migration codemod | `supported` | `build-time` | `static` | None | @honua/sdk-js/migration, honua-migrate | [fixture: migration-fixtures](../test/migration-codemod.test.ts) | Static analysis and rewrites run locally; no service is involved. | | Geometry operations | `supported` | `client-only` | `native` | None | @honua/sdk-js/geometry | [fixture: geometry-fixtures](../test/geometry/ops.test.ts) | Buffer, area, simplify, measure, and reprojection run in the client through optional peers. | | OGC API Features | `supported` | `standalone` | `discovery` | Any OGC API Features server | connect(), Source with locator.layout=ogc-api or auto | [fixture: ogc-features-fixtures](../test/contract/ogc-features-backend-agnostic.test.ts)<br>[live: standalone-live](../scripts/standalone-live-smoke.mjs) | Discovers collections and item links from a raw landing page; the Honua facade remains a zero-round-trip fast path. | | WFS 2.0 | `supported` | `standalone` | `discovery` | Any WFS 2.0 server | connect(), Source, HonuaWfs | [fixture: wfs-fixtures](../test/contract/wfs-backend-agnostic.test.ts)<br>[live: standalone-live](../scripts/standalone-live-smoke.mjs) | Uses the DCP operation URLs advertised by GetCapabilities instead of assuming a server path. | | STAC API and static catalogs | `supported` | `standalone` | `discovery` | Any STAC API or static catalog | connect(), Source with locator.layout=stac-api or stac-static | [fixture: stac-fixtures](../test/contract/stac-backend-agnostic.test.ts)<br>[live: standalone-live](../scripts/standalone-live-smoke.mjs) | Searches a raw STAC API or walks static catalog links with client-side filtering. | | OData v4 | `supported` | `standalone` | `discovery` | Any OData v4 service | connect(), Source, HonuaOdataEntitySet | [fixture: odata-fixtures](../test/contract/odata-backend-agnostic.test.ts)<br>[live: standalone-live](../scripts/standalone-live-smoke.mjs) | Reads $metadata, intersects advertised capabilities, and uses the raw service root. | | GeoParquet asset discovery | `experimental` | `client-only` | `discovery` | None; caller provides a GeoParquet profiler | connect({ protocol: 'geoparquet', geoparquet: { profiler } }) | [fixture: geoparquet-connect-fixtures](../test/connect-geoparquet.test.ts) | Profiles one or more assets and returns reviewed Source descriptors; query execution remains injected through the optional GeoParquet resolver. | | OGC API Tiles | `beta` | `standalone` | `discovery` | Any link-driven OGC API Tiles server | connect(), Source protocol ogc-tiles | [fixture: ogc-tiles-fixtures](../test/connect-ogc-tiles.test.ts) | Discovers raw landing, conformance, collection, tileset, and tile links; does not rewrite them to /ogc/tiles. | | OGC API Maps | `beta` | `standalone` | `discovery` | Any link-driven OGC API Maps server | connect(), Source protocol ogc-maps | [fixture: ogc-maps-fixtures](../test/connect-ogc-maps.test.ts) | Discovers and renders from the raw map path advertised by the service; does not require /ogc/maps. | | OGC API Records | `beta` | `standalone` | `discovery` | Any link-driven OGC API Records server | connect(), Source protocol ogc-records | [fixture: ogc-records-fixtures](../test/connect-ogc.test.ts) | Discovers and queries the raw records path advertised by the service; does not require /ogc/records. | | OGC API Processes discovery | `experimental` | `standalone` | `discovery` | Any link-driven OGC API Processes server | discoverOgcProcesses() | [fixture: ogc-processes-fixtures](../test/connect-ogc-processes.test.ts) | Discovers conformance and process metadata at raw paths. Processes are not a protocol-neutral Source. | | OGC API Processes execution | `facade-required` | `honua-facade` | `facade` | Honua Server | HonuaClient OGC Processes methods | [integration: ogc-processes-integration](../test/integration/surfaces/ogc-processes.integration.ts) | Typed execution uses the Honua facade today; raw third-party execution is not claimed. | | Server compatibility gate | `facade-required` | `honua-facade` | `facade` | Honua Server | HonuaClient.checkCompatibility() | [fixture: server-compatibility-fixtures](../test/server-compatibility.test.ts) | Reads the Honua administrative capabilities contract and should be skipped for standalone reads. | | Authored MapPackage runtime | `facade-required` | `honua-facade` | `facade` | Honua Server | @honua/sdk-js/runtime | [fixture: map-package-fixtures](../test/runtime/map-package-fetch.test.ts) | Loads server-authored styles, layer order, and metadata. | | Realtime subscriptions | `facade-required` | `honua-facade` | `transport` | Honua Server | @honua/sdk-js/realtime | [integration: realtime-integration](../test/integration/surfaces/realtime.integration.ts) | Subscription-backed live updates depend on the Honua realtime contract. | | Collaboration and saved maps compatibility shim | `deprecated` | `honua-facade` | `facade` | Honua Server and @honua/app-platform | @honua/sdk-js/collaboration | Lifecycle-only claim | The SDK entrypoint is a temporary shim; new code imports @honua/app-platform/collaboration. | | MCP tools and AI execution | `facade-required` | `honua-facade` | `facade` | Honua Server and @honua/mcp-server | mcp/, @honua/sdk-js/agent-tools | [fixture: agent-tools-fixtures](../test/agent-tools.test.ts) | Tool definitions are local, while discovery and query execution use the bounded Honua server surface. | ## Current OGC line Raw OGC API Tiles, Maps, and Records discovery/use is `beta` and fixture-proven. Raw OGC API Processes discovery is `experimental`; typed Processes execution is still `facade-required`. Those are deliberately separate claims so discovery evidence can never be mistaken for execution support. <!-- support-manifest:standalone-matrix:end --> --- # File: docs/sdk-surface-alignment.md # Cross-SDK Surface Alignment Status: pending review for https://github.com/honua-io/honua-sdk-js/issues/44. Once the PR merges this becomes the canonical reference for downstream Python and .NET SDK alignment work; flip the status line to `reviewed` at that point. The Honua SDKs should share one mental model even when each language keeps its own naming conventions. JavaScript may use `queryAll()`, Python may use `query_all()`, and .NET may use `QueryAllAsync()`. Those names are allowed to differ. The semantics behind them must not. ## Canonical Semantics Use the `@honua/sdk-js/contract` vocabulary as the current source of truth: | Concept | Meaning | | --- | --- | | `Dataset` | Logical grouping of one or more sources plus compatibility checks. | | `SourceDescriptor` | Serializable source identity: protocol, locator, capabilities, schema, and attribution. | | `Source` | Runtime handle for the common query, edit, related-record, attachment, and escape-hatch surface. | | `Protocol` | Stable source protocol identifier. | | `Capability` | Stable operation capability identifier. | | `Query` | Protocol-neutral request intent. | | `Result` | Protocol-neutral result envelope. | | `EditEnvelope` / `EditResult` | Protocol-neutral write envelope and result. | | `MapBinding` | Source → renderer-layer binding (used by `MapPackage` round-trips). | | `protocol(...)` | Explicit native protocol escape hatch. | These are the canonical nouns pinned in [`test/fixtures/sdk-contract/semantic-contract.v1.json`](../test/fixtures/sdk-contract/semantic-contract.v1.json) and validated by the drift gate ([`test/contract/sdk-contract-fixtures.test.ts`](../test/contract/sdk-contract-fixtures.test.ts)). Renaming a noun without updating both sites trips CI. ## Language Bindings Language bindings must be idiomatic. The binding table below is guidance for public API names, not a byte-for-byte requirement: | Concept | TypeScript | Python | .NET | | --- | --- | --- | --- | | query all records | `queryAll()` | `query_all()` | `QueryAllAsync()` | | stream pages | `stream()` | `stream()` / `iter_*()` | `StreamAsync()` / `QueryPagesAsync()` | | query object ids | `queryObjectIds()` | `query_object_ids()` | `QueryObjectIdsAsync()` | | apply edits | `applyEdits()` | `apply_edits()` | `ApplyEditsAsync()` | | return geometry | `returnGeometry` | `return_geometry` | `ReturnGeometry` | | output fields | `outFields` | `out_fields` | `OutFields` | | pagination | `pagination` | `pagination` / `limit` / `offset` | `Pagination` / `Limit` / `Offset` | | native protocol escape hatch | `source.protocol(...)` | `source.protocol(...)` | `source.Protocol(...)` | Existing SDK names can remain as aliases or facades. For example, Python's `FeatureQuery` and .NET's `FeatureQueryRequest` can continue to exist while new source-oriented facades converge on the same behavior. ## Stable Protocol IDs The canonical protocol identifiers are the values exported from `PROTOCOLS` in `src/contract/types.ts`. Serialized descriptors and docs should prefer the canonical identifiers; SDKs may accept short or legacy aliases for already-shipped public names by normalizing on read through the `protocolAliases` map in the fixture pack: - `grpc` - `geoservices-feature-service` - `geoservices-map-service` - `geoservices-image-service` - `geoservices-geometry-service` - `geoservices-gp-service` - `ogc-features` - `ogc-tiles` - `ogc-maps` - `stac` - `wfs` - `wms` - `wmts` - `odata` - `maplibre-vector` - `maplibre-raster` - `maplibre-geojson` ## Stable Capability IDs The canonical capability identifiers are the values exported from `CAPABILITIES` in `src/contract/types.ts`. SDKs should gate behavior on these semantic identifiers rather than inventing per-repo names for the same operation. Default capability sets per protocol live in `PROTOCOL_DEFAULT_CAPABILITIES` and are mirrored in [`docs/protocol-capability-matrix.md`](./protocol-capability-matrix.md). Every identifier must also have exactly one reviewed entry in the support manifest's `operationSurfaces` registry. That registry binds the operation to either a compile-checked canonical `Source` member or a named typed adapter member, plus executable evidence; CI fails if vocabulary and surfaces drift. Top-level `connect()` discovery is tracked separately as a product support claim because it is not an operation on a `Source`. Capability misses must be explicit. The required behavior is a typed SDK error that names the missing capability and protocol (`HonuaCapabilityNotSupportedError` in JS; equivalent typed errors in Python and .NET). Returning an empty result for an unsupported operation is not acceptable because it is indistinguishable from a valid query with no matches. ## Query Semantics All SDKs should preserve these query semantics even when the local request type uses language-specific names: - `where`: logical attribute filter. Adapters translate it to SQL-92, CQL2, OData `$filter`, FES, or provider-native syntax as appropriate. - `spatialFilter` / `bbox`: spatial constraint. SDKs may expose a compact bbox helper, but the behavior must be documented. - `outFields`: fields or properties to return. - `orderBy`: provider-supported sort order. - `pagination.offset`: records to skip before returning data. - `pagination.limit`: record cap. `query()`, `queryAll()`, and `stream()` must document whether the limit is per-page or total. - `returnGeometry`: whether returned features include geometry. - `outSr`: requested output spatial reference when the protocol supports it. - `signal` / cancellation token: caller-driven cancellation. ## Result Semantics All SDKs should expose the same result facts: - features are an array, empty when no records matched. - each feature has an identifier when available, attributes/properties, and optional geometry. - result envelopes preserve paging state (`exceededTransferLimit`, `hasMoreResults`, or an idiomatic alias). - total count is present when the protocol reports it. - field schema is present when the protocol reports it. - extent is present for extent-only or extent-enriched queries. - degraded results carry structured reasons with capability, protocol, and optional source id. - raw/provider-native payload access remains available for advanced workflows. ## Backwards Compatibility And Deprecation Policy The RFC aligns semantics — it does not delete shipped APIs. - **Existing public names are preserved** as aliases or facades over the canonical surface. JS keeps `Source.adapter()` as a documented alias of `Source.protocol()`; Python keeps `FeatureQuery` and friends; .NET keeps `FeatureQueryRequest` and friends. Each binding may add the canonical name alongside the legacy name without renaming the legacy name. - **Deprecation requires a documented removal timeline.** A binding that introduces a canonical alternative may mark the legacy name deprecated and remove it at the next major version, never sooner. The deprecation note must point at the canonical replacement and (where applicable) at this RFC. - **Protocol aliases normalize on read.** Short and legacy protocol names that already shipped in any SDK appear in the `protocolAliases` map of [`semantic-contract.v1.json`](../test/fixtures/sdk-contract/semantic-contract.v1.json). SDKs accept those aliases as input, but every SDK-side serialized descriptor — `SourceDescriptor` JSON, fixture pack, telemetry, log line — emits the canonical kebab-case id. The server `SourceBinding` wire format is independent: it stays on its documented snake_case enum (`geoservices_feature_service`, `ogc_features`, …) per [`source-binding-alignment.md`](./source-binding-alignment.md), and the runtime normalizes server wire values to canonical SDK ids inside `src/runtime/source-bridge.ts` before they reach `createDataset`. A server-side wire-format rename would be a coordinated cross-repo contract change, not a downstream SDK edit. Adding a new alias is backwards- compatible; renaming a canonical id is not. - **Capability behavior may not silently change.** Adding a capability to a protocol is backwards-compatible. Removing one (or downgrading from first-party to client-side fallback) is a breaking change and must ship in a major version with a `degraded[]` migration path documented in the per-protocol notes of `docs/protocol-capability-matrix.md`. - **`canonicalNouns` is part of the contract.** Renaming `Dataset`, `SourceDescriptor`, `Source`, `Protocol`, `Capability`, `Query`, `Result`, `EditEnvelope`, `EditResult`, or `MapBinding` is a breaking change to every downstream SDK; the drift gate enforces this. ## Decisions Locked By This RFC These are the alignment points the RFC nails down. Any future change to one of these requires a follow-up RFC plus coordinated multi-SDK updates. - Canonical protocol identifiers and the canonical → alias normalization direction. - Canonical capability identifiers and per-protocol default capability sets. - Query field names and semantics for `where`, spatial filter / bbox, `outFields`, `orderBy`, `pagination`, `returnGeometry`, `outSr`, and cancellation. - Result envelope shape: features array (never undefined), pagination state, `totalCount`, field schema, extent, degraded reasons, and raw payload access. - Unsupported-capability behavior: typed error, never a silent no-op or empty result. - Native protocol escape hatch: every protocol-specific operation that does not belong on the shared surface lives behind the binding-idiomatic `protocol(...)` accessor (`Source.protocol(...)` in JS / Python, `Source.Protocol(...)` in .NET). The shared surface stays free of protocol-typed structures. ## Fixture Pack The cross-SDK fixture pack lives under [`test/fixtures/sdk-contract/semantic-contract.v1.json`](../test/fixtures/sdk-contract/semantic-contract.v1.json). It is intentionally JSON-only so Python and .NET can consume the same payloads without depending on the JS test helpers. Coverage today: - `protocols`, `capabilities`, and `defaultCapabilities` are pinned against the live JS exports — drift trips CI. - `protocolAliases` records the short / legacy names already shipped (or about to ship) in Python and .NET so each SDK normalizes on read. - `canonicalNouns` enumerates the ten contract nouns the drift gate enforces. - `languageBindings` documents idiomatic per-language method and field names. - `resultScenarios` cover FeatureServer, OGC API Features, STAC, OData, and WFS; included variants exercise nominal queries, empty pages, exceeded transfer limits, and the `queryAggregate` client-side degraded fallback for OGC API Features. - `unsupportedCapabilityScenarios` cover render-only protocols (WMTS, OGC API Tiles, OGC API Maps), utility-only GeoServices protocols (Geometry Service, GP Service), and protocol-specific capability gaps (OGC API Features `queryRelated`). The JS drift gate in `test/contract/sdk-contract-fixtures.test.ts` validates that the fixture pack stays aligned with the exported JS contract registries and with the documented result/error/degraded semantics. Downstream SDK work should consume this fixture pack directly or mirror it with a clear checksum/update process. ## Downstream Implementation Work This RFC is JS-side and docs-only. The Python and .NET SDK alignment lands as separate downstream tickets: - **Python**: `honua-sdk-python` will pin against `semantic-contract.v1.json`, expose the canonical surface as `Source.query_all` / `Source.protocol(...)`, and keep `FeatureQuery` plus the existing free-function helpers as backwards-compatible facades. Track via `honua-io/honua-sdk-python` issue (TODO: add link once issue is filed). - **.NET**: `honua-sdk-dotnet` will mirror the same fixture pack, expose `Source.QueryAllAsync` / `Source.Protocol(...)` / `Source.QueryObjectIdsAsync`, and keep `FeatureQueryRequest` as a facade. Track via `honua-io/honua-sdk-dotnet` issue (TODO: add link once issue is filed). This ticket explicitly does not edit either repository. Filing the downstream issues is part of merging this RFC; updating the placeholders above with the real issue links is the only follow-up edit allowed inside `honua-sdk-js` once the downstream tickets are open. ## References - Canonical type definitions: [`src/contract/types.ts`](../src/contract/types.ts) - Cross-protocol matrix: [`docs/protocol-capability-matrix.md`](./protocol-capability-matrix.md) - Shared client contract design: [`docs/shared-client-contract.md`](./shared-client-contract.md) - Source-binding round-trip: [`docs/source-binding-alignment.md`](./source-binding-alignment.md) - Drift gate test: [`test/contract/sdk-contract-fixtures.test.ts`](../test/contract/sdk-contract-fixtures.test.ts) - Tracking issue: https://github.com/honua-io/honua-sdk-js/issues/44 - Cross-repo coordination: `honua-io/honua-server#813` --- # File: docs/errors.md # Error reference The Honua JS SDK exposes a tagged error envelope from `@honua/sdk-js`. Public errors migrated in the table below pass the cross-realm `isHonuaError(error)` guard. Use their stable classifications to gate retry, refresh, fallback, and surface-to-user decisions instead of parsing message strings. This release covers core transport/auth/protocol errors, discovery, the query planner, every public error exported by the stable `map` and `runtime` subpaths, the public realtime resume error, and the offline region plus replica synchronization classes migrated by [#569](https://github.com/honua-io/honua-sdk-js/issues/569), plus the plugin registry error migrated by [#571](https://github.com/honua-io/honua-sdk-js/issues/571). Agent errors ([#570](https://github.com/honua-io/honua-sdk-js/issues/570)) remain an explicit residual. Other experimental domains likewise retain their current domain-specific contracts until a scoped migration lands. ## Envelope contract Every migrated instance has these common fields: | Field | Meaning | |-------|---------| | `kind` | Constant `"honua.sdk.error.v1"` tag used by the cross-realm guard. | | `domain` | Stable broad owner: `core`, `discovery`, `query`, `map`, `runtime`, `realtime`, `offline`, or `plugin`. | | `sdkCode` | Globally unique code from `HONUA_ERROR_CODE_REGISTRY`. | | `category` | Stable `authentication`, `cancellation`, `capability`, `internal`, `network`, `protocol`, `timeout`, or `validation` classification. | | `retryable` | Stable boolean for this exact `sdkCode`. This metadata describes the existing policy; it does not initiate retries. | | `operationId` / `requestId` | Optional sanitized correlation identifiers when the throwing boundary has them. | | `context` | Frozen, recursively sanitized structured context. | | `cause` | Original cause, retained on the in-process instance for debugging. | Existing error-specific `.code` values remain compatible. For example, `HonuaGrpcError.code` is still the numeric gRPC status and `HonuaDiscoveryError.code` is still `"invalid-endpoint"` (or another legacy discovery code). Use `.sdkCode` when one globally unique value is required. `serializeHonuaError(error)` projects `.sdkCode` as the serialized envelope's `.code`. Serialization is deliberately fail-closed. `serializeHonuaError` and `JSON.stringify(error)` include classification, identifiers, sanitized context, and classification-only cause information. They omit raw messages, stacks, response bodies, details, cause payloads, credentials, authorization/cookie headers, cached feature bodies, raw cursors/resume tokens, signed URL values, query/filter/SQL values, local storage paths, plugin manifests/configuration, tool payloads, cleanup failures, binary payloads, and prototype-manipulation keys. The raw instance still retains its message, documented detail fields, exact cause, and documented cleanup aggregates for local use. ```ts doc-test=skip reason="partial excerpt requires application retry and logging hosts" import { isHonuaError, serializeHonuaError } from "@honua/sdk-js"; try { await operation(); } catch (error) { if (!isHonuaError(error)) throw error; console.error(serializeHonuaError(error)); if (error.category === "cancellation") return; if (error.retryable) scheduleRetry(); } ``` ## At-a-glance table | Class | Source | When it fires | Recover by | |-------|--------|---------------|------------| | `HonuaHttpError` | Any REST call | The server returned a non-2xx status with a parsed error envelope (4xx or 5xx). | Branch on `.statusCode`: `401`/`403` → refresh credentials or surface to user; `404` → treat as missing; `409` → conflict, refetch and retry; `429` → respect `Retry-After`; `5xx` → use the SDK's `retry` option or back off and retry idempotent calls. | | `HonuaTimeoutError` | Any REST call | The `timeoutMs` configured on the client elapsed before the response arrived. | Increase `timeoutMs` per-call (the per-request `AbortSignal` is independent), or surface a "server slow" indicator. The request is idempotent-safe to retry. | | `HonuaNetworkError` | Any REST call | The transport itself failed (`fetch` rejected) — DNS, TLS, offline, or upstream connection reset. | Inspect `.cause` if present; back off and retry. For browsers, this is also the most common error to render as "Check your connection." | | `HonuaAbortError` | Any REST call | The caller's `AbortSignal` was aborted (or the SDK aborted on timeout — see `HonuaTimeoutError` for that case). | Do **not** retry. The caller asked to stop. Treat as a successful cancellation. | | `HonuaGrpcError` | `transport: "grpc-web"` only | A gRPC-Web call returned a non-OK `Code`. | Branch on `.code` (Connect/`google.rpc.Code`): `UNAUTHENTICATED` → refresh credentials, `PERMISSION_DENIED` → surface; `UNAVAILABLE` → retry with backoff; `DEADLINE_EXCEEDED` → increase deadline or retry; `INVALID_ARGUMENT` → fix the call site. | | `HonuaAuthError` | `@honua/sdk-js/auth` providers (`oauth2`, `clientCredentials`) | A credential could not be produced. | Branch on `.code`: `interaction_required` → start interactive sign-in (`auth.signIn()`); `refresh_failed` → transient token-endpoint failure, retry later; `invalid_grant` → refresh token/authorization code expired or revoked (the stored credential is cleared) → interactive sign-in. The underlying transport/parse failure, when present, is on `.cause`. | | `HonuaCapabilityNotSupportedError` | `Source.query` / `Source.applyEdits` / etc. | Under the default `capabilityPolicy: "strict"`, the active source does not support the requested operation (e.g. `query()` on a `wmts` source). | Either downgrade the request (drop the unsupported clause), fall back to `Source.protocol(...)` for raw protocol access, or set `capabilityPolicy: "degraded"` on `createDataset` to coerce best-effort behavior with a `degraded` reason in the `Result`. | | `HonuaDiscoveryError` | `connect`, discovery truth, cache identity | Endpoint metadata, protocol hints, source selection, or cached discovery observations are invalid or ambiguous. | Branch on `.code`: provide an explicit supported protocol for `ambiguous-protocol`; select a listed source ID for `ambiguous-source`; use a reviewed adapter for `unsupported-protocol`; evict/rebuild entries for `invalid-discovery-cache`. Do not retry unchanged invalid input. | | `HonuaGeometryError` | Spatial-filter builders | Geometry classification would otherwise require guessing, or a recognized Esri geometry is malformed. | Branch on `.code`: `unknown-geometry` means no supported Esri shape discriminator was found; `malformed-geometry` means a recognized shape, coordinate, or envelope expansion is invalid. Fix the input; do not retry it unchanged. Diagnostic context is on `.detail`. | | `HonuaExplorationContextError` | `@honua/sdk-js/exploration` | An exploration intent referenced a missing slice / view, or the snapshot is incompatible with the active context schema. | Surface to user (UI bug) or migrate the saved snapshot. Do not retry. | | `HonuaWfsExceptionError` | `wfs` adapter | The WFS server returned a `<ows:ExceptionReport>`. The `exceptionCode`, optional `locator`, and formatted exception message are preserved on the instance. | Branch on `.exceptionCode` (`InvalidParameterValue`, `OperationNotSupported`, `MissingParameterValue`, etc.). Most are caller bugs; surface to user. | | `HonuaJobFailedError` | OGC Processes / geoprocessing job polling | An async job (`IJobRun.results()`) reached a non-success terminal state (`failed` / `dismissed`). The terminal `.status`, `.errorCode`, and `.details` are preserved on the instance. | Branch on `.status` / `.errorCode`. Usually a server-side or input error; surface to user. Do not blindly retry. | | `HonuaQueryPlanningError` / `HonuaQueryPlanExecutionError` | `@honua/sdk-js/query-planner` | Query validation/compilation/planning or accepted-plan execution fails. | Branch on the existing short `.code`; fix validation/context errors or choose a supported capability/fallback. | | `HonuaMapLibreSourceAdapterError` | Root or `@honua/sdk-js/map` source workflow | Source projection, plan compatibility, identifier conflict, lifecycle, or renderer mutation fails. | Branch on the existing short `.code`; recreate disposed mounts and correct conflicts/options before retrying. | | `HonuaDataToMapBridgeError` | `@honua/sdk-js/map` | The high-level bridge rejects options, renderer capabilities, conflicts, lifecycle, or mutation. | Correct options/host capability or recreate the mount. | | `HonuaAutomaticMapLibreStrategyError` | `@honua/sdk-js/map` | Automatic strategy selection/mounting has no exact candidate, a stale plan, conflict, cancellation, disposal, or renderer failure. | Re-explain stale plans; treat cancellation as terminal; correct host conflicts/capabilities. | | `HonuaMapLibreRasterStrategyError` | `@honua/sdk-js/map` | Raster strategy capability/metadata/options, identifiers, or renderer mutation fail. | Correct source truth/options or host conflicts; do not silently select a lossy fallback. | | `HonuaAutomaticMapLibreIntegrationError` | `@honua/sdk-js/map` | Incremental integration is disposed or receives an invalid target. | Recreate the integration or correct the target. | | `HonuaTemporalPlaybackError` | `@honua/sdk-js/map` | Playback options or temporal extent are invalid. | Correct input; do not retry unchanged input. | | `HonuaMapPackageError` | `@honua/sdk-js/runtime` | Map-package fetch/load/validation/update/style/source/view/popup/disposal stage fails. | Branch on `.stage`; only fetch and disposal classifications are marked retryable. | | `HonuaRuntimeDiagnosticError` | `@honua/sdk-js/runtime` | Runtime style/source/layer validation produces error diagnostics. | Inspect the local `.diagnostics` and correct invalid runtime input. Serialized context carries codes/count only. | | `QueryTileServerResponseError` | `@honua/sdk-js/runtime` | Query-tile HTTP response is unsuccessful. | Inspect `.status`; transient HTTP statuses are classified retryable without changing request policy. | | `HonuaRealtimeResumeError` | `@honua/sdk-js/realtime` | Realtime initialization, decoding, checkpoint, ordering, transport, or terminal delivery fails. | Branch on the existing reason `.code`; reconnect or request a replacement snapshot only when the stream contract already permits it. Envelope retryability is metadata and does not initiate reconnects. | | `HonuaOfflineRegionError` | `@honua/sdk-js/offline` | Offline manifest validation, quota admission, resource loading, integrity verification, cancellation, or atomic store work fails. | Branch on the existing detailed `.code`. Rebuild invalid manifests, free quota, and treat abort as terminal. Retry through the application's loader/store policy only when `.sdkCode` is `offline.transport.transient`; generic loader failures remain conservative. Raw resource identifiers and storage paths remain local-only. | | `HonuaReplicaSyncError` | `@honua/app-platform/replica-sync` (the deprecated `@honua/sdk-js/replica-sync` shim remains through 0.1.x) | Disconnected replica capability, conflict review/resolution, permission, validation, or transport work fails. | Branch on the existing detailed `.code` and preserve the current sync/conflict workflow. Only failures carrying a tagged retryable network/timeout cause receive retryable metadata; the envelope does not retry or resolve conflicts. | | `HonuaPluginRegistryError` | `@honua/sdk-js/plugin` | Plugin registry validation, compatibility, policy, capability, activation, execution validation, cancellation, or cleanup fails. | Branch on the existing `PLUGIN_*` `.code` or its grouped `.sdkCode`. Correct declarations or host policy/capability, treat cancellation as terminal, and inspect `.cause` / `.cleanupErrors` locally for activation or cleanup failures. No plugin classification is automatically retryable. | ## Registered code families The exported `HONUA_ERROR_CODE_REGISTRY` is the canonical, typed inventory. Its object keys are globally unique at compile time, the common base accepts only registered codes, and domain constructors either reject unknown runtime reasons or project them to a fixed registered fallback. Focused entrypoints retain only the code/domain/category/retryability classifications needed by the error base; human-readable registry summaries remain in the explicit public registry. `npm run check:error-codes` verifies exact classification parity, registry shape, and this class/family documentation. | Public class | Registered `sdkCode` family | |--------------|-----------------------------| | `HonuaHttpError` | `core.http.transient`, `core.http.rejected` | | `HonuaTimeoutError` | `core.timeout` | | `HonuaNetworkError` | `core.network` | | `HonuaAbortError` | `core.cancelled` | | `HonuaGrpcError` | `core.grpc.transient`, `core.grpc.rejected` | | `HonuaGeometryError` | `core.geometry.unknown-geometry`, `core.geometry.malformed-geometry` | | `HonuaAuthError` | `core.auth.interaction-required`, `core.auth.refresh-failed`, `core.auth.invalid-grant` | | `HonuaCapabilityNotSupportedError` | `core.capability-not-supported` | | `HonuaExplorationContextError` | `core.exploration-context` | | `HonuaWfsExceptionError` | `core.wfs-exception` | | `HonuaJobFailedError` | `core.job-failed` | | `HonuaWmsCapabilitiesParseError` | `core.wms-capabilities-parse` | | `HonuaWmtsCapabilitiesParseError` | `core.wmts-capabilities-parse` | | `HonuaDiscoveryError` | `discovery.*` (the eight values in `HonuaDiscoveryErrorCode`) | | `HonuaQueryPlanningError` | `query.planning.*` (the six values in `QueryPlanningErrorCode`) | | `HonuaQueryPlanExecutionError` | `query.execution.*` (the eight values in `QueryPlanExecutionErrorCode`) | | `HonuaMapLibreSourceAdapterError` | `map.source-adapter.*` | | `HonuaDataToMapBridgeError` | `map.data-bridge.*` | | `HonuaAutomaticMapLibreStrategyError` | `map.automatic-strategy.*` | | `HonuaMapLibreRasterStrategyError` | `map.raster-strategy.*` | | `HonuaAutomaticMapLibreIntegrationError` | `map.automatic-integration.*` | | `HonuaTemporalPlaybackError` | `map.temporal-playback.invalid-option` | | `HonuaMapPackageError` | `runtime.map-package.*` (one code per public stage) | | `HonuaRuntimeDiagnosticError` | `runtime.diagnostic` | | `QueryTileServerResponseError` | `runtime.query-tiles.transient`, `runtime.query-tiles.rejected` | | `HonuaRealtimeResumeError` | `realtime.cancelled`, `realtime.transport.reconnectable`, `realtime.checkpoint.invalid`, `realtime.sequence.gap`, `realtime.protocol.terminal` | | `HonuaOfflineRegionError` | `offline.region.validation`, `offline.region.quota`, `offline.region.integrity`, `offline.cancelled`, `offline.transport.failure`, `offline.transport.transient`, `offline.storage.*` | | `HonuaReplicaSyncError` | `offline.replica-sync.capability`, `offline.replica-sync.validation`, `offline.replica-sync.permission-denied`, `offline.transport.failure`, `offline.transport.transient` | | `HonuaPluginRegistryError` | `plugin.registry.validation`, `plugin.compatibility`, `plugin.execution.policy-denied`, `plugin.capability-unavailable`, `plugin.lifecycle.activation`, `plugin.execution.validation`, `plugin.lifecycle.cleanup`, `plugin.cancelled`, `plugin.internal` | `HonuaRealtimeResumeError.code` remains the existing detailed reason (for example, `invalid-checkpoint`, `sequence-gap`, `transport-gap`, or `delivery-failed`). Its `sdkCode` groups those reasons into stable recovery classes. `realtime.transport.reconnectable` and `realtime.sequence.gap` are marked retryable because the existing contract permits reconnect or replacement snapshot recovery; the envelope does not perform either action. SSE abort, unsubscribe, and close still complete normally without emitting an error. `HonuaOfflineRegionError.code` and `HonuaReplicaSyncError.code` likewise retain their detailed legacy reasons. Their grouped `sdkCode` values distinguish invalid state, quota/storage, cancellation, integrity, capability, permission, and transport recovery classes. Generic resource/replica transport failures are non-retryable by default; `offline.transport.transient` is selected only when the wrapped cause is itself a valid tagged, retryable network or timeout error. Raw cached content, sync cursors, signed URLs, filter values, resource locators, details, and filesystem paths are kept on the local error instance only; serialization emits a fixed registered reason and classification. Retryability is descriptive and does not alter offline eviction, commit, transport, or conflict-resolution policy. `HonuaPluginRegistryError.code` remains the existing `PLUGIN_*` reason and `cleanupErrors` remains a frozen shallow copy of cleanup failures. The grouped `sdkCode` distinguishes registry validation, compatibility, host-policy denial, missing capability, activation, execution validation, cleanup, cancellation, and internal failures. Every plugin classification is conservatively non-retryable. Serialization emits only the registered classification and a fixed known `reasonCode`; it never emits manifests, plugin/configuration IDs, raw cause payloads, or cleanup payloads. Unknown runtime codes project to `plugin.internal` with `reasonCode: "PLUGIN_UNKNOWN"` without changing a valid string's local legacy `.code` or message. ### Individual code registry <!-- error-code-registry:start --> | Registered code | Domain | Category | Retryable | Summary | |-----------------|--------|----------|-----------|---------| | `core.http.transient` | `core` | `protocol` | yes | Retryable HTTP response failure | | `core.http.rejected` | `core` | `protocol` | no | Non-retryable HTTP response failure | | `core.timeout` | `core` | `timeout` | yes | Request deadline elapsed | | `core.network` | `core` | `network` | yes | Network transport failure | | `core.cancelled` | `core` | `cancellation` | no | Caller cancelled the operation | | `core.grpc.transient` | `core` | `protocol` | yes | Retryable gRPC-Web transport failure | | `core.grpc.rejected` | `core` | `protocol` | no | Non-retryable gRPC-Web transport failure | | `core.geometry.unknown-geometry` | `core` | `validation` | no | Geometry shape cannot be classified safely | | `core.geometry.malformed-geometry` | `core` | `validation` | no | Recognized geometry has invalid coordinates or structure | | `core.auth.interaction-required` | `core` | `authentication` | no | Interactive authentication is required | | `core.auth.refresh-failed` | `core` | `authentication` | yes | Credential refresh failed transiently | | `core.auth.invalid-grant` | `core` | `authentication` | no | Authorization grant is invalid or expired | | `core.capability-not-supported` | `core` | `capability` | no | Requested source capability is unavailable | | `core.exploration-context` | `core` | `validation` | no | Exploration context operation is invalid | | `core.wfs-exception` | `core` | `protocol` | no | WFS exception report | | `core.job-failed` | `core` | `protocol` | no | Remote job reached a failed terminal state | | `core.wms-capabilities-parse` | `core` | `protocol` | no | WMS capabilities document is invalid | | `core.wmts-capabilities-parse` | `core` | `protocol` | no | WMTS capabilities document is invalid | | `discovery.ambiguous-protocol` | `discovery` | `validation` | no | Multiple protocols match the endpoint | | `discovery.ambiguous-source` | `discovery` | `validation` | no | Multiple sources match the selection | | `discovery.invalid-endpoint` | `discovery` | `validation` | no | Discovery endpoint is invalid | | `discovery.invalid-cache-identity` | `discovery` | `validation` | no | Discovery cache identity is invalid | | `discovery.invalid-discovery-cache` | `discovery` | `validation` | no | Discovery cache entry is invalid | | `discovery.invalid-capability` | `discovery` | `validation` | no | Discovered capability evidence is invalid | | `discovery.unsupported-protocol` | `discovery` | `capability` | no | Endpoint protocol is unsupported | | `discovery.protocol-mismatch` | `discovery` | `validation` | no | Endpoint protocol conflicts with its hint | | `query.planning.invalid-query` | `query` | `validation` | no | Query is invalid | | `query.planning.unsupported-compiler` | `query` | `capability` | no | No compiler supports the source protocol | | `query.planning.unsupported-query` | `query` | `capability` | no | Query cannot be represented by the compiler | | `query.planning.capability-not-supported` | `query` | `capability` | no | Query requires an unavailable capability | | `query.planning.fallback-disabled` | `query` | `capability` | no | Required local fallback is disabled | | `query.planning.unsafe-materialization` | `query` | `validation` | no | Planned local materialization exceeds its safety bound | | `query.execution.invalid-plan` | `query` | `validation` | no | Query plan is invalid | | `query.execution.plan-context-mismatch` | `query` | `validation` | no | Execution context does not match the accepted query plan | | `query.execution.unsafe-materialization` | `query` | `validation` | no | Query execution exceeded its materialization bound | | `query.execution.invalid-resource-handle` | `query` | `validation` | no | Query resource handle is invalid | | `query.execution.resource-unavailable` | `query` | `authentication` | no | Query resource is unavailable in the authorization context | | `query.execution.resource-expired` | `query` | `authentication` | no | Query resource authorization has expired | | `query.execution.resource-resolution-failed` | `query` | `internal` | no | Query resource resolution failed | | `query.execution.resource-execution-failed` | `query` | `internal` | no | Resolved query resource execution failed | | `map.source-adapter.disposed` | `map` | `validation` | no | Map source adapter is disposed | | `map.source-adapter.source-conflict` | `map` | `validation` | no | Map source identifier already exists | | `map.source-adapter.layer-conflict` | `map` | `validation` | no | Map layer identifier already exists | | `map.source-adapter.unsupported-plan` | `map` | `capability` | no | Query plan cannot be rendered by the source adapter | | `map.source-adapter.invalid-option` | `map` | `validation` | no | Map source adapter option is invalid | | `map.source-adapter.map-mutation-failed` | `map` | `internal` | no | Renderer mutation failed | | `map.data-bridge.invalid-option` | `map` | `validation` | no | Data-to-map option is invalid | | `map.data-bridge.disposed` | `map` | `validation` | no | Data-to-map bridge is disposed | | `map.data-bridge.source-conflict` | `map` | `validation` | no | Data-to-map source identifier already exists | | `map.data-bridge.layer-conflict` | `map` | `validation` | no | Data-to-map layer identifier already exists | | `map.data-bridge.map-mutation-failed` | `map` | `internal` | no | Data-to-map renderer mutation failed | | `map.data-bridge.interaction-unsupported` | `map` | `capability` | no | Renderer interaction is unsupported | | `map.data-bridge.filter-unsupported` | `map` | `capability` | no | Renderer filter mutation is unsupported | | `map.automatic-strategy.no-eligible-strategy` | `map` | `capability` | no | No exact map source strategy is eligible | | `map.automatic-strategy.stale-plan` | `map` | `validation` | no | Map strategy plan is stale | | `map.automatic-strategy.source-conflict` | `map` | `validation` | no | Automatic strategy source identifier already exists | | `map.automatic-strategy.layer-conflict` | `map` | `validation` | no | Automatic strategy layer identifier already exists | | `map.automatic-strategy.map-mutation-failed` | `map` | `internal` | no | Automatic strategy renderer mutation failed | | `map.automatic-strategy.cancelled` | `map` | `cancellation` | no | Automatic map strategy was cancelled | | `map.automatic-strategy.disposed` | `map` | `validation` | no | Automatic map strategy is disposed | | `map.raster-strategy.unsupported-strategy` | `map` | `capability` | no | Raster strategy is unsupported | | `map.raster-strategy.capability-mismatch` | `map` | `capability` | no | Raster source lacks a required capability | | `map.raster-strategy.missing-metadata` | `map` | `validation` | no | Raster source metadata is incomplete | | `map.raster-strategy.invalid-option` | `map` | `validation` | no | Raster option is invalid | | `map.raster-strategy.source-conflict` | `map` | `validation` | no | Raster source identifier already exists | | `map.raster-strategy.layer-conflict` | `map` | `validation` | no | Raster layer identifier already exists | | `map.raster-strategy.map-mutation-failed` | `map` | `internal` | no | Raster renderer mutation failed | | `map.automatic-integration.disposed` | `map` | `validation` | no | Automatic map integration is disposed | | `map.automatic-integration.invalid-target` | `map` | `validation` | no | Automatic map integration target is invalid | | `map.temporal-playback.invalid-option` | `map` | `validation` | no | Temporal playback option is invalid | | `runtime.map-package.fetch` | `runtime` | `network` | yes | Map package fetch failed | | `runtime.map-package.load` | `runtime` | `internal` | no | Map package load failed | | `runtime.map-package.validate` | `runtime` | `validation` | no | Map package validation failed | | `runtime.map-package.update` | `runtime` | `internal` | no | Map package update failed | | `runtime.map-package.style-compose` | `runtime` | `validation` | no | Map package style composition failed | | `runtime.map-package.source-bind` | `runtime` | `internal` | no | Map package source binding failed | | `runtime.map-package.view` | `runtime` | `internal` | no | Renderer view mutation failed | | `runtime.map-package.popup` | `runtime` | `validation` | no | Popup binding failed | | `runtime.map-package.dispose` | `runtime` | `internal` | yes | Runtime disposal failed | | `runtime.diagnostic` | `runtime` | `validation` | no | Runtime validation diagnostic | | `runtime.query-tiles.transient` | `runtime` | `protocol` | yes | Retryable query-tile response failure | | `runtime.query-tiles.rejected` | `runtime` | `protocol` | no | Non-retryable query-tile response failure | | `realtime.cancelled` | `realtime` | `cancellation` | no | Realtime operation was cancelled | | `realtime.transport.reconnectable` | `realtime` | `network` | yes | Realtime transport can reconnect or resnapshot | | `realtime.checkpoint.invalid` | `realtime` | `validation` | no | Realtime checkpoint or resume context is invalid | | `realtime.sequence.gap` | `realtime` | `protocol` | yes | Realtime ordering requires a replacement snapshot | | `realtime.protocol.terminal` | `realtime` | `protocol` | no | Realtime delivery reached a terminal failure | | `offline.region.validation` | `offline` | `validation` | no | Offline region input or lifecycle state is invalid | | `offline.region.quota` | `offline` | `validation` | no | Offline region exceeds a logical storage quota | | `offline.region.integrity` | `offline` | `protocol` | no | Offline resource integrity verification failed | | `offline.cancelled` | `offline` | `cancellation` | no | Offline operation was cancelled | | `offline.transport.failure` | `offline` | `network` | no | Offline resource or replica transport failed without a transient classification | | `offline.transport.transient` | `offline` | `network` | yes | Offline resource or replica transport failed transiently | | `offline.storage.concurrent` | `offline` | `internal` | yes | Offline storage inventory changed before commit | | `offline.storage.failure` | `offline` | `internal` | no | Offline storage operation failed | | `offline.replica-sync.capability` | `offline` | `capability` | no | Replica synchronization capability is unavailable | | `offline.replica-sync.validation` | `offline` | `validation` | no | Replica synchronization request or state is invalid | | `offline.replica-sync.permission-denied` | `offline` | `authentication` | no | Replica synchronization permission was denied | | `plugin.registry.validation` | `plugin` | `validation` | no | Plugin registry input or lifecycle state is invalid | | `plugin.compatibility` | `plugin` | `capability` | no | Plugin declaration is incompatible with the host or its dependencies | | `plugin.execution.policy-denied` | `plugin` | `capability` | no | Plugin execution was denied by host policy | | `plugin.capability-unavailable` | `plugin` | `capability` | no | Plugin execution requires an unavailable capability or dependency | | `plugin.lifecycle.activation` | `plugin` | `internal` | no | Plugin activation or registration failed | | `plugin.execution.validation` | `plugin` | `validation` | no | Plugin execution input is invalid | | `plugin.lifecycle.cleanup` | `plugin` | `internal` | no | Plugin lifecycle cleanup failed | | `plugin.cancelled` | `plugin` | `cancellation` | no | Plugin registration was cancelled | | `plugin.internal` | `plugin` | `internal` | no | Plugin registry internal failure | <!-- error-code-registry:end --> ## Narrowing in `catch` Prefer the `isHonuaError` guard so unrelated exceptions (e.g. caller TypeErrors in callbacks) propagate normally: ```ts doc-test=skip reason="partial excerpt requires application host context" import { HonuaHttpError, HonuaTimeoutError, HonuaCapabilityNotSupportedError, isHonuaError } from "@honua/sdk-js"; try { await dataset.source("parcels")!.queryAll({ where: "1=1" }); } catch (error) { if (!isHonuaError(error)) throw error; if (error instanceof HonuaCapabilityNotSupportedError) { // expected for capability misses — fall back to a narrower query return fallbackQuery(); } if (error instanceof HonuaHttpError && error.statusCode === 401) { await refreshCredentials(); return retry(); } if (error instanceof HonuaTimeoutError) { notifyUser("Server slow — try again in a moment."); return; } throw error; } ``` ## Retry policy The SDK's built-in retry (`HonuaClientOptions.retry`) automatically handles a subset of these errors when configured: | Error | Retried by built-in `retry`? | |-------|-------------------------------| | `HonuaHttpError` with status in `retryStatuses` (default `[408, 429, 500, 502, 503, 504]`) | Yes | | `HonuaNetworkError` | Yes | | `HonuaTimeoutError` | Yes | | `HonuaGrpcError` with retryable code | **No** — the built-in `retry` policy is not applied to the gRPC-web transport; wrap these calls yourself | | `HonuaAuthError` | **No** — resolved by the auth provider's own silent-refresh / single-flight logic; a 401/403 additionally triggers one force-refresh + replay. Branch on `.code` to sign in or surface. | | `HonuaAbortError` | **No** — caller asked to stop | | `HonuaRealtimeResumeError` | **No automatic retry** — the realtime transport and resumable delivery gate retain their existing reconnect/resnapshot policy; use `.sdkCode` only to classify the observed transition. | | `HonuaOfflineRegionError` | **No automatic retry** — loader, transaction, quota, and eviction behavior is unchanged; the application/store owns any retry after an explicitly transient tagged cause. | | `HonuaReplicaSyncError` | **No automatic retry** — the replica transport and conflict workflow retain their existing policy; generic transport failures remain non-retryable. | | `HonuaPluginRegistryError` | **No automatic retry** — every plugin classification is conservatively non-retryable; the host must correct registry input, compatibility, policy, capability, or lifecycle state explicitly. | | `HonuaCapabilityNotSupportedError` | **No** — would never succeed | | `HonuaGeometryError` | **No** — input must be corrected | | `HonuaWfsExceptionError` | **No** — caller bug | | `HonuaExplorationContextError` | **No** — state bug | ## Capability policy `createDataset({ capabilityPolicy: "strict" })` is the default and is recommended for production. It surfaces capability misses as `HonuaCapabilityNotSupportedError` *before* the network call, so unsupported features can never silently degrade to an empty result. `capabilityPolicy: "degraded"` is intended for exploratory tools that prefer best-effort results with an explicit `degraded` reason annotated on the `Result`. --- # File: docs/auth.md # Authentication `@honua/sdk-js` ships a small, pluggable authentication layer. A `HonuaClient` accepts an **auth provider** that resolves credentials on demand; the client attaches them to every request across **all transports** (REST fetch paths and gRPC-web calls), refreshes them transparently before they expire, and force- refreshes once on a replay-safe `401`/`403`. ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; import { oauth2 } from "@honua/sdk-js/auth"; const auth = oauth2({ authorizationEndpoint: "https://idp.example/authorize", tokenEndpoint: "https://idp.example/token", clientId: "my-app", redirectUri: `${location.origin}/callback`, scopes: ["openid", "profile"], }); const client = new HonuaClient({ baseUrl: "https://api.example", auth }); ``` The auth providers live in the dedicated `@honua/sdk-js/auth` subpath so a `HonuaClient`-only consumer never pays the PKCE / token-exchange code size. Only [WebCrypto](https://developer.mozilla.org/docs/Web/API/Web_Crypto_API) is used for PKCE, so there are **no new runtime dependencies** (Node ≥20 exposes `globalThis.crypto`). ## Built-in providers | Provider | Import | Use | Interactive? | |----------|--------|-----|--------------| | `apiKeyAuth(key)` | `@honua/sdk-js/auth` | Static API key → `X-API-Key`. | No | | `bearerTokenAuth(token)` | `@honua/sdk-js/auth` | Static bearer → `Authorization: Bearer …`. | No | | `oauth2(config)` | `@honua/sdk-js/auth` | OAuth2 authorization-code + PKCE (browser). | Yes | | `clientCredentials(config)` | `@honua/sdk-js/auth` | OAuth2 client-credentials (Node/server). | No | All four satisfy the core `HonuaAuthProvider` interface (`getCredentials(context) → credentials`), so they drop straight into `new HonuaClient({ auth })`. You can also pass a bare function (`auth: (ctx) => ({ bearerToken })`) for fully custom logic. ## OAuth2 authorization-code + PKCE `oauth2(config)` returns an `OAuth2Provider` that is **both** the client's auth provider **and** the controller your app drives for the interactive flow. ### Flow (redirect mode — the default) 1. **Start sign-in.** `await auth.signIn()` generates a PKCE verifier (`code_verifier`), its S256 challenge, and an unguessable `state`, stashes the verifier + state in `sessionStorage`, and redirects the browser to the authorization endpoint. (The returned promise never resolves — the page unloads.) 2. **Handle the callback.** When the browser returns to `redirectUri`, call `await auth.handleRedirectCallback()`. It validates `state` (CSRF guard), exchanges the `code` + verifier at the token endpoint, and persists the tokens in the credential store. 3. **Use the client.** Every request now carries `Authorization: Bearer …`. When the access token nears expiry it is silently refreshed via the `refresh_token` grant. ```ts doc-test=skip reason="partial excerpt requires application host context" // On the page that renders your app / callback: if (auth.isRedirectCallback()) { await auth.handleRedirectCallback(); // completes the sign-in } else if (!(await auth.isSignedIn())) { await auth.signIn(); // starts the sign-in (redirects away) } ``` ### Popup mode Set `mode: "popup"`. `await auth.signIn()` opens a popup, waits for the redirect back to `redirectUri`, exchanges the code, and resolves with the stored credential — no full-page navigation. The redirect page still runs your app; it does not need to call `handleRedirectCallback()` because the opener reads the result. ### Silent refresh & the no-refresh-token fallback When a request needs a token and the cached one is expiring (within the clock-skew window, default 60 s), the provider refreshes it using the `refresh_token` grant. If the authorization server did **not** issue a refresh token, the provider throws `HonuaAuthError` with code `interaction_required` — your app should catch it and call `signIn()` again (or use a hidden-iframe / silent-auth strategy of your own). ### Single-flight refresh If _N_ concurrent requests all observe an expiring token, exactly **one** token-endpoint round-trip is made; the other _N − 1_ await the same refresh. This holds both inside the provider and at the client level. ### Lifecycle events ```ts doc-test=skip reason="partial excerpt requires application host context" const handle = auth.on((event) => { switch (event.type) { case "signed-in": /* event.credential */ break; case "token-refreshed": /* event.credential */ break; case "refresh-failed": /* event.error (HonuaAuthError) */ break; case "signed-out": break; } }); handle.remove(); // unsubscribe ``` `await auth.signOut()` clears the stored credential (and calls the optional `revocationEndpoint`), emitting `signed-out`. ## Client-credentials (Node / server) For confidential server clients, use `clientCredentials`. There is no interactive step; tokens are fetched on demand and re-requested when they expire (this grant issues no refresh token). Refresh is single-flight. ```ts doc-test=compile import { clientCredentials } from "@honua/sdk-js/auth"; const auth = clientCredentials({ tokenEndpoint: "https://idp.example/token", clientId: process.env.CLIENT_ID!, clientSecret: process.env.CLIENT_SECRET!, scopes: ["honua.read"], }); ``` > **Never use `clientCredentials` in a browser** — the client secret would be > exposed to every visitor. It is for Node/server processes only. ## Credential stores Credentials are held in a pluggable `CredentialStore`, scoped per origin/service (the key defaults to `${clientId}@${token-endpoint origin}`) so a token for one service is never returned for another. | Store | Import | Persistence | Risk | |-------|--------|-------------|------| | `InMemoryCredentialStore` (default) | `@honua/sdk-js/auth` | JS heap; cleared on reload | Lowest — no other script/tab can read it. | | `sessionStorageCredentialStore()` | `@honua/sdk-js/auth` | Per-tab; cleared on tab close | Readable by any script on the origin (XSS). | | `localStorageCredentialStore()` | `@honua/sdk-js/auth` | Across tabs & restarts | Highest — persists the exposure window. | ```ts doc-test=compile import { oauth2, sessionStorageCredentialStore } from "@honua/sdk-js/auth"; const auth = oauth2({ authorizationEndpoint: "https://identity.example.com/oauth2/authorize", tokenEndpoint: "https://identity.example.com/oauth2/token", clientId: "public-browser-client", redirectUri: "https://app.example.com/oauth/callback", store: sessionStorageCredentialStore(), // opt-in; understand the risk below }); ``` ### Storage & security - **Prefer the in-memory default.** Tokens never touch disk or Web Storage, so a script-injection (XSS) bug cannot exfiltrate a token from another context. - **Web Storage is opt-in for a reason.** `sessionStorage`/`localStorage` are readable by _any_ JavaScript running on the origin. A single XSS vulnerability turns stored tokens into stolen tokens. `localStorage` is worse than `sessionStorage` because it persists across restarts and tabs. - **Credentials are never sent cross-origin.** The client refuses to follow a cross-origin redirect (it never replays your `X-API-Key`/`Authorization` to a redirect target off the configured base origin — see [`errors.md`](./errors.md) and the credential-leak tests). Absolute request URLs to a different origin are rejected outright. - **PKCE only, always S256.** The implicit flow is not supported; the code challenge method is always `S256`. ## Wiring into transports The client resolves credentials through one shared pipeline, so providers apply uniformly: - **REST / fetch** — auth headers are merged onto every request; a replay-safe `401`/`403` triggers one force-refresh and a single retry. - **gRPC-web** (`transport: "grpc-web"`) — a Connect interceptor re-resolves credentials on every call (and every retry attempt). - **Realtime (SSE)** — native `EventSource` cannot set headers and reconnects internally, so realtime streams that need a token should carry it as a query parameter (or use a custom `eventSourceFactory`) and **re-read it on each (re)connect** so a refreshed token is picked up after a drop. Use `await client.getAuthToken()` / `await client.getAuthHeaders()` to obtain the current (refreshed) credential at connect time. ## Esri IdentityManager compatibility Migrated ArcGIS apps that call `IdentityManager.registerOAuthInfos(...)` can be backed by the real engine. Bind an `oauth2(...)` provider to a server and `getCredential(url)` drives the actual PKCE / refresh flow: ```ts doc-test=compile import { oauth2 } from "@honua/sdk-js/auth"; import { identityManager, OAuthInfoCompat } from "@honua/sdk-js/esri-compat"; const info = new OAuthInfoCompat({ appId: "app", portalUrl: "https://portal.example" }); identityManager.registerOAuthInfos([info]); identityManager.registerOAuth2Engine( info.portalUrl, oauth2(info.toOAuth2Config({ redirectUri: `${location.origin}/callback` })), ); // Drives the real flow (silent refresh, or interactive signIn on // interaction_required), registers the token, and returns it: const credential = await identityManager.getCredential("https://portal.example/sharing/rest"); ``` `OAuthInfoCompat.toOAuth2Config()` derives the ArcGIS Portal endpoints (`<portalUrl>/sharing/rest/oauth2/authorize` and `/token`) from `portalUrl` + `appId`; pass explicit endpoints/overrides where needed. ## Errors Auth failures are `HonuaAuthError` (in the typed error hierarchy) with a `.code`: | `.code` | Meaning | Recover by | |---------|---------|------------| | `interaction_required` | No token and no way to get one silently. | `auth.signIn()`. | | `refresh_failed` | Transient token-endpoint failure. | Retry later; the stored credential is kept. | | `invalid_grant` | Refresh token / code expired or revoked. | The credential is cleared → `auth.signIn()`. | See [`errors.md`](./errors.md) for the full hierarchy and the runnable example under [`examples/oauth-signin/`](../examples/oauth-signin/). --- # File: docs/react.md # React bindings (`@honua/react`) `@honua/react` is the idiomatic React layer over the framework-neutral `@honua/sdk-js` core: a context provider, data hooks, and declarative map components. The core SDK stays React-free — React is imported only from this entry point (`@honua/sdk-js/react`, published standalone as `@honua/react`). - **SSR-safe.** Nothing touches `window` / `document` at import time; `HonuaMap` only imports `maplibre-gl` inside a mount effect. - **StrictMode-safe.** Works under React 18 and 19 StrictMode double-invocation — mount/unmount/remount leaks nothing and never double-subscribes. - **Optional peers.** `react` and `react-dom` are optional peer dependencies; `maplibre-gl` is needed only when you render a `HonuaMap`. ## Install ```bash npm install @honua/sdk-js @honua/react react react-dom maplibre-gl ``` Inside this monorepo the same surface is available at the subpath `@honua/sdk-js/react`. ## Provider setup Wrap your app once with a `HonuaClient`. The provider owns a session-scoped query cache shared by every hook below it. ```tsx doc-test=skip reason="partial excerpt requires application host context" import { HonuaClient } from "@honua/sdk-js/honua"; import { HonuaProvider } from "@honua/react"; const client = new HonuaClient({ baseUrl: "https://honua.example.com" }); export function Root() { return ( <HonuaProvider client={client}> <App /> </HonuaProvider> ); } ``` ## Hooks | Hook | Purpose | |------|---------| | `useHonuaClient()` | The active `HonuaClient`. | | `useDataset(options)` | A memoized `Dataset` (`createDataset`) bound to the provider client. | | `useQuery(source, query?, options?)` | Run a contract `Query` against a `Source` with loading/error/data state. | | `useCapabilities(options?)` | Fetch the server's capability / compatibility descriptor. | | `useMapRuntime()` | The `HonuaMapRuntime` owned by the enclosing `HonuaMap`. | | `useRealtime(factory, deps?)` | Open a realtime subscription and tear it down on unmount. | | `useHonuaMap(map?)` *(experimental)* | Resolve the nearest MapLibre map (explicit arg → `HonuaMapProvider` → `HonuaMap`). | | `useMountedSource(map, source, options?)` *(experimental)* | Mount a `Source` through the data-to-map bridge for the component lifetime. | | `useSelection()` / `useHover()` *(experimental)* | Read/write the shared selection & hover state of the enclosing `HonuaSelectionProvider`. | | `useMapSelectionBinding(map, options)` / `useMapHoverBinding(map, options)` *(experimental)* | Two-way-bind MapLibre layers to the shared selection/hover state. | ```tsx doc-test=compile import { PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { useDataset, useQuery } from "@honua/react"; function Incidents() { const dataset = useDataset({ id: "ops", sources: [ { id: "incidents", protocol: "geoservices-feature-service", locator: { url: "https://honua.example.com", serviceId: "incidents", layerId: 0 }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"], }, ], }); const source = dataset.source("incidents"); const { data, isLoading, error, refetch } = useQuery(source, { where: "STATUS = 'OPEN'", returnGeometry: true, }); if (isLoading) return <p>Loading…</p>; if (error) return <p>Query failed: {String(error)}</p>; return <p>{data?.features.length ?? 0} open incidents. <button onClick={refetch}>Refresh</button></p>; } ``` ### Memoization contract (NFR-001) `useQuery` caches per `(source, query-hash)` inside the provider and reads through `useSyncExternalStore`, so: - the returned `data` keeps a **stable reference** until the underlying result changes — safe as a `useEffect` / `useMemo` dependency; - two components issuing the same `(source, query)` share **one** in-flight request; - the request is aborted (via `AbortController`) when the last consumer unmounts or the query key changes, and superseded responses are ignored (no races). To keep the query key stable, memoize the `query` object (or pass a literal) and the dataset `sources`. `refetch()` forces a fresh fetch; `useHonuaQueryCache()` exposes `invalidate(key)` / `clear()` for manual cache control. ### Stale-while-revalidate, Suspense, and error boundaries (experimental) Three `useQuery` options extend the cache semantics (all `@experimental`): - **`staleTimeMs`** — when a consumer (re)mounts and the cached result is at least this old, the cached data keeps rendering while a background refetch runs (`isFetching: true`, `data` preserved). `0` revalidates on every mount; omitted keeps the historical never-revalidate behavior. The snapshot's `dataUpdatedAt` reports the last successful fetch time. - **`suspense`** — the hook suspends while the *first* fetch (no cached data) is in flight, and throws errors to the nearest error boundary. Background refetches never suspend. The render-phase fetch kick is idempotent, so StrictMode does not double-fetch. - **`throwOnError`** — throw query errors during render without Suspense. Typed errors (e.g. `HonuaCapabilityNotSupportedError` with its `capability` / `protocol` fields) arrive at the boundary intact. ```tsx doc-test=compile import { Suspense } from "react"; import { PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { useDataset, useQuery } from "@honua/react"; function Rows() { const dataset = useDataset({ id: "ops", sources: [ { id: "incidents", protocol: "geoservices-feature-service", locator: { url: "https://honua.example.com", serviceId: "incidents", layerId: 0 }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"], }, ], }); const { data } = useQuery(dataset.source("incidents"), { where: "1=1" }, { suspense: true, staleTimeMs: 30_000 }); return <p>{data?.features.length ?? 0} rows</p>; } export function Panel() { return ( <Suspense fallback={<p>Loading…</p>}> <Rows /> </Suspense> ); } ``` ## Map components `HonuaMap` owns a `HonuaMapRuntime` over a MapLibre map. `HonuaLayer` and `HonuaPopup` declaratively add a runtime source/layer and a click popup; they add on mount and remove on unmount. ```tsx doc-test=skip reason="partial excerpt requires application host context" import { HonuaMap, HonuaLayer, HonuaPopup } from "@honua/react"; import { HONUA_MAP_PACKAGE_FORMAT_V1 } from "@honua/sdk-js/runtime"; const mapPackage = { mapPackageId: "sites", format: HONUA_MAP_PACKAGE_FORMAT_V1, sourceBindings: [], mapSpec: { version: 8, sources: {}, layers: [{ id: "bg", type: "background", paint: { "background-color": "#0b1021" } }] }, initialView: { center: [-157.84, 21.31], zoom: 10 }, }; <HonuaMap package={mapPackage} style={{ height: 480 }}> <HonuaLayer source={{ id: "sites", spec: { type: "geojson", data: sitesGeoJson } }} layer={{ id: "sites-circles", type: "circle", source: "sites", paint: { "circle-radius": 8 } }} /> <HonuaPopup layer="sites-circles" binding={{ sourceId: "sites", title: "Site", fieldName: "name" }} /> </HonuaMap>; ``` By default `HonuaMap` creates and owns the MapLibre map (dynamically importing `maplibre-gl`). Pass `mapLibre={maplibregl}` to supply the module explicitly, or `mapOptions` to tune the constructor. ## External-map interop (`@vis.gl/react-maplibre`) — experimental Every map-attached hook/component resolves its MapLibre map through the same chain: an explicit `map` prop/argument wins, then the nearest **`HonuaMapProvider`** (or enclosing `HonuaMap`, which publishes the same context). The map is duck-typed on the MapLibre `Map` instance — `@vis.gl/react-maplibre` is *not* a dependency; hand over the raw instance from its `useMap()` and everything works: ```tsx doc-test=skip reason="requires the @vis.gl/react-maplibre host application" import { Map, useMap } from "@vis.gl/react-maplibre"; import { HonuaMapProvider, HonuaSourceLayer } from "@honua/react"; function HonuaOverlay({ source }) { const { current } = useMap(); return ( <HonuaMapProvider map={current?.getMap() ?? null}> <HonuaSourceLayer source={source} hover /> </HonuaMapProvider> ); } <Map initialViewState={{ longitude: -157.84, latitude: 21.31, zoom: 10 }} mapStyle={style}> <HonuaOverlay source={source} /> </Map>; ``` The provider never mutates or removes the map — the owner keeps the lifecycle. A plain, self-created `maplibre-gl` map works identically (see `examples/react-quickstart/`). ## Bridge components: `HonuaSourceLayer` and `useMountedSource` — experimental `HonuaSourceLayer` is the declarative face of the data-to-map bridge (`mountSource` from `@honua/sdk-js/map`): it mounts a contract `Source` as a styled, interactive MapLibre layer set inside the enclosing map and owns the full disposal on unmount. React 18/19 **StrictMode double-mounts neither leak MapLibre resources nor double-add layers** — each effect run performs one fresh mount and its cleanup aborts/disposes it. Prop changes are **diffed in place, never torn down**: - `query` → `handle.setFilter(query)` (GeoJSON `setData` / tile URL rewrite); - `renderer.paint` / `renderer.layout` → per-property `setPaintProperty` / `setLayoutProperty` on the bridge-owned layers (hosts without those methods fall back to a transactional remount); - structural options (`renderer.geometry`, `renderer.layers`, `strategy`, `sourceId`, `queryTiles`, …) → remount. ```tsx doc-test=compile import type { DataToMapLibreMap } from "@honua/sdk-js/map"; import { PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { HonuaSourceLayer, useDataset } from "@honua/react"; export function OpenIncidents({ map }: { map: DataToMapLibreMap | null }) { const dataset = useDataset({ id: "ops", sources: [ { id: "incidents", protocol: "geoservices-feature-service", locator: { url: "https://honua.example.com", serviceId: "incidents", layerId: 0 }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"], }, ], }); return ( <HonuaSourceLayer map={map} source={dataset.source("incidents")} query={{ where: "STATUS = 'OPEN'" }} renderer={{ paint: { point: { "circle-color": "#38bdf8" } } }} hover onDiagnostics={(diagnostics) => console.log(diagnostics.strategy, diagnostics.featureCount)} /> ); } ``` `useMountedSource(map, source, options)` is the same lifecycle as a hook: it returns `{ handle, diagnostics, error, isMounting, refresh }` for imperative composition (pass `undefined` as `map` to resolve it from context). Mount failures and update failures surface on `error` / `onError`; the bridge's strategy explanation and overflow reporting arrive through `diagnostics` / `onDiagnostics`. ## Shared selection & hover: `HonuaSelectionProvider` — experimental `HonuaSelectionProvider` owns selection/hover state built on the interactions layer's source-qualified targets, so map and non-map components stay in sync: - `useSelection()` → `{ selected, isSelected, select, deselect, toggle, clear }`; - `useHover()` → `{ hovered, isHovered, setHovered, clearHovered }`; - `HonuaSourceLayer selection` (or `useMapSelectionBinding`) two-way-binds the mounted layers: map clicks toggle the shared selection, and every selection change — from the map *or* a sidebar — is mirrored onto MapLibre feature-state (default key `"selected"`) for paint expressions; - `useMapHoverBinding` publishes the map-hovered feature; visual hover feature-state stays with the bridge's `hover` option. ```tsx doc-test=compile import type { DataToMapLibreMap } from "@honua/sdk-js/map"; import { PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { HonuaMapProvider, HonuaSelectionProvider, HonuaSourceLayer, useDataset, useSelection } from "@honua/react"; function Sidebar() { const { selected, clear } = useSelection(); return ( <button type="button" onClick={clear}> {selected.length} selected </button> ); } function ParcelsLayer() { const dataset = useDataset({ id: "ops", sources: [ { id: "parcels", protocol: "geoservices-feature-service", locator: { url: "https://honua.example.com", serviceId: "parcels", layerId: 0 }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["geoservices-feature-service"], }, ], }); return <HonuaSourceLayer source={dataset.source("parcels")} hover selection />; } export function Workspace({ map }: { map: DataToMapLibreMap | null }) { return ( <HonuaSelectionProvider> <HonuaMapProvider map={map}> <ParcelsLayer /> </HonuaMapProvider> <Sidebar /> </HonuaSelectionProvider> ); } ``` Pair it with a selection-aware paint expression, e.g. `["case", ["boolean", ["feature-state", "selected"], false], "#f59e0b", "#2dd4bf"]`. Feature-state needs stable feature ids: give the source descriptor a `schema.primaryKey` (the bridge promotes it to MapLibre feature ids). ### Attaching a `HonuaMap` runtime to an external map `HonuaMap` (the `MapPackage` runtime component) also accepts an existing map instance via its `map` prop; it then attaches its runtime and **does not** remove the map on unmount — the owner keeps control; Honua only disposes its runtime. ## Web components vs. React The SDK also ships framework-neutral web components (`@honua/sdk-js/web-components`). Choose based on your app: - **Use `@honua/react`** in a React app: you get JSX, typed props, hooks that participate in React state/effects, Suspense-friendly data flow, and ref-free composition with the rest of your component tree. - **Use web components** in a framework-agnostic page, a non-React framework, or when embedding a Honua map into server-rendered HTML with no build step. They work anywhere custom elements do, at the cost of React ergonomics. Both talk to the same `HonuaClient` and runtime, so you can mix them. ## Runnable example `examples/react-quickstart/` is a Vite app running under `StrictMode` that wires the whole depth-pass surface together: an **externally-created plain `maplibre-gl` map** (standing in for `@vis.gl/react-maplibre`'s `<Map>`) published through `HonuaMapProvider`, a `HonuaSourceLayer` with a selection-aware `renderer` prop, popups/hover from the bridge, and a sidebar list sharing selection with the map through `HonuaSelectionProvider` — plus the existing `HonuaProvider` / `useDataset` / `useQuery` / `useCapabilities` data panel: ```bash npm run demo:react-quickstart # dev server npm run demo:react-quickstart:mock # build + serve against fixtures npm run demo:react-quickstart:build # production build ``` --- # File: docs/geometry.md # `@honua/geometry` — client-side geometry operations `@honua/geometry` (the `@honua/sdk-js/geometry` subpath, split-packaged as `@honua/geometry`) adds curated, tree-shakeable client-side geometry operations and reprojection to the Honua SDK, wrapping the individual [`@turf/*`](https://turfjs.org) packages and [`proj4`](https://github.com/proj4js/proj4js). It is typed against the SDK's own GeoJSON contract and never reimplements the underlying algorithms. The core SDK has **no dependency edge** into this module, so core-only consumers never pull turf/proj4 into their bundle. See [`decisions/geometry-library-selection.md`](./decisions/geometry-library-selection.md) for the dependency-placement ADR. ## Install / import ```bash # split package (turf/proj4 are regular deps — zero config) npm install @honua/geometry # or via the unified SDK subpath (install the turf/proj4 optional peers you use) npm install @honua/sdk-js @turf/buffer @turf/area proj4 ``` ```ts doc-test=compile import { area, buffer, project, toWgs84 } from "@honua/geometry"; // unified: import { area, buffer } from "@honua/sdk-js/geometry"; ``` ## Operations | Op | turf backing | Notes | | --- | --- | --- | | `buffer(geom, radius, unit?)` | `@turf/buffer` | Geodesic buffer; `unit` default `"meters"`. | | `area(geom)` | `@turf/area` | Geodesic area in **m²**. | | `length(geom, unit?)` | `@turf/length` | Geodesic length; `unit` default `"meters"`. | | `centroid(geom)` | `@turf/centroid` | Returns a `Point`. | | `bbox(geom)` | `@turf/bbox` | `[minX, minY, maxX, maxY]`. | | `simplify(geom, tolerance, highQuality?)` | `@turf/simplify` | Ramer–Douglas–Peucker vertex reduction. | | `booleanIntersects(a, b)` | `@turf/boolean-intersects` | Predicate. | | `booleanContains(a, b)` | `@turf/boolean-contains` | Predicate. | | `booleanWithin(a, b)` | `@turf/boolean-within` | Predicate. | | `union(...polys)` | `@turf/union` | Polygon union; `null` if empty. | | `intersect(a, b)` | `@turf/intersect` | Polygon intersection; `null` if disjoint. | | `difference(a, b)` | `@turf/difference` | Polygon `a − b`; `null` if fully removed. | | `nearestPoint(target, points)` | `@turf/nearest-point` | Nearest candidate `Feature<Point>`. | | `convex(geom)` | `@turf/convex` | Convex hull; `null` if undefined. | ## Spatial-filter envelope migration Before 1.0, the package root exposed `buffer(x, y, distance, spatialReference?)` for an axis-aligned bounding box around a point. Despite its name, that helper never created a geometry buffer. It has been renamed so the approximation is visible at the call site: ```ts doc-test=compile import { bufferEnvelope } from "@honua/sdk-js"; const nearbyFilter = bufferEnvelope(-157.858, 21.307, 0.01, { wkid: 4326 }); ``` `bufferEnvelope` expands x and y by `distance` in the input coordinate system's units. It is planar and axis-aligned; it is not circular, geodesic, or suitable for measuring a setback. Pre-1.0 callers should mechanically rename root or `/honua` imports and calls from `buffer` to `bufferEnvelope` when they intended the old envelope behavior. Callers that intended a true geometry buffer must instead import `buffer(geometry, radius, unit?)` from `@honua/sdk-js/geometry` or `@honua/geometry`, supply WGS84 coordinates, and consume its polygonal GeoJSON result. The two operations deliberately have different signatures and return types. ### Units Linear units (`buffer`, `length`): `"meters"` (default), `"kilometers"`, `"miles"`, `"feet"`, `"yards"`, `"nauticalmiles"`. `area` always returns square meters — divide by the relevant factor for other units. ## Reprojection | Function | Purpose | | --- | --- | | `project(geom, fromCrs, toCrs)` | Reproject between any registered CRS. | | `toWgs84(geom, fromCrs)` | Fast path → EPSG:4326. | | `toWebMercator(geom, fromCrs)` | Fast path → EPSG:3857. | | `defineProjection(code, proj4def)` | Register an additional CRS on demand. | | `normalizeCrs(code)` | Resolve numeric/`"EPSG:xxxx"`/alias codes to a proj4 id. | Only **EPSG:4326** and **EPSG:3857** are bundled (both are built into proj4, so the module registers nothing at import time and is side-effect-safe for tree-shaking). Web Mercator aliases (`3785`, `900913`, `102100`, `102113`) are normalized to `EPSG:3857`. `project` never mutates its input; a same-CRS call is a deep clone. Extra ordinates (`z`/`m`) pass through untouched. ```ts doc-test=skip reason="partial excerpt requires application host context" defineProjection(32610, "+proj=utm +zone=10 +datum=WGS84 +units=m +no_defs +type=crs"); const utm = project(feature.geometry, 4326, 32610); ``` ## CRS caveats - turf operates on **WGS84 longitude/latitude degrees**. Feed geographic coordinates to `area`/`length`/`buffer`, or reproject first. - Running geodesic ops on projected coordinates (e.g. raw Web Mercator meters) yields wrong results — reproject to 4326 first (`toWgs84`). - Coordinate-space ops (`union`/`intersect`/`difference`/`simplify`/`convex` and the boolean predicates) are CRS-agnostic as long as **both** operands share the same CRS. ## `geometryEngine` compat shim For ArcGIS migrants, `@honua/sdk-js/esri-compat` exposes a `geometryEngine`-shaped shim (`geometryEngineCompat` / `geometryEngineAsyncCompat`) backed by `@honua/geometry`. Inputs may be plain Esri-JSON geometries or Honua compat instances (`PointCompat`, `PolygonCompat`, …) that expose `toJSON()`. Results are Esri geometries stamped with the source `spatialReference`. The migration codemod rewrites `import geometryEngine from "@arcgis/core/geometry/geometryEngine"` (and `geometryEngineAsync`) to these shims. ### Coverage matrix | geometryEngine op | Shim | turf backing | Semantic difference vs. Esri | | --- | --- | --- | --- | | `buffer` | ✅ `buffer` | `@turf/buffer` | Esri `buffer` is **planar**; the shim is **geodesic** (closer to `geodesicBuffer`). | | `union` | ✅ `union` | `@turf/union` | Coordinate-space; parity within polygon-clipping tolerance. | | `intersect` | ✅ `intersect` | `@turf/intersect` | Coordinate-space. `null` when disjoint. | | `difference` | ✅ `difference` | `@turf/difference` | Coordinate-space. | | `geodesicArea` | ✅ `geodesicArea` | `@turf/area` | Reprojects to WGS84; spherical model. | | `planarArea` | ✅ `planarArea` | shoelace | Exact in a projected CRS (e.g. Web Mercator); meaningless in degrees. | | `geodesicLength` | ✅ `geodesicLength` | `@turf/length` | Reprojects to WGS84; spherical model. | | `planarLength` | ✅ `planarLength` | Euclidean | Exact in a projected CRS. | | `simplify` | ✅ `simplify` | Esri↔GeoJSON round-trip | **Topological normalization** (ring rewinding), not vertex reduction. Use `@honua/geometry`'s `simplify(geom, tolerance)` for RDP thinning. | | `convexHull` | ✅ `convexHull` | `@turf/convex` | Coordinate-space. | | `contains` | ✅ `contains` | `@turf/boolean-contains` | Predicate. | | `intersects` | ✅ `intersects` | `@turf/boolean-intersects` | Predicate. | | `geodesicDensify`, `densify`, `offset`, `cut`, `generalize`, `nearestCoordinate`, `nearestVertex`, `rotate`, `flip*`, `clip`, `overlaps`, `touches`, `crosses`, `within`, `disjoint`, `equals`, `isSimple`, `relate`, `symmetricDifference`, `geodesicBuffer` | ❌ not shimmed | — | Migration codemod keeps a **manual-intervention TODO** for these call sites. | ### Parity tolerances Numerical parity is tested in `test/geometry-engine-compat.test.ts` against analytically-derived expected outputs (fixtures use Web Mercator geometries so planar ops have exact values): - **planar area / length:** exact to `< 1e-6` relative (pure coordinate arithmetic). - **geodesic area / length:** within ~0.5 % of the great-circle analytic value (turf's spherical model vs. a spherical hand-calc). - **buffer:** asserted on monotonic area growth and output shape, not exact vertices (geodesic turf buffer ≠ Esri planar buffer). ## Example: measure + buffer + reproject ```ts doc-test=skip reason="partial excerpt requires application host context" import { area, buffer, toWgs84 } from "@honua/geometry"; // A parcel returned in Web Mercator (EPSG:3857). const parcel3857 = feature.geometry; // Reproject to WGS84 so geodesic measures are correct. const parcel = toWgs84(parcel3857, 3857); // Measure it (m²) and grow a 25 m setback ring. const parcelArea = area(parcel); const setback = buffer(parcel, 25, "meters"); console.log(`parcel is ${parcelArea.toFixed(0)} m²`); ``` --- # File: docs/bundle-sizes.md <!-- GENERATED FILE — do not edit by hand. --> <!-- Regenerate with: npm run report:bundle-sizes --> # Bundle sizes Per-entrypoint bundle sizes for `@honua/sdk-js`, measured the way a real consumer builds them: esbuild `--bundle --minify`, target `es2020`, runtime peers (`maplibre-gl`, `cesium`, `@bufbuild/*`, `@connectrpc/*`) kept external. Ceilings are enforced in CI via `npm run verify:bundle-budgets` (budgets live in [`bundle-budgets.json`](../bundle-budgets.json), set to actual + ~10% headroom). _Generated 2026-07-16 at commit `10fe4df`._ | Entrypoint | Min | Min budget | Gzip | Gzip budget | | --- | ---: | ---: | ---: | ---: | | `.` (root) | 422.9 KiB | 425.3 KiB | 110.6 KiB | 112.5 KiB | | `/honua` | 523.0 KiB | 566.2 KiB | 137.7 KiB | 149.6 KiB | | `/contract` | 258.8 KiB | 287.3 KiB | 68.3 KiB | 72.9 KiB | | `/source-schema` (focused schema + pinned PROJJSON validator) | 631.0 KiB | 663.7 KiB | 129.3 KiB | 134.0 KiB | | `/source-capabilities` (static evidence ingestion + lightweight evaluator) | 252.9 KiB | 257.5 KiB | 31.0 KiB | 33.2 KiB | | `/source-capability-discovery` (GeoServices/OData schema-bound evaluation) | 662.9 KiB | 733.3 KiB | 137.7 KiB | 152.6 KiB | | `/plugin` (registry + certification, no heavy peers) | 53.2 KiB | 62.6 KiB | 16.5 KiB | 19.3 KiB | | `/agent-tools` | 20.6 KiB | 22.7 KiB | 6.4 KiB | 7.0 KiB | | `/agent-safety` | 51.4 KiB | 55.2 KiB | 14.8 KiB | 15.8 KiB | | `/nl-map-control` | 73.2 KiB | 84.5 KiB | 22.0 KiB | 25.3 KiB | | `/runtime` | 451.2 KiB | 458.7 KiB | 119.3 KiB | 131.7 KiB | | `/realtime` | 41.2 KiB | 49.3 KiB | 11.4 KiB | 13.5 KiB | | `/offline` | 36.6 KiB | 44.3 KiB | 11.1 KiB | 13.2 KiB | | `/query-planner` (worker runtime injected) | 399.7 KiB | 439.0 KiB | 71.7 KiB | 78.7 KiB | | `/scene-workspace` (MapLibre/Cesium external — optional peers) | 90.0 KiB | 100.0 KiB | 28.0 KiB | 30.8 KiB | | `/esri-compat` | 978.1 KiB | 1026.2 KiB | 243.2 KiB | 253.6 KiB | | `/expr` | 7.7 KiB | 8.4 KiB | 2.4 KiB | 2.7 KiB | | `/webmap` | 24.8 KiB | 27.3 KiB | 7.6 KiB | 8.3 KiB | | `/geocoding` | 25.1 KiB | 31.6 KiB | 7.3 KiB | 9.1 KiB | | `/routing` | 18.7 KiB | 24.6 KiB | 6.0 KiB | 7.6 KiB | | `/auth` | 24.1 KiB | 30.6 KiB | 7.0 KiB | 8.7 KiB | | `/style` | 59.1 KiB | 69.0 KiB | 14.6 KiB | 17.2 KiB | | `/map` | 164.6 KiB | 182.2 KiB | 46.0 KiB | 50.7 KiB | | `/geoparquet` (duckdb-wasm external — lazy peer) | 46.6 KiB | 53.6 KiB | 14.7 KiB | 16.8 KiB | | `/deckgl` (deck.gl external — lazy peer) | 15.0 KiB | 16.5 KiB | 5.0 KiB | 5.6 KiB | | `/react` (react/react-dom external) | 432.7 KiB | 446.7 KiB | 114.3 KiB | 117.2 KiB | | `/geometry` (turf/proj4 bundled — real consumer cost) | 516.4 KiB | 568.0 KiB | 142.7 KiB | 157.0 KiB | | browser IIFE (`./browser` unpkg/jsdelivr) | 423.5 KiB | 426.0 KiB | 110.8 KiB | 112.8 KiB | | browser ESM (`./browser`) | 422.2 KiB | 424.6 KiB | 110.6 KiB | 112.5 KiB | | tree-shake guard (`{ HonuaClient }` only) | 210.5 KiB | 229.7 KiB | 53.2 KiB | 57.6 KiB | | tree-shake guard (`{ connect }` from root, source-schema runtime excluded) | 345.7 KiB | 359.2 KiB | 89.0 KiB | 92.8 KiB | | tree-shake guard (`{ evaluateCapabilityProfile }` only, CRS/PROJJSON validator excluded) | 16.3 KiB | 17.9 KiB | 5.7 KiB | 6.2 KiB | | tree-shake guard (`{ FeatureLayerCompat }` from `/esri-compat`) | 225.3 KiB | 245.9 KiB | 56.6 KiB | 61.4 KiB | | tree-shake guard (`{ buffer }` from `/geometry`, turf bundled) | 287.5 KiB | 316.3 KiB | 65.6 KiB | 72.2 KiB | | tree-shake guard (`{ mountSourceToMapLibre }` from `/map`) | 33.3 KiB | 37.7 KiB | 10.8 KiB | 12.0 KiB | | tree-shake guard (`{ bindTerraDrawSketch }` from `/runtime`, terra-draw external) | 3.3 KiB | 3.3 KiB | 1.5 KiB | 1.5 KiB | --- # File: docs/guide.md # `@honua/sdk-js` reference guide This long-form guide collects the runnable demos, server compatibility contract, subpath entrypoints, protocol-specific cookbooks, MapLibre runtime, request/auth bridge, migration CLI, and other reference material that used to live in the project README. Skim the [README](../README.md) for the 60-second tour and the [`docs/`](.) directory for topic-specific docs. ## Contents ### Getting set up - [Demo apps in depth](#demo-apps-in-depth) - [Install](#install) - [Local development](#local-development) - [Verify](#verify) - [Server compatibility baseline](#server-compatibility-baseline) - [Entrypoints](#entrypoints) - [Split package artifacts](#split-package-artifacts) ### Core surfaces - [Shared client contract and exploration](#shared-client-contract-and-exploration) - [Standalone data-to-map bridge](#standalone-data-to-map-bridge) - [MapLibre GL JS runtime for `MapPackage`](#maplibre-gl-js-runtime-for-mappackage) - [Generated app preview runtime](#generated-app-preview-runtime) - [Request/auth bridge](#requestauth-bridge) - [Streaming pagination](#streaming-pagination) - [Event lifecycle (`.on`)](#event-lifecycle-on) ### Protocol cookbooks - [OGC API Features (Honua-first)](#ogc-api-features-honua-first) - [OGC API Tiles, Maps, Processes, STAC](#ogc-api-tiles-maps-processes-stac) - [WFS 2.0](#wfs-20) - [OData v4](#odata-v4) - [Mixed Esri + OGC in one app](#mixed-esri--ogc-in-one-app) - [MapServer query helpers](#mapserver-query-helpers) - [TimeSlider integration](#timeslider-integration) ### Migration tooling - [Migration CLI](#migration-cli) - [Migration admin scanner](#migration-admin-scanner) - [Esri sample corpus (#206)](#esri-sample-corpus-206) - [FeatureTable demo lane (#327)](#featuretable-demo-lane-327) ## Demo apps in depth > The committed quickstart app uses the same `queryFeatures()` request shape shown in > the [README quickstart](../README.md#60-second-quickstart) and fails fast when > compatibility is > unsupported, the query returns no features, or none of the returned records survive > conversion into the rendered point, line, or polygon geometry buckets. - [`examples/maplibre-quickstart/`](./examples/maplibre-quickstart/README.md): committed MapLibre quickstart app with a deterministic fixture-backed mock lane, one compatibility check, one read-only feature query, popup inspection, browser telemetry, and a matching staging integration suite that reuses the same compatibility-plus-query data-loading path. - [`examples/react-quickstart/`](./examples/react-quickstart/README.md): `@honua/react` quickstart — `HonuaProvider` + `useDataset`/`useQuery`/`useCapabilities` hooks and a `HonuaMap`/`HonuaLayer`/`HonuaPopup` composition over the same deterministic fixture lane, booted under React StrictMode with Playwright smoke coverage. - [`examples/storytelling-25d-map/`](./examples/storytelling-25d-map/README.md): pitched `2.5D` MapLibre demo with Honua compatibility gating, same-origin fixture mocking, OGC collection overlays, polygon extrusions, and route replay. - [`examples/kepler-analytics/`](./examples/kepler-analytics/README.md): fixture-first kepler.gl analytics demo for an `operations replay` workflow with committed GeoJSON plus metadata, KPI cards, walkthrough copy, and focused browser smoke coverage. - [`examples/imagery-cog-quickstart/`](./examples/imagery-cog-quickstart/README.md): MapLibre imagery proof for WMS `GetMap`, COG-backed ImageServer tiles, `exportImage` previews, legends, and metadata cache state through one Honua client configuration. - [`examples/spatial-analytics-workbench/`](./examples/spatial-analytics-workbench/README.md): Honua Cloud analytics workbench for AOI jobs, materialized outputs, linked map/table/chart state, and fixture-backed indexed aggregation cells plus category/histogram/range widgets. - [`examples/edit-workflow-demo/`](./examples/edit-workflow-demo/README.md): Honua Cloud editing workflow for metadata-backed forms, optimistic create/update/delete, rollback diagnostics, conflicts, relationships, and attachment lifecycle checks over shared map/table/form context. - [`examples/geocoding-quickstart/`](./examples/geocoding-quickstart/README.md): MapLibre geocoding sample for forward geocoding, reverse lookup from a clicked point, typeahead suggestions, and GeocodeServer audit mapping through `HonuaGeocodingClient`. - [`examples/terrain-rgb-elevation/`](./examples/terrain-rgb-elevation/README.md): MapLibre Terrain-RGB elevation proof with fixture-safe DEM tiles, clicked point elevation lookup, drawn line profile queries, and explicit SDK gap notes for untyped terrain value/profile endpoints. - [`examples/unified-ops-workspace/`](./examples/unified-ops-workspace/README.md): fixture-backed operational workspace shell that composes incident command and analysis review modules over one shared app workspace, linked-view context, realtime state, review drafts, and saved snapshot diagnostics. - [`docs/examples/cesium-route-playback/README.md`](./docs/examples/cesium-route-playback/README.md): exploratory Cesium route-playback spike that consumes one bounded Honua `FeatureServer/query` response, keeps the preprocessing steps explicit, and stays outside the SDK's `SceneViewCompat` and WebMap 3D support contract. Each example README documents its own env surface, network contract, browser telemetry hooks, run lanes, accepted data contracts, live-query narrowing rules, preprocessing rules, and browser diagnostics. The shared seeded Honua Cloud demo contract lives in [`docs/honua-cloud-demo-services.md`](./docs/honua-cloud-demo-services.md), with the machine-readable manifest at [`examples/cloud-demo-services.json`](./examples/cloud-demo-services.json) and env template at [`examples/cloud-demo.env.example`](./examples/cloud-demo.env.example). Use `npm run test:cloud-demo:config` to validate the config/docs shape without live credentials, and `npm run test:cloud-demo:staging` for the credential-gated cloud smoke scaffold. For the Cesium spike specifically, `window.__cesiumRoutePlaybackDone` is the completion signal on both success and failure, `window.__cesiumRoutePlaybackError` is failure-only, and `window.__cesiumRoutePlaybackResult` is populated only on success. Its `queryRequest` summary echoes `fixtures/source-manifest.json#query` in fixture mode and the bounded live `queryFeatures()` request in live mode; both describe the same `outFields=["*"]`, `outSr=4326`, `returnGeometry=true`, and `extraParams={ outSr: 4326, returnZ: true }` query shape, while `routeId` and `routeIdField` remain post-query selectors instead of extra server filters, `routeIdField` is authoritative when configured, matching normalizes numeric route ids to strings, the success summary leaves `routeId` as `null` when the selected feature has no route-id attribute, and fixture mode keeps `compatibilitySupported` plus `requestDurationMs` as `null`. The kepler example README documents the fixture metadata manifest, required dataset IDs and fields, the default incident status and replay-window filters, browser readiness/error plus replay-harness hooks, refresh stdout JSON, and the runtime style override env vars used by the demo. Deterministic local review flows from this repo: ```bash # Node.js 20.19.0+ at the repo root npm install # Run either mock server in its own terminal/session. npm run demo:quickstart:mock # or npm run demo:25d:mock # or npm run demo:geocoding:mock ``` The quickstart command prints `quickstartMockUrl=http://127.0.0.1:PORT`, the 2.5D command prints `story25dMockUrl=http://127.0.0.1:PORT`, and the geocoding command prints `geocodingMockUrl=http://127.0.0.1:PORT`. Live Honua flow for the `2.5D` demo: ```bash cp examples/storytelling-25d-map/.env.example examples/storytelling-25d-map/.env npm run demo:25d ``` Use the linked example READMEs for the `2.5D` collection contract, the Cesium live-query URL parameters, custom `routeIdField` matching and multi-route selection rules, terrain fallback behavior, and smoke-test globals. ## Server Compatibility Baseline Use the server compatibility contract before enabling admin/control-plane flows: ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://your-honua-server.com" }); const status = await client.checkCompatibility(); if (!status.supported) { throw new Error( `Server ${status.compatibility?.serverVersion ?? "unknown"} is unsupported. ` + `Minimum: ${HonuaClient.minimumSupportedServerVersion}. ` + `Reasons: ${status.reasons.join("; ")}`, ); } if (await client.supportsFeature("manifestApply")) { console.log("Manifest apply workflows are available on this server."); } const compatibilityContract = await client.getCompatibility(); console.log(compatibilityContract.metadataSchemas); ``` `checkCompatibility()` reports support status, `supportsFeature()` gates coarse capabilities from `data.compatibility.features`, and `getCompatibility()` returns the parsed `data.compatibility` object from `GET /api/v1/admin/capabilities`. The capabilities endpoint still needs to return a JSON object with `success` plus `data.compatibility`. The parsed compatibility object must include `serverVersion`, `releaseChannel`, `controlPlaneApi.major`/`basePath`/`deprecated`, `metadataSchemas[]` entries with `version` and `deprecated`, and the boolean `features` map. Top-level extras such as `metadataApiVersions` and `resourceKinds` may be present on the endpoint response, but they are not returned by `getCompatibility()`. This SDK baseline currently expects: - server version `>= 1.0.0` - control-plane API major integer `1` with base path `/api/v1/admin` - control-plane API deprecation flag `false` - server release channel `preview` or newer --- Initial JavaScript SDK scaffold for the JS-first migration phase (`#324`). This package currently provides: - core HTTP client (`HonuaClient`) for FeatureServer, MapServer export/query/related-record operations, and catalog operations, plus fluent layer wrappers (`client.featureLayer(...)`, `client.mapLayer(...)`, `service.featureLayer(...)`, `service.featureLayers()`, `service.mapLayer(...)`, `service.mapLayers()`, `service.mapService().layer(...)`), - first-class OGC API clients/wrappers for Features (`client.ogcFeatures()`), Tiles (`client.ogcTiles()`), Maps (`client.ogcMaps()`), Processes (`client.ogcProcesses()`), and STAC (`client.stac()`), including landing/conformance discovery, feature items, tile and map bytes, async `IJobRun` process execution, and STAC search, - first-party OGC web-map clients/wrappers for WMS 1.3.0 (`client.wms(serviceId)` → `HonuaWms` / `HonuaWmsLayer`) and WMTS 1.0.0 (`client.wmts(serviceId)` → `HonuaWmts` / `HonuaWmtsLayer` / `HonuaWmtsTileset`) covering Capabilities, `GetMap` (with `TIME` / `ELEVATION` dimension handling and CRS axis-order swap per WMS 1.3 §6.7.3.2), `GetFeatureInfo`, `GetLegendGraphic` (when the server advertises it; otherwise `HonuaCapabilityNotSupportedError`), RESTful + KVP tile fetch, plus MapLibre source helpers `buildWmsRasterSourceSpec(descriptor)` / `buildWmtsRasterSourceSpec(descriptor)` from `@honua/sdk-js/runtime`, - dynamic query tile descriptors and MapLibre helpers (`defineQueryTileSource`, `buildMapLibreQueryTileSourceSpec`, `QueryTileRequestController`) for query-backed vector tiles with cache key normalization, viewport request aborts, feature identity mapping, selected-feature detail lookup, and unsupported-protocol/fallback diagnostics, - Esri-style compatibility wrappers (`FeatureLayerCompat`, `MapImageLayerCompat`, `TileLayerCompat`, `RouteLayerCompat`, `MapCompat`, `MapViewCompat`, `SceneViewCompat`, `WebMapCompat`) for migration-critical patterns, including basic `when()` lifecycle support, `FeatureLayer.refresh()/createQuery()/queryFeaturesAll()/queryObjectIds()/queryFeatureCount()/queryExtent()/queryRelatedFeatures()/addAttachment()/updateAttachment()/listFields()/getField()`, `MapImageLayer.when()/refresh()/createQuery()/exportImage()/getLegend()/find()/identify()/queryFeatures()/queryFeaturesAll()/queryFeatureCount()/queryObjectIds()/queryExtent()/queryRelatedFeatures()/findSublayerById()/sublayer(...).query*()` where writable `layer.sublayers` and sublayer lookups return query-capable `MapImageSublayerCompat` wrappers (and auto-hydrate from metadata when not explicitly configured) with nested `sublayer.sublayers/allSublayers`, `sublayer.visible`, and `sublayer.definitionExpression` bridging to query defaults, `FeatureTableCompat` row/query helpers with runtime `layer` switching (`table.layer = nextLayer` / `table.setLayer(nextLayer)`), `Map` layer collection helpers, `GraphicsLayerCompat`/`GroupLayerCompat`, and `MapView` watch/event handles with popup/layer-view bridges plus `toMap`/`toScreen`/`hitTest`/`takeScreenshot()` and `view.ui.add/remove/move/getComponents` compatibility, - identify controller (`IdentifyCompat`) for cross-layer MapServer identify workflows with optional popup auto-open, - compat widgets/components (`LayerListCompat`, `LegendCompat`, `PopupCompat`, `SearchCompat`, `BasemapGalleryCompat`, `BookmarksCompat`, `ExpandCompat`, `SketchCompat`, `EditorCompat`, `TrackCompat`, `MeasurementCompat`, `TimeSliderCompat`, `DirectionsCompat`) backed by a shared `CompatEventBus` so widgets/components can subscribe to layer/view changes, including popup feature-selection navigation and search source/result state helpers (default search sources support both ArcGIS `queryFeatures` layers and OGC collection-style `items()` layers), - common map controls (`HomeCompat`, `BasemapToggleCompat`, `LocateCompat`, `ScaleBarCompat`, `CompassCompat`, `FullscreenCompat`, `ZoomCompat`, `AttributionCompat`) wired to the same event bus for shared view state updates, - request/auth migration bridge helpers (`createEsriRequestInterceptors`, `createArcGisTokenInterceptor`) plus core `HonuaClient` interceptor hooks (`before`/`after`/`error`), - URL parsing helpers for ArcGIS FeatureLayer endpoint detection, - ArcGIS usage scanner (`scanArcGisUsage`) for migration inventory and risk flags, - safe codemod runner (`runEsriCompatCodemod`) for migration-safe constructors across layers, views, widgets, and controls, - migration report builder with explicit manual TODOs and rewrite metric, - JS parity matrix artifacts (`getJsParityMatrix` / `summarizeJsParityMatrix` and `getJsRuntimeParityMatrix` / `summarizeJsRuntimeParity`) for constructor-level and runtime-capability `native/compat/assisted/unsupported` tracking across Honua compat and esri-leaflet targets, - service reconciliation helper (`runLayerReconciliation`) for feature-count, geometry-validity, and attribute-key checks, - unit tests for request mapping and URL parsing, - WebMap JSON conversion utilities (`parseWebMap`, renderer/symbol/popup converters) with a golden fixture suite and compatibility contract documented in [`docs/webmap-json-compatibility.md`](./docs/webmap-json-compatibility.md). ## Entrypoints Prefer subpath entrypoints to keep Honua-first and migration layers separate: - Honua-first core: `@honua/sdk-js/honua` - Esri compat bridge: `@honua/sdk-js/esri-compat` - Migration tooling: `@honua/sdk-js/migration` - Canonical shared client contract: `@honua/sdk-js/contract` - Exploration state + linked-view presets: `@honua/sdk-js/exploration` - MapLibre GL JS runtime for `MapPackage`: `@honua/sdk-js/runtime` - React bindings (provider, hooks, map components): `@honua/sdk-js/react` — see [`docs/react.md`](./react.md) - Client-side geometry ops + reprojection (curated turf/proj4): `@honua/sdk-js/geometry` — see [`docs/geometry.md`](./geometry.md) - Agent tool surface (bounded JSON-Schema map tools + executor, MCP/OpenAI compatible; stable tier): `@honua/sdk-js/agent-tools` — see the [agent-safety threat model](./agent-safety-threat-model.md) - Agent safety boundary (signed approvals, effect budgets, single-use consumption, receipts; stable tier): `@honua/sdk-js/agent-safety` — see [`docs/agent-safety.md`](./agent-safety.md) and the [threat model](./agent-safety-threat-model.md) - Natural-language map control (plan-first, BYO LLM, approval envelopes, receipts): `@honua/sdk-js/nl-map-control` — see [`docs/nl-map-control.md`](./nl-map-control.md) - Provider-pluggable geocoding (Nominatim/Photon/Pelias/Honua) + routing (OSRM/Valhalla/Honua): `@honua/sdk-js/geocoding`, `@honua/sdk-js/routing` — see [`docs/geocoding-routing-providers.md`](./geocoding-routing-providers.md) - Generated operations-dashboard manifest projection and preview runtime: `@honua/sdk-js/generated-app` - Studio package-family projections, validation/preview envelopes, capability manifest, and publish/share/embed contracts (MCP/QGIS-safe): `@honua/sdk-js/studio` — see [`docs/studio-package-contracts.md`](./studio-package-contracts.md) The root entrypoint (`@honua/sdk-js`) remains available as an aggregate export for compatibility. Surfaces documented as subpath-only, including `@honua/sdk-js/generated-app`, should be imported from their named subpath. ## Shared Client Contract And Exploration `HonuaFeatureLayer`, `HonuaMapService`, and `HonuaOgcFeatureCollection` continue to be the runtime classes. For cross-protocol code — exploration views, visual builders, and server packaging — the SDK also exposes a protocol-neutral contract and exploration state module that wrap (not replace) those classes. - `@honua/sdk-js/contract` — canonical `Dataset`, `Source`, `SourceDescriptor`, `Capabilities`, `Query`, `Result`, `IJobRun`, and `MapBinding` types, plus `createDataset(...)` and built-in adapters for the five GeoServices service types (`geoservices-feature-service`, `geoservices-map-service`, `geoservices-image-service`, `geoservices-geometry-service`, `geoservices-gp-service`), the four OGC API + STAC adapters (`ogc-features`, `ogc-tiles`, `ogc-maps`, `stac`), the OGC web-map adapters (`wms`, `wmts`), `wfs` (WFS 2.0), and `odata` (OData v4). Image / Geometry / GP services expose their protocol-specific surface (raster `exportImage` / `identify`, geometry `project` / `buffer` / `simplify` / `intersect` / `union` / `clip` / `difference`, GP `submitJob` / `jobStatus` / `cancelJob` / `jobResult`) through the typed `Source.protocol()` escape hatch — the canonical query family throws `HonuaCapabilityNotSupportedError` for utility-only services so mixed-source apps surface the limitation explicitly. The ImageServer adapter rejects `Query.spatialFilter` / `orderBy` / `outFields` rather than silently widening the catalog result. WMS surfaces `query` through point-only `GetFeatureInfo`; WMTS is render-only (`Source.query()` throws). The WFS adapter compiles `Query.where` / `Query.spatialFilter` to FES 2.0, prefers GeoJSON over GML via `OperationsMetadata` negotiation, builds `<wfs:Transaction>` bodies for `applyEdits`, and reaches raw GML / `LockFeature` / `GetPropertyValue` / stored queries through `Source.protocol("wfs")`. The OData adapter exposes `query` / `queryObjectIds` / `stream` / `applyEdits` first-party (PATCH-with-full-body in place of PUT, per the parity matrix) and surfaces `$batch` / `$apply` / `$search` / `$deltatoken` through `Source.protocol("odata")` on a `HonuaOdataEntitySet`; it is also the first adapter to lazily fetch service `$metadata` and intersect the declared capability set with the server's `Capabilities.*` annotations. Capability negotiation is `strict` by default; `degraded` opts into client-side fallbacks that surface `Result.degraded[]`. Full contract reference: [`docs/shared-client-contract.md`](./docs/shared-client-contract.md). - `@honua/sdk-js/exploration` — `createExplorationContext(...)` returning an observable, microtask-coalesced reducer over filters, spatial filter, extent, selection, sort, pagination, visible fields, grouping, and aggregation. View bindings (`map`, `grid`, `chart`, `form`, `custom`) propagate through five linked-view presets (`globalLinked`, `mapDriven`, `gridDriven`, `chartDriven`, `decoupled`). Full state model and worked example: [`docs/exploration-context.md`](./docs/exploration-context.md). - Capability coverage per protocol: [`docs/protocol-capability-matrix.md`](./docs/protocol-capability-matrix.md). - Cross-SDK semantic alignment for JS/Python/.NET language bindings: [`docs/sdk-surface-alignment.md`](./docs/sdk-surface-alignment.md). - Round-trip mapping to the server `SourceBinding` / `MapPackage` document: [`docs/source-binding-alignment.md`](./docs/source-binding-alignment.md). - Live SDK ↔ Honua Server protocol integration lane: [`docs/integration-tests.md`](./docs/integration-tests.md). ```ts doc-test=compile import { createDataset } from "@honua/sdk-js/contract"; import { createExplorationContext } from "@honua/sdk-js/exploration"; import { HonuaClient } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://your-honua-server.example" }); const dataset = createDataset({ id: "parcels", client, sources: [ { id: "parcels-fs", protocol: "geoservices-feature-service", locator: { url: "https://your-honua-server.example", serviceId: "parcels", layerId: 0 }, capabilities: new Set(["query", "queryExtent", "queryObjectIds"]), }, ], }); const parcels = dataset.source("parcels-fs")!; const result = await parcels.query({ where: "STATUS = 'ACTIVE'", pagination: { limit: 100 } }); const { extent } = await parcels.queryExtent({ where: "STATUS = 'ACTIVE'" }); const ctx = createExplorationContext({ datasetId: dataset.id, sourceIds: dataset.sourceIds(), preset: "mapDriven", }); ctx.bind({ id: "map", role: "map" }); if (extent) ctx.dispatch({ kind: "set-extent", extent, viewId: "map" }); console.log(`Loaded ${result.features.length} features`); ``` Capability misses throw `HonuaCapabilityNotSupportedError` (under `strict` policy). Exploration misuses throw `HonuaExplorationContextError`. Both are in the `HonuaError` union and pass `isHonuaError(e)`. ## Standalone Data-To-Map Bridge `mountSource(map, source, options)` from `@honua/sdk-js/map` (`@experimental`) mounts any contract `Source` as a live, styled MapLibre layer set with no MapPackage and no Honua server — the standalone slice of the kernel ADR's `connection.mount(target)` contract. The bridge selects bounded GeoJSON materialization or the dynamic query-tile path from declared capabilities plus a result-size heuristic, applies geometry-appropriate default styling, wires optional click popups and hover feature-state, and returns one disposable handle whose `setFilter()`/`refresh()` diff-update in place. ```ts doc-test=skip reason="partial excerpt requires application host context" import maplibregl from "maplibre-gl"; import { connect } from "@honua/sdk-js"; import { mountSource } from "@honua/sdk-js/map"; const data = await connect({ endpoint: FEATURE_LAYER_URL, protocol: "auto", authorizationScopeFingerprint: "public" }); const mounted = await mountSource(map, data.source(), { popup: { factory: () => new maplibregl.Popup() }, hover: true, fitBounds: true, }); console.log(mounted.diagnostics.strategy, mounted.diagnostics.reasons); mounted.dispose(); ``` - Full cookbook (strategy selection, options, disposal, overflow diagnostics): [`docs/data-to-map-bridge.md`](./data-to-map-bridge.md). - Runnable fixture/live demo: [`examples/endpoint-to-map/`](../examples/endpoint-to-map/README.md). - First-class renderer objects (`classBreaksRenderer`, `uniqueValueRenderer`, `heatmapRenderer`, `clusterRenderer` on `/style`), `mountSource({ renderer })` + `setRenderer()` swaps, and temporal playback (`createTemporalPlayback` on `/map`): [`docs/renderers.md`](./renderers.md). ## MapLibre GL JS Runtime For `MapPackage` `@honua/sdk-js/runtime` binds a server-produced `MapPackage` (from `honua-io/honua-server#731`) to a caller-provided `maplibre-gl.Map`. It composes the style from `mapSpec` + `styleRefs[]` + `theme` tokens, projects `sourceBindings[]` through the `@honua/sdk-js/contract` adapters, and exposes an operational API that `honua-io/honua-sdk-js#22` and `#29` build on. The runtime never instantiates the map (`maplibre-gl` stays a peer dependency) and never issues edit writes. ```ts doc-test=skip reason="partial excerpt requires application host context" import maplibregl from "maplibre-gl"; import { HonuaClient } from "@honua/sdk-js/honua"; import { loadMapPackage } from "@honua/sdk-js/runtime"; const map = new maplibregl.Map({ container: "map", style: { version: 8, sources: {}, layers: [] } }); const runtime = await loadMapPackage(pkg, map, { client: new HonuaClient({ baseUrl: "https://your-honua-server.example" }), popupFactory: () => new maplibregl.Popup(), }); runtime.setLayerVisibility("parcels-fill", true); runtime.bindPopup("parcels-fill"); await runtime.updatePackage(nextPkg); // diffs by stable ids, falls back to setStyle on structural change runtime.dispose(); ``` - Full runtime reference: [`docs/maplibre-runtime.md`](./docs/maplibre-runtime.md). - Protocol routing (server `SourceBinding` → MapLibre / contract adapter): [`docs/source-binding-alignment.md`](./docs/source-binding-alignment.md#runtime-consumer-honuasdk-jsruntime). - `MapPackage` format tag: `honua_map_package.v1`. The loader throws `HonuaMapPackageError { stage: "load" }` on any other value, and `updatePackage` rejects format mismatches without mutating the map. Binding failures throw `HonuaMapPackageError` with a `stage` of `"load" | "update" | "style-compose" | "source-bind" | "view" | "popup" | "dispose"` under the opt-in `sourceErrorPolicy: "fail-fast"`. Under the default `"tolerant"` policy a single per-source binding failure does not abort the load — the failed source is dropped from the composed style along with any layer that referenced it, the runtime emits a `source-error` event for the failed source, and a `source-bind` telemetry error span fires. Remaining sources keep rendering. Query-time adapter errors (`HonuaCapabilityNotSupportedError`, `HonuaHttpError`, adapter-specific classes) are not wrapped — they surface on the per-`Source` promises from `runtime.dataset` and through the shared `HonuaClient` interceptor chain; consumers fanning a query across the dataset can broadcast a per-source rejection through `runtime.reportSourceError(sourceId, error)` to fold it into the same `source-error` channel. For mixed-protocol compositions (parcels FeatureServer + WMS basemap + STAC overlay + OData operational layer in one map), use `intersectCapabilities` from `@honua/sdk-js/contract` to compute the **weakest** capability set across participating sources before fanning a call out, and rely on `Result.degraded[]` entries (now carrying optional `sourceId`) for per-source attribution. Full composition guide: [`docs/composition.md`](./docs/composition.md). ## Generated App Preview Runtime `@honua/sdk-js/generated-app` is the browser-safe proof slice for generated operations dashboards. It projects canonical `BuildSpec`, `AppPackage.manifest_artifact`, and `MapPackage` inputs into a versioned `honua_generated_app_manifest.v1` manifest with the `operations-dashboard.v1` profile, then binds the generated map/table or list/count/chart/filter widgets through `@honua/sdk-js/runtime` and the shared `ExplorationContext`. ```ts doc-test=skip reason="partial excerpt requires application host context" import { previewGeneratedApp } from "@honua/sdk-js/generated-app"; const preview = await previewGeneratedApp( { appPackage, mapPackage }, { mapFactory: () => ({ map }), mapLoadOptions: { client }, }, ); if (preview.status === "ready") { renderDashboard(preview.model); } else { renderPreviewErrors(preview.errors); } ``` The preview response is a discriminated union: ready responses include the resolved manifest, runtime handle, render model, and `errors: []`; error responses include serializable `HonuaGeneratedAppDiagnostic` objects and never throw from `previewGeneratedApp`. Call `loadGeneratedAppRuntime` directly when the host wants exceptions. Full contract reference: [`docs/generated-app-runtime.md`](./docs/generated-app-runtime.md). For map-backed manifests, the host must provide a `MapPackage`, `mapFactory`, and `mapLoadOptions`; when `manifest.mapPackageId` is present, the supplied `MapPackage.mapPackageId` must match before map construction. Map filter bindings use the widget `layerId` with `manifest.bindings.layerId` as fallback, and failed initial feature loads dispose partially loaded map resources before returning an error result. ## Install ```bash npm install @honua/sdk-js ``` ## Local development Repo-root installs for local development and the checked-in browser demos currently require Node.js 20.19.0 or newer because the current demo/dev toolchain dependencies set that patch-level floor. The published `@honua/sdk-js` package itself remains on the documented Node 20+ runtime contract. ```bash npm install ``` Storytelling demo loops: ```bash npm run demo:quickstart:mock # or, with examples/maplibre-quickstart/.env configured: npm run demo:quickstart # advanced storytelling demo: npm run demo:25d:mock # or, with examples/storytelling-25d-map/.env configured: npm run demo:25d ``` Advanced analytics demo loop: ```bash npm run demo:kepler:install npm run demo:kepler:dev ``` Open `http://127.0.0.1:4175` to view the fixture-first `operations replay` story. The committed fixture lives under `examples/kepler-analytics/public/data`, and maintainers can refresh it from a live Honua environment with: ```bash npm run demo:kepler:refresh-fixture ``` The repo-root refresh wrapper builds the SDK before delegating to the example-local script. Set `HONUA_DEMO_BASE_URL` and any optional auth or service override env vars described in the example README before running it. Imagery and COG demo loop: ```bash npm run demo:imagery-cog:mock # or, with examples/imagery-cog-quickstart/.env configured: npm run demo:imagery-cog ``` Node backend quickstart loop: ```bash npm run demo:node-backend:mock # in another terminal: npm run demo:node-backend ``` ## Verify ```bash npm run typecheck npm run build npm run demo:quickstart:typecheck npm run demo:25d:typecheck npm run demo:node-backend:typecheck npm run demo:unified-ops:typecheck npx vitest run test/quickstart-config.test.ts test/quickstart-data.test.ts npx vitest run test/node-backend-quickstart.test.ts npx vitest run test/unified-ops-workspace.test.ts npx vitest run test/cesium-route-playback.test.ts npx vitest run test/storytelling-25d-config.test.ts test/storytelling-25d-data.test.ts npm test npm run test:playwright:quickstart npm run test:playwright:unified-ops npx playwright test test/playwright/cesium-route-playback.spec.mjs npm run test:playwright:25d npm run test:playwright npm run demo:kepler:smoke npm run test:quickstart:staging # requires HONUA_STAGING_* env npm run test:integration # connect-only; requires HONUA_INTEGRATION_BASE_URL — see docs/integration-tests.md npm run scan:arcgis -- ../../path/to/arcgis-app npm run migrate:arcgis -- ../../path/to/arcgis-app --write --report migration-report.json npm run report:migration:real-samples npm run gate:migration:real-samples npm run gate:migration:demo-target npm run matrix:runtime npm run build:split-packages ``` `npm run test:playwright` and `npm run demo:kepler:smoke` now bootstrap the isolated `examples/kepler-analytics` dependencies automatically when that package has not been installed yet. ## Split Package Artifacts Generate publish-ready split packages under `dist/packages/`: - `@honua/sdk` -> `dist/packages/honua-sdk` - `@honua/sdk-esri-compat` -> `dist/packages/honua-sdk-esri-compat` - `@honua/honua-migrate` -> `dist/packages/honua-migrate` ```bash npm run build:split-packages npm run verify:split-packages ``` Create local tarballs for all split packages: ```bash npm run pack:split-packages ``` CI publish workflow: - manual dry-run or publish via `Publish JS SDK Packages` workflow - tag-triggered publish uses Release Please tags in form `js-sdk-<version>`; the workflow also accepts `js-sdk-v<version>` and enforces tag/version match - Release Please dispatches the JS SDK and MCP publish workflows after creating releases; package publishes skip versions that already exist on npm. ## Request/Auth Bridge ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js"; import { createArcGisTokenInterceptor, createEsriRequestInterceptors } from "@honua/sdk-js/esri-compat"; const client = new HonuaClient({ baseUrl: "https://example.test", interceptors: [ ...createEsriRequestInterceptors([ { urls: "/rest/services/default", before: (params) => { params.requestOptions.headers = { ...(params.requestOptions.headers ?? {}), "X-Migrated-By": "honua", }; }, }, ]), createArcGisTokenInterceptor({ applyTo: "/rest/services/default", mode: "query", getToken: async () => "arcgis-token-value", }), ], }); ``` For first-party Honua auth, prefer an auth provider over storing long-lived secrets in SDK configuration. The provider owns secure storage, refresh, and revocation; the SDK keeps only an in-memory cache and refreshes before `expiresAt` enters the configured skew window. ```ts doc-test=skip reason="partial excerpt requires application host context" const client = new HonuaClient({ baseUrl: "https://example.test", authRefreshSkewMs: 60_000, auth: { async getCredentials({ reason }) { const session = await authStore.getFreshSession({ force: reason !== "initial" }); return { bearerToken: session.accessToken, expiresAt: session.expiresAt, }; }, async revokeCredentials(credentials) { if (credentials.bearerToken) { await authStore.revoke(credentials.bearerToken); } }, }, }); await client.refreshAuthCredentials(); // force a key/token rotation probe await client.revokeAuthCredentials(); // revoke cached credentials and clear SDK memory ``` Do not persist bearer tokens, API keys, or refresh tokens inside the SDK instance. Store them in the platform credential store or your server-side session layer, return short-lived credentials from `auth.getCredentials`, and use `clearAuthCredentials()` on logout or account switch. If a request fails with `401`/`403`, call `refreshAuthCredentials("unauthorized")` after your app has handled any sign-in prompt, then retry the failed operation explicitly. Network, timeout, and retry behavior still flows through the same `timeoutMs`, `retry`, and interceptor pipeline. ## OGC API Features (Honua-first) ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://example.test" }); const ogc = client.ogcFeatures(); const collections = await ogc.collections(); const parcels = ogc.collection("0"); const items = await parcels.items({ limit: 100, filter: "status = 'active'" }); const allItems = await parcels.itemsAll({ pageSize: 500, maxPages: 20 }); const feature = await parcels.item({ featureId: "123" }); ``` ## OGC API Tiles, Maps, Processes, STAC The first-party OGC client covers the OGC conformance areas that operator apps need. Everything is exposed through canonical Honua types — OGC conformance class identifiers stay internal. ```ts doc-test=skip reason="partial excerpt requires application host context" import { HonuaClient } from "@honua/sdk-js/honua"; import type { IJobRun } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://example.test" }); // OGC API Tiles — vector or raster over the canonical collection-tile route const tile = await client.ogcTiles() .tileset("parcels", "WebMercatorQuad") .tile({ tileMatrix: 5, tileRow: 9, tileCol: 12 }); // OGC API Maps — server-rendered map images const map = await client.ogcMaps().map({ width: 1024, height: 1024, bbox: [-122, 37, -120, 38], collections: ["parcels", "roads"], }); // OGC API Processes — async job execution mapped onto canonical IJobRun const job: IJobRun = await client.ogcProcesses().execute({ processId: "buffer", inputs: { feature: someGeoJson, distance: 500 }, mode: "async", }); const { outputs } = await job.results(); // STAC API — cross-collection search, also available through Source.query() const search = await client.stac().search({ bbox: [-122, 37, -120, 38], collections: ["sentinel-2"], filter: "cloud_cover < 10", filterLang: "cql2-text", }); ``` ### STAC in the browser bundle `HonuaStacSearch` is part of the browser-safe `/honua` surface — import it (or call `client.stac()`) instead of hand-writing `fetch` against STAC endpoints. It is exported from the `@honua/sdk-js/honua` subpath, so it bundles with esbuild/Vite/Rollup like the rest of the client: ```ts doc-test=compile // Browser app (esbuild / Vite / Rollup). No Node-only imports. import { HonuaClient, HonuaStacSearch } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://example.test" }); // Either construct it directly… const stac = new HonuaStacSearch({ client }); // …or get the same instance from the client: const sameStac = client.stac(); const landing = await stac.landing(); const items = await stac.search({ bbox: [-122, 37, -120, 38], collections: ["sentinel-2"], datetime: "2026-01-01/2026-06-01", }); // `searchAll` paginates for you (bounded by `maxPages`): for await (const item of stac.searchStream({ collections: ["sentinel-2"] })) { // … } ``` See [`docs/ogc-api.md`](./docs/ogc-api.md) for the full developer reference, [`docs/shared-client-contract.md`](./docs/shared-client-contract.md) for the canonical `Source` / `IJobRun` model, and [`docs/protocol-capability-matrix.md`](./docs/protocol-capability-matrix.md) for capability coverage. ## WFS 2.0 ```ts doc-test=compile import { createDataset, PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { HonuaClient } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://server.honua.io" }); const dataset = createDataset({ id: "parcels", client, sources: [ { id: "parcels-wfs", protocol: "wfs", locator: { url: "https://server.honua.io/wfs", typeName: "parcels:lot", // Required for applyEdits when typeName is namespace-qualified; // bound on <wfs:Transaction xmlns:parcels="…"> so the server can // resolve the schema element. Falls back to a synthetic URN // when omitted. featureNamespace: "http://parcels.example.com/ns", }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES.wfs, }, ], }); const wfs = dataset.source("parcels-wfs")!; const result = await wfs.query({ where: "STATE = 'CA' AND ACRES > 10" }); const ids = await wfs.queryObjectIds({ where: "STATUS = 'ACTIVE'" }); // Stored-query discovery + execution stays under the typed escape hatch. const root = wfs.protocol("wfs")!.root; const storedQueries = await root.storedQueries(); ``` `Query.where` compiles to FES 2.0 (comparison, `IN`, `BETWEEN`, `LIKE`, `IS NULL`, boolean combinators); `Query.spatialFilter` becomes a KVP `bbox=` for envelope-only requests or a `<fes:Filter>` otherwise. Filters that exceed the GET budget switch to POST GetFeature with the `<fes:Filter>` body. `applyEdits` builds a single `<wfs:Transaction>` (`<wfs:Insert>` / `<wfs:Update>` / `<wfs:Delete>`) and surfaces per-handle `<fes:ResourceId>` IDs onto `EditOutcome.id`. GeoJSON is preferred over GML through `OperationsMetadata` negotiation; if the server only advertises GML the canonical surface throws `HonuaCapabilityNotSupportedError` and points callers at `Source.protocol("wfs")` for the raw payload. Full reference: [`docs/wfs.md`](./docs/wfs.md). ## OData v4 ```ts doc-test=compile import { createDataset, PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { HonuaClient } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://server.honua.io" }); const dataset = createDataset({ id: "parcels", client, sources: [ { id: "parcels-odata", protocol: "odata", // Pass `entitySet` directly — or pass `layerId` and let the // adapter derive `Layers(<layerId>)/Features` for layer-scoped // server bindings. locator: { url: "https://server.honua.io/odata", entitySet: "Parcels" }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES.odata, }, ], }); const parcels = dataset.source("parcels-odata")!; const result = await parcels.query({ where: "STATE = 'CA' AND ACRES > 10" }); const ids = await parcels.queryObjectIds({ where: "STATUS = 'ACTIVE'" }); // Dialect-specific operations stay behind the typed escape hatch. const odata = parcels.protocol("odata")!; const meta = await odata.metadata(); // `apply` accepts a literal OData v4 `$apply` transformation string // per OData v4 §5.1.4 — `groupby((<dim>),aggregate(<expr>))` is the // canonical form for SQL-style group-by + sum. const aggregated = await odata.apply( "groupby((STATE),aggregate(ACRES with sum as SumAcres))", ); ``` `Query.where` accepts SQL-92 / OData `$filter` text; the adapter rewrites the documented intersection (`IS NULL` → `eq null`, `<>` → `ne`, `=` → `eq`, plus the SQL comparison operators `>=` / `<=` / `>` / `<` → `ge` / `le` / `gt` / `lt`) and rejects operators the parity matrix marks unsupported (`has`, `in`, `any`, `all`, `cast`, `isof`). `Query.outFields` splits onto `$select` for plain field names and `$expand` for navigation paths — `["Owner.name"]` lowers to `$expand=Owner($select=name)` so related properties round-trip through the canonical request envelope. `Query.spatialFilter` translates to `geo.intersects` / `geo.distance` against the geometry column resolved from `SourceDescriptor.schema.fields` (typed `esriFieldTypeGeometry`) first, then the lazy `$metadata` probe. `applyEdits` routes adds → `POST`, updates → `PATCH /<entitySet>(<key>)` with the full canonical body (PUT is unsupported per the parity matrix), deletes → `DELETE /<entitySet>(<key>)`. When `EditEnvelope.rollbackOnFailure: true` and `$metadata` advertises `Capabilities.BatchSupported`, all operations collapse into one `$batch` request with a shared `atomicityGroup`. OData is the **first adapter** to lazily fetch service `$metadata` and intersect declared capabilities against the server's `Capabilities.*` annotations — see [`docs/protocol-capability-matrix.md`](./docs/protocol-capability-matrix.md) for the rule and [`docs/decisions/odata-library-selection.md`](./docs/decisions/odata-library-selection.md) for the runtime-library posture. ## Mixed Esri + OGC in one app ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://example.test" }); const parcelsLayer = client.service("transport").featureLayer(0); const parcelsOgc = client.ogcFeatures().collection("parcels"); const [features, items] = await Promise.all([ parcelsLayer.queryFeatures({ where: "status = 'active'", outFields: ["OBJECTID"] }), parcelsOgc.items({ limit: 50 }), ]); ``` ## MapServer query helpers ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://example.test", timeoutMs: 15000, retry: { maxRetries: 2, retryStatuses: [429, 503] }, }); const mapLayer = client.mapLayer("basemap", 4); const allMapLayerFeatures = await mapLayer.queryFeaturesAll({ pageSize: 2000, maxPages: 25 }); const mapService = client.mapService("basemap"); const allServiceLayerFeatures = await mapService.queryLayerFeaturesAll({ layerId: 4, pageSize: 2000, maxPages: 25, }); const related = await mapService.queryLayerRelatedRecords({ layerId: 4, relationshipId: 1, objectIds: [1001, 1002], }); const mapLayerRelated = await mapLayer.queryRelatedFeatures({ relationshipId: 1, objectIds: [1001], }); ``` ## Streaming Pagination ```ts doc-test=compile import { FeatureLayerCompat, CompatEventBus } from "@honua/sdk-js/esri-compat"; const layer = new FeatureLayerCompat({ url: "https://example.test/rest/services/transport/FeatureServer/0", }); // Collect all pages in one call const allFeatures = await layer.queryFeaturesAll({ pageSize: 500, maxPages: 50 }); // Stream pages one at a time with an async generator for await (const page of layer.queryFeaturesStream({ pageSize: 500 })) { console.log(`Received ${page.length} features`); } ``` ## Event Lifecycle (.on) ```ts doc-test=compile import { FeatureLayerCompat, CompatEventBus } from "@honua/sdk-js/esri-compat"; const eventBus = new CompatEventBus(); const layer = new FeatureLayerCompat({ url: "https://example.test/rest/services/transport/FeatureServer/0", eventBus, }); // Listen for edit completions const handle = layer.on("edits", (result) => { console.log("Edits applied:", result); }); await layer.applyEdits({ adds: [{ attributes: { name: "New" } }] }); // Clean up when done handle.remove(); ``` ## TimeSlider Integration ```ts doc-test=compile import { FeatureLayerCompat, TimeSliderCompat, CompatEventBus } from "@honua/sdk-js/esri-compat"; const eventBus = new CompatEventBus(); const layer = new FeatureLayerCompat({ url: "https://example.test/rest/services/events/FeatureServer/0", eventBus, }); const slider = new TimeSliderCompat({ eventBus, timeExtent: { start: new Date("2024-01-01"), end: new Date("2024-06-01") }, stops: { interval: { value: 1, unit: "days" } }, }); // Connect slider to layer — time extent changes auto-filter queries const connection = slider.connectLayer(layer); // Queries now include the time parameter automatically const features = await layer.queryFeatures({ where: "1=1" }); // Disconnect when done connection.remove(); ``` ## Migration CLI ```bash # Scan only node dist/src/migration/cli.js scan ./src --report scan-report.json # Widget-usage inventory + ArcGIS 6.0 readiness report (classic widgets are removed # at 6.0, as early as Q1 2027). Detects ESM imports, AMD require([...]) arrays, and # dynamic $arcgis.import(...) specifiers; per-widget dispositions come from the # generated docs/widget-survival-guide.md (source: src/migration/widget-dispositions.ts). node dist/src/migration/cli.js widgets ./src # human table node dist/src/migration/cli.js widgets ./src --json # machine-readable node dist/src/migration/cli.js widgets ./src --markdown # shareable report node dist/src/migration/cli.js widgets ./src --gate 80 # exit 2 if automated share < 80% node dist/src/migration/cli.js widgets ./src --report widget-readiness.json # Safe codemod (dry run) node dist/src/migration/cli.js codemod ./src --report migration-report.json # Safe codemod (write changes) node dist/src/migration/cli.js codemod ./src --write --report migration-report.json # Safe codemod (explicit honua target alias) node dist/src/migration/cli.js codemod ./src --target honua --write --report migration-report.json # Safe codemod (write changes targeting esri-leaflet for supported subset) node dist/src/migration/cli.js codemod ./src --target esri-leaflet --write --report migration-report.json # Safe codemod (write + inline TODO annotations for manual sites) node dist/src/migration/cli.js codemod ./src --write --annotate-todos --report migration-report.json # Emit parity matrix JSON (for docs/CI dashboards) node dist/src/migration/cli.js matrix --report parity-matrix.json # Emit runtime parity matrix JSON (for JS API capability tracking) node dist/src/migration/cli.js runtime-matrix --report runtime-parity-matrix.json # Generate readiness metrics for bundled complex real-sample fixtures node dist/src/migration/cli.js fixtures --report reports/real-sample-metrics.json # Inspect the fixture-only Esri sample migration corpus helpers from tests/docs # See docs/esri-sample-corpus.md and test/fixtures/esri-sample-corpus/manifest.json # Enforce strict readiness gates for bundled real-sample fixtures node dist/src/migration/cli.js fixtures --fail-on-manual --fail-on-unhandled --fail-on-blocked --max-manual-ratio 0 --max-manual-intervention-ratio 0 --report reports/real-sample-metrics.json # Enforce strict readiness gates for the demo target fixture only node dist/src/migration/cli.js fixtures --target honua --fixtures esri-demo-feature-table-relates-app --fail-on-manual --fail-on-unhandled --fail-on-blocked --max-manual-ratio 0 --max-manual-intervention-ratio 0 --report reports/demo-featuretable-primary-metrics.json # Limit fixture metrics to a subset and esri-leaflet target mode node dist/src/migration/cli.js fixtures --target esri-leaflet --fixtures esri-demo-feature-table-popup-interaction-app --report reports/demo-featuretable-fallback-esri-leaflet-metrics.json # Gate in CI (non-zero exit if migration constraints fail) node dist/src/migration/cli.js codemod ./src --fail-on-manual --fail-on-unhandled --fail-on-blocked --max-manual-ratio 0.2 --max-manual-intervention-ratio 0.3 # Compare source vs target service fidelity for one layer node dist/src/migration/cli.js reconcile --source-base-url https://source.example --source-service-id parcels --target-base-url https://target.example --target-service-id parcels --layer-id 0 --sample-size 200 --report reconcile-report.json # Content inventory scan from ArcGIS Online/Portal node dist/src/migration/cli.js content scan --portal https://org.maps.arcgis.com --report ./content/scan.json # Content export (WebMaps + hosted layers) node dist/src/migration/cli.js content export --portal https://org.maps.arcgis.com --output-dir ./export --report ./content/export.json # Content import into Honua admin endpoint node dist/src/migration/cli.js content import --source ./export --target https://honua.example.com --admin-api-key $HONUA_ADMIN_API_KEY --report ./content/import.json # Content reconcile using export + import reports node dist/src/migration/cli.js content reconcile --source ./export --report ./content/reconcile.json # Convert a WebMap JSON export into Honua style config and rewrite portal URLs node dist/src/migration/cli.js content-webmap --input ./export/webmap.json --output ./export/webmap.honua.json --source-url-prefix https://org.maps.arcgis.com --target-url-prefix https://honua.example.com --report ./export/webmap.report.json ``` ## Migration Admin Scanner `HonuaClient.scanMigrationSource()` wraps the stable admin scan endpoint for source-system migration planning: ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; import type { MigrationSourceInventoryArtifact } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://honua.example.com", apiKey: process.env.HONUA_ADMIN_API_KEY, }); const inventory: MigrationSourceInventoryArtifact = await client.scanMigrationSource({ sourceKind: "geoservices", sourceUrl: "https://source.example.com/arcgis/rest/services/Parcels/FeatureServer", timeoutSeconds: 30, }); if (inventory.scanCompleteness.status === "failed") { // HTTP 200 means Honua produced an artifact; completeness is the planning gate. } ``` Set `exportJson: true` to request `POST /api/v1/admin/import/scan?export=json`; the SDK still parses the JSON artifact. The SDK also exports public artifact constants and TypeScript shapes for source inventory, migration manifest, parity evidence pack, cutover readiness, and readiness attestations. Manifest, parity, and readiness artifacts are modeled for client-side review workflows only; the SDK does not assume server routes for those artifacts. ## Esri Sample Corpus (#206) The first paired sample-app/service corpus slice is fixture-only and documented in [`docs/esri-sample-corpus.md`](./docs/esri-sample-corpus.md). The curated manifest at `test/fixtures/esri-sample-corpus/manifest.json` records Esri sample source URLs as metadata only, license/terms notes, skip reasons, and expected service/Portal references. PR CI uses Honua-owned snippets and must not contact live Esri services, vendor Esri sample code, or commit Esri service data. ## FeatureTable Demo Lane (#327) Primary target: - fixture: `esri-demo-feature-table-relates-app` - sample: `FeatureTable with related records` - source: `https://developers.arcgis.com/javascript/latest/sample-code/widgets-featuretable-relates/` Fallback target: - fixture: `esri-demo-feature-table-popup-interaction-app` - sample: `Feature table with popup interaction` - source: `https://developers.arcgis.com/javascript/latest/sample-code/widgets-featuretable-popup-interaction/` Pinned attribution metadata is tracked in `test/fixtures/DEMO_TARGETS.md` and fixture-local `ATTRIBUTION.md` files. Runbook (codemod-only CI reproducible path): ```bash # 1) Run primary demo lane migration (honua target) npm run demo:migration:featuretable # 2) Validate primary lane readiness gates and report metrics npm run gate:migration:demo-target # 3) Validate fallback lane deterministic esri-leaflet mapping npm run gate:migration:esri-leaflet-target ``` Report metrics to capture: - elapsed time: `reports/demo-featuretable-codemod-report.json -> elapsedMs` - manual rewrite ratio: `migration.manualRewriteMetric.ratio` - manual intervention count: `migration.manualInterventionMetric.numerator` - manual rewrite count: `migration.manualRewriteMetric.numerator` Quick metric extract: ```bash node -e 'const r=require("./reports/demo-featuretable-codemod-report.json"); console.log({elapsedMs:r.elapsedMs, manualRewriteRatio:r.migration.manualRewriteMetric.ratio, manualInterventionCount:r.migration.manualInterventionMetric.numerator, manualRewriteCount:r.migration.manualRewriteMetric.numerator});' ``` The codemod is intentionally conservative: - default target (`--target honua` alias of `honua-compat`) rewrites safe constructors: - `new FeatureLayer({ url: ... })` -> `new FeatureLayerCompat({ url: ... })` (supports `id`, `title`, `outFields`, `definitionExpression`, `renderer`, `popupTemplate`, `labelingInfo`, `labelsVisible`, `opacity`, `visible`, `minScale`, `maxScale`, `legendEnabled`, and `listMode`; `url` may be absolute or relative, including path-prefixed deployments) - `new Polyline(...)` -> `new PolylineCompat(...)` - `new Polygon(...)` -> `new PolygonCompat(...)` - `new Extent(...)` -> `new ExtentCompat(...)` - `new SpatialReference(...)` -> `new SpatialReferenceCompat(...)` - `new Color(...)` -> `new ColorCompat(...)` - `new PictureMarkerSymbol(...)` -> `new PictureMarkerSymbolCompat(...)` - `new TextSymbol(...)` -> `new TextSymbolCompat(...)` - `new LabelClass(...)` -> `new LabelClassCompat(...)` - `new SimpleFillSymbol(...)` -> `new SimpleFillSymbolCompat(...)` - `new ClassBreaksRenderer(...)` -> `new ClassBreaksRendererCompat(...)` - `new SimpleRenderer(...)` -> `new SimpleRendererCompat(...)` - `new UniqueValueRenderer(...)` -> `new UniqueValueRendererCompat(...)` - `new GraphicsLayer(...)` -> `new GraphicsLayerCompat(...)` - `new GroupLayer(...)` -> `new GroupLayerCompat(...)` - `new MapImageLayer({ url: ... })` -> `new MapImageLayerCompat({ url: ... })` (supports `id`, `title`, `sublayers`, `opacity`, `visible`, `minScale`, `maxScale`, `listMode`, and `legendEnabled`; runtime helpers include `exportImage/getLegend/find/identify/queryFeatures/queryFeaturesAll/queryFeatureCount/queryObjectIds/queryExtent/queryRelatedFeatures` plus `sublayer(...).query*()`, `sublayer(...).queryFeaturesAll()`, `sublayer(...).queryRelatedFeatures()`, and `sublayer.visible/definitionExpression`; `url` may be absolute or relative, including path-prefixed deployments) - `new TileLayer({ url: ... })` -> `new TileLayerCompat({ url: ... })` (supports `id`, `title`, `opacity`, `visible`, `minScale`, `maxScale`, and `listMode`; `url` may be absolute or relative, including path-prefixed deployments) - `new RouteLayer(...)` -> `new RouteLayerCompat(...)` - `new Map(...)` -> `new MapCompat(...)` (supports `basemap`, `layers`, `ground`, `tables`, `portalItem`, and `spatialReference`) - `new MapView(...)` -> `new MapViewCompat(...)` (supports `map`, `container`, `center`, `zoom`, `scale`, `rotation`, `extent`, `constraints`, `padding`, `highlightOptions`, `spatialReference`, and `popup`) - `new SceneView(...)` -> `new SceneViewCompat(...)` (supports core `MapView` options plus `viewingMode`, `qualityProfile`, and `camera`) - `new WebMap(...)` -> `new WebMapCompat(...)` (supports `portalItem`, `basemap`, `layers`, `ground`, `tables`, and `spatialReference`) - `new FeatureTable(...)` -> `new FeatureTableCompat(...)` (supports common table options including `highlightIds` and `multiSortEnabled`) - `new FeatureForm(...)` -> `new FeatureFormCompat(...)` (supports `feature`, `fieldConfig`, `groupDisplay`, `headingLevel`, and `visibleElements`) - `new FeatureTemplates(...)` -> `new FeatureTemplatesCompat(...)` (supports `layerInfos`, `container`, `filterFunction`, and `groupBy`) - `new LayerList(...)` -> `new LayerListCompat(...)` (supports `view`, `map`, `container`, `includeHidden`, `autoRefresh`, and `listItemCreatedFunction`) - `new Legend(...)` -> `new LegendCompat(...)` (supports `view`, `map`, `layers`, `container`, `includeHidden`, and `autoRefresh`) - `new Popup(...)` -> `new PopupCompat(...)` - `new Home(...)` -> `new HomeCompat(...)` (supports `view`, `container`, and `viewpoint`) - `new BasemapToggle(...)` -> `new BasemapToggleCompat(...)` - `new Locate(...)` -> `new LocateCompat(...)` (supports `view`, `container`, `zoom`, and `locateProvider`) - `new ScaleBar(...)` -> `new ScaleBarCompat(...)` - `new Search(...)` -> `new SearchCompat(...)` (supports `sources`, `includeDefaultSources`, `autoNavigate`, and `autoRefreshSources`) - `new BasemapGallery(...)` -> `new BasemapGalleryCompat(...)` - `new Bookmarks(...)` -> `new BookmarksCompat(...)` - `new Expand(...)` -> `new ExpandCompat(...)` - `new Compass(...)` -> `new CompassCompat(...)` - `new Fullscreen(...)` -> `new FullscreenCompat(...)` - `new Zoom(...)` -> `new ZoomCompat(...)` - `new Attribution(...)` -> `new AttributionCompat(...)` - `new Sketch(...)` -> `new SketchCompat(...)` - `new Editor(...)` -> `new EditorCompat(...)` - `new Track(...)` -> `new TrackCompat(...)` (supports `tracking`, `goToLocationEnabled`, `useHeadingEnabled`, `rotationEnabled`, `scale`, and `trackProvider`) - `new Measurement(...)` -> `new MeasurementCompat(...)` - `new TimeSlider(...)` -> `new TimeSliderCompat(...)` - `new Directions(...)` -> `new DirectionsCompat(...)` - alternate target (`--target esri-leaflet`) rewrites deterministic subset plus broad compat fallbacks: - `new FeatureLayer({ ... })` -> `HonuaEsriLeaflet.featureLayer({ ... })` - `new MapImageLayer({ ... })` -> `HonuaEsriLeaflet.dynamicMapLayer({ ... })` - `new TileLayer({ ... })` -> `HonuaEsriLeaflet.tiledMapLayer({ ... })` - `new Map({ ... })` -> `new MapCompat({ ... })` - `new MapView({ ... })` -> `new MapViewCompat({ ... })` - `new SceneView({ ... })` -> `new SceneViewCompat({ ... })` - `new LayerList({ ... })` -> `new LayerListCompat({ ... })` - `new Legend({ ... })` -> `new LegendCompat({ ... })` - `new Popup({ ... })` -> `new PopupCompat({ ... })` - `new Search({ ... })` -> `new SearchCompat({ ... })` - `new Home/BasemapToggle/Locate/ScaleBar/BasemapGallery/Expand/Compass/Bookmarks/Fullscreen/Zoom/Attribution(...)` -> corresponding `*Compat` constructor - dynamic imports for those modules -> `Promise.resolve({ default: HonuaEsriLeaflet.* })` - dynamic imports for compat fallback modules -> `import("@honua/sdk-esri-compat").then((m) => ({ default: m.*Compat }))` - advanced 3D-only modules (for example `Slice` and external-renderer style APIs) are emitted as manual TODO/report entries - `--target esri-leaflet` is for ArcGIS JS (`@arcgis/core`) inputs; existing Esri Leaflet apps generally do not need codemod migration - it rewrites supported dynamic imports to compat bridge expressions when safe (for example SceneView dynamic import), - it skips complex constructors and records manual TODO entries in the report, - it keeps CommonJS `require(...)` constructor sites as manual TODOs (for example `.cjs` or `.js` files exporting via `module.exports`/`exports.*`), - optionally it can inject inline `// TODO(honua-migrate)...` comments for manual sites (`--annotate-todos`), - it computes `manualRewrite = numerator / denominator` for codemod-scoped call sites, - it computes `manualIntervention = numerator / denominator` across codemod-scoped call sites plus unhandled ArcGIS usage hits, - migration report JSON includes `codemodTarget` so CI artifacts clearly indicate target mode (`honua-compat` or `esri-leaflet`), - it supports CI gating flags: - `--fail-on-manual` - `--fail-on-unhandled` - `--fail-on-blocked` - `--max-manual-ratio <0..1>` - `--max-manual-intervention-ratio <0..1>` - CLI summary includes: - per-type migration counts as `byKind=feature-layer:auto/manual/total,graphic:auto/manual/total,point-geometry:auto/manual/total,polyline-geometry:auto/manual/total,polygon-geometry:auto/manual/total,extent-geometry:auto/manual/total,spatial-reference:auto/manual/total,color:auto/manual/total,simple-line-symbol:auto/manual/total,simple-marker-symbol:auto/manual/total,picture-marker-symbol:auto/manual/total,text-symbol:auto/manual/total,label-class:auto/manual/total,simple-fill-symbol:auto/manual/total,class-breaks-renderer:auto/manual/total,simple-renderer:auto/manual/total,unique-value-renderer:auto/manual/total,...,route-layer:auto/manual/total,layer-list:auto/manual/total,legend-widget:auto/manual/total,popup-widget:auto/manual/total,home-widget:auto/manual/total,basemap-toggle-widget:auto/manual/total,locate-widget:auto/manual/total,scale-bar-widget:auto/manual/total,search-widget:auto/manual/total,basemap-gallery-widget:auto/manual/total,bookmarks-widget:auto/manual/total,expand-widget:auto/manual/total,compass-widget:auto/manual/total,fullscreen-widget:auto/manual/total,zoom-widget:auto/manual/total,attribution-widget:auto/manual/total,sketch-widget:auto/manual/total,editor-widget:auto/manual/total,track-widget:auto/manual/total,measurement-widget:auto/manual/total,time-slider-widget:auto/manual/total,directions-widget:auto/manual/total,query:auto/manual/total,feature-set:auto/manual/total,oauth-info:auto/manual/total,identity-manager:auto/manual/total,esri-request:auto/manual/total,esri-config:auto/manual/total,reactive-utils:auto/manual/total`, - grouped manual reasons, - unhandled ArcGIS module inventory (with `static-import` / `dynamic-import` / `require` usage style), - scanner flags include module-shape and risk hints (for example `commonjs-detected`, `scene-3d-detected`, `dynamic-import-detected`), - readiness classification (`ready`, `assisted`, `blocked`) with explicit gate results. --- # File: docs/ogc-api.md # OGC API Client Status: implemented in `src/core/ogc-tiles.ts`, `src/core/ogc-maps.ts`, `src/core/ogc-processes.ts`, `src/core/ogc-records.ts`, `src/core/stac.ts`, and (for OGC API Features) `src/core/surfaces.ts`. This document is the developer reference for the first-party OGC API adapter. It complements the design notes in [`shared-client-contract.md`](./shared-client-contract.md) and the capability matrix in [`protocol-capability-matrix.md`](./protocol-capability-matrix.md). Canonical OGC API Features queries can be explained before execution through `@honua/sdk-js/query-planner`. The deterministic `ogc-api-features-query-v1` output exposes the collection, CQL2 text filter, properties, sort, bbox, CRS, and paging request without fetching metadata or rows. See [Deterministic query planner](./query-planner.md#remote-pushdown). ## Conformance areas covered | Area | Surface | Source protocol | Notes | | --- | --- | --- | --- | | OGC API Features | `client.ogcFeatures()` | `ogc-features` | landing → collections → items, CQL2 filtering, transactions where the server advertises them | | OGC API Tiles | `client.ogcTiles()` | `ogc-tiles` | tileset discovery, vector + raster tiles on the canonical `/collections/{id}/tiles/{tms}/…` route (styled tiles deferred — see below) | | OGC API Maps | `client.ogcMaps()` | `ogc-maps` | dataset / collection map renders, styled access | | OGC API Processes | `client.ogcProcesses()` | (none — job runner) | discovery, async execution, `IJobRun<T>` surface | | OGC API Records | `client.ogcRecords()` | `ogc-records` | metadata/catalog discovery, record search, record detail, raw response access | | STAC API | `client.stac()` | `stac` | landing, collections, items, cross-collection search | OGC conformance class identifiers (e.g. `http://www.opengis.net/spec/ogcapi-features-3/1.0/conf/filter`) are **not** primary SDK types. `negotiateOgcCapabilities(protocol, conformance)` translates a `/conformance` response into a canonical `Capabilities` set; `hasOgcConformanceClass(conformance, substring)` is the explicit substring gate for callers that want to branch on a specific extension. ## Getting started ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; const baseUrl = "https://your-honua-server.example"; const client = new HonuaClient({ baseUrl }); ``` ### OGC API Features (already shipped) ```ts doc-test=skip reason="partial excerpt requires application host context" const ogc = client.ogcFeatures(); const items = await ogc.collection("parcels").items({ limit: 50, filter: "STATUS = 'ACTIVE'" }); ``` ### OGC API Tiles ```ts doc-test=skip reason="partial excerpt requires application host context" const tiles = client.ogcTiles(); // 1) Discover tilesets the server advertises for a collection const tilesets = await tiles.tilesets({ collectionId: "parcels" }); // 2) Bind to one tileset and fetch a tile const tileset = tiles.tileset("parcels", "WebMercatorQuad"); const tile = await tileset.tile({ tileMatrix: 5, tileRow: 9, tileCol: 12 }); console.log(tile.contentType); // "application/vnd.mapbox-vector-tile" console.log(tile.bytes.byteLength); // Raster tiles use the same route and rely on the `Accept` header to // negotiate the output media type. const png = await tileset.tile({ tileMatrix: 4, tileRow: 2, tileCol: 3, accept: "image/png" }); ``` Styled-tile access (the OGC `/styles/{styleId}/tiles/…` route) is part of the OGC API Tiles standard but is not currently exposed by the Honua server. The SDK intentionally does not synthesize that path today; it will be added when the server endpoint ships. ### OGC API Maps ```ts doc-test=skip reason="partial excerpt requires application host context" const maps = client.ogcMaps(); // Dataset-level render across multiple collections const map = await maps.map({ width: 1024, height: 1024, bbox: [-122, 37, -120, 38], collections: ["parcels", "roads"], format: "png", // short-name token; `image/png` also accepted and normalized }); // Collection-level styled render const styled = await maps.collection("parcels", "topographic").map({ width: 512, height: 512, }); ``` The `format` option is serialized to the server's `f` query parameter as a short-name token (`png`, `jpeg`, `jpg`, `tiff`, `tif`); the SDK normalizes `image/…` media-type aliases for ergonomics and sends a media-type `Accept` header regardless. The request envelope intentionally has no `filter` field — honua-server's Maps request model has no matching property, so a CQL2 filter would be silently ignored. Callers who need a custom query parameter can still pass one through `extraParams`. ### OGC API Processes ```ts doc-test=skip reason="partial excerpt requires application host context" import type { IJobRun } from "@honua/sdk-js/honua"; const processes = client.ogcProcesses(); const job: IJobRun<{ result: GeoJSON.Feature }> = await processes.execute({ processId: "buffer", inputs: { feature: somePoint, distance: 500 }, mode: "async", }); const unwatch = job.watch((snap) => { console.log("status=", snap.status, "progress=", snap.progress?.percent); }); try { const { outputs } = await job.results(); console.log("result feature:", outputs.result); } catch (error) { // HonuaJobFailedError carries status, errorCode, details console.error(error); } finally { unwatch(); } ``` `IJobRun` is the canonical async-operation surface. It is reused for every long-running operation in the SDK; the OGC Processes runner is just one implementation. `cancel()` is idempotent against the documented 404 / terminal-race paths but does not silently swallow other failures: - `404` ("job already gone"): return the cached status. - `409 "Cannot dismiss completed job"` (honua-server's `JobEndpoints` terminal-state pre-check / post-apply / durable conflict — the job raced the caller into a terminal state): re-poll the job and return the authoritative terminal status if the poll confirms it. If the poll surfaces a non-terminal status, the original 409 is rethrown so the caller is not lied to. - `409 "Dismiss could not be confirmed"` (backend dismissal request unconfirmed) and `409 "Cancellation not supported"` (backend lacks dismissal capability): rethrow the `HonuaHttpError` so the caller can branch or retry. Discrimination is by RFC 7807 problem-details `title` (and `detail` substring fallback). Terminal-failure snapshots populate `JobError` from `statusInfo.exception` when the server provides it, and fall back to `statusInfo.message` otherwise (honua-server's `StatusInfo` DTO only emits `message`). The resulting `HonuaJobFailedError.message` carries the server's reason text. ### STAC API ```ts doc-test=skip reason="partial excerpt requires application host context" const stac = client.stac(); // GET /search const page = await stac.search({ bbox: [-122, 37, -120, 38], collections: ["sentinel-2"], filter: "cloud_cover < 10", filterLang: "cql2-text", limit: 50, offset: 0, }); // GET /search with intersects + fields selection const filtered = await stac.search({ intersects: somePolygon, fields: { include: ["id", "properties.datetime"], exclude: ["assets.thumbnail"] }, }); // POST /search (large filter bodies, big intersects geometries, etc.) const post = await stac.search({ usePost: true, intersects: somePolygon, collections: ["sentinel-2"], }); // Drain across pages — advances via the rel=next link's `?offset=N` const everything = await stac.searchAll({ collections: ["sentinel-2"] }); ``` `StacSearchRequest.offset` is honua-server's canonical paging token: its `/stac/search` GET handler binds `[FromQuery] int? offset` and emits a `rel=next` link whose `href` carries `?offset=N`. `searchAll` / `searchStream` follow that link verbatim. `next` is kept as optional support for non-Honua STAC servers that advertise an opaque `?next=…` token instead. `intersects` and `fields` are serialized onto the GET query (intersects as JSON; fields as `id,properties.datetime,-assets.thumbnail`) in addition to the POST body. ### OGC API Records ```ts doc-test=skip reason="partial excerpt requires application host context" const records = client.ogcRecords(); // Discover available metadata catalogs. const catalogs = await records.collections(); // Search one catalog. Records query parameters are catalog metadata // filters, not STAC item-search filters. const page = await records.collection("catalog").search({ q: ["roads", "parcels"], type: ["service", "collection"], externalIds: ["FeatureServer:transportation"], bbox: [-158, 21, -157, 22], datetime: "2025-01-01/2025-12-31", limit: 25, offset: 0, }); const detail = await records.collection("catalog").record({ recordId: "service-transportation" }); // Raw response access keeps the shared auth/interceptor/retry pipeline but // leaves body decoding to the caller. const html = await records.collection("catalog").rawRecord({ recordId: "service-transportation", responseFormat: "html", accept: "text/html", }); ``` Records and STAC are intentionally separate surfaces. STAC describes spatiotemporal assets and collection/item search for imagery/data assets. Records describes metadata about resources: services, layers, collections, maps, scenes, styles, STAC collections, source descriptors, and other catalog entries. Honua admin metadata and migration inventory remain Honua-specific control-plane/read-model APIs; Records is the standards-facing public catalog view over stable metadata. `OgcRecordsSearchRequest` supports the Records core search parameters `bbox`, `datetime`, `limit`, `q`, `ids`, `type`, and `externalIds`, plus optional `filter` / `filter-lang` / `filter-crs` when the server advertises the Records filtering conformance class. `searchAll` and `searchStream` follow `rel=next` links that carry `?offset=N`. ## Canonical Source registration Source-shaped OGC adapters register through the shared client contract from `@honua/sdk-js/contract`. Cross-protocol code consumes them through the same `Dataset` / `Source` vocabulary as GeoServices / OData: ```ts doc-test=skip reason="partial excerpt requires application host context" import { createDataset, PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; const dataset = createDataset({ id: "parcels", client, sources: [ { id: "parcels-ogc", protocol: "ogc-features", locator: { url: baseUrl, collectionId: "parcels" }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["ogc-features"], }, { id: "parcels-tiles", protocol: "ogc-tiles", locator: { url: baseUrl, collectionId: "parcels", tileMatrixSetId: "WebMercatorQuad" }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["ogc-tiles"], }, { id: "parcels-map", protocol: "ogc-maps", locator: { url: baseUrl, collectionId: "parcels", styleId: "topographic" }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["ogc-maps"], }, { id: "parcels-stac", protocol: "stac", locator: { url: baseUrl, collectionId: "parcels" }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES.stac, }, { id: "catalog-records", protocol: "ogc-records", locator: { url: baseUrl, collectionId: "catalog" }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES["ogc-records"], }, ], }); const features = await dataset.source("parcels-ogc")!.query({ where: "STATUS = 'ACTIVE'" }); const stacItems = await dataset.source("parcels-stac")!.query({ where: "cloud_cover < 10" }); const catalogRecords = await dataset.source("catalog-records")!.query({ where: "type = 'service'" }); const tileset = dataset.source("parcels-tiles")!.adapter("ogc-tiles"); // HonuaOgcTileset const map = dataset.source("parcels-map")!.adapter("ogc-maps"); // HonuaOgcCollectionMap const recordsCatalog = dataset.source("catalog-records")!.adapter("ogc-records"); // HonuaOgcRecordCollection ``` OGC API Tiles and OGC API Maps are render-only; their `Source.query*` methods throw `HonuaCapabilityNotSupportedError`. Renderers always reach the underlying class through `Source.adapter("ogc-tiles")` / `Source.adapter("ogc-maps")`. ## Capability negotiation and graceful degradation ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; import { negotiateOgcCapabilities, hasOgcConformanceClass } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://example.test" }); const conformance = await client.getOgcFeaturesConformance(); const caps = negotiateOgcCapabilities("ogc-features", conformance); if (caps.has("queryAggregate")) { // server advertises ogcapi-features-3/conf/filter; a strict Source can allow // the adapter's documented client-side aggregation fallback. } if (hasOgcConformanceClass(conformance, "features-4/1.0/conf/create-replace-delete")) { // server advertises Part 4 transactions } ``` Under `capabilityPolicy: "degraded"`, OGC API Features falls back to client-side aggregation and metadata-bbox extent (see [`protocol-capability-matrix.md`](./protocol-capability-matrix.md) for the per-protocol coverage). All other adapters honour the strict behaviour: a missing capability throws `HonuaCapabilityNotSupportedError`. ## Conformance fixtures The repo ships parametrized conformance suites under `test/contract/`: - `ogc-tiles.test.ts` — tileset discovery + tile fetch + Source adapter - `ogc-maps.test.ts` — dataset / collection / styled map renders - `ogc-processes.test.ts` — `IJobRun` lifecycle, cancel, error paths - `ogc-records.test.ts` — Records query params, paging, raw access, Source adapter - `stac.test.ts` — GET / POST search + Source adapter - `ogc-conformance.test.ts` — conformance-class negotiation These run against mock fetch responders and are the regression baseline for "passes against Honua Server's current OGC parity matrix" (Features CITE-certified, Tiles CITE-certified, Maps, Processes async). --- # File: docs/wfs.md # WFS 2.0 adapter `@honua/sdk-js` ships a first-party WFS 2.0 client that conforms to the shared JS client contract from [`docs/shared-client-contract.md`](./shared-client-contract.md). A WFS source registered through `createDataset({ sources })` produces the same canonical `Source<T>` / `Query<T>` / `Result<T>` / `EditEnvelope<T>` / `EditResult` shapes as the GeoServices and OGC Features adapters, so mixed-source operator apps do not have to learn WFS / XML specifics. ```ts doc-test=compile import { createDataset, PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { HonuaClient } from "@honua/sdk-js"; const client = new HonuaClient({ baseUrl: "https://server.honua.io" }); const dataset = createDataset({ id: "parcels", client, sources: [ { id: "parcels-wfs", protocol: "wfs", locator: { url: "https://server.honua.io/wfs", typeName: "parcels:lot" }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES.wfs, }, ], }); const source = dataset.source("parcels-wfs")!; const result = await source.query({ where: "STATE = 'CA' AND ACRES > 10" }); ``` ## Capabilities The default capability set (`PROTOCOL_DEFAULT_CAPABILITIES.wfs`) is `query`, `queryExtent`, `queryObjectIds`, `applyEdits`, `stream`. The capability matrix in [`protocol-capability-matrix.md`](./protocol-capability-matrix.md) covers each row's degraded fallbacks (none here — WFS is either supported or it isn't). `queryAggregate`, `queryRelated`, `attachments` throw `HonuaCapabilityNotSupportedError` because WFS 2.0 does not expose server-side aggregation, related-records, or feature attachments. ## Locator ```ts doc-test=compile interface WfsLocator { url: string; // Fully qualified WFS endpoint (e.g. https://server/wfs) typeName: string; // Namespace-qualified feature-type name (e.g. parcels:lot) featureNamespace?: string; // URI bound to the typeName prefix (required for prefixed applyEdits) } ``` The endpoint URL must share an origin with the `HonuaClient`'s `baseUrl`; cross-origin WFS sources require constructing a separate `HonuaClient`. `featureNamespace` is the namespace URI the server advertises for the `typeName` prefix (typically declared as `xmlns:<prefix>="…"` on the `<wfs:WFS_Capabilities>` root). The canonical adapter binds it on the `<wfs:Transaction>` root so per-handle feature elements (`<parcels:lot>…</parcels:lot>`) and prefixed `typeName="…"` attribute references on `<wfs:Update>` / `<wfs:Delete>` resolve. When the locator omits `featureNamespace` and the type name carries a prefix, the adapter falls back to a synthetic URN (`urn:honua:wfs:feature-namespace:<prefix>`) so the document is well-formed XML; strict servers will reject the synthetic URI with an `<ows:ExceptionReport>` whose locator names the prefix, telling callers which descriptor field to set. Unprefixed `typeName` values do not need `featureNamespace`. ## Capability negotiation `HonuaWfs.capabilities()` issues a single `GetCapabilities` request the first time `query`, `queryAll`, `queryObjectIds`, `stream`, or `queryExtent` runs (the no-network `queryExtent` shortcut also reads the cached snapshot to find the per-feature-type `ows:WGS84BoundingBox`). The parsed snapshot is cached per `HonuaWfs` instance — subsequent calls reuse it. Use `wfs.refresh()` to drop the cache. `applyEdits` does not pre-fetch capabilities because the canonical transaction body never needs the output-format negotiation; servers that do not advertise `Transaction` surface that as a server-side `OperationProcessingFailed` `<ows:ExceptionReport>` on the first transaction request, projected onto `HonuaWfsExceptionError` (carrying `exceptionCode` and `locator`). The descriptor's `capabilities` set is the SDK's promise of what the adapter can fulfil; the constructor does not currently widen or narrow it from `GetCapabilities`. Callers that need a downgraded set per source (for example, dropping `applyEdits` for a server that publishes WFS read-only) intersect the default themselves and pass the result on `SourceDescriptor.capabilities`. ## Content-type negotiation The adapter treats the server as advertising JSON when `OperationsMetadata.GetFeature` lists any of `application/geo+json`, `application/json`, `application/vnd.geo+json`, `json`, or `geojson` and prefers the GeoJSON encoding over GML. If only GML is advertised, the canonical `Source.query()` throws `HonuaCapabilityNotSupportedError("query")` rather than ship raw XML through `Result.features`. Callers can still reach the GML payload through `Source.protocol("wfs").getFeature(...)` (see "Protocol escape hatch" below). GML decoding is intentionally out of scope. A future ticket may add an opt-in GML decoder; for now the canonical surface is GeoJSON-only. ## Filter encoding (FES 2.0) `Query.where` compiles to FES 2.0 OGC Filter Encoding. The supported subset is: - comparison operators: `=`, `<>`, `!=`, `<`, `<=`, `>`, `>=` - `IN (a, b, …)` / `NOT IN (…)` - `BETWEEN x AND y` / `NOT BETWEEN` - `LIKE 'pattern%'` / `NOT LIKE` - `IS NULL` / `IS NOT NULL` - boolean combinators `AND`, `OR`, `NOT` - parenthesization - string literals (single-quoted, `''` escapes), numeric literals, property identifiers (dotted path supported) Anything richer — function calls, subqueries, vendor extensions — yields `HonuaCapabilityNotSupportedError("query")` rather than emitting a silent partial filter. Callers that need the full FES vocabulary reach the wire through `Source.protocol("wfs").getFeature({ filter: rawFesXml })`. `Query.spatialFilter` compiles to FES `<fes:BBOX>` (envelope geometry with `spatialRel` undefined / `esriSpatialRelIntersects` / `esriSpatialRelEnvelopeIntersects`) or the corresponding spatial predicate (`<fes:Intersects>`, `<fes:Within>`, `<fes:Contains>`, `<fes:Crosses>`, `<fes:Overlaps>`, `<fes:Touches>`). For envelope geometry with a non-intersects relation (`Contains`, `Within`, `Crosses`, `Overlaps`, `Touches`), the adapter lowers the envelope to a GML 3.2 polygon and emits the requested predicate so the server honors the relation rather than silently widening to bbox semantics. Geometry serialization is GML 3.2 simple (point / line / polygon); curves and surfaces throw and require the escape hatch. The geometry property name defaults to `the_geom`. Servers using a different name (`geometry`, `shape`, …) can supply a per-source filter through the protocol escape hatch. ## Field projection (`outFields` and `returnGeometry`) WFS `propertyName=` drops every property the caller does not list, including the geometry column. The canonical `Query` contract treats `outFields` and `returnGeometry` as independent controls (geometry is included unless `returnGeometry === false`), so the adapter resolves the two like this: | `outFields` | `returnGeometry` | wire `propertyName=` | | --- | --- | --- | | _unset / empty_ | _unset_ / `true` | _omitted_ — server returns all fields + geometry | | _set_ | _unset_ / `true` | `outFields,the_geom` (geometry property appended unless already listed) | | _set_ | `false` | `outFields` only — geometry is intentionally dropped | | _unset / empty_ | `false` | _refused_ — `HonuaCapabilityNotSupportedError("query")` | The `returnGeometry === false` + no-`outFields` case throws because WFS cannot suppress geometry without enumerating every non-geometry property; silently widening to "geometry included" would break the canonical contract. Callers that need geometry-less rows must list the non-geometry fields they want, or reach the wire through `Source.protocol("wfs")`. `queryExtent` and `queryObjectIds` ignore both `outFields` and `returnGeometry` on the drain path so caller intent on those fields cannot break the drain. `queryExtent` always issues geometry-bearing pages (it computes a bbox from each feature's geometry); a `returnGeometry: false` paired with `queryExtent` does **not** throw, the field is stripped before the drain. `queryObjectIds` reads each feature's GeoJSON `id` directly, so neither knob affects the result — both are stripped before the drain so the caller's `outFields` cannot push the geometry property onto the wire and `returnGeometry: false` cannot trip the propertyName-suppression guard. ## GET vs. POST routing Filters whose encoded length exceeds `~7000` characters are routed through POST GetFeature with a `<wfs:GetFeature>` body containing a `<wfs:Query typeNames="…" srsName="…">`, optional `<wfs:PropertyName>` projections, the same `<fes:Filter>` tree, and an optional `<fes:SortBy>` block. `Query.outFields`, `Query.orderBy`, and `Query.outSr` survive the GET → POST switch — the only transport difference is the body encoding. The 7000-character threshold is a single constant we revise after telemetry lands. `Query.outSr` accepts either a string CRS URI / EPSG token (passed through verbatim) or a numeric WKID. Numeric WKIDs are translated to the OGC URN form `urn:ogc:def:crs:EPSG::<wkid>` so the wire shape matches what `OperationsMetadata` and `Filter_Capabilities` advertise. ## Pagination `Query.pagination.offset` maps to `startIndex`; `Query.pagination.limit` maps to `count`. `queryAll` requests `limit + 1` rows so the adapter can stamp `Result.exceededTransferLimit: true` when more records exist. `stream` paginates internally with a 2000-row default page size or the caller's `pagination.limit` when supplied. `pagination.limit === 0` is treated as an explicit "zero records" cap across `query`, `queryAll`, `stream`, and `queryObjectIds` — the default page-size fallback only applies when `limit` is unset or negative. `query` / `stream` / `queryObjectIds` short-circuit before the wire call (returning an empty result, no yielded pages, or `[]` respectively); `queryAll` still issues a single 1-row lookahead so `exceededTransferLimit` can flip when more records exist. `Result.totalCount` populates from the GeoJSON `numberMatched` field; `exceededTransferLimit` flips when `numberMatched > features.length`. ## queryObjectIds WFS 2.0 has no interoperable server-side ids-only mode, so `queryObjectIds` drains the matching set across pages and projects the GeoJSON `id` from each feature. The default page size is 2000; the drain stops as soon as the server returns a short page. `Query.pagination.offset` chooses where the drain starts (forwarded as `startIndex` to `GetFeature`) and `Query.pagination.limit`, when set, caps the global id count — not the per-page count — so callers can stop the drain without learning the server's default page size. The adapter shrinks each page to `min(2000, remaining)` so the final page never overshoots the cap. A `pagination.limit` of `0` short-circuits the drain and returns `[]` without a wire call. `Query.outFields` and `Query.returnGeometry` are stripped before each drained page is requested. The drain reads each feature's top-level GeoJSON `id` (a sibling of `properties` and `geometry`), so neither knob affects the result; stripping them keeps the wire request from emitting an unnecessary `propertyName=` and prevents `returnGeometry: false` from tripping the canonical "no `outFields`" guard documented in [Field projection](#field-projection-outfields-and-returngeometry). ## queryExtent Unfiltered `queryExtent()` (no `where`, no `spatialFilter`, no `outSr`) reads the per-feature-type `ows:WGS84BoundingBox` from `GetCapabilities` and returns the cached envelope without any extra HTTP traffic. Filtered or `outSr`-bearing requests drain every page of the matching set (2000 features per page) and compute the bbox client-side, so the returned extent always covers the full filtered set rather than just the first server page. Caller pagination (`Query.pagination.offset` / `.limit`), `Query.outFields`, and `Query.returnGeometry` are intentionally ignored on this path — `queryExtent` answers "what bbox holds the matching records" rather than "what bbox holds the first page", and the drain must always see geometry on the wire to compute a bbox. A caller-supplied `outFields` projection would emit `propertyName=...` and drop geometry from every drained page; a caller-supplied `returnGeometry: false` would trip the field-projection guard. The drain therefore strips all three fields before issuing each `GetFeature` page so geometry is preserved end-to-end and the call cannot be refused on a knob that does not apply to extent computation. `queryExtent` returns `{ extent, count? }` and does not carry a `degraded[]` array; the OGC Features adapter is the only one that flags this fallback today. ## Edits (`applyEdits`) `applyEdits` builds a single `<wfs:Transaction>` POST body with `<wfs:Insert>`, `<wfs:Update>`, and `<wfs:Delete>` blocks. Geometry payloads come from `CanonicalFeature.geometry` (GeoJSON → GML 3.2). The transaction's `releaseAction` follows `EditEnvelope.rollbackOnFailure`: | `rollbackOnFailure` | `releaseAction` | | --- | --- | | `true` | `ALL` | | `false` / omitted | `SOME` | Per-handle `<wfs:InsertResults>` `<fes:ResourceId rid="…"/>` IDs populate `EditOutcome.id`. The adapter stamps each `<wfs:Insert>` with a stable `handle="add-N"` (1-based, matching `envelope.adds` order) and indexes the returned `<wfs:Feature handle="…">` buckets by handle when mapping ResourceIds back onto `EditResult.added`, so a server that reorders the buckets — or omits them under `releaseAction="SOME"` when an insert fails — does not misassign IDs to the wrong `envelope.adds[i]`. Inserts whose handle is missing from the response surface as `{ success: false }` rather than silently inheriting the neighbouring success. The handle attribute is informational in WFS 2.0, so when no `<wfs:Feature>` carries one the adapter falls back to the legacy positional pairing instead of dropping every id. `OperationProcessingFailed` and other `<ows:ExceptionReport>` responses surface as `HonuaWfsExceptionError` with `.exceptionCode` / `.locator` preserved. `CanonicalFeature.id` is required on every update because each `<wfs:Update>` is filtered by `<fes:ResourceId>`; without an id the block would mass-update every feature in the type. Updates whose `id` is `undefined` / `null` are filtered out before the transaction body is built and surface as deterministic per-item failures (`{ success: false, error: { code: 400, description: "update.id is required" } }`) on `EditResult.updated`. Valid updates in the same envelope still travel as a single transaction. When every operation in the envelope is absent or malformed the adapter skips the wire round-trip entirely so the server never sees an unaddressed transaction. ## Stored queries `ListStoredQueries` and `DescribeStoredQueries` are reachable through the protocol escape hatch: ```ts doc-test=skip reason="partial excerpt requires application host context" const wfs = source.protocol("wfs")!; // HonuaWfsFeatureType const ids = await wfs.root.storedQueries(); const sq = wfs.root.storedQuery("byKey"); const response = await sq.execute({ parameters: { id: 1 } }); ``` A stored query whose output is JSON returns canonical features through `response.kind === "json"`. Stored queries that advertise only GML (today: Honua Server's `urn:ogc:def:query:OGC-WFS::GetFeatureById`) cannot be projected onto the canonical envelope — `Source.query()` does not carry stored-query intent because that would re-introduce WFS-specific shapes at the top level. The escape hatch above still returns the raw GML payload. ## Protocol escape hatch `Source.protocol("wfs")` returns a bound `HonuaWfsFeatureType` whose methods carry the raw WFS-shaped payloads: ```ts doc-test=skip reason="partial excerpt requires application host context" const wfs = source.protocol("wfs")!; // Raw XML capabilities payload (cached after the first call). const snapshot = await wfs.capabilities(); // Custom FES filter (escape unsupported expressions). await wfs.getFeature({ filter: customFesXml }); // GetPropertyValue (returns raw XML). await wfs.getPropertyValue({ valueReference: "ACRES" }); // Custom Transaction body. await wfs.transaction({ body: rawTransactionXml }); ``` `HonuaWfs` (`wfs.root`) owns the capabilities cache and exposes `capabilities()`, `refresh()`, `rawCapabilities()`, `storedQueries()`, and `storedQuery(id)` so callers can drive WFS without going through the canonical `Source` surface when they need full FES expressivity. ## Locking WFS `LockFeature` / `GetFeatureWithLock` are not exposed in the canonical contract. Callers that need locks reach the wire through the protocol escape hatch — there is no top-level `Source.lock()` concept. ## Defenses - The capabilities XML walker refuses any document declaring `<!DOCTYPE>` or `<!ENTITY>`. This stops XXE-class attacks before any property is read. The same walker is reused for `<ows:ExceptionReport>` and `<wfs:TransactionResponse>` parsing, so every WFS XML payload entering the canonical surface is hardened. - The WFS adapter never reaches `fetch` directly; all wire calls go through `HonuaClient.requestText`, so the existing interceptor / retry / timeout / abort signal pipeline applies. - WFS responses with content-type `application/xml` containing `<ows:ExceptionReport>` are turned into typed `HonuaWfsExceptionError` instances (`exceptionCode`, `locator`, and the message as the parser saw it) so the canonical surface surfaces structured WFS errors instead of opaque HTTP failures. `HonuaWfsExceptionError` is also raised when an `<ows:ExceptionReport>` arrives wrapped inside a `HonuaHttpError` body (the body is sniffed for `ExceptionReport` and re-thrown as the typed error before the failure leaves the adapter). ## Server compatibility The adapter targets WFS 2.0 servers. WFS 1.x is intentionally not supported — Honua Server publishes WFS 2.0 only. Non-Honua servers that advertise WFS 2.0 with at least GeoJSON output should work out of the box; servers that only emit GML force the canonical surface to throw and require the escape hatch. --- # File: docs/geoparquet.md # GeoParquet / DuckDB-WASM source `@honua/sdk-js/geoparquet` adds a `Source` that runs the **same protocol-neutral `Query`** you use against a FeatureServer or an OGC API Features collection — but against GeoParquet files, in the browser, via [DuckDB-WASM](https://duckdb.org/docs/api/wasm/overview) and its `spatial` extension. The query compiles to SQL over `read_parquet(...)` and returns the standard `Result` (GeoJSON features + schema), so results render through the same query-tiles runtime path as any other source. This is the "query Overture GeoParquet in the browser via DuckDB-WASM" reference architecture, slotted directly into the `Dataset → Source → Query → Result` contract. ## Install `@duckdb/duckdb-wasm` is an **optional peer dependency** — it is not bundled and not pulled into the `/contract` or `/honua` entrypoints. Install it (and its `apache-arrow` peer) only when you use this source: ```bash npm i @duckdb/duckdb-wasm apache-arrow ``` The engine is reached through a dynamic `import()`, so there is no static dependency edge from the core SDK. If the peer is missing, constructing a query throws a clear "install `@duckdb/duckdb-wasm`" error rather than failing opaquely. ## Quickstart Wire the resolver into `createDataset`. One `GeoparquetRuntime` — one shared DuckDB Web Worker — backs every geoparquet source in the dataset. ```ts doc-test=compile import { createDataset, PROTOCOL_DEFAULT_CAPABILITIES } from "@honua/sdk-js/contract"; import { geoparquetResolver } from "@honua/sdk-js/geoparquet"; import { envelope } from "@honua/sdk-js"; import { HonuaClient } from "@honua/sdk-js/honua"; const client = new HonuaClient({ baseUrl: "https://your-honua-server.example" }); const geoparquet = geoparquetResolver(); const dataset = createDataset({ id: "overture", client, capabilityPolicy: "degraded", resolveSource: geoparquet, sources: [ { id: "places", protocol: "geoparquet", // A single file, or a hive-partitioned glob (e.g. an Overture theme): locator: { url: "https://example.com/overture/theme=places/**/*.parquet" }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES.geoparquet, }, ], }); const places = dataset.source("places")!; // The SAME Query object shape that runs against a FeatureServer source: const result = await places.query({ where: "categories.primary = 'restaurant'", spatialFilter: envelope(-158.5, 21.2, -157.6, 21.7), outFields: ["id", "names", "categories"], pagination: { limit: 500 }, returnGeometry: true, }); for (const feature of result.features) { console.log(feature.attributes.id /* GERS id preserved */, feature.geometry); } // Tear down the shared worker when the client is disposed: await geoparquet.dispose(); ``` You can also construct a source directly with `geoparquetSource(descriptor, { runtime })` if you are not using `createDataset`. ## How the Query compiles to SQL | `Query` field | DuckDB SQL | | --- | --- | | `outFields` | quoted identifier projection; geometry projected as `ST_AsGeoJSON(...)` | | `where` | passed through verbatim, wrapped in `( … )` (caller-authored SQL, like GeoServices `where`) | | `spatialFilter` (envelope) | `ST_Intersects(<geom>, ST_MakeEnvelope(xmin, ymin, xmax, ymax))`, or a GeoParquet 1.1 `bbox` covering-column comparison (row-group prune) | | `spatialFilter` (point/polyline/polygon) | reduced to its bounding box; reported in `Result.degraded` as an approximation | | `orderBy` | `ORDER BY "field" ASC|DESC` | | `pagination` | `LIMIT` / `OFFSET` | | `aggregation` | `GROUP BY` with `count/sum/avg/min/max/stddev_samp/var_samp` metrics | | `returnGeometry: false` | geometry omitted from the projection | ### SQL-injection safety Every value the compiler interpolates is escaped: - **Identifiers** (`outFields`, `orderBy`, `groupBy`, geometry column): double-quoted with embedded quotes doubled; control characters rejected. - **String literals** (parquet URLs): single-quoted with embedded quotes doubled; NUL rejected. - **Numeric literals** (bbox, limit, offset): validated finite / non-negative. The one deliberate exception is `Query.where`, which — exactly like the GeoServices and OGC adapters — is caller-authored filter SQL passed through verbatim. The trust boundary on `where` is the caller's, identical to a GeoServices `where` clause. The compiler is covered by snapshot tests in `test/geoparquet-sql.test.ts`. ## Both metadata styles The source handles both geometry storage conventions, detected from the parquet footer and cached per source-URL set: 1. **GeoParquet 1.0 / 1.1 metadata files** — the `geo` key-value JSON is parsed for the primary geometry column, CRS, and (1.1) the `bbox` covering column. 2. **Parquet-native geometry** — a `GEOMETRY` / `GEOGRAPHY` column type (Parquet 2.11, March 2025), a raw WKB `BLOB`, or a GeoJSON string column, inferred from the DuckDB column type and conventional geometry column names. The physical encoding (`GEOMETRY` used directly, `BLOB` wrapped in `ST_GeomFromWKB`, string wrapped in `ST_GeomFromGeoJSON`) is keyed off the type DuckDB actually returns, so both styles produce an identical `Result` shape. ## `describe()` Reach the metadata through the typed escape hatch: ```ts doc-test=skip reason="partial excerpt requires application host context" const handle = places.protocol("geoparquet")!; const description = await handle.describe(); // { schema: HonuaFieldInfo[], geometryColumns: ["geometry"], // geometryEncoding: "wkb" | "native" | "geojson", crs: "OGC:CRS84", // rowEstimate: 12345 } ← rowEstimate from the parquet footer, no table scan const rows = await handle.sql("SELECT count(*) FROM read_parquet('...')"); // raw escape hatch ``` ## Aggregation ```ts doc-test=skip reason="partial excerpt requires application host context" const summary = await places.queryAggregate({ aggregation: { groupBy: ["categories.primary"], metrics: [{ fn: "count", field: "*", alias: "n" }], }, }); // summary.aggregateRows: [{ "categories.primary": "restaurant", n: 812 }, …] ``` ## Lifecycle & memory ceiling - A `GeoparquetRuntime` owns **exactly one** DuckDB instance and one Web Worker, created lazily on the first query and shared across every source it backs (NFR-001: single shared worker per client). - Call `resolver.dispose()` / `runtime.dispose()` when the owning client is torn down to terminate the worker. Disposal is idempotent. - DuckDB-WASM runs inside a single WASM linear memory with a **~4 GiB ceiling** (32-bit addressing). In practice keep the working set — scanned columns × matched rows, plus the spatial index — well under ~2 GiB. Prefer narrow `outFields`, push a `spatialFilter` down, and bound results with `pagination.limit` on large Overture extracts. - Parquet footers / row-group metadata are cached per source-URL set **inside the runtime**; there is no on-disk persistence. - `Source.stream()` uses DuckDB-WASM Arrow record batches when the driver supports them; `Source.query()` intentionally materializes its bounded result. `Query.signal` is forwarded to the browser driver's `cancelSent()` path. - Browser deployments can set `loadSpatial: false` when a GeoParquet `bbox` covering is sufficient, and can pin `extensionRepository` plus `preloadExtensions` to keep Parquet execution self-hosted. - Browser deployments reading large remote objects can set `filesystem: { reliableHeadRequests: true, allowFullHttpReads: false }` to require range-capable HTTP I/O and fail closed instead of allowing DuckDB-WASM's full-file fallback. ## Capability honesty `geoparquet` advertises `{ query, queryAggregate, stream }`. Everything else is an honest miss that throws `HonuaCapabilityNotSupportedError`: `queryExtent`, `queryObjectIds`, `queryRelated`, `applyEdits`, and `attachments`. The source is read-only (static files) and exposes no server-side ids/extent endpoint. There is no realtime path. ## Overture recipe Overture Maps ships monthly GeoParquet releases. The [`examples/overture-geoparquet`](../examples/overture-geoparquet/) demo runs entirely against a **fixture-sized extract committed to the repo** (no Honua server, CI-deterministic) and preserves GERS ids in results. For live Overture data, resolve a pinned file from Overture's STAC catalog before constructing the source. Do not hand a global glob to a browser without an AOI, projection, result limit, memory budget, cancellation, and file-level STAC selection: ```ts doc-test=skip reason="partial excerpt requires application host context" // Overture release layout (see https://docs.overturemaps.org/): const PINNED_ITEM = "https://overturemaps-us-west-2.s3.us-west-2.amazonaws.com/release/2026-06-17.0/theme=places/type=place/part-00000-6c973aba-862d-590f-a178-70bcd31cde1c-c000.zstd.parquet"; createDataset({ id: "overture-live", client, capabilityPolicy: "degraded", resolveSource: geoparquetResolver(), sources: [ { id: "places", protocol: "geoparquet", locator: { url: PINNED_ITEM }, capabilities: PROTOCOL_DEFAULT_CAPABILITIES.geoparquet, }, ], }); ``` Always send a `spatialFilter`, narrow `outFields`, `pagination.limit`, and `signal` against live Overture. A bbox predicate creates a pruning opportunity; it does not by itself prove bytes avoided or row groups skipped. The current browser driver does not expose its internal HTTP bytes/ranges, rows scanned, or row-group pruning metrics. The flagship sample reports those as unverified and uses an explicit execution deadline rather than falling back to full materialization. ## Regenerating the test fixtures The tiny committed fixtures under `test/fixtures/geoparquet/` are produced by `npm run geoparquet:fixtures` (which drives DuckDB-WASM's Node bindings). Only run it when the fixture schema changes. --- # File: docs/webmap-json-compatibility.md # WebMap JSON Compatibility Contract This document defines the compatibility contract for `parseWebMap()` in `@honua/sdk-js/webmap`. Version target: ArcGIS WebMap JSON `2.x` (current AGOL output). ## Output Contract `parseWebMap(input)` returns: - `style`: Honua/MapLibre style specification (`version: 8`) - `warnings`: non-fatal compatibility warnings (`code`, `path`, `message`, optional `context`) - `bookmarks`: passthrough WebMap bookmarks array - `popups`: popup metadata keyed by operational layer id Parser behavior: - Unsupported or unknown properties are warnings, not throw conditions. - Conversion aims to preserve visible map behavior for supported 2D properties. - Unsupported 3D and complex Arcade flows are explicitly called out for manual intervention. - The exploratory Cesium example under `docs/examples/cesium-route-playback/` consumes `HonuaClient.queryFeatures()` directly and does not expand `parseWebMap()` 3D support. ## Support Matrix | WebMap JSON area | Support | Notes | | --- | --- | --- | | `operationalLayers` | Partial | `ArcGISFeatureLayer` and `ArcGISMapServiceLayer` supported | | `baseMap` | Partial | Tiled basemap layers supported; vector basemap partial | | `spatialReference` | Partial | Web Mercator (3857/102100/102113) and 4326 handling | | `initialViewpoint` | Partial | `targetGeometry` point/extent + optional `scale` | | `initialExtent` | Full | Converted to `center`/`zoom` | | `bookmarks` | Full | Passed through in parser result | | Simple renderer | Full | Converted to layer paint/layout | | Unique value renderer | Full | Converted to `match` expressions | | Class breaks renderer | Full | Converted to `step` expressions | | Heatmap renderer | Unsupported | Warning emitted | | Dot density renderer | Unsupported | Warning emitted | | Popup `title`/`description` | Full | Preserved in popup config | | Popup `fieldInfos` | Full | Preserved in popup config | | Popup `mediaInfos` | Full (basic) | Preserved in popup config | | Popup `expressionInfos` | Unsupported | Warning emitted; manual intervention | | `labelingInfo` | Partial | Basic `$feature.FIELD` and simple concat only | | 3D properties | Unsupported | Warning emitted; manual intervention | ## Warning Codes Primary warning codes emitted by the parser: - `unknown-property` - `unsupported-webmap-version` - `unsupported-renderer` - `unsupported-symbol` - `unsupported-layer-type` - `unsupported-feature-collection` - `unsupported-spatial-reference` - `unsupported-viewpoint-geometry` - `unsupported-arcade-expression` - `unsupported-3d-property` - `complex-arcade` - `complex-label-expression` - `vector-tile-partial` - `sprite-required` ## Golden Fixtures Golden fixtures live under: - `test/fixtures/webmap-json/*/input.json` - `test/fixtures/webmap-json/*/expected.json` Fixture suite test: - `test/webmap-parse.test.ts` The suite is executed by `npm test`, which is required in CI (`.github/workflows/ci.yml`) on every PR and push to `trunk`. ## Manual Intervention Cases Manual intervention is expected for: - 3D scene properties and layer types - complex Arcade expressions in labels/popups - renderer types outside simple/uniqueValue/classBreaks - inline `featureCollection` content --- # File: docs/renderers.md # Renderer objects and temporal playback > Status: `@experimental` — the surfaces ship on the stable `/style` and > `/map` entrypoints but the descriptor shapes may still change in minor > releases. (Issue #497.) First-class renderer objects give standalone MapLibre users the smart-mapping vocabulary Esri/CARTO users expect — class breaks, unique values, heatmaps, clustering — without Honua becoming a renderer. A renderer object is a serializable, renderer-neutral description that compiles deterministically to MapLibre style fragments through the `/expr` builder. Compilation is a pure function: the same descriptor always produces byte-identical style JSON, and nothing is cached. ```ts doc-test=skip reason="requires a browser MapLibre host" import { classBreaksRenderer } from "@honua/sdk-js/style"; const renderer = classBreaksRenderer({ field: "magnitude", breaks: [ { min: 0, max: 3, label: "Minor" }, { min: 3, max: 6, label: "Moderate" }, { min: 6, label: "Strong" }, ], colors: ["#fed976", "#fd8d3c", "#b10026"], defaultColor: "#cccccc", }); const [fragment] = renderer.toMapLibre("point"); // "point" | "line" | "polygon" map.addLayer({ id: "quakes", type: fragment.type, source: "quakes", paint: fragment.paint }); renderer.legendItems(); // [{ kind: "class-break", label: "Minor", color: "#fed976", minValue: 0, maxValue: 3 }, …] ``` ## The four renderers All four factories live on `@honua/sdk-js/style` and share the same contract: `toMapLibre(geometryType)` returns layer fragments, `legendItems()` returns legend metadata, and `toJSON()` returns a serializable descriptor that `rendererFromJSON()` revives. | Factory | Compiles to | Notes | | --- | --- | --- | | `classBreaksRenderer({ field, breaks, colors?, defaultColor? })` | one `step` expression per styled property | `breaks[i].min ?? max` is the step threshold; positional `colors` fill in omitted break colors | | `uniqueValueRenderer({ field, values, defaultColor? })` | one `match` expression per styled property | `field2`/`field3` + `fieldDelimiter` concatenate multi-field keys | | `heatmapRenderer({ weightField?, radius?, intensity?, colorRamp? })` | a single `heatmap` layer fragment | `colorRamp` is explicit `{ stop, color }` stops or a color list spread evenly over density 0..1 | | `clusterRenderer({ radius?, maxZoom?, countField?, steps })` | `clusters` + `cluster-count` + `unclustered` fragments | `toMapLibreSource()` returns the GeoJSON-source cluster options; `countField` sums a property per cluster instead of counting points | Advanced entries accept a `style: { paint, layout }` override instead of the `color` shorthand — that is how WebMap symbols round-trip losslessly. ### Legend metadata (stable contract) `legendItems()` always yields `{ kind, label, color }`, with `value` on unique-value entries, `minValue`/`maxValue` on ranged entries (class breaks, cluster steps), and the ramp position in `value` for heatmap stops. A trailing `kind: "default"` item appears when the renderer declares a default color/label/style. Legend components can consume this without knowing the renderer kind. ### Serialization Descriptors are plain JSON: ```ts doc-test=skip reason="illustrative snippet" const descriptor = renderer.toJSON(); // safe to persist / send over the wire const revived = rendererFromJSON(descriptor); // identical compile output ``` ## One implementation everywhere WebMap JSON conversion (`@honua/sdk-js/webmap`'s `convertRenderer`) and the esri-compat renderer shims emit these objects and compile through the same `/expr` path — there is exactly one class-breaks/unique-value compiler in the SDK, and the WebMap converter's style output is unchanged byte for byte. - `uniqueValueRendererFromWebMap(renderer, warn)` / `classBreaksRendererFromWebMap(renderer, warn)` build renderer objects from WebMap renderer JSON. - `rendererObjectFromClassBreaksCompat(compat)` / `rendererObjectFromUniqueValueCompat(compat)` (on `/esri-compat`) project a `ClassBreaksRendererCompat` / `UniqueValueRendererCompat` shim to a renderer object plus any symbol-conversion warnings. ## Bridge integration `mountSource(map, source, { renderer })` derives the mounted layer set from a renderer object; explicit `paint`/`layout` overrides still win per property. A cluster renderer additionally configures GeoJSON-source clustering (`cluster`, `clusterRadius`, `clusterMaxZoom`, `clusterProperties`) and therefore requires the `"geojson"` strategy. ```ts doc-test=skip reason="requires a browser MapLibre host" import { mountSource } from "@honua/sdk-js/map"; import { uniqueValueRenderer, heatmapRenderer } from "@honua/sdk-js/style"; const mounted = await mountSource(map, data.source(), { renderer: uniqueValueRenderer({ field: "priority", values: [ { value: "high", color: "#b91c1c" }, { value: "low", color: "#0f766e" }, ], }), }); // Swap renderers without teardown where MapLibre allows: same layer // structure → per-property setPaintProperty/setLayoutProperty diff; // structural change → only the owned layers (and, for cluster-option // changes, the source) are recreated. await mounted.setRenderer(heatmapRenderer({ weightField: "priorityScore" })); ``` Diagnostics record which path ran: `renderer-applied` (in-place diff), `renderer-recreated-layers`, or `renderer-recreated-source`. ## Temporal playback `createTemporalPlayback` from `@honua/sdk-js/map` is a renderer-neutral play/pause/scrub controller over a time extent with a bounded frame cadence. It drives time filters through a thin binding — either the bridge handle (`MountedSource.setFilter` with a generated `where` clause) or client-side MapLibre layer filters composed with each layer's bind-time filter. ```ts doc-test=skip reason="requires a browser MapLibre host" import { createTemporalPlayback } from "@honua/sdk-js/map"; const playback = createTemporalPlayback({ handle: mounted, // or layer: { map, layerIds: ["quakes"] } for client-side filters timeField: "event_time", extent: ["2026-01-01T00:00:00Z", "2026-02-01T00:00:00Z"], windowMs: 24 * 60 * 60 * 1000, // one-day window stepMs: 6 * 60 * 60 * 1000, // advance six hours per frame frameIntervalMs: 400, loop: true, }); playback.on("tick", ({ window, progress }) => updateSlider(progress)); playback.play(); playback.scrub("2026-01-15T00:00:00Z"); playback.setWindow(3 * 24 * 60 * 60 * 1000); playback.dispose(); ``` Memory is bounded by construction (issue #497 REQ-004): the controller keeps only the current window, and filter application is coalesced — at most one request in flight plus the single latest pending window; intermediate windows are dropped, never queued. No window data is pre-fetched or cached by the controller. Playback over static data has no realtime dependency; layering it over a live feed is where #393's snapshot-plus-delta resume vocabulary applies, and that integration is intentionally out of scope here. For the `layer` binding the time property must be numeric (epoch milliseconds) because MapLibre filters compare numbers; the `handle` binding generates `<timeField> >= <startMs> AND <timeField> < <endMs>` by default and accepts a `formatWhere` override for servers that need date literals. ## Demos - [`examples/temporal-playback/`](../examples/temporal-playback/README.md) — class-breaks renderer + playback over a deterministic time-enabled fixture (mock lane, no network). - [`examples/service-explorer/`](../examples/service-explorer/README.md) and [`examples/realtime-incident-dashboard/`](../examples/realtime-incident-dashboard/README.md) build their categorical styling from `uniqueValueRenderer` instead of hand-written `match` expressions. --- # File: docs/maplibre-runtime.md # MapLibre GL JS Runtime (`@honua/sdk-js/runtime`) Status: implemented in `src/runtime/` (ticket `honua-sdk-js-21`). Public entrypoint: `@honua/sdk-js/runtime` (subpath export only; the root barrel does not re-export the runtime so hosts that do not need a map can avoid pulling in the MapLibre-aware code). The runtime binds a server-produced `MapPackage` (from `honua-io/honua-server#731`) to a caller-provided `maplibre-gl.Map`. It composes the style, projects `sourceBindings[]` through the shared `@honua/sdk-js/contract` adapters, applies `StyleRef` overrides and `ThemeSpec` tokens, wires popups / legend / initial view, and exposes a stable operational API for `#22` (mixed-protocol composition) and `#29` (operator components) to build on. The runtime **does not** instantiate `maplibre-gl.Map`, issue edit writes, or duplicate query logic — `maplibre-gl` stays a peer dependency, edits flow through the existing adapters, and queries go through the contract's `Source` handles. ## Standalone data-to-map bridge For the shortest path — any contract `Source` to a styled, interactive MapLibre layer set without a MapPackage, plan review, or Honua server — use `mountSource(map, source, options)` from `@honua/sdk-js/map` (`@experimental`). It selects bounded GeoJSON vs the dynamic query-tile path from capabilities plus a result-size heuristic, applies geometry-appropriate default styling, wires optional popups/hover, and returns one disposable handle with diff-updating `setFilter()`/`refresh()`. See the cookbook: [`docs/data-to-map-bridge.md`](./data-to-map-bridge.md). The plan-bound workflows below remain the right tool when you need fingerprinted plan review, provenance, and freshness policy. ## Accepted plan to native GeoJSON `@honua/sdk-js/map` includes the first production slice of the automatic source-to-map workflow. It executes an already-accepted query plan against a canonical `Source`, projects the result to a native MapLibre GeoJSON source, generates geometry-aware default layers, and owns refresh/disposal without importing `maplibre-gl`: ```ts doc-test=skip reason="partial excerpt requires application host context" import { mountSourceToMapLibre } from "@honua/sdk-js/map"; import { explainQuery } from "@honua/sdk-js/query-planner"; const plan = explainQuery({ descriptor: parcels.descriptor, query: { pagination: { limit: 5_000 }, outSr: 4326 } }); const mounted = await mountSourceToMapLibre(map, parcels, plan); console.table(mounted.diagnostics); await mounted.refresh(); mounted.dispose(); ``` The mount is peer-injected and therefore safe to import in browser, SSR, Node, and worker builds. `executeQueryPlan` verifies the accepted fingerprint and source context before querying. The adapter then: - selects the exact `geojson-query` strategy and records plan fingerprint, source/schema versions, authorization scope, attribution, and strategy on the projection; - promotes the descriptor primary key to MapLibre feature identity; - emits point, line, and polygon layers with stable ids and default paint, including filtered layers for mixed-geometry results; - reports empty, mixed, and unsupported-geometry states through stable machine-readable diagnostics rather than hiding fidelity loss; - rejects descriptor/runtime capability drift, aggregate or attribute-only plans, existing source/layer ids, invalid clustering, stale plan context, and renderer mutation failures with typed errors; - treats invalid, missing, and explicitly mismatched geometry as visible degraded diagnostics rather than an exact-ready map; - rolls back partial source/layer mutation (including renderers that mutate and then throw), serializes refreshes through `setData`, cancels in-flight work, and disposes its layers/source idempotently. The focused API remains available when an application has already chosen the materialized feature lane. The automatic workflow below composes it with the native tile and raster lanes without changing its plan-binding guarantees. ## Explain and mount automatically `explainAutomaticSourceToMapLibre` evaluates every currently representable lane before renderer mutation: bounded GeoJSON, vector tiles, vector/raster PMTiles, dynamic query tiles, native raster, WMS, and WMTS. It returns the selected and rejected candidates with stable reason codes, fidelity, native-versus-materialized path, optional-peer requirements, bounds, freshness, credential-free provenance, authorization scope, and cache implications. ```ts doc-test=skip reason="partial excerpt requires application source and host context" import { explainAutomaticSourceToMapLibre, mountAutomaticSourceToMapLibre, } from "@honua/sdk-js/map"; import { explainQuery } from "@honua/sdk-js/query-planner"; const queryPlan = explainQuery({ descriptor: parcels.descriptor, query: { pagination: { limit: 5_000 }, returnGeometry: true, outSr: 4326 }, sourceVersion: "parcels-2026-07-12", authorizationScope: ["parcels:read"], }); const strategyPlan = explainAutomaticSourceToMapLibre(parcels, { queryPlan }); console.table(strategyPlan.candidates); const mounted = await mountAutomaticSourceToMapLibre(map, parcels, strategyPlan, { queryPlan }); await mounted.ready; await mounted.refresh(); mounted.dispose(); ``` Native vector and PMTiles plans require an accepted `sourceLayer`; PMTiles also requires archive payload evidence (`pmtilesType`) from archive metadata. A dynamic query-tile plan accepts the pure source spec returned by `buildMapLibreQueryTileSourceSpec`. This avoids network discovery or protocol guessing inside the planner: ```ts doc-test=skip reason="partial excerpt requires an accepted query-tile descriptor" const strategyPlan = explainAutomaticSourceToMapLibre(parcels, { queryTileSource: buildMapLibreQueryTileSourceSpec(queryTileDescriptor), sourceLayer: "parcels", }); ``` Selection is fail-closed. Unsafe credential-bearing URLs, unsupported CRS, missing capabilities or metadata, unbounded feature queries, stale evidence, and ineligible explicit overrides produce typed diagnostics and no selected strategy. Freshness checks require an explicit `observedAt`, `now`, and `maxAgeMs`, keeping explanation deterministic. Mounting re-explains the source and policy to reject stale or tampered plans, checks cancellation before host mutation, rolls back partial native mounts, and provides one `ready`/`refresh`/`cancel`/`dispose` lifecycle. Native immutable/source-owned lanes use a no-op refresh; bounded GeoJSON delegates to the query-backed `setData` refresh. No API in this section imports `maplibre-gl` or `pmtiles`. This automatic slice does not complete the broader #390 application runtime. Owned map construction, generalized styling, labels/popups/selection, edits, realtime subscription orchestration, and the published browser sample matrix remain explicit residual work. ## Metadata-driven raster sources `@honua/sdk-js/map` can select and mount an exact raster strategy directly from a discovered `SourceDescriptor`. The peer-injected workflow supports native XYZ raster templates (`maplibre-raster`), WMS GetMap, and RESTful WMTS tiles: ```ts doc-test=skip reason="partial excerpt requires application host context" import { mountRasterSourceToMapLibre } from "@honua/sdk-js/map"; const mounted = mountRasterSourceToMapLibre(map, imagery.descriptor, { tileSize: 512, paint: { "raster-opacity": 0.85 }, }); console.log(mounted.strategy); // native-raster-tiles, wms-raster, or wmts-raster console.table(mounted.diagnostics); mounted.dispose(); ``` Selection is deterministic and fail-closed. All three strategies require the descriptor's `render` and `tiles` capabilities. Native raster URLs must contain the `{z}`, `{x}`, and `{y}` placeholders; WMS requires `locator.typeName`; WMTS requires both `locator.typeName` and `locator.tileMatrixSetId`. Unsupported vector, PMTiles, query-tile, and query-only descriptors throw `HonuaMapLibreRasterStrategyError` before map mutation instead of falling back to GeoJSON or guessing protocol metadata. `projectRasterSourceToMapLibre` is the pure projection half. It returns the selected strategy, native raster source, raster layer, and stable fidelity diagnostics without touching the renderer or network. The mount checks source and layer conflicts, rolls back renderers that mutate and then throw, and owns idempotent best-effort cleanup. Neither API imports `maplibre-gl`, so both are safe in Node, SSR, and worker module graphs. ## Module layout ``` src/runtime/ ├── index.ts # barrel — public surface ├── map-package.ts # HonuaMapPackage type (mirrors honua-server#731) ├── map-package-fetch.ts # hosted fetch + load-from-id helpers ├── map-package-validation.ts # typed validation diagnostics ├── map-package-watch.ts # disposable polling watcher ├── load-package.ts # loadMapPackage(pkg, map, opts) → HonuaMapRuntime ├── runtime.ts # HonuaMapRuntime class + event/telemetry types ├── source-bridge.ts # SourceBinding[] → SourceDescriptor[] + native sources ├── query-tiles.ts # dynamic query tile MapLibre helpers + request lifecycle ├── style-compose.ts # applyStyleRefs + applyTheme ├── diff.ts # MapPackageDiff primitives for updatePackage ├── popups.ts # bindPopup + default unstyled DOM renderer ├── legend.ts # buildLegend + swatch backfill └── errors.ts # HonuaMapPackageError (stages) ``` ## Public surface ```ts doc-test=skip reason="partial excerpt requires application host context" import maplibregl from "maplibre-gl"; import { HonuaClient } from "@honua/sdk-js"; import { loadMapPackage } from "@honua/sdk-js/runtime"; const map = new maplibregl.Map({ container: "map" }); const runtime = await loadMapPackage(pkg, map, { client: new HonuaClient({ baseUrl: "https://honua.example.com" }), popupFactory: () => new maplibregl.Popup(), }); runtime.setLayerVisibility("parcels-fill", false); const legend = runtime.getLegend(); await runtime.updatePackage(nextPkg); runtime.dispose(); ``` | Export | Shape | Notes | | --- | --- | --- | | `loadMapPackage(pkg, map, opts)` | `Promise<HonuaMapRuntime>` | Inline-package load entry point. Throws `HonuaMapPackageError` for binding failures under `sourceErrorPolicy: "fail-fast"`; under the default `"tolerant"` policy a single per-source binding failure does not abort the load — see *Tolerant binding* below. Query-time adapter failures surface on the per-`Source` promises from `runtime.dataset` and through the shared `HonuaClient` interceptor chain; consumers can broadcast them through `runtime.reportSourceError(sourceId, error)` to convert query-time rejections into the canonical `source-error` event. | | `fetchMapPackage(idOrLocator, opts)` | `Promise<FetchMapPackageResult>` | Fetches a hosted package through `HonuaClient.pipelineFetch`, validates it, resolves style refs when a resolver is supplied, and uses ETag / Last-Modified validators from the server when available. | | `loadMapPackageFromId(idOrLocator, map, opts)` | `Promise<LoadMapPackageFromIdResult>` | Builder-style helper: fetches a hosted package, then delegates to `loadMapPackage`. The result includes the runtime plus fetch diagnostics/cache state. | | `watchMapPackage(idOrLocator, opts)` | `MapPackageWatchHandle` | Opt-in polling watcher with `dispose()` and `refresh()`. It reuses `fetchMapPackage`, reports structural updates that require full style reload, and can apply updates to an existing `HonuaMapRuntime`. | | `validateMapPackage(pkg, opts)` | `ValidateMapPackageResult` | Returns typed diagnostics for format/version, missing sources, unsupported protocols, stale/expired packages, and style-ref target mismatches. | | `HonuaMapRuntime` | class | `map`, `honuaMap`, `dataset`, `mapPackage`, `composedStyle`, `getLegend`, `setLayerVisibility`, `bindPopup`, `setViewState`, `updatePackage`, `on`, `reportSourceError`, `dispose`. | | `runtime.hitTest(input, opts)` | `Promise<HonuaHitTestResult>` | Renderer-neutral hit-test wrapper over MapLibre `queryRenderedFeatures`. Returns normalized pointer location, source-qualified feature identities, raw rendered features, geometry/properties when supplied by the renderer, optional detail payloads, and typed degraded states for unsupported or partial renderer data. | | `runtime.onPointer(handler, opts)` | `{ remove() }` | Subscribes to `"click"`, `"dblclick"`, or `"mousemove"` and invokes `hitTest` for each pointer event. | | `HonuaMapPackage` | type | v1 package shape. `format` is gated against `HONUA_MAP_PACKAGE_FORMAT_V1` (`"honua_map_package.v1"`). | | `HONUA_MAP_PACKAGE_FORMAT_V1` | const | Canonical format tag. | | `HonuaMapPackageError` / `HonuaMapPackageErrorStage` | class / union | Stage union: `"load" \| "update" \| "style-compose" \| "source-bind" \| "view" \| "popup" \| "dispose"`. | | `HonuaRuntimeEvent` / `HonuaRuntimeEventListener` | types | See Events below. | | `HonuaRuntimeTelemetry` | type | `before` / `after` / `error` collector, matching the `HonuaRequestInterceptor` shape. | | `MaplibreMap` | interface | Duck-typed subset of `maplibre-gl.Map`; keeps the SDK bundle-neutral. | | `SetViewStateInput` | type | `{ bbox?, center?, zoom?, pitch?, bearing?, padding?, animate? }`. | | `applyStyleRefs`, `applyTheme`, `composeStyle` | functions | Pure helpers — safe to call outside a runtime for testing / SSR composition. | | `projectSourceBindings`, `toHonuaSourceSpec` | functions | Exposed for `#22` and adapter tickets that need the bridge without loading a package. | | `buildWmsRasterSourceSpec`, `buildWmtsRasterSourceSpec` | functions | Pre-bake a MapLibre `raster` source spec from a WMS / WMTS `SourceDescriptor`. Used by callers that compose a map outside `loadMapPackage`. See the source-binding projection table for the URL templates emitted on each protocol. | | `buildMapLibreQueryTileSourceSpec`, `buildQueryTileJson`, `buildQueryTileUrlTemplate`, `buildQueryTileUrl` | functions | Build TileJSON and MapLibre `vector` source specs from `QueryTileSourceDescriptor`. See [`dynamic-query-tiles.md`](./dynamic-query-tiles.md). | | `QueryTileRequestController`, `queryTilesForViewport`, `diagnoseQueryTileSourceSupport` | class / functions | Opt-in viewport tile lifecycle helper with abortable requests, bounded cache, diagnostics, and unsupported-protocol/fallback reporting. | | `hitTestMap`, `normalizePointerEvent`, `normalizeHitTestFeatures`, `createQueryTileDetailLoader` | functions | Framework-neutral interaction helpers exported from `@honua/sdk-js/interactions`; useful for apps that do not load a full `HonuaMapRuntime`. | | `diffPackages`, `MapPackageDiff` | function / type | Stable-id diff used by `updatePackage`. | | `buildLegend`, `LegendEntry` | function / type | Shared with operator components. | | `bindPopup`, `defaultPopupRenderer`, `PopupFactory`, `PopupRenderer` | function / types | The default DOM renderer is intentionally unstyled — rich popups belong in `#29`. | ## Loader options ```ts doc-test=skip reason="partial excerpt requires application host context" interface LoadMapPackageOptions { client: HonuaClient; resolveStyleRef?: (styleId: string, presetId?: string) => Promise<HonuaStyleRefBody>; resolveTheme?: (themeId: string) => Promise<HonuaMapPackageThemeSpec>; resolveSource?: SourceResolver; // forwarded to createDataset for tiles / MapLibre-native sources skipCompatibilityCheck?: boolean; // tests / conformance fixtures telemetry?: HonuaRuntimeTelemetry; popupFactory?: PopupFactory; // required only if runtime.bindPopup is called popupRenderer?: PopupRenderer; // defaults to defaultPopupRenderer applyInitialView?: boolean; // default true onEvent?: HonuaRuntimeEventListener; // subscribed BEFORE initial emissions sourceErrorPolicy?: "tolerant" | "fail-fast"; // default "tolerant" — see Tolerant binding styleSpecValidationMode?: "strict" | "warning-only" | "renderer-deferred"; // default "strict" } ``` `resolveStyleRef` and `resolveTheme` are only invoked when the package omits the inline body. Draft-1 of `honua-server#731` attaches both inline; out-of-band retrieval plugs in through these hooks without reopening the loader. `onEvent` is registered on the runtime before the first `source-ready` / `package-loaded` emissions, so callers that need to observe the initial lifecycle without racing against `loadMapPackage`'s return must use this hook instead of calling `runtime.on(...)` after `await`. Subsequent events (`package-updated`, `disposed`, ...) also flow through the same listener. Runtime source/layer mutation helpers lazily use `@maplibre/maplibre-gl-style-spec` without constructing a MapLibre map. `"strict"` reports style-spec errors as fatal `HonuaRuntimeDiagnosticError` entries before renderer mutation, `"warning-only"` preserves the diagnostics as warnings, and `"renderer-deferred"` skips SDK style-spec checks so the host renderer reports invalid values. ## Source and Layer Mutation `HonuaMapRuntime` owns the renderer-specific implementation used by `HonuaController`'s app-level CRUD surface. The API follows Mapbox GL source and layer concepts: ```ts doc-test=skip reason="partial excerpt requires application host context" runtime.addSource("dispatch", { type: "geojson", data: { type: "FeatureCollection", features: [] }, }); runtime.addLayer( { id: "dispatch-points", type: "circle", source: "dispatch", paint: { "circle-color": "#00a884", "circle-radius": 6 }, }, { beforeId: "parcels-fill" }, ); runtime.updateLayer("dispatch-points", { paint: { "circle-color": "#006f5f" }, metadata: { editedBy: "operator" }, }); runtime.moveLayer("dispatch-points", { position: "top" }); runtime.refreshSource("dispatch"); runtime.removeLayer("dispatch-points"); runtime.removeSource("dispatch"); ``` Supported source inputs include common native MapLibre source entries and Honua custom source entries for GeoServices, OGC Features, WMS, and WMTS. Query-tile sources can be created with `buildMapLibreQueryTileSourceSpec()`, while hosted MapPackage source bindings should continue to flow through `loadMapPackage()` or `updatePackage()` when server state is the source of truth. The mutation helpers validate source specs, layer specs, style expressions, filters, layer ordering, and duplicate/missing IDs before mutating the map. Renderer failures are wrapped as `HonuaRuntimeDiagnosticError` diagnostics. For incremental paint/layout/filter patches the runtime uses MapLibre's property setters when available; structural updates fall back to `setStyle(..., { diff: true })`. ## Hosted MapPackage Fetch Builder-style usage starts from a package id instead of an inline `MapPackage`: ```ts doc-test=skip reason="partial excerpt requires application host context" import { HonuaClient } from "@honua/sdk-js"; import { loadMapPackageFromId, watchMapPackage } from "@honua/sdk-js/runtime"; const client = new HonuaClient({ baseUrl: "https://honua.example.com" }); const { runtime, diagnostics } = await loadMapPackageFromId("map_123", map, { client, popupFactory: () => new maplibregl.Popup(), resolveStyleRef: (styleId, presetId) => fetchStyleBody(styleId, presetId), }); for (const diagnostic of diagnostics) { console.warn(diagnostic.code, diagnostic.message); } const watcher = watchMapPackage("map_123", { client, runtime, intervalMs: 30_000, onEvent: (event) => { if (event.type === "reload-required") { console.info(event.reason); } }, }); // Later, when the host tears down the map: watcher.dispose(); ``` `fetchMapPackage` accepts either an id (`"map_123"`), a direct path or same-origin URL, a `honua://map-packages/{id}` locator, or an object with `id`, `packageId`, `path`, `url`, or `href`. Id locators default to `/api/v1/map-packages/{id}`; pass `resolvePath` when a deployment uses a different hosted package route. For low-latency hosted package updates, `watchMapPackage` can use a configured or package-advertised realtime channel and fall back to polling when the channel is unavailable. See [`map-package-realtime-watch.md`](./map-package-realtime-watch.md) for the message schema, lifecycle events, reconnect behavior, auth notes, and fallback contract. Fetch results include: - `mapPackage`: the validated package, with missing style-ref bodies inlined when `resolveStyleRef` succeeds. - `diagnostics`: typed warnings/errors for unsupported formats, missing source bindings, unsupported protocols, stale packages (`maxAgeMs`), expired packages (`status: "Expired"` or `expiresAt`), missing layer sources, and style-ref resolution failures. - `cache`: SDK fetch cache state. The helper stores validators in a per-client in-memory cache by default. On later fetches it sends `If-None-Match` / `If-Modified-Since` when the server supplied ETag or Last-Modified. Pass `cache: false` to bypass the SDK cache, or pass a `MapPackageFetchCache` to share cache state across clients/tests. Validation errors throw `HonuaMapPackageError { stage: "validate" }` with `{ diagnostics }` in `detail`. Pass `allowInvalid: true` when a host wants to display diagnostics without rejecting the fetch. ### Tolerant binding (`sourceErrorPolicy`) `loadMapPackage` defaults to `sourceErrorPolicy: "tolerant"`: a single per-source binding failure (resolver throws, `toHonuaSourceSpec` throws, eager `dataset.source(id)` materialization throws) does not abort the load. The failed source is dropped from the composed style along with any layer whose `source` references it; the runtime emits one `source-error` event per failed source after the `source-ready` events and before `package-loaded`; `HonuaRuntimeTelemetry.error` receives a `source-bind` span. Remaining sources continue to render. Pass `sourceErrorPolicy: "fail-fast"` to restore the historical single-source behaviour, where any binding failure rejects the load with `HonuaMapPackageError({ stage: "source-bind" })`. Configuration-level binding errors (unknown protocol, missing `locator.url`, duplicate `sourceId`, deferred `workspace_artifact`) raised by `projectSourceBindings` always fail-fast under either policy — those are operator errors that must be fixed. Mixed-source consumers that fan a query out across the dataset can broadcast a query-time rejection back through the runtime by calling `runtime.reportSourceError(sourceId, error)` — the helper emits the same `source-error` event and pipes the failure through the `source-bind` telemetry span, so observers see one consistent per-source error channel for both bind-time and query-time failures. The full guide lives in [`composition.md`](./composition.md). ## Hit Testing and Pointer Events `hitTest` accepts a MapLibre-style event, `{ point, lngLat }`, or a raw DOM pointer event. It returns screen point, optional longitude/latitude, and a feature stack normalized to Honua source identity: ```ts doc-test=skip reason="partial excerpt requires application host context" const hit = await runtime.hitTest(event, { layers: ["incidents-symbol", "incidents-fill"], sourceIds: ["incidents"], featureIdProperty: "incident_id", tolerance: 4, maxResults: 5, }); const first = hit.features[0]; if (first?.selectionTarget) { view.select([first.selectionTarget], { replace: true }); } ``` Every `HonuaHitFeature` includes `layerId`, `sourceId`, `sourceLayer`, `featureId`, `selectionTarget`, `properties`, `geometry`, `rawFeature`, and `degraded[]` when the renderer omits a field. The top-level result also has `degraded[]`; for example, non-MapLibre renderers without `queryRenderedFeatures` return an empty feature list plus `{ reason: "renderer-unsupported" }`. Optional detail loading is bounded by the caller's `AbortSignal`: ```ts doc-test=skip reason="partial excerpt requires application host context" const controller = new AbortController(); const hit = await runtime.hitTest(event, { layers: ["incidents-symbol"], queryTileSources: { incidents: incidentsQueryTileDescriptor }, loadDetails: true, signal: controller.signal, }); ``` When `queryTileSources` includes a descriptor for the hit source, the runtime composes with the existing query-tile detail path and `runtime.dataset.source(sourceId)`. Without a descriptor it falls back to a single-feature source query when an id field is available. Failed, aborted, or unavailable detail reads are reported in `feature.degraded` instead of rejecting the whole hit-test result. Apps that do not use `HonuaMapRuntime` can use the neutral helpers directly: ```ts doc-test=skip reason="partial excerpt requires application host context" import { hitTestMap } from "@honua/sdk-js/interactions"; map.on("click", async (event) => { const hit = await hitTestMap(map, event, { layers: interactiveLayerIds, sourceIds: ["incidents"], featureIdProperty: "incident_id", maxResults: 1, }); openInspector(hit.features[0]); }); ``` ## `MapPackage` version gate - `pkg.format` must equal `HONUA_MAP_PACKAGE_FORMAT_V1` (`"honua_map_package.v1"`). The loader throws `HonuaMapPackageError { stage: "load" }` for any other value. - `updatePackage(next)` throws `HonuaMapPackageError { stage: "update" }` when `next.format` does not match the already-loaded format so version mismatches surface at the call site rather than silently corrupting the map. - Unknown fields on `HonuaMapPackage` (and on each `SourceBinding` locator) are preserved on round-trip through `updatePackage`, so minor additive changes on the server do not force a runtime bump. ## Source binding projection `projectSourceBindings` routes each `SourceBinding` to one of three destinations, using the alignment table in [`source-binding-alignment.md`](./source-binding-alignment.md): | Server wire protocol (snake_case) | Route | SDK protocol / source type | | --- | --- | --- | | `geoservices_feature_service` | contract adapter | `geoservices-feature-service`, custom source type `honua-feature-service`. | | `geoservices_map_service` | contract adapter | `geoservices-map-service`, custom source type `honua-map-service`. | | `ogc_features` | contract adapter | `ogc-features`, custom source type `honua-ogc-features`. Collection id is copied from `locator.collectionId`. | | `wfs` | contract adapter | `wfs` (built-in), custom source type `honua-wfs`. `locator.typeName` (and optional `locator.featureNamespace`) are forwarded; first-party WFS 2.0 adapter ships in `@honua/sdk-js/contract`. | | `wms` | contract adapter | `wms`, custom source type `honua-wms`. `locator.typeName` projects as `layers`, `locator.styleId` as `styles`. Use `buildWmsRasterSourceSpec(descriptor)` to produce a MapLibre-ready `{ type: "raster", tiles, tileSize }` spec with a pre-baked KVP `GetMap` template that uses MapLibre's `{bbox-epsg3857}` / `{width}` / `{height}` placeholders. | | `wmts` | contract adapter | `wmts`, custom source type `honua-wmts`. `locator.typeName` / `locator.styleId` / `locator.tileMatrixSetId` project as `layer` / `style` / `tileMatrixSet`. Use `buildWmtsRasterSourceSpec(descriptor)` to produce a MapLibre-ready `{ type: "raster", tiles, tileSize, scheme: "xyz" }` spec using the RESTful `{layer}/{style}/{tms}/{z}/{y}/{x}.{ext}` route. | | `odata` | contract adapter | `odata`. The entity-set request path comes from `locator.entitySet` when set; otherwise it is derived from `locator.layerId` as `Layers(<layerId>)/Features` to match Honua Server's layer-scoped OData routes. Optional path prefix from `locator.url`. | | `vector_tile` / `ogc_tiles` | MapLibre-native | Projected to a `{ type: "vector", tiles: [url], attribution? }` source entry — no contract adapter. | | `raster_tile` / `ogc_maps` | MapLibre-native | Projected to a `{ type: "raster", tiles: [url], attribution? }` source entry. | | `workspace_artifact` | deferred | Throws `HonuaMapPackageError { stage: "source-bind" }` — no artifact resolver is wired yet. | `geoservices-image-service`, `geoservices-geometry-service`, and `geoservices-gp-service` are contract-layer adapters (constructed directly via `geoServicesImageSource`, `geoServicesGeometryServiceSource`, `geoServicesGPServiceSource`) and are not currently translated by `source-bridge.ts`. ImageServer / Geometry / GP bindings on a `MapPackage` are rejected at `stage: "source-bind"` because those services are typically utility / non-map surfaces; routing them through the runtime is a follow-on for downstream tickets that need ImageServer rasters or geoprocessing tasks composed alongside a map. Additional contract: - Duplicate `sourceId` across bindings is rejected at `stage: "source-bind"`. - A protocol-backed binding without a `locator.url` is rejected at `stage: "source-bind"`. - `binding.filter` is captured per source id and passed through to the Honua custom source spec (`definitionExpression` on `honua-feature-service`, `filter` on `honua-ogc-features` and the generic fallback). Edits never flow from the runtime. - Locator fields are normalized during projection so the shared contract adapters can bind even when the server ships a URL-only `SourceBinding.locator`: - **GeoServices Feature / Map Service**: `serviceId` and numeric `layerId` are parsed from the canonical `/rest/services/<name>/FeatureServer/<id>` or `/rest/services/<name>/MapServer/<id>` URL shape when the binding omits them. Explicit locator fields always win over parsed ones. - **OGC API Features**: `collectionId` is parsed from the `/collections/<id>` URL segment when omitted. - **WMS / WMTS**: `serviceId` is parsed from `/rest/services/<name>/MapServer/WMS` (and `/WMTS`) and from `/ogc/services/<name>/wms` (and `/wmts`) when the binding omits it. `locator.typeName` and `locator.styleId` are not URL-derived today; the server ships them when a binding pins a specific layer or style. - **OData**: the server `SourceLocator` carries only `url`, `serviceId`, and `layerId`, so `entitySet` is typically absent on bindings produced by the server. The `odataSource` adapter derives the canonical layer-scoped request path `Layers(<layerId>)/Features` from `locator.layerId` when `locator.entitySet` is absent (see the *OData* notes in [`protocol-capability-matrix.md`](./protocol-capability-matrix.md) for the exact resolution rule). - **`locator.layerId`**: the server's canonical `SourceLocator.LayerId` is `string?`, so `HonuaMapPackageLocator.layerId` is typed `number | string`. Numeric strings (e.g. `"0"`) are coerced to numbers during projection; non-numeric strings are left unset so the adapter surfaces the typed validation error. - Capabilities for protocol-backed descriptors are always sourced from `PROTOCOL_DEFAULT_CAPABILITIES[protocol]` (see [`protocol-capability-matrix.md`](./protocol-capability-matrix.md)). The server `SourceBinding` shape does not carry a `capabilities` field today, and the runtime does not expose a hook to downgrade per-source capabilities — callers that need a narrower set must call `createDataset` directly and pass explicit `SourceDescriptor` entries, then bind the map through the lower-level SDK primitives. ## Style composition `composeStyle` runs two passes over `pkg.mapSpec`: 1. **`applyStyleRefs`** merges each `styleRefs[*].body` onto its corresponding layer by id. The body is a `Record<string, HonuaStyleRefLayerOverride>` where keys are `mapSpec.layers[].id` and values carry any of `paint`, `layout`, `minzoom`, `maxzoom`, `filter`, `metadata`. Unknown layer ids are silently skipped (they may belong to a downstream adapter plugin). If `ref.body` is absent and no `resolveStyleRef` was supplied, the loader throws `HonuaMapPackageError { stage: "style-compose" }`. 2. **`applyTheme`** substitutes `{theme:key}` placeholders in string `paint` / `layout` values against `pkg.theme.tokens` (or the resolved `pkg.themeId` body). Only a full-string match on `/^\{theme:([^}]+)\}$/` is replaced — substring interpolation is not supported in v1. Unresolved tokens are left untouched so authors can flag missing tokens at review time. Theme application recurses into nested arrays / objects inside `paint` / `layout` so expression literals can reference theme tokens. ## Operational API | Method | Behavior | | --- | --- | | `addSource(sourceId, source)` | Adds a Honua custom source or MapLibre-native source to `runtime.honuaMap`, `runtime.composedStyle`, and the host map via `map.addSource()` when available. Falls back to `setStyle(..., { diff: true })` for renderer adapters that only expose full style application. | | `updateSource(sourceId, source)` | Replaces a source spec and reapplies the composed style while preserving layer ids. Use for locator/data/source-option changes; paint/layout/filter-only updates should use layer helpers to avoid source reloads. | | `removeSource(sourceId)` | Removes the source and any dependent layers from the runtime style, `HonuaMap`, and host map. Returns the removed layer ids. | | `addLayer(layer, order?)` | Adds a typed layer spec, validates paint/layout/filter expressions first, and supports MapLibre `beforeId` as a string or `{ beforeId }`, `{ afterId }`, `{ position: "top" | "bottom" }`. | | `updateLayer(layerId, patch)` | Patches layer paint/layout/filter in place with `setPaintProperty` / `setLayoutProperty` / `setFilter` when the layer shape is stable. Structural layer changes or explicit reordering use a diffed `setStyle` path. | | `removeLayer(layerId)` / `moveLayer(layerId, order?)` | Removes or reorders runtime-owned layers while keeping `runtime.composedStyle` and `runtime.honuaMap` aligned with the renderer. | | `setLayerPaint(layerId, paint)` / `setLayerLayout(layerId, layout)` / `setLayerFilter(layerId, filter)` | Convenience wrappers around `updateLayer` for common Mapbox-style style changes. | | `setLayerVisibility(layerId, visible)` | `map.setLayoutProperty(layerId, "visibility", …)`. | | `validateStyleExpression(value)` / `validateFilterExpression(filter, layerId?)` | Runs Honua expression checks plus MapLibre style-spec validation when enabled, returning typed diagnostics with path, layer id, source id, protocol, severity, and MapLibre validation context. Mutating helpers throw `HonuaRuntimeDiagnosticError` before touching the renderer when diagnostics contain errors. | | `getLegend()` | Runs `buildLegend` against the current package and composed style; backfills missing swatches from the first `fill-color` / `circle-color` / `line-color` paint property when it is a string literal. | | `bindPopup(layerId, binding?)` | Requires `opts.popupFactory`. When `binding` is omitted the runtime looks up `pkg.popupBindings[]` by the layer's source id. The default renderer emits an unstyled `<dl>` of the first feature's properties (or a `{field}` template when `binding.template` is set). Returns a `{ remove() }` handle; re-binding on the same layer tears down the prior handle. | | `bindHover(layerId, options?)` / `bindClick(layerId, handler, options?)` / `bindSelect(layerId, options?)` | Infers source and source-layer from the runtime layer, binds MapLibre layer events, and manages hover/click/select feature-state without requiring app code to pass MapLibre types. `bindClick` emits a source-qualified selection target when a feature id is available. | | `bindSelectionToExploration(layerId, view, options?)` / `syncSelectionFromExploration(layerId, view, options?)` | Bridges runtime layer interactions to `ExplorationContext` selection and reflects source-qualified shared selection back into MapLibre feature-state. | | `layerSelectionTarget(layerId, id)` / `setFeatureStateForTarget(target, state)` / `getFeatureStateForTarget(target)` / `removeFeatureStateForTarget(target, key?)` | Converts layer + feature id pairs into source-qualified targets and applies feature-state using either runtime targets or `ExplorationContext` source-qualified targets. | | `setViewState(view)` | If `view.bbox` is supplied and `map.fitBounds` exists, fits the bounds (`animate: false` by default). Otherwise falls back to `map.jumpTo` for `center` / `zoom` / `pitch` / `bearing`. A final fallback applies `pkg.initialView.bbox` when no input is given. | | `updatePackage(next)` | See the Update lifecycle section. | | `on(listener)` | Subscribes to `HonuaRuntimeEvent`. Returns a `{ remove() }` handle. | | `dispose()` | Clears popup bindings, removes every layer and source owned by the composed style via `honuaMap.clear()` + `map.removeLayer` / `map.removeSource`, emits `disposed`, and rejects subsequent mutating calls. Idempotent. | `runtime.map`, `runtime.honuaMap`, `runtime.dataset`, `runtime.mapPackage`, and `runtime.composedStyle` are readable at any time. The runtime helpers delegate to the lower-level `src/interactions/feature-state` and `src/interactions/exploration-bindings` modules, so apps can still use those lower-level primitives directly when they need custom behavior. ## Update lifecycle `updatePackage(next)` does three things in order: 1. **Format gate.** `next.format` must match the currently loaded format, or the call throws `HonuaMapPackageError { stage: "update" }` before any map mutation. 2. **Diff.** `diffPackages(previous, next)` produces a `MapPackageDiff` keyed by stable ids: - Added / removed / changed source bindings (locator, filter, attribution, or protocol differences). - Added / removed / changed layer ids (paint, layout, filter, source, source-layer, min/max zoom, metadata). - A `structuralReason` string and `incremental: false` when any of the following hold: `mapSpec.version` changed, the layer set changed, the layer order changed, any source binding was added / removed / changed, OR the composed layer changed outside the runtime's paint / layout / filter patch surface. Source-binding changes force the structural path because the runtime must rebuild the underlying `Dataset` and `HonuaMap` so `runtime.dataset.source(id)` observes the new locator / filter. 3. **Apply.** If `diff.incremental` is false, the runtime rebuilds the composed style and calls `map.setStyle(composed)` first; only once that returns does it clear the old `HonuaMap` and swap in the freshly projected `dataset` / `honuaMap` references. This ordering guarantees that if the host map's `setStyle` throws, the runtime's previous state — `dataset`, `honuaMap`, `mapPackage`, `composedStyle`, and all popup bindings — is left intact so the caller can retry without a half-applied update. After a successful swap, any popup binding whose layer id is no longer present, whose layer source changed, or whose package-resolved binding changed is torn down so stale click listeners do not linger. Otherwise it removes dropped layers, patches changed layers in place via `setPaintProperty` / `setLayoutProperty` / `setFilter`, and emits a single `package-updated` event with the diff attached. Theme-only tweaks and single-layer paint/filter edits never trigger a full `setStyle`; root layer changes such as `minzoom`, `maxzoom`, `metadata`, `source`, `source-layer`, or `type` do. Incremental layer patching iterates the **union** of previous and next paint / layout keys. Keys present in the previous layer but dropped in the next are cleared by calling `setPaintProperty(layerId, key, undefined)` / `setLayoutProperty(layerId, key, undefined)` so MapLibre resets them to the property default rather than retaining the stale value. Identical values are short-circuited with a strict-equality check so unchanged properties do not trip a MapLibre setter call. After any structural reload, `runtime.dataset` and `runtime.honuaMap` return the new references (both are exposed through getters, not fixed `readonly` fields, so live callers see the refreshed state immediately). ## Events Subscribe through `LoadMapPackageOptions.onEvent` to observe the initial emissions, or `runtime.on(listener)` for subsequent events. `onEvent` is the only way to capture `source-ready` / `package-loaded` on a successful load because those events are dispatched synchronously before `loadMapPackage` returns the runtime handle. `runtime.on(...)` handles every subsequent event. | Event | Emitted when | | --- | --- | | `{ type: "package-loaded", packageId }` | After the first `setStyle` + initial view apply succeed. Fired last, once per successful load. | | `{ type: "source-ready", sourceId }` | Once per source id produced by the contract `Dataset`, fired synchronously just before `package-loaded`. | | `{ type: "source-error", sourceId, error }` | Per-source binding or query-time failure. Under `sourceErrorPolicy: "tolerant"` the loader emits one `source-error` per source whose bind-time projection / spec-build / eager materialization threw; the runtime fans this through the listener chain right after `source-ready` and before `package-loaded`, with telemetry observing a `source-bind` error span. Consumers that fan a query out across the dataset broadcast query-time rejections through `runtime.reportSourceError(sourceId, error)`, which emits the same event so listeners do not have to subscribe to a parallel error channel. | | `{ type: "package-updated", packageId, diff }` | After `updatePackage` completes (both incremental and full-`setStyle` paths). | | `{ type: "layer-rendered", layerId }` | Declared for MapLibre render callbacks bridged by the host. The runtime itself does not fire it today. | | `{ type: "disposed", packageId }` | Once inside `dispose()`, just before listeners are cleared. | Listeners fire synchronously in subscription order. Adapter-level request errors continue to flow through the `HonuaClient` interceptor chain for trace correlation — the runtime does not add a parallel pipeline. ## Errors `HonuaMapPackageError` wraps every runtime-binding failure and carries `{ packageId, stage, detail, cause }`. Stages: - `load` — format validation, `mapSpec` missing, unknown loader error. - `update` — `updatePackage` format mismatch or unhandled error. - `style-compose` — missing style-ref body with no resolver, theme resolver threw, general composition failure. - `source-bind` — unknown protocol, missing locator, duplicate source id, deferred `workspace_artifact`. - `view` — `initialView` application failed. - `popup` — `bindPopup` called without a `popupFactory`, or no binding found for the layer. - `dispose` — mutating call after `dispose()`. Per-source protocol failures keep their existing classes (`HonuaCapabilityNotSupportedError`, `HonuaHttpError`, adapter-specific errors) and are not wrapped by the runtime. They surface on the per-`Source` promises exposed by `runtime.dataset` and through the shared `HonuaClient` interceptor chain. The runtime additionally emits `source-error` events for per-source binding failures absorbed under the tolerant policy and for any query-time rejection a consumer broadcasts through `runtime.reportSourceError(sourceId, error)`. See *Tolerant binding* above and [`composition.md`](./composition.md) for the full mixed-source contract. ## Telemetry `HonuaRuntimeTelemetry` is a `{ before?, after?, error? }` collector matching the `HonuaRequestInterceptor` contract. The runtime emits spans for `kind: "load" | "update" | "dispose" | "source-bind" | "popup"` with `startedAt` / `finishedAt` / `durationMs`. The `source-bind` error span fires once per source whose binding fails under the tolerant `sourceErrorPolicy`, and once per call to `runtime.reportSourceError(sourceId, error)`; its `detail` carries `{ sourceId }` so observability stacks see the failure alongside other runtime spans. Adapter traffic is still instrumented through the shared `HonuaClient` interceptor chain, so distributed-trace correlation is preserved end-to-end. ## Peer dependency posture - `maplibre-gl` is a peer/dev dependency — the runtime never imports it at the type or value level. `MaplibreMap` and `PopupHandle` are duck-typed, matching the pattern used by `src/interactions/feature-state`. - Hosts pass their own `maplibre-gl.Map` instance. Custom subclasses and third-party wrappers (deck.gl overlay, OpenLayers bridge) are supported as long as they satisfy the `MaplibreMap` method shape. - `popupFactory` keeps the popup dependency on the host side; omit it when the app does not call `runtime.bindPopup`. ## Test coverage `test/runtime/runtime.test.ts` exercises the full `load → updatePackage → dispose` lifecycle against a recording mock map (31 tests). Behavior covered includes: - Format gate rejects non-v1 packages and `workspace_artifact` bindings surface `HonuaMapPackageError { stage: "source-bind" }`. - Source projection routes each protocol to the correct destination, captures filters, translates `snake_case` server protocol names to `kebab-case` SDK protocols, and rejects duplicate source ids. - `composeStyle` applies `StyleRef` overrides; `applyTheme` substitutes `{theme:key}` placeholders and leaves unknown tokens in place. - `diffPackages` flags structural changes (layer reorder, mapSpec version bump, source bindings added / removed / changed), and the runtime promotes composed root-layer changes to the same path; incremental patches update paint / layout / filter without re-running `setStyle`. - Event stream emits `package-loaded`, `source-ready`, `package-updated`, `disposed` in the documented order. - `dispose` removes layers and sources in reverse and ignores subsequent calls; further mutating calls throw `stage: "dispose"`. Regression coverage added alongside this release (+11 tests) locks in the fix-pass behaviors: - **Source-binding structural fallback.** A locator change or a new binding forces a full `setStyle` *and* swaps `runtime.dataset` / `runtime.honuaMap` to fresh references so `runtime.dataset.source(id)` observes the new locator / filter. - **Paint / layout key removal.** Removing a paint or layout key (e.g. dropping `fill-opacity` or `fill-sort-key` from the next layer) calls `setPaintProperty` / `setLayoutProperty` with `undefined` so MapLibre resets the property instead of retaining the stale value. - **URL-only locator backfill.** `projectSourceBindings` parses `serviceId` / numeric `layerId` from a canonical `/rest/services/<name>/FeatureServer/<id>` (and `MapServer` variant) URL when the binding omits them, parses `collectionId` from `/collections/<id>` for OGC API Features bindings, and coerces numeric-string `layerId` values to numbers so the C# server mirror (which serialises `LayerId` as a string) still binds through the built-in adapters. An end-to-end test loads a URL-only GeoServices binding and verifies `runtime.dataset.source(id).adapter(...)` is reachable. - **`onEvent` captures initial lifecycle.** `LoadMapPackageOptions.onEvent` receives `source-ready` and `package-loaded` without racing against `loadMapPackage`'s `await`-return. - **Structural-update error containment.** When `map.setStyle` throws during a structural `updatePackage`, the previous `honuaMap` / `dataset` / `mapPackage` references are preserved so the runtime is not left half-applied. - **Popup reap on layer removal.** A structural update that drops a previously bound layer tears down the layer's popup click listener before emitting `package-updated`. - **Non-patchable composed layer changes.** A package update that changes a root layer field such as `minzoom` routes through `setStyle` rather than claiming an incremental paint/layout/filter patch applied it. - **Popup reap on binding changes.** Updating `popupBindings[]` for an active package-resolved popup tears down the existing click listener so the closed-over binding cannot go stale. Conformance-style assertions rely only on the duck-typed `MaplibreMap` interface so no `maplibre-gl` dependency creeps into the SDK's runtime bundle. ## Deferred follow-ups - `workspace_artifact` resolver wiring — blocked on server surface. - Partial-load recovery (skip unresolved sources, continue) — the loader is strict in v1; an `opts.allowPartial` escape hatch is tracked alongside `#22` mixed-source composition. - Refinement / preview components — opaque pass-through today; `#29` operator components are the documented home. - Finer-grained diff primitives (layer reorder without teardown) — extension point already in `diff.ts`; no consumer yet. --- # File: docs/terra-draw-sketch.md # terra-draw sketch binding (`@honua/sdk-js/runtime`) Status: experimental (issue `#492`, Esri Widget Cliff workstream). Public entrypoint: `@honua/sdk-js/runtime` — `bindTerraDrawSketch`, `createTerraDrawSketch`, `createTerraDrawSnapping`, `terraDrawSketchToolCapabilities`, `editSketchToolForTerraDrawMode`, `TERRA_DRAW_SKETCH_TOOL_MODES`. Interactive drawing on the MapLibre path is provided by [terra-draw](https://terradraw.io), the engine-agnostic community successor to mapbox-gl-draw. The SDK does not fork or wrap terra-draw's rendering — it adapts terra-draw's mode events onto the renderer-neutral `EditSketchWorkflowModel` from `@honua/sdk-js/contract`, so undo/redo, validation, snapping configuration, and edit-session `applyEdits` submission are workflow features that apply to every sketch the same way. ## Peer setup `terra-draw` and `terra-draw-maplibre-gl-adapter` are **optional** peer dependencies. The SDK never imports them at module scope: `bindTerraDrawSketch` accepts a duck-typed instance your app constructed, and `createTerraDrawSketch` loads both packages lazily via dynamic `import()` (throwing a descriptive error when they are missing). Importing `@honua/sdk-js/runtime` without terra-draw installed stays side-effect free; the `tree-shake:runtime-terra-draw-sketch` bundle-budget fixture guards this. ```bash npm i terra-draw terra-draw-maplibre-gl-adapter # only if you use the binding ``` ## Modes and tools terra-draw mode names map onto the contract `EditSketchTool` values: | terra-draw mode | `EditSketchTool` | | --- | --- | | `point`, `marker` | `point` | | `linestring`, `polyline`, `freehand-linestring` | `line` | | `polygon`, `freehand`, `sector`, `sensor` | `polygon` | | `rectangle`, `angled-rectangle` | `rectangle` | | `circle` | `circle` | | `select`, `render`, `static`, custom modes | — (not applied) | The contract defaults mark `rectangle` and `circle` as unsupported (they need renderer support); pass `terraDrawSketchToolCapabilities()` as the workflow's `sketchTools` to mark the terra-draw-backed tools supported. `buffer` stays unsupported — it needs geometry-service support, not a drawing engine. ## One-call setup ```ts doc-test=skip reason="partial excerpt requires a map instance and an editable source" import { createEditSketchWorkflow, createSnapIndex } from "@honua/sdk-js/contract"; import { createTerraDrawSketch, terraDrawSketchToolCapabilities } from "@honua/sdk-js/runtime"; const workflow = createEditSketchWorkflow({ source, // any editable contract Source kind: "create", feature: { attributes: {} }, sketchTools: terraDrawSketchToolCapabilities(), snapping: { enabled: true, tolerance: 16 }, }); const index = createSnapIndex(); index.setSourceFeatures("parcels", parcels); const sketch = await createTerraDrawSketch(map, { model: workflow, snapping: { index, model: workflow }, }); sketch.setTool("polygon"); // user draws on the map sketch.undo(); // workflow history, mirrored back into terra-draw await workflow.submit(); // edit-session applyEdits path, unchanged ``` Every terra-draw `finish` event — freshly drawn features and select-mode edits (dragged features, dragged/inserted/deleted coordinates) — flows through `model.setSketchGeometry`, so each is one undoable workflow step. Deleting the tracked feature stages an undoable `null` geometry. `undo()`/`redo()` on the handle drive the model and push the restored geometry back into terra-draw. Apps that need custom terra-draw mode options construct the instance themselves and call `bindTerraDrawSketch(draw, { model })` — the binding only attaches listeners (detached by `handle.remove()`). ## Geometry round-trip and reprojection terra-draw emits EPSG:4326 GeoJSON. When the edit source stores another CRS, pass the `@honua/sdk-js/geometry` reprojection helpers through the binding: ```ts doc-test=skip reason="partial excerpt requires a terra-draw instance and workflow model" import { toWebMercator, toWgs84 } from "@honua/sdk-js/geometry"; bindTerraDrawSketch(draw, { model, transformGeometry: (g) => toWebMercator(g, 4326), // model/applyEdits side restoreGeometry: (g) => toWgs84(g, 3857), // terra-draw side (undo/redo sync) }); ``` ## Snapping `createTerraDrawSnapping({ index, model })` produces a function with terra-draw's `Snapping.toCustom` shape, backed by the SDK `SnapIndex` and the workflow's live snapping config — the same deterministic candidate ordering as `bindEditSketchSnapping`. `createTerraDrawSketch` wires it automatically. The seam is honest: terra-draw exposes per-mode snapping options on its **linestring, polygon, and polyline** modes only. Point, rectangle, circle, and freehand modes have no custom-snapping hook in terra-draw's pointer pipeline, so those modes keep terra-draw-native behavior. If you need snapped point placement, resolve the position with `SnapIndex.resolve()` on click and set the geometry through the workflow directly. ## esri-compat delegation The `Sketch` shim (`@honua/sdk-js/esri-compat`) feature-detects a binding via its `sketchBinding` option: any object with a callable `setTool` (the `bindTerraDrawSketch` / `createTerraDrawSketch` handle qualifies) receives `create` tool-mode changes (`polyline` → `line`), `update()` switches to select mode, and `cancel`/`reset` leave the drawing mode. Without a binding — including when terra-draw is not installed — the shim keeps its existing headless behavior and events. ## Example `examples/sketch-editing` demonstrates draw/edit/delete with undo/redo, snapping, and fixture-lane `applyEdits` (`npm run demo:sketch-editing`, Playwright smoke via `npm run test:playwright:sketch-editing`). --- # File: docs/pmtiles.md # PMTiles [PMTiles](https://github.com/protomaps/PMTiles) is a single-file archive format for an entire pyramid of map tiles (raster or vector). One `.pmtiles` file on static hosting — S3, R2, GCS, or any HTTP server that honours `Range` requests — is a complete basemap or overlay backend. No tile server, no Honua server. MapLibre GL JS renders PMTiles through a registered protocol handler (`maplibregl.addProtocol("pmtiles", …)`). The Honua SDK wires that up for you: the runtime auto-registers the `pmtiles://` protocol on map attach, and the `pmtiles` package is an **optional peer dependency** imported lazily, so a build that never touches PMTiles pays no bundle cost. - `pmtiles` is an optional `peerDependency` (see `package.json`). Install it alongside `maplibre-gl` when you use PMTiles: `npm i pmtiles`. - Reference an archive as a MapLibre source `url` with the `pmtiles://` scheme: `pmtiles://https://example.com/basemap.pmtiles`. ## Rendering a PMTiles source (runtime) `loadMapPackage` auto-registers the `pmtiles://` protocol before it applies the composed style, so a `pmtiles` source binding renders with no manual `addProtocol` call. The registration is lazy (the `pmtiles` and `maplibre-gl` packages are imported only when a PMTiles-backed map loads) and idempotent across every map you attach. ```ts doc-test=compile import { HonuaClient } from "@honua/sdk-js/honua"; import { HONUA_MAP_PACKAGE_FORMAT_V1, loadMapPackage } from "@honua/sdk-js/runtime"; import maplibregl from "maplibre-gl"; const map = new maplibregl.Map({ container: "map", style: { version: 8, sources: {}, layers: [] } }); await new Promise((resolve) => map.on("load", resolve)); await loadMapPackage( { format: HONUA_MAP_PACKAGE_FORMAT_V1, mapPackageId: "pmtiles-basemap", sourceBindings: [ { sourceId: "basemap", protocol: "pmtiles", // `sourceType` picks the MapLibre source kind: "vector" (default) or "raster". locator: { url: "pmtiles://https://example.com/basemap.pmtiles", sourceType: "vector" }, }, ], mapSpec: { version: 8, sources: {}, layers: [ { id: "water", type: "fill", source: "basemap", "source-layer": "water", paint: { "fill-color": "#9cf" } }, ], }, }, map, // No protocol-backed sources → no Honua server needed. `HonuaClient` is // required by the contract but never called here. { client: new HonuaClient({ baseUrl: location.origin }), skipCompatibilityCheck: true }, ); ``` A `pmtiles` source binding projects onto a MapLibre-native source (`{ type: "vector" | "raster", url: "pmtiles://…" }`) via `projectSourceBindings`. The `locator.sourceType` hint selects the MapLibre source kind and defaults to `vector` (the common PMTiles basemap case). ### Registering the protocol yourself If you add a PMTiles source to a live map imperatively (`runtime.addSource`, which is synchronous) or drive MapLibre directly, register the protocol first: ```ts doc-test=skip reason="partial excerpt requires application host context" import { ensurePmtilesProtocol } from "@honua/sdk-js/runtime"; await ensurePmtilesProtocol(); // lazy, idempotent — safe to call repeatedly map.addSource("basemap", { type: "vector", url: "pmtiles://https://example.com/basemap.pmtiles" }); ``` ## Inspecting archive metadata (contract) PMTiles participates in the protocol-neutral `Dataset` / `Source` model as a **tiles-only** protocol. Its default capability set is `{ tiles }`, so the canonical query family throws `HonuaCapabilityNotSupportedError` — an archive has no feature-query surface. Archive metadata is inspected through the typed escape hatch or the standalone helper: ```ts doc-test=skip reason="partial excerpt requires application host context" import { createDataset, describePmtilesArchive } from "@honua/sdk-js/contract"; // Standalone: inspect any archive URL. const info = await describePmtilesArchive("https://example.com/basemap.pmtiles"); console.log(info.tileKind); // "mvt" | "png" | "jpeg" | "webp" | "avif" | "unknown" console.log(info.bounds); // [west, south, east, north] in degrees console.log(info.minZoom, info.maxZoom); console.log(info.vectorLayers.map((layer) => layer.id)); // source-layer names // Through a Dataset: `describe()` on the typed adapter handle. const dataset = createDataset({ id: "basemaps", client, skipCompatibilityCheck: true, sources: [ { id: "basemap", protocol: "pmtiles", locator: { url: "pmtiles://https://example.com/basemap.pmtiles" }, capabilities: new Set(["tiles"]), }, ], }); const archive = dataset.source("basemap")!.protocol("pmtiles"); const meta = await archive!.describe(); ``` `PmtilesArchiveDescription` carries `url`, `tileKind`, `bounds`, `minZoom`, `maxZoom`, `center`, `vectorLayers`, an optional `attribution`, and the raw `metadata` JSON. ## Build-less CDN recipe PMTiles works from a plain HTML page with no bundler — load `maplibre-gl` and `pmtiles` from a CDN and register the protocol: ```html <script src="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.js"></script> <script src="https://unpkg.com/pmtiles@4/dist/pmtiles.js"></script> <link href="https://unpkg.com/maplibre-gl@5/dist/maplibre-gl.css" rel="stylesheet" /> <div id="map" style="position:absolute;inset:0"></div> <script> const protocol = new pmtiles.Protocol(); maplibregl.addProtocol("pmtiles", protocol.tile); new maplibregl.Map({ container: "map", style: { version: 8, sources: { basemap: { type: "raster", url: "pmtiles://https://example.com/basemap.pmtiles" } }, layers: [{ id: "basemap", type: "raster", source: "basemap" }], }, }); </script> ``` ## Notes - **Immutable + HTTP caching.** PMTiles archives are immutable; the reader fetches byte ranges and relies on HTTP caching. There is no realtime path. - **Range requests required.** Static hosts must honour the `Range` header (S3 / R2 / GCS do). The `examples/pmtiles-static` mock server does too. - **Runnable example.** See [`examples/pmtiles-static`](../examples/pmtiles-static) and `npm run demo:pmtiles-static`. --- # File: docs/browser-bundle.md # Prebuilt browser bundle (CDN / build-less) `@honua/sdk-js` ships ESM + TypeScript types as its canonical output, intended for consumption through a bundler (Vite, webpack, esbuild, Rollup) or Node. For static sites, quick prototypes, and CSP-strict pages that cannot run their own bundler, the package also publishes a **prebuilt, self-contained browser bundle** under `dist/browser/`. This is an *additive* artifact — it does not change the ESM/`exports`/types surface. Production apps should keep importing from `@honua/sdk-js` (and its subpaths) through their bundler; the browser bundle exists only for build-less consumers. ## Artifacts | File | Format | Use | | --- | --- | --- | | `dist/browser/honua-sdk.min.js` | minified IIFE (`globalName: HonuaSDK`) | `<script>` tags, unpkg, jsDelivr | | `dist/browser/honua-sdk.esm.js` | minified ESM | `<script type="module">`, esm.sh, native CDN imports | Both ship with `.map` sourcemaps. The bundle targets `es2020`. The `package.json` `browser`, `unpkg`, and `jsdelivr` fields point at the IIFE build, and the `./browser` subpath export points at the ESM build, so ESM CDNs that resolve subpaths (e.g. esm.sh) can serve it directly. ## Usage — global `<script>` (IIFE) ```html <script src="https://cdn.jsdelivr.net/npm/@honua/sdk-js/dist/browser/honua-sdk.min.js"></script> <script> // The reviewed root API of `@honua/sdk-js` is on window.HonuaSDK. const client = new HonuaSDK.HonuaClient({ baseUrl: "https://your-honua-server.example", }); const dataset = HonuaSDK.createDataset({ id: "parcels", client, sources: [{ id: "parcels-fs", protocol: "geoservices", url: "https://.../FeatureServer/0" }], }); </script> ``` unpkg works the same way: ```html <script src="https://unpkg.com/@honua/sdk-js/dist/browser/honua-sdk.min.js"></script> ``` ## Usage — native ES module (ESM) ```html <script type="module"> import { HonuaClient, createDataset } from "https://esm.sh/@honua/sdk-js/browser"; const client = new HonuaClient({ baseUrl: "https://your-honua-server.example" }); </script> ``` ## What's bundled vs. external The bundle is focused on the **core SDK public API** (everything re-exported from `src/index.ts`). The sole real runtime dependency, `@maplibre/maplibre-gl-style-spec`, is bundled in. The heavy runtime *peers* are kept **external** so the artifact stays small and does not inline multi-megabyte map/protobuf runtimes: - `maplibre-gl` - `cesium` - `@bufbuild/protobuf` - `@connectrpc/connect` - `@connectrpc/connect-web` If you use a part of the SDK that needs one of these (e.g. the MapLibre runtime or gRPC transport), load that peer yourself — for the IIFE build, ensure it is available on the page before the code path that needs it runs. ## Building the bundle ```bash npm run build # canonical tsc ESM + types output (dist/src) npm run build:browser # esbuild → dist/browser/*.js (+ .map) ``` `scripts/build-browser-bundle.mjs` bundles straight from `src/index.ts` using the locally installed `esbuild`, so it does not strictly require `npm run build` to have run first — but `npm run build:browser` is the documented entry point. It is intentionally **not** wired into the CI `build` step so an esbuild option mismatch can never break the main release build; run it explicitly (or at publish time) to produce the artifact. The script smoke-checks that the IIFE build defines the `HonuaSDK` global and prints the output sizes. > Note: `dist/` is gitignored. The browser bundle is produced at build/publish > time, not committed to source control. The `files` array in `package.json` > includes `dist/browser` so the artifact is included in the published npm > tarball. --- # File: docs/studio-package-contracts.md # Studio Package Contracts (`@honua/sdk-js/studio`) Status: experimental, implemented for ticket `honua-sdk-js#230`. `@honua/sdk-js/studio` is the single, browser-safe import path for the Studio package families, their unified validation/preview envelopes, the capability manifest, and the publish/share/embed contracts. It exists so Console browser interop, MCP, QGIS, generated apps, and embeds **consume one set of server-owned contract projections instead of forking their own package schemas.** ```ts doc-test=compile import { HONUA_QUERY_PACKAGE_FORMAT_V1, type HonuaStudioPackage, type StudioPackageValidationResponse, tagStudioPackage, toStudioValidationResponse, } from "@honua/sdk-js/studio"; ``` ## MCP / QGIS safety The barrel exports **only types and pure functions** and never imports from `operator`, `esri-compat`, `web-components`, `interactions`, or `realtime` — none of the MapLibre/DOM/Console-coupled modules. MCP servers and QGIS plugins can import `@honua/sdk-js/studio` without pulling renderer code or triggering a build error from Console/Esri internals. This boundary is enforced by a source scan in `test/studio/studio-contracts.test.ts`. The established `map` and `dashboard`/`app` shapes are re-exported here from their leaf modules (`runtime/map-package`, `generated-app/manifest`), so a consumer reaches every family from one path without taking on the MapLibre runtime. ## Package families and format constants Each family is gated by a `format` constant — the canonical version string, exactly as on `MapPackage`. A loader refuses any other value. | Family | Format constant | Format string | Projection type | Stability | | --- | --- | --- | --- | --- | | query | `HONUA_QUERY_PACKAGE_FORMAT_V1` | `honua_query_package.v1` | `HonuaQueryPackage` | experimental (stub) | | analysis | `HONUA_ANALYSIS_PACKAGE_FORMAT_V1` | `honua_analysis_package.v1` | `HonuaAnalysisPackage` | experimental (stub) | | map | `HONUA_MAP_PACKAGE_FORMAT_V1` | `honua_map_package.v1` | `HonuaMapPackage` | stable family, re-exported | | dashboard | `HONUA_GENERATED_APP_MANIFEST_FORMAT_V1` | `honua_generated_app_manifest.v1` | `HonuaGeneratedAppManifest` | re-exported | | report | `HONUA_REPORT_PACKAGE_FORMAT_V1` | `honua_report_package.v1` | `HonuaReportPackage` | experimental (stub) | | form | `HONUA_FORM_PACKAGE_FORMAT_V1` | `honua_form_package.v1` | `HonuaFormPackage` | experimental (stub) | | app | — (uses `HonuaGeneratedAppPackage.version`) | — | `HonuaGeneratedAppPackage` | re-exported | | workflow | `HONUA_WORKFLOW_PACKAGE_FORMAT_V1` | `honua_workflow_package.v1` | `HonuaWorkflowPackage` | experimental (stub) | | gp | `HONUA_GP_PACKAGE_FORMAT_V1` | `honua_gp_package.v1` | `HonuaGPPackage` | experimental (stub) | | etl | `HONUA_ETL_PACKAGE_FORMAT_V1` | `honua_etl_package.v1` | `HonuaETLPackage` | experimental (stub) | The **stub** families (query, analysis, report, form, workflow, gp, etl) have no finalized server contract yet. Their interfaces are minimal and open-ended (every field optional beyond `packageId`/`format`, plus `[extra: string]: unknown`) so additive server changes never break a client. They expand once the matching server contract lands. The `map` and generated-app (`dashboard`/`app`) families are the established, landed shapes. Lifecycle status is shared across families via `HonuaStudioPackageStatus` (`"Draft" | "Composing" | "Ready" | "Failed" | "Expired"`), the same union as `HonuaMapPackageStatus`. ### The `HonuaStudioPackage` discriminated union `HonuaStudioPackage` is a union tagged by a client-side `packageFamily` field. **The server wire shape does not carry `packageFamily`** — projection helpers add it. Build a tagged value with `tagStudioPackage(family, pkg)` rather than casting a raw wire object, then narrow on `packageFamily`: ```ts doc-test=skip reason="partial excerpt requires application host context" const tagged = tagStudioPackage("query", rawQueryPackage); if (tagged.packageFamily === "query") { // tagged is narrowed to { packageFamily: "query" } & HonuaQueryPackage console.log(tagged.querySpec?.where); } ``` `STUDIO_PACKAGE_FAMILIES` enumerates every family discriminant and `isStudioPackageFamily(value)` guards an untrusted string. ## Unified validation response Every family returns the same `{ valid, diagnostics, pkg? }` shape through `StudioPackageValidationResponse<T>`, so SDK, Console, MCP, and QGIS clients consume one contract: ```ts doc-test=skip reason="partial excerpt requires application host context" interface StudioPackageValidationResponse<T> { readonly valid: boolean; readonly diagnostics: readonly StudioPackageDiagnostic[]; readonly pkg?: T; } ``` The existing map-family `ValidateMapPackageResult` is **not renamed** — it is structurally bridged: ```ts doc-test=skip reason="partial excerpt requires application host context" import { validateMapPackage } from "@honua/sdk-js/runtime"; import { fromMapPackageValidation } from "@honua/sdk-js/studio"; const response = fromMapPackageValidation(validateMapPackage(rawMapPackage)); // response: StudioPackageValidationResponse<HonuaMapPackage> ``` For other families, the generic adapter takes the field name holding the package: ```ts doc-test=skip reason="partial excerpt requires application host context" toStudioValidationResponse<HonuaQueryPackage>(rawQueryResult, "queryPackage"); ``` `HonuaMapPackageDiagnostic` is already a structural subtype of `StudioPackageDiagnostic` (it only adds `packageId?`), so map diagnostics flow through unchanged. For convenience, `fromMapPackageValidation` and `toStudioValidationResponse` are also re-exported from `@honua/sdk-js/runtime` (tagged `@experimental`) so existing map-package consumers can bridge from the path they already use. `StudioPackagePreviewResponse<T>` is the parallel envelope for previewing a package (composed without publishing), carrying optional `artifacts` and diagnostics. ## Capability manifest `StudioCapabilityManifest` lets a client gate UI/tool exposure on what the connected server actually supports: ```ts doc-test=skip reason="partial excerpt requires application host context" import { hasCapability, getCapability } from "@honua/sdk-js/studio"; if (hasCapability(manifest, "package.query")) { // advertise the query builder } ``` `hasCapability` is `true` only for an advertised **and enabled** capability; `getCapability` returns the entry regardless of enabled state. > The server capability-manifest endpoint is not yet defined (see Open > questions). These are client projection types ahead of that contract. ## Publish, share, and embed `StudioPublishRequest<T>`, `StudioPublishResponse`, and `StudioEmbedConfig` carry the versioned publication contract for generated artifacts. `HonuaShareRequest` / `HonuaShareResponse` are **re-exported from `control-plane/types`** (single source of truth — not re-declared) so Console and MCP reach the share contract from the one `@honua/sdk-js/studio` path without taking on the full control-plane client. `StudioEmbedConfig.token` / `embedUrl` describe an **already-issued** embed descriptor; the type does not imply a token-minting call inside the SDK. ## Generated apps Generated apps consume published `map`, `dashboard`, `report`, and `app` package projections from `@honua/sdk-js/studio` without importing Console or MapLibre code — the `dashboard` family is `HonuaGeneratedAppManifest` and the `app` family is `HonuaGeneratedAppPackage`, both re-exported here. For the preview runtime that hydrates these manifests, see [`docs/generated-app-runtime.md`](./generated-app-runtime.md). ## Versioning Every new export is tagged `@experimental` in JSDoc and is subpath-only (not re-exported from the root barrels), so it is outside the SDK semver contract until the matching server contracts land. The format constants follow the `HONUA_X_PACKAGE_FORMAT_V1 = "honua_x_package.v1"` pattern. ## Cross-surface parity (MCP / QGIS) The parity layer that makes packages portable across Console, MCP, and QGIS — a shared `provenance` envelope, a family-agnostic `validateStudioPackage` helper, a documented Vega-Lite chart subset, and cross-surface fixtures — is documented in [`studio-package-parity.md`](./studio-package-parity.md) (`honua-sdk-js#226`). ## Open questions (pending server contracts) These are tracked for follow-up once the server shapes are finalized: - Whether `dashboard` is exactly `HonuaGeneratedAppManifest` or a distinct server `DashboardPackage` wrapper. - The fetch path for `StudioCapabilityManifest` (dedicated endpoint vs. embedded in another response). - Full ETL/workflow/GP package shapes (currently stub-only). - Whether embed-token issuance is in scope for the SDK client. - Whether the MCP server (`/mcp`) should import package/validation types from `@honua/sdk-js/studio` in a follow-on. --- # File: docs/migration-honua-maplibre.md # `honua-maplibre` migration target The `honua-maplibre` codemod target rewrites a curated subset of `@arcgis/core` constructors directly into `@honua/sdk-js/map` helpers plus MapLibre GL source/layer definitions, instead of routing them through the Esri-shaped compat shims. It is the codemod option that produces MapLibre-native output for apps that want to leave the ArcGIS JS API behind end-to-end. This page documents the slice that shipped in PR #208 (commit `af1ebee`). It does not close issue #205 — open acceptance items are called out under [Manual gaps](#manual-gaps). ## How it differs from the other targets The migration codemod (`src/migration/codemod.ts`) exposes three targets selected with `--target` on the CLI: | Target | Output shape | What it rewrites natively | | --- | --- | --- | | `honua-compat` (alias `honua`) | `@honua/sdk-esri-compat` shims that mimic the ArcGIS JS API surface | Every kind in `REWRITE_SPECS` (`SUPPORTED_ARCGIS_MODULE_KIND_BY_PATH`) — full 2D constructor surface (layers, views, widgets, controls, tasks, support). | | `honua-maplibre` | `@honua/sdk-js/map` helpers + raw MapLibre style/layer objects | The five kinds in `HONUA_MAPLIBRE_NATIVE_KINDS`: `feature-layer`, `map-image-layer`, `tile-layer`, `map`, `map-view`. Everything else still falls through to a manual TODO. | | `esri-leaflet` | Mixed esri-leaflet primitives + compat fallback | `feature-layer`, `map-image-layer`, `tile-layer` natively; the remaining 2D surface via `ESRI_LEAFLET_COMPAT_FALLBACK_KINDS`. | `honua-compat` is the broadest deterministic option — it covers the full `REWRITE_SPECS` matrix and is the default. `honua-maplibre` trades surface coverage for a MapLibre-native output: it only emits native helpers for the layer/map/view core, and everything else (widgets, controls, renderers, geometry constructors, tasks) becomes a manual TODO because there is no `@honua/sdk-js/map` helper for it yet. `esri-leaflet` sits in between — three native layer kinds with a compat fallback for the rest. ## Auto-migrated, assisted, and unsupported kinds The exact set of kinds the `honua-maplibre` target rewrites natively is defined in `src/migration/codemod.ts` as `HONUA_MAPLIBRE_NATIVE_KINDS` and consumed by `TARGET_SUPPORTED_KINDS["honua-maplibre"]`: - `feature-layer` (`@arcgis/core/layers/FeatureLayer`) → `createHonuaFeatureServiceLayer({ url, ... })` returning a `HonuaFeatureServiceSourceSpecification` plus a default MapLibre render layer (`circle`/`line`/`fill` chosen via `layerType`). - `map-image-layer` (`@arcgis/core/layers/MapImageLayer`) → `createHonuaMapServiceLayer({ url, ... })` returning a `HonuaMapServiceSourceSpecification` plus a default raster render layer. - `tile-layer` (`@arcgis/core/layers/TileLayer`) → `createHonuaTileServiceLayer({ url, ... })` returning a MapLibre raster source pointing at `<url>/tile/{z}/{y}/{x}` plus a raster render layer. - `map` (`@arcgis/core/Map`) → `createHonuaMapLibreStyle({ basemap, layers, ... })` returning a `HonuaStyleSpecification` (MapLibre style version 8) that aggregates the migrated layers' sources and layers. - `map-view` (`@arcgis/core/views/MapView`) → `createHonuaMapLibreMapOptions({ container, style, center, zoom, bearing, pitch })`, the options bag passed to `new maplibregl.Map(...)`. The helper signatures live in `src/map/maplibre-target.ts`. ### Rendering feature-service layers (custom source → `geojson`) `createHonuaTileServiceLayer` and `createHonuaMapServiceLayer` emit MapLibre-native `raster` sources that render as soon as you add them to a map. `createHonuaFeatureServiceLayer` is different: its `source` uses the custom `honua-feature-service` type, which MapLibre's renderer does not understand. Adding that source to a `maplibre-gl` `Map` directly is a silent no-op — no error, no features. To render feature-service layers, run them through the MapLibre runtime adapter exported from `@honua/sdk-js/map`. It fetches features via the SDK query path and produces a standard `geojson` source MapLibre renders natively: ```ts doc-test=skip reason="partial excerpt requires application host context" import maplibregl from "maplibre-gl"; import { HonuaClient } from "@honua/sdk-js"; import { createHonuaFeatureServiceLayer, loadHonuaFeatureServiceGeoJson, } from "@honua/sdk-js/map"; const client = new HonuaClient({ baseUrl: "https://gis.example.com" }); const layer = createHonuaFeatureServiceLayer({ url, outFields: ["*"] }); // Replace the custom honua-feature-service source with a fetched geojson source. const source = await loadHonuaFeatureServiceGeoJson(client, layer.source.url); map.addSource(layer.sourceId, source); map.addLayer(layer.layer); ``` For a whole `HonuaMap`, `registerHonuaFeatureServiceSources(map, honuaMap, client)` walks every `honua-feature-service` source and live-patches it on the MapLibre map (adding a new `geojson` source or calling `setData` on an existing one). Both helpers live in `src/map/feature-service-adapter.ts`. Every other constructor kind in `REWRITE_SPECS` — geometries, symbols, renderers, `WebMap`, `SceneView`, `GraphicsLayer`, `GroupLayer`, `VectorTileLayer`, `GeoJSONLayer`, `WMSLayer`, `WFSLayer`, `ImageryLayer`, `FeatureFilter`, all widgets (`LayerList`, `Legend`, `Popup`, `Search`, `Sketch`, `Editor`, `TimeSlider`, …), all controls (`Home`, `Zoom`, `Compass`, `ScaleBar`, `Fullscreen`, `BasemapToggle`, …), `Query`, `OAuthInfo`, `IdentityManager`, `esriRequest`, `esriConfig`, `reactiveUtils`, `RouteTask`, etc. — is **not** in `HONUA_MAPLIBRE_NATIVE_KINDS`. The codemod emits a manual TODO with a reason at each call site and lists the unhandled ArcGIS module under `unhandledArcGisModules` in the report. The runtime parity matrix (`src/migration/runtime-matrix.ts::inferHonuaMapLibreRuntimeStatus`) categorizes these surfaces as `assisted` for `honua-maplibre`, except for the `feature-layer`, `map-image-layer`, and the `map-view.navigation-go-to` capability which are tagged `native`. Use the canonical fixture [`test/fixtures/esri-maplibre-simple-app/`](../test/fixtures/esri-maplibre-simple-app/src/main.ts) as a worked example — it imports `Map`, `MapView`, `FeatureLayer`, `MapImageLayer`, and `TileLayer` from `@arcgis/core` and exercises exactly the kinds that `honua-maplibre` can rewrite natively. ## CLI flag and invocations The codemod is selected with `--target honua-maplibre` on the `codemod`, `fixtures`, and `demo` subcommands of `node dist/src/migration/cli.js`. The accepted target tokens are `honua` (alias of `honua-compat`), `honua-compat`, `honua-maplibre`, and `esri-leaflet` — anything else is rejected by the parser. ```bash # Dry-run the codemod against the bundled MapLibre fixture node dist/src/migration/cli.js codemod test/fixtures/esri-maplibre-simple-app \ --target honua-maplibre \ --report reports/maplibre-fixture-report.json # Write the rewrite in place with inline TODOs for manual sites node dist/src/migration/cli.js codemod test/fixtures/esri-maplibre-simple-app \ --target honua-maplibre \ --write --annotate-todos \ --report reports/maplibre-fixture-report.json # Run the codemod against the hand-written parcel viewer example node dist/src/migration/cli.js codemod examples/arcgis-source-app \ --target honua-maplibre \ --report reports/arcgis-source-app-maplibre-report.json # Per-fixture readiness metrics for a single MapLibre fixture, no gating node dist/src/migration/cli.js fixtures test/fixtures \ --target honua-maplibre \ --fixtures esri-maplibre-simple-app \ --report reports/maplibre-fixture-metrics.json ``` The shared codemod flags (`--write`, `--annotate-todos`, `--report <path>`, `--compat-import-path <pkg>`, `--fail-on-manual`, `--fail-on-unhandled`, `--fail-on-blocked`, `--max-manual-ratio`, `--max-manual-intervention-ratio`) all apply unchanged. With `--target honua-maplibre` the codemod only rewrites the five native kinds; manual TODOs and unhandled-module entries are expected to appear for any constructor outside that set, and gating flags like `--fail-on-manual` will fail closed against apps with widgets, renderers, or non-2D-core surfaces. For contributor validation, use `npm run test:migration:cli`. Its prerequisite prepares the SDK once before Vitest starts, and every CLI spec executes the same manifest-owned `dist/src/migration/cli.js` artifact. The atomic preparation manifest hashes every compiler/control input and the complete `dist/` tree, binds workers to one run ID, and revalidates both trees at teardown. A direct Vitest invocation may run source-only tests without a manifest; a test that consumes built output fails with an actionable `npm run prepare:test-sdk` prerequisite error. Composed CI and publish lanes use their `:prepared` variants after the single root build. ## Migration report fields The report writer is `buildJsMigrationReport` (`src/migration/report.ts`); its `JsMigrationReport` shape is what gets written to the path passed to `--report`. The fields you can key off when consuming a `honua-maplibre` report are: - `codemodTarget`: `"honua-maplibre"` for runs launched with `--target honua-maplibre`. The union is `"honua-compat" | "esri-leaflet" | "honua-maplibre"`. - `rootDir`: absolute path of the codemod root that was scanned. - `scanSummary` / `scanReport`: the `scanArcGisUsage`/`summarizeArcGisScan` output (import counts, flags like `scene-3d-detected`, `advanced-widget-or-networking-detected`). - `codemodResult.metrics.totalCodemodScopedCallSites`, `codemodResult.metrics.autoMigratedCallSites`, `codemodResult.metrics.manualCallSites`, `codemodResult.metrics.byKind[<kind>]` (per-kind `auto/manual/total` counts). - `manualRewriteMetric`: `{ numerator, denominator, ratio, scope }` where `numerator/denominator` = manual call sites / total codemod-scoped call sites. `ratio` is the value compared against `--max-manual-ratio`. - `manualInterventionMetric`: `{ numerator, denominator, ratio, scope, manualCodemodCallSites, unhandledUsageHits }` — extends the rewrite metric by adding `unhandledArcGisModules` hits into both numerator and denominator. Compared against `--max-manual-intervention-ratio`. - `readiness`: `"ready" | "assisted" | "blocked"` — derived from `gates`. Blocking flags (`scene-3d-detected`, `advanced-widget-or-networking-detected`) force `blocked`. - `gates`: array of `{ gate: "no-manual-todos" | "no-unhandled-modules" | "no-blocking-flags", passed, detail }`. These are the MapLibre readiness gates: with `honua-maplibre`, expect `no-manual-todos` and `no-unhandled-modules` to fail on any app that uses widgets, renderers, geometry constructors, or other kinds outside `HONUA_MAPLIBRE_NATIVE_KINDS`. - `manualTodos`: per-call-site `{ file, line, column, kind, reason, difficulty? }`. - `manualTodoReasons`: rolled-up reasons sorted by count, each with a `kinds` list — useful for grouping cleanup work by category. - `manualTodosByKind`: dense map of every `CodemodConstructorKind` to its manual-call-site count for this run. - `unhandledArcGisModules`: `{ modulePath, usageStyle, count }` entries for ArcGIS modules outside the codemod's per-target supported set. `usageStyle` is `"static-import"`, `"dynamic-import"`, or `"require"`. The parity matrix tooling (`matrix` / `runtime-matrix` subcommands) also emits a `honuaMapLibre` summary block alongside `honuaCompat` and `esriLeaflet` with `native`/`assisted`/`unsupported` counts — see `summarizeJsParityMatrix` and `summarizeJsRuntimeParity`. ## Manual gaps Issue #205 is a slice ladder, not a single landing. `honua-maplibre` ships the native-rewrite path for the layer/map/view core; the remaining acceptance items live in [`docs/migration-punch-list.md`](./migration-punch-list.md) and stay open until they ship. The notable ones, framed against the punch list: - **WebMap → MapLibre style conversion.** The `web-map` kind is not in `HONUA_MAPLIBRE_NATIVE_KINDS`, so `new WebMap(...)` constructors emit a manual TODO under this target. Server-side / CLI WebMap conversion lives behind the `content-webmap` subcommand and is tracked separately. - **Widget visual parity.** Per the punch list "Widget UI behavior" entry: the compat shims accept ArcGIS option shapes but render through the Honua widget host with non-byte-identical visuals. `honua-maplibre` does not paper over this — widget constructors fall to manual TODO instead of being silently rewritten. - **3D / SceneView and scene layers.** `scene-view`, `SceneLayer`/`BuildingSceneLayer`/`IntegratedMeshLayer`/ `PointCloudLayer`/`MeshLayer`/`ElevationLayer`/`VoxelLayer` are flagged with the `scene-3d-detected` blocking flag and force `readiness: "blocked"`. MapLibre is 2D-only by design; 3D parity is not in this target's scope. - **`Locator` / `Geoprocessor` / `NetworkAnalyst` (beyond `RouteTask`).** Not in `HONUA_MAPLIBRE_NATIVE_KINDS`; manual TODO with the unhandled-module list pointing at the missing surfaces. - **Renderers, symbols, popup templates, `reactiveUtils.watch`, event-name remap, `Query` deep-transform.** These ship for `honua-compat` (some shipped as Tasks D/E/F in the punch list) but they do not exist as native MapLibre helpers — under `honua-maplibre` they remain manual TODO surfaces. - **Playwright smoke / runtime evidence lane for MapLibre output.** Open acceptance item on #205. For the broader migration story — including the `honua-compat` parity surface, the codemod gates, and the test corpus — start at [`docs/migration-punch-list.md`](./migration-punch-list.md) and the fixture-only Esri sample corpus in [`docs/esri-sample-corpus.md`](./esri-sample-corpus.md). --- # File: docs/migration-punch-list.md # ArcGIS JS SDK → Honua JS SDK migration punch list This is an honest accounting of where the Honua JS SDK's two public-facing claims stand: 1. **"Parity with the ArcGIS JS SDK"** — the symbol surface app authors can `import` and call against. 2. **"Automated app conversion"** — the `src/migration` codemod that rewrites ArcGIS imports/constructors to Honua compat shims. It is intentionally written so a reader can tell what is shipped, what is *partial*, and what is *not started*. None of the entries below are aspirational — they are concrete work items. --- ## What is true today ### Parity surface (`src/esri-compat/`) The compat module ships shims for the constructors enumerated in `src/migration/codemod.ts::SUPPORTED_ARCGIS_MODULE_KIND_BY_PATH`. Every kind in that map has a row in `parity-matrix.ts`, and every row is asserted by `test/migration-parity-matrix.test.ts`. The shims back onto real Honua surfaces in `src/core/` (HonuaClient, HonuaFeatureService, HonuaImageService, HonuaMapService, …) rather than being throwaway no-ops. Specifically: - 2D `FeatureLayer`, `GraphicsLayer`, `GroupLayer`, `MapImageLayer`, `TileLayer`, `RouteLayer`, `Basemap`, `VectorTileLayer`, `GeoJSONLayer`, `WMSLayer`, `WFSLayer`, `ImageryLayer` - `Graphic`, `Point`, `Polyline`, `Polygon`, `Extent`, `SpatialReference`, `Color`, `FeatureSet` - Symbols: `SimpleLineSymbol`, `SimpleMarkerSymbol`, `PictureMarkerSymbol`, `TextSymbol`, `LabelClass`, `SimpleFillSymbol` - Renderers: `SimpleRenderer`, `UniqueValueRenderer`, `ClassBreaksRenderer` - Views: `Map`, `MapView`, `SceneView` (2D-only behavior), `WebMap` - Widgets (deterministic 2D-only set): `Home`, `BasemapToggle`, `BasemapGallery`, `BasemapLayerList`, `LayerList`, `Legend`, `Popup`, `Search`, `Track`, `Swipe`, `Feature`, `FeatureForm`, `FeatureTemplates`, `FeatureTable`, `DistanceMeasurement2D`, `AreaMeasurement2D`, `Compass`, `Fullscreen`, `Zoom`, `Attribution`, `ScaleBar`, `Locate`, `Bookmarks`, `Print`, `Sketch`, `Editor`, `Expand`, `TimeSlider`, `Directions`, `CoordinateConversion`, `Measurement` - Tasks & support: `RouteTask`, `Query`, `OAuthInfo`, `IdentityManager`, `esriRequest`, `esriConfig`, `reactiveUtils`, `FeatureFilter` The `MapViewLayerViewCompat` returned from `view.whenLayerView()` now carries `filter` / `effect` / `visible` state and forwards filter predicates through `queryFeatures` / `queryFeatureCount` / `queryObjectIds`, merging `where`, `objectIds`, `geometry`, `spatialRelationship`, and `timeExtent` with any per-call options (layer-view filter ∧ caller-provided options). `Sketch` and `Editor` now accept ArcGIS-shaped `snappingOptions` (`enabled`, `distance`, `featureEnabled`, `selfEnabled`, `featureSources`) and map them onto the renderer-neutral `SnappingConfig` from `@honua/sdk-js/contract` (`snappingOptionsToSnappingConfig`). The contract snapping engine (`SnapIndex` + `resolveSnapCandidate`) resolves vertex / edge / feature candidates deterministically over a packed-grid spatial index, invalidates on optimistic edit apply/rollback (`createSnapIndexEditSessionHooks`), and the MapLibre runtime binding (`bindEditSketchSnapping` in `@honua/sdk-js/runtime`) wires pointer-move, snap/unsnap events, and a default indicator layer. `selfEnabled` is stored for parity but self-snapping needs the host to index the active sketch source; 3D snapping is out of scope with the rest of the SceneView surface. ### Automated app conversion (`src/migration/codemod.ts`) The codemod is a real AST rewriter built on the TypeScript Compiler API (it does **not** use regex). It: - Detects `import { X } from "@arcgis/core/..."` and rewrites bindings to the matching `XCompat` symbol from `esri-compat`. - Detects `new X(opts)` for every kind above and rewrites to the compat constructor when the option literal is "safe" — i.e., a top-level object literal whose properties are all in the per-kind allowlist (`FEATURE_LAYER_ALLOWED_PROPS`, `MAP_VIEW_ALLOWED_PROPS`, …). The new layer kinds added in this pass — `feature-filter`, `vector-tile-layer`, `geojson-layer`, `wms-layer`, `wfs-layer`, `imagery-layer` — go through the same `isSafeAllowedPropertiesCall` switch and gain TODO annotations on unsafe call sites. - Emits `manualTodos` and `manualTodoReasons` on a `byKind` matrix for every untouched call site, so app authors can drive cleanup against a checklist. - Emits a parity report (`src/migration/report.ts`) with three gates (`no-manual-todos`, `no-unhandled-modules`, `no-blocking-flags`) and a readiness verdict. - Knows the `esri-leaflet` migration target as a separate column, with `ESRI_LEAFLET_COMPAT_FALLBACK_KINDS` gating which kinds are treated as deterministic vs. assisted. - Knows the `honua-maplibre` migration target as a third column, gated by `HONUA_MAPLIBRE_NATIVE_KINDS` (`feature-layer`, `map-image-layer`, `tile-layer`, `map`, `map-view`). The native rewrite emits `@honua/sdk-js/map` helpers plus MapLibre style/layer objects instead of compat shims; everything outside that set falls through to a manual TODO. See [`docs/migration-honua-maplibre.md`](./migration-honua-maplibre.md) for the per-target rewrite surface, CLI invocations, report fields, and the manual-gap list against issue #205. Everything in this section is covered by tests under `test/` (`migration-codemod.test.ts` is 75 cases; `migration-report.test.ts`, `migration-gating.test.ts`, and `migration-parity-matrix.test.ts` hold the surface stable). --- ## What the claim does **not** yet cover ### Parity gaps 1. **3D / SceneView.** `SceneView` exists as a compat class but it shares the 2D `MapView` behavior under the hood. Anything that requires a WebGL/CesiumJS path (`environment`, `viewingMode: "global"`, `goTo` with altitude, `Ground`, `ElevationLayer`, scene layers, `Camera`, `qualityProfile`) is not implemented. The codemod sets the `scene-3d-detected` blocking flag when it sees such imports, so the gate fails closed. 2. **Scene layers.** `SceneLayer`, `BuildingSceneLayer`, `IntegratedMeshLayer`, `PointCloudLayer`, `MeshLayer`, `ElevationLayer`, `VoxelLayer` have no shims. These all need server-side glTF/I3S support (`honua-server` ticket). 3. **`Locator` / `Geoprocessor` / `NetworkAnalyst` (beyond RouteTask).** Today only `RouteTask` is shimmed against `HonuaRouteService`. The remaining task surfaces (geocoding, service-area, OD-cost-matrix, closest-facility, non-network geoprocessing) need their own surfaces under `src/core/` and matching compat classes. 4. **`Query` argument depth.** *Shipped (Task E).* The codemod now deep-transforms `new Query({...})` argument literals into the Honua `QueryFeaturesRequest` shape: renames `start` → `resultOffset`, `num` → `resultRecordCount`, `outSpatialReference` → `outSr`, `spatialRelationship` → `spatialRel`; splits `geometry: { type, ...rest }` into a sibling `geometryType` field with the matching `esriGeometry*` enum value; and lowercases `outStatistics[i].statisticType` against the STATISTIC_TYPE_MAP keyset (count/sum/min/max/avg/stddev/var). Divergent / dynamic shapes emit a manual TODO with a precise reason — specifically: `timeExtent` (no Honua field; use `extraParams.time`), `quantizationParameters` (server-side optimization with no Honua equivalent), `relationParam` (no Honua support), `geometry` without a string-literal `type` discriminator, and `outStatistics` items with a non-literal `statisticType` or an unknown enum value. The shim `QueryCompat` accepts either ArcGIS or Honua property spellings (`spatialRelationship` / `spatialRel`, `outSpatialReference` / `outSr`, `num` / `resultRecordCount`, `start` / `resultOffset`) so codemod output and hand-written callers both validate. 5. **Popup actions / popup templates with `actions`, `outFields: ["*"]` expansions, and `fieldInfos` formatters.** These rewrite cleanly only for the simple case; arrow-function field-info `format` callbacks fall through to manual TODO. 6. **Widget UI behavior.** The widget shims accept the same constructor options ArcGIS does, but they render through the Honua widget host (`HonuaWidgetHost`). Visual parity (icons, ARIA, CSS class names that downstream apps style against) is **not** byte-identical. Apps that rely on `calcite-action--`-prefixed selectors will need style work. 7. **`reactiveUtils.watch` semantics (partial).** Compat `watch` is property-name-based and synchronous. ArcGIS `watch` accepts an accessor function and returns a `WatchHandle` with `pause()` / `resume()`. Single-property accessors — `reactiveUtils.watch(() => view.scale, h)` where `view` is a tracked compat instance — are now rewritten by the codemod to `reactiveUtils.watch(view, "scale", h)`. Multi-property accessors (`() => [view.scale, view.zoom]`) and complex bodies still fall through to a manual TODO. `pause()` / `resume()` on the handle is still unsupported. ### Codemod gaps These are the load-bearing pieces required to turn "rewrites known constructors" into "automated app conversion": 1. **Event-name remap (Task D, partial).** The codemod now rewrites well-known divergent event names on `.on()` and `.watch()` calls in files that have at least one ArcGIS import being touched. The dictionary is in `ARCGIS_TO_COMPAT_EVENT_REMAP` in `src/migration/codemod.ts` and currently covers `layerview-create*`, `layerview-destroy`, `visibility-change`, `extent-change`, `rotation-change`, `scale-change`, `zoom-change`, `center-change`, `spatial-reference-change`, `padding-change`, `constraints-change`, `highlight-options-change`, `basemap-change`, `ground-change`, `portal-item-change`, `active-basemap-change`, `camera-change`, `quality-profile-change`, `viewing-mode-change`, and `refresh`. Receiver-aware scoping is now in place: the rewrite only fires when the receiver is an Identifier whose binding came from `new XCompat(...)` where `X` was a tracked ArcGIS import (via `resolveAssignedIdentifierForNewExpression`). Receivers that don't trace back to a tracked compat instance (e.g., `someEmitter.on("layerview-create", h)`) are left alone even when the file has ArcGIS imports. What is still missing: pointer/keyboard event handlers (`click`, `pointer-down`, `key-down`, …) which compat doesn't emit yet. 2. **Dynamic / CJS imports (Task F, partial).** Dynamic ESM imports (`import("@arcgis/core/...")`) are rewritten through the `isArcGisDynamicImportCall` pass and have test coverage for SceneView, esriConfig, esriRequest, and IdentityManager. CommonJS `require("@arcgis/core/...")` is now auto-rewritten for the `honua-compat` target when constructor options are safe: the codemod emits `const { XCompat } = require("@honua/sdk-esri-compat");` and rewrites `new X(opts)` to `new XCompat(opts)` in `.cjs` files and `.js` files containing CommonJS markers. The original `const X = require("@arcgis/core/...")` declaration is now pruned when no other references to `X` remain in the file (constructor calls are the only references in the typical case; the codemod scans for non-constructor uses and preserves the require if it sees any). The `esri-leaflet` target still emits a manual TODO for CJS require constructors. 3. **Module re-exports beyond the registered set.** The codemod already follows `localArcGisReExports` for one level. Deeper barrel-file chains (`./esri.ts` → `./layers/index.ts` → …) aren't followed. 4. **`view.map.add(layer)` argument-shape transformations.** When a `new FeatureLayer({ ... })` is rewritten, its option literal is passed through verbatim. We do **not** translate ArcGIS-shaped properties whose Honua-side names differ (e.g., `renderer.field` casing, `popupTemplate.content` block shapes). The shim accepts the ArcGIS shape at runtime, but the report should flag known-divergent property values so app authors can confirm intent. 5. **WebMap JSON → MapLibre style derivation (`honua-maplibre` target).** *Partially shipped.* `src/map/webmap-maplibre.ts` exposes `webmapJsonToMapLibreStyle(webmap, options)`, a pure converter that delegates the heavy lifting to the existing `src/webmap/` pipeline — `parseWebMap` orchestrates `convertBasemap`, `convertOperationalLayer`, `convertRenderer`, `convertPopupInfo`, `convertLabelingInfo`, and `convertExtent`/`convertInitialViewpoint` — and returns a `HonuaStyleSpecification` ready for `map.setStyle(...)` plus a structured `manualGaps: WebMapMapLibreManualGap[]` array. `manualGaps` is the single source of truth for unsupported constructs: every entry carries `{ kind, reason, path?, layerId?, expression?, context? }` and the `kind` taxonomy covers `arcade-expression` (popup `expressionInfos` and complex Arcade label expressions), `unsupported-renderer` (heatmap, dotDensity, and any other renderer the converter doesn't handle), `scene-3d` (top-level `ground` / `camera` / `viewingMode`, `ArcGISSceneServiceLayer`, `elevationInfo`, `heightInfo`, `sceneProperties`), `dashboard-reference`, `experience-builder-reference`, `custom-widget-reference` (`applicationProperties.viewing.widgetsOnScreen` and the top-level `widgets` array used by host shells), plus pass-throughs for `unsupported-symbol`, `unsupported-layer-type`, `unsupported-feature-collection`, and `unsupported-webmap-version`. The migration codemod now wires this converter into its `honua-maplibre` constructor-rewriting pass: any `new WebMap({ ... })` call whose argument is a static WebMap JSON object literal (top-level `operationalLayers` and/or `baseMap`, fully literal values, no `portalItem`) is rewritten to `webmapJsonToMapLibreStyle({ ... })` from `@honua/sdk-js/map`, and the helper's `manualGaps` array is propagated into the migration report as per-gap `web-map` manual TODOs (Arcade, unsupported renderer, scene/3D, dashboard shell, …). **What still requires manual review:** dynamic / portal-loaded WebMaps (`new WebMap({ portalItem: { id: someId } })`, `WebMap.load()`, identifier references, computed properties, spreads) still emit a `web-map` manual TODO with no rewrite — they need a runtime fetch the codemod cannot synthesize. The gap surface is also intentionally honest about its ceiling, since Arcade execution, scene/3D rendering, Dashboard widget hosts, Experience Builder pages, and custom-widget plugins all require runtime support the JS SDK cannot synthesize from JSON alone. Each emitted gap is a `// TODO` anchor for an app author, not a promise of automated migration. 6. **End-to-end demo conversion.** Shipped at `examples/arcgis-source-app/` + `test/migration-e2e.test.ts`. The sample is a hand-written parcel viewer exercising `FeatureLayer` (with `outFields` + `popupTemplate`), `Map`, `MapView`, an untouched `view.on("click", …)` handler, and an event-name-remapped `layer.on("layerview-create", …)` handler. The e2e test copies it into a tempdir, runs the codemod with `target: "honua-compat"`, asserts every expected rewrite landed and the readiness gate is `"ready"`, and then runs `tsc --noEmit` against the migrated source with `paths` resolving `@honua/sdk-esri-compat` to the workspace `src/esri-compat/` entry. The CI job runs this harness immediately after the unit test step. Remaining work: extend the sample to additional layer kinds (Imagery / VectorTile / WMS / WFS / GeoJSON) so the harness exercises the full surface, not just the parcel viewer slice. --- ## What's required to make the claim defensibly true In rough effort order: | Bucket | Effort | Notes | | --- | --- | --- | | Codemod event-name remap (Task D) | 1–2 days | Pure JS-side work; needs an event-name dictionary plus AST pass. | | Codemod dynamic-import + CJS (Task F) | 1–2 days | Mirror the static-ESM path; care needed for awaited dynamic imports' destructuring. | | ~~Query argument deep-transform (Task E)~~ | ~~3–5 days~~ | Shipped: codemod renames `start`/`num`/`outSpatialReference`/`spatialRelationship`, splits `geometry` into `geometry`+`geometryType`, normalizes `outStatistics[i].statisticType` against `STATISTIC_TYPE_MAP`, and emits precise manual TODOs for `timeExtent`, `quantizationParameters`, `relationParam`, dynamic statisticType, and geometry without a literal `type`. `QueryCompat` accepts both ArcGIS and Honua property spellings. | | Locator + Geoprocessor compat (Task C) | 1–2 weeks | Requires `HonuaGeocodeService`, `HonuaGeoprocessService` surfaces (server work). | | Scene-layer compat (Task A-rest) | 4–8 weeks | Requires I3S/glTF pipeline on `honua-server`; not pure-JS work. | | ~~E2E demo conversion harness (Task I)~~ | ~~1 week~~ | Shipped: `examples/arcgis-source-app/` + `test/migration-e2e.test.ts`, wired into the JS SDK CI workflow after the unit-test step. | With the first three rows (Tasks D/F/E) now shipped, "automated app conversion" reaches deterministic constructor rewrite + event-name remap + dynamic/CJS imports + Query argument deep-transform, plus a manual-TODO report for everything else. The remaining rows (Locator/Geoprocessor and Scene-layer compat) still gate the unqualified "parity with ArcGIS JS SDK" claim — that should remain qualified as "deterministic 2D parity; scene/3D and advanced tasks remain assisted migration" until they land. --- # File: docs/esri-sample-corpus.md # Esri Sample Migration Corpus This corpus is the first bounded slice for paired Esri sample app and referenced service migration evidence. It is intentionally fixture-first. ## PR CI Guardrails - PR CI must not contact live Esri services. - PR CI must not vendor Esri sample source code. - PR CI must not commit Esri-hosted service data, basemaps, screenshots, or Portal exports. - Sample source URLs are metadata references only. - Samples that require API keys, OAuth, private content, premium services, or unclear content terms stay skipped unless credentials, permission, and terms review are explicitly configured. The committed manifest lives at `test/fixtures/esri-sample-corpus/manifest.json`. Its fixtures are tiny Honua-owned snippets that mimic common ArcGIS Maps SDK for JavaScript patterns: service URL references, Portal item references, API-key routing references, and OAuth/private Portal references. ## Manifest Shape The manifest uses `schemaVersion: "honua.esri-sample-corpus.v1"` and records: - global guardrails for no vendored Esri code, no committed Esri service data, fixture-only PR CI, and opt-in live evidence lanes - one entry per curated sample with `id`, `title`, source URL metadata, fixture location, status, license metadata, terms notes, skip reasons, and expected references - status values: `ci-fixture`, `live-evidence`, and `skipped` - skip reasons: `requires-api-key`, `requires-oauth`, `premium-service`, `private-content`, `unclear-content-terms`, and `unsupported-sample-family` The migration entrypoint exports helpers to load and inspect the corpus: ```ts doc-test=compile import { analyzeEsriSampleFixture, loadEsriSampleCorpusManifest, summarizeEsriSampleCorpus, } from "@honua/sdk-js/migration"; const manifest = loadEsriSampleCorpusManifest("test/fixtures/esri-sample-corpus/manifest.json"); const summary = summarizeEsriSampleCorpus(manifest); const analysis = analyzeEsriSampleFixture(manifest.samples[0], { manifestDir: "test/fixtures/esri-sample-corpus", }); void summary; void analysis; ``` ## Per-sample evidence For each curated sample, the migration entrypoint can run the existing codemod against the local fixture and emit a structured evidence record: ```ts doc-test=compile import { emitEsriSampleCorpusEvidence } from "@honua/sdk-js/migration"; const evidence = emitEsriSampleCorpusEvidence({ manifestPath: "test/fixtures/esri-sample-corpus/manifest.json", // Defaults to "honua-maplibre". Other codemod targets are also accepted. }); for (const sample of evidence.samples) { // sample.status === "migrated" | "skipped" | "error" // sample.classification.auto / manual / unsupported // sample.manualTodos.reasons (deduped by reason, includes affected kinds) // sample.referencedServices / sample.portalItems / sample.guardrailFlags // sample.urlRewriteSummary.byKind / sample.unsupportedApis } // Aggregate across the corpus — per-status counts always sum to the manifest // length, and unsupported APIs are deduplicated. const { statusCounts, totals, uniqueUnsupportedApis } = evidence.aggregate; void statusCounts; void totals; void uniqueUnsupportedApis; ``` Samples whose manifest entry is `status: "skipped"` (private-portal, routing API-key, premium-service, etc.) appear in the evidence record with `status: "skipped"` and the manifest skip reason — they always count toward the aggregate, but never as `migrated`. No live Esri services are contacted; the helper operates entirely on the committed fixture corpus. The same evidence can be persisted to disk via the migration CLI subcommand `corpus-evidence`. It writes one JSON artifact per sample to `<out>/samples/<sampleId>.json` and a single aggregate document to `<out>/corpus-evidence.json`. `--corpus` defaults to `test/fixtures/esri-sample-corpus`, and `--target` defaults to `honua-maplibre`: ```bash node dist/src/migration/cli.js corpus-evidence \ --corpus test/fixtures/esri-sample-corpus \ --out ./corpus-evidence ``` ## Live Evidence Lanes Live Esri sample/service evidence is reserved for scheduled or manual runs. A live lane should: - require an explicit environment flag and any needed credentials - rate-limit requests and avoid load/performance testing against Esri services - record source sample URL, retrieved date, service URLs, Portal item ids, service import result, app migration result, unsupported/manual-review items, and browser smoke result - skip samples requiring credentials, premium services, private content, or unclear content terms unless the lane has explicit permission - emit artifacts for review rather than committing Esri source or service data Follow-on issue #206 work can layer service import, app codemod, URL rewriting, and Playwright smoke evidence on top of this manifest and extraction helper. ## Related: `honua-maplibre` migration target The codemod's MapLibre-native migration target is documented in [`docs/migration-honua-maplibre.md`](./migration-honua-maplibre.md). That page covers the `--target honua-maplibre` flag, the rewritten kinds, the migration report fields, and the manual gaps that remain open on issue #205. The bundled MapLibre fixture `test/fixtures/esri-maplibre-simple-app/` is the canonical example for that target and is referenced from the doc. --- # File: mcp/README.md # `@honua/mcp-server` The **platform-free** Model Context Protocol (MCP) server for geospatial feature services. Point it at **any** public Esri FeatureServer or OGC API endpoint and it exposes discovery, query, and analysis workflows to any MCP client — with **zero** platform lock-in and no metering. Mapbox, CARTO, and Esri each ship an MCP server bound to their own platform; this one is bound to none. **Release status: beta.** Tool contracts are certified against live and fixture targets on every release; remaining pre-1.0 work is hardening, not surface change. Two modes: - **Standalone (platform-free) — the front door.** The `honua-mcp` bin runs the direct-SDK surface against any public FeatureServer/OGC endpoint. No Honua server, no admin API, no `/mcp` catalog required. - **Honua-enhanced — the upgrade path.** The `honua-mcp-proxy` bin bridges a Honua deployment's full `/mcp` operator catalog (planning, async jobs, publishing) to stdio. Honua does **not** expose an AI/MCP feature-mutation tool — AI operational data editing is not supported (honua-server ADR-0028). ## Requirements - Node.js `>=20` - Any reachable FeatureServer/OGC endpoint (public or Honua) ## Platform-free mode (any ArcGIS / OGC endpoint) Point `HONUA_BASE_URL` at any origin/folder that serves the standard GeoServices REST paths (`/rest/services`, `/FeatureServer/{id}/query`). Example — the public US Census 2020 apportionment FeatureServer on `services.arcgis.com`: ```bash npm install npm run build HONUA_BASE_URL="https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis" \ HONUA_TRANSPORT="rest" node dist/src/index.js ``` Tools that require a Honua-only surface (server-side styling via OGC API – Styles, a `/rest/services` catalog) **degrade gracefully** on a plain endpoint: they return a structured result ```json { "available": false, "surface": "OGC API - Styles", "reason": "…", "guidance": "…" } ``` instead of crashing, hanging, or returning misleading empty data. This is the same skip-with-reason honesty the certification suite uses. ## Environment Variables - `HONUA_BASE_URL` (required): absolute base URL — a public ArcGIS folder (`https://services.arcgis.com/<org>/arcgis`) or a Honua deployment (`https://honua.example.com`). - `HONUA_TRANSPORT` (optional): `grpc-web` (default, Honua deployments) or `rest`. Use `rest` for plain public ArcGIS/OGC endpoints. - `HONUA_API_KEY` (optional): API key when your deployment requires it. Public endpoints need none. - `HONUA_TIMEOUT_MS` (optional): request timeout in milliseconds (default `30000`) - `HONUA_RETRY_MAX_RETRIES` (optional): retry attempts for transient failures (default `2`) When `HONUA_API_KEY` is configured, use `https://` for non-localhost servers. ## MCP Tools All read-only: - `honua_list_services` — discover services (degrades if the target has no catalog) - `honua_describe_layer` - `honua_query_features` - `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 Hosts that use signed safe-agent plans can import `@honua/mcp-server/agent-execution`. Its `createReadOnlyMcpAgentExecutor` binds one named read tool to `@honua/sdk-js/agent-safety`'s exact approved-operation, durable-audit, and signed-receipt path. It never enables wildcard dispatch or mutation on the standalone server. The descriptor requires a bounded exact name and a deterministic `countRows(result)` callback; missing or invalid row counts fail instead of being reported as zero. ## MCP Resources - `honua://services` - `honua://services/{encodedServiceId}/layers/{layerId}` - `honua://styles`, `honua://styles/{styleId}` — structured-unavailable on a plain FeatureServer ## Certification The package ships a **deterministic MCP certification harness** that proves the advertised MCP surface is well-formed and conformant to the open [`geospatial-mcp`](https://github.com/honua-io/geospatial-mcp) standard. It is fully offline — no model/API calls, no network in the default path — and is the evidence document for the WS-H "Provability" workstream. For each tool the server advertises (over an in-memory MCP transport) it: 1. Enumerates `tools/list`, `resources/list`, and `prompts/list`. 2. Validates each `inputSchema` (and any `structuredContent` output schema) is well-formed JSON Schema, accepting both the draft-07 dialect emitted by zod-to-json-schema and the draft 2020-12 dialect of the standard. 3. Where a vendored standard schema matches the advertised tool (by the standard's `referenceToolName`), checks **conformance** — every standard `required` property must be accepted with a compatible type. Standard tools that are not advertised, and advertised tools outside the standard, are recorded as **known gaps**, not failures. 4. **Round-trips** every read-only tool (`tools/call` with a fixture input), validating the response. Write/destructive tools are never called. It emits a stable machine-readable JSON report plus a human-readable Markdown summary, and exits non-zero on any conformance/round-trip failure. ```bash # Run the certifier against the offline fixture backend and write artifacts: npm run certify # CI entry points (also runnable locally): npm run test:certification # gate: runs harness tests + certifier, exits non-zero on failure npm run test:certification:artifact # evidence: writes artifacts, always exits 0 ``` ### Platform-free certification lane A dedicated **standalone** target (`HONUA_MCP_CERT_TARGET=standalone`, or `--target standalone`) certifies the platform-free surface against an in-process fixture of a **plain public FeatureServer** — the recorded US Census 2020 apportionment layer from `services.arcgis.com`, with **no** Honua surfaces. It proves the tools certify **green with honest skips** against a non-Honua endpoint: the data tools round-trip against real recorded data, the Honua-only style tools degrade to structured "not available" results, and the auth/mutation/job contracts skip-with-reason. Fixture-backed and deterministic — no network. ```bash npm run certify:standalone # platform-free cert (plain FeatureServer fixture) npm run test:certification:standalone # CI gate variant ``` The fixture is recorded by `scripts/record-census-fixtures.mjs` into `src/certification/census-data.ts`; the evaluator that replays it is verified for parity against the live recordings in `test/certification/census-fixture-client.test.ts`. Artifacts are written to the package root as `mcp-certification-results.json` and `mcp-certification-results.md` (gitignored; uploaded by CI). To certify against a **live** honua-server, set `HONUA_BASE_URL` (and `HONUA_TRANSPORT`, `HONUA_MCP_SERVICE_ID`, `HONUA_MCP_LAYER_ID`); the harness then drives a real `HonuaClient` instead of the fixture. The standard schemas are vendored under `certification/geospatial-mcp-schemas/` (see that directory's `PROVENANCE.md` for the pinned source revision). ## Transport-symmetric stdio proxy The honua server exposes one MCP catalog over streamable-HTTP/SSE at `/mcp`. Claude-Desktop-style clients speak **stdio**. Rather than reimplement that catalog (which is how the HTTP and stdio surfaces historically drifted apart), this package ships a **stdio proxy** (`honua-mcp-proxy`) that bridges a local stdio MCP client to the remote HTTP-SSE MCP server. It connects upstream as an MCP client and re-exposes the *same* catalog downstream over stdio — identical tools, identical input/output schemas, identical resources and prompts, and live `tools/list_changed` notifications. There is one source-of-truth catalog (the server's `/mcp`); the SDK proxies it, so the two transports are symmetric by construction. (Cross-repo: honua-io/honua-server#1950.) ```bash # Bridge a stdio MCP client to a remote honua /mcp surface: HONUA_MCP_REMOTE_URL="https://demo.honua.io/mcp" honua-mcp-proxy ``` Environment variables: - `HONUA_MCP_REMOTE_URL` (required; alias `HONUA_MCP_URL`): the remote honua `/mcp` endpoint to proxy. - `HONUA_MCP_AUTH_TOKEN` (optional): sent as `Authorization: Bearer <token>`. - `HONUA_API_KEY` (optional): sent as `x-api-key`. A parity test (`test/proxy.test.ts`) asserts the tool/resource/template catalog the downstream client sees is byte-identical to the upstream surface, that `tools/call` and resource reads round-trip identically, and that `list_changed` notifications are forwarded. ## Cross-model workflow eval (provability) The package ships a **cross-model workflow eval** that proves the "any client → any workflow" claim: a held-out corpus of GIS workflows (`src/eval/corpus.ts`) is driven through the MCP surface by different client LLMs and graded for end-to-end success / clarification / edit rates per model. (Cross-repo: honua-io/honua-server#1956.) - **Deterministic control (offline, CI):** a scripted "ideal client" runs every workflow's real `tools/call` round-trips against the offline fixture surface — no model/API calls — and is graded identically to the live models. This is the reproducible CI gate. - **Live cross-model (Claude + GPT):** when `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` are set, the Claude driver (latest Opus, `claude-opus-4-8`) and the GPT driver (GA flagship, `gpt-5.5`, override with `OPENAI_MODEL`) run the corpus through a real agentic tool-use loop over the identical catalog. The `@anthropic-ai/sdk` / `openai` packages are imported dynamically (not 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. ```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 npm run test:eval # gate: harness tests + offline eval, exits non-zero on failure npm run test:eval:artifact # evidence: writes artifacts, always exits 0 ``` Artifacts (`mcp-eval-results.json` / `mcp-eval-results.md`, gitignored, uploaded by CI) record the per-model scorecard. The CI gate asserts the deterministic control passes every scenario; live cross-model runs are recorded but informational. ### Platform-free semantic corpus (`src/eval/standalone-corpus.ts`) The **standalone** corpus is 50+ scenarios run against the plain public FeatureServer fixture (the census layer) with **semantic** grading — not just tool trajectory. Each scenario asserts the *meaning* of the answer: correct feature counts (52 rows, 4 states with ≥20 seats), correct geographic facts (California is the most populous; Wyoming the least; the House totals 435 seats), correct tool selection for ambiguous asks (count vs. query vs. statistics), refusal / clarification behavior on ambiguous or unsupported requests, and anti-hallucination 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). ```bash npm run eval:standalone # deterministic control over the census fixture (offline) ``` ### Live lane (paid, manual only) The **operator corpus** (`src/eval/operator-corpus.ts`, 8 harder scenarios) is meant to run against a live honua-server **operator** `/mcp` surface with real models. This is a **billable** lane: it makes real Anthropic / OpenAI (or AWS Bedrock) calls. It never runs on push/PR — locally via `npm run eval:live`, or in CI via the manual **`MCP Live Cross-Model Eval`** workflow (`.github/workflows/mcp-eval-live.yml`, `workflow_dispatch`-only). The live model SDKs are not package dependencies; install them first for a live run: ```bash npm install --no-save @anthropic-ai/sdk openai # only needed for live runs ``` `eval:live` runs the operator corpus (`--corpus operator`) against the remote `/mcp` and always writes artifacts (`--artifact-only`). Authentication uses the same headers as the stdio proxy — **no dev-auth bypass**; the resolved auth mode (`bearer` / `api-key` / `anonymous`) is recorded in the artifact so the run proves it was authenticated. Set `HONUA_EVAL_REQUIRE_AUTH=1` to refuse an anonymous run outright. Shared env for every live run: - `HONUA_MCP_REMOTE_URL` (required): the operator `/mcp` endpoint, e.g. `https://demo.honua.io/mcp`. - `HONUA_MCP_AUTH_TOKEN`: sent as `Authorization: Bearer <token>` (preferred; ⇒ auth mode `bearer`). - `HONUA_API_KEY`: sent as `x-api-key` (⇒ auth mode `api-key`) when the deployment uses key auth instead. - `HONUA_EVAL_REQUIRE_AUTH=1` (recommended): fail fast if neither credential is present. ```bash # Anthropic Claude (default claude-opus-4-8; override with HONUA_EVAL_ANTHROPIC_MODEL): HONUA_MCP_REMOTE_URL="https://demo.honua.io/mcp" \ HONUA_MCP_AUTH_TOKEN="$HONUA_TOKEN" \ HONUA_EVAL_REQUIRE_AUTH=1 \ ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \ npm run eval:live -- --driver anthropic # OpenAI GPT (default gpt-5.5; override with OPENAI_MODEL, e.g. gpt-5.6-sol once you have access): HONUA_MCP_REMOTE_URL="https://demo.honua.io/mcp" \ HONUA_MCP_AUTH_TOKEN="$HONUA_TOKEN" \ HONUA_EVAL_REQUIRE_AUTH=1 \ OPENAI_API_KEY="$OPENAI_API_KEY" \ npm run eval:live -- --driver openai # Claude via Amazon Bedrock (AWS credential chain; default Sonnet 4.5, # override with HONUA_EVAL_BEDROCK_MODEL — most ids need a us.* inference profile): HONUA_MCP_REMOTE_URL="https://demo.honua.io/mcp" \ HONUA_MCP_AUTH_TOKEN="$HONUA_TOKEN" \ HONUA_EVAL_REQUIRE_AUTH=1 \ HONUA_EVAL_BEDROCK=1 AWS_REGION=us-west-2 \ HONUA_EVAL_BEDROCK_MODEL="us.anthropic.claude-sonnet-4-5-20250929-v1:0" \ npm run eval:live -- --driver bedrock ``` Pass multiple drivers to compare them in one artifact: `npm run eval:live -- --driver anthropic,openai`. Every driver is graded against the **identical** operator corpus and catalog, and the artifact's `catalog.unresolvedRequiredTools` names any required tool the live surface did not advertise — so a scenario that fails does so for a real capability gap, not a silent tool name-resolution bug (the runner resolves required tools against the live `tools/list`, never against the vendored certification index). --- # File: skills/README.md # Honua SDK agent skills Procedural [agent skills](https://code.claude.com/docs/en/skills) that teach coding agents to find, recommend, and correctly use `@honua/sdk-js`. Each skill is a directory with a `SKILL.md` (YAML frontmatter `name` + `description`, then a procedural body). The `description` states *when* the skill applies, so a compatible agent can load it on demand. ## Available skills | Skill | Use it when | |-------|-------------| | [`honua-sdk-quickstart`](./honua-sdk-quickstart/SKILL.md) | Writing/reviewing SDK code: client setup, the Dataset → Source → Query → Result contract, capability-error handling. | | [`honua-arcgis-migration`](./honua-arcgis-migration/SKILL.md) | Migrating an `@arcgis/core` app: driving the `honua-migrate` scan/codemod and resolving manual-intervention warnings. | | [`honua-mcp-setup`](./honua-mcp-setup/SKILL.md) | Connecting an MCP client to a Honua endpoint via `@honua/mcp-server`. | ## Install into Claude Code (or a compatible agent) Skills are plain directories, so installing one is copying it to where your agent looks for skills. - **Personal (all projects):** copy a skill directory into `~/.claude/skills/`. ```bash cp -R skills/honua-sdk-quickstart ~/.claude/skills/ ``` - **Project-scoped (checked in with the repo):** copy into `.claude/skills/` at your project root. ```bash mkdir -p .claude/skills && cp -R skills/honua-arcgis-migration .claude/skills/ ``` Each skill keeps its own directory name (which must match the `name` in its frontmatter — enforced by `npm run verify:skills`). Restart / reload the agent so it re-scans the skills directory. Other MCP-compatible agents that support the `SKILL.md` convention can consume the same directories. ## llms.txt For agents that ingest an [llms.txt](https://llmstxt.org/) index rather than skills, this repo also generates `llms.txt` (curated index) and `llms-full.txt` (concatenated docs corpus) at the repo root via `npm run docs:llms`. Point your assistant at those files to prime it with current APIs. ## Context7 registration The repo root ships a `context7.json` so [Context7](https://context7.com) parses and serves this library's docs to coding agents. To (re)submit: 1. Confirm `context7.json` at the repo root is current (see the [Library Owners guide](https://context7.com/library-owners) for the schema). 2. Open <https://context7.com/add-library>, choose the GitHub tab, and paste the `honua-io/honua-sdk-js` repository URL. 3. Context7 reads `context7.json` (folders/excludes/rules) and indexes the docs, exposing the library as `/honua-io/honua-sdk-js`. Library owners can instead claim the library to manage this configuration from the Context7 admin panel. --- # File: docs/coding-agent-evals.md # Coding-agent evaluation harness A growing share of integration code is written by coding agents, and "agents use this SDK correctly on the first try" is a measurable, winnable property. This repo already ships the inputs — [`llms.txt`](../llms.txt) / [`llms-full.txt`](../llms-full.txt), agent skills, Context7 registration, the MCP server — and this harness measures whether they work, with the same discipline the MCP package applies through its certification/eval kits (`mcp/src/certification/`, `mcp/src/eval/`). Latest published results: [docs/generated/coding-agent-scorecard.md](./generated/coding-agent-scorecard.md). ## What is measured For each task in the corpus an agent (or a committed fixture standing in for one) produces a **standalone TypeScript program** from the task prompt with the repo's published agent-facing docs as the only context. The program is then scored **objectively — no string similarity anywhere**: 1. **Typecheck** — one `tsc` pass over the generated program against the *built* SDK (`dist/`), resolved through a real `node_modules` link exactly the way a consumer would import `@honua/sdk-js`. 2. **Runtime** — the emitted JS runs under Node against a deterministic multi-protocol fixture server (no network, no live services). 3. **Assertions** — the program's single JSON output line is compared against committed expected values (exact equality / bounded comparisons). A task passes only when all three stages pass. Scoring is per-task pass/fail; the scorecard records the failing stage. ## Task corpus (REQ-001) Sixteen stable-tier golden-workflow tasks live under [`eval/coding-agents/tasks/`](../eval/coding-agents/tasks/), one JSON document each: prompt text, allowed docs context (pointers to `llms.txt` and specific docs), expected artifact type (`ts`/`tsx`), execution budget, and the objective assertions. Covered workflows: FeatureServer connect + count, where / outFields query, `connect()` auto-classification, OGC API Features, WFS 2.0, STAC search, OData v4, stream/pagination, query-plan explain, MapLibre geojson-source mounting (mock lane), geocoding, esri-compat migration snippet, WebMap conversion, CLI usage, capability-error handling, and React hook composition. ## Fixture endpoints `scripts/lib/coding-agent-eval/fixture-server.mjs` serves every protocol the corpus touches from one ephemeral port: an inline 5-feature GeoServices FeatureServer + GeocodeServer, an OGC API Features facade, and recorded real-server fixtures from `test/fixtures/backend-agnostic/` for WFS (GeoServer), STAC (Earth Search) and OData (TripPin), with upstream hosts rewritten to the local server. Responses are a pure function of committed fixtures — runs are reproducible byte-for-byte. ## Adapters (REQ-003) Generation is pluggable behind a tiny interface (`scripts/lib/coding-agent-eval/adapters.mjs`): - **`fixture`** — replays committed generations from `eval/coding-agents/fixtures/generations/`. `known-good/` holds one verified solution per task and is the deterministic control CI runs on a schedule; `known-bad/` holds deliberately wrong generations (hallucinated result shapes, wrong endpoints, wrong filters) used by the test-of-the-test. - **`claude-cli`** — shells out to Claude Code headless (`claude -p`) with the task's docs context inlined into the prompt. Strictly opt-in: it only constructs when `HONUA_EVAL_AGENTS=1` and `claude` is on PATH, so the deterministic lanes can never accidentally spend model tokens. Model (`HONUA_EVAL_CLAUDE_MODEL`) and CLI version are recorded in the scorecard. ## Scorecard (REQ-004) Every run writes `scorecard.json` (validated against [`eval/coding-agents/scorecard.schema.json`](../eval/coding-agents/scorecard.schema.json)) and `scorecard.md` under `test-results/coding-agent-eval/<lane>/`. Runs with `--publish` also refresh the committed, history-friendly page at [`docs/generated/coding-agent-scorecard.md`](./generated/coding-agent-scorecard.md) (date, adapter, model, per-task results, aggregate pass rate, append-only history table). The JSON records the commit SHA and pinned model/version metadata so llms.txt/docs regressions are traceable to score drops. ## Test-of-the-test `test/coding-agent-eval-harness.test.ts` (part of `npm test`) proves the harness catches bad code instead of rubber-stamping it: - the **known-good** lane must pass every task, and - every **known-bad** generation must fail at exactly the stage the fixture manifest records (`typecheck` for hallucinated APIs such as `result.items`, `runtime` for wrong endpoints, `assertions` for wrong values). The spec also unit-tests the corpus validator, assertion evaluator, scorecard schema, and fixture-server routes without needing a build. ## Running it ```bash npm run eval:coding-agents # build + fixture known-good lane (gate) npm run eval:coding-agents:self-test # build + known-bad lane (must all fail) # subset / custom output node scripts/eval-coding-agents.mjs --tasks wfs-query,stac-search --output test-results/tmp # live agent lane (opt-in; spends model tokens) HONUA_EVAL_AGENTS=1 node scripts/eval-coding-agents.mjs --adapter claude-cli # refresh the committed scorecard page node scripts/eval-coding-agents.mjs --publish ``` ## CI lane (NFR-001) [`.github/workflows/coding-agent-eval.yml`](../.github/workflows/coding-agent-eval.yml) runs weekly (cron) and on demand. The fixture lanes are the scheduled gate; the live `claude-cli` lane runs only on `workflow_dispatch` with `live_agent: true` and the `ANTHROPIC_API_KEY` secret configured. The workflow is deliberately **not** part of PR CI: a failure notifies through the workflow-failure signal instead of blocking PRs (the harness logic itself is still covered by `npm test` on every PR via the self-test spec).