mover-os 4.7.8 → 4.7.9

package/src/dashboard/lib/state-core/events.js

@@ -0,0 +1,265 @@
+"use strict";
+
+/**
+ * events.js — CORE-LOOP PHASE 1: the v0.2 fact vocabulary as validated
+ * constructors (SCHEMA-SPEC.md v0.2 amendments 5-8, sol-rescore-2.md
+ * blocking objections 5-8, answered). Same scope fence as event-log.js: not
+ * wired to any workflow, route, or hook in this phase.
+ *
+ * Each constructor returns a full v0.2 envelope (via event-log.makeEvent)
+ * ready to hand to event-log.appendEvent. They validate required fields and
+ * throw loudly on a malformed payload — a caller building a fact wrong
+ * should fail at construction time, not silently corrupt the log.
+ */
+
+const { makeEvent, computeDedupeKey } = require("./event-log");
+
+// TIME-SERIES facts (plan.ticked, receipt.filed, override.logged) fold their
+// ts into the dedupe basis. Payload-only dedupe silently DROPPED a re-tick
+// after an untick (identical payload -> same key -> no-op -> the projection
+// said done:false forever) and would drop a legitimately repeated receipt or
+// override on a later day. Identity facts keep payload-only dedupe: session.*
+// carry a UUID sessionId, ship.published carries receiptId (single-sourcing
+// is intentional), plan.observed is latest-wins. Retry discipline still
+// holds: a retry REUSES the built envelope (same ts, same key), and backfill
+// derives ts deterministically from the source, so re-runs still dedupe.
+// (Self-caught live repro 2026-07-11, spec amendment v0.2.2.)
+function timeSeriesDedupe(type, body, opts) {
+  if (opts.dedupeKey != null) return opts;
+  const ts = opts.ts != null ? opts.ts : Date.now();
+  return { ...opts, ts, dedupeKey: computeDedupeKey(type, { ...body, tsDiscriminator: ts }) };
+}
+
+function requireString(payload, field, typeName) {
+  const v = payload && payload[field];
+  if (typeof v !== "string" || v.length === 0) {
+    throw new Error(`events.${typeName}: payload.${field} must be a non-empty string`);
+  }
+  return v;
+}
+
+function requireBool(payload, field, typeName) {
+  const v = payload && payload[field];
+  if (typeof v !== "boolean") {
+    throw new Error(`events.${typeName}: payload.${field} must be a boolean`);
+  }
+  return v;
+}
+
+function optionalString(payload, field, typeName) {
+  const v = payload && payload[field];
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "string") throw new Error(`events.${typeName}: payload.${field}, if present, must be a string`);
+  return v;
+}
+
+function optionalNumber(payload, field, typeName) {
+  const v = payload && payload[field];
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`events.${typeName}: payload.${field}, if present, must be a finite number`);
+  return v;
+}
+
+// ── session.started / session.closed (SCHEMA-SPEC v0.2 amendment 6) ────────
+//
+// Share a stable `sessionId` (UUID). A crash before Close is later closed by
+// a `session.closed { reason:"reaped" }` written from the NEXT session's
+// start-time sweep (see findOrphanSessions / reapSession below) — this is
+// what makes session correlation survive a crash rather than leaving a
+// session open forever (objection 6).
+
+function sessionStarted(payload = {}, opts = {}) {
+  const sessionId = payload.sessionId != null ? requireString(payload, "sessionId", "sessionStarted") : (opts.sessionId || require("crypto").randomUUID());
+  const agent = requireString(payload, "agent", "sessionStarted");
+  const project = requireString(payload, "project", "sessionStarted");
+  const focus = optionalString(payload, "focus", "sessionStarted");
+  const body = { sessionId, agent, project };
+  if (focus !== undefined) body.focus = focus;
+  return makeEvent("session.started", body, opts);
+}
+
+function sessionClosed(payload = {}, opts = {}) {
+  const sessionId = requireString(payload, "sessionId", "sessionClosed");
+  const agent = requireString(payload, "agent", "sessionClosed");
+  const project = requireString(payload, "project", "sessionClosed");
+  const reason = optionalString(payload, "reason", "sessionClosed") || "closed";
+  if (reason !== "closed" && reason !== "reaped") {
+    throw new Error(`events.sessionClosed: payload.reason must be "closed" or "reaped" (got ${JSON.stringify(reason)})`);
+  }
+  const mins = optionalNumber(payload, "mins", "sessionClosed");
+  // Vault-zone policy (SCHEMA-SPEC v0.2.7, the wiring precondition from
+  // clause 17): the WRITER stamps the product-local day (the Daily Note date
+  // rule, pre-05:00 belongs to yesterday) into dateKey; ts stays the
+  // zone-free epoch truth. Reducers prefer dateKey over a UTC derivation of
+  // ts, so a rebuild on a machine in any zone reproduces the same
+  // projections. Optional: migrated/legacy closes fall back to ts.
+  const dateKey = optionalString(payload, "dateKey", "sessionClosed");
+  if (dateKey !== undefined) {
+    // Shape AND round-trip (terra wiring finding 9): Date.UTC silently
+    // normalizes impossible dates, so components must compare back.
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(dateKey);
+    const rt = m && (() => {
+      const dt = new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]));
+      return dt.getUTCFullYear() === +m[1] && dt.getUTCMonth() === +m[2] - 1 && dt.getUTCDate() === +m[3];
+    })();
+    if (!rt) throw new Error(`events.sessionClosed: payload.dateKey must be a real YYYY-MM-DD date (got ${JSON.stringify(dateKey)})`);
+  }
+  // A normal close needs a real summary; a reaped close is machine-written
+  // and gets an honest default rather than forcing a caller to fabricate one.
+  const summary = reason === "reaped" ? optionalString(payload, "summary", "sessionClosed") || "session reaped: no session.closed found before the next session.started" : requireString(payload, "summary", "sessionClosed");
+  const body = { sessionId, agent, project, reason, summary };
+  if (mins !== undefined) body.mins = mins;
+  if (dateKey !== undefined) body.dateKey = dateKey;
+  return makeEvent("session.closed", body, opts);
+}
+
+// Pure scan: given the full raw event list (log order), returns the
+// session.started events whose sessionId has no matching session.closed —
+// crashed/orphaned sessions a new Start's sweep should reap. Pure function
+// of `events`, no fs/clock access, so it composes cleanly with either a
+// fresh readEvents() result or a projections.js reduction.
+function findOrphanSessions(events) {
+  const started = new Map(); // sessionId -> first session.started event seen
+  const closed = new Set();
+  for (const e of events) {
+    if (e.type === "session.started" && e.payload && e.payload.sessionId) {
+      if (!started.has(e.payload.sessionId)) started.set(e.payload.sessionId, e);
+    } else if (e.type === "session.closed" && e.payload && e.payload.sessionId) {
+      closed.add(e.payload.sessionId);
+    }
+  }
+  const orphans = [];
+  for (const [sessionId, startEvt] of started) {
+    if (!closed.has(sessionId)) orphans.push(startEvt);
+  }
+  return orphans;
+}
+
+// Builds the reaping session.closed event for one orphaned session.started.
+function reapSession(startEvent, opts = {}) {
+  if (!startEvent || startEvent.type !== "session.started") {
+    throw new Error("events.reapSession: startEvent must be a session.started event");
+  }
+  return sessionClosed(
+    {
+      sessionId: startEvent.payload.sessionId,
+      agent: startEvent.payload.agent,
+      project: startEvent.payload.project,
+      reason: "reaped",
+    },
+    opts
+  );
+}
+
+// ── receipt.filed ────────────────────────────────────────────────────────
+
+function receiptFiled(payload = {}, opts = {}) {
+  const text = requireString(payload, "text", "receiptFiled");
+  const cat = requireString(payload, "cat", "receiptFiled");
+  const project = optionalString(payload, "project", "receiptFiled");
+  const published = requireBool(payload, "published", "receiptFiled");
+  const body = { text, cat, published };
+  if (project !== undefined) body.project = project;
+  return makeEvent("receipt.filed", body, timeSeriesDedupe("receipt.filed", body, opts));
+}
+
+// ── override.logged ─────────────────────────────────────────────────────
+
+function overrideLogged(payload = {}, opts = {}) {
+  const what = requireString(payload, "what", "overrideLogged");
+  const over = requireString(payload, "over", "overrideLogged");
+  const reason = requireString(payload, "reason", "overrideLogged");
+  const level = payload && payload.level;
+  if (typeof level !== "string" && typeof level !== "number") {
+    throw new Error("events.overrideLogged: payload.level must be a string or number");
+  }
+  const body = { what, over, reason, level };
+  return makeEvent("override.logged", body, timeSeriesDedupe("override.logged", body, opts));
+}
+
+// ── plan.ticked / plan.observed (SCHEMA-SPEC v0.2 amendment 5) ─────────────
+//
+// plan.observed is the denominator inventory: written at Start (and on plan
+// edits) so `done/total` can be derived honestly even for tasks that were
+// NEVER ticked (objection 5 — a toggle-only log can't see untouched tasks).
+// plan.ticked gains a stable `taskId`; untick emits a new event with
+// `done:false` — a state transition, not a correction (sol's answer #2).
+
+function planTicked(payload = {}, opts = {}) {
+  const taskId = requireString(payload, "taskId", "planTicked");
+  const task = requireString(payload, "task", "planTicked");
+  const noteDate = requireString(payload, "note_date", "planTicked");
+  const done = requireBool(payload, "done", "planTicked");
+  const body = { taskId, task, note_date: noteDate, done };
+  return makeEvent("plan.ticked", body, timeSeriesDedupe("plan.ticked", body, opts));
+}
+
+function planObserved(payload = {}, opts = {}) {
+  const noteDate = requireString(payload, "noteDate", "planObserved");
+  const taskIds = payload && payload.taskIds;
+  const texts = payload && payload.texts;
+  if (!Array.isArray(taskIds) || !taskIds.every((t) => typeof t === "string" && t.length > 0)) {
+    throw new Error("events.planObserved: payload.taskIds must be an array of non-empty strings");
+  }
+  if (!Array.isArray(texts) || texts.length !== taskIds.length || !texts.every((t) => typeof t === "string")) {
+    throw new Error("events.planObserved: payload.texts must be an array of strings the same length as taskIds");
+  }
+  // plan.observed is ALSO a time-series fact (sol re-score #3 refutation:
+  // re-observing inventory A after an edit to B deduped the second A against
+  // the first, leaving B as the latest plan forever). "Latest-wins" only
+  // tolerates payload-dedupe when the duplicate IS the latest; an A-B-A
+  // sequence proves it is not.
+  const body = { noteDate, taskIds: taskIds.slice(), texts: texts.slice() };
+  return makeEvent("plan.observed", body, timeSeriesDedupe("plan.observed", body, opts));
+}
+
+// ── ship.published (SCHEMA-SPEC v0.2 amendment 7) ──────────────────────────
+//
+// Carries `receiptId` so a published receipt and its ship.published event
+// are single-sourced — projections.js dedupes ships by receiptId, never
+// double-counting a receipt that both set published:true AND has a
+// ship.published (objection 7).
+
+function shipPublished(payload = {}, opts = {}) {
+  const what = requireString(payload, "what", "shipPublished");
+  const channel = requireString(payload, "channel", "shipPublished");
+  const receiptId = requireString(payload, "receiptId", "shipPublished");
+  const url = optionalString(payload, "url", "shipPublished");
+  const body = { what, channel, receiptId };
+  if (url !== undefined) body.url = url;
+  return makeEvent("ship.published", body, opts);
+}
+
+// ── event.corrected (SCHEMA-SPEC v0.2 amendment 8) ─────────────────────────
+//
+// One universal correction event. Reducers REPLACE the referenced event's
+// payload wholesale (never merge/overlay); correction-of-correction follows
+// the latest `refId` chain tip — implemented in projections.js
+// (resolveEffectiveEvents), tested for determinism there.
+
+function eventCorrected(payload = {}, opts = {}) {
+  const refId = requireString(payload, "refId", "eventCorrected");
+  const replacement = payload && payload.replacement;
+  if (replacement === null || typeof replacement !== "object" || Array.isArray(replacement)) {
+    throw new Error("events.eventCorrected: payload.replacement must be an object (the replacement payload)");
+  }
+  return makeEvent("event.corrected", { refId, replacement }, opts);
+}
+
+const FACT_TYPES = ["session.started", "session.closed", "receipt.filed", "override.logged", "plan.ticked", "plan.observed", "ship.published"];
+const CORRECTION_TYPE = "event.corrected";
+
+module.exports = {
+  FACT_TYPES,
+  CORRECTION_TYPE,
+  sessionStarted,
+  sessionClosed,
+  findOrphanSessions,
+  reapSession,
+  receiptFiled,
+  overrideLogged,
+  planTicked,
+  planObserved,
+  shipPublished,
+  eventCorrected,
+};

package/src/dashboard/lib/state-core/projections.js

@@ -0,0 +1,376 @@
+"use strict";
+
+/**
+ * projections.js — CORE-LOOP PHASE 1: the four v0.2 projections (metrics,
+ * streak, bet, drift) as pure reducers over the event log, plus correction
+ * resolution (SCHEMA-SPEC.md v0.2 amendment 8 / sol-rescore-2.md objection
+ * 8). Same scope fence as event-log.js / events.js: not wired to any route
+ * or dashboard render in this phase.
+ *
+ * Determinism (SCHEMA-SPEC.md v0.2 amendment 3 / objection 2, answered): the
+ * canonical HASHED body carries `throughEventId` + `throughEventTs` (a pure
+ * function of the events replayed); `rebuiltAt` is wall-clock operational
+ * metadata and lives OUTSIDE the hashed body, as a sibling field on the
+ * returned envelope. Three calls to rebuildProjections() over an unchanged
+ * log must produce the same hash regardless of when each call happened.
+ */
+
+const fs = require("fs");
+const crypto = require("crypto");
+const { readEvents, parseLog, stableStringify, sha256Hex } = require("./event-log");
+
+const PROJECTION_VERSION = 1;
+const DEFAULT_DRIFT_LAST_N = 5;
+
+// ── correction resolution (objection 8) ─────────────────────────────────
+//
+// `event.corrected { refId, replacement }` REPLACES the referenced event's
+// payload wholesale. A correction can itself be corrected — refId then
+// points at the earlier correction's own id, not the original fact — so
+// resolution walks the chain to its tip. Multiple corrections landing on the
+// same target (direct re-corrections, not a chain) resolve to whichever one
+// is LATEST in log order.
+
+function indexCorrections(events) {
+  // targetId -> [event.corrected events in log order] that named it directly
+  const targets = new Map();
+  for (const e of events) {
+    if (e.type !== "event.corrected") continue;
+    const refId = e.payload && e.payload.refId;
+    if (!refId) continue;
+    if (!targets.has(refId)) targets.set(refId, []);
+    targets.get(refId).push(e);
+  }
+  return { targets };
+}
+
+function effectivePayload(eventId, originalPayload, index) {
+  let current = eventId;
+  let payload = originalPayload;
+  const visited = new Set([current]);
+  while (index.targets.has(current)) {
+    const corrections = index.targets.get(current);
+    const winner = corrections[corrections.length - 1]; // latest in log order wins at this hop
+    payload = winner.payload.replacement;
+    current = winner.id;
+    if (visited.has(current)) break; // cycle guard; should never happen with real UUIDs
+    visited.add(current);
+  }
+  return payload;
+}
+
+// Returns a new array: `event.corrected` entries removed (they are
+// operators, not facts to fold on their own), every corrected fact's payload
+// swapped for its resolved effective payload, everything else untouched.
+// Pure function of `events` (log order in, same order out minus corrections).
+function resolveEffectiveEvents(events) {
+  const index = indexCorrections(events);
+  const out = [];
+  for (const e of events) {
+    if (e.type === "event.corrected") continue;
+    const payload = effectivePayload(e.id, e.payload, index);
+    out.push(payload === e.payload ? e : Object.assign({}, e, { payload }));
+  }
+  return out;
+}
+
+// ── date helpers (pure functions of ts; UTC, never wall-clock "now") ──────
+
+function dateKeyFromTs(ts) {
+  return new Date(ts).toISOString().slice(0, 10); // YYYY-MM-DD, UTC
+}
+
+// A dateKey is valid only if it ROUND-TRIPS: right shape AND a calendar date
+// that exists (Date.UTC normalizes "2031-13-40" to 2032-02-09, so components
+// must be compared back). Terra wiring finding 9.
+function validDateKey(dk) {
+  if (typeof dk !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(dk)) return false;
+  const [y, m, d] = dk.split("-").map(Number);
+  const dt = new Date(Date.UTC(y, m - 1, d));
+  return dt.getUTCFullYear() === y && dt.getUTCMonth() === m - 1 && dt.getUTCDate() === d;
+}
+
+function daysBetween(aDateKey, bDateKey) {
+  const [ay, am, ad] = aDateKey.split("-").map(Number);
+  const [by, bm, bd] = bDateKey.split("-").map(Number);
+  const a = Date.UTC(ay, am - 1, ad);
+  const b = Date.UTC(by, bm - 1, bd);
+  return Math.round((b - a) / 86400000);
+}
+
+// ── metrics projection (objections 5 and 7) ────────────────────────────
+
+function computeMetrics(events) {
+  const byDate = {}; // dateKey(ts) -> { receipts, ships, overrides }
+  const shipReceiptSeenByDate = {}; // dateKey -> Set(receiptId) for the ship dedupe
+  const observedByNoteDate = {}; // noteDate -> { taskIds, atTs } — latest plan.observed wins
+  const tickedState = {}; // `${note_date}::${taskId}` -> last-write-wins done boolean
+
+  function ensureDate(d) {
+    if (!byDate[d]) byDate[d] = { receipts: 0, ships: 0, overrides: 0 };
+    return byDate[d];
+  }
+
+  for (const e of events) {
+    if (e.type === "receipt.filed") {
+      ensureDate(dateKeyFromTs(e.ts)).receipts += 1;
+    } else if (e.type === "ship.published") {
+      const d = dateKeyFromTs(e.ts);
+      const receiptId = e.payload && e.payload.receiptId;
+      if (!shipReceiptSeenByDate[d]) shipReceiptSeenByDate[d] = new Set();
+      // A published receipt and its ship.published event are single-sourced
+      // by receiptId (objection 7): the same receiptId shipped twice on the
+      // same date counts once, never inflating the ships tally.
+      if (!shipReceiptSeenByDate[d].has(receiptId)) {
+        shipReceiptSeenByDate[d].add(receiptId);
+        ensureDate(d).ships += 1;
+      }
+    } else if (e.type === "override.logged") {
+      ensureDate(dateKeyFromTs(e.ts)).overrides += 1;
+    } else if (e.type === "plan.observed") {
+      const noteDate = e.payload.noteDate;
+      const prev = observedByNoteDate[noteDate];
+      // Latest plan.observed per noteDate wins (a plan edit re-inventories
+      // the day); ties broken by log position (later in `events` wins).
+      if (!prev || e.ts >= prev.atTs) {
+        observedByNoteDate[noteDate] = { taskIds: e.payload.taskIds.slice(), atTs: e.ts };
+      }
+    } else if (e.type === "plan.ticked") {
+      const key = `${e.payload.note_date}::${e.payload.taskId}`;
+      tickedState[key] = e.payload.done; // last write in log order wins — a toggle, not a merge
+    }
+  }
+
+  // done/total derives from plan.observed (denominator) + plan.ticked
+  // (numerator), including tasks that were NEVER ticked (objection 5) —
+  // those default to not-done rather than being invisible.
+  const ticksByNoteDate = {};
+  for (const noteDate of Object.keys(observedByNoteDate)) {
+    const { taskIds } = observedByNoteDate[noteDate];
+    let done = 0;
+    for (const taskId of taskIds) {
+      if (tickedState[`${noteDate}::${taskId}`] === true) done += 1;
+    }
+    ticksByNoteDate[noteDate] = { done, total: taskIds.length };
+  }
+
+  return { byDate, ticksByNoteDate };
+}
+
+// ── streak projection ────────────────────────────────────────────────────
+//
+// "Logging" activity = session.closed (the /log workflow's fact). A
+// projection must be a PURE function of the events it folds — it cannot
+// reference wall-clock "today" without breaking rebuild determinism across
+// calendar days — so `current` is the run ending at the MOST RECENT active
+// date found IN THE LOG, not real-world today. `asOfDate` makes that
+// reference point explicit to any caller who needs to reconcile it against
+// wall-clock "today" themselves.
+
+function computeStreak(events) {
+  // ONE close per session: a grace-window false reap followed by the real
+  // Close produced two session.closed events for one session and inflated
+  // the streak by a day (terra re-verdict #5). The LAST close per sessionId
+  // in log order wins - the real close supersedes an earlier reap; an event
+  // without a sessionId (foreign/legacy) still counts individually.
+  const lastCloseBySession = new Map();
+  const anonymous = [];
+  for (const e of events) {
+    if (e.type !== "session.closed") continue;
+    const sid = e.payload && e.payload.sessionId;
+    if (sid) lastCloseBySession.set(sid, e);
+    else anonymous.push(e);
+  }
+  const dateSet = new Set();
+  for (const e of [...lastCloseBySession.values(), ...anonymous]) {
+    // Vault-zone policy (SCHEMA-SPEC v0.2.7): a live-wired close carries the
+    // product-local day in payload.dateKey (writer-stamped, zone-stable
+    // across rebuild machines). Migrated/legacy closes fall back to the UTC
+    // derivation of ts, which is zone-safe for their noon-anchored stamps.
+    // Round-trip validated, not just shape (terra wiring finding 9: a
+    // hand-written "2031-13-40" passed the regex and Date.UTC silently
+    // normalized it into a phantom streak day). An impossible date falls
+    // back to ts like any other malformed payload.
+    const dk = e.payload && validDateKey(e.payload.dateKey) ? e.payload.dateKey : dateKeyFromTs(e.ts);
+    dateSet.add(dk);
+  }
+  const sorted = [...dateSet].sort(); // ISO YYYY-MM-DD sorts lexicographically == chronologically
+  if (sorted.length === 0) {
+    return { current: 0, best: 0, coverage: 0, activeDays: 0, spanDays: 0, asOfDate: null };
+  }
+
+  let best = 1;
+  let run = 1;
+  for (let i = 1; i < sorted.length; i++) {
+    run = daysBetween(sorted[i - 1], sorted[i]) === 1 ? run + 1 : 1;
+    if (run > best) best = run;
+  }
+
+  let current = 1;
+  for (let i = sorted.length - 1; i > 0; i--) {
+    if (daysBetween(sorted[i - 1], sorted[i]) === 1) current += 1;
+    else break;
+  }
+
+  const spanDays = daysBetween(sorted[0], sorted[sorted.length - 1]) + 1;
+  const coverage = spanDays > 0 ? sorted.length / spanDays : 0;
+
+  return { current, best, coverage, activeDays: sorted.length, spanDays, asOfDate: sorted[sorted.length - 1] };
+}
+
+// ── bet projection ──────────────────────────────────────────────────────
+//
+// Honesty contract (SCHEMA-SPEC.md section 2): activated-install / referral
+// counts stay MANUAL/owner-fed — nothing in the six fact types asserts them,
+// so this projection aggregates only what events actually assert (shipped
+// artifacts, filed receipts) and says so explicitly rather than fabricating
+// a bet-progress number the log cannot support.
+
+function computeBet(events) {
+  const shipReceiptIds = new Set();
+  let receiptsCount = 0;
+  for (const e of events) {
+    if (e.type === "ship.published" && e.payload && e.payload.receiptId != null) {
+      shipReceiptIds.add(e.payload.receiptId); // deduped, matches computeMetrics' ships tally
+    } else if (e.type === "receipt.filed") {
+      receiptsCount += 1;
+    }
+  }
+  return {
+    shipsCount: shipReceiptIds.size,
+    receiptsCount,
+    note: "activated-install / referral counts are owner-fed manually, not derived from events (SCHEMA-SPEC.md section 2 honesty contract)",
+  };
+}
+
+// ── drift projection ────────────────────────────────────────────────────
+
+function computeDrift(events, opts = {}) {
+  const lastN = opts.lastN != null ? opts.lastN : DEFAULT_DRIFT_LAST_N;
+  const overrides = events.filter((e) => e.type === "override.logged");
+  const byLevel = {};
+  for (const e of overrides) {
+    const level = String(e.payload.level);
+    byLevel[level] = (byLevel[level] || 0) + 1;
+  }
+  const lastNEntries = overrides.slice(-lastN).map((e) => ({
+    id: e.id,
+    ts: e.ts,
+    what: e.payload.what,
+    over: e.payload.over,
+    reason: e.payload.reason,
+    level: e.payload.level,
+  }));
+  return { total: overrides.length, byLevel, lastN: lastNEntries };
+}
+
+// ── rebuild ─────────────────────────────────────────────────────────────
+
+// Reads the log fresh from disk, resolves corrections, folds all four
+// projections, and returns { rebuiltAt, hash, body }. `rebuiltAt` is outside
+// the hashed body (operational metadata, objection 2); `body.throughEventId`
+// / `body.throughEventTs` are the deterministic watermark INSIDE the hashed
+// body, taken from the last RAW event in the log (including any trailing
+// event.corrected — the watermark tracks log position, not fact count).
+// Pure reduction from an already-parsed event set to the projection body +
+// hash. Factored out of rebuildProjections so readVerifiedState can reduce
+// from a CAPTURED buffer (not a fresh read), which is what closes the
+// A->B->A window sol named: the reduction must be of the exact bytes we
+// verified, never a separate read that could have caught an interleaved B.
+function reduceToBody(events, opts = {}) {
+  const effective = resolveEffectiveEvents(events);
+  const last = events.length ? events[events.length - 1] : null;
+  const body = {
+    v: PROJECTION_VERSION,
+    throughEventId: last ? last.id : null,
+    throughEventTs: last ? last.ts : null,
+    eventCount: effective.length,
+    metrics: computeMetrics(effective),
+    streak: computeStreak(effective),
+    bet: computeBet(effective),
+    drift: computeDrift(effective, opts.driftLastN != null ? { lastN: opts.driftLastN } : {}),
+  };
+  return { body, hash: sha256Hex(stableStringify(body)) };
+}
+
+function rebuildProjections(logPath, opts = {}) {
+  const { events, quarantined } = readEvents(logPath, opts);
+  const { body, hash } = reduceToBody(events, opts);
+  const rebuiltAt = typeof opts.now === "function" ? opts.now() : Date.now();
+
+  return { rebuiltAt, hash, body, quarantinedCount: quarantined.length };
+}
+
+// readVerifiedState — the check-then-use read path terra round 3 required
+// (SCHEMA-SPEC v0.2.5 clause 29). readEvents/rebuildProjections validate
+// envelope SHAPE and reduce, but a consumer that will ACT on the state needs
+// stronger assurance that what it reduced is what is on disk at the moment
+// of use. This does three things the plain rebuild does not:
+//
+//   1. Reads the raw log as a Buffer and reduces THAT captured buffer (event
+//      + reducer integrity). Reducing the captured bytes, not a fresh read,
+//      is what closes the A->B->A window sol #5 named: a separate middle read
+//      could reduce an interleaved B while the two outer reads both saw A.
+//   2. Reads the raw buffer a SECOND time and compares the two as BYTES
+//      (Buffer.equals, not a utf8-decoded string). A utf8 compare let an
+//      invalid-byte change decode identically (the same lossy-decode class
+//      terra caught in the apply path); byte comparison catches it. Any write
+//      landing between the reads makes verified:false with reason
+//      "log-mutated-during-read", and the caller retries rather than acting on
+//      a torn/stale snapshot. Honest bound: it cannot stop a writer who
+//      mutates strictly AFTER the second read (terra confirmed that residual
+//      is not cheaply solvable in userspace).
+//   3. When the caller supplies expectHash (e.g. the hash stored in a
+//      persisted projection file), cross-checks the fresh reduction against
+//      it so a stale or tampered stored projection is caught before use.
+//
+// Returns { verified, reason, hash, body, rawSha, quarantinedCount,
+// eventCount }. verified:false is a signal to retry or refuse, never to
+// proceed on the returned body.
+function readVerifiedState(logPath, opts = {}) {
+  const fsImpl = opts.fs || fs;
+  const bufOf = (p) => {
+    try {
+      const b = fsImpl.readFileSync(p); // no encoding => Buffer
+      return Buffer.isBuffer(b) ? b : Buffer.from(String(b), "utf8");
+    } catch (e) {
+      if (e.code === "ENOENT") return Buffer.alloc(0);
+      throw e;
+    }
+  };
+
+  const buf1 = bufOf(logPath);
+  // Reduce the CAPTURED buffer, never a fresh read (A->B->A close).
+  const { events, quarantined } = parseLog(buf1.toString("utf8"));
+  const { body, hash } = reduceToBody(events, opts);
+  const buf2 = bufOf(logPath);
+
+  const rawSha = crypto.createHash("sha256").update(buf1).digest("hex");
+  const result = (verified, reason) => ({
+    verified,
+    reason,
+    hash,
+    body,
+    rawSha,
+    quarantinedCount: quarantined.length,
+    eventCount: body.eventCount,
+  });
+
+  // Byte-exact comparison: catches invalid-byte edits a utf8 compare masks.
+  if (!buf1.equals(buf2)) return result(false, "log-mutated-during-read");
+  if (opts.expectHash != null && opts.expectHash !== hash) return result(false, "projection-hash-mismatch");
+  return result(true, null);
+}
+
+module.exports = {
+  PROJECTION_VERSION,
+  resolveEffectiveEvents,
+  dateKeyFromTs,
+  daysBetween,
+  computeMetrics,
+  computeStreak,
+  computeBet,
+  computeDrift,
+  rebuildProjections,
+  readVerifiedState,
+};