fieldlog 0.15.0

package/src/kernel.ts

@@ -0,0 +1,333 @@
+// kernel.ts — createKernel({file}): append/query/undo/sync.
+// Local-first: append/query/undo NEVER touch the network. Sync is background
+// delta handled by sync.ts against a Relay object.
+import { randomUUID } from 'node:crypto';
+import { openLog, type AppendLog, type AppendInput, type LogEvent } from './log.js';
+import { checkAppend, openStore, type EventStore, type SqlParams } from './store.js';
+import {
+  createFailoverState,
+  getAckSeq,
+  getServerTime,
+  syncKernel as runSync,
+  syncWithFailover,
+  type FailoverState,
+  type PushResult,
+  type PullResult,
+  type Relay,
+  type SyncOpts,
+} from './sync.js';
+import { takeSnapshot, sweepLogFile } from './retain.js';
+import { guardSeal, type Hold, type SplitPair } from './tombstone.js';
+import { CAP_TOKEN_TTL_MS, mintCapToken, signEvent, type CapToken } from './auth.js';
+import { openQuotaGuard, type QuotaGuard, type QuotaStatus } from './quota.js';
+
+export interface KernelOpts {
+  file: string; // e.g. 'ledger.db' (+ sidecar 'ledger.log')
+  deviceId?: string;
+  /** Wall-clock source for ts_device (display only, never order). Test seam for skew. */
+  clock?: () => number;
+  /** Max locally queued events awaiting ack (default 50_000). Append past it throws ERR_OUTBOX_FULL. */
+  maxPending?: number;
+  /** Hard byte ceiling over [db, log] files, enforced fail-closed on every
+   * append (throws ERR_QUOTA_EXCEEDED / ERR_QUOTA_UNKNOWN). Unset = no quota. */
+  quotaLimitBytes?: number;
+  /** Per-append byte estimate reserved against the quota (default: measured
+   * JSON size of the event input, min 1). Test seam for deterministic denial. */
+  quotaEstimateBytes?: number;
+  /** ed25519 private key PEM: every local append is signed at source, so
+   * trusted-mode receivers verify (not dead-letter) legitimate traffic. */
+  privateKeyPem?: string;
+}
+
+/** Default bound on unsynced outbox events before append refuses with ERR_OUTBOX_FULL. */
+export const DEFAULT_OUTBOX_CAP = 50_000;
+
+export type AppendArgs =
+  | { type: string; payload: Record<string, unknown>; actor?: string }
+  | ({ type: string; actor?: string } & Record<string, unknown>);
+
+export interface LogHealth {
+  events: number;
+  quarantined: number;
+  repairedTail: boolean;
+  gaps: number[];
+  /** Poison log lines skipped by the open-time replay (hash mismatch / corrupt apply). */
+  skipped: number;
+}
+
+export interface SnapshotInfo {
+  snapshot: string;
+  sealedSeq: number;
+  dbSeq: number;
+}
+
+export interface TruncateInfo {
+  removed: number;
+  kept: number;
+  sealedSeq: number;
+  /** Holds on this replica and whether each blocked the sweep. */
+  held: Hold[];
+  /** Tombstone/target pairs the seal would have split. */
+  pairs: SplitPair[];
+}
+
+export interface Kernel {
+  deviceId: string;
+  dbPath: string;
+  logPath: string;
+  append(args: AppendArgs): Promise<LogEvent>;
+  query<T = Record<string, unknown>>(sql: string, params?: SqlParams): Promise<T[]>;
+  undo(eventId: string, actor?: string): Promise<LogEvent>;
+  /** Resolve an IOU: 'resolved' needs online ack; failed/expired record locally. */
+  resolve(eventId: string, outcome: 'resolved' | 'failed' | 'expired', actor?: string): Promise<LogEvent>;
+  /** Sync via one relay, or fail over across a list in order (sticks to first healthy). */
+  sync(relay: Relay | Relay[], opts?: SyncOpts): Promise<PushResult & PullResult & { pushRelay?: number; pullRelay?: number }>;
+  /** Mint a relay capability token for this kernel's deviceId with a device private key. */
+  capToken(privateKeyPem: string, scopes?: string[], ttlMs?: number): CapToken;
+  conflicts(): Promise<Record<string, unknown>[]>;
+  ackSeq(): number;
+  serverTime(): number | null;
+  verifyLog(): { ok: boolean; at?: number; reason?: string; gaps?: number[]; skipped: number };
+  health(): LogHealth;
+  /** Current quota snapshot, or null when no quotaLimitBytes was configured. */
+  quota(): QuotaStatus | null;
+  /** Online full copy of the db + seal the acked prefix into it. */
+  snapshot(dest?: string): Promise<SnapshotInfo>;
+  /** Sweep the sealed log prefix (guarded by ack seq, holds, tombstone pairs). */
+  truncate(): Promise<TruncateInfo>;
+  close(): void;
+}
+export function logPathFor(file: string): string {
+  return file.replace(/\.(db|sqlite|sqlite3)$/, '') + '.log';
+}
+
+function toAppendInput(args: AppendArgs, deviceId: string, clock: () => number): AppendInput {
+  const { type, actor, payload, ...rest } = args as {
+    type: string;
+    actor?: string;
+    payload?: Record<string, unknown>;
+  } & Record<string, unknown>;
+  if (!type) throw new Error('append: type is required');
+  // Shorthand (README): append({type:'entry', value, actor}) → payload.
+  // Explicit: append({type, payload}) — extra keys merge under payload.
+  const { device_id: _d, id: _i, ts_device: _t, ...clean } = rest;
+  void _d;
+  void _i;
+  void _t;
+  return { type, actor, device_id: deviceId, ts_device: clock(), payload: { ...clean, ...(payload ?? {}) } };
+}
+
+export async function createKernel(opts: KernelOpts): Promise<Kernel> {
+  const dbPath = opts.file;
+  const logPath = logPathFor(opts.file);
+  const store: EventStore = openStore(dbPath);
+  const storedDevice: string | null = store.getMeta('device.id');
+  const storedExplicit: string | null = store.getMeta('device.explicit');
+  if (storedDevice && opts.deviceId && storedDevice !== opts.deviceId && storedExplicit === '1') {
+    const msg =
+      `ERR_DEVICE_MISMATCH: explicit deviceId '${opts.deviceId}' != stored '${storedDevice}' for '${dbPath}'; ` +
+      `refusing to split-brain (reopen with the stored id, or use a fresh file for a new device)`;
+    store.close();
+    throw new Error(msg);
+  }
+  const deviceId: string = opts.deviceId ?? storedDevice ?? randomUUID();
+  if (!storedDevice) {
+    store.setMeta('device.id', deviceId);
+    store.setMeta('device.explicit', opts.deviceId ? '1' : '0');
+  } else if (opts.deviceId && storedDevice !== opts.deviceId) {
+    // First explicit open over an auto-generated id: adopt it (the common
+    // init-then-sync flow), and mark it explicit so any later id throws.
+    store.setMeta('device.id', deviceId);
+    store.setMeta('device.explicit', '1');
+  }
+  const signer = opts.privateKeyPem ? (ev: LogEvent) => signEvent(opts.privateKeyPem as string, ev) : undefined;
+  let log: AppendLog = openLog(logPath, deviceId, signer);
+  const openReplay = store.replay(log.readAll());
+  if (openReplay.skipped > 0) {
+    console.warn(`WARN_REPLAY_SKIPPED: ${openReplay.skipped} poison log line(s) skipped on open of '${logPath}'`);
+  }
+  let replaySkipped = openReplay.skipped;
+  store.exciseMissing(
+    log.readAll().map((e) => e.seq),
+    log.sealedBelow,
+  );
+
+  const clock = opts.clock ?? Date.now;
+  const maxPending = opts.maxPending ?? DEFAULT_OUTBOX_CAP;
+  if (!Number.isInteger(maxPending) || maxPending < 1) {
+    throw new Error(`maxPending must be a positive integer, got ${opts.maxPending}`);
+  }
+  // Byte quota over the two state files (db + log sidecar). Fail-closed:
+  // every append reserves its estimated size first, so ERR_QUOTA_EXCEEDED
+  // and ERR_QUOTA_UNKNOWN propagate and nothing is written past the ceiling.
+  const quota: QuotaGuard | null =
+    opts.quotaLimitBytes === undefined
+      ? null
+      : openQuotaGuard({ limitBytes: opts.quotaLimitBytes, files: [dbPath, logPath] });
+  if (!quota) console.warn(`WARN_UNCAPPED: no quotaLimitBytes set — uncapped growth; set quotaLimitBytes to bound disk usage ('${dbPath}')`);
+  const quotaFixed = opts.quotaEstimateBytes;
+  if (quotaFixed !== undefined && (!Number.isInteger(quotaFixed) || quotaFixed < 1)) {
+    throw new Error(`quotaEstimateBytes must be a positive integer, got ${opts.quotaEstimateBytes}`);
+  }
+  // Failover memory across sync calls: failed relays cool down with backoff,
+  // then get re-probed; list order decides fail-back.
+  const failover: FailoverState = createFailoverState(0);
+  // Append/truncate mutex: truncate closes and reopens the log fd, so an
+  // append racing it could write into a closed fd or a stale generation.
+  // Serialize both through one promise chain (cooperative: same process).
+  let tail: Promise<void> = Promise.resolve();
+  function serialize<T>(fn: () => Promise<T>): Promise<T> {
+    const next = tail.then(fn);
+    tail = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    return next;
+  }
+  /** Re-drive log lines the read-model never applied (kill between log.append
+   * and store.apply), like the sync/deltasync pull path. Idempotent by UUID.
+   * Gated on a suspect flag: a split can only appear when an append's
+   * store.apply throws (flagged below) or across a restart (covered by the
+   * open-time replay), so the steady path stays O(1) instead of O(log). */
+  let splitSuspect = false;
+  function healSplit(): void {
+    if (!splitSuspect) return;
+    splitSuspect = false;
+    for (const e of log.readAll()) {
+      if (store.hasId(e.id)) continue;
+      try {
+        store.apply(e);
+      } catch {
+        splitSuspect = true; // still failing: leave it for the next append or restart
+      }
+    }
+  }
+  async function appendInner(args: AppendArgs): Promise<LogEvent> {
+    healSplit();
+    const input = toAppendInput(args, deviceId, clock);
+    checkAppend(input.type, input.payload ?? {}); // fail fast: no poison lines in the log
+    const pending = log.maxSeq() - getAckSeq(store);
+    if (pending >= maxPending) {
+      throw new Error(
+        `ERR_OUTBOX_FULL: outbox holds ${pending} pending events (cap ${maxPending}); ` +
+          `oldest unsynced seq is ${getAckSeq(store) + 1}; sync to drain before appending`,
+      );
+    }
+    // Reserve before growing state; release once the growth is measured on
+    // disk (or when the append fails) so `held` never double-counts `used`.
+    let reserved = 0;
+    if (quota) {
+      reserved = quotaFixed ?? Math.max(1, Buffer.byteLength(JSON.stringify(input), 'utf8'));
+      quota.reserve(reserved); // throws ERR_QUOTA_* fail-closed: nothing written below
+    }
+    let ev: LogEvent;
+    try {
+      ev = log.append(input);
+    } catch (err) {
+      if (quota) quota.release(reserved);
+      throw err;
+    }
+    if (quota) quota.release(reserved);
+    // Contract: the log line above is already fsynced, so a store failure
+    // here is a split, not a loss. Fail loud (never swallow) and let the
+    // next append/restart re-drive the durable line via healSplit/replay.
+    try {
+      store.apply(ev);
+    } catch (err) {
+      splitSuspect = true; // the durable line above still needs re-driving
+      const why = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `ERR_APPLY_SPLIT: log seq ${ev.seq} (id ${ev.id}) is durable but the read-model apply failed (${why}); ` +
+          `it will be re-driven on the next append or restart`,
+      );
+    }
+    return ev;
+  }
+  const kernel: Kernel = {
+    deviceId,
+    dbPath,
+    logPath,
+    append: (args) => serialize(() => appendInner(args)),
+
+    query: <T = Record<string, unknown>>(sql: string, params?: SqlParams): Promise<T[]> =>
+      Promise.resolve(store.query<T>(sql, params)),
+    undo: async (eventId, actor) => {
+      // Blind compensator by design: the target may live on a peer replica
+      // not yet synced here. Convergence is by fold, not by local existence.
+      return serialize(() => appendInner({ type: 'undo.compensate', payload: { reverses: eventId }, actor }));
+    },
+    resolve: async (eventId, outcome, actor) => {
+      const type = outcome === 'resolved' ? 'entry.resolved' : outcome === 'failed' ? 'entry.failed' : 'entry.expired';
+      return serialize(() => appendInner({ type, payload: { event_id: eventId }, actor }));
+    },
+    sync: (relay, syncOpts) => {
+      const relays = Array.isArray(relay) ? relay : [relay];
+      if (
+        relays.length === 0 ||
+        relays.some((r) => !r || typeof (r as Relay).push !== 'function' || typeof (r as Relay).pull !== 'function')
+      ) {
+        throw new Error('sync needs a Relay object (push/pull) — raw URLs carry no transport in v0.1');
+      }
+      if (!Array.isArray(relay)) return runSync(log, store, relay as Relay, deviceId, syncOpts);
+      return syncWithFailover(log, store, relays as Relay[], deviceId, syncOpts, failover);
+    },
+    capToken: (privateKeyPem, scopes = ['relay:push', 'relay:pull'], ttlMs = CAP_TOKEN_TTL_MS) =>
+      mintCapToken(privateKeyPem, deviceId, scopes, ttlMs),
+    conflicts: () => Promise.resolve(store.query(`SELECT * FROM conflicts WHERE status = 'open'`)),
+    ackSeq: () => getAckSeq(store),
+    serverTime: () => getServerTime(store),
+    verifyLog: () => {
+      const v = log.verify();
+      return { ...v, skipped: replaySkipped };
+    },
+    health: () => {
+      const v = log.verify();
+      return { events: log.readAll().length, quarantined: log.quarantined, repairedTail: log.repairedTail, gaps: v.gaps ?? [], skipped: replaySkipped };
+    },
+    quota: () => (quota ? quota.status() : null),
+    snapshot: (dest) => Promise.resolve(takeSnapshot(store, dbPath, getAckSeq(store), dest)),
+    truncate: () =>
+      serialize(async () => {
+        const sealed = Number(store.getMeta('snapshot.sealed_seq') ?? 0);
+        const noop = { removed: 0, kept: log.readAll().length, sealedSeq: 0, held: [], pairs: [] };
+        if (sealed <= 0) return noop;
+        // Guard the seal before sweeping: never remove unacked/unapplied
+        // data, a legally-held event, or half a tombstone/target pair
+        // (a swept target whose hide survives — or vice versa — would
+        // resurrect or orphan on replay). Sweep report.effective and tell
+        // the operator exactly what blocked the rest.
+        const report = guardSeal(
+          store,
+          log.readAll().map((e) => e.seq),
+          sealed,
+          getAckSeq(store),
+        );
+        if (report.effective <= 0)
+          return { removed: 0, kept: log.readAll().length, sealedSeq: 0, held: report.held, pairs: report.pairs };
+        // The log fd must be closed for the sweep, so a failed sweep must
+        // still reopen it: a closed-but-referenced log breaks every later
+        // append with EBADF. finally keeps the kernel usable either way.
+        log.close();
+        try {
+          const swept = sweepLogFile(logPath, report.effective);
+          return { ...swept, sealedSeq: report.effective, held: report.held, pairs: report.pairs };
+        } finally {
+          log = openLog(logPath, deviceId, signer);
+          const r = store.replay(log.readAll()); // incremental: kept suffix re-applies, db stands
+          if (r.skipped > 0) {
+            console.warn(`WARN_REPLAY_SKIPPED: ${r.skipped} poison log line(s) skipped after truncate of '${logPath}'`);
+          }
+          replaySkipped += r.skipped;
+          store.exciseMissing(
+            log.readAll().map((e) => e.seq),
+            log.sealedBelow,
+          );
+        }
+      }),
+    close: () => {
+      log.close();
+      store.close();
+    },
+  };
+  return kernel;
+}

package/src/log.ts

@@ -0,0 +1,344 @@
+// log.ts — JSONL append-only log: UUID per event, hash chain, fsync per append.
+// Boring file: `tail -f ledger.log` friendly. One JSON object per line.
+import { createHash, randomUUID } from 'node:crypto';
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  ftruncateSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+
+export const GENESIS_HASH = 'GENESIS';
+
+/** First line of a swept log: chains the kept suffix to the removed prefix. */
+export interface TruncateMarker {
+  v: 1;
+  marker: 'fieldlog-truncate' | 'fielog-truncate';
+  truncated_before: number; // first kept seq; removed seqs are all below this
+  tip: string; // hash of the last removed event; verify base for the suffix
+  next_seq: number; // seq counter at sweep time; never reuse a seq
+}
+export function isMarker(o: unknown): o is TruncateMarker {
+  if (!o || typeof o !== 'object') return false;
+  if (!('marker' in o) || (o.marker !== 'fieldlog-truncate' && o.marker !== 'fielog-truncate')) return false;
+  if (!('v' in o) || o.v !== 1) return false;
+  return (
+    'tip' in o &&
+    typeof o.tip === 'string' &&
+    'next_seq' in o &&
+    typeof o.next_seq === 'number' &&
+    'truncated_before' in o &&
+    typeof o.truncated_before === 'number'
+  );
+}
+
+export interface LogEvent {
+  id: string; // UUID, idempotency key across devices/relays
+  seq: number; // local monotonic sequence, assigned on append
+  type: string;
+  actor?: string;
+  device_id: string;
+  ts_device: number; // wall clock, display only — NEVER authoritative
+  payload: Record<string, unknown>;
+  prev_hash: string;
+  hash: string;
+  // Set only when learned from the relay / a peer; never hashed.
+  origin_seq?: number;
+  origin_device?: string;
+  server_time?: number;
+  // Auth envelope: device signature over the hash-chain hash. Never hashed
+  // (signature covers the hash, not vice versa). Unsigned locals stay valid;
+  // pull verification only enforces this when a trusted registry is given.
+  signature?: string;
+  countersignatures?: Array<{ deviceId: string; signatureHex: string }>;
+}
+
+export interface AppendInput {
+  type: string;
+  payload?: Record<string, unknown>;
+  actor?: string;
+  device_id?: string;
+  id?: string;
+  ts_device?: number;
+  // Preserved when re-importing a remote event locally.
+  origin_seq?: number;
+  origin_device?: string;
+  server_time?: number;
+  signature?: string;
+  countersignatures?: Array<{ deviceId: string; signatureHex: string }>;
+}
+
+/** Deep key-sorted copy of JSON data so identical payloads hash identically
+ * regardless of key insertion order across devices. Arrays keep their order
+ * (they are sequences, not sets); non-plain objects keep JSON semantics. */
+function canonicalValue(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(canonicalValue);
+  if (v !== null && typeof v === 'object') {
+    const proto = Object.getPrototypeOf(v);
+    if (proto !== Object.prototype && proto !== null) return v;
+    const src = v as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(src).sort()) out[k] = canonicalValue(src[k]);
+    return out;
+  }
+  return v;
+}
+
+ /** Canonical bytes covered by the hash chain (server_time excluded on purpose). */
+ export function canonicalOf(e: Omit<LogEvent, 'hash'>): string {
+   return JSON.stringify({
+     id: e.id,
+     seq: e.seq,
+     type: e.type,
+     actor: e.actor ?? null,
+     device_id: e.device_id,
+     ts_device: e.ts_device,
+    payload: canonicalValue(e.payload),
+     prev_hash: e.prev_hash,
+   });
+ }
+
+export function hashFor(e: Omit<LogEvent, 'hash'>): string {
+  return createHash('sha256').update(canonicalOf(e), 'utf8').digest('hex');
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  at?: number;
+  reason?: string;
+  gaps?: number[]; // seqs re-anchored after a quarantined line (known gap, not tamper)
+}
+
+export interface AppendLog {
+  path: string;
+  append(input: AppendInput): LogEvent;
+  readAll(): LogEvent[];
+  readAfter(seq: number): LogEvent[];
+  /** UUID lookup over the live file (dedupe retries without re-appending). */
+  hasId(id: string): boolean;
+  getById(id: string): LogEvent | null;
+  maxSeq(): number;
+  lastHash(): string;
+  verify(): VerifyResult;
+  /** true when open truncated a torn tail write (kill mid-append). */
+  repairedTail: boolean;
+  /** mid-file lines skipped into <path>.quarantine. */
+  quarantined: number;
+  /** first kept seq after a sweep (0 when never truncated); excise forgives below this. */
+  sealedBelow: number;
+  close(): void;
+}
+
+export function openLog(path: string, defaultDeviceId: string, signer?: (ev: LogEvent) => string): AppendLog {
+  const dir = dirname(path);
+  if (dir !== '' && dir !== '.') mkdirSync(dir, { recursive: true });
+  const quarantinePath = path + '.quarantine';
+  const seenQ = new Set<string>();
+  if (existsSync(quarantinePath)) {
+    for (const line of readFileSync(quarantinePath, 'utf8').split('\n')) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        const parsed: unknown = JSON.parse(t);
+        if (parsed && typeof parsed === 'object' && 'sha' in parsed && typeof parsed.sha === 'string') {
+          seenQ.add(parsed.sha);
+        }
+      } catch {
+        seenQ.add(createHash('sha256').update(t, 'utf8').digest('hex'));
+      }
+    }
+  }
+  const noteQuarantine = (lineNo: number, raw: string): void => {
+    const sha = createHash('sha256').update(raw, 'utf8').digest('hex');
+    if (seenQ.has(sha)) return; // reopening must not duplicate forensics
+    seenQ.add(sha);
+    appendFileSync(quarantinePath, JSON.stringify({ line: lineNo, sha, raw }) + '\n');
+  };
+  let events: LogEvent[] = [];
+  let marker: TruncateMarker | null = null;
+  const gapBefore = new Set<number>(); // kept seqs following a skipped line
+  let skipPending = false;
+  let quarantined = 0;
+  let repairedTail = false;
+  if (existsSync(path)) {
+    const raw = readFileSync(path, 'utf8');
+    const parts = raw.split('\n');
+    // Last content line, not assumed position: a kill can land between the
+    // content write and its trailing newline, leaving a complete event with
+    // no terminator. Skipping it would silently drop a durable event.
+    let lastIdx = parts.length - 1;
+    while (lastIdx >= 0 && !parts[lastIdx].trim()) lastIdx--;
+    // Offsets locate a torn tail for truncation.
+    let off = 0;
+    const starts: number[] = parts.map((p) => {
+      const s = off;
+      off += Buffer.byteLength(p, 'utf8') + 1;
+      return s;
+    });
+    for (let i = 0; i <= lastIdx; i++) {
+      const t = parts[i].trim();
+      if (!t) continue;
+      try {
+        const parsed: unknown = JSON.parse(t);
+        if (isMarker(parsed)) {
+          marker = parsed; // last marker wins; old ones are dropped by sweep
+          skipPending = false;
+          continue;
+        }
+        const ev = parsed as LogEvent;
+        if (skipPending) {
+          gapBefore.add(ev.seq);
+          skipPending = false;
+        }
+        events.push(ev);
+      } catch {
+        if (i === lastIdx) {
+          // Torn tail: the write never completed, so no event was ever
+          // durable — truncate it, keep a forensic copy, carry on.
+          const f = openSync(path, 'r+');
+          try {
+            ftruncateSync(f, starts[i]);
+            fsyncSync(f);
+          } finally {
+            closeSync(f);
+          }
+          try {
+            const dfd = openSync(dirname(path), 'r');
+            try {
+              fsyncSync(dfd);
+            } finally {
+              closeSync(dfd);
+            }
+          } catch {
+            /* platforms without directory fsync: file fsync still holds */
+          }
+          noteQuarantine(i + 1, t + ' /* torn tail, truncated on open */');
+          repairedTail = true;
+        } else {
+          noteQuarantine(i + 1, t);
+          quarantined += 1;
+          skipPending = true;
+        }
+      }
+    }
+  }
+  const byId = new Map<string, LogEvent>(events.map((e) => [e.id, e]));
+  const keptMax = events.length === 0 ? 0 : Math.max(...events.map((e) => e.seq));
+  let nextSeq = Math.max(marker?.next_seq ?? 1, keptMax + 1); // seqs never reused across sweeps
+  let tip = events.length === 0 ? (marker?.tip ?? GENESIS_HASH) : events[events.length - 1].hash;
+
+  // Long-lived append fd so every write can be followed by fsync.
+  const fd = openSync(path, 'a');
+
+  return {
+    path,
+    append(input: AppendInput): LogEvent {
+      if (!input.type || typeof input.type !== 'string') {
+        throw new Error('log.append: type must be a non-empty string');
+      }
+      if (input.id !== undefined && byId.has(input.id)) {
+        throw new Error(`log.append: duplicate id ${input.id}`);
+      }
+      const core: Omit<LogEvent, 'hash'> = {
+        id: input.id ?? randomUUID(),
+        seq: nextSeq,
+        type: input.type,
+        actor: input.actor,
+        device_id: input.device_id ?? defaultDeviceId,
+        ts_device: input.ts_device ?? Date.now(),
+        payload: input.payload ?? {},
+        prev_hash: tip,
+        origin_seq: input.origin_seq,
+        origin_device: input.origin_device,
+        server_time: input.server_time,
+      };
+      const ev: LogEvent = { ...core, hash: hashFor(core) };
+      // Source signing: the device key covers the chain hash BEFORE the line
+      // hits disk, so relayed copies always carry a verifiable signature and
+      // trusted-mode receivers apply (not dead-letter) legitimate traffic.
+      // input.signature is never preserved: it covered the origin hash, which
+      // the local re-hash replaced — keeping it would fail verification under
+      // the local device_id and brick relayed pulls.
+      if (signer && !ev.signature) ev.signature = signer(ev);
+      writeSync(fd, JSON.stringify(ev) + '\n');
+      fsyncSync(fd); // durable before ack — offline means the disk is the server
+      events.push(ev);
+      byId.set(ev.id, ev);
+      nextSeq += 1;
+      tip = ev.hash;
+      return ev;
+    },
+    readAll(): LogEvent[] {
+      return [...events];
+    },
+    readAfter(seq: number): LogEvent[] {
+      return events.filter((e) => e.seq > seq);
+    },
+    hasId(id: string): boolean {
+      return byId.has(id);
+    },
+    getById(id: string): LogEvent | null {
+      return byId.get(id) ?? null;
+    },
+    maxSeq(): number {
+      return nextSeq - 1;
+    },
+    lastHash(): string {
+      return tip;
+    },
+    verify(): VerifyResult {
+      let prev = marker?.tip ?? GENESIS_HASH; // swept prefix re-anchors here
+      let expectedSeq = marker?.truncated_before ?? 1; // seqs run contiguously from here
+      const gaps: number[] = [];
+      for (const e of events) {
+        const { hash, signature: _s, countersignatures: _c, ...core } = e;
+        void _s;
+        void _c;
+        if (hashFor(core) !== hash) {
+          return { ok: false, at: e.seq, reason: 'hash mismatch (tampered payload?)' };
+        }
+        // A re-chained survivor hides a surgically removed prefix/suffix from
+        // the prev_hash check, so seq continuity is enforced too. Only a
+        // forward jump onto a quarantined gap is forgiven (re-anchored below).
+        const seqForgiven = e.seq > expectedSeq && gapBefore.has(e.seq);
+        if (e.seq !== expectedSeq && !seqForgiven) {
+          return {
+            ok: false,
+            at: e.seq,
+            reason:
+              e.seq < expectedSeq
+                ? 'duplicate seq (forked/edited log?)'
+                : 'seq gap (truncated/edited log?)',
+          };
+        }
+        if (e.prev_hash !== prev) {
+          if (!gapBefore.has(e.seq)) {
+            return { ok: false, at: e.seq, reason: 'prev_hash mismatch (truncated/edited log?)' };
+          }
+        }
+        if (seqForgiven || e.prev_hash !== prev) {
+          gaps.push(e.seq); // known gap: predecessor was quarantined, re-anchor
+        }
+        prev = hash;
+        expectedSeq = e.seq + 1;
+      }
+      return gaps.length > 0 ? { ok: true, gaps } : { ok: true };
+    },
+    repairedTail,
+    quarantined,
+    sealedBelow: marker?.truncated_before ?? 0,
+    close(): void {
+      try {
+        closeSync(fd);
+      } catch {
+        /* already closed */
+      }
+    },
+  };
+}