mover-os 4.7.8 → 4.7.9

package/src/dashboard/lib/state-core/event-log.js

@@ -0,0 +1,615 @@
+"use strict";
+
+/**
+ * event-log.js — CORE-LOOP PHASE 1: the production event store.
+ *
+ * Scope fence (qa/campaign-2026-07/core-loop/SCHEMA-SPEC.md, task brief):
+ * this module is NOT wired to any workflow, server route, dashboard render,
+ * or hook. It is a standalone product-path library exercised only by its own
+ * tests until phase 2 wires a caller. Never point it at a real vault path
+ * outside tests.
+ *
+ * Envelope (SCHEMA-SPEC.md v0.2 amendments 1-2, sol-rescore-2.md blocking
+ * objections 1-2, answered):
+ *   { v:1, id:<UUID>, ts:<epoch-ms number>, type:<string>, payload:<object>,
+ *     dedupeKey:<sha256 hex>, source?:{path,sourceHash,parserVersion,locator} }
+ *
+ *   - `ts` is frozen as an epoch-ms NUMBER (objection 1). The v0.1 draft's
+ *     "ISO string with zone" contradicted the lab validator and is dead.
+ *     Rendering to a display format happens at the UI edge, never here.
+ *   - `id` is opaque event identity (a fresh UUID by default) — NOT a
+ *     content hash. Two independently-real events can share content.
+ *   - `dedupeKey` is the full sha256 of canonical `{type, payload}` (ts and
+ *     id excluded on purpose — sol's answer #1: "including a changing
+ *     timestamp in the content prevents retry deduplication"). Two retries
+ *     of the SAME logical fact collapse to one append; this is a deliberate
+ *     idempotency contract, not a hashing accident — see events.js.
+ *   - `source` is REQUIRED by migration code (phase 2+, not built here) on
+ *     backfilled events, optional on native live events. This module only
+ *     validates its SHAPE when present; it does not enforce presence, since
+ *     that policy differs by call site.
+ *
+ * Append strategy (SCHEMA-SPEC.md v0.2 amendment 4, objection 3 answered):
+ * the state-lab spike (test/state-lab/lib/event-log.js) rewrites the WHOLE
+ * log to a temp file and renames over the target on every append — O(n)
+ * write cost, explicitly flagged by the spike's own comments as unfit for
+ * forever retention. This module instead:
+ *   1. Takes an exclusive advisory lock (a sibling `<log>.lock` file created
+ *      with O_EXCL; stale locks — dead pid or past a TTL — are reaped and
+ *      retried, so a crashed holder can never wedge the log forever).
+ *   2. Reads the log ONCE to check for a duplicate `id`/`dedupeKey` (a read,
+ *      not a rewrite — the cost the spike's own comment calls out is the
+ *      WRITE, and dedup honesty requires seeing what's already there).
+ *   3. Appends exactly one line via `fs.appendFileSync` (flag 'a' ==
+ *      O_WRONLY|O_CREAT|O_APPEND) — a single write() syscall that extends
+ *      the file in place. The target path's inode never changes and no byte
+ *      already on disk is ever rewritten. This is the O(1) part: proven in
+ *      test/state-core.test.mjs by asserting the inode and the leading bytes
+ *      of the file are IDENTICAL before and after thousands of further
+ *      appends (a stronger, non-flaky proof than a timing benchmark).
+ *   4. Releases the lock.
+ *
+ * The quarantine reader (torn-tail / corrupt-line / duplicate-id) is a
+ * direct port of the state-lab approach, updated for the v0.2 envelope
+ * shape (`dedupeKey` now required, `ts` now a number).
+ */
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const ENVELOPE_VERSION = 1;
+const DEFAULT_STALE_LOCK_MS = 30000; // a lock older than this (or held by a dead pid) is reaped
+const DEFAULT_LOCK_WAIT_MS = 15000; // how long a caller will wait for a live lock before giving up
+
+// ── canonical serialization / hashing (shared by event-log, events, projections) ──
+
+// Recursively sorts object keys so two values with identical content but
+// different insertion order always serialize to identical bytes. Arrays keep
+// their order (order is meaningful there). Used both for the envelope's
+// on-disk line (fixed field order, written out explicitly below) and for
+// dedupeKey / projection-hash inputs (arbitrary nested payloads).
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const k of Object.keys(value).sort()) out[k] = sortKeysDeep(value[k]);
+    return out;
+  }
+  return value;
+}
+
+function stableStringify(value) {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+function sha256Hex(input) {
+  return crypto.createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+// ── envelope shape ──────────────────────────────────────────────────────────
+
+function isValidSource(source) {
+  return source !== null && typeof source === "object" && !Array.isArray(source);
+}
+
+function isValidEnvelope(o) {
+  if (o === null || typeof o !== "object" || Array.isArray(o)) return false;
+  if (typeof o.v !== "number") return false;
+  if (typeof o.id !== "string" || o.id.length === 0) return false;
+  // ts frozen as epoch-ms NUMBER (objection 1) — an ISO string or anything
+  // else is an invalid envelope, not tolerated/coerced.
+  if (typeof o.ts !== "number" || !Number.isFinite(o.ts)) return false;
+  if (typeof o.type !== "string" || o.type.length === 0) return false;
+  if (!Object.prototype.hasOwnProperty.call(o, "payload")) return false;
+  if (typeof o.dedupeKey !== "string" || o.dedupeKey.length === 0) return false;
+  if (o.source !== undefined && !isValidSource(o.source)) return false;
+  return true;
+}
+
+// Fixed key order on disk so identical envelopes always serialize to
+// identical bytes, and so a foreign reader can rely on field order.
+function serializeEnvelope(evt) {
+  const obj = {
+    v: evt.v,
+    id: evt.id,
+    ts: evt.ts,
+    type: evt.type,
+    payload: evt.payload === undefined ? null : evt.payload,
+    dedupeKey: evt.dedupeKey,
+  };
+  if (evt.source !== undefined) obj.source = evt.source;
+  return JSON.stringify(obj);
+}
+
+// dedupeKey = sha256 of canonical {type, payload} — ts and id excluded so a
+// retried/backfilled identical fact always produces the same key (sol's
+// answer #1 in sol-rescore-2.md).
+function computeDedupeKey(type, payload) {
+  return sha256Hex(stableStringify({ type, payload: payload === undefined ? null : payload }));
+}
+
+// Convenience constructor. `id` defaults to a fresh UUID (opaque identity,
+// per sol's identity-model ruling); `dedupeKey` defaults to the canonical
+// content hash unless the caller supplies one explicitly (events.js always
+// lets this default).
+function makeEvent(type, payload, opts = {}) {
+  const evt = {
+    v: opts.v != null ? opts.v : ENVELOPE_VERSION,
+    id: opts.id != null ? String(opts.id) : crypto.randomUUID(),
+    ts: opts.ts != null ? opts.ts : Date.now(),
+    type: String(type),
+    payload: payload === undefined ? null : payload,
+    dedupeKey: opts.dedupeKey != null ? String(opts.dedupeKey) : computeDedupeKey(type, payload),
+  };
+  if (opts.source !== undefined) evt.source = opts.source;
+  return evt;
+}
+
+// ── tolerant parse + quarantine (state-lab pattern, ported for v0.2) ───────
+
+function parseLog(raw) {
+  const events = [];
+  const quarantined = [];
+  if (raw === "" || raw == null) return { events, quarantined };
+
+  const hadTrailingNewline = raw.endsWith("\n");
+  const lines = raw.split("\n");
+  if (hadTrailingNewline) lines.pop();
+
+  const seenIds = new Set();
+  const seenDedupeKeys = new Set();
+  lines.forEach((line, idx) => {
+    if (line === "") return; // tolerate stray blank lines
+    const isLastLine = idx === lines.length - 1;
+    const tornTail = isLastLine && !hadTrailingNewline;
+
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (e) {
+      quarantined.push({ lineNo: idx + 1, raw: line, reason: tornTail ? "torn-tail" : "corrupt-line", detail: e.message });
+      return;
+    }
+    if (!isValidEnvelope(parsed)) {
+      quarantined.push({ lineNo: idx + 1, raw: line, reason: tornTail ? "torn-tail" : "invalid-envelope", detail: "missing/malformed required v0.2 envelope fields" });
+      return;
+    }
+    if (seenIds.has(parsed.id)) {
+      quarantined.push({ lineNo: idx + 1, raw: line, reason: "duplicate-id", detail: `id ${parsed.id} already present earlier in the log` });
+      return;
+    }
+    // A duplicate dedupeKey with a different id is the same logical fact
+    // written twice (a lock failure or a foreign writer) — counting it twice
+    // would inflate every projection, so quarantine it like a duplicate id
+    // (terra attack 7: parseLog quarantined ids but never dedupeKeys).
+    if (seenDedupeKeys.has(parsed.dedupeKey)) {
+      quarantined.push({ lineNo: idx + 1, raw: line, reason: "duplicate-dedupe-key", detail: `dedupeKey ${parsed.dedupeKey.slice(0, 16)}... already present earlier in the log` });
+      return;
+    }
+    seenIds.add(parsed.id);
+    seenDedupeKeys.add(parsed.dedupeKey);
+    events.push(parsed);
+  });
+
+  return { events, quarantined };
+}
+
+// Sidecar bound (terra round 3 finding 7, which refuted the "unbounded
+// growth needs a log rewrite" scoping): the newest SIDECAR_MAX_RECORDS
+// quarantine records stay verbatim; older ones fold into a single aggregate
+// first line keeping total + per-reason counts, plus a FIFO of folded
+// identity hashes so a persistent corrupt line that was folded out is not
+// re-appended as "fresh" on every subsequent read.
+const SIDECAR_MAX_RECORDS = 200;
+const SIDECAR_MAX_SEEN_KEYS = 2000;
+
+function writeQuarantineSidecar(logPath, entries, fsImpl) {
+  if (!entries.length) return;
+  const sidecar = `${logPath}.quarantine`;
+  const ts = Date.now();
+  // Identity = lineNo + raw content, NUL-joined (raw content cannot contain
+  // an unescaped NUL after JSON round-tripping).
+  const idKey = (lineNo, raw) => `${lineNo}\u0000${raw}`;
+  try {
+    // Dedupe against what the sidecar already records: readEvents and
+    // appendEvent both report the same persistent quarantined bytes, so an
+    // unconditional append duplicated the audit record on every access
+    // (terra finding 8).
+    let existing = "";
+    try { existing = fsImpl.readFileSync(sidecar, "utf8"); } catch (_) {}
+    let aggregate = null;
+    const records = [];
+    const recorded = new Set();
+    for (const line of existing.split("\n")) {
+      if (!line) continue;
+      try {
+        const p = JSON.parse(line);
+        if (p && p.aggregate === true) { aggregate = p; continue; }
+        records.push(line);
+        recorded.add(idKey(p.lineNo, p.raw));
+      } catch (_) {}
+    }
+    const seenHashes = new Set((aggregate && aggregate.seenKeys) || []);
+    const fresh = entries.filter((e) => {
+      const k = idKey(e.lineNo, e.raw);
+      return !recorded.has(k) && !seenHashes.has(sha256Hex(k).slice(0, 16));
+    });
+    if (!fresh.length) return;
+    if (records.length + fresh.length > SIDECAR_MAX_RECORDS) {
+      for (const e of fresh) records.push(JSON.stringify({ ts, ...e }));
+      const folded = records.splice(0, records.length - SIDECAR_MAX_RECORDS);
+      aggregate = aggregate || { aggregate: true, foldedRecords: 0, byReason: {}, seenKeys: [] };
+      if (!Array.isArray(aggregate.seenKeys)) aggregate.seenKeys = [];
+      for (const line of folded) {
+        aggregate.foldedRecords += 1;
+        let reason = "unknown";
+        try {
+          const q = JSON.parse(line);
+          reason = q.reason || "unknown";
+          aggregate.seenKeys.push(sha256Hex(idKey(q.lineNo, q.raw)).slice(0, 16));
+        } catch (_) {}
+        aggregate.byReason[reason] = (aggregate.byReason[reason] || 0) + 1;
+      }
+      if (aggregate.seenKeys.length > SIDECAR_MAX_SEEN_KEYS) {
+        aggregate.seenKeys.splice(0, aggregate.seenKeys.length - SIDECAR_MAX_SEEN_KEYS);
+      }
+      aggregate.lastFoldedTs = ts;
+      const tmp = `${sidecar}.tmp-${process.pid}`;
+      fsImpl.mkdirSync(path.dirname(sidecar), { recursive: true });
+      fsImpl.writeFileSync(tmp, [JSON.stringify(aggregate), ...records].join("\n") + "\n", "utf8");
+      fsImpl.renameSync(tmp, sidecar);
+      return;
+    }
+    const lines = fresh.map((e) => JSON.stringify({ ts, ...e })).join("\n") + "\n";
+    fsImpl.mkdirSync(path.dirname(sidecar), { recursive: true });
+    fsImpl.appendFileSync(sidecar, lines, "utf8");
+  } catch (_) {
+    // best-effort sidecar; a failure here must not fail the (successful)
+    // read/append it is reporting on
+  }
+}
+
+function readEvents(logPath, opts = {}) {
+  const fsImpl = opts.fs || fs;
+  let raw = "";
+  try {
+    raw = fsImpl.readFileSync(logPath, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return { events: [], quarantined: [] };
+    throw e;
+  }
+  const { events, quarantined } = parseLog(raw);
+  if (quarantined.length) writeQuarantineSidecar(logPath, quarantined, fsImpl);
+  return { events, quarantined };
+}
+
+// ── exclusive advisory lock (sibling lockfile, O_EXCL, stale reaping) ──────
+
+function pidAlive(pid) {
+  if (typeof pid !== "number" || !Number.isFinite(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM"; // exists, owned by someone else on this host: treat as alive
+  }
+}
+
+// Process start time via `ps` (mac/linux), used to detect PID RECYCLING: a
+// process that started AFTER the lockfile was written cannot be its writer
+// (terra round 3 finding 4: a dead holder's pid reused by an unrelated live
+// process wedged waiters until timeout). Returns null when unavailable
+// (windows, ps failure); callers treat null conservatively - holder stays
+// alive and the loud timeout below still fires.
+function processStartMs(pid) {
+  try {
+    const out = require("child_process")
+      .execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+      .trim();
+    if (!out) return null;
+    const t = Date.parse(out);
+    return Number.isFinite(t) ? t : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// Liveness of a lock HOLDER: pid alive, and not provably a recycled pid.
+// The start-time probe execs `ps`, so it is gated to locks older than 3s
+// (recycling needs the holder to die AND the OS to reuse the pid; inside 3s
+// the pre-existing loud timeout is the honest answer) and memoized per
+// acquisition wait via `cache`.
+function holderAlive(holder, cache) {
+  if (!pidAlive(holder.pid)) return false;
+  if (typeof holder.ts !== "number" || Date.now() - holder.ts <= 3000) return true;
+  let startMs;
+  if (cache && cache.has(holder.pid)) {
+    startMs = cache.get(holder.pid);
+  } else {
+    startMs = processStartMs(holder.pid);
+    if (cache) cache.set(holder.pid, startMs);
+  }
+  // 2s slack: `ps lstart` has second precision and a real holder stamps ts
+  // strictly after its own process start.
+  return !(startMs != null && startMs > holder.ts + 2000);
+}
+
+// Reap `lockPath` ONLY if it still holds exactly `expectedRaw` bytes.
+// Blind unlink-by-path raced (terra round 3 finding 1, CRITICAL): between a
+// waiter's read of a dead holder and its unlink, another waiter could reap
+// and MINT, so the unlink deleted the NEW holder's valid lock and two
+// writers overlapped. Reapers now serialize on a short-lived reap mutex and
+// re-verify the victim's exact bytes under it; minting (linkSync) requires
+// the path to be absent, so a verified-unchanged victim cannot have been
+// replaced before the unlink. The mutex itself is cleared dead-pid-only,
+// same doctrine as the main lock: a SIGSTOP-paused reaper holds it and
+// waiters time out loudly instead of risking a steal.
+function reapLockIfUnchanged(lockPath, expectedRaw) {
+  if (typeof expectedRaw !== "string") return false;
+  const reapPath = `${lockPath}.reap`;
+  const tmp = `${lockPath}.mint-reap-${process.pid}-${crypto.randomUUID().slice(0, 8)}`;
+  let acquired = false;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify({ pid: process.pid, ts: Date.now() }), "utf8");
+    try {
+      fs.linkSync(tmp, reapPath);
+      acquired = true;
+    } catch (_) {}
+  } catch (_) {
+  } finally {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+  }
+  if (!acquired) {
+    try {
+      const m = JSON.parse(fs.readFileSync(reapPath, "utf8"));
+      if (m && !pidAlive(m.pid)) fs.unlinkSync(reapPath);
+    } catch (_) {
+      // unreadable mutex: it only ever lives for three syscalls, so judge
+      // by its own age with a generous bound
+      try {
+        if (Math.abs(Date.now() - fs.statSync(reapPath).mtimeMs) > 5000) fs.unlinkSync(reapPath);
+      } catch (_) {}
+    }
+    return false;
+  }
+  try {
+    let raw = null;
+    try { raw = fs.readFileSync(lockPath, "utf8"); } catch (_) {}
+    if (raw === expectedRaw) {
+      try { fs.unlinkSync(lockPath); } catch (_) {}
+    }
+    return true;
+  } finally {
+    try { fs.unlinkSync(reapPath); } catch (_) {}
+  }
+}
+
+// A crash between temp-write and linkSync leaks a `.mint-*` file (terra
+// round 3 finding 6). Leaks never block acquisition; this sweep is disk
+// hygiene, run once per CONTENDED acquisition so the uncontended fast path
+// stays readdir-free.
+function sweepAbandonedMints(lockPath) {
+  try {
+    const dir = path.dirname(lockPath);
+    const prefix = `${path.basename(lockPath)}.mint-`;
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.startsWith(prefix)) continue;
+      const p = path.join(dir, name);
+      try {
+        if (Date.now() - fs.statSync(p).mtimeMs > 60000) fs.unlinkSync(p);
+      } catch (_) {}
+    }
+  } catch (_) {}
+}
+
+// Synchronous sleep — appendEvent is a sync API (matches event-log.js/
+// state-lab's sync contract), so lock-wait backoff must also be sync.
+// Atomics.wait blocks the calling thread without a busy loop; it is
+// available in every Node version this project targets.
+function syncSleep(ms) {
+  if (ms <= 0) return;
+  try {
+    const sab = new SharedArrayBuffer(4);
+    Atomics.wait(new Int32Array(sab), 0, 0, ms);
+  } catch (_) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+      /* busy-wait fallback; Atomics.wait is unavailable in this host */
+    }
+  }
+}
+
+// Acquires `<logPath>.lock`. A holder is reaped (its lockfile removed and
+// acquisition retried immediately, no backoff) ONLY when its pid is provably
+// dead or the lockfile is unreadable garbage past a short settle window —
+// this is what stops a crashed writer from wedging the log forever
+// (objection 4). Age alone NEVER steals a LIVE holder's lock: terra's round
+// (2026-07-11) reproduced two writers inside the critical section after an
+// age-based reap of a paused-but-alive holder, followed by the old holder's
+// unconditional release() deleting the new holder's lock. The cost is
+// honest: a hung-but-alive holder makes waiters time out LOUDLY below
+// instead of silently proceeding in parallel. Always uses the real `fs`
+// module: locks are an OS-level cross-process primitive and a
+// caller-injected fault-fs would not apply across processes.
+function acquireLock(logPath, opts = {}) {
+  const lockPath = `${logPath}.lock`;
+  const staleMs = opts.staleLockMs != null ? opts.staleLockMs : DEFAULT_STALE_LOCK_MS;
+  const maxWaitMs = opts.lockWaitMs != null ? opts.lockWaitMs : DEFAULT_LOCK_WAIT_MS;
+  const start = Date.now();
+  const startTimeCache = new Map(); // pid -> processStartMs, per-wait memo
+  let attempt = 0;
+
+  for (;;) {
+    attempt += 1;
+    // Write-then-LINK creation (terra re-verdict #6): opening with wx and
+    // writing afterwards left a window where the lockfile existed EMPTY; a
+    // waiter's settle window then reaped a paused-but-live creator's lock.
+    // linkSync is atomic - the lockfile appears with its full content or
+    // not at all, so an unreadable lockfile now really is garbage.
+    const token = crypto.randomUUID();
+    const tmpLock = `${lockPath}.mint-${process.pid}-${token.slice(0, 8)}`;
+    try {
+      fs.writeFileSync(tmpLock, JSON.stringify({ pid: process.pid, ts: Date.now(), token }), "utf8");
+      fs.linkSync(tmpLock, lockPath); // EEXIST when held - same exclusivity as wx
+      fs.unlinkSync(tmpLock);
+      return {
+        release() {
+          try {
+            const cur = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+            if (cur && cur.token === token) fs.unlinkSync(lockPath);
+          } catch (_) {
+            // gone or unreadable; never blind-unlink a lock that may not be ours
+          }
+        },
+      };
+    } catch (e) {
+      try { fs.unlinkSync(tmpLock); } catch (_) {}
+      if (e.code !== "EEXIST") throw e;
+
+      if (attempt === 1) sweepAbandonedMints(lockPath);
+
+      let rawHolder = null;
+      let holder = null;
+      try {
+        rawHolder = fs.readFileSync(lockPath, "utf8");
+        holder = JSON.parse(rawHolder);
+      } catch (_) {
+        holder = null; // unreadable lockfile: with link-creation this is garbage, judged by ITS OWN age below
+      }
+      if (!holder) {
+        // Judge garbage by the LOCKFILE's mtime, never by this waiter's own
+        // elapsed time (terra re-verdict #6: a waiter that had already
+        // waited 1s reaped a lockfile created 1ms earlier). A FUTURE mtime
+        // beyond clock skew is equally garbage - write-then-link means our
+        // own writer never produces one, and "settling" on it wedged
+        // waiters until timeout (terra round 3 finding 5).
+        let ageMs = Infinity;
+        try { ageMs = Date.now() - fs.statSync(lockPath).mtimeMs; } catch (_) { continue; }
+        if (ageMs > Math.min(staleMs, 1000) || ageMs < -2000) {
+          if (rawHolder != null) reapLockIfUnchanged(lockPath, rawHolder);
+          continue;
+        }
+        if (Date.now() - start > maxWaitMs) {
+          throw new Error(`event-log: lock wait timeout after ${maxWaitMs}ms on ${lockPath} (unreadable lockfile, settling)`);
+        }
+        syncSleep(5);
+        continue;
+      }
+
+      // Reapable = holder pid provably dead, or provably a RECYCLED pid
+      // (holderAlive). Never by age alone - terra round 2 reproduced overlap
+      // after an age steal of a paused-but-alive holder.
+      const stale = !holderAlive(holder, startTimeCache);
+
+      if (stale) {
+        // Guarded reap (terra round 3 finding 1): verify-unchanged under the
+        // reap mutex, never blind unlink-by-path. False return = another
+        // reaper holds the mutex; just retry the acquisition loop.
+        reapLockIfUnchanged(lockPath, rawHolder);
+        continue; // immediate retry, no backoff, after a reap
+      }
+
+      if (Date.now() - start > maxWaitMs) {
+        throw new Error(`event-log: lock wait timeout after ${maxWaitMs}ms on ${lockPath} (held by pid ${holder && holder.pid})`);
+      }
+      syncSleep(Math.min(5 + attempt * 2, 40)); // small linear backoff, capped
+    }
+  }
+}
+
+// True O_APPEND can never HEAL a foreign torn write the way a full rewrite
+// could (state-lab's temp+rename approach rebuilds from clean events, so a
+// torn tail on disk is silently dropped from the physical file). We do not
+// rewrite, so a torn tail left by a foreign writer stays on disk forever —
+// quarantined on every future read, but still bytes on the page. What we
+// MUST do is make sure OUR OWN new line never gets silently concatenated
+// onto the end of that torn tail (which would corrupt our own valid event
+// too). This is a single 1-byte read, still O(1), still touches no existing
+// byte — it only decides whether to prefix our write with one extra "\n".
+function fileEndsWithNewlineOrEmpty(logPath, fsImpl) {
+  let size;
+  try {
+    size = fsImpl.statSync(logPath).size;
+  } catch (e) {
+    if (e.code === "ENOENT") return true; // no file yet; nothing to pad against
+    throw e;
+  }
+  if (size === 0) return true;
+  const fd = fsImpl.openSync(logPath, "r");
+  try {
+    const buf = Buffer.alloc(1);
+    fsImpl.readSync(fd, buf, 0, 1, size - 1);
+    return buf.toString("utf8") === "\n";
+  } finally {
+    fsImpl.closeSync(fd);
+  }
+}
+
+// ── append ───────────────────────────────────────────────────────────────
+
+// Appends one event, atomically w.r.t. other appendEvent callers (via the
+// lock), idempotently (via the id/dedupeKey dedup check), as a true O(1)
+// single-line write (via O_APPEND — never a whole-file rewrite).
+//
+//   - `event` must already be a valid v0.2 envelope (build one with
+//     makeEvent / events.js's typed constructors, not by hand).
+//   - duplicate `id` OR duplicate `dedupeKey` (already present among the
+//     log's clean events): no-op, `{ appended:false, duplicate:true }`.
+//   - `opts.fs` lets a caller inject a wrapped fs for the READ/WRITE steps
+//     only (lock acquisition always uses the real fs — see acquireLock).
+function appendEvent(logPath, event, opts = {}) {
+  const fsImpl = opts.fs || fs;
+  if (!isValidEnvelope(event)) {
+    throw new Error("event-log: appendEvent requires a valid v0.2 envelope (v, id, ts:number, type, payload, dedupeKey)");
+  }
+
+  const dir = path.dirname(logPath);
+  fsImpl.mkdirSync(dir, { recursive: true });
+
+  const lock = acquireLock(logPath, opts);
+  try {
+    const { events: existing, quarantined } = readEvents(logPath, { fs: fsImpl });
+    if (quarantined.length) writeQuarantineSidecar(logPath, quarantined, fsImpl);
+
+    const isDuplicate = existing.some((e) => e.id === event.id || e.dedupeKey === event.dedupeKey);
+    if (isDuplicate) return { appended: false, duplicate: true, total: existing.length };
+
+    const needsLeadingNewline = !fileEndsWithNewlineOrEmpty(logPath, fsImpl);
+    const line = (needsLeadingNewline ? "\n" : "") + serializeEnvelope(event) + "\n";
+    // A single appendFileSync call with flag 'a' (the default) opens with
+    // O_APPEND and issues one write() syscall: the OS atomically seeks to
+    // end-of-file and writes, so this can never overwrite or truncate a byte
+    // already on disk, and the target path's inode never changes. This is
+    // the O(1) append the SCHEMA-SPEC v0.2 amendment 4 / objection 3 ask for
+    // — no temp file, no rename, no rewrite of prior content.
+    fsImpl.appendFileSync(logPath, line, "utf8");
+
+    return { appended: true, duplicate: false, total: existing.length + 1 };
+  } finally {
+    lock.release();
+  }
+}
+
+module.exports = {
+  ENVELOPE_VERSION,
+  DEFAULT_STALE_LOCK_MS,
+  DEFAULT_LOCK_WAIT_MS,
+  sortKeysDeep,
+  stableStringify,
+  sha256Hex,
+  isValidEnvelope,
+  serializeEnvelope,
+  computeDedupeKey,
+  makeEvent,
+  parseLog,
+  readEvents,
+  acquireLock,
+  appendEvent,
+  pidAlive,
+  // exported for direct adversarial testing (terra round 3 fixes)
+  holderAlive,
+  processStartMs,
+  reapLockIfUnchanged,
+  SIDECAR_MAX_RECORDS,
+};