mover-os 4.7.8 → 4.7.10

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

@@ -0,0 +1,188 @@
+"use strict";
+
+// dryrun.js — CORE-LOOP PHASE 2 (SCHEMA-SPEC v0.2 section 4, steps 2-3).
+// The migration contract the owner inspects BEFORE anything touches a live
+// vault: predictState computes the exact bytes a migration would write
+// (events.jsonl + the four projection files) WITHOUT writing; applyState
+// writes them to a pristine copy, re-reads every file from disk, and throws
+// unless predicted and actual sha256 match byte-for-byte. The manifest is
+// the lab's dry-run.js pattern promoted to the product path.
+//
+// Determinism: the caller captures ONE `now` and passes it to both predict
+// and apply (rebuiltAt is operational metadata outside the hashed projection
+// body, but it is inside the FILE bytes, so byte-identity needs the same
+// clock reading). Event ids are fresh UUIDs per backfill run, so the
+// manifest binds one run's events to one run's files — rerunning backfill
+// produces the same dedupeKeys and facts, not the same ids.
+
+const fs = require("fs");
+const path = require("path");
+const { serializeEnvelope, sha256Hex, stableStringify, isValidEnvelope, acquireLock } = require("./event-log");
+const { resolveEffectiveEvents, computeMetrics, computeStreak, computeBet, computeDrift, rebuildProjections, PROJECTION_VERSION } = require("./projections");
+
+const STATE_DIR = path.join("02_Areas", "Engine", "State");
+const LOG_NAME = "events.jsonl";
+const PROJECTION_NAMES = {
+  metrics: "projection-metrics.json",
+  streak: "projection-streak.json",
+  bet: "projection-bet.json",
+  drift: "projection-drift.json",
+};
+
+// One projection file's content. The hashed body carries the deterministic
+// watermark (v0.2 amendment 3: throughEventId/throughEventTs inside, never
+// rebuiltAt); `hash` must reproduce across rebuilds of the same log.
+function projectionFileBody(kind, data, watermark, eventCount) {
+  return {
+    v: PROJECTION_VERSION,
+    kind,
+    throughEventId: watermark.id,
+    throughEventTs: watermark.ts,
+    eventCount,
+    data,
+  };
+}
+
+function projectionFileText(kind, data, watermark, eventCount, rebuiltAt) {
+  const body = projectionFileBody(kind, data, watermark, eventCount);
+  const hash = sha256Hex(stableStringify(body));
+  // rebuiltAt and hash sit OUTSIDE the hashed body; stableStringify keeps
+  // the bytes reproducible for identical inputs.
+  return stableStringify({ rebuiltAt, hash, body }) + "\n";
+}
+
+// Predicts every byte a migration write would produce. Pure of the target
+// filesystem: takes the events, returns { files: [{file, bytes, sha256}] }.
+function predictState(events, { now } = {}) {
+  if (!Array.isArray(events) || !events.every((e) => isValidEnvelope(e))) {
+    throw new Error("dryrun.predictState: events must all be valid v0.2 envelopes");
+  }
+  if (typeof now !== "number") {
+    throw new Error("dryrun.predictState: opts.now (epoch ms) is required: predict and apply must share one clock reading for byte identity");
+  }
+
+  const logText = events.map((e) => serializeEnvelope(e) + "\n").join("");
+
+  const effective = resolveEffectiveEvents(events);
+  const last = events.length ? events[events.length - 1] : null;
+  const watermark = { id: last ? last.id : null, ts: last ? last.ts : null };
+  const eventCount = effective.length;
+
+  const data = {
+    metrics: computeMetrics(effective),
+    streak: computeStreak(effective),
+    bet: computeBet(effective),
+    drift: computeDrift(effective, {}),
+  };
+
+  const files = [{ file: path.join(STATE_DIR, LOG_NAME), text: logText }];
+  for (const [kind, name] of Object.entries(PROJECTION_NAMES)) {
+    files.push({ file: path.join(STATE_DIR, name), text: projectionFileText(kind, data[kind], watermark, eventCount, now) });
+  }
+
+  return {
+    files: files.map((f) => ({ file: f.file, bytes: Buffer.byteLength(f.text, "utf8"), sha256: sha256Hex(f.text), text: f.text })),
+  };
+}
+
+// Writes the predicted state onto a vault COPY and verifies byte identity by
+// re-reading RAW BUFFERS from disk (a utf8-decode round trip can mask an
+// invalid byte, terra attack 3). Refuses a non-pristine target; the whole
+// check-write-verify sequence runs under the log's own advisory lock so two
+// concurrent migrations cannot both pass the pristine check (terra attack 4),
+// and an `.applying` marker makes a crash mid-write recoverable: a rerun
+// that finds the marker knows the previous apply never completed and clears
+// the partial State files instead of refusing forever.
+//
+// SCOPE (terra re-verdict #3, acknowledged not patched): verification is
+// point-in-time. The lock binds every COOPERATIVE state-core writer; a
+// hostile direct filesystem writer can always mutate a file between the last
+// check and the caller's next read - no userspace check-then-return closes
+// that. The durable integrity token is IN each file: every projection
+// carries its own body hash, and the log's lines are self-validating
+// envelopes, so a READER can re-verify at read time. verified:true means
+// "the bytes I wrote were the bytes on disk when I looked", nothing more.
+function applyState(vaultRoot, events, { now } = {}) {
+  const predicted = predictState(events, { now });
+  const logAbs = path.join(vaultRoot, STATE_DIR, LOG_NAME);
+  const applyingMarker = path.join(vaultRoot, STATE_DIR, ".applying");
+
+  fs.mkdirSync(path.dirname(logAbs), { recursive: true });
+  const lock = acquireLock(logAbs);
+  try {
+    if (fs.existsSync(applyingMarker)) {
+      // A previous apply crashed mid-write: everything under State/ from
+      // that run is unpublished garbage. Clear exactly the files we own.
+      for (const f of predicted.files) {
+        try { fs.rmSync(path.join(vaultRoot, f.file), { force: true }); } catch (_) {}
+      }
+      fs.rmSync(applyingMarker, { force: true });
+    }
+    if (fs.existsSync(logAbs)) {
+      throw new Error(`dryrun.applyState: ${logAbs} already exists. applyState only writes to a pristine copy, never over an existing log`);
+    }
+
+    fs.writeFileSync(applyingMarker, JSON.stringify({ pid: process.pid, startedAt: now }), "utf8");
+    for (const f of predicted.files) {
+      fs.writeFileSync(path.join(vaultRoot, f.file), f.text, "utf8");
+    }
+
+    const mismatches = [];
+    const manifest = predicted.files.map((f) => {
+      const actualBuf = fs.readFileSync(path.join(vaultRoot, f.file)); // raw Buffer, no decode
+      const actual = cryptoSha(actualBuf);
+      if (actual !== f.sha256 || actualBuf.length !== f.bytes) {
+        mismatches.push({ file: f.file, predicted: f.sha256, actual, predictedBytes: f.bytes, actualBytes: actualBuf.length });
+      }
+      return { file: f.file, bytes: f.bytes, sha256: f.sha256, actual };
+    });
+
+    if (mismatches.length) {
+      throw new Error(`dryrun.applyState: predicted vs actual bytes diverge for ${mismatches.map((m) => m.file).join(", ")}. Do not proceed to a live vault`);
+    }
+
+    // Cross-check the file assembly against the product reducer itself: the
+    // rebuilt projection HASH (the full reduced body, not just the watermark
+    // id — terra attack 3b showed a mid-window event mutation slipping past
+    // an id-only check) must be reproducible from the bytes on disk.
+    const rebuilt = rebuildProjections(logAbs, { now: () => now });
+    const last = events.length ? events[events.length - 1] : null;
+    if ((rebuilt.body.throughEventId || null) !== (last ? last.id : null)) {
+      throw new Error("dryrun.applyState: rebuildProjections watermark disagrees with the written log: dryrun assembly has drifted from the reducer");
+    }
+    const effective = resolveEffectiveEvents(events);
+    const expectedBody = {
+      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, {}),
+    };
+    if (rebuilt.hash !== sha256Hex(stableStringify(expectedBody))) {
+      throw new Error("dryrun.applyState: the reducer's rebuilt hash does not match the predicted reduction. Do not proceed to a live vault");
+    }
+
+    fs.rmSync(applyingMarker, { force: true });
+    return { manifest: manifest.map(({ file, bytes, sha256 }) => ({ file, bytes, sha256 })), verified: true, rebuiltHash: rebuilt.hash };
+  } finally {
+    lock.release();
+  }
+}
+
+// Raw-buffer sha256 (predictState hashes the utf8 TEXT, which encodes to the
+// same bytes it writes; verification must hash what is actually on disk).
+function cryptoSha(buf) {
+  return require("crypto").createHash("sha256").update(buf).digest("hex");
+}
+
+module.exports = {
+  STATE_DIR,
+  LOG_NAME,
+  PROJECTION_NAMES,
+  projectionFileText,
+  predictState,
+  applyState,
+};