Sense 52 — The Cartography
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
Sense 52 · In bloom · Last touched 2026-08-20
- last_verified: 2026-07-27
Synced from
docs/design/sense_52_the_cartography.mdin the engine repo — that’s the source; this page is a build-time mirror.
Status: proposal · 2026-07-09 Author: claude (Opus 4.7) with Mig Working title alternatives: The Terrain, The Atlas Sense number: 52 (Sense 51 The Skill claimed on origin/main; 52 verified free)
The one-line pitch
Section titled “The one-line pitch”Declarative geographic maps as first-class JinDesk artifacts: entities plotted at their real-world coordinates on a real base map, with switchable layers, per-point rich content, and a 3D path forward.
Not “Map Salon” — that already exists as a generic visual-encoding room ([[project_studio_lab_salon]]). Cartography is the real map: latitude, longitude, altitude, tile layers, projections, geodesic distance. When delta’s field team looks at delta.jinflow.io they should see their sensors where they actually are, not a scatter plot pretending to be a map.
Why now
Section titled “Why now”Two things converged on 2026-07-09:
- Riverflow shipped with lat/lon/altitude already in the Gold contract.
gold_deployment_sitescarriescoordinates_lat DECIMAL(10,6),coordinates_lon DECIMAL(10,6),altitude_m INTEGER. Verified on delta today: SITE_A at 46.812°N, 7.712°E, 1820m. Real Alpine coordinates in synthetic data. The forcing function. - Sense 15 Observations landed in delta today. Chantal’s cattle-crossing observation names three sites and asks “why these three?” — the natural answer is geographic proximity to summer transhumance routes. That answer is illegible on a scatter plot. It becomes obvious on a map with the pastoral routes as an overlay layer.
Without a real map surface, delta’s geospatial data goes uninterpreted and its Sense 15 observations lose half their explanatory power.
The three moves the reader wants
Section titled “The three moves the reader wants”Sense 15 gave the CEO conversation three moves (“What? / Is it real? / Why?”). Cartography gives the field team three moves:
- “Where?” — plot the entity at its actual location on a base map the reader recognises.
- “What’s there?” — hover/click reveals rich per-point content: current state, recent readings, active alarms, signed observations.
- “What’s happening there?” — data-driven styling: colour by severity, size by intensity, animate over time.
Any map interface that answers only one of the three is a scatter plot. Any map that answers all three is Cartography.
Structural claim — peer of Canvas, cascade-aware
Section titled “Structural claim — peer of Canvas, cascade-aware”Two foundational relationships anchor Sense 52 in the existing substrate. Naming them here so the shape of what we’re building is unambiguous before we get to data or code.
Sense 13 (Canvas) — peer artifact, not extension
Section titled “Sense 13 (Canvas) — peer artifact, not extension”Sense 13 established the author-time artifact discipline: YAML
→ validate → compile → bake into a _<tenant>.<kind>_registry
table → render through a Svelte component that reads the bake.
Tiles, panels, and pages all follow this shape. Maps follow the
same shape exactly.
Maps are a peer of tiles/panels/pages, not a sub-element of them. The tile→panel→page hierarchy composes: a page is made of panels, a panel is made of tiles. A map is not made of smaller maps. A map does not go inside a tile, a panel, or a page. It sits alongside the hierarchy as its own artifact class, inheriting the same author-time discipline. Concretely:
| Sense 13 element | Sense 52 counterpart |
|---|---|
tiles/*.yaml | maps/*.yaml |
scripts/tilecheck.py | scripts/mapcheck.py |
scripts/tilecompile.py | scripts/mapcompile.py |
_<tenant>.tile_registry | _<tenant>.map_registry |
<MetricTile> Svelte renderer | <CartographyMap> Svelte renderer |
/{tenant}/tiles/{tile_id} | /{tenant}/maps/{map_id} |
Authors already fluent in panel/page authoring are 90 % of the
way to authoring maps because the YAML conventions are
deliberately parallel — same display_name, description,
scope, tags, same locale-substitution rules. This is the
structural inheritance the Sense makes.
Sense 43 (The Cascade) — map defaults resolve through L0..L3
Section titled “Sense 43 (The Cascade) — map defaults resolve through L0..L3”Map defaults (base layer choice, tile source keys, viewport
padding, opacity of overlay styles) resolve through the same
Sense 43 cascade every other display config uses. Concretely,
under a display.cartography.* namespace:
L0 engine fallback → { default_base_layer: "streets", padding_px: 40 }L1 pack default → riverflow prefers "topo"; interlogic prefers "streets"; alptrack prefers "topo" as wellL2 tenant override → delta.jinflow.io picks "satellite" as its audience-facing defaultL3 map YAML override → a specific map declares its own `default_base_layer: "topo"` for a watershed-focused viewdisplay.cartography.mapbox_token, display.cartography.google_token
follow the same cascade — silently hidden from the base-layer
switcher when unset, promoted to first-class options when the
key resolves.
The cascade is load-bearing for the base-layer story. Without it, either every pack ships every base layer (visual noise) or the choice is hard-coded per pack (breaks the declarative posture).
Data prerequisites
Section titled “Data prerequisites”Every entity that participates in a map declares its geometry in its Gold contract. Three geometry kinds are canonical:
| Kind | Columns | Storage | Example entities |
|---|---|---|---|
| Point | coordinates_lat DECIMAL(10,6), coordinates_lon DECIMAL(10,6), optionally altitude_m INTEGER | Native columns | DeploymentSite, Building, Hospital, Warehouse, Vineyard, PickupLocation |
| Polyline | geometry_geojson VARCHAR containing a GeoJSON LineString, OR inferred from ordered child points | Column or derived | Reach (river segment), Route (freight), Ski run, Pipeline |
| Polygon | geometry_geojson VARCHAR containing a GeoJSON Polygon/MultiPolygon | Column | Watershed, Field, Vineyard block, Delivery zone, Administrative area |
The preferred representation is GeoJSON in a single VARCHAR column (geometry_geojson) — human-readable, universally supported by mapping libraries, no extra compilation step. For entities where geometry is derivable (a Reach’s polyline is its sites in ordinal order), a geometry: inferred_from(...) clause in the map YAML skips the column requirement.
Riverflow status today:
- DeploymentSite → Point ✅ (lat/lon/altitude present)
- Reach → Polyline via inference (walk sites by
ordinal) - Watershed → Polygon ⚠️ (only
area_km2, no boundary). V1 renders reach envelopes as a fallback; V2 adds a proper boundary column.
Cross-pack readiness (2026-07-09):
- alptrack → ski slopes (polyline), lift stations (point), snowmaking zones (polygon) — all data candidates exist but not typed as geometry yet
- hrcentral → buildings/clinics (point) — VAI has org_units but no coordinates today
- interlogic → warehouses (point), routes (polyline), delivery zones (polygon) — perfect fit
- numetrix → hospitals (point in city) — low geo value; not a priority
- millesime → parcels (polygon), cellars (point) — beautiful fit if data added
- riverflow → the driver
Contract change is small and additive: any pack that wants map participation adds coordinates_lat/lon/altitude and/or geometry_geojson columns to its Gold contract. Zero cost to packs that don’t.
The declarative shape
Section titled “The declarative shape”Maps live in afs/maps/*.yaml. Compiled into KLS as _<tenant>.map_registry alongside other artifacts. JinDesk route: /{tenant}/maps (list) + /{tenant}/maps/{map_id} (detail).
Full annotated example
Section titled “Full annotated example”map_id: map_delta_field_networkkind: map # required — first-class typeversion: 0.1.0created_at: 2026-07-09modified_at: 2026-07-09
display_name: en: Field sensor network de: Feldsensor-Netzwerk fr: Réseau de capteurs terrain it: Rete di sensori sul campo
description: en: | All delta sensors plotted at their deployment coordinates. Click a site for readings, alarms, and any signed observations at that location. de: | Alle delta-Sensoren an ihren Einsatzkoordinaten. Klicken Sie auf einen Standort für Messwerte, Alarme und signierte Beobachtungen. # ... fr, it
scope: tenant_id: delta
# ─── Initial camera position ─────────────────────────────initial_view: fit_bounds: sensor_sites # auto-fit to a named layer # or: # center: [46.5, 7.7] # explicit lat/lon # zoom: 10 # pitch: 0 # 3D tilt (0 = top-down) # bearing: 0 # rotation padding: 40 # px around fit_bounds
# ─── Base layer options — user toggles at runtime ────────base_layers: - id: streets label: { en: Streets, de: Strassen, fr: Rues, it: Strade } style: openstreetmap default: true attribution: "© OpenStreetMap contributors"
- id: topo label: { en: Topographic, de: Topografie, fr: Topographique, it: Topografico } style: opentopomap attribution: "Map data © OpenStreetMap contributors, SRTM · style © OpenTopoMap"
- id: satellite label: { en: Satellite, de: Satellit, fr: Satellite, it: Satellite } style: esri_world_imagery attribution: "Esri, Maxar, Earthstar Geographics"
- id: mapbox_outdoors label: { en: Mapbox Outdoors, ... } style: "mapbox://styles/mapbox/outdoors-v12" requires_key: mapbox # config engine resolves; silently hidden if unset
# future: google, custom tile URLs
# ─── Data layers stack — user toggles each independently ──layers: - id: watersheds label: { en: Watershed boundaries, ... } source: entity: Watershed geometry: boundary_geojson # column reference style: type: fill fill_color: "#8ec5fc" fill_opacity: 0.15 stroke_color: "#4c8bff" stroke_width: 2 default_visible: true
- id: reaches label: { en: River reaches, ... } source: entity: Reach geometry: inferred_from: child_entity: DeploymentSite child_geometry: point order_by: ordinal style: type: line stroke_color: "#0369a1" stroke_width: 2.5 default_visible: true
- id: sensor_sites label: { en: Sensor sites, ... } source: entity: DeploymentSite coords: lat: coordinates_lat lon: coordinates_lon altitude: altitude_m # optional; drives 3D extrusion marker: type: circle # or icon, symbol size: 8 color: # Data-driven: query signal_findings for this entity from_signal: signal_id: signal_calibration_drift value_field: severity scale: high: "#ef4444" medium: "#eab308" low: "#84cc16" none: "#94a3b8" default: "#94a3b8" popup: title: "{{name}}" body_template: | {{site_id}} · {{altitude_m}} m Reach: {{reach_name}} Watershed: {{watershed_name}} Active sensors: {{sensor_count}} lang_locale: true # {{name}} auto-picks name_de/en/fr/it click_action: href: "/{tenant}/dimensions/deployment_sites/{{site_id}}" new_tab: false default_visible: true
# ─── 3D roadmap ──────────────────────────────────────────three_d: enabled: false # opt-in per map (V2) terrain: source: mapbox-dem # or maptiler-terrain exaggeration: 1.5 # dramatize the vertical extrude: point_layers: [sensor_sites] # markers extrude to altitude height_scale: 1.0
# ─── Access + audience metadata ──────────────────────────audience: [field, science, executive] # nav visibility hintstags: [riverflow, delta, field_ops, sense_52_seed]YAML shape notes
Section titled “YAML shape notes”- Familiarity by design: mirrors Panel / Lens / Perspective YAML conventions — same
display_name,description,scope,tagsfields. New authors trained on Panels write Maps without new grammar. - Declarative styling: the
marker.color.from_signalblock queries the signal at runtime. Same pattern that Lenses use for severity mapping — reuses the resolver code. {{template}}fields: reuse the same Handlebars-lite renderer as Panel popups. No new template engine.- Locale substitution:
{{name}}picksname_de/name_en/name_fr/name_itbased on the viewer’s locale, matching JinDesk’s existing i18n.
Library choice: MapLibre GL JS
Section titled “Library choice: MapLibre GL JS”Recommendation: MapLibre GL JS — the open-source fork of Mapbox GL, WebGL-native, no API key required for OSM-based tiles, supports 3D terrain and extrusions natively.
Why MapLibre over alternatives:
| Library | 3D | Vector tiles | API key needed | Bundle size | Verdict |
|---|---|---|---|---|---|
| MapLibre GL | ✅ native terrain, extrusions | ✅ | ❌ (uses OSM freely) | ~500 KB gz | Pick this |
| Mapbox GL | ✅ | ✅ | ✅ paid at scale | ~500 KB | Wraps in vendor lock-in |
| Leaflet | ❌ (2D only) | 🟡 via plugin | ❌ | ~40 KB | Great but caps at 2D |
| OpenLayers | 🟡 limited | ✅ | ❌ | ~250 KB | Overkill for our shape |
| CesiumJS | ✅ full globe | ✅ | 🟡 (assets) | ~4 MB | Beautiful but heavy |
MapLibre wins on: no lock-in, native 3D for the altitude story, free tiles, mature ecosystem (Mapbox v1 fork with active dev), first-class TypeScript.
Fallback path: If MapLibre proves too heavy for JinDesk’s bundle-size target, Leaflet 2D-only is a graceful fallback. The YAML shape stays identical; only the renderer swaps. three_d.enabled becomes a no-op with a “3D requires MapLibre” hint.
Rollout phases
Section titled “Rollout phases”V1 — 2D map with points, inferred polylines, data-driven markers ✅ SHIPPED 2026-07-10..11
Section titled “V1 — 2D map with points, inferred polylines, data-driven markers ✅ SHIPPED 2026-07-10..11”Shipped:
mapcompile.py— validate + compileafs/maps/*.yaml→ KLS_<tenant>.map_registrymapcheck.py— validator with clear error messages- JinDesk routes
/{tenant}/maps+/{tenant}/maps/{map_id} - MapLibre GL renderer with 3 base layers (OSM, OpenTopoMap, Esri Imagery)
- Point markers with data-driven color from signal severity
- Reach polylines inferred from site ordinal
- Popup with title + body_template + click_action
- Five graceful loader states — never a bare 404 (
ok/not_found/no_maps/malformed/load_error) - SSR-safe lifecycle (types split, browser guards in Svelte hooks)
- Config engine keys:
cartography.default_base_layer,cartography.mapbox_token(optional),cartography.google_token(optional)
Riverflow deliverable ✅: map_delta_field_network.yaml in delta AFS, live on delta.jinflow.io — 31 real Alpine sensor sites plot on the topographic base with reach polylines + popup click-through.
V1.1 — Signal-adjacent map annotations (2026-07-11 spec)
Section titled “V1.1 — Signal-adjacent map annotations (2026-07-11 spec)”The riverflow reshape (Three-family Reading contract + Calibration + MaintenanceEvent facts, sister-9’s W-track through 2026-07-10) opened three specific map surfaces that V1’s “entity + coords” layer shape can’t quite express. V1.1 adds three composable capabilities so the map YAML can paint them.
The three ideas driving this — named by sister-9:
- Datastreams with
is_active=false— channel gaps rendered as grey-dashed pins at their sites rather than absence - MaintenanceEvents with
event_type=fouling_cleared— event pins that fade with age (recent solid, old ghosted) - EnvironmentalVariables with
uncertainty_source=fouling— bad data on the map, not just marker-severity paint
Each maps to a specific composition of the three new capabilities. None of these need geometry beyond points — the reason V1.1 is distinct from V2 (which needs polygons for watersheds and terrain for 3D altitude).
Cap A — Fact layers via join
Section titled “Cap A — Fact layers via join”The gap V1 has: a layer’s source.entity must currently be a
Gold entity that carries coordinates_lat / coordinates_lon
columns directly. But MaintenanceEvent, Datastream, and
EnvironmentalVariable are fact tables — they carry
site_id / sensor_id foreign keys but no coords of their own.
The addition: a layer’s source can declare a join block
that resolves geometry via a coord-carrying entity. Kept inside
the existing source: block so V1 authors read one vocabulary,
not two — sister-9 and sister-7 aligned on this 2026-07-11.
# V1.1 — MaintenanceEvent fact layer- id: fouling_events source: entity: MaintenanceEvent join: to: DeploymentSite on: site_id # left-side FK on the source entity to_field: site_id # right-side PK on the joined entity # (defaults to `id` or `<entity>_id`) coords: lat: coordinates_lat # column lives on the joined entity lon: coordinates_lon # ...marker, popup, click_action as V1The loader materialises this as SELECT fact.*, site.lat, site.lon FROM fact_table JOIN site_table ON fact.<on> = site.<to_field>.
Each row still becomes one point, but the point’s properties
carry every column from the fact table — so popup templates can
reference {{event_type}}, {{cleared_at}}, etc.
Same shape covers the silent-sensors case (signal_datastream_inactive
findings key by sensor_id; Sensor gains current_site_id on
sister-9’s side; one-hop Sensor JOIN DeploymentSite gets coords).
NULL discipline: current_site_id IS NULL for in-stock /
decommissioned / lost sensors, WHERE lat IS NOT NULL AND lon IS NOT NULL
already filters those out. Correct behavior on both sides confirmed.
Cap B — Temporal opacity fade
Section titled “Cap B — Temporal opacity fade”The gap V1 has: markers have one color and one opacity. Fine for signal-severity paint. Not fine for “this maintenance event happened three weeks ago” where age matters.
The addition: marker.opacity can be a declaration instead of
a static number.
marker: type: circle size: 8 color: "#0891b2" opacity: from_timestamp: cleared_at decay: P30D # linear fade to 0 over 30 days minimum: 0.15 # never fully invisible — keeps historical events discoverableRenderer computes opacity = clamp(1 - (now - timestamp)/decay, minimum, 1).
Feature-level, not layer-level — each row’s opacity depends on
its own timestamp.
Cap C — Dropped 2026-07-11
Section titled “Cap C — Dropped 2026-07-11”The initial draft proposed a third capability, marker.style.from_field,
so a Datastream’s is_active=false could paint as grey-dashed via
a boolean field mapping. Dropped after conversation with sister-9
- Mig:
- The substrate discipline is “everything paints through signals.”
Sister-9 authored
signal_datastream_inactive(severity by hours- idle) andsignal_site_fouling_burden(severity by ratio) instead of exposing a bespoke state-mapping shape. - With those two signals in place, the Datastream and
EnvironmentalVariable uncertainty stories render through the
existing V1 signal-severity paint code path — same as
signal_calibration_drifttoday. - Cap C was a special-case shortcut that violated the “always through signals” grammar. Cleaner to keep the substrate honest.
Mig pushed against a sister-9 “gold_site_quality_snapshot helper” in a parallel conversation for the same reason — the substrate speaks signals, not bespoke aggregates. The Cap C drop is the same principle applied on the map-YAML side.
V1.1 = Cap A + Cap B only. Cleaner, less to build, no substrate compromise.
The two ideas as compositions
Section titled “The two ideas as compositions”Each of sister-9’s demos is one YAML file composing these capabilities:
| Idea | Capabilities | Layer shape |
|---|---|---|
| MaintenanceEvent fading pins | A + B | Fact layer over MaintenanceEvent × DeploymentSite, marker.opacity.from_timestamp: cleared_at |
| Silent sensors | A + V1 severity paint | Fact layer over Sensor × DeploymentSite (via current_site_id), marker.color.from_signal: signal_datastream_inactive |
| Site fouling burden | V1 severity paint | Plain V1 point layer over DeploymentSite, marker.color.from_signal: signal_site_fouling_burden |
Implementation surface — V1.1
Section titled “Implementation surface — V1.1”| Path | Change |
|---|---|
scripts/mapcheck.py | Validate: source.join.{to, on, to_field}, marker.opacity.{from_timestamp, decay, minimum} shapes |
scripts/mapcompile.py | No change — the whole map YAML round-trips through config_json already; new fields land automatically |
tests/test_mapcheck.py | New cases for the two additions |
explorer/src/lib/server/queries/maps.ts | Extend MapConfig types to carry the new optional fields |
explorer/src/routes/[tenant]/maps/[map_id]/+page.server.ts | Layer loader gains a JOIN branch when source.join is set; materialises fact rows carrying the joined coords |
explorer/src/lib/cartography/renderer.ts | Marker paint reads opacity declaration; new helper resolveOpacity(row, decl) |
| Delta AFS | Real map_delta_maintenance_pulse.yaml composing the two capabilities against sister-9’s confirmed column shapes. Verification target once her rebuild pings. |
Not shipping in V1.1
Section titled “Not shipping in V1.1”Explicitly held for later — same discipline as V1 scope:
- Polygon geometry (that’s V2 watershed contract)
- 3D extrusion (that’s V2 terrain)
- Overlay tile layers with independent opacity (that’s V1.2 or V2 — TBD)
- Time-scrubber / animation (V3)
- Any new base-layer preset
Data-side asks for sister-9
Section titled “Data-side asks for sister-9”Coordinated on sister7_sister9_conversations.md under the
“V1.1 conversation” section — the three specific column shapes
that need to be present on MaintenanceEvent, Datastream,
and EnvironmentalVariable for the three demos to render live
on delta.
V2 — Watershed polygons (2026-07-11 spec)
Section titled “V2 — Watershed polygons (2026-07-11 spec)”The third geometry primitive after V1’s points and inferred polylines. V2 adds the ability to render real polygon boundaries — watersheds tinted by aggregate signal severity, deployment sites drawn as their real footprint rather than a lat/lon dot, administrative boundaries as context layers. The spec is deliberately narrower than the original stub: 3D altitude extrusion and terrain rendering earn their own phase (V3) because they need a DEM-source decision, a camera-UX pass, and performance testing that shouldn’t share a session with the polygon substrate work.
The one-line pitch: every entity that carries a geometry.polygon-typed column renders as a fill layer; every fill layer can be tinted by signal severity the same way V1’s point markers can.
- Data model.
boundary_geojson(geometry.polygon) added to theWatershedentity contract. Ships as aVARCHARcolumn storing an RFC 7946 GeoJSON geometry object (not a full Feature — the renderer adds the Feature wrapper with the row’s other columns as properties). CRS is WGS 84. Nullable — packs that don’t have polygon data for a watershed row get skipped by the fill layer without breaking the map. - Typology binding. The seventh Typology kind (
geometry, per Sense 54’s expansion) with thepolygonandmultipolygonsubkinds available. Theboundary_geojsoncolumn declareskind: geometry, subkind: polygon, standard: rfc_7946_geojson, crs: wgs84. The Codex’srfc_7946_geojsonstandard’sbinding_kindsmoves from[]to[geometry].typologycheck.pyvalidates that any column declaredgeometry.polygonbinds eitherrfc_7946_geojsonor another future geometry-serialization standard. - YAML shape — the fill layer. New
style.type: fillaccepted on a data layer.source.geometrynames the column carrying the GeoJSON string. Static paint viastyle.fill_color, dynamic paint viastyle.fill_color.from_signal(mirroring V1’smarker.color.from_signalshape — the mechanism is layer-agnostic, so it stops being a marker-only concern in V2). Optional stroke viastyle.stroke_color/style.stroke_width, likewise supportingfrom_signal. Opacity as a static number (V2 does not extend Cap B’s temporal fade to fills; that stays a point-marker facility for now). - Renderer. New
addFillLayerinexplorer/src/lib/cartography/renderer.ts. Parses the GeoJSON string per row into the geometry object; wraps as a Feature with the row’s columns as properties; assembles a FeatureCollection; adds MapLibrefilland (ifstroke_*set)linelayers. Data-driven paint uses the same['get', '__color']/['get', '__severity']pattern V1 established for points — the renderer’s severity-resolution helper stays where it is, only the paint spec changes. - Base-layer switcher — custom tile URLs. V1’s switcher accepts a fixed enumeration (
openstreetmap,opentopomap,esri_world_imagery). V2 addsstyle: custom_tile_urlwith aurl:field carrying the tile-template URL, letting packs and tenants bring their own tile providers (Swisstopo, BAFU, USGS, Mapbox Outdoors under a paid key, tenant-hosted MBTiles) without an engine change.attribution:remains required. - Layer legend + attribution panel. Small piece of chrome the map has needed since V1: a legend showing each visible layer’s label and colour swatch (for severity-scaled layers, the scale is expanded), and a collapsible attribution strip reading from each declared layer’s
attributionfield. Docked to the map’s bottom-right by default; position is adisplay.layout.map_legendconfig-engine key (Sense 43 cascade).
Doesn’t ship in V2 (deferred to V3)
Section titled “Doesn’t ship in V2 (deferred to V3)”- 3D + terrain. MapLibre terrain source, DEM tile provider,
three_d.enabledYAML block, altitude-bar fill-extrusion, pitched camera controls, terrain-aware fly-to. Real work; earns its own phase. - Fill temporal fade. Cap B on polygons — a watershed that fades with time since its last-verified survey date, for example. Legitimate use case, but the two-layer-type coordination isn’t V2’s job; revisit if it comes up.
- Polyline severity paint. A gap V1 left open — polylines take
stroke_coloras a static value only. V2 could close this by extendingfrom_signaltostyle.stroke_color, which is a small change if we’re already adding it to fills. I’d bundle this into V2’s renderer diff on that logic. Confirmed: bundled. - Fill-based click actions. V1’s
click_actionblock works for points; V2’s fills support it identically (the renderer wires the same handler onto the fill layer). Not a deferral — landing under “ships” — but worth explicit call-out because customers will ask.
Data prerequisites (sister-9’s territory)
Section titled “Data prerequisites (sister-9’s territory)”Sister-9 needs to land three things on claude/9th before V2’s renderer work can be verified end-to-end on delta:
boundary_geojson VARCHARonWatershedincontracts/gold_contract.v1.json.- Backfill delta’s watersheds (
WS_DELTA, and any siblings — Simme, Meridian, Cascade per prior conversation) with real Swiss BAFU (or OSM-derived) polygons. Format: GeoJSON geometry object serialized as a single-line VARCHAR string. rfc_7946_geojson.binding_kinds: [geometry](was[]per the V1 stub decision that deferred it).
Sister-7 lands the renderer, column_types: block on Watersheds, Sense 52 V2 spec (this section), Sense 54 seventh-kind expansion, and the delta test map (map_delta_watershed_severity.yaml) that consumes the substrate. Order-independent within a merge cycle — either side can be first as long as both land before the map compiles.
Riverflow deliverable
Section titled “Riverflow deliverable”map_delta_watershed_severity.yaml — a second declared map on delta whose primary layer is fill polygons per watershed tinted by an aggregate signal (signal_site_fouling_burden or signal_datastream_inactive rolled up per basin — sister-9’s call which is the right aggregation grain). Same three-layer discipline as map_delta_maintenance_pulse.yaml from V1.1: base layers, reach polylines, watershed fill polygons. If the fill layer renders on delta with real Swiss geography and correct per-basin severity paint, V2 is proven.
V3 — 3D altitude extrusion + terrain
Section titled “V3 — 3D altitude extrusion + terrain”Ships:
- MapLibre
raster-demterrain source with hillshading - DEM tile provider selection (BAFU 10m for Swiss tenants, open Amazon Terrain Tiles for global fallback, paid Maptiler as a
requires_key-gated option) three_d.enabledYAML block with terrain toggle + camera pitch/bearing/exaggeration parameters- Fill-extrusion for altitude-bar points (small polygon buffer per site, extruded to
altitude_m) - Terrain-aware
fly_tobehaviour on click-actions from other JinDesk surfaces - Performance guardrails: WebGL feature-detect + fallback to 2D for machines that can’t handle the pitched terrain scene
Riverflow deliverable: map_delta_field_network_3d.yaml, a second declared map with three_d.enabled: true showing the delta watershed as a real terrain scene with sensor altitude bars.
V4 — Multi-tenant + specialized layer types
Section titled “V4 — Multi-tenant + specialized layer types”Ships:
- Heatmap layer type (density from a source entity or reading table)
- Choropleth layer type (color polygons by aggregate — arguably subsumed by V2’s fill +
from_signalif the fill’s source is already an aggregate; revisit whether V4 needs a separate primitive or just docs) - Time-scrubber for animated layers (readings over time)
- Cross-tenant map (Steward pattern from Sense 24): compare deployments across multiple riverflow tenants on one map
- hrcentral adoption: buildings/clinics as points; the “which faculties are where” map
- interlogic adoption: freight routes as polylines; the “in-transit right now” map
Watershed-specific concerns (Riverflow)
Section titled “Watershed-specific concerns (Riverflow)”Beyond the generalization, riverflow drives some specific design decisions:
-
Flow direction on reaches — arrows on the polyline pointing downstream. Compiled from
upstream_reach_id/downstream_reach_idon Gold. Optional layer, small but signature-worthy for river maps. -
Elevation cross-section — click a reach and get a side-panel showing altitude profile (upstream → downstream, with sensor positions marked). Uses
altitude_mfrom sites along the reach. Distinguishes riverflow from generic point maps. -
Snowmelt overlay (future) — when delta ships snow-line data or SWE (snow water equivalent) grids, add a raster overlay layer. Not V1.
-
Trout-spawning stretch highlight — Leila’s Sense 15 observation names DS-007 through DS-011 as the reach where the October DO dip happens. If a pack lets its observation renderer opt into a “show on map” affordance, her observation gets a click-through that highlights the stretch on this map. This is not a Sense-level integration between 52 and 15 — it’s a specific rendering choice a pack makes for a specific observation shape. A pack could equally choose to render the same observation as a timeline marker or a table row; the observation is legible without any of those. The Sense 15 observation contract is untouched by Sense 52. Named here only because riverflow is likely to want it.
-
Cattle crossing overlay — Chantal’s observation would be a static overlay layer showing the transhumance routes. Sourced from a
overlays/cattle_transhumance.geojsonfile in the tenant AFS. Not from Gold; from the tenant’s own domain knowledge base.
Known Sense-level gaps (not this Sense’s job to solve)
Section titled “Known Sense-level gaps (not this Sense’s job to solve)”Some things this doc should not try to solve are worth naming here so they don’t fall through the cracks — they’re substrate-wide concerns that Sense 52 inherits from the declarative-artifact family.
Discovery — where does the user find the maps? V1 gives us
/{tenant}/maps (list) + /{tenant}/maps/{map_id} (detail),
but nothing about how the user knows the maps exist in the
first place. This is the same problem tiles / panels / pages
already have — the substrate now has five artifact types (tile,
panel, page, note, map) all reachable only by URL. Discovery
is now a Sense-level topic, not a per-artifact one. Named in
Sense 13’s V3.1 conversation queue for the wider treatment
(sidebar? per-tenant nav? global search? per-artifact index
routes?). Sense 52 ships without discovery in V1 the same way
tiles / panels / pages did — inherits whatever decision the
substrate-wide conversation lands on.
Authoring lifecycle — Lab vs published. When a consultant wants to ship a per-engagement map without committing to the tenant AFS, where does it live? Same problem tiles have, same answer: waits for the substrate-wide policy. Not a Sense 52 concern.
Cross-tenant browsing (Sense 24 Steward pattern). V3 lists this as a rollout item (“compare deployments across multiple riverflow tenants on one map”). The Sense 24 pattern is the substrate; Sense 52 consumes it when V3 lands. Not something Sense 52 designs from scratch.
Open questions
Section titled “Open questions”-
Sense number check — verified 52 is free on origin/main today. If a sister claims 52 before this doc lands, renumber and don’t fight the collision ([[feedback_check_origin_before_claiming_sense_number]]). Re-verify before code lands.
-
geometry_geojsonvs. dedicated columns — should polygons/polylines be stored as opaque GeoJSON strings, or should we design a proper geometry type? GeoJSON string is simple and universal; a proper type unlocks GeoSPARQL / PostGIS-style spatial queries later. V1 recommendation: GeoJSON string, revisit for V2 if spatial queries prove valuable. -
Bundle size — MapLibre is ~500 KB gzipped. That’s significant for tenants that don’t use maps. Should the Cartography renderer be lazy-loaded (dynamic import when the /maps route is hit)? Recommended: yes. First
/mapsvisit incurs the cost; other routes stay slim. -
Offline / air-gapped tenants — some tenants may run without internet (P2P2P scenario, Sense 16). What happens to the map with no tile server? V1 answer: shows a “map unavailable” fallback and lists sites by lat/lon in text form. V2: allow tenants to bundle their own MBTiles / vector tile pack in the AFS for full offline operation.
-
type: mapcells inkind: reportnotebooks (future). If ametriccell in a report note can carry asignal_idand inherit provenance, can a cell betype: mapand reference an existingmap_id? A trace note prose above, a rendered map below. Attractive shape — a note like “why these three sites?” would gain enormous legibility. Not V1. Add to the note cell type registry when maps ship and a real driver names the observation-plus-map pattern. Same posture as V3 pages: build the substrate first, wire the composition once the primitives are stable.
What we’re NOT doing
Section titled “What we’re NOT doing”- Not replacing Map Salon. Map Salon stays as the generic visual-encoding room. Cartography is the geographic-specific tool. Users don’t choose between them — they use whichever fits the question.
- Not shipping a globe. Local-region 2D → 3D. If someone wants the full CesiumJS globe experience later, that’s Sense 5X (Sense 53? The Globe?), not this doc.
- Not vending Google as a first-class base layer in V1. Google Maps requires a paid API + terms of service review + billing setup. Ship OSM + OpenTopoMap + Esri Imagery in V1 (all free); add Google via a
requires_keygate in V2. - Not baking coordinates into every pack. Zero cost for packs that don’t want maps. Coordinates are opt-in per Gold entity per pack.
Cross-references
Section titled “Cross-references”Ordered by structural weight. The distinction between foundational cross-refs and tactical / example cross-refs matters — bloating this section with every Sense that Cartography could touch weakens the doc’s structural claim (this Sense’s place in the substrate).
Foundational (Sense 52 is only possible because these exist):
- [[project_sense13_the_canvas]] — Sense 52 inherits Sense 13’s author-time artifact discipline (YAML → validate → compile → bake → render). Maps are peer artifacts alongside tile/panel/page, not sub-elements. See “Structural claim” above.
- [[project_sense_43_the_cascade]] — map defaults resolve through the same L0..L3 cascade as every other display config. Load-bearing for the base-layer story. See “Structural claim” above.
Tactical (concrete decisions Sense 52 makes to accommodate these):
- [[project_sense16_p2p2p]] — offline map story for owner-hosted tenants that can’t reach OSM tile servers. V1 fallback: “map unavailable” + text list of sites by coordinate. V2: bundled MBTiles pack in the AFS.
- [[project_studio_lab_salon]] — Cartography is a new surface class parallel to Map Salon. Not a replacement. Users use whichever fits the question — Map Salon for generic visual encoding (heatmap / scatter / strip auto-detected from axis types), Cartography for the specific case of “plot the entities on a real base map.”
Example clients (packs that will want maps early, not Sense-level ties):
- [[project_hrcentral_coming]] — buildings / clinics as points. Adopts in V3 once VAI has coordinates in its Gold contract.
- riverflow — the driver. V1 target.
Not cross-referenced here (correction from initial draft):
- Sense 15 (Observation) — the initial proposal named this as “deepest integration.” On review it’s not a Sense-level tie — a pack can choose to render Sense 15 observations that reference geographic entities as map annotations, but that’s a pack-level display choice, not a design principle of either Sense. Sense 15 observations are legible without any map; Sense 52 maps carry no special observation-awareness. The riverflow-specific rendering choices live under “Watershed- specific concerns” as examples, not as structural claims.
Cross-refs in code / data (V1 shipping list)
Section titled “Cross-refs in code / data (V1 shipping list)”docs/design/sense_52_the_cartography.md— this filescripts/mapcompile.py— newscripts/mapcheck.py— newexplorer/src/routes/[tenant]/maps/+page.svelte— listexplorer/src/routes/[tenant]/maps/[map_id]/+page.svelte— detail with rendererexplorer/src/routes/[tenant]/maps/[map_id]/+page.server.ts— data loaderexplorer/src/lib/cartography/renderer.ts— MapLibre wrapperexplorer/src/lib/cartography/layers.ts— layer type registryexplorer/src/lib/cartography/tile_sources.ts— base layer registryexplorer/src/lib/utils/anchorRoute.ts— extend withmapkind (done later)- Pack:
packs/riverflow/entities/watersheds.yaml— addboundary_geojsoncolumn contract (V2)
Signature
Section titled “Signature”Proposed 2026-07-09 by claudia9 (Opus 4.7 in worktree jinflow-9th) with Mig.
Extended and finalised 2026-07-09 by Claude (Opus 4.7 in worktree jinflow-7th) with Mig:
- Added the “Structural claim — peer of Canvas, cascade-aware” section to name the Sense 13 and Sense 43 relationships up front.
- Demoted the Sense 15 “trout-spawning” claim from “deepest integration” to “pack-level display choice, not a Sense-level tie” — the initial framing overreached; the observation is legible without a map.
- Rewrote the Cross-references section to distinguish foundational ties (Sense 13, 43) from tactical ones (16, 24) and example clients (hrcentral).
- Added the “Known Sense-level gaps” section — flags discovery, authoring lifecycle, and cross-tenant browsing as substrate-wide concerns that Sense 52 inherits rather than solves alone.
- Added
type: mapcells inkind: reportnotebooks as an Open Question (future, not V1). - Sister-conversation surface opened at [[sister7_sister9_conversations]] for further coordination with claudia9 as V1 implementation proceeds.
Ready for V1 implementation on claude/7th.
No solo structural moves ([[feedback_team_no_solo_structural_moves]]) — Mig ratified via merge to main + delegation on this session.
Numerical neighbors: ← Sense 51: The Skill — cross-domain analytical patterns · Sense 53 — The Codex →