knosky 0.5.0 → 0.6.1

package/core/key-store.mjs

@@ -0,0 +1,348 @@
+// KnoSky signing-key rotation/revocation lifecycle (SAT-446 / Hardening Addendum 2).
+// In-process HMAC-SHA256 key store — local-first, no external KMS, no telemetry.
+// Callers own persistence; this module is pure in-memory state + crypto.
+// Pure Node stdlib, ESM — no third-party dependencies.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Generate a random 16-byte key id as a 32-char lowercase hex string. */
+function newKeyId() {
+  return randomBytes(16).toString('hex');
+}
+
+/**
+ * Compute HMAC-SHA256 over a canonical JSON serialisation of `payload`.
+ * "Canonical" = top-level keys sorted alphabetically before serialisation.
+ * Returns a lowercase 64-char hex string.
+ *
+ * @param {Buffer} keyBuf
+ * @param {object} payload
+ * @returns {string}
+ */
+function hmacPayload(keyBuf, payload) {
+  const sorted = Object.fromEntries(
+    Object.keys(payload).sort().map(k => [k, payload[k]]),
+  );
+  return createHmac('sha256', keyBuf).update(JSON.stringify(sorted)).digest('hex');
+}
+
+/**
+ * Strip `key_id` and `sig` from a manifest object to get the signing payload.
+ * These two fields are metadata added *after* signing and must not be part
+ * of the signed content.
+ *
+ * @param {object} manifest
+ * @returns {object}
+ */
+function signingPayload(manifest) {
+  const out = {};
+  for (const [k, v] of Object.entries(manifest)) {
+    if (k === 'key_id' || k === 'sig') continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// createKeyStore
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new in-memory key store with a single initial active key.
+ *
+ * The returned object has the following shape:
+ * ```
+ * {
+ *   keys:        Map<key_id, KeyEntry>,
+ *   activeKeyId: string | null,
+ * }
+ * ```
+ *
+ * where each `KeyEntry` is:
+ * ```
+ * { key_id: string, status: 'active'|'rotated'|'revoked', created_at: string, raw: Buffer }
+ * ```
+ *
+ * @returns {{ keys: Map<string, object>, activeKeyId: string }}
+ */
+export function createKeyStore() {
+  const ks = { keys: new Map(), activeKeyId: null };
+  _issueKey(ks);
+  return ks;
+}
+
+/**
+ * @internal
+ * Issue a new active key.  Demotes the current active key to `'rotated'` if
+ * one exists (rotated keys remain verifiable; only revoked ones are rejected).
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @returns {string}  The newly-issued key_id.
+ */
+function _issueKey(ks) {
+  // Demote any current active key → 'rotated' (still usable for verification).
+  if (ks.activeKeyId !== null) {
+    const prev = ks.keys.get(ks.activeKeyId);
+    if (prev && prev.status === 'active') prev.status = 'rotated';
+  }
+  const key_id = newKeyId();
+  ks.keys.set(key_id, {
+    key_id,
+    status: 'active',
+    created_at: new Date().toISOString(),
+    raw: randomBytes(32),
+  });
+  ks.activeKeyId = key_id;
+  return key_id;
+}
+
+// ---------------------------------------------------------------------------
+// rotateKey
+// ---------------------------------------------------------------------------
+
+/**
+ * Rotate the signing key: demote the current active key to `'rotated'` and
+ * issue a fresh one.
+ *
+ * Manifests already signed with the old (now `'rotated'`) key remain
+ * verifiable.  Only `'revoked'` keys are rejected by {@link verifyManifest}.
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @returns {string}  The new active key_id.
+ */
+export function rotateKey(ks) {
+  return _issueKey(ks);
+}
+
+// ---------------------------------------------------------------------------
+// revokeKey / makeRevocationApproval
+// ---------------------------------------------------------------------------
+
+/**
+ * The canonical payload that approval signers HMAC to authorise a revocation.
+ * Keys are sorted alphabetically (matching {@link hmacPayload}).
+ *
+ * @param {string} targetKeyId
+ * @returns {{ action: string, target_key_id: string }}
+ */
+function revocationPayload(targetKeyId) {
+  // Return in key-sorted order so hmacPayload produces a deterministic digest.
+  return { action: 'revoke_key', target_key_id: targetKeyId };
+}
+
+/**
+ * Produce a revocation-approval token signed by `signingKeyId`.
+ *
+ * The token is an `{ key_id, sig }` object that can be collected from multiple
+ * non-revoked keys and passed as the `approvals` array to {@link revokeKey}
+ * to satisfy the quorum requirement.
+ *
+ * Throws if `signingKeyId` is unknown, already revoked, or equal to
+ * `targetKeyId` (a key may not approve its own revocation).
+ *
+ * @param {{ keys: Map<string,object> }} ks
+ * @param {string} signingKeyId
+ * @param {string} targetKeyId
+ * @returns {{ key_id: string, sig: string }}
+ */
+export function makeRevocationApproval(ks, signingKeyId, targetKeyId) {
+  if (signingKeyId === targetKeyId) {
+    throw new Error('makeRevocationApproval: signing key and target key must differ');
+  }
+  const entry = ks.keys.get(signingKeyId);
+  if (!entry) {
+    throw new Error(`makeRevocationApproval: unknown key_id ${JSON.stringify(signingKeyId)}`);
+  }
+  if (entry.status === 'revoked') {
+    throw new Error(`makeRevocationApproval: signing key ${JSON.stringify(signingKeyId)} is revoked`);
+  }
+  const sig = hmacPayload(entry.raw, revocationPayload(targetKeyId));
+  return { key_id: signingKeyId, sig };
+}
+
+/**
+ * Revoke a key by id.
+ *
+ * After revocation {@link verifyManifest} rejects any manifest that was
+ * signed with the revoked key.  Revocation is permanent within a key-store
+ * instance.  The operation is idempotent — revoking an already-revoked key
+ * is a no-op.
+ *
+ * If the revoked key was the active signing key, `activeKeyId` is cleared to
+ * `null`; callers must {@link rotateKey} to obtain a new active key.
+ *
+ * **Authorization / quorum gate (SAT-472)**
+ *
+ * Let `M` be the number of non-revoked keys other than `keyId`.  The
+ * required quorum is `Math.floor(M / 2) + 1` (strict majority of peers).
+ * When `M === 0` (the target is the only remaining key) no approvals are
+ * needed.  Each approval in the `approvals` array must be a valid
+ * {@link makeRevocationApproval} token signed by a distinct, non-revoked key
+ * that is not `keyId` itself.
+ *
+ * This ensures a single compromised key cannot unilaterally revoke all
+ * others: it can only contribute one approval, which is always less than
+ * the strict majority needed when `M >= 2`.
+ *
+ * Throws if `keyId` is not present in the store or if the quorum is not met.
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @param {string} keyId
+ * @param {{ key_id: string, sig: string }[]} [approvals=[]]
+ */
+export function revokeKey(ks, keyId, approvals = []) {
+  if (!ks.keys.has(keyId)) {
+    throw new Error(`revokeKey: unknown key_id ${JSON.stringify(keyId)}`);
+  }
+  const entry = ks.keys.get(keyId);
+  if (entry.status === 'revoked') return; // idempotent
+
+  // Count non-revoked peer keys (all keys except the revocation target).
+  const peers = [...ks.keys.values()].filter(
+    e => e.key_id !== keyId && e.status !== 'revoked',
+  );
+  const required = peers.length > 0 ? Math.floor(peers.length / 2) + 1 : 0;
+
+  if (required > 0) {
+    // Validate each approval token over the canonical revocation payload.
+    const payload = revocationPayload(keyId);
+    const seen = new Set();
+    let valid = 0;
+
+    for (const approval of approvals) {
+      const { key_id: aKeyId, sig } = approval ?? {};
+      if (!aKeyId || !sig) continue;
+      if (aKeyId === keyId) continue;      // target cannot self-approve
+      if (seen.has(aKeyId)) continue;      // deduplicate per signer
+
+      const aEntry = ks.keys.get(aKeyId);
+      if (!aEntry || aEntry.status === 'revoked') continue;
+
+      const expected = hmacPayload(aEntry.raw, payload);
+      if (typeof sig !== 'string' || sig.length !== expected.length) continue;
+
+      let match = false;
+      try {
+        match = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(sig, 'hex'));
+      } catch { match = false; }
+
+      if (match) {
+        seen.add(aKeyId);
+        valid++;
+      }
+    }
+
+    if (valid < required) {
+      throw new Error(
+        `revokeKey: quorum not met — ${required} approval(s) required from peer keys, got ${valid}`,
+      );
+    }
+  }
+
+  entry.status = 'revoked';
+  // If the active key was just revoked, clear the active pointer.
+  if (ks.activeKeyId === keyId) ks.activeKeyId = null;
+}
+
+// ---------------------------------------------------------------------------
+// signManifest
+// ---------------------------------------------------------------------------
+
+/**
+ * Sign a manifest with the store's current active key.
+ *
+ * Returns a shallow copy of `manifest` with two new fields appended:
+ * - `key_id` — identifies the signing key for later verification.
+ * - `sig`    — lowercase hex HMAC-SHA256 over the canonical signing payload
+ *              (all manifest fields except `key_id` and `sig` themselves,
+ *              with top-level keys sorted alphabetically).
+ *
+ * Throws if there is no active key in the store (e.g. after revoking the
+ * active key without rotating first).
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @param {object} manifest   Typically the result of {@link makeIntentManifest}.
+ * @returns {object}          Manifest copy decorated with `key_id` and `sig`.
+ */
+export function signManifest(ks, manifest) {
+  const entry = ks.activeKeyId != null ? ks.keys.get(ks.activeKeyId) : null;
+  if (!entry || entry.status !== 'active') {
+    throw new Error('signManifest: no active key in store — rotate to obtain one');
+  }
+  const payload = signingPayload(manifest);
+  const sig = hmacPayload(entry.raw, payload);
+  return { ...manifest, key_id: entry.key_id, sig };
+}
+
+// ---------------------------------------------------------------------------
+// verifyManifest
+// ---------------------------------------------------------------------------
+
+/**
+ * Verify a signed manifest.
+ *
+ * Returns `{ ok: true }` when the signature is valid and the signing key is
+ * present and not revoked.  Otherwise returns `{ ok: false, reason }`.
+ *
+ * Never throws on malformed input — treats it as a verification failure.
+ *
+ * | `reason`          | Meaning                                             |
+ * |-------------------|-----------------------------------------------------|
+ * | `'missing_key_id'`| `key_id` field absent from the manifest.            |
+ * | `'unknown_key'`   | `key_id` is not registered in this store.           |
+ * | `'key_revoked'`   | The key exists but has been revoked.                |
+ * | `'bad_signature'` | HMAC did not match — data was tampered or wrong key.|
+ *
+ * @param {{ keys: Map<string,object>, activeKeyId: string|null }} ks
+ * @param {object} signedManifest
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+export function verifyManifest(ks, signedManifest) {
+  const { key_id, sig } = signedManifest;
+
+  if (!key_id) return { ok: false, reason: 'missing_key_id' };
+
+  const entry = ks.keys.get(key_id);
+  if (!entry) return { ok: false, reason: 'unknown_key' };
+  if (entry.status === 'revoked') return { ok: false, reason: 'key_revoked' };
+
+  const payload = signingPayload(signedManifest);
+  const expected = hmacPayload(entry.raw, payload);
+
+  // Use timingSafeEqual to prevent timing-side-channel leaks.
+  // Both buffers must have the same length; a length mismatch is a sig failure.
+  const eBuf = Buffer.from(expected, 'hex');
+  if (typeof sig !== 'string' || sig.length !== expected.length) {
+    return { ok: false, reason: 'bad_signature' };
+  }
+  const aBuf = Buffer.from(sig, 'hex');
+  let match;
+  try {
+    match = timingSafeEqual(eBuf, aBuf);
+  } catch {
+    match = false;
+  }
+  return match ? { ok: true } : { ok: false, reason: 'bad_signature' };
+}
+
+// ---------------------------------------------------------------------------
+// getKey
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the metadata for a registered key (without the raw key material).
+ * Returns `null` if `keyId` is not in the store.
+ *
+ * @param {{ keys: Map<string,object> }} ks
+ * @param {string} keyId
+ * @returns {{ key_id: string, status: string, created_at: string } | null}
+ */
+export function getKey(ks, keyId) {
+  const entry = ks.keys.get(keyId);
+  if (!entry) return null;
+  // Never expose the raw key material to callers.
+  return { key_id: entry.key_id, status: entry.status, created_at: entry.created_at };
+}

package/core/ledger.mjs

@@ -0,0 +1,141 @@
+// KnoSky ledger high-water-mark guard (SAT-443 / V13).
+//
+// Independently persists the highest-seen ledger sequence number in a
+// dedicated file (separate from the ledger itself) so that a truncation
+// attack that replaces the whole ledger cannot roll back the sequence.
+//
+// Anti-truncation rule (D-164 TUF-evolution): a ledger state whose sequence
+// number is STRICTLY LOWER than the persisted high-water mark is refused.
+//
+// The HWM file is a minimal JSON document:  { "ledger_hwm": <integer> }
+// It is intentionally kept narrow — no ledger content lives here.
+//
+// Pure Node stdlib, ESM — no third-party dependencies.
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync, openSync, fsyncSync, closeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { MAX_PLAUSIBLE_LEDGER_SEQ } from './constants.mjs';
+
+// ---------------------------------------------------------------------------
+// HWM file I/O
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the persisted high-water mark from `hwmPath`.
+ * Returns 0 when the file does not exist (first run — any sequence is valid).
+ * Throws on I/O errors other than ENOENT, and on malformed content (fail-closed).
+ *
+ * @param {string} hwmPath  Path to the independently-persisted HWM file.
+ * @returns {number}  Stored sequence number (non-negative integer).
+ */
+export function readHwm(hwmPath) {
+  let text;
+  try {
+    text = readFileSync(hwmPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return 0;
+    throw err; // permission error — fail-closed
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`ledger HWM file is not valid JSON: ${hwmPath}`);
+  }
+  if (!Number.isInteger(parsed.ledger_hwm) || parsed.ledger_hwm < 0) {
+    throw new Error(
+      `ledger HWM file has invalid ledger_hwm: ${JSON.stringify(parsed.ledger_hwm)} in ${hwmPath}`,
+    );
+  }
+  return parsed.ledger_hwm;
+}
+
+/**
+ * Persist `seq` as the current high-water mark.
+ * Creates parent directories if they do not already exist.
+ *
+ * @param {string} hwmPath  Path to write.
+ * @param {number} seq      New HWM value (non-negative integer).
+ */
+export function writeHwm(hwmPath, seq) {
+  if (!Number.isInteger(seq) || seq < 0) {
+    throw new TypeError(
+      `ledger_hwm must be a non-negative integer, got: ${JSON.stringify(seq)}`,
+    );
+  }
+  const dir = dirname(hwmPath);
+  mkdirSync(dir, { recursive: true });
+  // Atomic write: write to a sibling temp file, then rename into place.
+  // This prevents a partial/corrupt HWM file on crash or power loss —
+  // critical because a corrupt HWM would either silently reset the guard
+  // (ENOENT path) or throw (parse error), both of which weaken security.
+  const tmp = hwmPath + '.tmp';
+  writeFileSync(tmp, JSON.stringify({ ledger_hwm: seq }) + '\n', 'utf8');
+  // fsync the temp file's contents before rename — otherwise the rename can
+  // land on disk before the data it points to does (SAT-474 hardening review).
+  const tmpFd = openSync(tmp, 'r');
+  try { fsyncSync(tmpFd); } finally { closeSync(tmpFd); }
+  renameSync(tmp, hwmPath);
+  // fsync the containing directory so the rename itself (the directory-entry
+  // update) is durable — without this, a crash immediately after renameSync
+  // can leave the old HWM file name visible on some filesystems/mount options
+  // (e.g. ext4 without data=ordered). POSIX-specific guarantee; best-effort
+  // on platforms where directory fsync isn't supported.
+  try {
+    const dirFd = openSync(dir, 'r');
+    try { fsyncSync(dirFd); } finally { closeSync(dirFd); }
+  } catch { /* best-effort; not all platforms support directory fsync */ }
+}
+
+// ---------------------------------------------------------------------------
+// checkAndAdvance — the core anti-truncation guard
+// ---------------------------------------------------------------------------
+
+/**
+ * Enforce the high-water-mark invariant for incoming ledger state.
+ *
+ * Reads the persisted HWM from `hwmPath`, then applies the anti-truncation
+ * rule:
+ *   - `seq` STRICTLY LESS than HWM → refuse. The HWM file is NOT updated.
+ *   - `seq` EQUAL to HWM           → accept (idempotent replay).  HWM written.
+ *   - `seq` GREATER than HWM       → accept and advance.           HWM written.
+ *
+ * Returning `{ ok: false }` means the caller must treat the incoming ledger
+ * state as invalid and stop processing — it must not be applied or surfaced
+ * as authoritative.
+ *
+ * @param {number} seq      Claimed sequence number from the incoming ledger state.
+ * @param {string} hwmPath  Path to the independently-persisted HWM file.
+ * @returns {{ ok: boolean, seq: number, hwm: number, error?: string }}
+ */
+// Second layer of defense: enforced here too (not only in
+// core/freshness.mjs's extractLedgerSeq) so checkAndAdvance is safe even if
+// called directly. Imports the single source of truth from constants.mjs
+// (a dependency-free module) so the two layers cannot silently diverge.
+export function checkAndAdvance(seq, hwmPath) {
+  if (!Number.isInteger(seq) || seq < 0 || seq > MAX_PLAUSIBLE_LEDGER_SEQ) {
+    return {
+      ok: false,
+      seq,
+      hwm: -1,
+      error: `seq must be a non-negative integer no greater than ${MAX_PLAUSIBLE_LEDGER_SEQ}, got: ${JSON.stringify(seq)}`,
+    };
+  }
+
+  const hwm = readHwm(hwmPath);
+
+  if (seq < hwm) {
+    // Anti-truncation guard: incoming sequence is below the highest-seen mark.
+    // Do NOT update the file — the old (higher) mark must remain authoritative.
+    return {
+      ok: false,
+      seq,
+      hwm,
+      error: `ledger sequence ${seq} is below the high-water mark ${hwm} — refusing (anti-truncation guard)`,
+    };
+  }
+
+  // seq >= hwm: advance (or re-confirm) the mark.
+  writeHwm(hwmPath, seq);
+  return { ok: true, seq, hwm };
+}

package/core/lod.mjs

@@ -0,0 +1,155 @@
+// core/lod.mjs — Level-of-detail, viewport culling, clustering, and streaming
+// utilities for large single-repo city graphs (SAT-447).
+//
+// All functions are pure (no side-effects, no DOM/canvas imports) so they can
+// be used both in the Node.js test harness and inlined into the browser renderer.
+
+// ---------------------------------------------------------------------------
+// LOD tier constants
+// Each tier drives rendering fidelity in city.template.html.
+//   FULL   — full-detail buildings, cars, trees, props, shadows, connections
+//   SIMPLE — buildings only (no cars / trees / props / shadows)
+//   DOT    — each building renders as a coloured dot (very-far-out zoom)
+//   CLUSTER— entire district collapses to a single cluster badge
+// ---------------------------------------------------------------------------
+export const LOD_FULL    = 0;  // zoom >= LOD_FULL_THRESHOLD
+export const LOD_SIMPLE  = 1;  // zoom >= LOD_SIMPLE_THRESHOLD
+export const LOD_DOT     = 2;  // zoom >= LOD_DOT_THRESHOLD
+export const LOD_CLUSTER = 3;  // zoom <  LOD_DOT_THRESHOLD
+
+// Zoom boundary constants (cam.zoom scale, matching renderer defaults)
+export const LOD_FULL_THRESHOLD    = 0.35;  // below → drop cars/trees/props/shadows
+export const LOD_SIMPLE_THRESHOLD  = 0.12;  // below → dots only
+export const LOD_DOT_THRESHOLD     = 0.06;  // below → cluster badges
+
+/**
+ * Map a camera zoom value to an LOD tier.
+ * @param {number} zoom
+ * @returns {0|1|2|3}
+ */
+export function lodForZoom(zoom) {
+  if (zoom >= LOD_FULL_THRESHOLD)   return LOD_FULL;
+  if (zoom >= LOD_SIMPLE_THRESHOLD) return LOD_SIMPLE;
+  if (zoom >= LOD_DOT_THRESHOLD)    return LOD_DOT;
+  return LOD_CLUSTER;
+}
+
+// ---------------------------------------------------------------------------
+// Viewport culling
+// Works in canvas/screen-space: test an iso-world point against a padded
+// screen rectangle.  Call once per draw to compute the clip region, then
+// call isVisible() per object.
+//
+// cam  = { x, y, zoom }       (renderer camera object)
+// cw   = canvas CSS width
+// ch   = canvas CSS height
+// pad  = extra margin in world-units so objects at the edge aren't clipped
+//         (default: 2 tile-widths, 64px each → 128)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute an axis-aligned world-space clip rect for the current camera view.
+ * Returns { wx0, wy0, wx1, wy1 } in *world* coordinates (pre-camera transform).
+ * @param {{ x: number, y: number, zoom: number }} cam
+ * @param {number} cw  canvas CSS width
+ * @param {number} ch  canvas CSS height
+ * @param {number} [pad=128]  extra padding around the edges in world units
+ * @returns {{ wx0: number, wy0: number, wx1: number, wy1: number }}
+ */
+export function viewportClip(cam, cw, ch, pad = 128) {
+  // Screen corners → world coords: worldX = (screenX - cam.x) / cam.zoom
+  const wx0 = (0 - cam.x) / cam.zoom - pad;
+  const wy0 = (0 - cam.y) / cam.zoom - pad;
+  const wx1 = (cw - cam.x) / cam.zoom + pad;
+  const wy1 = (ch - cam.y) / cam.zoom + pad;
+  return { wx0, wy0, wx1, wy1 };
+}
+
+/**
+ * Return true if the iso-world point (wx, wy) is inside the clip rect.
+ * @param {number} wx
+ * @param {number} wy
+ * @param {{ wx0: number, wy0: number, wx1: number, wy1: number }} clip
+ * @returns {boolean}
+ */
+export function isVisible(wx, wy, clip) {
+  return wx >= clip.wx0 && wx <= clip.wx1 && wy >= clip.wy0 && wy <= clip.wy1;
+}
+
+// ---------------------------------------------------------------------------
+// Clustering
+// Group city nodes by their district and compute a single representative
+// "cluster badge" position + count.  The badge sits at the
+// district centroid in world-space.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an array of cluster descriptors from the current NODES array.
+ * Each cluster has: { districtId, label, color, count, wx, wy }
+ *
+ * @param {Array<{ d: string, bx: number, by: number }>} nodes  renderer-adapted nodes (with bx/by world pos)
+ * @param {{ [id: string]: { name: string, color: string } }} dcfg  DCFG district config
+ * @returns {Array<{ districtId: string, label: string, color: string, count: number, wx: number, wy: number }>}
+ */
+export function buildClusters(nodes, dcfg) {
+  const acc = {};
+  for (const n of nodes) {
+    const k = n.d;
+    if (!acc[k]) acc[k] = { sumX: 0, sumY: 0, count: 0 };
+    acc[k].sumX += n.bx;
+    acc[k].sumY += n.by;
+    acc[k].count++;
+  }
+  return Object.keys(acc).map(k => {
+    const a = acc[k];
+    const cfg = dcfg[k] || { name: k, color: '#7c83a3' };
+    return {
+      districtId: k,
+      label: cfg.name,
+      color: cfg.color,
+      count: a.count,
+      wx: a.sumX / a.count,
+      wy: a.sumY / a.count,
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Streaming geometry build
+// For large repos (node count >= STREAM_THRESHOLD) instead of building the
+// entire OBJ array synchronously during ingest, the renderer schedules small
+// batches of geometry across animation frames.  This function splits a nodes
+// array into fixed-size batches.
+// ---------------------------------------------------------------------------
+
+/** Minimum node count before streaming geometry build is preferred. */
+export const STREAM_THRESHOLD = 400;
+
+/** Nodes processed per animation-frame batch. */
+export const STREAM_BATCH_SIZE = 80;
+
+/**
+ * Split an array into batches of `size`.
+ * @template T
+ * @param {T[]} items
+ * @param {number} [size=STREAM_BATCH_SIZE]
+ * @returns {T[][]}
+ */
+export function makeBatches(items, size = STREAM_BATCH_SIZE) {
+  if (!Array.isArray(items)) throw new TypeError('items must be an array');
+  if (!Number.isInteger(size) || size < 1) throw new RangeError('size must be a positive integer');
+  const batches = [];
+  for (let i = 0; i < items.length; i += size) {
+    batches.push(items.slice(i, i + size));
+  }
+  return batches;
+}
+
+/**
+ * Return true when the node count warrants streaming geometry build.
+ * @param {number} nodeCount
+ * @returns {boolean}
+ */
+export function shouldStream(nodeCount) {
+  return nodeCount >= STREAM_THRESHOLD;
+}