OpenMapStack 0.5.0

0.5.0 release preparation

Status: 0.5.0 accepted for publication by the maintainer on 2026-10-27, with explicit exceptions (#122). Changes cover v0.4.0 through main at eb41c238a7d82d41ddfa74703a1f20fdbb38720c. The coordinated CLI, collection, plugin and four skill versions are 0.5.0. No tag or release has been published. The acceptance record records the decision and its exceptions; candidate evidence records the executed checks.

OpenMapStack 0.5.0 expands the reproducible-project contract beyond a single dashboard, adds integrations with established data stacks, and strengthens the link between an analysis, its delivered views and its evidence. The four independently installable skills retain their identities: open-map-stack, reproducible-gis-project, geospatial-data-discovery and spatial-sql. Install the CLI separately at the matching release version.

Skills, project contract and delivery

• Selectable delivery profiles. Projects can select dashboard, QGIS, Observable, or combined delivery through openmapstack-delivery/v1. New templates default to the dashboard; manifests without a delivery declaration keep their legacy behavior. Selected targets bind their artifacts to canonical inputs, shared analysis semantics and receipts. Missing selected artifacts cannot be rescued by an unrelated legacy output. (#81)
• Established-stack integrations. Optional openmapstack-integrations/v1 declarations bind existing owners of ingestion, models, orchestration and presentation instead of introducing a second analysis DAG. Runnable examples cover dlt, dbt with DuckDB Spatial, Dagster, Observable Framework and optional QGIS, including a composed workflow. Observable delivery includes the complete local static bundle and checks for missing or changed resources. (#82)
• Versioned views. openmapstack-views/0.1 defines workspace/report layouts, semantic tokens, themes and a control-state protocol while keeping each project's renderer local. Projects can declare multiple pages through top-level views:, page-specific presentation, and exploratory versus published controls. Tartu and NYC demonstrate the protocol; checks operate controls on inactive tabs and restore canonical state. (#84)
• AOI extent checks. An optional project.aoi declares an x/y bounding box and CRS. geodata.layer_extent_within_aoi checks local output extents, warns on partial excursions, fails wholly out-of-area results, and diagnoses likely swapped axes without changing coordinates. Explicit global outputs are exempt. (#87)
• Basemaps and vector tiles. Basemap guidance prefers an explicit user choice, then a suitable regional official service, with the preconfigured goplex.ee Protomaps service as fallback. Tartu reads basemap configuration from the manifest, retains provider attribution and preserves it across themes. Tiling guidance adds tylertoo alongside Tippecanoe and Planetiler, with a runnable GeoParquet-to-PMTiles example, explicit overview choices and fidelity checks. (#85, #90)
• Lazy raster processing. Guidance replaces an eagerly warping chunked-rioxarray pattern with a tested lazy odc-geo warp. Optional async GeoTIFF examples use explicit overviews, bounded windows, concurrency and deadlines. Tests check grids, masks, calibration, range responses and eager-computation mutations. (#99)
• Override evidence. Shared validation accepts title-and-page citations as well as source/value entries and plain references, preserves documented value precedence, and rejects empty, malformed or placeholder evidence that previously passed. This establishes declaration completeness; it does not certify the truth of the cited document. (#103)
• Findings and delivery credits. Optional pipeline-generated findings.md combines versioned structured claims with readable Markdown, tying findings to definitions, units, assumptions, limitations, validation and run identity. Its evidence inventory includes primary results and every declared table download. Delivery credits bind the author, OpenMapStack link and offset-bearing analysis time across selected HTML, QGIS and report surfaces; example findings and credits are generated from the canonical run. (#106, #108)
• DuckDB 1.5.3 and 2.0 support. Spatial connections explicitly configure x/y order after loading Spatial, including MotherDuck and the example/provisioning paths. Clear per-transform always_xy arguments remain. Tartu reads GeoJSON FeatureCollections explicitly under DuckDB 2.0; NYC handles geometry bytes explicitly and its swapped-axis mini-fleet fixture has been corrected. Tartu's manifest, requirements and run attestation now agree on its higher 2.0.0 pin. (#113)
• Installation and execution. The homepage provides ChatGPT, Claude, Codex and Cursor installation guides and four uploadable skill ZIPs. The discovery and SQL specialists now carry only their bounded guidance and references; the two project-owning skills retain templates, schemas and trimmed examples. openmapstack run prepares declared Python dependencies in a reusable project virtualenv and reports native-runtime setup separately. (#105, payload-scope change, CLI dependency setup)
• Worked examples and sample discovery. Tartu adds pedestrian-network isochrones and explicit hypothetical scenarios. NYC adds a private-mobility demonstration using synthetic business records and historical TLC pickup coordinates, rather than a live operational fleet. The homepage groups NYC mobility and Tartu city development under “Bundled templates,” with standalone and Observable views, and links once to the independent More examples gallery. (Tartu changes, NYC changes, Observable samples, #116)

Checks and evals

• Live-output checks resolve results through declared semantic IDs instead of a reference pipeline's physical filenames. Coordinate checks use independent asymmetric known points across GeoJSON, MapLibre and Leaflet interfaces. Wrong, missing, invented and axis-swapped results remain failures. (#72, #74, integration #76)
• Non-spatial kind: table outputs support CSV/JSON and optional Parquet/XLSX, with declared columns, types, unique keys, download consistency and semantic clean-rerun comparisons. Declared document outputs are checked for existence. Date/time validation rejects impossible values while accepting supported timezone-bearing DuckDB timestamps. (#75, #76)
• Preflight treats an unfetched source snapshot as unavailable content evidence rather than an immediate missing-artifact failure; full validation still audits fetched artifacts. (preflight change)
• QGIS checks strengthen native save/reopen, project CRS, local datasource portability and regeneration. Browser checks reject zero-height maps, inspect the map before unrelated canvases, require actual basemap tile requests, and check declared pages, controls, resets and mobile bounds. (#76, #84, #85)
• The scheduled mobile-overflow defect was fixture-only CSS: a desktop sidebar left a 50px map at a 390px viewport. The reference fixture now places the map above the sidebar on phones. Strict bounds assertions are unchanged; healthy controls pass and a mutation restoring the overflow fails. Tartu and NYC's shipped layouts passed the scoped inspection and required no corresponding CSS change. (#115)
• Static evidence remains conservative. project.duckdb_axis_order_explicit warns on an obvious setup omission and otherwise reports not_testable; it never reports passed. An independent runtime coordinate assertion supplies the axis-order guarantee. Ambiguous static credit visibility also defers to an explicit browser assertion. Expected diagnostic deferrals do not count as passed assertion coverage or fully exercised capability. (#108, #113)

CI and maintenance

• Compatibility and complete fixture/offline CI matrices now cover DuckDB 1.5.3 and 2.0.x. Dedicated real tylertoo, optional raster, warehouse and native QGIS/browser jobs provide evidence beyond deterministic fixtures. Pages builds cover pull requests; deployment remains restricted to main. (#90, #99, #113, #116)
• Allure exports retained trial evidence, and optional LangSmith imports support human review without executing or regrading agents. Provider setup failures remain distinct from skill assertion failures. Benchmark CI explicitly records unconfigured providers as skipped/not run, installs Bubblewrap prerequisites, limits jobs to 90 minutes and the benchmark step to 35 minutes, and checkpoints incomplete runs without hiding failure. (reporting work, #117)
• Evidence ZIPs omit virtualenvs and symlinks with recorded omissions while retaining artifact-root protections. Atomic result publication preserves normal umask-controlled permissions so root-produced offline JSON can be uploaded by the runner. Skill packaging also works from source directories without Git metadata. (#106, #117)
• Maintainer decisions document standalone payloads, in-repository sandboxed release trials, delivery profiles, integrations and the design language. Historical 0.4.0 preparation links point to the frozen release tag. (#77, #78)

Upgrade notes / breaking changes

1. DuckDB now requires duckdb>=1.5.3 wherever the DuckDB runtime is used. This is the first version combining geometry_always_xy and ST_SymDifference; older versions can also export projected GeoJSON without CRS metadata. Upgrade the runtime, configure axes after Spatial loads, then regenerate and validate affected artifacts. The core CLI still has optional geospatial dependencies, and higher reproducible example pins remain in force. (spatial SQL reference, #113)
2. Credits change validation outcomes for existing projects. New or updated deliveries must declare both project.author and project.generated_with. A legacy v1 manifest declaring neither receives warning credits_legacy_missing; this warning alone does not invalidate a stored validated status. Declaring either requires both, and partial declarations fail validation. Declared credits must match rendered identities, links and the offset-bearing runs.latest.completed_at; only projects without a canonical run may use a labeled project.updated_at fallback. Regenerate views and attestations together. (credits contract, #108)
3. Strict mode still treats warnings and not_testable as non-success. Ordinary validation/verification accepts warnings with aggregate status warning; --strict returns exit 1 for warnings or unavailable checks. Thus the legacy credits warning, unavailable browser/native checks, or the deliberately non-passing static DuckDB advisory can change a previously green strict run. Absence of an axis warning is not proof of correct coordinates. (verification behavior, #113)
4. Older basemap and assumption declarations may need migration. Every declared basemap now needs its actual kind (raster-xyz, raster-wms or vector-style); vector styles need a style url. Assumptions require unique nonblank id, statement and rationale strings; an empty assumptions list warns. Extension metadata is permitted only where the schema allows additional properties and gains no implicit execution semantics. (basemap contract, assumption change)
5. New declarations opt into their complete contracts. Delivery, integrations, findings and the design language add artifact, evidence and runtime checks when declared; omitting delivery preserves legacy behavior. Findings must inventory all declared downloads, and missing/stale evidence fails. CSV/JSON analytical tables need explicit kind: table; an omitted output kind still means geodata. Update manifests, pipelines, delivered files and run inventories together. The project schema remains openmapstack-project/v1. (#75, #81, #82, #84, #106)
6. Revalidate override evidence and copied skill assets. Placeholder or incomplete override evidence may now fail. Consumers that obtained project templates from the discovery or SQL skill should install a project-owning skill instead; those bounded specialists no longer include project payloads. Refresh installed skill copies and the CLI together at matching versions. (#103, standalone distribution decision)

Validation and release status

The prepublication candidate is fb0531d15167c1287a47737b9358e43a0a9a5063. It merges main at c40488b (#119, #121, #123, #124) into the earlier candidate 6558374, which it supersedes. Later preparation commits update only this document and the acceptance record; the tested runtime, package inputs and skill payloads retain the candidate bytes.

Executed locally with Python 3.12.14 and DuckDB 2.0.0:

• Version agreement and shared-asset synchronization passed. The full coverage run completed 1,139 tests, with 49 explicit skips, and reached 83% assertion coverage against the 70% gate.
• Fixture evals matched 31/31 diagnostic/contract cases and detected 68/68 isolated mutations, with no assertion or setup failures. 5/378 contract assertions remain not_testable and 4 soft gates are unmet; 9 mode-only case definitions were skipped. This is not fully exercised capability.
• Wheel and source distribution builds passed twine check. All four skill ZIPs and five collection/standalone snapshots were built; snapshot inspection passed, and changed/missing-file controls were rejected. Source-directory ZIP builds without Git metadata retained identical payloads. Against the 6558374 build, the wheel, ZIP and snapshot payloads are identical and the source distribution differs only in tests/test_benchmark_ci.py; no file is byte-identical, because archives record build times and snapshots record their source commit.
• A fresh installed wheel reported 0.5.0 and exposed its packaged schemas and check API. All four physically isolated skills passed copied project/global install, explicit replacement of the real 0.4.0 generalist, payload, v2 snapshot and removal checks. All eight installed snapshot hashes match the candidate. The four trimmed-example preflights each retain 31 passed, 1 warning and 1 not-testable check, with no failures; they do not establish a completed example analysis.
• Hosted commit-pinned project/generalist and global/SQL installs preserved payload and lock through update, then removed cleanly. Local plugin manifest/inventory and isolated install/update/uninstall checks passed. Default-branch floating updates and actual-tag/PyPI installs remain separate verification.
• In the CI visual image (QGIS 3.44.15, headless Chromium), the full visual suite passed 3/3 integration cases and 4/4 visual mutations with no not_testable assertions. All 69 PyQGIS unit tests passed; the two real worked-example tests needed the example regenerated from its sources first, as the CI worked-example job does. With host QGIS 3.40.15, verify of the regenerated worked example passed every executed check, but the process aborted on exit; the maintainer accepted this as a limitation of that older QGIS version. Raster, PostGIS, warehouse, live-catalog and other optional runtimes without local fixtures remain not_testable.

CI on the candidate passed all nine jobs that ran (the Pages deploy job was skipped), including fixture/offline evals on DuckDB 1.5.3 and 2.0.x and the worked example (fixture evals, worked example, plugin manifests).

Exact filenames, SHA-256 hashes, snapshot inventories, tool versions, logs and pending gates are recorded in candidate evidence. Build outputs, environments and caches are retained under ~/.cache/agent-tmp/oms-050-rc2/ and are excluded from the repository.

Recorded PR evidence includes full unit/coverage and fixture/offline CI passes on DuckDB 1.5.3 and 2.0.x (#113, #117), scoped credits visibility controls (#108), a healthy mobile layout and failing overflow mutation (#115), and desktop/390px homepage checks (#116). These are evidence at their recorded PR revisions, not new 0.5.0 acceptance totals. Unavailable assertions remain unavailable even when a diagnostic case matches its expected result.

The maintainer accepted 0.5.0 for publication with three explicit exceptions, recorded in the acceptance record: live executed-project and routing acceptance, with the recheck of the October 6 output and contract failures, is deferred (#122); the host QGIS 3.40.15 exit abort is accepted as a limitation of that version; and the capabilities recorded as not_testable, including the 5 fixture assertions and 4 unmet soft gates, remain unavailable and are not counted as passed. No live or paid benchmark ran for this release. Actual-tag/PyPI verification remains separate from local deterministic, installation and native/visual checks.

Reference format and prior evidence: published 0.4.0 notes, frozen final preparation, and 0.4.0 acceptance JSON.