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
/**
* Source-ingest pipeline (Knowledge Provenance suite). One text-bearing source
* becomes entity/concept pages plus a per-source summary page that backlinks
* the source, lists the entities it introduced, and lists its connections to
* pre-existing material. Idempotent on the source path. OSB runs no model -
* the agent supplies the extraction and the summary prose.
*/
import { afterEach, beforeEach, describe, expect, setDefaultTimeout, spyOn, test } from "bun:test";
import * as fs from "node:fs";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { join, relative } from "node:path";
import { tmpdir } from "node:os";
import { IS_WINDOWS } from "../../../helpers/platform.ts";
import { bootstrapBrain } from "../../../../src/core/brain/init.ts";
import { atomicWriteFileSync } from "../../../../src/core/fs-atomic.ts";
import {
getEntity,
listEntities,
upsertEntity,
} from "../../../../src/core/brain/entities/registry.ts";
import {
ingestSource,
PRE_EXTRACT_MAX_SOURCE_BYTES,
readSourceBounded,
} from "../../../../src/core/brain/ingest/ingest.ts";
import { manifestPath, hashBytes } from "../../../../src/core/brain/ingest/content-manifest.ts";
import { computeExtractionContractFingerprint } from "../../../../src/core/brain/ingest/contract.ts";
import { computePlanId, readCheckpoint } from "../../../../src/core/brain/ingest/checkpoint.ts";
import {
applyPendingLane,
listPendingLane,
WriteRefusedError,
} from "../../../../src/core/brain/pending/pending-lanes.ts";
import { REVIEW_LANE } from "../../../../src/core/brain/write-gate.ts";
import { entityPath } from "../../../../src/core/brain/paths.ts";
import { canonicalNotePath } from "../../../../src/core/path-safety.ts";
import { queryDecisionLedger } from "../../../../src/core/brain/permissions/ledger.ts";
import { deleteBySource } from "../../../../src/core/brain/source-cleanup.ts";
import { readManifest } from "../../../../src/core/brain/ingest/content-manifest.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);
function readManifestEntries(): string[] {
return Object.keys(readManifest(vault).entries);
}
/** The canonical vault-relative path of a created entity's page. */
function canonicalPage(category: string, id: string): string {
return canonicalNotePath(relative(vault, entityPath(vault, category, id)));
}
let vault: string;
let configHome: string;
const NOW = new Date("2026-06-13T12:00:00Z");
const LATER = new Date("2026-06-14T09:00:00Z");
beforeEach(() => {
vault = mkdtempSync(join(tmpdir(), "o2b-ingest-vault-"));
configHome = mkdtempSync(join(tmpdir(), "o2b-ingest-cfg-"));
const configPath = join(configHome, "config.yaml");
atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: claude\n`);
bootstrapBrain(vault, { configPath });
});
afterEach(() => {
rmSync(vault, { recursive: true, force: true });
rmSync(configHome, { recursive: true, force: true });
});
/**
* A source is trusted only when its file exists (GitHub #160), and an
* untrusted ingest quarantines the entities it introduces - so every case
* that reads its entities back from the canonical registry seeds the source
* it names. The cases that deliberately do NOT seed it are marked.
*/
function seedSourceFile(rel = INPUT.sourcePath): void {
const abs = join(vault, rel);
mkdirSync(join(abs, ".."), { recursive: true });
writeFileSync(abs, "the source bytes\n", "utf8");
}
/** Write raw bytes as the content manifest, for the corrupted-manifest cases. */
function writeManifestBytes(bytes: string): void {
const path = manifestPath(vault);
mkdirSync(join(path, ".."), { recursive: true });
writeFileSync(path, bytes, "utf8");
}
const INPUT = {
sourcePath: "Articles/restaking-primer.md",
summary: "An overview of restaking and its role for validators.",
extraction: {
entities: [
{ category: "concept", name: "Restaking" },
{ category: "concept", name: "Validators" },
],
relations: [{ from: "Restaking", relation: "related", to: "Validators" }],
},
};
function readSummary(summaryPath: string): string {
return readFileSync(join(vault, summaryPath), "utf8");
}
describe("ingestSource", () => {
test("creates entity pages and a summary page that backlinks the source", () => {
seedSourceFile();
const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW });
expect(res.created).toBe(true);
expect(res.entitiesCreated).toHaveLength(2);
expect(listEntities(vault, { category: "concept" })).toHaveLength(2);
const md = readSummary(res.summaryPath);
expect(md).toContain("kind: brain-source");
expect(md).toContain("An overview of restaking");
expect(md).toContain("## Sources");
expect(md).toContain("[[Articles/restaking-primer.md]]");
expect(md).toContain("## Entities");
});
test("lists pre-existing entities as connections, new ones only as entities", () => {
// Seed Validators so it pre-exists; the ingest should report it as a
// connection to existing material, while Restaking is freshly created.
upsertEntity(vault, { category: "concept", name: "Validators", agent: "claude", now: NOW });
seedSourceFile();
const res = ingestSource(vault, INPUT, { agent: "claude", now: LATER });
expect(res.entitiesCreated).toHaveLength(1); // Restaking
expect(res.connections).toHaveLength(1); // Validators
expect(res.connections[0]).toContain("validators");
const md = readSummary(res.summaryPath);
expect(md).toContain("## Connections to existing notes");
});
test("is idempotent on the source path: re-ingest rewrites, does not duplicate", () => {
seedSourceFile();
const first = ingestSource(vault, INPUT, { agent: "claude", now: NOW });
const second = ingestSource(vault, INPUT, { agent: "claude", now: LATER });
expect(second.created).toBe(false);
expect(second.summaryPath).toBe(first.summaryPath);
// created_at is preserved from the first ingest; updated_at advanced.
expect(first.created).toBe(true);
const md = readSummary(second.summaryPath);
expect(md).toContain('created_at: "2026-06-13T12:00:00Z"');
expect(md).toContain('updated_at: "2026-06-14T09:00:00Z"');
});
test("entity pages cite the source in their body", () => {
seedSourceFile();
const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW });
expect(res.summaryPath).toBeTruthy();
const restaking = getEntity(vault, { category: "concept", query: "Restaking" });
expect(restaking?.body).toContain("[[Articles/restaking-primer.md]]");
});
test("planId records the ingested vault-file source into the plan checkpoint (t_ba1fa5f6)", () => {
// The checkpoint is only recorded for a real vault file, so materialize it.
seedSourceFile();
const planId = computePlanId(
"Articles",
["Articles/restaking-primer.md"],
computeExtractionContractFingerprint(vault),
);
ingestSource(vault, INPUT, { agent: "claude", now: NOW, planId });
const cp = readCheckpoint(vault, planId);
expect(cp?.completed).toEqual(["Articles/restaking-primer.md"]);
});
test("without planId no checkpoint is written", () => {
seedSourceFile();
const planId = computePlanId(
"Articles",
["Articles/restaking-primer.md"],
computeExtractionContractFingerprint(vault),
);
ingestSource(vault, INPUT, { agent: "claude", now: NOW });
expect(readCheckpoint(vault, planId)).toBeNull();
});
test("a plan id the checkpoint store cannot use is refused before anything is written", () => {
// A plan id becomes a checkpoint filename, so the store refuses
// anything but lowercase hex. Swallowed - as it was - the ingest
// succeeded, no checkpoint was EVER written for that plan, and
// `--reconcile` then reported every source as never ingested.
seedSourceFile();
expect(() =>
ingestSource(vault, INPUT, { agent: "claude", now: NOW, planId: "docs-migration" }),
).toThrow(/plan id/);
// Refused at the boundary: the summary page was not written either.
expect(existsSync(join(vault, "Brain", "sources"))).toBe(false);
});
});
describe("ingestSource pre-extract pass (P4, t_ef786747)", () => {
const CODE_INPUT = {
sourcePath: "Code/widget.ts",
summary: "A widget module.",
extraction: { entities: [{ category: "concept", name: "Widget" }], relations: [] },
};
function writeCode(): void {
mkdirSync(join(vault, "Code"), { recursive: true });
writeFileSync(
join(vault, "Code", "widget.ts"),
'import { h } from "./dom";\nexport class Widget extends Base {}\n',
"utf8",
);
}
test("returns deterministic code-structure seeds when the pass is on", () => {
writeCode();
const res = ingestSource(vault, CODE_INPUT, { agent: "claude", now: NOW, preExtract: true });
expect(res.preExtract?.extracted).toBe(true);
if (res.preExtract?.extracted) {
expect(res.preExtract.language).toBe("typescript");
expect(res.preExtract.entities).toEqual([{ kind: "class", name: "Widget" }]);
expect(res.preExtract.edges).toEqual([
{ kind: "imports", from: "Code/widget.ts", to: "./dom" },
{ kind: "inherits", from: "Widget", to: "Base" },
]);
}
});
test("a relative import binds to a sibling already in the content manifest", () => {
writeCode();
mkdirSync(join(vault, "Code"), { recursive: true });
writeFileSync(join(vault, "Code", "dom.ts"), "export const h = 1;\n", "utf8");
// The sibling lands in the manifest first; the importer's own pass runs
// before its own manifest entry is written, so binding needs a prior
// ingest of the imported file - exactly the incremental reality.
ingestSource(
vault,
{
sourcePath: "Code/dom.ts",
summary: "A dom module.",
extraction: { entities: [{ category: "concept", name: "Dom" }], relations: [] },
},
{ agent: "claude", now: NOW },
);
const res = ingestSource(vault, CODE_INPUT, { agent: "claude", now: NOW, preExtract: true });
expect(res.preExtract?.extracted).toBe(true);
if (res.preExtract?.extracted) {
expect(res.preExtract.edges[0]).toEqual({
kind: "imports",
from: "Code/widget.ts",
to: "./dom",
resolvedTo: "Code/dom.ts",
});
}
});
test.each([
["corrupted JSON", "{ not json", /ingest manifest is corrupted JSON/],
[
"an unsupported schema_version",
JSON.stringify({ schema_version: 999, entries: {} }),
/ingest manifest schema_version 999 not supported/,
],
])(
"a manifest with %s surfaces its own error before anything is written",
(_label, bytes, error) => {
writeCode();
writeManifestBytes(bytes);
expect(() =>
ingestSource(vault, CODE_INPUT, { agent: "claude", now: NOW, preExtract: true }),
).toThrow(error);
// The named manifest error must stop the ingest at the pre-extract read,
// not get reported as unreadable source bytes while the page is written.
expect(existsSync(join(vault, "Brain", "sources"))).toBe(false);
},
);
test("a non-code source never reads the manifest", () => {
// Deliberately unseeded, so the ingest itself never reaches the manifest
// update either: a corrupted manifest is then visible only to the pass.
writeManifestBytes("{ not json");
const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW, preExtract: true });
expect(res.preExtract?.extracted).toBe(false);
if (res.preExtract !== undefined && res.preExtract.extracted === false) {
expect(res.preExtract.reason).toContain("unsupported source extension");
}
});
test("a code source with no bytes on disk never reads the manifest", () => {
writeManifestBytes("{ not json");
const res = ingestSource(vault, CODE_INPUT, { agent: "claude", now: NOW, preExtract: true });
expect(res.preExtract?.extracted).toBe(false);
if (res.preExtract !== undefined && res.preExtract.extracted === false) {
expect(res.preExtract.reason).toContain("no readable file bytes");
}
});
test("a code source the caller may not read answers as one with no bytes", () => {
writeCode();
const refused = ingestSource(vault, CODE_INPUT, {
agent: "claude",
now: NOW,
preExtract: true,
readable: (rel) => rel !== CODE_INPUT.sourcePath,
});
expect(refused.preExtract).toEqual({
extracted: false,
reason: `source has no readable file bytes for code-structure pre-extraction: ${CODE_INPUT.sourcePath}`,
});
const allowed = ingestSource(vault, CODE_INPUT, {
agent: "claude",
now: NOW,
preExtract: true,
readable: () => true,
});
expect(allowed.preExtract?.extracted).toBe(true);
});
test("a code source larger than the read limit is skipped by name", () => {
writeCode();
writeFileSync(
join(vault, "Code", "widget.ts"),
`export const big = "${"x".repeat(PRE_EXTRACT_MAX_SOURCE_BYTES)}";\n`,
);
const res = ingestSource(vault, CODE_INPUT, { agent: "claude", now: NOW, preExtract: true });
expect(res.preExtract).toEqual({
extracted: false,
reason: `source is larger than ${PRE_EXTRACT_MAX_SOURCE_BYTES} bytes; code-structure pre-extraction skipped: ${CODE_INPUT.sourcePath}`,
});
});
// Windows has no FIFOs.
test.skipIf(IS_WINDOWS)(
"a FIFO code source has no readable bytes and the read does not block",
() => {
mkdirSync(join(vault, "Code"), { recursive: true });
const fifo = join(vault, "Code", "widget.ts");
expect(Bun.spawnSync(["mkfifo", fifo]).exitCode).toBe(0);
// A writer that holds the FIFO open for two seconds and writes
// nothing: a reader that blocks fails on its answer after two seconds
// instead of hanging the run.
const writer = Bun.spawn(["sh", "-c", 'exec 3>"$0"; exec sleep 2', fifo]);
try {
const res = ingestSource(vault, CODE_INPUT, {
agent: "claude",
now: NOW,
preExtract: true,
});
expect(res.preExtract).toEqual({
extracted: false,
reason: `source has no readable file bytes for code-structure pre-extraction: ${CODE_INPUT.sourcePath}`,
});
} finally {
writer.kill();
}
},
);
test("with the pass off the result carries no seeds and the page is byte-identical", () => {
writeCode();
// First ingest creates the entity + page; a second (idempotent) re-ingest
// reaches a stable state where the entity already exists, so the page no
// longer changes between runs. Compare that stable off-page against an
// on-page: the only variable left is the pass, proving it never leaks.
ingestSource(vault, CODE_INPUT, { agent: "claude", now: NOW });
const off = ingestSource(vault, CODE_INPUT, { agent: "claude", now: NOW });
const offBytes = readSummary(off.summaryPath);
expect(off.preExtract).toBeUndefined();
const on = ingestSource(vault, CODE_INPUT, { agent: "claude", now: NOW, preExtract: true });
expect(readSummary(on.summaryPath)).toBe(offBytes);
expect(on.preExtract?.extracted).toBe(true);
});
test("a non-code source reports unextracted rather than a fake empty success", () => {
// Deliberately unseeded: INPUT's source is not materialized on disk, so
// there is nothing to read (and the ingest quarantines its entities).
const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW, preExtract: true });
expect(res.preExtract?.extracted).toBe(false);
});
test("a source_path that climbs out of the vault is never read (t_sec_ingest_containment)", () => {
// The outside file exists and is parseable Python; if the pre-extract read
// skipped containment, its class names would land in the result.
const outside = mkdtempSync(join(tmpdir(), "o2b-ingest-outside-"));
try {
const outsideFile = join(outside, "secret-module.py");
writeFileSync(outsideFile, "class OutsideSecret:\n pass\n", "utf8");
// A relative path from the vault to that file is, by construction, a
// `..`-climbing traversal string - exactly what a caller would supply.
const traversalPath = relative(vault, outsideFile);
const res = ingestSource(
vault,
{
sourcePath: traversalPath,
summary: "An outside file.",
extraction: { entities: [{ category: "concept", name: "Outside" }], relations: [] },
},
{ agent: "claude", now: NOW, preExtract: true },
);
expect(res.preExtract?.extracted).toBe(false);
if (res.preExtract !== undefined && res.preExtract.extracted === false) {
expect(res.preExtract.reason).toContain("does not resolve inside this vault");
}
} finally {
rmSync(outside, { recursive: true, force: true });
}
});
});
/** Report `size` from the next fstat, as if the file grew after it. */
function fstatReportsSize(size: number): { mockRestore(): void; mock: { calls: unknown[] } } {
const real = fs.fstatSync;
return spyOn(fs, "fstatSync").mockImplementation(((fd: number) => {
const stat = real(fd);
return Object.assign(Object.create(Object.getPrototypeOf(stat)), stat, { size });
}) as typeof fs.fstatSync);
}
describe("readSourceBounded", () => {
const READ_LIMIT = 64;
test("a source read whole returns its text and its exact bytes", () => {
const abs = join(vault, "small.txt");
writeFileSync(abs, "caf\u00e9\n");
const read = readSourceBounded(abs, READ_LIMIT);
expect(read.text).toBe("caf\u00e9\n");
expect(read.unread).toBeUndefined();
expect(Buffer.from(read.bytes ?? new Uint8Array()).equals(fs.readFileSync(abs))).toBe(true);
});
test("a source that grows after the fstat but stays under the cap is read whole", () => {
const abs = join(vault, "grown.txt");
const body = "y".repeat(40);
writeFileSync(abs, body);
const spy = fstatReportsSize(16);
try {
const read = readSourceBounded(abs, READ_LIMIT);
expect(spy.mock.calls.length).toBe(1);
expect(read.text).toBe(body);
} finally {
spy.mockRestore();
}
});
test("a source that grows past the cap after the fstat is refused", () => {
const abs = join(vault, "big.txt");
writeFileSync(abs, "z".repeat(READ_LIMIT + 10));
const spy = fstatReportsSize(16);
try {
const read = readSourceBounded(abs, READ_LIMIT);
expect(spy.mock.calls.length).toBe(1);
expect(read).toEqual({ text: null, unread: "larger than the read limit" });
} finally {
spy.mockRestore();
}
});
test("a source over the cap at the fstat is refused without a read", () => {
const abs = join(vault, "over.txt");
writeFileSync(abs, "z".repeat(READ_LIMIT + 1));
expect(readSourceBounded(abs, READ_LIMIT)).toEqual({
text: null,
unread: "larger than the read limit",
});
});
test("a directory is not a regular file", () => {
mkdirSync(join(vault, "dir.txt"));
expect(readSourceBounded(join(vault, "dir.txt"), READ_LIMIT)).toEqual({
text: null,
unread: "not a regular file",
});
});
});
describe("ingestSource — extraction contract (t_586d5d8b)", () => {
test("ingesting under a v1 manifest rewrites the summary and lands the manifest as v3", () => {
seedSourceFile();
// Pre-fingerprint era manifest: the source's live hash recorded, no
// contract. The ingest records the source under the live contract, so the
// manifest it rewrites must land as v3 stamped with the fingerprint.
writeManifestBytes(
JSON.stringify({
schema_version: 1,
entries: {
[INPUT.sourcePath]: hashBytes(readFileSync(join(vault, INPUT.sourcePath))),
},
}),
);
const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW });
expect(res.created).toBe(true);
expect(readSummary(res.summaryPath)).toContain("kind: brain-source");
const onDisk = JSON.parse(readFileSync(manifestPath(vault), "utf8")) as {
schema_version: number;
contract: { fingerprint: string } | null;
};
expect(onDisk.schema_version).toBe(3);
expect(onDisk.contract?.fingerprint).toBe(computeExtractionContractFingerprint(vault));
});
});
/**
* The review gate (write-side trust, Task 9): the FIRST publish of a
* summary page stages under the ingest lane and the intake's created
* entity pages stage beside it, so a staged ingest publishes nothing -
* except the manifest row, which owes the stage verdict like every other
* registration row of the write and stays unrecorded until a publish arm
* lands; a re-ingest of an already-published page stays direct; and a
* source cleanup removes the staged page the way it removes a published
* one.
*/
describe("ingestSource under the ingest review gate", () => {
const INGEST_ENV = "OPEN_SECOND_BRAIN_WRITE_APPROVAL_INGEST_ENABLED";
let saved: string | undefined;
beforeEach(() => {
saved = process.env[INGEST_ENV];
process.env[INGEST_ENV] = "true";
});
afterEach(() => {
if (saved === undefined) delete process.env[INGEST_ENV];
else process.env[INGEST_ENV] = saved;
saved = undefined;
});
test("a first ingest stages the summary page while registration completes", () => {
seedSourceFile();
const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW });
expect(res.staged).toBe(true);
expect(res.pendingId).toBeDefined();
// The publish target is untouched; the bytes sit in the queue.
expect(existsSync(join(vault, res.summaryPath))).toBe(false);
const stagedPath = join(vault, "Brain/pending/ingest", `${res.pendingId}.md`);
const stagedBytes = readFileSync(stagedPath, "utf8");
expect(stagedBytes).toContain("kind: brain-source");
expect(stagedBytes).toContain("An overview of restaking");
// Nothing of a staged ingest publishes ahead of review (the intake's
// disposition contract): the created entity pages stage beside the
// summary at their canonical publish targets instead of entering the
// registry, and the manifest row owes the stage verdict like every
// other registration row of this write - a staged ingest must not
// record itself as done while its output awaits review.
expect(listEntities(vault, { category: "concept" })).toHaveLength(0);
const notesEntries = listPendingLane(vault, REVIEW_LANE.notes).entries;
expect(notesEntries.map((e) => e.publishTarget).toSorted()).toEqual(
res.entitiesCreated.map((id) => canonicalPage("concept", id)).toSorted(),
);
expect(readManifestEntries()).not.toContain(INPUT.sourcePath);
});
test("an apply of the staged page publishes byte-identical bytes", () => {
seedSourceFile();
const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW });
const stagedBytes = readFileSync(
join(vault, "Brain/pending/ingest", `${res.pendingId}.md`),
"utf8",
);
const applied = applyPendingLane(vault, res.pendingId!);
expect(applied.path).toBe(join(vault, res.summaryPath));
expect(readFileSync(applied.path, "utf8")).toBe(stagedBytes);
});
test("a re-ingest of an already-published page stays direct", () => {
seedSourceFile();
const first = ingestSource(vault, INPUT, { agent: "claude", now: NOW });
// A staged ingest queues the summary AND its created entity pages, so
// "already published" means the operator applied every staged entry.
applyPendingLane(vault, first.pendingId!);
for (const entry of listPendingLane(vault, REVIEW_LANE.notes).entries) {
applyPendingLane(vault, entry.id);
}
const second = ingestSource(vault, INPUT, { agent: "claude", now: LATER });
expect(second.staged).toBeUndefined();
expect(existsSync(join(vault, second.summaryPath))).toBe(true);
// The queue is empty: nothing re-staged behind the published page.
expect(existsSync(join(vault, "Brain/pending/ingest", `${first.pendingId}.md`))).toBe(false);
});
test("a source cleanup removes the staged page like a published one", () => {
seedSourceFile();
const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW });
expect(existsSync(join(vault, "Brain/pending/ingest", `${res.pendingId}.md`))).toBe(true);
const plan = deleteBySource(vault, INPUT.sourcePath, { confirm: true });
// The staged page is derived solely from this source (its bytes carry
// the same `source_path` the published page would), so the cleanup's
// trace finds it under Brain/pending/ingest/ and removes it.
const deleted = plan.deleted.map((path) => path.replaceAll("\\", "/"));
const stagedRelPath = join(vault, "Brain/pending/ingest", `${res.pendingId}.md`)
.slice(vault.length + 1)
.replaceAll("\\", "/");
expect(deleted).toContain(stagedRelPath);
expect(existsSync(join(vault, "Brain/pending/ingest", `${res.pendingId}.md`))).toBe(false);
});
/**
* Review M13: a relation from a PUBLISHED entity into one of this
* batch's staged pages used to be applied before staging, writing
* `[[new-id]]` into the published page - a link to an entity that
* exists only in the queue, left behind for good when the operator
* rejects the staged page. The staged ingest defers it instead, and a
* re-ingest while the first is still pending dedupes onto the open
* queue entries instead of staging duplicates.
*/
const ANCHORED_INPUT = {
sourcePath: INPUT.sourcePath,
summary: "A summary anchoring a published entity.",
extraction: {
entities: [
{ category: "concept", name: "Anchor" },
{ category: "concept", name: "Fresh" },
],
relations: [{ from: "Anchor", relation: "related", to: "Fresh" }],
},
};
function seedPublishedAnchor(): void {
seedSourceFile();
upsertEntity(vault, { category: "concept", name: "Anchor", agent: "claude", now: NOW });
}
test("a staged ingest defers a relation into a published page - no dangling link", () => {
seedPublishedAnchor();
const res = ingestSource(vault, ANCHORED_INPUT, { agent: "claude", now: NOW });
expect(res.staged).toBe(true);
// The published Anchor page names no entity that exists only in the queue.
const anchor = getEntity(vault, { category: "concept", query: "Anchor" });
expect(anchor?.relations ?? []).toEqual([]);
// The deferral surfaces on the ingest result for the publish flow.
expect(res.deferredRelations).toEqual([{ from: "Anchor", relation: "related", to: "Fresh" }]);
// One open entry per publish target: the summary and the one entity page.
expect(listPendingLane(vault, REVIEW_LANE.ingest).entries).toHaveLength(1);
expect(listPendingLane(vault, REVIEW_LANE.notes).entries).toHaveLength(1);
});
test("a re-ingest while the first is still pending dedupes the pending entries", () => {
seedPublishedAnchor();
const first = ingestSource(vault, ANCHORED_INPUT, { agent: "claude", now: NOW });
const second = ingestSource(vault, ANCHORED_INPUT, { agent: "claude", now: LATER });
// No duplicate entries: still one summary entry and one entity entry.
expect(listPendingLane(vault, REVIEW_LANE.ingest).entries).toHaveLength(1);
expect(listPendingLane(vault, REVIEW_LANE.notes).entries).toHaveLength(1);
// The re-ingest reports the SAME open entries, not new ones.
expect(second.pendingId).toBe(first.pendingId);
// The published page is still clean, and the re-created duplicate left
// no canonical orphan.
expect(getEntity(vault, { category: "concept", query: "Anchor" })?.relations ?? []).toEqual([]);
expect(getEntity(vault, { category: "concept", query: "Fresh" })).toBeNull();
});
test("after the queue applies, a re-ingest applies the deferred relation", () => {
seedPublishedAnchor();
const first = ingestSource(vault, ANCHORED_INPUT, { agent: "claude", now: NOW });
const freshId = first.entitiesCreated[0]!;
applyPendingLane(vault, first.pendingId!);
for (const entry of listPendingLane(vault, REVIEW_LANE.notes).entries) {
applyPendingLane(vault, entry.id);
}
// Both endpoints are published now: the same extraction applies the
// edge instead of deferring it.
const second = ingestSource(vault, ANCHORED_INPUT, { agent: "claude", now: LATER });
expect(second.deferredRelations).toBeUndefined();
expect(second.staged).toBeUndefined();
const anchor = getEntity(vault, { category: "concept", query: "Anchor" });
expect(anchor?.relations).toEqual([{ relation: "related", target: freshId }]);
});
});
/**
* The document-backed disposition (write-side trust, Task 12): a
* permissions document that denies the ingest action refuses
* `brain_ingest_source` BEFORE any write - no entity page, no manifest
* row, no summary page, no queue entry - and lands exactly one
* decision-ledger row naming the rule that decided.
*/
describe("ingestSource under a denying permissions document", () => {
test("a deny default refuses the ingest before any write", () => {
seedSourceFile();
writeFileSync(join(vault, "Brain/_permissions.yaml"), "version: 1\ndefault_action: deny\n");
expect(() => ingestSource(vault, INPUT, { agent: "claude", now: NOW })).toThrow(
WriteRefusedError,
);
// Nothing was written: not the summary page, not the queue, not the
// entities, not the manifest.
expect(listEntities(vault, { category: "concept" })).toHaveLength(0);
expect(readManifestEntries()).toEqual([]);
expect(existsSync(join(vault, "Brain/pending/ingest"))).toBe(false);
const sourcesDir = join(vault, "Brain", "sources");
const summaryFiles = existsSync(sourcesDir)
? fs.readdirSync(sourcesDir).filter((n) => n.endsWith(".md"))
: [];
expect(summaryFiles).toEqual([]);
// Exactly one ledger row, naming the default rule and the ingest action.
const rows = queryDecisionLedger(vault, { verdict: "deny" });
expect(rows).toHaveLength(1);
expect(rows[0]).toMatchObject({
actor: "claude",
action: "ingest",
verdict: "deny",
source: "default",
});
});
test("an ask default stages the first publish and records exactly one row", () => {
seedSourceFile();
writeFileSync(join(vault, "Brain/_permissions.yaml"), "version: 1\ndefault_action: ask\n");
const res = ingestSource(vault, INPUT, { agent: "claude", now: NOW });
expect(res.staged).toBe(true);
const rows = queryDecisionLedger(vault, { verdict: "ask" });
expect(rows).toHaveLength(1);
expect(rows[0]).toMatchObject({ action: "ingest", verdict: "ask", source: "default" });
});
});