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
8.7 KB
Raw Blame
/**
 * An unreachable origin is reported, never dropped (a-label-is-not-a-boundary,
 * U5; t_a160764a, t_77efc212).
 *
 * `listSearchOrigins` used to remove a broken recall source from the fan-out
 * before `cross-vault.ts` could see it, so a union over three origins with one
 * dead origin came back as though that origin had honestly contributed
 * nothing. `warnings` was maintained one layer down and could not be
 * populated, because the information was destroyed upstream.
 *
 * The three verdicts are distinct on purpose: `reachable` was read,
 * `unreachable` was looked at and is not there, `unknown` could not be looked
 * at at all. None of the three is a count of zero.
 */

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

import {
  ORIGIN_REACH,
  ORIGIN_REACHES,
  ORIGIN_REACH_REASON,
  ORIGIN_REACH_REASONS,
  isOriginReach,
  isOriginReachReason,
  probeOriginReach,
} from "../../../src/core/brain/portability/origin-reach.ts";
import { listSearchOrigins } from "../../../src/core/brain/portability/origins.ts";
import { addRecallSource } from "../../../src/core/brain/portability/recall-sources.ts";
import { RETRIEVAL_DEGRADATION } from "../../../src/core/search/retrieval-trail.ts";
import { searchAcrossVaults } from "../../../src/core/search/cross-vault.ts";
import { indexVault } from "../../../src/core/search/indexer.ts";
import { resolveSearchConfig } from "../../../src/core/search/index.ts";
import { writeMd } from "../../helpers/search-fixtures.ts";
import { CHMOD_CANNOT_DENY } from "../../helpers/platform.ts";

let tmp: string;
let active: string;
let external: string;
let configPath: string;

beforeEach(async () => {
  tmp = mkdtempSync(join(tmpdir(), "o2b-origin-reach-"));
  active = join(tmp, "active-vault");
  external = join(tmp, "external-vault");
  mkdirSync(join(active, "Brain"), { recursive: true });
  mkdirSync(join(external, "Brain"), { recursive: true });
  configPath = join(tmp, "config.yaml");
  writeFileSync(configPath, `vault: "${active}"\n`);

  writeMd(active, "Brain/notes/local-note.md", "# Local\n\nThe griffin nests in the local vault.");
  writeMd(
    external,
    "Brain/notes/external-note.md",
    "# External\n\nThe griffin also visits the external vault aviary.",
  );
  await indexVault(resolveSearchConfig({ vault: active, configPath }));
  await indexVault(resolveSearchConfig({ vault: external, configPath }));
});

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

/** Register a source that existed at registration time and then vanished. */
function registerVanishedSource(alias: string): string {
  const vault = join(tmp, `${alias}-vault`);
  mkdirSync(join(vault, "Brain"), { recursive: true });
  addRecallSource(configPath, active, alias, vault);
  rmSync(vault, { recursive: true, force: true });
  return vault;
}

test("a union across three origins with one unreachable warns by name", async () => {
  addRecallSource(configPath, active, "team", external);
  const gone = registerVanishedSource("gone");

  const outcome = await searchAcrossVaults(configPath, active, { query: "griffin", limit: 10 });

  // The two origins that could be read still answer.
  expect(new Set(outcome.results.map((r) => r.origin))).toEqual(new Set(["local", "source/team"]));
  // And the third is NAMED rather than silently absent.
  const warning = outcome.warnings.find((w) => w.includes("source/gone"));
  expect(warning).toBeDefined();
  expect(warning).toContain(ORIGIN_REACH_REASON.vaultMissing);
  // The origin's path never crosses this boundary - the label is the
  // actionable part, and warnings travel verbatim into MCP payloads.
  expect(outcome.warnings.some((w) => w.includes(gone))).toBe(false);
  // The same fact as a code, so a caller does not have to read prose.
  const entry = outcome.retrievalTrail?.degraded.find(
    (d) => d.code === RETRIEVAL_DEGRADATION.crossVaultOriginFailed,
  );
  expect(entry?.detail).toEqual({
    origin: "source/gone",
    cause: ORIGIN_REACH_REASON.vaultMissing,
  });
});

test("listSearchOrigins reports an unreachable origin rather than dropping it", () => {
  addRecallSource(configPath, active, "team", external);
  registerVanishedSource("gone");

  const origins = listSearchOrigins(configPath, active);
  expect(origins.map((o) => o.label)).toEqual(["local", "source/gone", "source/team"]);

  const dead = origins.find((o) => o.label === "source/gone");
  expect(dead?.reach).toBe(ORIGIN_REACH.unreachable);
  expect(dead?.reason).toBe(ORIGIN_REACH_REASON.vaultMissing);
  expect(origins.find((o) => o.label === "local")?.reach).toBe(ORIGIN_REACH.reachable);
  expect(origins.find((o) => o.label === "source/team")?.reason).toBeUndefined();
});

// chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
test.skipIf(CHMOD_CANNOT_DENY)(
  "unreachable and unknown are different values, and neither reads as zero",
  async () => {
    const holder = join(tmp, "holder");
    const shielded = join(holder, "shielded-vault");
    mkdirSync(join(shielded, "Brain"), { recursive: true });
    addRecallSource(configPath, active, "shielded", shielded);
    registerVanishedSource("gone");
    // An unreadable parent makes the probe fail with something other than
    // ENOENT: the origin may well be there, and nothing was learned about it.
    chmodSync(holder, 0o000);
    try {
      const origins = listSearchOrigins(configPath, active);
      const unknown = origins.find((o) => o.label === "source/shielded");
      const missing = origins.find((o) => o.label === "source/gone");
      expect(unknown?.reach).toBe(ORIGIN_REACH.unknown);
      expect(missing?.reach).toBe(ORIGIN_REACH.unreachable);
      expect(unknown?.reach).not.toBe(missing?.reach);
      expect(unknown?.reason).toBe(ORIGIN_REACH_REASON.vaultUnreadable);

      const outcome = await searchAcrossVaults(configPath, active, { query: "griffin", limit: 10 });
      // Neither origin contributed a result, and neither is reported as a
      // zero contribution: both are named, each with its own reason.
      expect(outcome.warnings.some((w) => w.includes("source/shielded"))).toBe(true);
      expect(outcome.warnings.some((w) => w.includes("source/gone"))).toBe(true);
      const causes = (outcome.retrievalTrail?.degraded ?? [])
        .filter((d) => d.code === RETRIEVAL_DEGRADATION.crossVaultOriginFailed)
        .map((d) => d.detail?.["cause"]);
      expect(causes).toContain(ORIGIN_REACH_REASON.vaultUnreadable);
    } finally {
      chmodSync(holder, 0o755);
    }
  },
);

test("the shared namespace is enumerable as a read origin", () => {
  const shared = join(tmp, "shared-vault");
  mkdirSync(join(shared, "Brain"), { recursive: true });
  writeFileSync(configPath, `vault: "${active}"\nshared_namespace: "${shared}"\n`);

  const origins = listSearchOrigins(configPath, active);
  const sharedOrigin = origins.find((o) => o.kind === "shared");
  expect(sharedOrigin?.label).toBe("shared");
  expect(sharedOrigin?.vault).toBe(shared);
  expect(sharedOrigin?.reach).toBe(ORIGIN_REACH.reachable);
});

test("a shared namespace pointing at the active vault is deduped, not listed twice", () => {
  writeFileSync(configPath, `vault: "${active}"\nshared_namespace: "${active}"\n`);
  expect(listSearchOrigins(configPath, active).map((o) => o.label)).toEqual(["local"]);
});

// chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
test.skipIf(CHMOD_CANNOT_DENY)(
  "probeOriginReach splits absent, not-a-directory, and could-not-look",
  () => {
    expect(probeOriginReach(active).reach).toBe(ORIGIN_REACH.reachable);
    expect(probeOriginReach(join(tmp, "never-existed"))).toEqual({
      reach: ORIGIN_REACH.unreachable,
      reason: ORIGIN_REACH_REASON.vaultMissing,
    });
    const file = join(tmp, "a-file");
    writeFileSync(file, "not a vault");
    expect(probeOriginReach(file)).toEqual({
      reach: ORIGIN_REACH.unreachable,
      reason: ORIGIN_REACH_REASON.vaultNotDirectory,
    });
    expect(probeOriginReach(join(file, "under-a-file"))).toEqual({
      reach: ORIGIN_REACH.unreachable,
      reason: ORIGIN_REACH_REASON.vaultNotDirectory,
    });
  },
);

test("the reachability vocabulary is closed in both directions", () => {
  expect([...ORIGIN_REACHES]).toEqual([
    ORIGIN_REACH.reachable,
    ORIGIN_REACH.unreachable,
    ORIGIN_REACH.unknown,
  ]);
  for (const member of ORIGIN_REACHES) expect(isOriginReach(member)).toBe(true);
  for (const member of ORIGIN_REACH_REASONS) expect(isOriginReachReason(member)).toBe(true);
  expect(isOriginReach("reachable-ish")).toBe(false);
  expect(isOriginReach(0)).toBe(false);
  expect(isOriginReachReason(null)).toBe(false);
});