Zum Inhalt springen

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.md in 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)

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.

Two things converged on 2026-07-09:

  1. Riverflow shipped with lat/lon/altitude already in the Gold contract. gold_deployment_sites carries coordinates_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.
  2. 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.

Sense 15 gave the CEO conversation three moves (“What? / Is it real? / Why?”). Cartography gives the field team three moves:

  1. “Where?” — plot the entity at its actual location on a base map the reader recognises.
  2. “What’s there?” — hover/click reveals rich per-point content: current state, recent readings, active alarms, signed observations.
  3. “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 elementSense 52 counterpart
tiles/*.yamlmaps/*.yaml
scripts/tilecheck.pyscripts/mapcheck.py
scripts/tilecompile.pyscripts/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 well
L2 tenant override → delta.jinflow.io picks "satellite" as its
audience-facing default
L3 map YAML override → a specific map declares its own
`default_base_layer: "topo"` for a
watershed-focused view

display.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).

Every entity that participates in a map declares its geometry in its Gold contract. Three geometry kinds are canonical:

KindColumnsStorageExample entities
Pointcoordinates_lat DECIMAL(10,6), coordinates_lon DECIMAL(10,6), optionally altitude_m INTEGERNative columnsDeploymentSite, Building, Hospital, Warehouse, Vineyard, PickupLocation
Polylinegeometry_geojson VARCHAR containing a GeoJSON LineString, OR inferred from ordered child pointsColumn or derivedReach (river segment), Route (freight), Ski run, Pipeline
Polygongeometry_geojson VARCHAR containing a GeoJSON Polygon/MultiPolygonColumnWatershed, 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.

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).

map_id: map_delta_field_network
kind: map # required — first-class type
version: 0.1.0
created_at: 2026-07-09
modified_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 hints
tags: [riverflow, delta, field_ops, sense_52_seed]
  • Familiarity by design: mirrors Panel / Lens / Perspective YAML conventions — same display_name, description, scope, tags fields. New authors trained on Panels write Maps without new grammar.
  • Declarative styling: the marker.color.from_signal block 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}} picks name_de / name_en / name_fr / name_it based on the viewer’s locale, matching JinDesk’s existing i18n.

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:

Library3DVector tilesAPI key neededBundle sizeVerdict
MapLibre GL✅ native terrain, extrusions✅❌ (uses OSM freely)~500 KB gzPick this
Mapbox GL✅✅✅ paid at scale~500 KBWraps in vendor lock-in
Leaflet❌ (2D only)🟡 via plugin❌~40 KBGreat but caps at 2D
OpenLayers🟡 limited✅❌~250 KBOverkill for our shape
CesiumJS✅ full globe✅🟡 (assets)~4 MBBeautiful 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.

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 + compile afs/maps/*.yaml → KLS _<tenant>.map_registry
  • mapcheck.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).

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 V1

The 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.

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 discoverable

Renderer computes opacity = clamp(1 - (now - timestamp)/decay, minimum, 1). Feature-level, not layer-level — each row’s opacity depends on its own timestamp.

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) and signal_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_drift today.
  • 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.

Each of sister-9’s demos is one YAML file composing these capabilities:

IdeaCapabilitiesLayer shape
MaintenanceEvent fading pinsA + BFact layer over MaintenanceEvent × DeploymentSite, marker.opacity.from_timestamp: cleared_at
Silent sensorsA + V1 severity paintFact layer over Sensor × DeploymentSite (via current_site_id), marker.color.from_signal: signal_datastream_inactive
Site fouling burdenV1 severity paintPlain V1 point layer over DeploymentSite, marker.color.from_signal: signal_site_fouling_burden
PathChange
scripts/mapcheck.pyValidate: source.join.{to, on, to_field}, marker.opacity.{from_timestamp, decay, minimum} shapes
scripts/mapcompile.pyNo change — the whole map YAML round-trips through config_json already; new fields land automatically
tests/test_mapcheck.pyNew cases for the two additions
explorer/src/lib/server/queries/maps.tsExtend MapConfig types to carry the new optional fields
explorer/src/routes/[tenant]/maps/[map_id]/+page.server.tsLayer loader gains a JOIN branch when source.join is set; materialises fact rows carrying the joined coords
explorer/src/lib/cartography/renderer.tsMarker paint reads opacity declaration; new helper resolveOpacity(row, decl)
Delta AFSReal map_delta_maintenance_pulse.yaml composing the two capabilities against sister-9’s confirmed column shapes. Verification target once her rebuild pings.

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

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 the Watershed entity contract. Ships as a VARCHAR column 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 the polygon and multipolygon subkinds available. The boundary_geojson column declares kind: geometry, subkind: polygon, standard: rfc_7946_geojson, crs: wgs84. The Codex’s rfc_7946_geojson standard’s binding_kinds moves from [] to [geometry]. typologycheck.py validates that any column declared geometry.polygon binds either rfc_7946_geojson or another future geometry-serialization standard.
  • YAML shape — the fill layer. New style.type: fill accepted on a data layer. source.geometry names the column carrying the GeoJSON string. Static paint via style.fill_color, dynamic paint via style.fill_color.from_signal (mirroring V1’s marker.color.from_signal shape — the mechanism is layer-agnostic, so it stops being a marker-only concern in V2). Optional stroke via style.stroke_color / style.stroke_width, likewise supporting from_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 addFillLayer in explorer/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 MapLibre fill and (if stroke_* set) line layers. 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 adds style: custom_tile_url with a url: 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 attribution field. Docked to the map’s bottom-right by default; position is a display.layout.map_legend config-engine key (Sense 43 cascade).
  • 3D + terrain. MapLibre terrain source, DEM tile provider, three_d.enabled YAML 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_color as a static value only. V2 could close this by extending from_signal to style.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_action block 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:

  1. boundary_geojson VARCHAR on Watershed in contracts/gold_contract.v1.json.
  2. 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.
  3. 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.

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.

Ships:

  • MapLibre raster-dem terrain 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.enabled YAML 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_to behaviour 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_signal if 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

Beyond the generalization, riverflow drives some specific design decisions:

  1. Flow direction on reaches — arrows on the polyline pointing downstream. Compiled from upstream_reach_id/downstream_reach_id on Gold. Optional layer, small but signature-worthy for river maps.

  2. Elevation cross-section — click a reach and get a side-panel showing altitude profile (upstream → downstream, with sensor positions marked). Uses altitude_m from sites along the reach. Distinguishes riverflow from generic point maps.

  3. Snowmelt overlay (future) — when delta ships snow-line data or SWE (snow water equivalent) grids, add a raster overlay layer. Not V1.

  4. 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.

  5. Cattle crossing overlay — Chantal’s observation would be a static overlay layer showing the transhumance routes. Sourced from a overlays/cattle_transhumance.geojson file 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.

  1. 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.

  2. geometry_geojson vs. 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.

  3. 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 /maps visit incurs the cost; other routes stay slim.

  4. 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.

  5. type: map cells in kind: report notebooks (future). If a metric cell in a report note can carry a signal_id and inherit provenance, can a cell be type: map and reference an existing map_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.

  • 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_key gate 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.

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 file
  • scripts/mapcompile.py — new
  • scripts/mapcheck.py — new
  • explorer/src/routes/[tenant]/maps/+page.svelte — list
  • explorer/src/routes/[tenant]/maps/[map_id]/+page.svelte — detail with renderer
  • explorer/src/routes/[tenant]/maps/[map_id]/+page.server.ts — data loader
  • explorer/src/lib/cartography/renderer.ts — MapLibre wrapper
  • explorer/src/lib/cartography/layers.ts — layer type registry
  • explorer/src/lib/cartography/tile_sources.ts — base layer registry
  • explorer/src/lib/utils/anchorRoute.ts — extend with map kind (done later)
  • Pack: packs/riverflow/entities/watersheds.yaml — add boundary_geojson column contract (V2)

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: map cells in kind: report notebooks 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 →

jazzisnow jinflow is a jazzisnow product
v0.65.0 · built 2026-11-13 10:20 UTC