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
9.3 KB
Raw Blame
/**
 * Two architect runs on one repo, driven by genuinely concurrent
 * processes (finding C5 of the locks-and-races review).
 *
 * `generateArchDocs` takes `<vault>/Brain/projects/arch/<key>.lock` across
 * the whole plan-then-write pass, because planning is a read of every note
 * on disk and writing is a rewrite of the same notes. A lock that starts
 * after the read does not prevent a lost update - and the file's existing
 * lock test cannot see the difference: it samples `existsSync(lock)` from
 * the `advanced` events, and every one of those is emitted from the write
 * loop, which runs after all planning either way.
 *
 * WHY THE TALLY IS THE INSTRUMENT, AND NOT THE BYTES. One run's output is
 * a pure function of the scanned facts plus the prose already outside each
 * note's regions. Two runs on one repo therefore compute the same bytes,
 * so whichever writes last leaves the same file whether it read the
 * other's output or the state before it - the bytes cannot tell the two
 * interleavings apart. What CAN is `created`/`updated`/`unchanged`: those
 * counts are the verdict of the read, they are in the CLI's JSON envelope,
 * and they are only true if the read that produced them is inside the same
 * critical section as the write. Under the lock, exactly one of N
 * concurrent runs may report that it created a note; the rest must report
 * finding it already correct. With the lock moved to cover only the
 * writes, every run claims to have created the same file.
 *
 * Real `bun` children behind a wall-clock barrier, the discipline of
 * `tests/core/brain/ingest/concurrent-shared-writes.test.ts`: process
 * startup alone staggers three processes by more than a plan takes, which
 * would serialize them by accident and pass against the defect.
 */

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

import { generateArchDocs } from "../../../src/core/brain/architect/generate.ts";
import { repoKey } from "../../../src/core/brain/git/identity.ts";
import { CLI_SPAWN_BUDGET_MS } from "../../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

/** Enough notes that one run's write loop outlasts another run's plan. */
const MODULES = 40;
const FILES_PER_MODULE = 3;
/** The overview, the key-decisions note, and one note per module. */
const NOTE_COUNT = MODULES + 2;

const RUNNERS = 3;
const SPAWN_TIMEOUT_MS = 60_000;

/**
 * Milliseconds the children wait before starting work. `bun` startup alone
 * staggers three processes by more than a plan pass takes, which would
 * serialize them by accident; the barrier makes the overlap real.
 */
const BARRIER_LEAD_MS = 1_500;

/**
 * How many named refusals one racer absorbs before its run counts as a
 * failure. Each refusal costs one lock budget of waiting, so this is a
 * bound on a stuck lock, not a pacing knob: two holds is the most a racer
 * can queue behind.
 */
const MAX_REFUSALS = 5;

const GENERATE = join(import.meta.dir, "../../../src/core/brain/architect/generate.ts");

let tmp: string;
let project: string;
let vault: string;
let archDir: string;

function seedProject(): void {
  mkdirSync(project, { recursive: true });
  writeFileSync(
    join(project, "package.json"),
    JSON.stringify({ name: "race-app", version: "0.0.1" }),
  );
  for (let m = 0; m < MODULES; m += 1) {
    const name = `m${String(m).padStart(2, "0")}`;
    const dir = join(project, "src", name);
    mkdirSync(dir, { recursive: true });
    for (let f = 0; f < FILES_PER_MODULE; f += 1) {
      writeFileSync(join(dir, `f${f}.ts`), `// ${name} ${f}\n`, "utf8");
    }
  }
}

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-architect-race-"));
  project = join(tmp, "race-app");
  vault = join(tmp, "vault");
  mkdirSync(join(vault, "Brain"), { recursive: true });
  seedProject();
  archDir = join(vault, "Brain", "projects", "arch", repoKey(project));
});

afterEach(() => {
  rmSync(tmp, { recursive: true, force: true });
});

/** What one child run reported about the disk it found. */
interface RunReport {
  readonly created: number;
  readonly updated: number;
  readonly unchanged: number;
}

/** Run `RUNNERS` copies of one architect run, released together. */
async function raceRuns(scriptName: string): Promise<ReadonlyArray<RunReport>> {
  const script = join(tmp, scriptName);
  writeFileSync(
    script,
    [
      // Imported BEFORE the barrier: module graph load is exactly the
      // startup stagger the barrier exists to absorb.
      `const { generateArchDocs } = await import(${JSON.stringify(GENERATE)});`,
      "const [vaultArg, projectArg, startAt] = process.argv.slice(2);",
      "while (Date.now() < Number(startAt)) Bun.sleepSync(1);",
      // A run that waits out LOCK_WAIT_INTERACTIVE_MS is refused by name
      // (ELOCKED) - the product's answer to a second run over one repo,
      // and not a lost update. How often that happens is a function of
      // the runner, not the lock: the third racer queues behind two whole
      // plan-and-write holds, which a slow Windows runner stretched past
      // the one-second budget. So the racer does what an operator would,
      // and runs again. Only a refusal is retried, so a run that read
      // outside the lock still reports what it read, and the tally below
      // still catches it.
      "let res;",
      `for (let attempt = 1; ; attempt += 1) {`,
      "  try { res = generateArchDocs(vaultArg, projectArg); break; }",
      `  catch (e) { if (e?.code !== "ELOCKED" || attempt >= ${MAX_REFUSALS}) throw e; }`,
      "}",
      "process.stdout.write(JSON.stringify({",
      "  created: res.created, updated: res.updated, unchanged: res.unchanged,",
      "}));",
    ].join("\n"),
    "utf8",
  );
  const startAt = String(Date.now() + BARRIER_LEAD_MS);
  const procs = Array.from({ length: RUNNERS }, () =>
    Bun.spawn(["bun", script, vault, project, startAt], {
      stdout: "pipe",
      stderr: "pipe",
      // Bun hands a child without `env` the environment this process STARTED
      // with, not the live `process.env`: pass it so the child sees the
      // throwaway config tests/setup.ts installs, not the operator's real one.
      env: { ...process.env },
    }),
  );
  const reports: RunReport[] = [];
  const failures: string[] = [];
  await Promise.all(
    procs.map(async (proc) => {
      const out = await new Response(proc.stdout).text();
      const err = await new Response(proc.stderr).text();
      const code = await proc.exited;
      if (code !== 0) {
        failures.push(`exit ${code}: ${err.trim()}`);
        return;
      }
      reports.push(JSON.parse(out) as RunReport);
    }),
  );
  expect(failures).toEqual([]);
  return reports;
}

/** Reports that claim the run changed something, and the ones that do not. */
function split(reports: ReadonlyArray<RunReport>): {
  readonly acting: ReadonlyArray<RunReport>;
  readonly observing: ReadonlyArray<RunReport>;
} {
  return {
    acting: reports.filter((r) => r.created + r.updated > 0),
    observing: reports.filter((r) => r.created + r.updated === 0),
  };
}

describe("concurrent architect runs on one repo", () => {
  test(
    "only one of three simultaneous first runs may report creating the notes",
    async () => {
      const reports = await raceRuns("first-run-racer.ts");

      // The winner of the lock finds an empty tree; the two that queue
      // behind it must find the tree it left, note for note.
      expect(split(reports).acting).toEqual([{ created: NOTE_COUNT, updated: 0, unchanged: 0 }]);
      expect(split(reports).observing).toEqual([
        { created: 0, updated: 0, unchanged: NOTE_COUNT },
        { created: 0, updated: 0, unchanged: NOTE_COUNT },
      ]);
      expect(existsSync(`${archDir}.lock`)).toBe(false);
    },
    SPAWN_TIMEOUT_MS,
  );

  test(
    "only one of three simultaneous re-runs may report refreshing the notes",
    async () => {
      // The read-modify-write shape proper: every note already exists, so
      // each run's plan is a `readFileSync` plus a `mergeRegions` of what
      // it read. Three runs that all read the same "before" state all
      // decide the same three notes need rewriting.
      const first = generateArchDocs(vault, project);
      expect(first.created).toBe(NOTE_COUNT);

      // One module gains a file and a new module appears: overview.md and
      // m00.md change, znew.md is new, and the other 40 notes - the 39
      // untouched modules plus the key-decisions note, whose candidate set
      // did not move - are already right.
      writeFileSync(join(project, "src", "m00", "extra.ts"), "// extra\n", "utf8");
      mkdirSync(join(project, "src", "znew"), { recursive: true });
      writeFileSync(join(project, "src", "znew", "a.ts"), "// new\n", "utf8");

      const reports = await raceRuns("rerun-racer.ts");

      expect(split(reports).acting).toEqual([
        { created: 1, updated: 2, unchanged: NOTE_COUNT - 2 },
      ]);
      expect(split(reports).observing).toEqual([
        { created: 0, updated: 0, unchanged: NOTE_COUNT + 1 },
        { created: 0, updated: 0, unchanged: NOTE_COUNT + 1 },
      ]);
      expect(existsSync(`${archDir}.lock`)).toBe(false);
    },
    SPAWN_TIMEOUT_MS,
  );
});