@twinsearth/w2m-dsh-plugin 0.0.0-stage → 0.4.7

package/src/relay/metrics.mjs

@@ -0,0 +1,284 @@
+/**
+ * W2M relay — Prometheus metrics (v0.3.3 "metrics" item).
+ *
+ * A machine-readable surface so a fleet can be monitored without a human reading
+ * reports. Text exposition format 0.0.4.
+ *
+ * ## The rule this module exists to get right: absent is not zero
+ *
+ * `w2m_rtt_ms` is emitted ONLY for machines that have actually reported a
+ * round-trip time. A machine that never reported has **no series at all**.
+ *
+ * That is not a stylistic choice. In Prometheus a `0` is a real measurement --
+ * "this machine answered instantaneously" -- while a missing series is what
+ * `absent()` and `unless` are for. Emitting `0` for "unknown" would make a fleet
+ * of silent machines look like a fleet of perfectly fast ones, which is the
+ * worst possible failure mode for a latency dashboard: it fails toward "all
+ * good". The same null-vs-zero distinction runs through the rest of this project
+ * (`rtt_ms: null` in `/v1/agents/{id}/status`, `avg_ms: null` in `/healthz`).
+ *
+ * ## Why some series carry a `stale` companion
+ *
+ * A machine that reported 40ms and then vanished keeps that series forever; a
+ * dashboard would read "40ms" from a machine that is gone. `w2m_rtt_stale`
+ * therefore distinguishes the two readings the same way `rtt_stale` does in the
+ * HTTP API: a genuinely slow machine is `w2m_rtt_ms > X and w2m_rtt_stale == 0`.
+ *
+ * ## Determinism
+ *
+ * `renderMetrics` never reads the wall clock: `nowMs` is a parameter. Series are
+ * sorted, so two renders of the same state are byte-identical -- which is what
+ * makes the output testable instead of merely plausible.
+ */
+
+import { AGGREGATE_STATUSES, aggregate } from './report.mjs';
+
+/** Content type for the text exposition format. */
+export const METRICS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
+
+/** Prefix for every metric this module emits. */
+export const METRIC_PREFIX = 'w2m_';
+
+/**
+ * Escape a label VALUE for the text exposition format.
+ *
+ * The format defines exactly three escapes: backslash, double quote and newline.
+ * A bare carriage return has no escape defined and would break the line
+ * structure, so it is folded into the newline escape: keeping the body parseable
+ * matters more than preserving a byte that no metric label should contain.
+ */
+export function escapeLabelValue(value) {
+  return String(value)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\r\n|\r|\n/g, '\\n');
+}
+
+/** Escape HELP text (only backslash and newline are meaningful there). */
+function escapeHelpText(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/\r\n|\r|\n/g, '\\n');
+}
+
+/** `name{label="escaped",...} value`, or `name value` with no labels. */
+function sample(name, labels, value) {
+  const keys = Object.keys(labels ?? {});
+  if (keys.length === 0) return `${name} ${value}`;
+  const rendered = keys.map((k) => `${k}="${escapeLabelValue(labels[k])}"`).join(',');
+  return `${name}{${rendered}} ${value}`;
+}
+
+/** A `# HELP` / `# TYPE` header followed by its samples. */
+function family(name, help, type, lines) {
+  return [`# HELP ${name} ${escapeHelpText(help)}`, `# TYPE ${name} ${type}`, ...lines];
+}
+
+/** Prometheus text format values are Go floats; keep integers integral. */
+function formatNumber(value) {
+  if (!Number.isFinite(value)) return null; // never emit NaN/Inf by accident
+  return Number.isInteger(value) ? String(value) : String(value);
+}
+
+/**
+ * Count leases by state across every tracked task.
+ *
+ * Only observed states get a series. Unlike aggregate verdicts there is no
+ * frozen, exported list of lease states to iterate, and inventing one here is
+ * exactly the "hardcoded list that silently misses a new member" problem -- for
+ * a gauge, an absent series already reads as zero.
+ */
+function leaseCounts(state) {
+  const counts = new Map();
+  for (const task of state.tasks.values()) {
+    for (const lease of task.leases.values()) {
+      const key = String(lease.state);
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+}
+
+/**
+ * Aggregate verdict counts, one entry per `AGGREGATE_STATUSES` member.
+ *
+ * The list is IMPORTED, never restated: a future verdict added to report.mjs must
+ * appear here automatically. Hardcoding it would mean a new verdict silently has
+ * no series, and a dashboard would show "no tasks" instead of "a state nobody
+ * taught the metrics layer about".
+ *
+ * Results are grouped by task first so this stays O(results) rather than
+ * O(tasks x results) per scrape.
+ */
+function taskStatusCounts(state, nowMs) {
+  const byTask = new Map();
+  for (const record of state.results.values()) {
+    const taskId = record?.envelope?.task_id;
+    if (typeof taskId !== 'string') continue;
+    let bucket = byTask.get(taskId);
+    if (bucket === undefined) {
+      bucket = [];
+      byTask.set(taskId, bucket);
+    }
+    bucket.push(record);
+  }
+
+  const counts = new Map(AGGREGATE_STATUSES.map((status) => [status, 0]));
+  for (const task of state.tasks.values()) {
+    let verdict;
+    try {
+      verdict = aggregate(task, byTask.get(task.task_id) ?? [], { nowMs }).status;
+    } catch {
+      // A task that cannot be aggregated is a bug, but a metrics scrape must never
+      // be the thing that takes the relay down. It is left out of every bucket
+      // rather than being counted as a verdict it does not have.
+      continue;
+    }
+    if (counts.has(verdict)) counts.set(verdict, counts.get(verdict) + 1);
+  }
+  return counts;
+}
+
+/**
+ * Collect every metric as plain data, separately from rendering it.
+ *
+ * Exported because the interesting part of this module is the numbers, and a
+ * test that asserts on numbers is far clearer than one that greps text.
+ *
+ * @param {object} state - A `RabbitState` (or anything with the same shape).
+ * @param {{nowMs?: number}} [options] - `nowMs` defaults to `state.nowMs()`.
+ * @returns {{nowMs:number, gauges:object, taskStatus:Map<string,number>, leases:Array<[string,number]>, rtt:Array<{machine_id:string, rtt_ms:number, stale:boolean, age_ms:number|null}>}}
+ */
+export function collectMetrics(state, { nowMs } = {}) {
+  if (!state || typeof state !== 'object') {
+    throw new TypeError('collectMetrics(state): state is required');
+  }
+  const at = nowMs ?? (typeof state.nowMs === 'function' ? state.nowMs() : 0);
+
+  let online = 0;
+  for (const device of state.devices.values()) {
+    if (device.online === true) online += 1;
+  }
+
+  // ONLY machines that reported. `rtt_ms === 0` is a real measurement and is kept;
+  // `null`/`undefined` means "never measured" and must produce no series at all.
+  const rtt = [];
+  for (const device of state.devices.values()) {
+    const value = device.rtt_ms;
+    if (value === null || value === undefined) continue;
+    if (!Number.isFinite(value)) continue; // defensive: state validates, but never emit NaN
+    const stale = typeof state.isRttStale === 'function'
+      ? state.isRttStale(device, at) === true
+      : false;
+    const age = typeof state.rttAgeMs === 'function' ? state.rttAgeMs(device, at) : null;
+    rtt.push({ machine_id: String(device.machine_id), rtt_ms: value, stale, age_ms: age });
+  }
+  rtt.sort((a, b) => (a.machine_id < b.machine_id ? -1 : a.machine_id > b.machine_id ? 1 : 0));
+
+  return {
+    nowMs: at,
+    gauges: {
+      devices: state.devices.size,
+      devices_online: online,
+      tasks: state.tasks.size,
+      results: state.results.size,
+    },
+    taskStatus: taskStatusCounts(state, at),
+    leases: leaseCounts(state),
+    rtt,
+  };
+}
+
+/**
+ * Render the Prometheus text exposition format.
+ *
+ * @param {object} state - A `RabbitState`.
+ * @param {{nowMs?: number}} [options] - Deterministic clock injection.
+ * @returns {string} The exposition body, ending in a single newline.
+ */
+export function renderMetrics(state, { nowMs } = {}) {
+  const data = collectMetrics(state, { nowMs });
+  const lines = [];
+
+  lines.push(...family(
+    `${METRIC_PREFIX}devices`,
+    'Number of devices paired with this relay.',
+    'gauge',
+    [sample(`${METRIC_PREFIX}devices`, {}, data.gauges.devices)],
+  ));
+
+  lines.push(...family(
+    `${METRIC_PREFIX}devices_online`,
+    'Number of paired devices currently marked online.',
+    'gauge',
+    [sample(`${METRIC_PREFIX}devices_online`, {}, data.gauges.devices_online)],
+  ));
+
+  lines.push(...family(
+    `${METRIC_PREFIX}tasks`,
+    'Number of tasks the relay is tracking in memory.',
+    'gauge',
+    [sample(`${METRIC_PREFIX}tasks`, {}, data.gauges.tasks)],
+  ));
+
+  lines.push(...family(
+    `${METRIC_PREFIX}results`,
+    'Number of result envelopes recorded (per machine, dedupe key and attempt).',
+    'gauge',
+    [sample(`${METRIC_PREFIX}results`, {}, data.gauges.results)],
+  ));
+
+  // One series per AGGREGATE_STATUSES entry, INCLUDING zeros: a verdict that no
+  // task currently holds still exists as a concept, and a dashboard that plots a
+  // fixed set of statuses should not see series appear and vanish.
+  //
+  // TYPE is `gauge`, not `counter`, on purpose. These are current verdict counts:
+  // a task moving pending -> consistent decrements one and increments another.
+  // A counter that can go down makes `rate()` meaningless and breaks the
+  // "counter resets to 0 on restart" contract Prometheus relies on.
+  lines.push(...family(
+    `${METRIC_PREFIX}task_status_total`,
+    'Number of tracked tasks whose current aggregate verdict is this status.',
+    'gauge',
+    AGGREGATE_STATUSES.map((status) => sample(
+      `${METRIC_PREFIX}task_status_total`,
+      { status },
+      data.taskStatus.get(status) ?? 0,
+    )),
+  ));
+
+  lines.push(...family(
+    `${METRIC_PREFIX}leases`,
+    'Number of task leases in each lease state.',
+    'gauge',
+    data.leases.map(([leaseState, count]) => sample(`${METRIC_PREFIX}leases`, { state: leaseState }, count)),
+  ));
+
+  // The null-vs-zero contract, in the exposition format.
+  const rttLines = [];
+  for (const entry of data.rtt) {
+    const formatted = formatNumber(entry.rtt_ms);
+    if (formatted === null) continue;
+    rttLines.push(sample(`${METRIC_PREFIX}rtt_ms`, { machine_id: entry.machine_id }, formatted));
+  }
+  lines.push(...family(
+    `${METRIC_PREFIX}rtt_ms`,
+    'Last reported round-trip time to this machine, in milliseconds. '
+    + 'A machine that has never reported one has NO series here: absent, not 0.',
+    'gauge',
+    rttLines,
+  ));
+
+  // Companion to the above: 1 when the stored measurement is older than the
+  // staleness window. Emitted only alongside an actual measurement, so a machine
+  // that never reported stays absent here too.
+  lines.push(...family(
+    `${METRIC_PREFIX}rtt_stale`,
+    '1 when this machine\'s last RTT measurement is older than the staleness window, else 0. '
+    + 'Only emitted for machines that have reported an RTT.',
+    'gauge',
+    data.rtt.map((entry) => sample(`${METRIC_PREFIX}rtt_stale`, { machine_id: entry.machine_id }, entry.stale ? 1 : 0)),
+  ));
+
+  return `${lines.join('\n')}\n`;
+}
+
+export default renderMetrics;

package/src/relay/peers.mjs

@@ -0,0 +1,180 @@
+/**
+ * Peer candidate registry — the signalling half of the P2P transport.
+ *
+ * Hole punching needs each side to know the other's reflexive address, and neither
+ * can learn it alone. The relay is already the one place every paired machine
+ * talks to, so it is the natural rendezvous: a machine announces the addresses it
+ * believes it is reachable at, and a peer reads them back.
+ *
+ * Design decisions worth stating:
+ *
+ *   * **Ephemeral, and deliberately not persisted.** A candidate is a NAT mapping,
+ *     and a NAT mapping is gone the moment the process that created it stops sending.
+ *     Writing these to `devices.json` would survive a restart and then hand out
+ *     addresses that cannot work -- a stale candidate is worse than no candidate,
+ *     because it turns "nobody has announced yet" into a punch that fails for a
+ *     reason the operator cannot see.
+ *   * **A machine may only announce for itself.** The route uses the authenticated
+ *     device's `machine_id` and ignores any `machine_id` in the body. Otherwise any
+ *     paired machine could redirect a peer's punch at a third party.
+ *   * **Bounded.** Candidate count, address shape and TTL are all validated, because
+ *     this is the one place where a peer supplies an address another peer will send
+ *     UDP datagrams to.
+ */
+
+/** Most candidates a single machine may announce. Enough for several interfaces, not for a scan. */
+export const MAX_CANDIDATES = 16;
+
+/** Default lifetime of an announcement. NAT mappings are kept alive by traffic; this is the backstop. */
+export const DEFAULT_TTL_MS = 60_000;
+
+/** Upper bound a caller may request, so an announcement cannot be pinned indefinitely. */
+export const MAX_TTL_MS = 10 * 60_000;
+
+const IPV4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} Whether `value` is a syntactically valid dotted-quad IPv4.
+ */
+export function isIpv4(value) {
+  if (typeof value !== 'string') return false;
+  const match = IPV4.exec(value);
+  if (!match) return false;
+  for (let i = 1; i <= 4; i += 1) {
+    const octet = Number(match[i]);
+    if (!Number.isInteger(octet) || octet < 0 || octet > 255) return false;
+    // Leading zeros are accepted by some parsers and not others; refuse them rather
+    // than let two ends disagree about which address a string means.
+    if (match[i].length > 1 && match[i].startsWith('0')) return false;
+  }
+  return true;
+}
+
+export class PeerRegistry {
+  /**
+   * @param {object} [options]
+   * @param {() => number} [options.nowMs]
+   * @param {number} [options.defaultTtlMs]
+   */
+  constructor(options = {}) {
+    this.nowMs = options.nowMs ?? (() => Date.now());
+    this.defaultTtlMs = options.defaultTtlMs ?? DEFAULT_TTL_MS;
+    /** @type {Map<string, {machine_id:string, candidates:Array<{address:string,port:number}>,
+     *                      nat:{mapping:string|null}, announced_at_ms:number, expires_at_ms:number}>} */
+    this.entries = new Map();
+  }
+
+  /**
+   * Record (or replace) a machine's candidates.
+   *
+   * @param {string} machineId Authenticated device id. Never taken from the body.
+   * @param {object} body
+   * @returns {{machine_id:string, candidates:Array<object>, expires_at:string, ttl_ms:number}}
+   */
+  announce(machineId, body = {}) {
+    if (typeof machineId !== 'string' || machineId === '') {
+      throw new TypeError('announce: machineId is required');
+    }
+    const raw = Array.isArray(body.candidates) ? body.candidates : [];
+    if (raw.length === 0) {
+      throw Object.assign(new Error('candidates must be a non-empty array'), { code: 'BAD_CANDIDATES' });
+    }
+    if (raw.length > MAX_CANDIDATES) {
+      throw Object.assign(
+        new Error(`too many candidates: ${raw.length} > ${MAX_CANDIDATES}`),
+        { code: 'TOO_MANY_CANDIDATES' },
+      );
+    }
+
+    const candidates = [];
+    const seen = new Set();
+    for (const candidate of raw) {
+      const address = candidate?.address;
+      const port = candidate?.port;
+      if (!isIpv4(address)) {
+        throw Object.assign(new Error(`candidate address is not IPv4: ${JSON.stringify(address)}`), {
+          code: 'BAD_CANDIDATE_ADDRESS',
+        });
+      }
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw Object.assign(new Error(`candidate port out of range: ${JSON.stringify(port)}`), {
+          code: 'BAD_CANDIDATE_PORT',
+        });
+      }
+      const key = `${address}:${port}`;
+      if (seen.has(key)) continue; // a duplicate is not an error, just noise
+      seen.add(key);
+      candidates.push({ address, port });
+    }
+
+    const requestedTtl = Number.isInteger(body.ttl_ms) ? body.ttl_ms : this.defaultTtlMs;
+    const ttlMs = Math.max(1000, Math.min(requestedTtl, MAX_TTL_MS));
+    const now = this.nowMs();
+
+    const entry = {
+      machine_id: machineId,
+      candidates,
+      nat: { mapping: typeof body.nat?.mapping === 'string' ? body.nat.mapping : null },
+      announced_at_ms: now,
+      expires_at_ms: now + ttlMs,
+    };
+    this.entries.set(machineId, entry);
+
+    return {
+      machine_id: machineId,
+      candidates,
+      expires_at: new Date(entry.expires_at_ms).toISOString(),
+      ttl_ms: ttlMs,
+    };
+  }
+
+  /**
+   * Read a machine's candidates, or `null` when it never announced or the
+   * announcement has expired. Expiry is checked on read as well as on sweep, so a
+   * stale entry can never be served between sweeps.
+   *
+   * @param {string} machineId
+   * @returns {object|null}
+   */
+  get(machineId) {
+    const entry = this.entries.get(machineId);
+    if (!entry) return null;
+    if (this.nowMs() >= entry.expires_at_ms) {
+      this.entries.delete(machineId);
+      return null;
+    }
+    return {
+      machine_id: entry.machine_id,
+      candidates: entry.candidates.map((c) => ({ ...c })),
+      nat: { ...entry.nat },
+      announced_at: new Date(entry.announced_at_ms).toISOString(),
+      expires_at: new Date(entry.expires_at_ms).toISOString(),
+    };
+  }
+
+  /** Drop expired entries. @returns {number} how many were dropped */
+  sweep() {
+    const now = this.nowMs();
+    let dropped = 0;
+    for (const [machineId, entry] of this.entries) {
+      if (now >= entry.expires_at_ms) {
+        this.entries.delete(machineId);
+        dropped += 1;
+      }
+    }
+    return dropped;
+  }
+
+  /** Live announcements, for `/healthz` and diagnostics. */
+  stats() {
+    this.sweep();
+    return { peers_announced: this.entries.size };
+  }
+
+  clear() {
+    this.entries.clear();
+  }
+}
+
+export default PeerRegistry;

package/src/relay/persistence.mjs

@@ -0,0 +1,207 @@
+/**
+ * W2M Rabbit relay — v0.1.2 persistence (PROTOCOL-v0.1.2 §7).
+ *
+ * `<state>/devices.json`  atomic snapshot (tmp file + rename)
+ * `<state>/ledger.jsonl`  append-only, one JSON object per line
+ * `<state>/operator-token.txt`  single line, 0600
+ *
+ * This is the only relay module allowed to touch the filesystem.
+ * Corruption is never silent: every skipped line / unreadable snapshot is
+ * recorded in `warnings` and surfaced through `/healthz`.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { rfc3339 } from './state.mjs';
+
+export const DEVICES_FILE = 'devices.json';
+export const LEDGER_FILE = 'ledger.jsonl';
+export const OPERATOR_TOKEN_FILE = 'operator-token.txt';
+
+/** Ledger entry types understood by `RabbitState#restore`. */
+export const LEDGER_TYPES = Object.freeze([
+  'task.created',
+  'lease.changed',
+  'result.stored',
+  'task.cancelled',
+]);
+
+export class Persistence {
+  /**
+   * @param {{dir?:string|null, now?:() => number}} options `dir: null` disables persistence.
+   */
+  constructor({ dir = null, now = Date.now } = {}) {
+    this.dir = dir ? path.resolve(dir) : null;
+    this._now = now;
+    /** @type {{file:string, message:string, line?:number}[]} */
+    this.warnings = [];
+    this.devicesCorrupt = false;
+    this.devicesMissing = true;
+    this.revivedDevices = 0;
+    this.revivedTasks = 0;
+    this.ledgerLinesRead = 0;
+    this.ledgerLinesSkipped = 0;
+  }
+
+  get enabled() { return this.dir !== null; }
+  get devicesFile() { return this.enabled ? path.join(this.dir, DEVICES_FILE) : null; }
+  get ledgerFile() { return this.enabled ? path.join(this.dir, LEDGER_FILE) : null; }
+  get operatorTokenFile() { return this.enabled ? path.join(this.dir, OPERATOR_TOKEN_FILE) : null; }
+
+  warn(file, message, extra = {}) {
+    this.warnings.push({ file, message, ...extra });
+    return this.warnings[this.warnings.length - 1];
+  }
+
+  ensureDir() {
+    if (!this.enabled) return false;
+    fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    return true;
+  }
+
+  /* ---------------- devices.json ---------------- */
+
+  /**
+   * @returns {{devices: Record<string, object>, corrupt: boolean, missing: boolean}}
+   * `corrupt: true` means the snapshot was unreadable — the caller starts from an
+   * EMPTY table and must report that loudly (never a silent wipe).
+   */
+  loadDevices() {
+    if (!this.enabled) return { devices: {}, corrupt: false, missing: true };
+    if (!fs.existsSync(this.devicesFile)) return { devices: {}, corrupt: false, missing: true };
+
+    let raw;
+    try {
+      raw = fs.readFileSync(this.devicesFile, 'utf8');
+    } catch (err) {
+      this.devicesCorrupt = true;
+      this.warn(DEVICES_FILE, `unreadable (${err.message}); starting from an empty device table`);
+      return { devices: {}, corrupt: true, missing: false };
+    }
+    if (raw.trim() === '') return { devices: {}, corrupt: false, missing: false };
+
+    try {
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('snapshot must be a JSON object keyed by machine_id');
+      }
+      return { devices: parsed, corrupt: false, missing: false };
+    } catch (err) {
+      this.devicesCorrupt = true;
+      this.warn(DEVICES_FILE, `corrupt snapshot ignored (${err.message}); starting from an empty device table`);
+      return { devices: {}, corrupt: true, missing: false };
+    }
+  }
+
+  /** Atomic snapshot: write a temp file, fsync, then rename over the target. */
+  saveDevices(devices) {
+    if (!this.enabled) return false;
+    this.ensureDir();
+    const out = {};
+    const iterable = devices instanceof Map ? devices.values() : Object.values(devices ?? {});
+    for (const d of iterable) {
+      out[d.machine_id] = {
+        machine_name: d.machine_name ?? d.machine_id,
+        platform: d.platform ?? {},
+        caps: d.caps ?? {},
+        user_id: d.user_id ?? null,
+        device_token: d.device_token ?? null,
+        paired_at: rfc3339(d.paired_at_ms ?? this._now()),
+        re_paired: d.re_paired === true,
+      };
+    }
+    const body = JSON.stringify(out, null, 2);
+    const tmp = `${this.devicesFile}.tmp-${process.pid}-${Date.now().toString(36)}`;
+    const fd = fs.openSync(tmp, 'w', 0o600);
+    try {
+      fs.writeFileSync(fd, body, 'utf8');
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, this.devicesFile);
+    return true;
+  }
+
+  /* ---------------- ledger.jsonl ---------------- */
+
+  /** Replay-safe read: a single broken line is skipped and counted, never fatal. */
+  loadLedger() {
+    if (!this.enabled) return [];
+    if (!fs.existsSync(this.ledgerFile)) return [];
+    let text;
+    try {
+      text = fs.readFileSync(this.ledgerFile, 'utf8');
+    } catch (err) {
+      this.warn(LEDGER_FILE, `unreadable (${err.message}); ledger not replayed`);
+      return [];
+    }
+    const entries = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (line.trim() === '') continue;
+      this.ledgerLinesRead += 1;
+      try {
+        const entry = JSON.parse(line);
+        if (!entry || typeof entry !== 'object' || typeof entry.type !== 'string') {
+          throw new Error('entry must be an object with a string `type`');
+        }
+        entries.push(entry);
+      } catch (err) {
+        this.ledgerLinesSkipped += 1;
+        this.warn(LEDGER_FILE, `line ${i + 1} skipped: ${err.message}`, { line: i + 1 });
+      }
+    }
+    return entries;
+  }
+
+  /** §7: synchronous append is enough — the volume is tiny. */
+  append(entry) {
+    if (!this.enabled) return false;
+    this.ensureDir();
+    const line = `${JSON.stringify({ ts: rfc3339(this._now()), ...entry })}\n`;
+    fs.appendFileSync(this.ledgerFile, line, { encoding: 'utf8', mode: 0o600 });
+    return true;
+  }
+
+  /* ---------------- operator-token.txt ---------------- */
+
+  readOperatorToken() {
+    if (!this.enabled) return null;
+    try {
+      if (!fs.existsSync(this.operatorTokenFile)) return null;
+      const token = fs.readFileSync(this.operatorTokenFile, 'utf8').trim();
+      return token.length > 0 ? token : null;
+    } catch (err) {
+      this.warn(OPERATOR_TOKEN_FILE, `unreadable (${err.message}); a new token will be generated`);
+      return null;
+    }
+  }
+
+  writeOperatorToken(token) {
+    if (!this.enabled || !token) return false;
+    this.ensureDir();
+    fs.writeFileSync(this.operatorTokenFile, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
+    try { fs.chmodSync(this.operatorTokenFile, 0o600); } catch { /* best effort on Windows */ }
+    return true;
+  }
+
+  /** Redacted view for `/healthz` — never contains tokens. */
+  describe() {
+    return {
+      enabled: this.enabled,
+      dir: this.dir,
+      revived_devices: this.revivedDevices,
+      revived_tasks: this.revivedTasks,
+      devices_corrupt: this.devicesCorrupt,
+      devices_missing: this.devicesMissing,
+      ledger_lines_read: this.ledgerLinesRead,
+      ledger_lines_skipped: this.ledgerLinesSkipped,
+      warnings: this.warnings.map((w) => ({ ...w })),
+    };
+  }
+}
+
+export default Persistence;