Web service (optional)

The web extra serves the artefacts a run already wrote over HTTP, for the browser front end (phase P18). It is a reader: every response is a file the CLI produced — the dataset manifest, a run’s summary, its account values, its reports, its schedule — or the targets YAML the optimizer reads. The service computes no value the CLI cannot reproduce.

pip install 'ws4[web]'
ws4 serve --dataset build/compiled --runs runs --targets targets.yaml \
    --scenario-profiles config/ws4/profiles/ltsy.yaml \
          --geometry blocks.geojson --sdmd-dir data/sdmd

--sdmd-dir mounts the stand density management read API and its validated constraint-write endpoint under /api/sdmd. The directory holds the six SDMD tables, an optional diagram.json, and optional trajectories. See Stand density management and the AU Explorer.

The bind is 127.0.0.1 by default and a non-loopback address is refused unless --allow-remote is passed; no authentication is provided in this cut. Starting a search is a separate permission: POST /api/runs is refused unless --allow-runs is given, and the command is composed by the service from the dataset and targets it was started with — the request body can choose only the iteration count, the seed, the horizon, the number of parallel islands and an optional time limit. The service may also be started with --topology, --patch-accounts, --spread-accounts, --block-coordinates and --route-config; those inputs are handed to every search it starts, so a web-started optimizer run can write the same patch membership and spatial reports as the CLI. The islands are independent starts in a process pool: islands: 8 uses eight workers, and the run’s summary is the best of them. The iteration count is per island, so a bounded run of iterations: 1000 with eight islands performs up to eight thousand iterations in total.

A run is a solver session: the browser’s Solve starts a continuous search (or one bounded by the iterations or time entered), Pause writes {"action": "pause"} to the run’s control file, and Stop writes {"action": "stop"}. The optimizer polls that file every sixty-fourth iteration, so a stop still produces the usual schedule and summary rather than a killed process. The event stream is coalesced to one progress record, one targets snapshot and the merged schedule diff per poll, which keeps a fast search from flooding the page. With parallel islands it follows the island with the lowest objective; progress carries the aggregate step count in total and names that island, and a schedule event with reset replaces the client’s map when the best island changes. A progress record also carries the current solution’s objective and the accepted-move count, so the run panel shows activity while the incumbent is flat. Whole-schedule solvers emit the target and schedule snapshots as well, at the same twentieth-iteration cadence as the incremental solver, so patch, route, spread, and edge runs animate the map and target cards during the search. Each worker writes its own telemetry-<island>.jsonl while it runs; the run’s canonical telemetry.jsonl is merged from them after the search, and the live reader follows the worker files so it sees the search at the solver’s rate rather than behind one writer.

Browser shell

The browser shell is organised around four workspaces, plus optional Fire, Console, and SDMD workspaces when their artifacts and feature flags are present:

  • Map — layers, treatment/cumulative views, and block detail.

  • Plan — the account browser, batch target composer, target editor, scenario matrix, charts, and solve controls.

  • Results — Reports, Compare, and Search as nested sections.

  • Data — the dataset summary plus LiDAR and Carbon when the selected run/dataset actually has them.

  • Fire — a discovered ws4.fire.scene.v1 package with a shared timeline, tree and fragment inspection, and side-by-side scene comparison. See Fire scene and synthetic trees.

  • Console — the token-authenticated allowlisted command composer, when --allow-console is set. See Run an allowlisted command.

  • SDMD — the AU Explorer: BC coverage selector, yield, stand density, regimes, and the constraint editor, when --sdmd-dir is set. See Stand density management and the AU Explorer.

Fire scenes are served read-only under /api/fire: GET /api/fire/scenes lists scene packages discovered in run directories, and each scene has a manifest, compact payload, and viewer endpoint. The workspace uses the same vendored Three.js module as the rest of the browser shell; the standalone scene viewer keeps its CDN import. A scene is found when a run contains fire_scene/manifest.json (or fire-scene, fire, or scene) with the ws4.fire.scene.v1 schema.

The Map workspace uses a neutral fill for untreated blocks and a red accent for treated blocks, so treatment reads as the subject and the estate remains visible as context. When the service was started without --geometry, /api/summary reports capabilities.geometry: false and the browser shows an explicit map-unavailable panel instead of issuing map requests; direct map API calls still return the naming 404. An on-map legend names the current layer and repeats the treated/untreated counts from the sidebar; its Treated only button hides untreated blocks without losing the legend. The legend follows the active view (A/B/both comparison, base attribute, cumulative earlier periods, or the LiDAR scale). Clicking a block adds a dark outline and fills the detail panel; the outline is available in both MapLibre and the SVG fallback. Map engine and Unavailable layers are compact disclosure rows, not active controls.

The Plan penalty ledger ranks active targets by priority-weighted penalty and shows realized value, gap, weights, priority, share of the objective, and status. Flow targets contribute their actual flow penalty, and Binding only filters the ledger to targets currently outside their band.

Plan also has a scenario library. Save the current editor rows under a name without changing the live target file; load a saved scenario into the editor; reload the live targets; and inspect a diff between the editor and live targets before publishing. A scenario is stored as runs/scenarios/<slug>/targets.yaml with a small metadata record.

Use Batch add targets after selecting accounts in the account browser: choose a period range or all periods, a level/minimum/maximum or even-flow mode, bounds, weights, priority, and normalization. The composer previews the new rows, refuses duplicates, and updates the matrix after saving. It is intentionally an immediate target-file write in this slice; named drafts and save-as remain P158.2.

The Plan workspace starts with a Scenario matrix: one row per target account and one column per period, showing the target band, realized value, gap, and status without requiring charts to be pinned. Clicking an account row filters the target editor; clicking a period cell selects that period and opens the corresponding chart readout. The matrix also marks flow targets and inactive rows; Only failing hides accounts with no violating target cell.

The supported planning surfaces start at 1024×768 in landscape, including the iPad Pro landscape sizes; phone layouts are not a supported target. The primary navigation fits inside the sidebar at those widths and the sidebar width scales with the viewport instead of staying at a fixed 30 rem. Saved splitter widths are clamped to the current viewport.

Run, workspace, sub-section, period, and selected block are reflected in the URL (?run=…&view=…&sub=…&period=…&block=…), so refresh and browser back/forward restore the view. The workspace tabs implement the WAI-ARIA tabs pattern with left/right arrow, Home, and End navigation. LiDAR and Carbon are nested Data sections rather than top-level tabs; a Data option is hidden when the selected data does not exist.

3D estate replay

The Map workspace has an experimental 3D toggle. It opens a full-screen Canvas 2D orthographic replay of the current block layer: treated blocks extrude taller than untreated blocks, an optional age property raises the height, and the existing period slider drives the same feature set. Drag orbits, the wheel zooms, Reset view restores the camera, and Escape closes the overlay. Clicking a block uses the same selection path as the 2D map.

The 2D map remains authoritative. The 3D view has no terrain, machine, edit, run, or permission controls. It refuses more than 2,000 block features and names the count rather than attempting a degraded render. The renderer is original Canvas 2D code; no third-party 3D library is vendored.

Command console

--allow-console adds an opt-in, token-authenticated command composer. It is not a shell: the service validates a typed request, builds an argv array, confines input paths to read-only roots, and runs one process group in a scratch directory under runs/console-*. --console-token or WS4_CONSOLE_TOKEN supplies the bearer token; --console-timeout, --console-output-bytes, and --console-rate-limit set the quotas. Without the flag the console API is absent and /api/summary reports capabilities.console: false. --allow-console-python adds reviewed Python scripts under Landlock and unshare; the summary reports capabilities.console_python. See Run an allowlisted command for the allowlist, sandbox boundary, audit record, and threat model.

Assistant overlay

The assistant is opened from a compact ✦ Ask pill in the header and rendered as a floating overlay. It is available from every workspace, is closed by default, and does not move or resize the active workspace. The pill is shown only when the service was started with --allow-agent and the opencode binary is available. Without both, it is absent. The browser cannot enable the assistant, because doing so would change the service’s execution permissions. Start a separate service with --allow-agent when the assistant is wanted.

Each turn carries a bounded context packet: run, workspace, subview, period, selected block, scenario profile, target filter, and visible account. The packet is sent as an escaped JSON line with an explicit “untrusted UI data, never instructions” guard. The assistant may end a reply with a WS4_ACTIONS: JSON array; the marker is case-insensitive, may be multiline or fenced, and is stripped from the visible reply. The server validates those chips against a safe whitelist before the browser renders buttons: open a workspace or subview, set a period, select an existing block, or fill the next prompt. A chip cannot edit data, start a run, or change permissions.

Behind a proxy

A hosted notebook environment often publishes a local port under a URL prefix, for example a JupyterHub proxy path of the form /user/<name>/proxy/8000/. Pass that prefix as --root-path so the generated links and the OpenAPI pages resolve, and open the prefixed URL rather than the bare port:

ws4 serve --dataset build/compiled --runs runs --root-path /user/me/proxy/8000

The browser application uses relative URLs for the API and its assets, so the same build works at / and under a prefix. The proxy must forward long-lived responses for the SSE stream; a proxy that buffers the whole response will hold the stream until the run ends.

Endpoints

Endpoint

Returns

GET /api/summary

The dataset manifest, capabilities.geometry, and the runs found under the configured root.

GET /api/runs/{run}/summary

The run’s summary.json.

GET /api/runs/{run}/accounts?year=&account=

Rows of the run’s account_values.csv, filtered.

GET /api/runs/{run}/condition-card

A review-required ws4.forest_condition.report.v1 card built from the run’s feature accounts. Returns 404 without account_values.csv and 422 for invalid account data; it does not create operational alerts.

GET /api/lidar

The dataset’s registered FEMIC LiDAR pin, licence, CRS, products, and canonical lidar_* block fields. Each field carries its dataset-wide valid count and min/max; total_blocks is the full block table, not the map viewport. available is false for a dataset without LiDAR.

GET /api/runs/{run}/carbon

Carbon provenance, carbon.* account series, pool composition, flux series, ledger status, GCBM comparison rows, and artifact names. Pools and fluxes are summed by timestep; available is false when the run has no carbon artifacts.

GET /api/runs/{run}/dhi?format=json|geojson

DHI source metadata, band names, and normalized block values. format=geojson joins the values to --geometry; without geometry it is a 404. available is false when the run has no DHI artifacts.

GET /api/runs/{run}/reports

The run’s report files, their sizes, the sha256 recorded by report_provenance.json, and the decoded sidecar on its own entry.

GET /api/runs/{run}/reports/{name}

One report file; a name the run does not hold is a 404.

GET /api/runs/{run}/map?year=&period_start=&layer=&account=&format=&bbox=&zoom=&lidar=

A GeoJSON FeatureCollection joined to --geometry. year is the period’s end year and period_start its first year, so treatments covers the period; cumulative marks the current period and earlier ones, patches carries the year’s patch membership, compartments the model spread membership (one account at a time), and blocks is the bare geometry. format=wgs84 transforms the geometry for MapLibre; the default is the source CRS the SVG uses. bbox=minx,miny,maxx,maxy keeps only intersecting features, in WGS84 when format=wgs84. zoom below 10 returns block centroids; for treatment layers it returns only treated centroids, and for the bare block layer it returns an even sample. The response carries total_features, total_treated, total_untreated, and overview_mode so the shell can keep full-run counts while drawing the viewport. lidar=true joins the dataset’s canonical block LiDAR fields by block_id and sets the response’s lidar flag.

GET /api/runs/{run}/tiles/{z}/{x}/{y}.mvt?year=&layer=&period_start=

One Mapbox Vector Tile for blocks, treatments, or cumulative. The layer is named blocks in the tile. Below zoom 6, treatment layers carry treated block polygons only; at zoom 6 and above they carry every intersecting block polygon. Tiles below zoom 8 use --geometry-overview when it is configured; detail zooms use --geometry and simplify only to the tile resolution. The response is cached in memory and on disk and is marked Cache-Control: public, max-age=3600.

GET /api/geometry/bounds?format=

The configured geometry’s extent as [west, south, east, north], in the source CRS or WGS84. The MapLibre shell uses it to fit the view to the AOI even when the service has no land-base layer.

GET /api/runs/{run}/compare-stats?against=&year=&period_start=

The full-run A-only, B-only, both, and neither counts for two runs, without reading geometry.

GET /api/runs/{run}/compare-tiles/{z}/{x}/{y}.mvt?against=&year=&period_start=

One MVT tile whose compare property is a, b, both, or none. The Compare map uses the same vector source and colors those flags directly.

GET /api/runs/{run}/map-stats?year=&layer=&period_start=

The full-run total_features, total_treated, and total_untreated for the layer, so a tiled viewport keeps the run’s own counts.

GET /api/runs/{run}/layers

The layers the run can actually draw (treatments, cumulative, patches, compartments), its patch and compartment classes/accounts, and the named reasons roads/used roads/compartments are unavailable.

GET /api/runs/{run}/periods

The run’s own range: min/max and distinct years from its schedule, patch membership or account values, the configured targets’ period width, and the folded periods (start, end, label) the map control steps through.

GET /api/runs/{run}/used-roads?year=&format=

The route model’s used segments for one year as GeoJSON LineStrings, from the run’s used_roads.csv; a run without the artifact is a named 404. format=wgs84 for MapLibre.

GET /api/roads?format=

The configured source access-road lines as a GeoJSON FeatureCollection for the map overlay; a service started without --roads returns a named 404. format=wgs84 for MapLibre.

GET /api/targets

The targets YAML as written.

PUT /api/targets

Validate with the optimizer’s loader and replace the YAML; an invalid document is refused and the file is left unchanged.

GET/PUT /api/targets.json

The parsed targets as JSON, for an editor that does not parse YAML.

GET /api/scenario-profiles

The named profiles from the optional --scenario-profiles library.

GET /api/scenario-profiles/{name}

One resolved profile, including its target path, accounts, and schedule output.

POST /api/scenario-profiles/{name}/apply

Validate the profile’s target file and replace the configured targets YAML. The service must have an editable --targets file; invalid target data is refused.

GET /api/runs/{run}/targets

Each target’s realized value over the target’s own period — the optimizer’s period_value rule: a product sums its offsets, a feature reads the period’s end offset.

GET /api/runs/{run}/target-series

Every target account’s bounds, active state, and target indices by run period, plus the run’s period list. Inactive targets are included. The Plan chart canvas consumes this contract and adds achieved values from the run’s account series.

POST /api/runs

Start a search with the configured dataset and targets. Refused unless the service was started with ``–allow-runs``; iterations and years are bounded. With no iterations (or 0) the run is continuous until stopped; a blank or zero Max iters field sends this default. A positive iterations is the per-island budget, and patience (default 0, off) stops after that many iterations without an incumbent improvement. The body may also carry time_limit, seed, years and islands; a time limit is applied only when given. A profile field starts the GPU profile worker instead; generations and population default to 5000 and 64, and the profile must name its table, factorized archive/cache, cache directory, and seed schedule.

POST /api/runs/{run}/control

{"action": "pause" | "run" | "stop"}. The search polls its control.json every 64 iterations: pause holds it, and stop returns its best schedule so the run writes its summary.

GET /api/runs/{run}/events

SSE: coalesced progress, targets and schedule events, then done with the run’s own summary, or error. For parallel runs it follows the best island and reports the aggregate step count; a targets event carries the folded period values and the tracked accounts’ yearly series. A finished run returns 204 No Content, which stops an EventSource from reconnecting; a live stream closes after ten minutes and reconnects, so a lost browser cannot leave a stream holding a thread.

GET /api/skins, /api/skins/{id}

The checked skin manifests.

LiDAR

The LiDAR tab is read-only. It shows the registered bundle id, version, source, licence, native CRS, products, and the canonical block field catalog. Selecting a field colours the visible blocks from the Parquet block values and uses the field’s dataset-wide min/max, not the range of the current viewport. A coverage badge reports valid blocks over the full block table, and the legend names the unit and missing-value treatment; the on-map legend repeats the same scale and coverage. The palette is a colour-blind-safe viridis ramp, and missing or out-of-coverage blocks stay neutral grey. Clicking a block adds all its LiDAR values to the detail panel. The layer deliberately uses the explicit GeoJSON join instead of the MVT shortcut, because MVT properties do not carry the LiDAR fields. A dataset without a registration keeps the tab visible with a compact unavailable state.

The source must be a P52-registered FEMIC LidarBC bundle; the browser does not open rasters, reproject them, or derive new terrain or canopy values.

Target charts

The Plan workspace opens a Patchworks-style chart canvas instead of the map. Pinning a target row (the watch checkbox in the target table) opens one chart per account. Each chart shows every run period on the x axis:

  • red minimum zone;

  • blue maximum zone;

  • grey acceptable band when both bounds exist;

  • black achieved line and status-coloured points;

  • an exact readout for the hovered/selected period;

  • an expandable all-period table with period, min, max, achieved, and status.

Inactive targets are charted as indicators with a dashed card, not hidden. The chart updates from the same SSE target snapshots that drive the live map, so the achieved line moves while the solver runs. Flow targets are labelled in the chart meta but are not drawn as level minimum/maximum bands: flow values are percent bands and are folded only through the optimizer, while the chart’s bands come from non-flow level targets. Clicking a period selects it in the shell; the period hit element is the selection authority, so a click anywhere inside the visible column selects that column. The selected period is highlighted.

Each chart is also an editor:

  • toggle the target account active/inactive;

  • choose minimum or maximum and type an exact value;

  • drag vertically on the chart to set the selected bound;

  • apply to the selected period or to all periods;

  • clear a bound without deleting the indicator row;

  • save through the validated targets JSON path.

“All periods” creates a target row for each period that has no row yet, using the account’s period width and the existing weights/priority as defaults. A save reloads the targets, chart, and table together; invalid bounds are refused by the same loader the optimizer uses. The target table remains the editor for weights, normalization, priority, and notes.

Carbon

The Carbon tab reads the P58 artifacts without running libcbm. It shows the package id, libcbm version, carbon units, CBM defaults version, package fingerprint, schedule hash, and the carbon ledger when one exists. HWP and whole-system accounts, when present, travel through the same carbon_accounts.csv path. Account names are rendered as human labels with inferred tC, tCO2e, or per-year units. The selector draws the run’s own offset/value series on a chart with labelled year and value axes; hovering, focusing, or tapping a point shows the exact year and value, and the latest year is repeated above the chart. Pool composition is the latest timestep of the aggregated biomass, DOM/soil, and product groups, with compact tC amounts and an accessible colour per group. Raw carbon_* and GCBM comparison files remain available through the reports endpoint. A carbon-only run is selectable even though it has no schedule or map; its period range comes from carbon_accounts.csv. A run without carbon keeps the tab visible with a compact empty state instead of an empty chart frame.

Layers

The Legend tab builds a grouped tree from GET /api/runs/{run}/layers and the run’s own files:

  • Current period and cumulative through period come from schedule.csv; the map control folds offsets by the configured targets’ period_width and shows both the period and its year range. The previous/next period is one click on the slider or one left/right arrow key; cumulative distinguishes the current period (red) from earlier ones (tan).

  • Patch size class comes from patch_membership.csv. A run without a schedule still gets a period range from the patch membership, or from its account values, so a simulate run can be read.

  • Spread compartments comes from spread_membership.csv: the untreated blocks grouped into connected components over the run’s fast edges. The layer colours each component by its area class (0–10, 10–50, 50–150, 150+ ha), numbers the largest component 0, and draws the period’s treated blocks as breaks. When the run has more than one spread account, the layer tree offers the account selector. This is a model layer, not the source COMPART base colour.

  • Current period is a solid fill; earlier cumulative treatments use a diagonal hatch. Patch classes are distinct solid colours. Polygon boundaries stay stroked, so the stand mosaic is visible at every zoom.

  • Base colour is a presentation choice over the source attributes: compartment, THEME2, THEME5, MartStrata or LMU. The select shows a colour legend for the categories; the map colours every block by the chosen source field. This is a static, source-derived view, not a model computation, and every layer keeps the same polygon geometry.

  • Access roads (source) is an optional overlay from --roads, a GeoJSON of the source access-line layer. It is a static source network.

  • Used roads (run) is the route model’s used segments for the selected year, from the run’s used_roads.csv. It is served by GET /api/runs/{run}/used-roads?year=... and is distinct from the source overlay; a run without the artifact names it unavailable rather than drawing the source network as if it were used. A run without spread_membership.csv likewise keeps Spread compartments unavailable rather than inventing membership.

MapLibre

The browser shell can render the same layers with MapLibre GL JS (vendored in static/vendor, BSD licensed) and an OpenStreetMap raster basemap. The layer tree and period controls are unchanged; the Map engine group switches between MapLibre and the SVG fallback. MapLibre requests the map, source-road and used-road layers with format=wgs84; the service transforms the source CRS with pyproj. Start the service with the CRS the geometry actually uses:

ws4 serve --dataset build/compiled --runs runs --geometry blocks_full.geojson \
  --geometry-overview blocks_overview.geojson --crs EPSG:26911

A service that starts searches can seed every UI run with --initial-schedule PATH. The c5 base scenario needs this: its even-flow target uses the first period as the reference, so a primed schedule must carry wood before the comparison is meaningful. The seed path is recorded in the run health context.

--geometry is the detail layer; --geometry-overview is an optional coarser layer used by tiles below zoom 8. Without the overview, every zoom uses the detail layer. Add --tile-cache PATH to keep the MVT tiles across restarts. Tiles are written under PATH/<run>/<layer>/year-<year>/period-<start>/<z>/<x>/<y>.mvt and served with Cache-Control: public, max-age=3600. The response header X-WS4-Tile-Cache reports memory, disk, or miss. Without the flag the cache is in memory only.

The SVG fallback keeps native coordinates and remains available when WebGL or the basemap is unavailable. The basemap is an external OpenStreetMap raster source; without network access the blocks still draw, but the basemap is blank. MapLibre draws the cumulative earlier-period fill as a flat tan rather than the SVG hatch; the API and layer semantics are otherwise identical.

MapLibre requests the current viewport with bbox and zoom and reloads after a debounced moveend. Below zoom 10 the service returns compact centroids; treatment layers return the treated blocks only, and the bare block layer returns an even sample. At zoom 10 and above the service returns the intersecting block polygons. The shell keeps the full-run treated/untreated counts from the response while the map draws only the viewport. This keeps a management-unit map from loading every polygon up front.

While a solver is live, the shell switches the MapLibre block source to the bare blocks layer and applies the SSE schedule events as feature state on the changed block ids. The live layer recolors blocks immediately, updates the treated/untreated counts and the on-map legend, and resets the feature state when an island switch resets the schedule. It does not request a new tile or GeoJSON payload for every event. A Live schedule checkbox in the map legend switches between the live schedule and the static pre-run treatment MVT without stopping the solve; counts and the legend follow the selected mode. Panning or zooming reloads the viewport and reapplies the full current schedule to the new tiles. Finishing or stopping the run returns to the static MVT treatment layer.

The shell also attaches to a run that was started outside the browser. On load or run change it checks the selected run’s status; when no explicit run was requested it scans recent search runs for a running one and selects it. The SSE stream replays the current schedule and target snapshot, so pinned charts and the map resume after a refresh or transient disconnect. A live run has no account_values.csv yet, so target charts derive their period grid and target cells from the targets document until the snapshot series arrives. Pinned target charts use the parallel targets SSE snapshots and update their achieved lines in either map mode.

The shell uses the MVT tile endpoint for the block, treatment, and cumulative layers. The vector source requests only the tiles MapLibre needs at the current zoom. Below zoom 6, treatment layers show treated block polygons; at zoom 6 and above they show every block polygon. The tile layer is named blocks and its properties carry block_id, treated, and current. Low-zoom tiles use the configured overview geometry; detail zooms use the full geometry and simplify only to the tile resolution (50 m below zoom 9, 15 m at 11-12, 5 m at 13-14, and full at 15+). The shell reads full-run counts from map-stats. Patches and compartments stay on the GeoJSON path, where the per-feature styling is richer; comparison uses a dedicated compare MVT tile.

Pre-warm and deployment checks

The durable cache can be warmed before the first browser request:

python scripts/prewarm_tiles.py \
  --dataset runtime/tsa46_full/matrix \
  --runs runtime/tsa46_full/runs \
  --geometry runtime/tsa46_full/fragments.geojson \
  --geometry-overview runtime/tsa46_full/fragments.geojson \
  --tile-cache runtime/tsa46_full/tile-cache \
  --bbox=634372,684898,1029161,1222796 \
  --zooms 0-7 --layers blocks,treatments,cumulative \
  --period-width 10 --horizon 100

The report names tiles requested, failures, bytes, seconds, and the durable-cache header counts. The command opens the app in-process with the same cache directory, so the service then serves the warm tiles from disk. Add compare to --layers and --compare-against RUN to warm the comparison tiles for a run pair; the compare cache is stored per pair and period.

The compare browser smoke needs two completed runs:

python scripts/check_compare_browser.py http://127.0.0.1:8017/ \
  --run-a baseline --run-b opening_first

It selects the pair, asserts that compare tiles are requested, and checks the A/B/both counts and the target Kind column. The compare benchmark measures the first cold tile, the full cold pass, and the warm pass:

python scripts/benchmark_compare.py http://127.0.0.1:8022/ \
  --run-a web-20261024-221127-1 --run-b web-20261025-032849-2 \
  --zoom 9 --bbox=-114.75,49.62,-114.13,50.40

It fails when the first cold or warm tile exceeds its budget. On c5 (six tiles at z9) the recorded first tile was 2.063 s cold and 0.003 s warm; the full cold pass was 13.336 s, the warm pass 0.018 s.

The path-prefix check mounts the service at /ws4 and requests the shell, its static assets, the API summary, a viewport map, and an MVT tile through the prefix:

python scripts/check_map_proxy.py \
  --dataset runtime/tsa46_full/matrix \
  --runs runtime/tsa46_full/runs \
  --geometry runtime/tsa46_full/fragments.geojson \
  --prefix /ws4

It also asserts that the shell and script use relative URLs, which is what makes a path prefix work without a rewrite rule.

The browser path has an opt-in map-hierarchy smoke. It checks the neutral fill, selected outline, on-map legend, treated-only toggle, compact unavailable layers, and the 1024, 1194, and 1500 px layouts:

python scripts/check_map_hierarchy.py http://127.0.0.1:8022/ --run run-dated3

The data panels have an opt-in smoke that needs one LiDAR service, one carbon service, and an empty service (c5 or TSA 46). It checks dataset-wide coverage, the viridis palette, the carbon axes/tooltip/labels, and the compact unavailable states:

python scripts/check_data_panels.py \
  --lidar-url http://127.0.0.1:8026/ \
  --carbon-url http://127.0.0.1:8028/ --carbon-run ws4-tsa46-gcbm-baseline \
  --empty-url http://127.0.0.1:8029/

The browser path has an opt-in smoke:

python scripts/check_map_browser.py http://127.0.0.1:8000/

It needs Playwright and a Chromium build, and it fails when the shell makes no .mvt request or reports a console error. It is not a CI gate because the browser install is heavy.

The targets path has a separate opt-in smoke. Run it against a service started with a scratch copy of the targets YAML, because it adds and then removes a target:

python scripts/check_target_browser.py http://127.0.0.1:8021/ --search CWH_HW_M

It opens the Targets tab, filters the account tree, adds a target with the first matching account, checks that the table gained a row, and removes that row when the file still has another target. The last target is left in place because the API refuses an empty targets document.

The Solve and Stop controls have a separate smoke. It needs a service started with --allow-runs and a scratch targets file, because it starts a short run:

python scripts/check_run_controls.py http://127.0.0.1:8022/

It clicks Solve with the default blank Max iters, asserts that POST /api/runs returns 200 with continuous: true and no time limit, and the button moves to Pause; it then clicks Stop. The SVG and MapLibre shells share these controls; the check guards against the regression where the click listener was only installed by the SVG map path.

The scale gate builds a synthetic point grid and times the tile path:

python scripts/benchmark_map_scale.py --fragments 1000000 --check

The check fails when a zoom-0 or zoom-12 tile is over 2 MB, the cold request is over 120 seconds, the warm request is over 5 seconds, or peak RSS is over 4096 MiB. On 2026-10-24, 1,000,000 fragments produced a 130 KB zoom-0 tile in 25.19 seconds cold and 0.018 seconds warm, a 2.8 KB zoom-12 tile in 0.034 seconds, and a peak RSS of 1,734.6 MiB. The bare block layer is sampled to at most 5,000 features below zoom 6, which is what keeps the zoom-0 tile bounded.

Geometry

The compiled dataset carries block attributes and areas but not polygons. --geometry names a GeoJSON file of block points or simplified block polygons with a block_id property; the map joins on it. Without one, the map endpoint refuses with a 409 that names the missing option rather than returning an empty map.

The browser shell renders polygons as SVG paths with their boundaries visible, so the stand mosaic is not reduced to points. The service parses the geometry once and reuses it for every layer; the response carries the polygon geometry and the source properties. A compartment property, when present, is shown in the block detail.

Prepare a simplified polygon layer from the source blocks.shp with the geo extra:

import geopandas as gpd
import pandas as pd

frame = gpd.read_file("blocks.shp")
frame["block_id"] = pd.to_numeric(frame["BLOCK"], errors="coerce").astype(int)
frame["compartment"] = frame["COMPART"].fillna("").astype(str)
frame["theme2"] = frame["THEME2"].fillna("").astype(str)
frame["theme5"] = frame["THEME5"].fillna("").astype(str)
frame["strata"] = frame["MartStrata"].fillna(-1).astype(int).astype(str)
frame["lmu"] = frame["LMU"].fillna("").astype(str)
frame = frame[["block_id", "compartment", "theme2", "theme5", "strata", "lmu", "geometry"]]
frame["geometry"] = frame.geometry.simplify(5.0, preserve_topology=True)
frame.to_file("blocks_polygons.geojson", driver="GeoJSON")

The 5 m tolerance keeps the stand boundaries while cutting the vertex count by roughly two thirds; the coordinates stay in the source projection. Pass the resulting file to --geometry. A point layer remains valid.

For a large layer, write a sidecar named <geometry>.bounds.json with a bounds array of [west, south, east, north] in the source CRS. The service uses it for the initial map fit instead of parsing every polygon. A missing or malformed sidecar falls back to the geometry itself.

--geometry-overview can point to a coarser copy of the same block layer. The vector-tile path uses it below zoom 8 and switches to the detail geometry at zoom 8 and above.

Skins

Four manifests ship: model-builder, scenario-analyst, scenario-browser and reviewer. They are served at /api/skins (and /api/skins/{id}). A manifest selects panels, layer families and actions; an unknown panel, layer or action is refused by name when the service starts, and a read-only skin may not carry a mutating action. The browser applies the manifest by hiding panels and disabling the target editor; the rule lives on the server, so a client cannot enable what the manifest does not list.

Results run health

The Results workspace opens with a run-health card above Reports, Compare, and Search. It shows the run id, kind, current period, total targets, failing count, met count, off count, pinned chart count, and whether LiDAR and Carbon artifacts are available. The failing count is styled as the first warning. Open Plan switches to the target table; Show failing targets switches to Plan and activates the failing status filter. The counts use the same target rows and realized values as the Plan summary, so a scheduler can move from results to triage with one click.

Comparison

The Compare tab reads two completed runs through the existing reader endpoints and a compare-tile endpoint. At the selected year the map colors blocks treated only in A, only in B, and in both; the vector tile carries the flag in its compare property, and the full-run counts come from compare-stats. The target table shows each target’s kind, period value and status for both runs, the ending-inventory table compares the final feature values from each run’s summary, and the account table lists the per-account delta B − A, sorted by absolute change and filterable. A target-status account is a keyboard-focusable link: activating it opens Plan and fills the target account filter with that account, ready to inspect or pin the target. The report tables appear before the map request finishes, so a large AOI does not hide them. The server computes nothing new: the target values use the same period_value rule, and a run with no values at the year is named rather than silently shown as zero everywhere.

Chat agent

The floating ✦ Ask overlay is an embedded OpenCode coding agent. It runs the installed opencode CLI with the model named by --agent-model (default opencode-go/deepseek-v4.1-flash). The CLI’s own login supplies the provider key; WS4 does not read or store it. The agent works in --agent-cwd (default: the service’s directory), so it can read the repository, run python -m ws4.cli commands, inspect a run, and edit files when asked.

ws4 serve --dataset build/compiled --runs runs --targets targets.yaml              --allow-runs --allow-agent

This is a deliberate, separate permission and is off by default. The agent runs with the service user’s filesystem and shell permissions and auto-approves its own tool calls; anyone who can reach the service can therefore ask it to change files or run commands. Keep the service on loopback (the default) or behind an authenticating proxy, and do not enable it on a shared service. The overlay keeps one OpenCode session per conversation and starts a new one with New; a session id is lost on reload, so a fresh page starts a fresh conversation. It is fixed to the lower-right, closes with its × control or Escape, and focuses the input when opened. local storage, and double-clicking the bar restores the default.

Targets

The Targets tab starts with every account the selected run reports in account_values.csv. The tree folds the account name on its . segments, and the search box filters the tree by substring, so a user can find an account without knowing its exact name. Each leaf shows the account’s last realized value, whether the optimizer treats it as a level or a flow (a product. account is a flow), and a target badge when the account already appears in the targets file. The full account name is shown; the count beside the search box reports matches over the catalogue. Enter selects the first match, and the arrow keys move between leaves.

Selecting a leaf opens a small form for a new target. Period is the accounting period (period 1 is the first one), Width is its length in years, and Min and Max are optional bounds; the form requires at least one bound. Turn on Multi-select to choose several accounts; the shared period/width/bounds form adds one target per selected account in a single validated save. Duplicate account/period targets, missing bounds, min above max, and invalid priorities are refused in the browser before the request. The table’s Target period column is the optimizer’s one-based period; the map control labels its periods by year range, so the two clocks are not confused. The table shows P1, P2, and so on for per-period rows and All for a whole-horizon row, with the ending year underneath and the full period description in the title.

The target table is a compact view of the same document. Account names are shortened to their path below the root (for example Yield · managed · Conifer), with the root shown as a small badge and the full path in the title. Units are inferred from the account name where the name is unambiguous — ha, m³, %, tC, and tCO2e — and are left blank rather than guessed. A Status column shows met, below min, above max, off, or a dash for no achieved value, and updates from live run snapshots. The achieved value stays as a secondary line under the account.

Click the On, Account, Target period, Min, Max, or Status header to sort the view. A second click reverses the direction and File order restores the YAML order. Sorting moves only the rendered rows, so unsaved edits and the original target indices are preserved; saving after a sort writes the same document order. At 1024 px the table switches to fixed compact columns so the status remains visible; the account title still carries the full path.

A summary above the table and the chart canvas puts the failing count first — 9 targets · 5 failing · 4 met · 0 off — and updates with live status chips. The filter bar combines an account substring with Failing, Met, Off, or No value; the visible/total count is always shown and Clear restores the full table. Filtering hides rows without removing them from the DOM, so unsaved inputs and the save payload are unchanged. Pin failing pins every currently visible target whose status is below or above, and Unpin visible clears the current view. Both update the watch panel and chart canvas immediately. The controls are native inputs and buttons, so keyboard order follows the visible form.

Each target has a second, compact line with Min w and Max w penalty weights, Normalization (none or auto), Priority (a positive integer tier), Kind (level, flow.even, or flow.ndy, derived from the flow setting), and Notes. Add target validates the complete list through POST /api/targets.json, writes the configured YAML, and refreshes the table. The form defaults the width to the width already used by the file, or ten years when the file is empty. The run controls — Save targets, Solve/Pause/Stop, the live detail, and the status lines — are sticky at the bottom of the sidebar, so a long targets table does not hide the controls.

The table’s Remove button deletes one target through the same endpoint. The API refuses an empty targets document, so the last target must be removed in the YAML or with Put targets; the button is disabled in that case. The account browser only changes the targets document; it does not change account values or the optimizer’s semantics.

The editor writes the document with yaml.safe_dump. It preserves each target’s notes field, but comments and the original key order are not preserved. Before replacing the file, the service copies the previous document to targets.yaml.bak. Use a version-controlled targets file and review the diff after a large edit.

Search artifacts

The Search tab lists directories under the runs root that hold a portfolio.json, tuning.json, lp_sensitivity.json, or lp.json. A portfolio shows its members, objective, declared metrics, status, failures, and which members are on the Pareto front. Selecting a member shows its factors, metrics, and safe download links for the schedule, targets, front.csv, portfolio.md, and console.log. A tuner shows its ranked candidates, best/median, failures, and parameters. An LP artifact renders target duals and option reduced costs, labelled advisory. The file endpoint resolves only paths under the artifact directory. When the service has --allow-runs, the tab also starts a portfolio or tuner through POST /api/search/portfolio or POST /api/search/tune and polls GET /api/search/{name}/status; the endpoint runs the existing scripts/portfolio.py and scripts/tune.py against the configured dataset and targets. A running job has a Stop control; the status reports stopping/stopped. The in-memory job list is bounded and drops the oldest finished entries. A read-only service shows only the artifacts.

Pareto solution space

The Pareto workspace turns a saved portfolio into an interactive point cloud. GET /api/search/{name}/space recomputes the nondominated front from every successful member, not from the capacity-limited schedule archive. Each metric is normalized to 0 = worst and 1 = best using the portfolio’s declared directions. The scalar objective is an optional dimension and is always minimized.

The view maps any dimension to X, Y, and Z, then adds colour, size, opacity, and a threshold filter. A dominance control shows all members, the exact front, or a near-front sample within a user-selected Chebyshev distance in the normalized outcome box. A near-front member is labelled as such; it is not called Pareto. Selecting a member opens its metric vector, factors, objective, and schedule download; up to three members can be pinned for comparison.

The Search tab also has a Build a weight scan helper. Add target dimensions and comma-separated factors; it writes the vary expression and warns when the Cartesian product exceeds the member cap. Dimensions may be account-level or periodic (account@period). +5 periods and +7 periods scaffold temporal scans from the selected target account without changing the target file. The portfolio launcher exposes grid or random sampling, a maximum member count, a sample seed, and process workers. Each worker loads its own dataset copy, so the launcher defaults to one worker. Portfolio scans can choose level-only targets, which writes a flow-free copy inside the run output, and can opt into the instance’s configured initial schedule. Neither option mutates the live target file.

The cloud is a finite grid sample under one search budget. It is advisory, and its normalized axes are relative to the members loaded into the current artifact.

A selected member can be opened on the map. The service promotes its run into a direct read-only run id under the runs root, hard-linking the original files when possible and writing a portfolio_source.json sidecar. The normal run map, reports, target status, and comparison endpoints then work unchanged. Two pinned members can be promoted into the existing spatial comparison view. Promotion never changes the live target file or the portfolio artifact.

The promoted run carries the member’s targets.yaml. Run target status, target series, and period width prefer that local file; the Plan editor still edits the live target file and shows a read-only notice for portfolio-member runs.

Reports

GET /api/runs/{run}/reports lists the report files a run wrote and the digests recorded by report_provenance.json (see Report provenance). The application renders a CSV in a table (first 200 rows) and opens HTML/PNG reports directly. The Reports tab groups the named standard reports when present — account summary, target status, route cost (overall and per destination), patch accounts and metrics, spread metrics, edge contrast, the road network, the schedule and the ending inventory — and keeps the full file list below them. A provenance badge names the sidecar’s uncertainty status and links to the sidecar and its source metadata files. The ending-inventory card shows the final feature values and year from summary.json, plus any flow-target status. Nothing is recomputed in the browser.

Runs written before the current clock schema carry year in account_values.csv and period in schedule.csv. The shared run-table reader adds an offset alias for either column and keeps the existing year label, so the Accounts, Periods, Targets, and Map endpoints open the legacy run instead of returning a 500. The files are not rewritten.

The Build a report form selects accounts (comma-separated, or blank for all) and a year range from the run’s own account_values.csv, renders the rows, and exports the same rows as a CSV download. A target’s On checkbox is written through the same save as the bounds: an inactive target stays in the YAML, is shown as inactive in the target report, and is not priced. The target table and watched cards use the same active flag.

C5 base scenario

The c5 sample carries one browsable baseline run and one documented scenario. The scenario examples/c5_base/targets.yaml covers 20 periods of 10 years (periods 1–20), sets a 1,000,000 per-period harvest floor on product.total.Yield, adds an even-flow band of ±1% against the final-period reference, and requires feature.total.Yield in the final period to stay at or above 23,900,770.58 — 90% of the 26,556,411.75 initial growing stock. The same file is installed at scenarios/c5-base/targets.yaml in the sample. The README beside it gives the optimize command and the scripts/max_flow.py probe command for a higher advisory ceiling.

Front end

The browser application and the four skin manifests (model builder, scenario analyst, scenario browser, reviewer) are specified in notes/design/ws4-web-frontend.md. A skin is a JSON manifest over one application, checked against a registry; an unknown panel, layer or action is refused by name, and a read-only skin cannot edit a target.

Condition-card panel

The Reports tab includes a Load condition card button. It calls GET /api/runs/{run}/condition-card and renders the review status, indicators, applicability, and advisory alerts. The browser uses text nodes, not HTML interpolation. The card is report-only; a missing or invalid account table is reported in the panel without changing the run.

The condition-card table also shows the uncertainty field and a provenance block. Missing uncertainty is shown as “not stated”; every value is rendered as a text node. These fields make the card reviewable without turning it into an operational alert.