knosky 0.6.3 → 0.7.0

package/core/layout.mjs

@@ -1,46 +1,46 @@
-// Deterministic N-category city layout (Phase 2b). Implements locked D3:
-// stable order (category manifest order), each district a square sized to hold its nodes,
-// districts shelf-packed into a roughly square city. Recompute is deterministic (same data -> same layout).
-export function layoutCity(city, opts = {}) {
-  const PAD = opts.pad ?? 1;   // building-cells of padding inside a district
-  const GAP = opts.gap ?? 2;   // building-cells between districts
-
-  const cats = (city.categories || []).slice().sort((a, b) => a.order - b.order);
-  const byCat = new Map(cats.map(c => [c.id, []]));
-  for (const n of city.nodes || []) {
-    if (!byCat.has(n.category)) byCat.set(n.category, []);   // tolerate uncategorized
-    byCat.get(n.category).push(n);
-  }
-  // ensure any extra categories (not in manifest) still get a district, appended in id order
-  const extra = [...byCat.keys()].filter(id => !cats.find(c => c.id === id)).sort();
-  const order = [...cats.map(c => ({ id: c.id, label: c.label, color: c.color })),
-                 ...extra.map(id => ({ id, label: id, color: '#888' }))];
-
-  const districts = order.map((c, i) => {
-    const nodes = byCat.get(c.id) || [];
-    const side = Math.max(1, Math.ceil(Math.sqrt(nodes.length || 1)));
-    return { id: c.id, label: c.label, color: c.color, idx: i, nodes, side, w: side + PAD * 2, h: side + PAD * 2 };
-  });
-
-  const totalArea = districts.reduce((a, d) => a + d.w * d.h, 0);
-  const rowTarget = Math.max(Math.max(...districts.map(d => d.w)), Math.ceil(Math.sqrt(totalArea)));
-
-  const placed = [];
-  let x = 0, y = 0, rowH = 0;
-  for (const d of districts) {
-    if (x > 0 && x + d.w > rowTarget) { x = 0; y += rowH + GAP; rowH = 0; }
-    d.x = x; d.y = y; rowH = Math.max(rowH, d.h);
-    d.nodes.forEach((n, i) => {
-      placed.push({
-        id: n.id, title: n.title, category: n.category, kind: n.kind,
-        gx: d.x + PAD + (i % d.side),
-        gy: d.y + PAD + Math.floor(i / d.side),
-        ref: n.provenance ? n.provenance.ref : null,
-      });
-    });
-    x += d.w + GAP;
-  }
-  const gridW = Math.max(1, ...placed.map(p => p.gx + 1), ...districts.map(d => d.x + d.w));
-  const gridH = Math.max(1, ...placed.map(p => p.gy + 1), ...districts.map(d => d.y + d.h));
-  return { districts, nodes: placed, gridW, gridH };
-}
+// Deterministic N-category city layout (Phase 2b). Implements locked D3:
+// stable order (category manifest order), each district a square sized to hold its nodes,
+// districts shelf-packed into a roughly square city. Recompute is deterministic (same data -> same layout).
+export function layoutCity(city, opts = {}) {
+  const PAD = opts.pad ?? 1;   // building-cells of padding inside a district
+  const GAP = opts.gap ?? 2;   // building-cells between districts
+
+  const cats = (city.categories || []).slice().sort((a, b) => a.order - b.order);
+  const byCat = new Map(cats.map(c => [c.id, []]));
+  for (const n of city.nodes || []) {
+    if (!byCat.has(n.category)) byCat.set(n.category, []);   // tolerate uncategorized
+    byCat.get(n.category).push(n);
+  }
+  // ensure any extra categories (not in manifest) still get a district, appended in id order
+  const extra = [...byCat.keys()].filter(id => !cats.find(c => c.id === id)).sort();
+  const order = [...cats.map(c => ({ id: c.id, label: c.label, color: c.color })),
+                 ...extra.map(id => ({ id, label: id, color: '#888' }))];
+
+  const districts = order.map((c, i) => {
+    const nodes = byCat.get(c.id) || [];
+    const side = Math.max(1, Math.ceil(Math.sqrt(nodes.length || 1)));
+    return { id: c.id, label: c.label, color: c.color, idx: i, nodes, side, w: side + PAD * 2, h: side + PAD * 2 };
+  });
+
+  const totalArea = districts.reduce((a, d) => a + d.w * d.h, 0);
+  const rowTarget = Math.max(Math.max(...districts.map(d => d.w)), Math.ceil(Math.sqrt(totalArea)));
+
+  const placed = [];
+  let x = 0, y = 0, rowH = 0;
+  for (const d of districts) {
+    if (x > 0 && x + d.w > rowTarget) { x = 0; y += rowH + GAP; rowH = 0; }
+    d.x = x; d.y = y; rowH = Math.max(rowH, d.h);
+    d.nodes.forEach((n, i) => {
+      placed.push({
+        id: n.id, title: n.title, category: n.category, kind: n.kind,
+        gx: d.x + PAD + (i % d.side),
+        gy: d.y + PAD + Math.floor(i / d.side),
+        ref: n.provenance ? n.provenance.ref : null,
+      });
+    });
+    x += d.w + GAP;
+  }
+  const gridW = Math.max(1, ...placed.map(p => p.gx + 1), ...districts.map(d => d.x + d.w));
+  const gridH = Math.max(1, ...placed.map(p => p.gy + 1), ...districts.map(d => d.y + d.h));
+  return { districts, nodes: placed, gridW, gridH };
+}

package/core/ledger.mjs

@@ -1,141 +1,176 @@
-// 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 };
-}
+// 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';
+import { openCheckpoint, appendCheckpointEntry } from './append-only-checkpoint.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: sibling temp + rename (SAT-474).
+  const tmp = hwmPath + '.tmp';
+  writeFileSync(tmp, JSON.stringify({ ledger_hwm: seq }) + '\n', 'utf8');
+  // Best-effort fsync: Windows TEMP often returns EPERM; full write + rename still atomic.
+  try {
+    const tmpFd = openSync(tmp, 'r');
+    try {
+      fsyncSync(tmpFd);
+    } finally {
+      closeSync(tmpFd);
+    }
+  } catch {
+    /* EPERM / unsupported */
+  }
+  renameSync(tmp, hwmPath);
+  try {
+    const dirFd = openSync(dir, 'r');
+    try {
+      fsyncSync(dirFd);
+    } finally {
+      closeSync(dirFd);
+    }
+  } catch {
+    /* best-effort directory fsync (often unsupported on Windows) */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+ *
+ * When `checkpointPath` is supplied, every accepted write is also appended to
+ * the append-only secondary checkpoint file (SAT-561 / F0.2b).  The checkpoint
+ * write is best-effort: any error is swallowed so that a checkpoint failure
+ * never blocks the primary HWM write.  `openCheckpoint` is called once per
+ * path on first use (idempotent; no-op on subsequent calls).
+ *
+ * @param {number} seq                   Claimed sequence number from the incoming ledger state.
+ * @param {string} hwmPath               Path to the independently-persisted HWM file.
+ * @param {string} [checkpointPath]      Optional path to the append-only JSONL checkpoint file.
+ * @returns {{ ok: boolean, seq: number, hwm: number, checkpoint_ok: boolean | null, checkpoint_error: string | null, 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, checkpointPath) {
+  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);
+
+  // SAT-561 (F0.2b): secondary append-only checkpoint write — best-effort,
+  // never blocks or fails the primary HWM write.
+  let checkpoint_ok = null;
+  let checkpoint_error = null;
+  if (checkpointPath !== undefined && checkpointPath !== null) {
+    try {
+      openCheckpoint(checkpointPath);
+      appendCheckpointEntry(checkpointPath, {
+        seq,
+        event: 'ledger_state',
+        ts: new Date().toISOString(),
+        hwm_previously: hwm,
+      });
+      checkpoint_ok = true;
+    } catch (err) {
+      // best-effort — checkpoint failure must not affect the primary write
+      checkpoint_ok = false;
+      checkpoint_error = err.message || null;
+    }
+  }
+
+  return { ok: true, seq, hwm, checkpoint_ok, checkpoint_error };
+}