Documentation / Quorumz map integration

HiNet — Quorumz Map Integration (the intelligence layer)

Status: [NEW spec, MVP-buildable — clones an existing Quorumz pattern] · consumes Node Identity & Registry (§2 registry, §4.5 attested specialities) and Routing & Aggregation §2.5 (competence). UI host: the Quorumz discover map.

Render the HiNet node pool as a new layer on the Quorumz map — the same registry that routing reads, made visible: iCore nodes geographically, and grouped/filterable by domain/expertise category. This is the network's public face. It reuses Quorumz's existing map + layer machinery almost verbatim; the only net-new design is location privacy (a HiNet node maps to a person's device — its position must never be precise).

0. Why this is mostly reuse

The Quorumz discover map (Google Maps JS, apps/web/src/app/discover/discover-client.tsx) already has a first-class layer registry (apps/web/src/lib/layers.ts) and a self-contained marker-layer archetype — the public_figures layer — whose markers already carry lat/lon + primary_category + secondary_categories and drive a category drill-down panel. The "geographic AND by-category" duality is a solved pattern there. HiNet's hinet_nodes layer is a clone of that path pointed at the HiNet registry, plus the privacy gate below.

1. What a node looks like on the map `[MVP]`

Each public node is one marker. The marker's color = its primary expertise domain; clicking opens a panel that can also browse by domain (domain → nodes → node detail).

// HiNetMarker — the public, privacy-safe projection of a registry node (clone of PfMarker)
type HiNetMarker = {
  node_id: string;                 // self-certifying icore_… id (Identity §1.2)
  name: string;                    // owner-chosen node name (e.g. "eLiCore1")
  lat: number; lon: number;        // COARSE, consented location only — see §3 (never precise)
  loc_precision: "region" | "city" | "hidden";   // what the point actually represents
  primary_domain: DomainCategory;  // top-level governed taxonomy bucket → marker color
  secondary_domains: DomainCategory[];
  proof_tier: "declared" | "committed" | "provenance" | "challenged" | "attested";  // badge (Routing §2.5.2)
  personhood: "none" | "account" | "proof_of_personhood";                            // verified-human badge
  liveness: "online" | "recent" | "offline";
  kind: "icore" | "iquorum" | "icorp";   // iCorps appear as ONE identity (membrane, §2.3)
  country_code?: string;
};

// DomainCategory = the top-level buckets of the governed competence taxonomy (Identity §4.5.2),
// e.g. engineering | law | medicine | finance | software | science | arts | … (versioned, not free-text)

Two views, both already patterned in Quorumz: - Geographic — markers on the map, colored by primary_domain, clustered by zoom (reuse buildClusters). A legend maps color → domain. - By domain/expertise — a CategoryGrid-style panel (clone PublicFiguresPanel): pick a domain → list its nodes → node detail. This is the "show them per domain / expertise category" view, decoupled from geography.

2. Data flow `[MVP]` — clone the `public_figures` pipeline

HiNet registry (Postgres; Identity §2)
  └─ cron builds markers.json  (clone api_payload.py: public_figures_markers_payload)
        • one entry per PUBLIC, consented node
        • PRIVACY GATE applied here (§3) — server-side, before anything leaves
     → GCS  gs://quorumz-feeds-*/hinet/v1/markers.json   (+ a categories index for the grouped view)
        → Cloudflare Worker proxy  /api/layers/hinet  (or /api/hinet/markers) — edge-cached
           → client fetchHiNetMarkers()  (clone public-figures-api.ts)
              → mountHiNetMarkerLayer(map, googleMaps)  (clone public-figures-map-layer.ts)
                 • one google.maps.Marker/node, icon fill = categoryColor(primary_domain)
                 • click → CustomEvent "hinet:select" → HiNetPanel (grouped/filterable by domain)

Refresh cadence follows public_figures (~120 s republish). The categories index (Record<DomainCategory, {count, node_ids[]}>) powers the grouped view without a second fetch.

3. Location privacy — the one net-new gate `[MVP, REQUIRED]`

A HiNet node is a person's device. Publishing precise coordinates would leak an owner's home — a direct violation of HiNet's sovereignty constraint. So the marker's position is coarse, consented, and never precise:

Opt-in only. A node has no map presence unless the owner sets map_visibility = public and provides a location grant. Default = hidden. (Distinct from routing exposure: a node can route in the network yet be invisible on the map.)
Coarsening, server-side, before publish. The owner picks a precision: region (state/metro centroid) or city (city centroid), snapped to a fixed grid (e.g. an H3 cell at a coarse resolution). The published lat/lon is the cell/centroid, plus small deterministic jitter, never the device's GPS. hidden → the node appears only in the by-domain view with country_code, no point.
No precise source ever server-side. The node reports only its chosen coarse cell (derived locally); the registry never stores fine coordinates. k-anonymity target: never render a point that localizes to < K nodes' worth of area at that zoom (cluster instead).
Attestation/consent gates carried through (reuse Identity §4.5.3): drop expires_at <= now, exclude exposure != public specialities from the shown domains, and never surface sensitive/secret specialities (a domain label can itself be sensitive). proof_tier/personhood badges are shown so viewers can tell a proven node from a self-declared one (Routing §2.5) — the map does not launder unproven claims into apparent credibility.

4. Entry points (from the Quorumz codebase) `[MVP]`

Clone the public_figures layer path — no new map infrastructure:

apps/web/src/lib/layers.ts — add "hinet_nodes" to LayerId; add a Layer entry (label "Intelligence" / icon / accentColor); optionally a new LayerCategory: "intelligence"; optionally default-on.
apps/web/src/lib/hinet-types.ts (new) — HiNetMarker + DomainCategory union + categories index (clone public-figures-types.ts).
apps/web/src/lib/hinet-api.ts (new) — fetchHiNetMarkers() (clone public-figures-api.ts).
apps/web/src/app/api/layers/hinet/route.ts (new) — GCS/registry proxy, CF-cached (clone usgs/route.ts or the PF proxy).
apps/web/src/lib/hinet-map-layer.ts (new) — mountHiNetMarkerLayer(...)→{refresh,teardown}; icon fill = categoryColor(node.primary_domain); dispatch hinet:select (clone public-figures-map-layer.ts).
apps/web/src/app/discover/discover-client.tsx — wire it (mirror the public_figures refs): import + hinetLayerRef + a mount useEffect gated on selectedLayers.has("hinet_nodes") + a hinet:select listener.
apps/web/src/components/hinet/HiNetPanel.tsx (new, optional) — the domain-grouped drill-down (clone PublicFiguresPanel.tsx), lazy-loaded.

Backend: a hinet markers-payload builder in the HiNet backend (or the Quorumz api), analogous to services/public_figures/api_payload.py, applying the §3 privacy gate.

5. Reuses vs adds

Reuses [EXISTS in Quorumz]: the Google-Maps discover map + mapReady/mapRef lifecycle; the layers.ts registry + LayersBar/dropdown toggles + sessionStorage persistence; the public_figures marker-layer archetype (fetch → google.maps.Marker → hinet:select → panel) + buildClusters; the CategoryGrid/PublicFiguresPanel by-category drill-down; the GCS→CF-proxy→client feed pattern + ~120 s cron republish. Reuses [EXISTS in HiNet]: the registry as source of truth (Identity §2), attested specialities + proof-tier + personhood + exposure/sensitivity gates (Identity §4.5, Routing §2.5), the governed domain taxonomy (§4.5.2) as the category union. Adds [NEW]: the HiNetMarker contract; the location-privacy gate (opt-in + coarse H3/centroid + jitter + k-anonymity, §3) — the only genuinely new design; the hinet markers payload builder; the seven cloned web files.

6. Open decisions `[OPEN]`

Location granularity vs. usefulness — region-centroid is safest but visually clumps; per-owner precision choice with a hard coarse floor is the proposal. Confirm the floor (H3 resolution) + the k-anonymity threshold.
What the map is for — discovery/marketing (browse the network, find expertise) vs. an operator view. MVP = public discovery; an owner's own richer view (their node's routing/earnings) is a separate authenticated surface.
Which registry — dev vs prod HiNet registry feeding the dev vs prod Quorumz map; namespacing in GCS.
iCorp representation — an iCorp is one identity on the map (members hidden, §2.3); does it get a location at all, or only a by-domain presence?
Ownership of the payload builder — HiNet backend emits markers.json vs. the Quorumz api reads the HiNet registry directly. (Leaning: HiNet backend emits, Quorumz proxies — keeps the privacy gate on the HiNet side.)

Next: Node distribution, EVM identity & sense → · All documentation →

HiNet — Quorumz Map Integration (the intelligence layer)

0. Why this is mostly reuse

1. What a node looks like on the map [MVP]

2. Data flow [MVP] — clone the public_figures pipeline

3. Location privacy — the one net-new gate [MVP, REQUIRED]

4. Entry points (from the Quorumz codebase) [MVP]