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.v1package 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-consoleis set. See Run an allowlisted command.SDMD — the AU Explorer: BC coverage selector, yield, stand density, regimes, and the constraint editor, when
--sdmd-diris 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 |
|---|---|
|
The dataset manifest, |
|
The run’s |
|
Rows of the run’s |
|
A review-required |
|
The dataset’s registered FEMIC LiDAR pin, licence, CRS, products, and canonical
|
|
Carbon provenance, |
|
DHI source metadata, band names, and normalized block values. |
|
The run’s report files, their sizes, the |
|
One report file; a name the run does not hold is a 404. |
|
A GeoJSON |
|
One Mapbox Vector Tile for |
|
The configured geometry’s extent as |
|
The full-run A-only, B-only, both, and neither counts for two runs, without reading geometry. |
|
One MVT tile whose |
|
The full-run |
|
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. |
|
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 ( |
|
The route model’s used segments for one year as GeoJSON |
|
The configured source access-road lines as a GeoJSON |
|
The targets YAML as written. |
|
Validate with the optimizer’s loader and replace the YAML; an invalid document is refused and the file is left unchanged. |
|
The parsed targets as JSON, for an editor that does not parse YAML. |
|
The named profiles from the optional |
|
One resolved profile, including its target path, accounts, and schedule output. |
|
Validate the profile’s target file and replace the configured targets YAML. The service
must have an editable |
|
Each target’s realized value over the target’s own period — the optimizer’s
|
|
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. |
|
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 |
|
|
|
SSE: coalesced |
|
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_widthand 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 sourceCOMPARTbase 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 byGET /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 withoutspread_membership.csvlikewise 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.