knosky 0.4.1 → 0.6.0

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;
+}