@polderlabs/bizar 6.3.0 → 7.0.0

package/packages/sdk/src/consensus/index.ts

@@ -0,0 +1,147 @@
+/**
+ * consensus/index.ts — Public orchestrator for the consensus layer.
+ *
+ * F-039 — wraps `ByzantineConsensus` behind a stable factory API and
+ * re-exports every type/utility callers need. This is the surface the
+ * MCP tool (`consensus_propose`) and any future dashboard wiring
+ * consume.
+ *
+ * The orchestrator is intentionally minimal — it's a thin facade over
+ * `ByzantineConsensus` plus the type re-exports. Anything fancier
+ * (proposer scheduling, fault dashboards, etc.) belongs in `queen.ts`
+ * or a future `dashboard.ts`.
+ */
+
+import { ByzantineConsensus, type ByzantineConsensusOpts } from "./byzantine.js";
+import {
+  DEFAULT_MAX_FAULTS,
+  DEFAULT_QUORUM,
+  type CommitResult,
+  type ConsensusStatus,
+  type Decision,
+  type ProposeResult,
+  type ProposalSnapshot,
+  type Vote,
+  type VoteResult,
+  type ViewChangeResult,
+} from "./types.js";
+
+export interface CreateConsensusOpts extends Omit<ByzantineConsensusOpts, "localAgentId" | "peers"> {
+  localAgentId: string;
+  peers: string[];
+}
+
+export interface ConsensusHandle {
+  /** Identity of the local agent (vote short-circuits on its own calls). */
+  readonly localAgentId: string;
+  /** Read-only snapshot of every proposal the instance has tracked. */
+  status(): ConsensusStatus;
+  /** Snapshot of a single proposal, or `undefined` if unknown. */
+  getProposal(proposalId: string): ProposalSnapshot | undefined;
+  /** Initiate pre-prepare for a new proposal. Re-submitting the same
+   *  payload under the same view returns the cached proposalId. */
+  propose(payload: unknown): ProposeResult;
+  /** Cast a vote for a peer during the `prepare` phase. */
+  castVote(proposalId: string, agentId: string, decision: Decision, signature?: string): VoteResult;
+  /** Transport-friendly entry point — `onPrepare(proposalId, vote)`. */
+  onPrepare(proposalId: string, vote: Vote): VoteResult;
+  /** Force-commit a proposal (admin override; rare). */
+  commit(proposalId: string): CommitResult;
+  /** Trigger a view-change; returns the new proposer + view number. */
+  viewChange(reason: string, proposalId?: string): ViewChangeResult;
+  /** Head of the round-robin proposer schedule. */
+  getCurrentProposer(): string;
+  /** Current view number (incremented on every view-change). */
+  getViewNumber(): number;
+  /** Quorum threshold in effect. */
+  getQuorum(): number;
+  /** Peer roster (read-only copy). */
+  getPeers(): string[];
+}
+
+/**
+ * Build a `ConsensusHandle` for a given local agent + peer roster.
+ * The returned object is the public surface used by the MCP tool and
+ * any dashboard wiring.
+ */
+export function createConsensus(opts: CreateConsensusOpts): ConsensusHandle {
+  const instance = new ByzantineConsensus(opts);
+  return {
+    localAgentId: opts.localAgentId,
+    status: () => instance.status(),
+    getProposal: (id) => instance.getProposal(id),
+    propose: (payload) => instance.propose(payload),
+    castVote: (proposalId, agentId, decision, signature) =>
+      instance.castVote(proposalId, agentId, decision, signature),
+    onPrepare: (proposalId, vote) => instance.onPrepare(proposalId, vote),
+    commit: (proposalId) => instance.commit(proposalId),
+    viewChange: (reason, proposalId) => instance.viewChange(reason, proposalId),
+    getCurrentProposer: () => instance.getCurrentProposer(),
+    getViewNumber: () => instance.getViewNumber(),
+    getQuorum: () => instance.getQuorum(),
+    getPeers: () => instance.getPeers(),
+  };
+}
+
+// ─── Re-exports ────────────────────────────────────────────────────────
+
+export { ByzantineConsensus, type ByzantineConsensusOpts } from "./byzantine.js";
+export { QueenCoordinator, type QueenCoordinatorOpts } from "./queen.js";
+export {
+  DEFAULT_MAX_FAULTS,
+  DEFAULT_PEER_COUNT,
+  DEFAULT_QUORUM,
+  PHASE_ORDER,
+} from "./types.js";
+export type {
+  CommitResult,
+  ConsensusOpts,
+  ConsensusStatus,
+  Decision,
+  Phase,
+  ProposeResult,
+  Proposal,
+  ProposalSnapshot,
+  ProposalStatus,
+  Vote,
+  VoteResult,
+  ViewChangeResult,
+} from "./types.js";
+
+// ─── Process-wide singleton ───────────────────────────────────────────
+
+/**
+ * The shared consensus singleton used by the MCP tool. Initialized
+ * with the Bizar default 5-peer roster (odin / frigg / vor / mimir /
+ * heimdall — the same five Norse agents F-033 routes between) and a
+ * deterministic seed so MCP-driven consensus is reproducible across
+ * restarts. Tests should call `createConsensus()` with their own
+ * `localAgentId` + `peers` to get an isolated instance.
+ *
+ * The roster here is intentional — it maps to the existing 5-agent
+ * surface F-033 already exposes, so a single MCP call can drive the
+ * same set of agents the orchestrator routes to.
+ */
+const DEFAULT_PEERS: readonly string[] = ["odin", "frigg", "vor", "mimir", "heimdall"];
+const DEFAULT_LOCAL_AGENT = "odin";
+const DEFAULT_PROPOSER_SEED = "bizar-f039-default";
+
+let _shared: ConsensusHandle | null = null;
+
+export function getSharedConsensus(): ConsensusHandle {
+  if (_shared) return _shared;
+  _shared = createConsensus({
+    localAgentId: DEFAULT_LOCAL_AGENT,
+    peers: [...DEFAULT_PEERS],
+    quorum: DEFAULT_QUORUM,
+    maxFaults: DEFAULT_MAX_FAULTS,
+    proposerSeed: DEFAULT_PROPOSER_SEED,
+    historyLimit: 50,
+  });
+  return _shared;
+}
+
+/** Reset the singleton — test/dev only. */
+export function resetSharedConsensus(): void {
+  _shared = null;
+}

package/packages/sdk/src/consensus/queen.ts

@@ -0,0 +1,173 @@
+/**
+ * consensus/queen.ts — Proposer election (QueenCoordinator).
+ *
+ * F-039 — thin port of ruflo's capability-scored QueenCoordinator
+ * (v3/@claude-flow/swarm/src/coordination/queen-coordinator.ts) for
+ * the consensus layer's proposer selection. Bizar needs a deterministic,
+ * fault-aware round-robin; we don't port the full ReasoningBank pattern
+ * matching because Bizar's review steps don't have agent capability
+ * vectors — they have peer rosters + a fault log.
+ *
+ * Algorithm: round-robin weighted by recent fault count. A peer with
+ * N faults is skipped N times before becoming proposer again. With
+ * `proposerSeed`, the initial head is computed deterministically so
+ * tests can pin it.
+ */
+
+export interface QueenCoordinatorOpts {
+  /** Full peer roster, in the order round-robin walks them. Required. */
+  peers: string[];
+  /** Maximum Byzantine faults the cluster can tolerate (used as the
+   *  skip-multiplier floor). Defaults to 1. */
+  maxFaults?: number;
+  /** Optional seed — when set, the initial head is `peers[seedHash % peers.length]`. */
+  seed?: string;
+}
+
+/**
+ * Tracks per-peer fault counts and walks the peer list in
+ * round-robin order, skipping any peer whose `faultCount` is greater
+ * than the candidate's expected count at that position.
+ *
+ * Concretely: if peer X has faultCount 2, the next 2 round-robin
+ * positions that would land on X skip it instead and the proposer
+ * becomes the peer at the next non-skipped position. After 2
+ * `advance()` calls (or `selectProposer` calls that consumed a skip),
+ * X is eligible again.
+ *
+ * The fault penalty decays as the round-robin walks — this keeps
+ * the cluster moving even when one peer has accumulated many faults.
+ */
+export class QueenCoordinator {
+  private readonly peers: readonly string[];
+  /** Maximum Byzantine faults the cluster is sized for (used as the
+   *  skip-multiplier floor — `recordFault` adds a skip of size
+   *  `maxFaults` so the worst peer is skipped `maxFaults` rounds). */
+  private readonly maxFaults: number;
+  /** Per-peer cumulative fault count. */
+  private readonly faults: Map<string, number> = new Map();
+  /** Per-peer remaining-skip count (decremented on every advance). */
+  private readonly skips: Map<string, number> = new Map();
+  /** Current head of the round-robin walk. */
+  private cursor = 0;
+
+  constructor(opts: QueenCoordinatorOpts) {
+    if (!opts || !Array.isArray(opts.peers) || opts.peers.length === 0) {
+      throw new Error("QueenCoordinator: `peers` is required and must be non-empty");
+    }
+    const seen = new Set<string>();
+    for (const p of opts.peers) {
+      if (typeof p !== "string" || p.length === 0) {
+        throw new Error("QueenCoordinator: every peer id must be a non-empty string");
+      }
+      if (seen.has(p)) {
+        throw new Error(`QueenCoordinator: duplicate peer id "${p}"`);
+      }
+      seen.add(p);
+      this.faults.set(p, 0);
+      this.skips.set(p, 0);
+    }
+    this.peers = [...opts.peers];
+    this.maxFaults = Math.max(0, opts.maxFaults ?? 1);
+    if (opts.seed) {
+      this.cursor = this.seedCursor(opts.seed);
+    }
+  }
+
+  /** Current proposer (head of the round-robin walk). */
+  currentProposer(): string {
+    return this.peers[this.cursor % this.peers.length] as string;
+  }
+
+  /** Record a fault against a peer (the proposer just voted `no`, or
+   *  missed its pre-prepare window). Increments both the cumulative
+   *  fault log and the per-peer skip counter — the peer is then
+   *  skipped for `maxFaults` round-robin steps before becoming
+   *  proposer-eligible again. With `maxFaults = 1` (the F-039
+   *  default), one fault skips the peer for one round. */
+  recordFault(peerId: string): void {
+    if (!this.faults.has(peerId)) {
+      throw new Error(`recordFault: unknown peer "${peerId}"`);
+    }
+    this.faults.set(peerId, (this.faults.get(peerId) ?? 0) + 1);
+    this.skips.set(peerId, (this.skips.get(peerId) ?? 0) + this.maxFaults);
+  }
+
+  /**
+   * Walk one step forward. Skips any peer whose remaining-skip count
+   * is > 0 (decrementing the counter as it skips). Returns the new
+   * proposer.
+   */
+  advance(): string {
+    const n = this.peers.length;
+    let steps = 0;
+    while (steps < n) {
+      this.cursor = (this.cursor + 1) % n;
+      const candidate = this.peers[this.cursor] as string;
+      const skip = this.skips.get(candidate) ?? 0;
+      if (skip > 0) {
+        this.skips.set(candidate, skip - 1);
+        steps++;
+        continue;
+      }
+      return candidate;
+    }
+    // Everyone had skip > 0 — we walked the full circle and decremented
+    // everyone. Just return where we landed.
+    return this.peers[this.cursor] as string;
+  }
+
+  /**
+   * Equivalent to `selectProposer(peers, recentFaults)` from the F-039
+   * spec — but stateful, because we own the fault log. Returns the
+   * current proposer without advancing.
+   */
+  selectProposer(): string {
+    // If the current proposer has a non-zero skip, walk forward to find
+    // the next eligible peer.
+    const n = this.peers.length;
+    let probe = this.cursor;
+    for (let i = 0; i < n; i++) {
+      const candidate = this.peers[probe] as string;
+      const skip = this.skips.get(candidate) ?? 0;
+      if (skip === 0) return candidate;
+      probe = (probe + 1) % n;
+    }
+    // All peers have skip > 0 — same fallback as advance().
+    return this.peers[this.cursor] as string;
+  }
+
+  /** Cumulative fault counts (read-only snapshot). */
+  faultCounts(): Record<string, number> {
+    return Object.fromEntries(this.faults);
+  }
+
+  /** Number of peers currently under a skip penalty. */
+  pendingSkipCount(): number {
+    let n = 0;
+    for (const v of this.skips.values()) if (v > 0) n++;
+    return n;
+  }
+
+  /** Test/dev helper: drop the cursor and fault counts. */
+  reset(): void {
+    this.cursor = 0;
+    for (const k of this.faults.keys()) this.faults.set(k, 0);
+    for (const k of this.skips.keys()) this.skips.set(k, 0);
+  }
+
+  // ─── Helpers ────────────────────────────────────────────────────────
+
+  /**
+   * Stable hash of an optional seed string → integer cursor in
+   * `[0, peers.length)`. Lets a test caller pin the initial proposer
+   * for replay safety (F-039 determinism rule).
+   */
+  private seedCursor(seed: string): number {
+    let h = 5381;
+    for (let i = 0; i < seed.length; i++) {
+      h = ((h << 5) + h + seed.charCodeAt(i)) >>> 0;
+    }
+    return h % this.peers.length;
+  }
+}

package/packages/sdk/src/consensus/types.ts

@@ -0,0 +1,199 @@
+/**
+ * consensus/types.ts — Shared type definitions for the in-process
+ * Byzantine consensus layer.
+ *
+ * F-039 — thin port of ruflo's `v3/@claude-flow/swarm/src/consensus/byzantine.ts`
+ * for Bizar's review/decision steps. We carry the full PBFT phase
+ * vocabulary (pre-prepare / prepare / commit / reply) and a 3-of-5
+ * simple-majority quorum — enough surface for Bizar to gate
+ * multi-agent review decisions without the operational cost of full
+ * PBFT (no transport, no crypto signatures, no checkpoint protocol).
+ *
+ * Determinism rule: quorum math is purely set-based. The only place
+ * randomness (or ordering) enters is the optional round-robin
+ * proposer election in `queen.ts`, and even there the caller can
+ * pass an explicit seed for replay safety.
+ */
+
+// ─── Phase vocabulary ──────────────────────────────────────────────────
+
+/**
+ * PBFT-style phase identifiers. Each proposal walks
+ * `pre-prepare → prepare → commit → reply` in order.
+ */
+export type Phase =
+  | "pre-prepare"
+  | "prepare"
+  | "commit"
+  | "reply";
+
+export const PHASE_ORDER: readonly Phase[] = [
+  "pre-prepare",
+  "prepare",
+  "commit",
+  "reply",
+] as const;
+
+/** Decision a peer casts during the `prepare` phase. */
+export type Decision = "yes" | "no" | "abstain";
+
+// ─── Messages ──────────────────────────────────────────────────────────
+
+/**
+ * A vote cast by a peer during the `prepare` phase. The signature
+ * field is a free-form string — we don't enforce cryptographic
+ * signatures in the thin port (no transport), but callers that
+ * wire in a transport can stuff an HMAC in here without changing
+ * the shape.
+ */
+export interface Vote {
+  agentId: string;
+  phase: Extract<Phase, "prepare">;
+  decision: Decision;
+  signature?: string;
+  /** Wall-clock timestamp at which the peer emitted the vote. */
+  timestamp: string;
+}
+
+/**
+ * A proposal is the unit of agreement. `proposer` is the agent that
+ * initiated pre-prepare; `quorum` is the number of matching `yes`
+ * votes required for commit (3-of-5 simple majority by default).
+ */
+export interface Proposal {
+  id: string;
+  payload: unknown;
+  proposer: string;
+  quorum: number;
+  /** Total peer count this proposal was negotiated against (incl. proposer). */
+  peerCount: number;
+  /** Current phase, drives which transitions are legal. */
+  phase: Phase;
+  /** Set of agentIds that have voted `yes` in `prepare`. */
+  approvals: Set<string>;
+  /** Set of agentIds that have voted `no` in `prepare`. */
+  rejections: Set<string>;
+  /** Set of agentIds that have voted `abstain`. */
+  abstentions: Set<string>;
+  /** Free-form reason for `view-change` (set if status === 'view-change'). */
+  viewChangeReason?: string;
+  /** Set when the proposal is committed. */
+  committedAt?: string;
+  /** Set when the proposal is finalized (reply phase). */
+  finalizedAt?: string;
+  /** Wall-clock timestamp at which the proposer started pre-prepare. */
+  createdAt: string;
+}
+
+export type ProposalStatus =
+  | "pending"
+  | "pre-prepare"
+  | "prepare"
+  | "commit"
+  | "reply"
+  | "view-change"
+  | "committed"
+  | "rejected"
+  | "expired";
+
+/** A snapshot of a proposal for the public `status()` query. */
+export interface ProposalSnapshot {
+  id: string;
+  status: ProposalStatus;
+  phase: Phase;
+  proposer: string;
+  quorum: number;
+  peerCount: number;
+  approvals: number;
+  rejections: number;
+  abstentions: number;
+  createdAt: string;
+  committedAt?: string;
+  finalizedAt?: string;
+  viewChangeReason?: string;
+  payload: unknown;
+}
+
+// ─── Quorum ────────────────────────────────────────────────────────────
+
+/** 3-of-5 simple majority quorum, per the F-039 spec. */
+export const DEFAULT_QUORUM = 3;
+export const DEFAULT_PEER_COUNT = 5;
+
+/** The default fault tolerance — at most 1 Byzantine peer per cluster. */
+export const DEFAULT_MAX_FAULTS = 1;
+
+// ─── Consensus status (returned by `status()`) ─────────────────────────
+
+export interface ConsensusStatus {
+  /** All proposals the instance has processed, in arrival order. */
+  proposals: ProposalSnapshot[];
+  /** Current proposer (head of the round-robin schedule, weighted by faults). */
+  currentProposer: string;
+  /** View number — increments on every view-change. */
+  viewNumber: number;
+  /** Total proposals ever committed (status === 'committed'). */
+  committed: number;
+  /** Total proposals ever rejected (status === 'rejected'). */
+  rejected: number;
+  /** Total proposals ever expired (status === 'expired'). */
+  expired: number;
+  /** Total view-changes triggered by a faulty proposer. */
+  viewChanges: number;
+}
+
+// ─── Constructor / orchestrator options ─────────────────────────────────
+
+export interface ConsensusOpts {
+  /** Local agent id — votes cast by `localAgentId` are short-circuited
+   *  to `prepare`. Required. */
+  localAgentId: string;
+  /** Full peer roster (including `localAgentId`). Order matters for
+   *  round-robin proposer election. Required. */
+  peers: string[];
+  /** Quorum threshold for `prepare → commit`. Defaults to 3. */
+  quorum?: number;
+  /** Maximum Byzantine faults the cluster is sized for. Defaults to 1. */
+  maxFaults?: number;
+  /** Wall-clock timeout (ms) after which a pending proposal expires. */
+  /** Optional seed for round-robin proposer election — makes proposer
+   *  selection deterministic for tests. If absent, round-robin walks
+   *  the peer list in the order given. */
+  proposerSeed?: string;
+  /** A clock function for deterministic timestamps in tests. */
+  now?: () => Date;
+}
+
+// ─── Public result shapes ──────────────────────────────────────────────
+
+export interface ProposeResult {
+  proposalId: string;
+  status: ProposalStatus;
+  phase: Phase;
+}
+
+export interface VoteResult {
+  proposalId: string;
+  status: ProposalStatus;
+  phase: Phase;
+  approvals: number;
+  rejections: number;
+  abstentions: number;
+  committed: boolean;
+}
+
+export interface CommitResult {
+  proposalId: string;
+  status: ProposalStatus;
+  committedAt: string;
+  finalizedAt: string;
+  approvals: number;
+}
+
+export interface ViewChangeResult {
+  previousProposer: string;
+  newProposer: string;
+  viewNumber: number;
+  reason: string;
+  proposalId: string;
+}

package/packages/sdk/src/federation/audit.ts

@@ -0,0 +1,156 @@
+/**
+ * federation/audit.ts — AuditService: NDJSON log of every
+ * federation decision.
+ *
+ * F-038 — ported from ruflo
+ * `v3/@claude-flow/plugin-agent-federation/src/domain/services/audit-service.ts`
+ * stripped to the parts the skeleton needs:
+ *
+ *   - record(envelope, decision) appends ONE NDJSON line to
+ *     `.harness/federation-audit.log`.
+ *   - When the file exceeds 10 MB, it rotates to
+ *     `.harness/federation-audit.log.1` (single generation).
+ *   - tail() reads the last N lines for the `federation_status` MCP tool.
+ *   - size() returns the on-disk file size for the status payload.
+ *
+ * Writes are synchronous (fs.appendFileSync) — the skeleton is
+ * in-process and not throughput-bound; an async path would only
+ * complicate testing.
+ *
+ * The `.harness/` directory is created on first write. The audit
+ * log file is added to `.gitignore` by the Makefile/install step.
+ */
+
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** Default audit log path — colocated with the rest of `.harness/`. */
+export const DEFAULT_AUDIT_PATH = ".harness/federation-audit.log";
+
+/** Rotate when the file exceeds this size. */
+const ROTATION_THRESHOLD_BYTES = 10 * 1024 * 1024; // 10 MB
+
+/** Tail size cap — protects against reading gigabytes into memory. */
+const TAIL_MAX_BYTES = 1 * 1024 * 1024; // 1 MB
+
+/** Decisions recorded by the orchestrator — matches the schema the
+ *  `federation_status` MCP tool reads back. */
+export type AuditDecision =
+  | { allowed: true; reason: string }
+  | { allowed: false; reason: string };
+
+export interface AuditEntry {
+  readonly ts: string;
+  readonly envelopeId: string;
+  readonly sourceNodeId: string;
+  readonly targetNodeId: string;
+  readonly messageType: string;
+  readonly nonce: string;
+  readonly allowed: boolean;
+  readonly reason: string;
+  readonly layer: "trust" | "policy" | "hmac" | "budget" | "received" | "sent";
+  readonly nodeId: string;
+}
+
+export interface AuditServiceOpts {
+  /** Override the audit file path (defaults to .harness/federation-audit.log). */
+  readonly path?: string;
+  /** Local nodeId stamped into every entry. */
+  readonly nodeId: string;
+}
+
+export class AuditService {
+  private readonly path: string;
+  private readonly nodeId: string;
+  private rotated = false;
+
+  constructor(opts: AuditServiceOpts) {
+    if (!opts || typeof opts.nodeId !== "string" || opts.nodeId.length === 0) {
+      throw new Error("AuditService: nodeId is required");
+    }
+    this.path = opts.path ?? DEFAULT_AUDIT_PATH;
+    this.nodeId = opts.nodeId;
+  }
+
+  getPath(): string {
+    return this.path;
+  }
+
+  /** Append an NDJSON line. Triggers rotation if the file would
+   *  exceed the threshold after the write. */
+  record(entry: Omit<AuditEntry, "nodeId">): void {
+    const full: AuditEntry = { ...entry, nodeId: this.nodeId };
+    const dir = dirname(this.path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+    // Pre-write rotation check: if appending would exceed the
+    // threshold AND we haven't already rotated this session, rotate
+    // first. We keep a single generation (`.log.1`); older logs
+    // are the operator's responsibility (or a separate cron).
+    if (!this.rotated && existsSync(this.path)) {
+      try {
+        const size = statSync(this.path).size;
+        if (size + 256 > ROTATION_THRESHOLD_BYTES) {
+          this.rotate();
+        }
+      } catch {
+        // stat failed (file gone between check and write) — fall through.
+      }
+    }
+
+    appendFileSync(this.path, JSON.stringify(full) + "\n", "utf-8");
+  }
+
+  /** Rotate the current log to `.log.1`. Subsequent writes go to a
+   *  fresh `.log` file. Idempotent within a single service lifetime. */
+  rotate(): void {
+    const target = `${this.path}.1`;
+    if (existsSync(this.path)) {
+      try { renameSync(this.path, target); }
+      catch { /* ignore — best-effort */ }
+    }
+    this.rotated = true;
+  }
+
+  /** On-disk size in bytes. 0 if file missing. */
+  size(): number {
+    try {
+      return existsSync(this.path) ? statSync(this.path).size : 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  /** Read the last `n` entries from the log. Bounded by TAIL_MAX_BYTES. */
+  tail(n: number = 50): AuditEntry[] {
+    if (!existsSync(this.path)) return [];
+    let raw: string;
+    try {
+      const stats = statSync(this.path);
+      const start = Math.max(0, stats.size - TAIL_MAX_BYTES);
+      const buffer = Buffer.alloc(stats.size - start);
+      // Read the last TAIL_MAX_BYTES via a small open/read/close dance.
+      const handle = openSync(this.path, "r");
+      try { readSync(handle, buffer, 0, buffer.length, start); }
+      finally { closeSync(handle); }
+      raw = buffer.toString("utf-8");
+    } catch {
+      raw = readFileSync(this.path, "utf-8");
+    }
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    const slice = lines.slice(-n);
+    const out: AuditEntry[] = [];
+    for (const line of slice) {
+      try { out.push(JSON.parse(line) as AuditEntry); }
+      catch { /* malformed line — skip */ }
+    }
+    return out;
+  }
+
+  /** Wipe the audit log. Test-only helper. */
+  reset(): void {
+    this.rotated = false;
+    try { if (existsSync(this.path)) renameSync(this.path, `${this.path}.deleted`); }
+    catch { /* ignore */ }
+  }
+}