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
37.0 KB
Raw Blame
/**
 * The in-vault state inventory: declaration, measurement, rendering.
 *
 * `STATE_SURFACES` is a declaration, so most of what can go wrong with it
 * is a row that no longer describes the resolver it claims to describe.
 * The binding block below is the guard against exactly that: a row whose
 * owning resolver is EXPORTED is compared against it, so a rename inside
 * `brain/paths.ts` or `search/paths.ts` fails here rather than printing a
 * path nothing writes, and a row whose resolver is PRIVATE is bound by
 * driving the module's own exported writer against a temporary vault and
 * asking whether the artifact landed where the row says it does.
 *
 * Both halves exist because half a guard reads exactly like a whole one.
 * This block bound 26 of the 40 rows and the state-surface census
 * delegated row-path correctness to it in prose, so the other fourteen -
 * the writer lock, the session focus, the protect manifest, the
 * maintenance journal, the watchdog audit fallback, the inject cache, the
 * Aider sidecar, the Brain log, the continuity and lineage ledgers, the
 * anticipatory cache, the metrics tree, the skill accept journal and the
 * Claude memory manifest - were checked by nothing at all: renaming
 * `WATCHDOG_AUDIT_DIR` to a deliberately wrong value left the suite
 * green. Every row is bound now, and the count of deliberate exceptions
 * is itself asserted.
 *
 * The measured half has one rule the whole design turns on: "it is not
 * there" and "I could not look" are different repairs. Both directions
 * are driven below, because a probe that swallows an `EACCES` into
 * `absent` reads exactly like a healthy vault that has not been used yet.
 */

import { afterEach, describe, expect, test } from "bun:test";
import { selfHealUpgradeMarkerPath } from "../../../src/core/maintenance/self-heal-upgrade-state.ts";
import {
  EMPTY_FRESHEN_STATE,
  FRESHEN_STATE_FILE,
  writeFreshenState,
} from "../../../src/core/search/freshen.ts";
import { chmodSync, existsSync, mkdirSync, statSync, symlinkSync, writeFileSync } from "node:fs";
import { dirname, join, resolve, sep } from "node:path";

import {
  brainArtifactsDir,
  brainDirs,
  claimGraphPath,
  crossTopicLedgerPath,
  dreamRunsDir,
  hookAuditDir,
  prefAuditDir,
  proceduralGraphPath,
  proceduralHintsPath,
  proceduralMemoryUsagePath,
  proceduralRecurrencePath,
  proposalWatermarkPath,
  queryDemandLogPath,
  rollupLedgerPath,
  skillAcceptJournalPath,
  snapshotsDir,
  brainStateDir,
  captureDecisionLogPath,
  captureWatermarkPath,
  writeImagesDir,
} from "../../../src/core/brain/paths.ts";
import { deadLetterDir } from "../../../src/core/brain/dead-letter.ts";
import {
  attestationsDir,
  buildAttestationRecord,
  writeAttestationRecord,
} from "../../../src/core/brain/attestation/record.ts";
import {
  attestationKeysDir,
  generateAttestationKeypair,
} from "../../../src/core/brain/attestation/signing.ts";
import { collectAttestationManifest } from "../../../src/core/brain/attestation/digest.ts";
import { sourceArchivesDir } from "../../../src/core/brain/provenance/source-archive.ts";
import { decisionLedgerDir } from "../../../src/core/brain/permissions/ledger.ts";
import { checkpointPath } from "../../../src/core/brain/ingest/checkpoint.ts";
import { sessionCheckpointPath } from "../../../src/core/brain/sessions/checkpoint.ts";
import { manifestPath as ingestManifestPath } from "../../../src/core/brain/ingest/content-manifest.ts";
import { sessionLedgerPath } from "../../../src/core/brain/sessions/discover.ts";
import { sessionMiningLedgerPath } from "../../../src/core/brain/session-mining-ledger.ts";
import { sessionMiningSurveysPath } from "../../../src/core/brain/session-mining-surveys.ts";
import { secretsDir } from "../../../src/core/brain/secrets/store.ts";
import { manifestPath as installManifestPath } from "../../../src/core/install/manifest.ts";
import { instructionBlockLockPath } from "../../../src/core/install/instruction-block.ts";
import { lessonsApprovalsPath } from "../../../src/core/brain/lessons-promotion.ts";
import { skillBenchmarkTasksPath } from "../../../src/core/brain/paths.ts";
import { bootstrapReceiptPath } from "../../../src/cli/bootstrap/receipt.ts";
import { receiptsDir } from "../../../src/core/brain/decisions/receipts.ts";
import { anticipatoryCachePath } from "../../../src/core/brain/anticipatory-cache.ts";
import { continuityLogPath } from "../../../src/core/brain/continuity/store.ts";
import { frozenMarkerPath } from "../../../src/core/brain/freeze-marker.ts";
import { repairCandidatesStorePath } from "../../../src/core/brain/link-graph/hub-candidates.ts";
import { sessionLineageLedgerPath } from "../../../src/core/brain/lineage/ledger.ts";
import { appendJournal, MAINTENANCE_VERDICT } from "../../../src/core/brain/maintenance/journal.ts";
import { acquireLease, MAINTENANCE_LEASE_NAME } from "../../../src/core/brain/maintenance/lease.ts";
import { appendMetric } from "../../../src/core/brain/metrics.ts";
import { saveManifest as saveClaudeMemoryManifest } from "../../../src/core/brain/claude-memory-manifest.ts";
import { writeInjectCache } from "../../../src/core/brain/inject-failopen.ts";
import { writeManifest as writeProtectManifest } from "../../../src/core/brain/protect.ts";
import { runBrainWatchdog } from "../../../src/core/brain/watchdog.ts";
import { resolveAiderSidecarPath } from "../../../src/core/install/adapters/aider-wrapper.ts";
import type { InstallEnv } from "../../../src/core/install/types.ts";
import { feedbackDir, learnedWeightsPath } from "../../../src/core/search/feedback.ts";
import { reinforceDir } from "../../../src/core/search/reinforce.ts";
import { tuningPath } from "../../../src/core/search/tuning-store.ts";
import { activationDir } from "../../../src/core/search/activation/store.ts";
import { providerRegistryPath } from "../../../src/core/search/embeddings/registry.ts";
import { rerankRegistryPath } from "../../../src/core/search/rerank/registry.ts";
import { resolveIndexPath } from "../../../src/core/search/paths.ts";
import { sessionFocusPath } from "../../../src/core/search/session-focus.ts";
import { acquireWriterLockSync } from "../../../src/core/search/store/writer-lock.ts";
import type { ResolvedSearchConfig } from "../../../src/core/search/types.ts";
import { hookStateFilePath } from "../../../hooks/lib/session-state.ts";
import { CONFIG_ORIGIN } from "../../../src/core/validate.ts";
import {
  inventoryStateSurfaces,
  isStateSurfaceId,
  isStateReachability,
  isStateTier,
  renderStateInventory,
  STATE_REACHABILITIES,
  STATE_REACHABILITY,
  STATE_SURFACE_ID,
  STATE_SURFACE_IDS,
  STATE_SURFACES,
  STATE_TIER,
  STATE_TIERS,
  type StateSurfaceId,
} from "../../../src/core/state/surfaces.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";
import { tempDirs } from "../../helpers/temp-dir.ts";
import { useUnshardedLegacyLog } from "../../helpers/device-id.ts";

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

const mkTemp = tempDirs();

/**
 * Writer locks a drive took to look at, released after each test.
 * `proper-lockfile` keeps refreshing a held lock on a timer: one left held
 * outlives its vault, and the refresh that then fails throws out of a timer
 * into whatever test file happens to be running.
 */
const heldLocks: Array<() => void> = [];
afterEach(() => {
  for (const release of heldLocks.splice(0)) release();
});

const EMPTY_ENV: NodeJS.ProcessEnv = Object.freeze({});
const EMPTY_CONFIG: Readonly<Record<string, string>> = Object.freeze({});

function tempVault(): string {
  const vault = mkTemp("osb-state-surfaces-");
  // A legacy Brain/ tree: an unswitched machine, whose writers still put
  // bytes in the vault (a vault without one is store-only).
  mkdirSync(join(vault, "Brain"), { recursive: true });
  return vault;
}

function row(id: StateSurfaceId) {
  const found = STATE_SURFACES.find((surface) => surface.id === id);
  expect(`${id} is declared: ${found !== undefined}`).toBe(`${id} is declared: true`);
  return found!;
}

function reportFor(vault: string, id: StateSurfaceId) {
  const inventory = inventoryStateSurfaces({ vault, env: EMPTY_ENV, config: EMPTY_CONFIG });
  const found = inventory.surfaces.find((surface) => surface.id === id);
  expect(`${id} is reported: ${found !== undefined}`).toBe(`${id} is reported: true`);
  return found!;
}

describe("the state-surface vocabulary", () => {
  test("the members list and the object agree, and the guard accepts exactly them", () => {
    // `Object.values(STATE_SURFACE_IDS)` compared the array with itself:
    // the array IS `Object.values(STATE_SURFACE_ID)`, so the assertion
    // read `X.toSorted()` against `X.toSorted()` and could not fail. The
    // intended operand is the frozen OBJECT, which is the declaration the
    // list is derived from and the only thing worth comparing it to.
    const values = Object.values(STATE_SURFACE_ID);
    expect([...STATE_SURFACE_IDS].toSorted()).toEqual(values.toSorted());
    for (const id of STATE_SURFACE_IDS) expect(isStateSurfaceId(id)).toBe(true);
    expect(isStateSurfaceId("no_such_surface")).toBe(false);
    expect(isStateSurfaceId(7)).toBe(false);
  });

  test("the tier vocabulary separates rebuildable state from vault content", () => {
    // Two members, and the census below leans on the separation: a
    // derived surface is one an operator may delete, and a vault-content
    // surface is one whose loss is permanent. One bucket would make the
    // inventory unable to say which is which.
    expect([...STATE_TIERS].toSorted()).toEqual([STATE_TIER.derived, STATE_TIER.vaultContent]);
    for (const tier of STATE_TIERS) expect(isStateTier(tier)).toBe(true);
    expect(isStateTier("cache")).toBe(false);
  });

  test("reachability has three members, and unchecked is one of them", () => {
    expect([...STATE_REACHABILITIES].toSorted()).toEqual(
      [
        STATE_REACHABILITY.present,
        STATE_REACHABILITY.absent,
        STATE_REACHABILITY.unchecked,
      ].toSorted(),
    );
    for (const state of STATE_REACHABILITIES) expect(isStateReachability(state)).toBe(true);
    expect(isStateReachability("missing")).toBe(false);
  });

  test("every row is declared once, with a reason a reader can act on", () => {
    const ids = STATE_SURFACES.map((surface) => surface.id);
    expect(ids.length).toBe(new Set(ids).size);
    expect(ids.toSorted()).toEqual([...STATE_SURFACE_IDS].toSorted());
    const thin = STATE_SURFACES.filter((surface) => surface.reason.trim().length < 40).map(
      (surface) => surface.id,
    );
    expect(thin.join("\n")).toBe("");
  });

  test("every declared source exists AND is the kind of thing its spelling claims", () => {
    // An anchor that rots orphans a surface silently; the census attributes
    // swept path builders through this field.
    //
    // The kind check is the second half and it is not decoration: a
    // trailing slash means "the modules in this directory" and a bare
    // name means "this module". `existsSync` alone accepted either
    // spelling for either thing, so `src/core/` and `src/core` were
    // interchangeable to it - and the looser of the two is the one that
    // answers for a whole tree.
    const repoRoot = join(import.meta.dir, "..", "..", "..");
    const wrong: string[] = [];
    for (const surface of STATE_SURFACES) {
      expect(`${surface.id} names a source: ${surface.sources.length > 0}`).toBe(
        `${surface.id} names a source: true`,
      );
      for (const source of surface.sources) {
        const directory = source.endsWith("/");
        const abs = join(repoRoot, directory ? source.slice(0, -1) : source);
        if (!existsSync(abs)) {
          wrong.push(`${surface.id}: ${source} does not exist`);
          continue;
        }
        const stat = statSync(abs);
        if (directory && !stat.isDirectory()) {
          wrong.push(`${surface.id}: ${source} ends in a slash but is not a directory`);
        }
        if (!directory && !stat.isFile()) {
          wrong.push(`${surface.id}: ${source} names a module but is not a file`);
        }
      }
    }
    expect(wrong.join("\n")).toBe("");
  });

  test("every derivation stays inside the vault it was handed", () => {
    // Absolute on the host (`C:\srv\...` on Windows), so it is the form a
    // resolver would hand back and the containment check uses the host
    // separator.
    const vault = resolve("/srv/vaults/example");
    const escaping = STATE_SURFACES.filter(
      (surface) => !surface.derive(vault, null).startsWith(`${vault}${sep}`),
    ).map((surface) => surface.id);
    expect(escaping.join("\n")).toBe("");
  });
});

/**
 * Row id -> the path its owning resolver computes, for every row whose
 * resolver is EXPORTED.
 *
 * A table rather than a list of statements, because the point is no
 * longer only "these rows are right": it is that the set of rows bound
 * here, plus {@link DRIVEN_BINDINGS}, plus {@link UNBOUND_ROWS}, is
 * every row there is. Twenty-six of forty rows were bound when this
 * block was three tests of hand-written expectations, and nothing
 * noticed the other fourteen - renaming `WATCHDOG_AUDIT_DIR` to a
 * deliberately wrong value left the whole suite green, because the
 * census that delegates row-path correctness here only ever checked
 * that a module PATH appeared in some row's `sources`.
 */
const RESOLVER_BINDINGS: ReadonlyArray<readonly [StateSurfaceId, (vault: string) => string]> =
  Object.freeze([
    // --- Under `<vault>/.open-second-brain/` -------------------------------
    ["search_index", (v) => resolveIndexPath(v, null)],
    [
      "search_session_focus",
      // `sessionFocusPath` reads two fields of the resolved search config
      // and nothing else, so the cast supplies exactly those. Building a
      // whole `ResolvedSearchConfig` here would bind this row to the
      // config loader rather than to the resolver that owns its path.
      (v) => dirname(sessionFocusPath({ vault: v, dbPath: "" } as ResolvedSearchConfig, "scope")),
    ],
    ["secret_custody", (v) => secretsDir(v)],
    ["ingest_content_manifest", (v) => ingestManifestPath(v)],
    ["ingest_checkpoints", (v) => dirname(checkpointPath(v, "0f1e2d3c"))],
    ["session_import_checkpoints", (v) => dirname(sessionCheckpointPath(v, "0f1e2d3c"))],
    ["write_dead_letters", (v) => deadLetterDir(v)],
    ["session_import_ledger", (v) => sessionLedgerPath(v)],
    ["session_mining_ledger", (v) => sessionMiningLedgerPath(v)],
    ["session_mining_surveys", (v) => sessionMiningSurveysPath(v)],
    ["attestations", (v) => attestationsDir(v)],
    ["attestation_keys", (v) => attestationKeysDir(v)],
    ["install_manifest", (v) => installManifestPath(v)],
    ["instruction_block_lock", (v) => instructionBlockLockPath(v)],
    [
      "lesson_approvals",
      // t_1e952e43: the approval ledger lives in the derived store beside
      // the install manifest; the kernel owns the one path spelling.
      (v) => lessonsApprovalsPath(v),
    ],
    [
      "skill_benchmarks",
      // The tasks file is what an operator authors and the receipt
      // verification reads; the row is the TREE above it (one directory
      // per skill), so the binding climbs two levels from the core
      // resolver's file to the directory the row declares.
      (v) => dirname(dirname(skillBenchmarkTasksPath(v, "example-skill"))),
    ],
    ["bootstrap_receipt", (v) => bootstrapReceiptPath(v)],
    ["hook_audit", (v) => hookAuditDir(v)],
    ["hook_session_state", (v) => dirname(hookStateFilePath(v, null))],
    ["self_heal_upgrade_marker", (v) => selfHealUpgradeMarkerPath(v)],
    // `freshen.ts` takes the directory its caller hands it, always
    // `dirname(config.dbPath)`, so the row is bound to the index resolver.
    ["freshen_state", (v) => join(dirname(resolveIndexPath(v, null)), FRESHEN_STATE_FILE)],
    ["aider_context_artifact", (v) => resolveAiderSidecarPath({ vault: v } as InstallEnv, {})],
    // --- Under `<vault>/Brain/` --------------------------------------------
    ["brain_log", (v) => brainDirs(v).log],
    ["continuity_ledger", (v) => dirname(continuityLogPath(v, "2026-08"))],
    ["dream_runs", (v) => dreamRunsDir(v)],
    ["pref_audit", (v) => prefAuditDir(v)],
    ["recurrence_ledger", (v) => proceduralRecurrencePath(v)],
    ["query_demand_ledger", (v) => queryDemandLogPath(v)],
    ["capture_decision_log", (v) => captureDecisionLogPath(v)],
    ["capture_watermark", (v) => captureWatermarkPath(v)],
    ["proposal_watermark", (v) => proposalWatermarkPath(v)],
    ["procedural_usage", (v) => proceduralMemoryUsagePath(v)],
    ["procedural_graph", (v) => proceduralGraphPath(v)],
    ["procedural_hints", (v) => proceduralHintsPath(v)],
    ["decision_receipts", (v) => receiptsDir(v)],
    ["lineage_ledger", (v) => sessionLineageLedgerPath(v)],
    ["freeze_marker", (v) => frozenMarkerPath(v)],
    ["repair_candidates", (v) => repairCandidatesStorePath(v)],
    ["write_images", (v) => writeImagesDir(v)],
    ["anticipatory_cache", (v) => dirname(anticipatoryCachePath(v, "root-session"))],
    ["exact_state", (v) => brainStateDir(v)],
    ["search_feedback", (v) => feedbackDir(v)],
    ["search_learned_weights", (v) => learnedWeightsPath(v)],
    ["search_reinforce", (v) => reinforceDir(v)],
    ["search_tuning", (v) => tuningPath(v)],
    ["search_embedding_providers", (v) => providerRegistryPath(v)],
    ["search_rerank_providers", (v) => rerankRegistryPath(v)],
    ["search_activation", (v) => activationDir(v)],
    ["snapshots", (v) => snapshotsDir(v)],
    ["mcp_artifacts", (v) => brainArtifactsDir(v)],
    ["skill_accept_journal", (v) => dirname(skillAcceptJournalPath(v, "probe"))],
    ["claim_graph", (v) => claimGraphPath(v)],
    ["rollup_ledger", (v) => rollupLedgerPath(v)],
    ["cross_topic_ledger", (v) => crossTopicLedgerPath(v)],
    ["decision_ledger", (v) => decisionLedgerDir(v)],
    ["source_archives", (v) => sourceArchivesDir(v)],
  ]);

/**
 * A row whose resolver is module-private, bound by DRIVING the module's
 * own exported writer against a real temporary vault.
 *
 * The comparison is not "something appeared under the vault": that would
 * pass for a row naming any ancestor of the real location. Each entry
 * names the concrete artifact the write produces AS A FUNCTION OF THE
 * ROW'S OWN PATH, so a row pointing one directory up, or at a sibling,
 * has nowhere for that artifact to be.
 */
interface DrivenBinding {
  readonly id: StateSurfaceId;
  /**
   * Make the owning module write, through its exported surface only.
   * Return the path the writer REPORTS having written when it reports
   * one - a report is a stronger binding than "something appeared" -
   * and `null` when it reports nothing.
   */
  readonly drive: (vault: string) => string | null;
  /** The artifact the drive creates, expressed from the row's own path. */
  readonly artifact: (derived: string) => string;
}

const DRIVEN_BINDINGS: ReadonlyArray<DrivenBinding> = Object.freeze([
  {
    // `leaseDbPath` is private; `acquireLease` creates the database.
    id: STATE_SURFACE_ID.maintenanceLease,
    drive: (vault) => {
      acquireLease(vault, {
        name: MAINTENANCE_LEASE_NAME,
        holder: "state-surface-binding",
        ttlMs: 60_000,
        now: new Date("2026-08-16T10:00:00.000Z"),
      });
      return null;
    },
    artifact: (derived) => derived,
  },
  {
    // `journalPath` is private; `appendJournal` writes the JSONL.
    id: STATE_SURFACE_ID.maintenanceJournal,
    drive: (vault) => {
      appendJournal(vault, {
        ts: "2026-08-16T10:00:00.000Z",
        holder: "state-surface-binding",
        verdict: MAINTENANCE_VERDICT.run,
      });
      return null;
    },
    artifact: (derived) => derived,
  },
  {
    // The protect manifest path is private; `writeManifest` is not.
    id: STATE_SURFACE_ID.protectManifest,
    drive: (vault) => {
      writeProtectManifest(vault, {
        schema_version: 1,
        target: "claudecode",
        vault,
        owned_deny: [],
        owned_allow: [],
      });
      return null;
    },
    artifact: (derived) => derived,
  },
  {
    // `cachePath` is private; the row is the DIRECTORY, so the artifact
    // is the cache file the write puts inside it.
    id: STATE_SURFACE_ID.injectFailopenCache,
    drive: (vault) => {
      writeInjectCache(vault, "state-surface-binding", "cached body");
      return null;
    },
    artifact: (derived) => join(derived, "state-surface-binding.txt"),
  },
  {
    // `metricsDir` is private; same directory-plus-artifact shape.
    id: STATE_SURFACE_ID.metrics,
    drive: (vault) => {
      appendMetric(vault, {
        surface: "state_surface_binding",
        runAt: "2026-08-16T10:00:00Z",
        payload: {},
      });
      return null;
    },
    artifact: (derived) => join(derived, "state_surface_binding.jsonl"),
  },
  {
    // `manifestPath` is private; `saveManifest` writes the row's file.
    id: STATE_SURFACE_ID.claudeMemoryManifest,
    drive: (vault) => {
      saveClaudeMemoryManifest(vault, { version: 1, imports: {} });
      return null;
    },
    artifact: (derived) => derived,
  },
  {
    // The FALLBACK the watchdog uses when its configured audit directory
    // refuses the write, so the drive has to make that directory refuse:
    // `Brain/log/watchdog` is pre-created as a FILE, and `mkdirSync` on
    // it throws. `runBrainWatchdog` reports the path it landed on, which
    // is what makes this a comparison and not a sighting.
    id: STATE_SURFACE_ID.watchdogAudit,
    drive: (vault) => {
      const log = brainDirs(vault).log;
      mkdirSync(log, { recursive: true });
      writeFileSync(join(log, "watchdog"), "not a directory", "utf8");
      return runBrainWatchdog(vault).audit_path;
    },
    artifact: (derived) => derived,
  },
  {
    // The attestation writer reports the exact file it created; the row
    // declares the DIRECTORY, so the report binds through dirname.
    id: STATE_SURFACE_ID.attestations,
    drive: (vault) =>
      writeAttestationRecord(
        vault,
        buildAttestationRecord(vault, collectAttestationManifest(vault), {
          now: new Date("2026-08-16T10:00:00Z"),
        }),
      ).path,
    artifact: (derived) => derived,
  },
  {
    // The signing keys appear when the operator generates a keypair; the
    // row declares the directory both halves live in.
    id: STATE_SURFACE_ID.attestationKeys,
    drive: (vault) => {
      generateAttestationKeypair(vault);
      return null;
    },
    artifact: (derived) => derived,
  },
  {
    // No resolver at all: the `.lock` suffix is `proper-lockfile`'s, and
    // the only honest way to bind it is to take the lock and look.
    id: STATE_SURFACE_ID.searchWriterLock,
    drive: (vault) => {
      const index = row(STATE_SURFACE_ID.searchIndex).derive(vault, null);
      mkdirSync(dirname(index), { recursive: true });
      heldLocks.push(acquireWriterLockSync(index));
      return null;
    },
    artifact: (derived) => derived,
  },
]);

/**
 * Rows deliberately left unbound, each with the reason no binding is
 * reachable. An entry here is a decision; the absence of one is not.
 *
 * EMPTY today, and that is the finding: of the fourteen rows nothing
 * bound, every one turned out to have either an exported resolver or an
 * exported writer that reports where it wrote. The map and its count
 * stay because the next row added to the catalogue is the one that will
 * want an excuse, and an excuse should have to be typed.
 */
const UNBOUND_ROWS: ReadonlyMap<StateSurfaceId, string> = new Map();

/** How many rows are deliberately unbound. An equality, so a new one is a decision. */
const UNBOUND_ROW_COUNT = 0;

/** An unbound reason has to be an argument, at the bar the censuses use. */
const MIN_UNBOUND_REASON_LENGTH = 80;

describe("each row is bound to the resolver that owns it", () => {
  // A legacy vault: the row names the legacy location the migration reads,
  // which is where an unswitched machine's resolver puts it. A vault with
  // no `Brain/` is store-only and resolves to device-local state instead.
  // Host-absolute: resolvers `resolve()` the vault, which on Windows adds
  // the drive, while the row joins what it was handed.
  for (const [id, resolver] of RESOLVER_BINDINGS) {
    test(`${id} derives what its resolver returns`, () => {
      const vault = resolve(tempVault());
      expect(row(id).derive(vault, null)).toBe(resolver(vault));
    });
  }

  test("the cross-topic rule ledger names its Brain/ file exactly (t_642bc2b8)", () => {
    const example = resolve(tempVault());
    expect(crossTopicLedgerPath(example)).toBe(join(example, "Brain", "cross-topic-rules.json"));
    expect(row(STATE_SURFACE_ID.crossTopicLedger).derive(example, null)).toBe(
      crossTopicLedgerPath(example),
    );
    // Nothing creates the ledger at init - it appears with the first
    // fired promotion - so a fresh vault reports it absent, not unchecked.
    expect(reportFor(tempVault(), STATE_SURFACE_ID.crossTopicLedger).reachability.state).toBe(
      STATE_REACHABILITY.absent,
    );
  });

  test("the search index follows its override, and so does everything derived from it", () => {
    const vault = resolve(tempVault());
    const elsewhere = "/elsewhere/brain.sqlite";
    expect(row("search_index").derive(vault, elsewhere)).toBe(resolveIndexPath(vault, elsewhere));
    expect(row("search_writer_lock").derive(vault, elsewhere)).toBe(`${elsewhere}.lock`);
    expect(row("search_session_focus").derive(vault, elsewhere)).toBe(
      dirname(sessionFocusPath({ vault, dbPath: elsewhere } as ResolvedSearchConfig, "scope")),
    );
    expect(row("freshen_state").derive(vault, elsewhere)).toBe(
      join(dirname(elsewhere), FRESHEN_STATE_FILE),
    );
  });

  test("a relocated index moves the freshen state to where the run writes it", () => {
    const home = tempVault();
    const elsewhere = join(tempVault(), "brain.sqlite");
    writeFreshenState(dirname(elsewhere), EMPTY_FRESHEN_STATE);
    const inventory = inventoryStateSurfaces({
      vault: home,
      env: { OPEN_SECOND_BRAIN_SEARCH_DB: elsewhere },
      config: EMPTY_CONFIG,
    });
    const state = inventory.surfaces.find((s) => s.id === "freshen_state")!;
    expect(state.path).toBe(join(dirname(elsewhere), FRESHEN_STATE_FILE));
    expect(state.origin).toBe(CONFIG_ORIGIN.env);
    expect(existsSync(state.path)).toBe(true);
  });

  for (const binding of DRIVEN_BINDINGS) {
    test(`${binding.id} is where its own writer puts bytes`, () => {
      const temp = tempVault();
      const derived = row(binding.id).derive(temp, null);
      const artifact = binding.artifact(derived);
      expect(existsSync(artifact)).toBe(false);
      const reported = binding.drive(temp);
      expect(existsSync(artifact)).toBe(true);
      // A writer that names the path it wrote is held to it exactly:
      // either it IS the artifact, or it sits directly in the directory
      // the row declares. Anything else means the row and the writer
      // disagree about where this surface lives.
      if (reported !== null) {
        expect(reported === artifact || dirname(reported) === artifact).toBe(true);
      }
    });
  }

  test("every declared row is bound, or is one of the counted exceptions", () => {
    // The assertion the fourteen unbound rows needed. Without it a new
    // row joins the catalogue bound to nothing, and the census that
    // delegates path correctness to this block keeps saying it is
    // covered here.
    const bound = new Set<string>([
      ...RESOLVER_BINDINGS.map(([id]) => id),
      ...DRIVEN_BINDINGS.map((binding) => binding.id),
    ]);
    const overlap = [...UNBOUND_ROWS.keys()].filter((id) => bound.has(id));
    expect(overlap.join("\n")).toBe("");
    const unaccounted = STATE_SURFACE_IDS.filter((id) => !bound.has(id) && !UNBOUND_ROWS.has(id));
    expect(unaccounted.toSorted().join("\n")).toBe("");
    const stale = [...UNBOUND_ROWS.keys()].filter((id) => !isStateSurfaceId(id));
    expect(stale.join("\n")).toBe("");
    expect(UNBOUND_ROWS.size).toBe(UNBOUND_ROW_COUNT);
  });

  test("every deliberately unbound row says why, at the bar the censuses use", () => {
    const thin = [...UNBOUND_ROWS.entries()]
      .filter(
        ([, reason]) =>
          reason.trim().length < MIN_UNBOUND_REASON_LENGTH ||
          /\bTODO\b|\bfor now\b|\blater\b/i.test(reason),
      )
      .map(([id]) => id);
    expect(thin.join("\n")).toBe("");
  });
});

describe("the measured half", () => {
  test("a surface nothing has written reports absent, with the reason it is absent", () => {
    const report = reportFor(tempVault(), "maintenance_lease");
    expect(report.reachability.state).toBe(STATE_REACHABILITY.absent);
    expect(report.reachability.reason).not.toBeNull();
    expect(report.reachability.path).toBe(report.path);
  });

  test("a surface that exists reports present, with no reason to give", () => {
    const vault = tempVault();
    const path = row("maintenance_lease").derive(vault, null);
    mkdirSync(dirname(path), { recursive: true });
    writeFileSync(path, "", "utf8");
    const report = reportFor(vault, "maintenance_lease");
    expect(report.reachability.state).toBe(STATE_REACHABILITY.present);
    expect(report.reachability.reason).toBeNull();
  });

  test("a dangling symlink is present: something IS there, and it needs a decision", () => {
    // `statSync` follows the link and reports the missing TARGET as
    // ENOENT, so a surface whose root is a broken link read as `absent`
    // and `state migrate` skipped it in silence. Reporting it present is
    // what carries it to the `symlink` refusal, which is the one place
    // that knows what to tell the operator about a link.
    const vault = tempVault();
    const path = row("maintenance_lease").derive(vault, null);
    mkdirSync(dirname(path), { recursive: true });
    symlinkSync(join(vault, "nowhere"), path);

    const report = reportFor(vault, "maintenance_lease");
    expect(report.reachability.state).toBe(STATE_REACHABILITY.present);
    expect(report.reachability.reason).toBeNull();
  });

  test("a probe that cannot look reports unchecked, never absent", () => {
    // The whole point of the tri-state. A permission error folded into
    // `absent` tells the operator to create a file that is already there.
    const denied = new Error("EACCES: permission denied") as NodeJS.ErrnoException;
    denied.code = "EACCES";
    const inventory = inventoryStateSurfaces({
      vault: tempVault(),
      env: EMPTY_ENV,
      config: EMPTY_CONFIG,
      statAt: () => {
        throw denied;
      },
    });
    const states = new Set(inventory.surfaces.map((s) => s.reachability.state));
    expect([...states]).toEqual([STATE_REACHABILITY.unchecked]);
    const sample = inventory.surfaces[0]!;
    expect(sample.reachability.reason).toContain("EACCES");
  });

  test("the inventory reports one row per declared surface, in declaration order", () => {
    const inventory = inventoryStateSurfaces({
      vault: tempVault(),
      env: EMPTY_ENV,
      config: EMPTY_CONFIG,
    });
    expect(inventory.surfaces.map((s) => s.id)).toEqual(STATE_SURFACES.map((s) => s.id));
  });
});

describe("the origin names the layer that placed the path", () => {
  test("an environment override moves the path and is reported as env", () => {
    const vault = tempVault();
    const inventory = inventoryStateSurfaces({
      vault,
      env: { OPEN_SECOND_BRAIN_SEARCH_DB: "/elsewhere/brain.sqlite" },
      config: EMPTY_CONFIG,
    });
    const index = inventory.surfaces.find((s) => s.id === "search_index")!;
    expect(index.path).toBe("/elsewhere/brain.sqlite");
    expect(index.origin).toBe(CONFIG_ORIGIN.env);
    // Everything derived from the index follows it, or the inventory
    // would print a lock file beside a database nobody opens.
    const lock = inventory.surfaces.find((s) => s.id === "search_writer_lock")!;
    expect(lock.path).toBe("/elsewhere/brain.sqlite.lock");
    expect(lock.origin).toBe(CONFIG_ORIGIN.env);
  });

  test("a machine-config key moves the path and is reported as user-config", () => {
    const vault = tempVault();
    const inventory = inventoryStateSurfaces({
      vault,
      env: EMPTY_ENV,
      config: { search_db_path: "/elsewhere/brain.sqlite" },
    });
    const index = inventory.surfaces.find((s) => s.id === "search_index")!;
    expect(index.path).toBe("/elsewhere/brain.sqlite");
    expect(index.origin).toBe(CONFIG_ORIGIN.userConfig);
  });

  test("a row nothing can move reports default, whatever the environment holds", () => {
    const vault = tempVault();
    const inventory = inventoryStateSurfaces({
      vault,
      env: { OPEN_SECOND_BRAIN_SEARCH_DB: "/elsewhere/brain.sqlite" },
      config: { search_db_path: "/elsewhere/brain.sqlite" },
    });
    const drifted = inventory.surfaces
      .filter((s) => s.override_env === null && s.override_config_key === null)
      .filter((s) => s.origin !== CONFIG_ORIGIN.default)
      .map((s) => s.id);
    expect(drifted.join("\n")).toBe("");
  });
});

describe("one value, two renderings", () => {
  test("the rendered statement names every surface it was built from", () => {
    const inventory = inventoryStateSurfaces({
      vault: tempVault(),
      env: EMPTY_ENV,
      config: EMPTY_CONFIG,
    });
    const text = renderStateInventory(inventory);
    const unnamed = inventory.surfaces
      .filter((s) => !text.includes(s.label) || !text.includes(s.path))
      .map((s) => s.id);
    expect(unnamed.join("\n")).toBe("");
  });

  test("the rendering states the vault and the count it measured", () => {
    const vault = tempVault();
    const inventory = inventoryStateSurfaces({ vault, env: EMPTY_ENV, config: EMPTY_CONFIG });
    const text = renderStateInventory(inventory);
    expect(text).toContain(vault);
    expect(text).toContain(String(inventory.surfaces.length));
  });

  test("an unchecked surface is never rendered as an absent one", () => {
    const denied = new Error("EACCES: permission denied") as NodeJS.ErrnoException;
    denied.code = "EACCES";
    const inventory = inventoryStateSurfaces({
      vault: tempVault(),
      env: EMPTY_ENV,
      config: EMPTY_CONFIG,
      statAt: () => {
        throw denied;
      },
    });
    const text = renderStateInventory(inventory);
    expect(text).toContain("EACCES");
    expect(text).not.toContain("nothing has created it");
  });
});

function logDir(vault: string): string {
  return join(vault, "Brain", "log");
}

describe("sharded ledger surfaces (t_774dea61)", () => {
  test("a fixed-name ledger surface is present when only a device shard exists", () => {
    const vault = tempVault();
    mkdirSync(logDir(vault), { recursive: true });
    const shard = join(logDir(vault), "query-demand.device-x.jsonl");
    writeFileSync(shard, "{}\n", "utf8");

    const report = reportFor(vault, STATE_SURFACE_ID.queryDemandLedger);

    expect(report.reachability.state).toBe(STATE_REACHABILITY.present);
    expect(report.reachability.path).toBe(shard);
  });

  test("the legacy name alone still reads present at its own path; neither reads absent", () => {
    const vault = tempVault();
    mkdirSync(logDir(vault), { recursive: true });
    const legacy = join(logDir(vault), "query-demand.jsonl");
    writeFileSync(legacy, "{}\n", "utf8");
    const present = reportFor(vault, STATE_SURFACE_ID.queryDemandLedger).reachability;
    expect(present.state).toBe(STATE_REACHABILITY.present);
    expect(present.path).toBe(legacy);

    const empty = tempVault();
    mkdirSync(logDir(empty), { recursive: true });
    expect(reportFor(empty, STATE_SURFACE_ID.queryDemandLedger).reachability.state).toBe(
      STATE_REACHABILITY.absent,
    );
    expect(reportFor(tempVault(), STATE_SURFACE_ID.queryDemandLedger).reachability.state).toBe(
      STATE_REACHABILITY.absent,
    );
  });

  test("a conflict copy alone is not a shard and does not make the surface present", () => {
    const vault = tempVault();
    mkdirSync(logDir(vault), { recursive: true });
    writeFileSync(join(logDir(vault), "recurrence-support.sync-conflict-x.jsonl"), "{}\n", "utf8");
    expect(reportFor(vault, STATE_SURFACE_ID.recurrenceLedger).reachability.state).toBe(
      STATE_REACHABILITY.absent,
    );
  });

  test("the maintenance journal and the lineage ledger read their device shards too", () => {
    const vault = tempVault();
    const journal = join(vault, ".open-second-brain", "maintenance-runs.device-x.jsonl");
    const lineage = join(vault, "Brain", ".state", "session-lineage.device-x.jsonl");
    for (const path of [journal, lineage]) {
      mkdirSync(dirname(path), { recursive: true });
      writeFileSync(path, "{}\n", "utf8");
    }

    expect(reportFor(vault, STATE_SURFACE_ID.maintenanceJournal).reachability.path).toBe(journal);
    expect(reportFor(vault, STATE_SURFACE_ID.lineageLedger).reachability.path).toBe(lineage);
  });

  test.skipIf(CHMOD_CANNOT_DENY)(
    "a ledger directory that cannot be listed is unchecked by its code, never absent",
    () => {
      const vault = tempVault();
      mkdirSync(logDir(vault), { recursive: true });
      // Traversable but not listable: the legacy stat answers ENOENT, the
      // shard listing answers EACCES.
      chmodSync(logDir(vault), 0o300);
      try {
        const verdict = reportFor(vault, STATE_SURFACE_ID.captureDecisionLog).reachability;
        expect(verdict.state).toBe(STATE_REACHABILITY.unchecked);
        expect(verdict.reason).toContain("EACCES");
      } finally {
        chmodSync(logDir(vault), 0o700);
      }
    },
  );
});