Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
35.9 KB
Raw Blame
/**
 * Receipt fold engine (storage-lifecycle, Lane 3 task 3.2).
 *
 * `compactReceiptLedgers` rewrites explicitly named receipt-ledger
 * shards: records older than the age threshold fold into one aggregate
 * line per (kind, month) preserving count, first/last timestamps and the
 * folded records' byte total; protected records survive verbatim, in
 * file order; unknown kinds fail closed to keep. The rewrite is atomic
 * per shard (compare-and-swap through `atomicWriteFileSync`) inside a
 * `withDestructiveSnapshot` span, and per-shard fail-soft: a poisoned
 * shard is collected and the run still completes with an honest audit.
 *
 * The audit is the additive `receipt_compaction` continuity kind: one
 * record per confirmed run, never on a dry run. A count-guard mismatch
 * aborts before any write, including the snapshot.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import {
  chmodSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import {
  continuityLogDir,
  continuityLogPath,
  listContinuityRecords,
} from "../../../src/core/brain/continuity/store.ts";
import { metricsDir, appendMetric } from "../../../src/core/brain/metrics.ts";
import {
  compactReceiptLedgers,
  RECEIPT_AUDIT_APPEND_FAILED,
} from "../../../src/core/brain/receipts/compact.ts";
import {
  RECEIPT_SHARD_FOREIGN_DEVICE,
  RECEIPT_SHARD_UNREADABLE,
} from "../../../src/core/brain/receipts/scan.ts";
import { compactView } from "../../../src/core/brain/receipts/views.ts";
import {
  RECEIPT_COMPACTION_OPERATION,
  RECEIPT_FOLD_SCHEMA,
  RECEIPT_LEDGER_FAMILY,
} from "../../../src/core/brain/receipts/types.ts";
import { CountGuardError } from "../../../src/core/brain/count-guard.ts";
import { listSnapshots } from "../../../src/core/brain/snapshot.ts";
import { bootstrapBrain } from "../../../src/core/brain/init.ts";
import { resetVaultIdentityPins } from "../../../src/core/brain/vault-identity.ts";
import { atomicWriteFileSync } from "../../../src/core/fs-atomic.ts";
import { WriteRefusedError } from "../../../src/core/brain/write-disposition.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";
import { withDeviceId, useUnshardedLegacyLog } from "../../helpers/device-id.ts";
import { digestVaultTree } from "../../helpers/vault-digest.ts";

// The legacy day log and ledgers are read under their un-sharded names.
useUnshardedLegacyLog();

const NOW = new Date("2026-09-25T00:00:00Z");

let vault: string;
let configHome: string;

function continuityLine(
  kind: string,
  createdAt: string,
  payload: Record<string, unknown> = {},
): string {
  const id = `ctn_${createdAt.replace(/[^0-9]/g, "").slice(0, 14)}_${kind}`;
  return `${JSON.stringify({
    schema: "o2b.continuity.v1",
    id,
    kind,
    createdAt,
    sourceRefs: [],
    payload,
    private: false,
    redacted: false,
  })}\n`;
}

function metricLine(surface: string, runAt: string, payload: Record<string, unknown> = {}): string {
  return `${JSON.stringify({ schema: "o2b.metrics.v1", surface, run_at: runAt, payload })}\n`;
}

function writeShard(dir: string, name: string, lines: ReadonlyArray<string> | string): void {
  const text = typeof lines === "string" ? lines : lines.join("");
  writeFileSync(join(dir, name), text, "utf8");
}

function readShard(dir: string, name: string): string {
  return readFileSync(join(dir, name), "utf8");
}

/** Byte length of one record line, newline separators excluded. */
function recordLineBytes(line: string): number {
  return Buffer.byteLength(line.trimEnd(), "utf8");
}

/** The continuity shard the happy-path tests fold: two old, one protected, one young. */
const MIXED_SHARD = [
  continuityLine("recall_telemetry", "2026-08-10T12:00:00Z", { note: "first old" }),
  continuityLine("source_invalidation", "2026-08-11T12:00:00Z", { reason: "audit trail" }),
  continuityLine("recall_telemetry", "2026-08-20T12:00:00Z", { note: "second old" }),
  continuityLine("gate_telemetry", "2026-09-15T12:00:00Z", { fresh: true }),
].join("");

beforeEach(() => {
  resetVaultIdentityPins();
  vault = mkdtempSync(join(tmpdir(), "o2b-receipts-compact-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-receipts-compact-cfg-"));
  const configPath = join(configHome, "config.yaml");
  atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: test-agent\n`);
  bootstrapBrain(vault, { configPath });
  mkdirSync(continuityLogDir(vault), { recursive: true });
  mkdirSync(metricsDir(vault), { recursive: true });
});

afterEach(() => {
  resetVaultIdentityPins();
  rmSync(vault, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
  rmSync(configHome, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
});

describe("compactReceiptLedgers", () => {
  test("folds old records into one aggregate line per (kind, month), preserving the totals", () => {
    writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
      expect: 2,
    });
    expect(result.dryRun).toBe(false);
    expect(result.totals.folded).toBe(2);
    const after = readShard(continuityLogDir(vault), "2026-08.jsonl");
    const lines = after.split("\n").filter((line) => line.trim() !== "");
    // Two folded records became one aggregate line; protected and young kept.
    expect(lines).toHaveLength(3);
    const aggregate = JSON.parse(lines[0]!) as {
      schema: string;
      fold: Record<string, unknown>;
    };
    expect(aggregate.schema).toBe(RECEIPT_FOLD_SCHEMA);
    expect(aggregate.fold).toMatchObject({
      family: RECEIPT_LEDGER_FAMILY.continuity,
      kind: "recall_telemetry",
      month: "2026-08",
      count: 2,
      first_created_at: "2026-08-10T12:00:00Z",
      last_created_at: "2026-08-20T12:00:00Z",
    });
    // The folded records' byte total is preserved as metadata (record
    // lines, newline separators excluded).
    const foldedBytes =
      Buffer.byteLength(
        continuityLine("recall_telemetry", "2026-08-10T12:00:00Z", { note: "first old" }).trimEnd(),
      ) +
      Buffer.byteLength(
        continuityLine("recall_telemetry", "2026-08-20T12:00:00Z", {
          note: "second old",
        }).trimEnd(),
      );
    expect(aggregate.fold.bytes).toBe(foldedBytes);
    // Shrink verified: the rewrite is strictly smaller than the original.
    expect(Buffer.byteLength(after)).toBeLessThan(Buffer.byteLength(MIXED_SHARD));
    expect(result.totals.bytesBefore).toBe(Buffer.byteLength(MIXED_SHARD));
    expect(result.totals.bytesAfter).toBe(Buffer.byteLength(after));
  });

  test("protected records survive verbatim, in file order, and unknown kinds fail closed to keep", () => {
    const shard = [
      continuityLine("recall_telemetry", "2026-08-10T12:00:00Z"),
      continuityLine("source_invalidation", "2026-08-11T12:00:00Z", { reason: "audit" }),
      continuityLine("kind_from_the_future", "2026-08-12T12:00:00Z"),
      continuityLine("gate_telemetry", "2026-08-13T12:00:00Z", { session_id: "sess-1" }),
      continuityLine("recall_telemetry", "2026-08-14T12:00:00Z"),
    ].join("");
    writeShard(continuityLogDir(vault), "2026-08.jsonl", shard);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    expect(result.totals.folded).toBe(2);
    expect(result.totals.kept).toBe(3);
    const after = readShard(continuityLogDir(vault), "2026-08.jsonl");
    // Every kept line is byte-present, and their relative order holds.
    const keptLines = [
      continuityLine("source_invalidation", "2026-08-11T12:00:00Z", { reason: "audit" }),
      continuityLine("kind_from_the_future", "2026-08-12T12:00:00Z"),
      continuityLine("gate_telemetry", "2026-08-13T12:00:00Z", { session_id: "sess-1" }),
    ];
    let cursor = -1;
    for (const line of keptLines) {
      const at = after.indexOf(line.trim());
      expect(at).toBeGreaterThan(cursor);
      cursor = at;
    }
  });

  test("the aggregate's first and last compare by instant, not by stamp text", () => {
    // Both stamps pass the canonical grammar, which admits optional
    // fractional seconds - and "." sorts before "Z", so a text compare
    // puts the LATER half-second stamp first. Written later-instant-first
    // to make the text order and the instant order disagree.
    const shard = [
      continuityLine("recall_telemetry", "2026-08-10T12:00:00.500Z", { note: "later half" }),
      continuityLine("recall_telemetry", "2026-08-10T12:00:00Z", { note: "earlier whole" }),
    ].join("");
    writeShard(continuityLogDir(vault), "2026-08.jsonl", shard);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
      expect: 2,
    });
    expect(result.totals.folded).toBe(2);
    const aggregate = JSON.parse(
      readShard(continuityLogDir(vault), "2026-08.jsonl")
        .split("\n")
        .find((line) => line.trim() !== "")!,
    ) as { fold: Record<string, unknown> };
    expect(aggregate.fold.first_created_at).toBe("2026-08-10T12:00:00Z");
    expect(aggregate.fold.last_created_at).toBe("2026-08-10T12:00:00.500Z");
  });

  test("metrics shards fold per (surface, month)", () => {
    writeShard(metricsDir(vault), "storage_usage.jsonl", [
      metricLine("storage_usage", "2026-08-01T00:00:00Z", { bytes: 10 }),
      metricLine("storage_usage", "2026-08-05T00:00:00Z", { bytes: 11 }),
      metricLine("storage_usage", "2026-08-10T00:00:00Z", { bytes: 12 }),
      metricLine("storage_usage", "2026-08-15T00:00:00Z", { bytes: 13 }),
      metricLine("storage_usage", "2026-08-20T00:00:00Z", { bytes: 14 }),
      metricLine("storage_usage", "2026-07-05T00:00:00Z", { bytes: 5 }),
      metricLine("storage_usage", "2026-07-06T00:00:00Z", { bytes: 6 }),
    ]);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.metrics, name: "storage_usage.jsonl" }],
      now: NOW,
      dryRun: false,
      expect: 7,
    });
    expect(result.totals.folded).toBe(7);
    const lines = readShard(metricsDir(vault), "storage_usage.jsonl")
      .split("\n")
      .filter((line) => line.trim() !== "");
    expect(lines).toHaveLength(2);
    const folds = lines.map((line) => (JSON.parse(line) as { fold: Record<string, unknown> }).fold);
    expect(folds.map((f) => f.month).toSorted()).toEqual(["2026-07", "2026-08"]);
    const august = folds.find((f) => f.month === "2026-08")!;
    expect(august).toMatchObject({
      family: RECEIPT_LEDGER_FAMILY.metrics,
      surface: "storage_usage",
      count: 5,
      first_run_at: "2026-08-01T00:00:00Z",
      last_run_at: "2026-08-20T00:00:00Z",
    });
  });

  test("a metrics line outside the record shape is kept, never folded into a surface-less aggregate", () => {
    // The scan counts a parsed line without the full metrics record shape
    // (schema, surface and run_at strings, plain-object payload) as
    // unparseable. The fold engine must classify it the same way: gated
    // only on run_at, a line carrying nothing but an old stamp would fold
    // with an undefined surface, and JSON.stringify would drop that
    // surface from the aggregate - an aggregate no reader can attribute.
    const malformed = JSON.stringify({ run_at: "2026-07-01T00:00:00Z" });
    writeShard(metricsDir(vault), "storage_usage.jsonl", [
      metricLine("storage_usage", "2026-08-01T00:00:00Z", { bytes: 10 }),
      metricLine("storage_usage", "2026-08-05T00:00:00Z", { bytes: 11 }),
      metricLine("storage_usage", "2026-08-10T00:00:00Z", { bytes: 12 }),
      `${malformed}\n`,
    ]);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.metrics, name: "storage_usage.jsonl" }],
      now: NOW,
      dryRun: false,
      expect: 3,
    });
    expect(result.totals.folded).toBe(3);
    expect(result.totals.kept).toBe(1);
    expect(result.totals.aggregates).toBe(1);
    const after = readShard(metricsDir(vault), "storage_usage.jsonl");
    // The malformed line is still there, byte-verbatim.
    expect(after).toContain(malformed);
    for (const line of after.split("\n").filter((entry) => entry.trim() !== "")) {
      const fold = (JSON.parse(line) as { fold?: { surface?: unknown } }).fold;
      if (fold !== undefined) expect(typeof fold.surface).toBe("string");
    }
  });

  test("a confirmed run takes one recovery point and appends the audit record exactly once", () => {
    writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    expect(result.snapshotRunId).toBeDefined();
    expect(result.auditRecordId).toBeDefined();
    expect(result.recoverability).toBeDefined();
    const snapshots = listSnapshots(vault).snapshots;
    expect(snapshots.some((s) => s.run_id === result.snapshotRunId)).toBe(true);
    const audits = listContinuityRecords(vault, { kind: "receipt_compaction" });
    expect(audits).toHaveLength(1);
    expect(audits[0]!.id).toBe(result.auditRecordId!);
  });

  test("a dry run writes nothing: no rewrite, no snapshot, no audit record", () => {
    writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
    const before = digestVaultTree(vault);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: true,
    });
    expect(result.dryRun).toBe(true);
    expect(result.totals.folded).toBe(2);
    expect(digestVaultTree(vault)).toBe(before);
    expect(listContinuityRecords(vault, { kind: "receipt_compaction" })).toHaveLength(0);
  });

  test("a count-guard mismatch aborts before any write, snapshot included", () => {
    writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
    const before = digestVaultTree(vault);
    expect(() =>
      compactReceiptLedgers(vault, {
        shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
        now: NOW,
        dryRun: false,
        expect: 3,
      }),
    ).toThrow(CountGuardError);
    expect(digestVaultTree(vault)).toBe(before);
    expect(readdirSync(join(vault, "Brain", ".snapshots"))).toEqual([]);
    expect(listContinuityRecords(vault, { kind: "receipt_compaction" })).toHaveLength(0);
  });

  test("a re-run over a compacted ledger folds nothing and writes nothing", () => {
    writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
    compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    const after = digestVaultTree(vault);
    const audits = listContinuityRecords(vault, { kind: "receipt_compaction" }).length;
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    expect(result.totals.folded).toBe(0);
    expect(digestVaultTree(vault)).toBe(after);
    expect(listContinuityRecords(vault, { kind: "receipt_compaction" })).toHaveLength(audits);
  });

  test("the confirmed result reports the recovery point's bytes and the net delta", () => {
    // M6 (confirm half): the recovery point is a whole-Brain archive
    // written BEFORE the ledger shrink lands, into a surface the storage
    // census counts as vault content. A result carrying only the ledger
    // shrink reads as pure win even where the net effect is growth. The
    // confirmed result names both sides: the archive's bytes, and the
    // ledger shrink minus the recovery point's growth.
    writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    expect(result.snapshotRunId).toBeDefined();
    expect(result.snapshotBytes).toBeGreaterThan(0);
    const shrink = result.totals.bytesBefore - result.totals.bytesAfter;
    expect(shrink).toBeGreaterThan(0);
    expect(result.netDeltaBytes).toBe(shrink - result.snapshotBytes!);
    // A dry run takes no recovery point, so it names neither.
    writeShard(continuityLogDir(vault), "2026-07.jsonl", [
      continuityLine("recall_telemetry", "2026-07-10T12:00:00Z"),
    ]);
    const preview = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-07.jsonl" }],
      now: NOW,
      dryRun: true,
    });
    expect(preview.snapshotBytes).toBeUndefined();
    expect(preview.netDeltaBytes).toBeUndefined();
    // Both figures ride the shared wire view.
    const view = compactView(result);
    expect(view["snapshot_bytes"]).toBe(result.snapshotBytes);
    expect(view["net_delta_bytes"]).toBe(result.netDeltaBytes);
    expect(compactView(preview)["snapshot_bytes"]).toBeUndefined();
  });

  test("a shard whose fold would not shrink is collected and the rest of the run completes", () => {
    // One old record whose aggregate line would be LARGER than the
    // record itself: the engine refuses the rewrite rather than grow a
    // ledger, and the refusal is collected while the healthy shard
    // beside it still folds and the run still completes.
    writeShard(continuityLogDir(vault), "2026-07.jsonl", [
      continuityLine("recall_telemetry", "2026-07-10T12:00:00Z"),
    ]);
    writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
    const result = compactReceiptLedgers(vault, {
      shards: [
        { family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-07.jsonl" },
        { family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" },
      ],
      now: NOW,
      dryRun: false,
    });
    expect(result.shards.map((s) => s.shard)).toEqual(["continuity:2026-08.jsonl"]);
    expect(result.failures).toHaveLength(1);
    expect(result.failures[0]!.shard).toBe("continuity:2026-07.jsonl");
    expect(result.failures[0]!.message).toContain("shrink");
    // The run still completed: the healthy shard folded, and the audit
    // names the refusal honestly.
    expect(result.totals.folded).toBe(2);
    const audits = listContinuityRecords(vault, { kind: "receipt_compaction" });
    expect(audits).toHaveLength(1);
    expect(JSON.stringify(audits[0]!.payload)).toContain("continuity:2026-07.jsonl");
    // The refused shard is untouched on disk.
    expect(readShard(continuityLogDir(vault), "2026-07.jsonl")).toContain("2026-07-10T12:00:00Z");
  });

  test("a lost audit record is a named outcome, never a throw that discards the run", () => {
    // The audit record lands in the continuity ledger under the run
    // clock's month, beside the shards being folded. A directory parked
    // at that exact path makes the append fail while the metrics shard
    // selected here folds untouched - the window where every shard is
    // already durable and a post-write throw would discard every
    // outcome, failure and recovery point with it.
    writeShard(
      metricsDir(vault),
      "storage_usage.jsonl",
      [
        metricLine("brain", "2026-06-01T00:00:00Z", { n: 1 }),
        metricLine("brain", "2026-06-02T00:00:00Z", { n: 2 }),
        metricLine("brain", "2026-06-03T00:00:00Z", { n: 3 }),
        metricLine("brain", "2026-06-04T00:00:00Z", { n: 4 }),
      ].join(""),
    );
    mkdirSync(continuityLogPath(vault, "2026-09"), { recursive: true });
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.metrics, name: "storage_usage.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    expect(result.totals.folded).toBe(4);
    expect(result.auditRecordId).toBeUndefined();
    expect(result.auditError).toBe(RECEIPT_AUDIT_APPEND_FAILED);
    // The fold itself landed: the shard on disk holds the aggregate.
    expect(readShard(metricsDir(vault), "storage_usage.jsonl")).toContain(RECEIPT_FOLD_SCHEMA);
    expect(listContinuityRecords(vault, { kind: "receipt_compaction" })).toHaveLength(0);
  });

  test("the review probe: entity mentions and the audit trail survive two confirmed runs", () => {
    // The H1 probe the external review ran: a 2026-08 shard holding 28
    // session_entity_mention records and 28 receipt_compaction records
    // ended 0 records / 4 aggregates after two confirmed runs - the
    // cross-session entity index and the fold's own audit trail folded
    // away, because folding used to be the default for every kind outside
    // a short protected list. Folding is now opt-in per kind and both
    // kinds are data, not telemetry: nothing here may fold, so two runs
    // leave all 56 records in place and write no aggregate at all.
    const lines: string[] = [];
    for (let i = 0; i < 28; i += 1) {
      const day = String((i % 25) + 1).padStart(2, "0");
      lines.push(
        continuityLine("session_entity_mention", `2026-08-${day}T12:00:00Z`, {
          session_ref: "imports/a.md",
          key: `sym:S${i}`,
        }),
      );
      lines.push(
        continuityLine("receipt_compaction", `2026-08-${day}T13:00:00Z`, {
          operation: RECEIPT_COMPACTION_OPERATION,
        }),
      );
    }
    writeShard(continuityLogDir(vault), "2026-08.jsonl", lines);
    for (let run = 0; run < 2; run += 1) {
      const result = compactReceiptLedgers(vault, {
        shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
        now: NOW,
        dryRun: false,
      });
      expect(result.totals.folded).toBe(0);
      expect(result.failures).toEqual([]);
    }
    // The read model still sees every record, and no aggregate line was
    // written. (Nothing folded, so the runs appended no audit either.)
    expect(listContinuityRecords(vault, { kind: "session_entity_mention" })).toHaveLength(28);
    expect(listContinuityRecords(vault, { kind: "receipt_compaction" })).toHaveLength(28);
    expect(readShard(continuityLogDir(vault), "2026-08.jsonl")).not.toContain(RECEIPT_FOLD_SCHEMA);
  });

  test("a later run merges into the existing (kind, month) aggregate instead of adding a second line", () => {
    // M13: the cutoff slides with each run and re-imports append new old
    // records into an already-compacted monthly shard, so a shard folded
    // twice used to gain a SECOND aggregate line per (kind, month) - a
    // growing stack the one-aggregate-per-key contract forbids, and whose
    // ~200-byte lines could tip a small fold into the strict-shrink
    // refusal. The fold now merges into the aggregate it finds: count and
    // bytes sum, first and last widen.
    writeShard(continuityLogDir(vault), "2026-08.jsonl", [
      continuityLine("recall_telemetry", "2026-08-10T12:00:00Z", { note: "first" }),
      continuityLine("recall_telemetry", "2026-08-20T12:00:00Z", { note: "second" }),
    ]);
    const first = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    expect(first.totals.aggregates).toBe(1);
    // A re-import appends another old record into the same monthly shard.
    const compacted = readShard(continuityLogDir(vault), "2026-08.jsonl");
    const reimported = continuityLine("recall_telemetry", "2026-08-15T12:00:00Z", {
      note: "re-imported",
    });
    writeShard(continuityLogDir(vault), "2026-08.jsonl", compacted + reimported);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    expect(result.totals.folded).toBe(1);
    // The prior aggregate was merged away, not kept verbatim.
    expect(result.totals.kept).toBe(0);
    // The small fold merged instead of failing the strict-shrink guard.
    expect(result.failures).toEqual([]);
    const lines = readShard(continuityLogDir(vault), "2026-08.jsonl")
      .split("\n")
      .filter((line) => line.trim() !== "");
    expect(lines).toHaveLength(1);
    const fold = (JSON.parse(lines[0]!) as { fold: Record<string, unknown> }).fold;
    expect(fold.kind).toBe("recall_telemetry");
    expect(fold.month).toBe("2026-08");
    expect(fold.count).toBe(3);
    expect(fold.first_created_at).toBe("2026-08-10T12:00:00Z");
    expect(fold.last_created_at).toBe("2026-08-20T12:00:00Z");
    expect(fold.bytes).toBe(
      recordLineBytes(
        continuityLine("recall_telemetry", "2026-08-10T12:00:00Z", { note: "first" }),
      ) +
        recordLineBytes(
          continuityLine("recall_telemetry", "2026-08-20T12:00:00Z", { note: "second" }),
        ) +
        recordLineBytes(reimported),
    );
  });

  test("a metrics fold merges into the existing (surface, month) aggregate the same way", () => {
    writeShard(metricsDir(vault), "storage_usage.jsonl", [
      metricLine("storage_usage", "2026-08-01T00:00:00Z", { bytes: 10 }),
      metricLine("storage_usage", "2026-08-05T00:00:00Z", { bytes: 11 }),
    ]);
    compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.metrics, name: "storage_usage.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    const compacted = readShard(metricsDir(vault), "storage_usage.jsonl");
    writeShard(metricsDir(vault), "storage_usage.jsonl", [
      compacted,
      metricLine("storage_usage", "2026-08-03T00:00:00Z", { bytes: 12 }),
    ]);
    const result = compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.metrics, name: "storage_usage.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    expect(result.totals.folded).toBe(1);
    expect(result.failures).toEqual([]);
    const lines = readShard(metricsDir(vault), "storage_usage.jsonl")
      .split("\n")
      .filter((line) => line.trim() !== "");
    expect(lines).toHaveLength(1);
    const fold = (JSON.parse(lines[0]!) as { fold: Record<string, unknown> }).fold;
    expect(fold.surface).toBe("storage_usage");
    expect(fold.count).toBe(3);
    expect(fold.first_run_at).toBe("2026-08-01T00:00:00Z");
    expect(fold.last_run_at).toBe("2026-08-05T00:00:00Z");
  });

  test("appendMetric holds the shard's lock, so a rewrite window cannot swallow a sample", () => {
    // M12: the metrics append path wrote bare `appendFileSync` with no
    // lock, so a sample landing between the fold engine's compare-and-swap
    // re-read and its rename was overwritten without error - exactly the
    // loss the CAS was built to turn into reported drift. The append now
    // takes the same per-file lock the continuity appender takes, in both
    // directions: a contended append is a loud failure, never a silent
    // overwrite, and a compact that meets a held lock is a collected
    // failure, never a rewrite that wins the race.
    mkdirSync(metricsDir(vault), { recursive: true });
    const shardPath = join(metricsDir(vault), "storage_usage.jsonl");
    writeFileSync(
      shardPath,
      [
        metricLine("storage_usage", "2026-08-01T00:00:00Z", { bytes: 10 }),
        metricLine("storage_usage", "2026-08-02T00:00:00Z", { bytes: 11 }),
      ].join(""),
      "utf8",
    );
    writeFileSync(`${shardPath}.lock`, "held by another writer", "utf8");
    try {
      expect(() =>
        appendMetric(vault, {
          surface: "storage_usage",
          runAt: "2026-09-02T00:00:00Z",
          payload: { bytes: 12 },
        }),
      ).toThrow(/lock busy/);
      // Nothing landed while the lock was held.
      expect(readFileSync(shardPath, "utf8")).not.toContain("2026-09-02");
      // And the fold engine reports the contention instead of rewriting.
      const result = compactReceiptLedgers(vault, {
        shards: [{ family: RECEIPT_LEDGER_FAMILY.metrics, name: "storage_usage.jsonl" }],
        now: NOW,
        dryRun: false,
      });
      expect(result.shards).toEqual([]);
      expect(result.failures).toHaveLength(1);
      expect(result.failures[0]!.shard).toBe("metrics:storage_usage.jsonl");
      expect(result.failures[0]!.message).toContain("locked");
    } finally {
      rmSync(`${shardPath}.lock`, { force: true });
    }
  });

  test("another device's shard is refused by name; this device's shard beside it still folds", () => {
    // M11: shards are named per device so exactly one device writes a
    // given file, but the fold's lock and compare-and-swap are local
    // only - rewriting a peer's shard here is the divergent-copy conflict
    // the shard layout exists to prevent. A named foreign shard is a
    // refusal by name, and the local shard in the same selection folds.
    withDeviceId("", () => {
      writeShard(continuityLogDir(vault), "2026-08.telescope.jsonl", MIXED_SHARD);
      writeShard(continuityLogDir(vault), "2026-07.jsonl", [
        continuityLine("recall_telemetry", "2026-07-10T12:00:00Z", { note: "local a" }),
        continuityLine("recall_telemetry", "2026-07-20T12:00:00Z", { note: "local b" }),
      ]);
      const result = compactReceiptLedgers(vault, {
        shards: [
          { family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.telescope.jsonl" },
          { family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-07.jsonl" },
        ],
        now: NOW,
        dryRun: false,
      });
      expect(result.failures).toEqual([
        {
          shard: "continuity:2026-08.telescope.jsonl",
          message: RECEIPT_SHARD_FOREIGN_DEVICE,
        },
      ]);
      expect(result.totals.folded).toBe(2);
      // The foreign shard is untouched on disk.
      expect(readShard(continuityLogDir(vault), "2026-08.telescope.jsonl")).toBe(MIXED_SHARD);
      // A dry run refuses the same way, so a preview never promises a
      // peer's fold.
      const preview = compactReceiptLedgers(vault, {
        shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.telescope.jsonl" }],
        now: NOW,
        dryRun: true,
      });
      expect(preview.failures).toEqual([
        { shard: "continuity:2026-08.telescope.jsonl", message: RECEIPT_SHARD_FOREIGN_DEVICE },
      ]);
    });
  });

  test("a mixed selection reports a compacted shard as nothing-to-do, not a failure", () => {
    // The re-run contract: a compacted shard folds nothing and writes
    // nothing. A MIXED selection never reaches the run-level
    // nothing-foldable shortcut - the compacted shard arrives at the
    // rewriter with foldable 0, its rebuild is byte-identical, and the
    // strict-shrink guard then failed exactly the shard the contract
    // calls a no-op.
    writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
    compactReceiptLedgers(vault, {
      shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
      now: NOW,
      dryRun: false,
    });
    const compacted = readShard(continuityLogDir(vault), "2026-08.jsonl");
    writeShard(continuityLogDir(vault), "2026-07.jsonl", [
      continuityLine("recall_telemetry", "2026-07-10T12:00:00Z"),
      continuityLine("recall_telemetry", "2026-07-20T12:00:00Z"),
    ]);
    const result = compactReceiptLedgers(vault, {
      shards: [
        { family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-07.jsonl" },
        { family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" },
      ],
      now: NOW,
      dryRun: false,
    });
    expect(result.failures).toEqual([]);
    expect(result.shards.map((shard) => shard.shard).toSorted()).toEqual([
      "continuity:2026-07.jsonl",
      "continuity:2026-08.jsonl",
    ]);
    const untouched = result.shards.find((shard) => shard.shard === "continuity:2026-08.jsonl");
    expect(untouched).toBeDefined();
    expect(untouched!.folded).toBe(0);
    expect(untouched!.bytesAfter).toBe(untouched!.bytesBefore);
    // The compacted shard is byte-identical on disk.
    expect(readShard(continuityLogDir(vault), "2026-08.jsonl")).toBe(compacted);
    // The run still folded the shard that had foldable records.
    expect(result.totals.folded).toBe(2);
    expect(result.auditRecordId).toBeDefined();
  });

  test("a zero-foldable shard is never rewritten, so its bytes never grow", () => {
    // The rebuild joins the kept lines and appends one newline, so a
    // shard whose file lacks a trailing newline rebuilds one byte LONGER
    // than it stands. With nothing foldable there is nothing to write:
    // the file must come out byte-identical, not grown, not failed.
    writeShard(
      continuityLogDir(vault),
      "2026-08.jsonl",
      continuityLine("gate_telemetry", "2026-09-15T12:00:00Z").replace(/\n$/, ""),
    );
    writeShard(continuityLogDir(vault), "2026-07.jsonl", [
      continuityLine("recall_telemetry", "2026-07-10T12:00:00Z"),
      continuityLine("recall_telemetry", "2026-07-20T12:00:00Z"),
    ]);
    const before = readShard(continuityLogDir(vault), "2026-08.jsonl");
    const result = compactReceiptLedgers(vault, {
      shards: [
        { family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-07.jsonl" },
        { family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" },
      ],
      now: NOW,
      dryRun: false,
    });
    expect(result.failures).toEqual([]);
    expect(readShard(continuityLogDir(vault), "2026-08.jsonl")).toBe(before);
    expect(result.totals.folded).toBe(2);
  });

  test.skipIf(CHMOD_CANNOT_DENY)(
    "an unreadable shard fails by name, never with the raw filesystem error",
    () => {
      // The failure rows ride the compact view to remote callers verbatim:
      // the raw Node error text would hand them an absolute host path and
      // an absent-versus-denied oracle. The boundary names the shard and
      // the one class the operator can act on: unreadable.
      writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
      const shardPath = join(continuityLogDir(vault), "2026-08.jsonl");
      chmodSync(shardPath, 0o000);
      try {
        const result = compactReceiptLedgers(vault, {
          shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
          now: NOW,
          dryRun: true,
        });
        expect(result.failures).toHaveLength(1);
        expect(result.failures[0]!.shard).toBe("continuity:2026-08.jsonl");
        expect(result.failures[0]!.message).toBe(RECEIPT_SHARD_UNREADABLE);
        const rendered = JSON.stringify(result.failures);
        expect(rendered).not.toContain("ENOENT");
        expect(rendered).not.toContain("EACCES");
        expect(rendered).not.toContain(vault);
      } finally {
        chmodSync(shardPath, 0o644);
      }
    },
  );

  test("a shard ref that is not a valid shard name is refused before anything runs", () => {
    expect(() =>
      compactReceiptLedgers(vault, {
        shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "../metrics/x.jsonl" }],
        now: NOW,
        dryRun: true,
      }),
    ).toThrow(/not a continuity shard/);
  });

  test("a permissions-document deny refuses the confirmed run before any write", () => {
    writeShard(continuityLogDir(vault), "2026-08.jsonl", MIXED_SHARD);
    atomicWriteFileSync(
      join(vault, "Brain", "_permissions.yaml"),
      "version: 1\ndefault_action: allow\nentries:\n  - id: freeze\n    agent: test-agent\n" +
        "    action: ingest\n    verdict: deny\n",
    );
    const before = readShard(continuityLogDir(vault), "2026-08.jsonl");
    expect(() =>
      compactReceiptLedgers(vault, {
        shards: [{ family: RECEIPT_LEDGER_FAMILY.continuity, name: "2026-08.jsonl" }],
        now: NOW,
        dryRun: false,
        subject: { agent: "test-agent", via: "config" },
      }),
    ).toThrow(WriteRefusedError);
    // The ledger shard is untouched. (The refusal itself writes its
    // decision-ledger row - that record is the point of the consult -
    // so the assertion is on the shard the run would have rewritten.)
    expect(readShard(continuityLogDir(vault), "2026-08.jsonl")).toBe(before);
    expect(readdirSync(join(vault, "Brain", ".snapshots"))).toEqual([]);
  });

  test("an empty shard selection is a named caller error, never a silent full scan", () => {
    expect(() => compactReceiptLedgers(vault, { shards: [], now: NOW, dryRun: true })).toThrow(
      /explicit shard ids/,
    );
  });
});