A self-organizing Obsidian vault that gives AI coding agents persistent memory.
TypeScript ai-agentsclaude-codecodex-cligemini-cliknowledge-managementobsidianobsidian-vaultpersistent-memorysecond-braintemplate
/**
* Hardening suite for the vault memory layer.
*
* Ordered from real situations outward to the adversarial ones, because the
* cheap tests are the ones that fail first when something breaks. The last
* section is a containment property test: the path builder is handed hostile
* titles and must never produce a path that escapes the memory root.
*
* Zero dependencies, matching the harness.
*/
import { test, describe } from "node:test";
import { extractAliases, buildResolver, extractWikilinkTargets } from "../lib/wikilinks.ts";
import assert from "node:assert/strict";
import { mkdtempSync, existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, sep, resolve } from "node:path";
import {
slugify,
isoDate,
memoryPath,
narrowScope,
resolveLinks,
validateMemory,
renderMemory,
deriveDescription,
writeMemory,
readMemory,
MEMORY_ROOT,
type MemoryInput,
} from "../lib/memory-write.ts";
import { rmTemp } from "./_helpers.ts";
const DAY = new Date(2026, 6, 26, 14, 2, 11); // 2026-07-26, local
const OK = {
title: "tsup externals decide what a patch can fix",
body:
"patch-package only patches this repo's node_modules. A dependency marked external in tsup is resolved on the user's machine at install time, so the patch never reaches them.",
confidence: "inferred",
};
function tmpVault(): string {
return mkdtempSync(join(tmpdir(), "memtest-"));
}
/** Split frontmatter off a rendered memory and return the raw lines. */
function frontmatter(md: string): string[] {
const m = md.match(/^---\n([\s\S]*?)\n---\n/);
assert.ok(m, "rendered memory must open with a frontmatter block");
return (m[1] ?? "").split("\n");
}
function fmValue(md: string, key: string): string | undefined {
const line = frontmatter(md).find((l: string) => l.startsWith(`${key}:`));
return line === undefined ? undefined : line.slice(key.length + 1).trim();
}
/** fmValue where the caller has already established the key must be present. */
function fmRequired(md: string, key: string): string {
const v = fmValue(md, key);
assert.ok(v !== undefined, `frontmatter key "${key}" is missing`);
return v;
}
// ---------------------------------------------------------------------------
// 1. The real path
// ---------------------------------------------------------------------------
describe("real usage", () => {
test("a normal memory validates, renders and writes where the blueprint says", () => {
const v = validateMemory(OK, { now: DAY, origin: "pocket" });
assert.equal(v.ok, true, JSON.stringify(v.errors));
const dir = tmpVault();
try {
const { rel } = writeMemory(dir, v.value!, ["pocket"]);
assert.equal(rel, "memories/2026/07/2026-07-26 tsup externals decide what a patch can fix.md");
assert.ok(existsSync(join(dir, rel)));
} finally {
rmTemp(dir);
}
});
test("frontmatter carries every field the architecture doc promises", () => {
const v = validateMemory(
{ ...OK, scope: "project", projects: ["pocket", "obsidian-mind"], platforms: ["ios"] },
{ now: DAY, origin: "pocket" },
);
const md = renderMemory(v.value!, ["pocket"]);
assert.equal(fmValue(md, "date"), "2026-07-26");
assert.equal(fmValue(md, "source"), "mcp-capture");
assert.equal(fmValue(md, "origin"), '"pocket"');
assert.equal(fmValue(md, "scope"), "project");
assert.equal(fmValue(md, "projects"), '["pocket", "obsidian-mind"]');
assert.equal(fmValue(md, "platforms"), '["ios"]');
assert.equal(fmValue(md, "confidence"), "inferred");
assert.equal(fmValue(md, "tags"), "[memory]");
assert.ok(fmRequired(md, "session").includes("T"));
});
test("projects is a list, which is the whole point", () => {
const v = validateMemory({ ...OK, projects: ["a", "b", "c"] }, { now: DAY, origin: "a" });
assert.deepEqual(v.value!.projects, ["a", "b", "c"]);
});
test("body and title survive into the note verbatim", () => {
const v = validateMemory(OK, { now: DAY, origin: "pocket" });
const md = renderMemory(v.value!, []);
assert.ok(md.includes(`# ${OK.title}`));
assert.ok(md.includes(OK.body));
});
test("verification renders its own section", () => {
const v = validateMemory({ ...OK, verification: "Ran npm pack; patches/ absent." }, { now: DAY, origin: "p" });
const md = renderMemory(v.value!, []);
assert.ok(md.includes("## How this is known"));
assert.ok(md.includes("Ran npm pack"));
});
});
// ---------------------------------------------------------------------------
// 2. Scope narrowing — never widens
// ---------------------------------------------------------------------------
describe("scope narrowing", () => {
test("general + named projects downgrades to project", () => {
const r = narrowScope({ scope: "general", projects: ["pocket"], origin: "pocket" });
assert.equal(r.scope, "project");
assert.equal(r.downgraded_from, "general");
});
test("general naming nothing STANDS, with or without an origin", () => {
// Regression. An earlier version attributed this case to the origin repo,
// so every general memory silently became project-scoped to whoever wrote
// it and the general tier was UNREACHABLE through the server — while the
// reader, the tool schema, the Base view and the docs all still described
// it. Found by an adversarial run in which five of six callers could not
// see a memory explicitly written as general.
for (const origin of ["pocket", null]) {
const r = narrowScope({ scope: "general", projects: [], origin });
assert.equal(r.scope, "general", `origin=${origin}`);
assert.deepEqual(r.projects, []);
assert.equal(r.downgraded_from, null);
}
});
test("a downgrade is recorded in the note, not hidden", () => {
// The surviving downgrade: general WITH named projects is scoped to them
// by the caller's own admission.
const v = validateMemory({ ...OK, scope: "general", projects: ["pocket"] }, { now: DAY, origin: "pocket" });
const md = renderMemory(v.value!, []);
assert.equal(fmValue(md, "claimed_scope"), "general");
});
test("scope is never widened", () => {
for (const origin of ["pocket", null]) {
for (const projects of [[], ["a"], ["a", "b"]]) {
const r = narrowScope({ scope: "project", projects, origin });
assert.notEqual(r.scope, "general", "project must never become general");
}
}
});
test("platform scope passes through untouched", () => {
const r = narrowScope({ scope: "platform", projects: [], origin: "pocket" });
assert.equal(r.scope, "platform");
});
});
// ---------------------------------------------------------------------------
// 3. Link resolution — never emit a broken edge
// ---------------------------------------------------------------------------
describe("link resolution", () => {
const known = new Set(["pocket", "obsidian-mind"]);
test("resolvable links survive, unresolvable are dropped and reported", () => {
const r = resolveLinks(["pocket", "Ghost Note"], known);
assert.deepEqual(r.resolved, ["pocket"]);
assert.deepEqual(r.dropped, ["Ghost Note"]);
});
test("matching is case-insensitive but preserves the caller's casing", () => {
const r = resolveLinks(["POCKET"], known);
assert.deepEqual(r.resolved, ["POCKET"]);
});
test("duplicates collapse", () => {
const r = resolveLinks(["pocket", "Pocket", "pocket"], known);
assert.equal(r.resolved.length, 1);
});
test("empty and non-array input is survivable", () => {
assert.deepEqual(resolveLinks(undefined, known).resolved, []);
assert.deepEqual(resolveLinks(null, known).dropped, []);
assert.deepEqual(resolveLinks(["", " "], known).resolved, []);
});
test("no resolvable links means no Related section rather than an empty one", () => {
const v = validateMemory(OK, { now: DAY, origin: "p" });
assert.ok(!renderMemory(v.value!, []).includes("## Related"));
});
});
// ---------------------------------------------------------------------------
// 4. The epistemic contract
// ---------------------------------------------------------------------------
describe("epistemic contract", () => {
const ctx = { now: DAY, origin: "pocket" };
test("recurrence claims are flagged and capped, not rejected", () => {
// v1 REJECTED these. That was wrong: a false reject destroys knowledge the
// session already had, while a false flag costs one frontmatter line.
for (const claim of [
"This always breaks on Windows when the path has a space in it somewhere.",
"The installer never recovers from a partial write, so state is lost.",
"Every time the cache is cold the build fails with a null exit code.",
"This keeps happening whenever two vaults share one index name.",
]) {
const r = validateMemory({ ...OK, body: claim, confidence: "verified" }, ctx);
assert.equal(r.ok, true, `should accept but flag: ${claim}`);
assert.ok(r.value!.flags.includes("generalised"), `no flag for: ${claim}`);
assert.equal(r.value!.confidence, "inferred", "a generalised claim cannot stay verified");
assert.equal(r.value!.claimed_confidence, "verified", "the original claim stays auditable");
}
});
test("a deterministic consequence using the word 'never' is NOT flagged", () => {
// The regression that killed v1: "the patch never reaches them" describes a
// mechanism, not a frequency. This is the canonical example from the docs.
const r = validateMemory(OK, ctx);
assert.equal(r.ok, true, JSON.stringify(r.errors));
assert.deepEqual(r.value!.flags, [], "benign prose must not be flagged");
});
test("a single dated occurrence is accepted", () => {
const r = validateMemory(
{
...OK,
body: "On 2026-07-26 the build failed with a null exit code because the guard had no timeout.",
},
ctx,
);
assert.equal(r.ok, true, JSON.stringify(r.errors));
});
test("volatile figures without a date anchor are flagged, not rejected", () => {
const r = validateMemory(
{
...OK,
body: "The template repo has 3974 stars and 480 forks right now, which is worth recording.",
confidence: "verified",
},
ctx,
);
assert.equal(r.ok, true);
assert.ok(r.value!.flags.includes("volatile"));
assert.equal(r.value!.confidence, "inferred", "an undated figure cannot be verified");
});
test("the same figure with an anchor is accepted", () => {
const r = validateMemory(
{ ...OK, body: "The template repo has 3974 stars as of 2026-07-26, which is up from launch." },
ctx,
);
assert.equal(r.ok, true, JSON.stringify(r.errors));
assert.deepEqual(r.value!.flags, [], "an anchored figure carries no volatile flag");
});
test("transcripts are rejected, short dialogue quotes are not", () => {
const transcript = ["User: why did it fail", "Assistant: because of X", "User: fix it", "Assistant: done"].join("\n");
assert.equal(validateMemory({ ...OK, body: transcript }, ctx).ok, false);
const quoted = "The maintainer said:\nUser: it fails on Windows\nThat was the only report we had, so it stays unverified for now.";
assert.equal(validateMemory({ ...OK, body: quoted }, ctx).ok, true);
});
test("verified without verification warns but does not block", () => {
const r = validateMemory({ ...OK, confidence: "verified" }, ctx);
assert.equal(r.ok, true);
assert.ok(r.warnings.some((w) => /verified/i.test(w)));
});
test("general without generality warns but does not block", () => {
const r = validateMemory({ ...OK, scope: "general" }, ctx);
assert.equal(r.ok, true);
assert.ok(r.warnings.some((w) => /generality/i.test(w)));
});
test("a supplied generality silences the warning and is carried onto the value", () => {
const r = validateMemory({ ...OK, scope: "general", generality: "true of any language with a module system" }, ctx);
assert.equal(r.ok, true);
assert.ok(!r.warnings.some((w) => /generality/i.test(w)));
assert.match(String(r.value?.generality), /module system/);
});
// The warning keys on the NARROWED scope. A caller who claims `general` and
// names projects has been downgraded to `project` by their own admission, so
// asking them to justify a reach they did not end up claiming is noise.
test("general downgraded to project by named projects does not warn about generality", () => {
const r = validateMemory({ ...OK, scope: "general", projects: ["alpha"] }, ctx);
assert.equal(r.ok, true);
assert.equal(r.value?.scope, "project");
assert.ok(!r.warnings.some((w) => /generality/i.test(w)));
});
test("an oversized body warns about atomicity rather than failing", () => {
const r = validateMemory({ ...OK, body: "x. ".repeat(5000) }, ctx);
assert.equal(r.ok, true);
assert.ok(r.warnings.some((w) => /atomic/i.test(w)));
});
});
// ---------------------------------------------------------------------------
// 5. Input validation
// ---------------------------------------------------------------------------
describe("input validation", () => {
const ctx = { now: DAY, origin: "pocket" };
test("missing required fields are all reported at once, not one at a time", () => {
const r = validateMemory({}, ctx);
assert.equal(r.ok, false);
assert.ok(r.errors.length >= 3, "should report title, body and confidence together");
});
test("a too-short body is rejected with its actual length", () => {
const r = validateMemory({ ...OK, body: "it broke" }, ctx);
assert.equal(r.ok, false);
assert.ok(r.errors.some((e) => /\d+ chars/.test(e)));
});
test("bad confidence and scope enums are rejected", () => {
assert.equal(validateMemory({ ...OK, confidence: "pretty sure" }, ctx).ok, false);
assert.equal(validateMemory({ ...OK, scope: "universe" }, ctx).ok, false);
});
test("projects must be an array, not a string", () => {
const r = validateMemory({ ...OK, projects: "pocket" }, ctx);
assert.equal(r.ok, false);
assert.ok(r.errors.some((e) => /multi-valued/i.test(e)));
});
test("project slugs with separators or spaces are rejected", () => {
for (const bad of ["../etc", "a/b", "has space", "semi;colon", ""]) {
assert.equal(validateMemory({ ...OK, projects: [bad] }, ctx).ok, false, `should reject ${JSON.stringify(bad)}`);
}
});
test("non-string project entries are rejected rather than coerced", () => {
assert.equal(validateMemory({ ...OK, projects: [42] }, ctx).ok, false);
assert.equal(validateMemory({ ...OK, projects: [null] }, ctx).ok, false);
assert.equal(validateMemory({ ...OK, projects: [{}] }, ctx).ok, false);
});
test("null and undefined input do not throw", () => {
assert.equal(validateMemory(null, ctx).ok, false);
assert.equal(validateMemory(undefined, ctx).ok, false);
});
});
// ---------------------------------------------------------------------------
// 6. Slug and path — the hostile section
// ---------------------------------------------------------------------------
describe("slug and path safety", () => {
test("path separators cannot survive a title", () => {
assert.ok(!slugify("a/b\\c").includes("/"));
assert.ok(!slugify("a/b\\c").includes("\\"));
});
test("traversal is neutralised", () => {
const s = slugify("../../etc/passwd");
assert.ok(!s.includes(".."));
assert.ok(!s.includes("/"));
});
test("a wikilink terminator cannot survive a title, and `#` is the one that used to", () => {
// The defect: `#` is not a path hazard, so none of the filesystem classes
// removed it, and it reached the filename. The note then looked entirely
// normal and could not be addressed by any link, because a wikilink splits
// on `#` into a note target and a heading reference.
const s = slugify("Config flag #7 changes the default");
assert.ok(!s.includes("#"), `slug kept the hash: ${s}`);
// A space, not nothing: `Flag #7 set` must not collapse to `Flag7 set`.
assert.match(s, /flag 7 changes/i, `word boundary lost: ${s}`);
assert.ok(!/\s{2,}/.test(s), `double space left behind: ${s}`);
});
/**
* A backtick in the filename made the note unaddressable: the link reader
* strips inline code first, and a code span inside `[[...]]` took part of
* the target with it.
*/
test("a code span in the title leaves no backtick, and its words survive", () => {
// A space, not nothing, and the collapse tidies the double space.
assert.equal(slugify("Porting a bash `jq '.'` gate"), "Porting a bash jq '.' gate");
});
test("a wikilink to a slug made from a code-span title resolves to that slug", () => {
const stem = `2026-09-01 ${slugify("Porting a bash `jq '.'` gate")}`;
const targets = extractWikilinkTargets(`see [[${stem}|Capture]]`);
assert.deepEqual(targets, [stem]);
});
test("widening the class does not start eating ordinary titles", () => {
// The risk of a wider removal class is that it reaches titles it was never
// aimed at. A title whose words survive must keep all of them.
for (const [title, expect] of [
["Never revert a probe with git checkout", "Never revert a probe with git checkout"],
["Issue #142 and issue #7 disagree", "Issue 142 and issue 7 disagree"],
["C# is a language, not a heading", "C is a language, not a heading"],
] as const) {
assert.equal(slugify(title), expect);
}
});
test("a title of nothing but terminators is rejected rather than padded", () => {
// It slugifies to empty, which is the state the existing guard already
// catches — the same answer `...` and `***` get. Asserted here because the
// wider class creates new ways to reach that state, and the alternative
// (inventing a stem) would write a note nobody asked for.
for (const bad of ["#", "###", "# # #", "[[#]]"]) {
assert.equal(slugify(bad), "", `expected an empty slug for ${JSON.stringify(bad)}`);
const r = validateMemory({ ...OK, title: bad }, { now: DAY, origin: "p" });
assert.equal(r.ok, false, `should reject title ${JSON.stringify(bad)}`);
}
});
test("the link built from a written path contains no wikilink terminator", () => {
// The round trip, and the assertion that generalises: whatever the class
// grows to hold, the target built from the stem must stay addressable.
// This is the one that would have failed before the fix.
const stem = memoryPath(new Date("2026-01-05T00:00:00Z"), "Config flag #7 changes the default")
.replace(/\.md$/, "")
.split(sep)
.pop() as string;
for (const terminator of ["#", "[", "]", "|"]) {
assert.ok(!stem.includes(terminator), `[[${stem}]] is not addressable: contains ${terminator}`);
}
});
test("windows reserved stems are escaped", () => {
for (const name of ["CON", "con", "PRN", "AUX", "NUL", "COM1", "LPT9"]) {
assert.ok(slugify(name).startsWith("_"), `${name} must not be a bare reserved name`);
}
});
test("trailing dots and spaces are folded (NTFS strips them silently)", () => {
assert.ok(!/[. ]$/.test(slugify("trailing dots...")));
assert.ok(!/[. ]$/.test(slugify("trailing space ")));
});
test("long titles are truncated on a word boundary", () => {
const s = slugify("the quick brown fox jumps over the lazy dog and keeps running for a very long time indeed");
assert.ok(s.length <= 60);
assert.ok(!s.endsWith(" "));
});
test("unicode titles survive as filenames", () => {
assert.ok(slugify("日本語のメモ").length > 0);
assert.ok(slugify("café déjà vu").length > 0);
});
test("a title that slugifies to nothing is rejected, not written as a dotfile", () => {
for (const bad of ["...", "///", " ", "***"]) {
const r = validateMemory({ ...OK, title: bad }, { now: DAY, origin: "p" });
assert.equal(r.ok, false, `should reject title ${JSON.stringify(bad)}`);
}
});
test("newlines in a title cannot break the path or the H1", () => {
const s = slugify("line one\nline two");
assert.ok(!s.includes("\n"));
});
test("the month folder is zero-padded and the year splits correctly", () => {
assert.equal(memoryPath(new Date(2026, 0, 5), "x"), "memories/2026/01/2026-01-05 x.md");
assert.equal(memoryPath(new Date(2026, 11, 31), "x"), "memories/2026/12/2026-12-31 x.md");
});
test("a custom memory root is honoured (config, not hardcoded)", () => {
assert.ok(memoryPath(DAY, "x", "recall").startsWith("recall/2026/07/"));
});
});
// ---------------------------------------------------------------------------
// 7. YAML safety — frontmatter that fails to parse is invisible
// ---------------------------------------------------------------------------
describe("frontmatter safety", () => {
test("quotes and colons in the body cannot break the description", () => {
const body =
'He said: "it fails", and the config had key: value pairs inline — which is exactly the shape that breaks naive YAML.';
const v = validateMemory({ ...OK, body }, { now: DAY, origin: "p" });
const desc = fmRequired(renderMemory(v.value!, []), "description");
assert.doesNotThrow(() => JSON.parse(desc), "description must be a valid double-quoted scalar");
});
test("a newline in the body never reaches the description as a literal", () => {
const v = validateMemory({ ...OK, body: "first line\nsecond line, long enough to pass the minimum length check." }, { now: DAY, origin: "p" });
const desc = fmRequired(renderMemory(v.value!, []), "description");
assert.ok(!desc.includes("\n"));
assert.doesNotThrow(() => JSON.parse(desc));
});
test("an origin with a quote cannot escape its scalar", () => {
const v = validateMemory(OK, { now: DAY, origin: 'we"ird' });
const md = renderMemory(v.value!, []);
assert.doesNotThrow(() => JSON.parse(fmRequired(md, "origin")));
});
test("description stays within the vault's ~150 char convention", () => {
const v = validateMemory({ ...OK, body: "word ".repeat(200) }, { now: DAY, origin: "p" });
assert.ok(deriveDescription(v.value!.body).length <= 152);
});
test("frontmatter opens and closes exactly once", () => {
const v = validateMemory(OK, { now: DAY, origin: "p" });
const md = renderMemory(v.value!, []);
assert.equal((md.match(/^---$/gm) || []).length, 2);
});
});
// ---------------------------------------------------------------------------
// 8. Write collisions — never clobber
// ---------------------------------------------------------------------------
describe("write collisions", () => {
test("two memories with the same title on the same day do not overwrite", () => {
const dir = tmpVault();
try {
const v = validateMemory(OK, { now: DAY, origin: "p" }).value!;
const a = writeMemory(dir, v, []);
const b = writeMemory(dir, { ...v, body: "different body, same title, same day, still needs saving." }, []);
assert.notEqual(a.rel, b.rel);
assert.ok(b.rel.includes("(2)"));
assert.ok(readMemory(dir, a.rel).includes(OK.body), "the first memory must survive intact");
} finally {
rmTemp(dir);
}
});
test("the collision suffix keeps the .md extension", () => {
const dir = tmpVault();
try {
const v = validateMemory(OK, { now: DAY, origin: "p" }).value!;
writeMemory(dir, v, []);
assert.ok(writeMemory(dir, v, []).rel.endsWith(".md"));
} finally {
rmTemp(dir);
}
});
test("missing month folders are created", () => {
const dir = tmpVault();
try {
const v = validateMemory(OK, { now: new Date(2027, 2, 3), origin: "p" }).value!;
assert.ok(existsSync(writeMemory(dir, v, []).full));
} finally {
rmTemp(dir);
}
});
});
// ---------------------------------------------------------------------------
// 9. Containment property — the fuzz pass
// ---------------------------------------------------------------------------
describe("containment property", () => {
/**
* The one invariant that must hold for EVERY input: whatever a caller puts
* in a title, the resolved write path stays inside the memory root. A single
* escape here is an arbitrary-file-write through a tool description.
*/
test("no title can produce a path outside the memory root", () => {
const hostile = [
"../../../etc/passwd",
"..\\..\\windows\\system32\\config",
"/etc/shadow",
"C:\\Windows\\System32",
"....//....//escape",
"a\u0000b",
"\u202Egnp.exe",
"CON",
"....",
"~/.ssh/authorized_keys",
"%2e%2e%2f",
"a".repeat(500),
"🙂".repeat(80),
"\n\n../x",
"..",
".",
];
const root = resolve("/vault");
for (const title of hostile) {
const slug = slugify(title);
if (!slug) continue; // rejected upstream by validateMemory
const rel = memoryPath(DAY, title);
const full = resolve(root, rel);
assert.ok(
full.startsWith(resolve(root, MEMORY_ROOT) + sep),
`escaped containment: ${JSON.stringify(title)} -> ${full}`,
);
assert.ok(!rel.includes(".."), `traversal survived: ${JSON.stringify(title)}`);
}
});
test("random titles always yield a containable, single-segment filename", () => {
const alphabet = "abc /\\.:*?\"<>|\u0000\n\t~%-_日🙂";
let checked = 0;
for (let i = 0; i < 400; i++) {
let title = "";
const len = 1 + ((i * 7) % 40);
for (let j = 0; j < len; j++) title += alphabet[(i * 13 + j * 31) % alphabet.length];
const slug = slugify(title);
if (!slug) continue;
assert.ok(!slug.includes("/"), `slug kept a separator: ${JSON.stringify(slug)}`);
assert.ok(!slug.includes("\\"), `slug kept a backslash: ${JSON.stringify(slug)}`);
assert.ok(!slug.includes(".."), `slug kept a traversal: ${JSON.stringify(slug)}`);
assert.ok(!/[. ]$/.test(slug), `slug ended in dot/space: ${JSON.stringify(slug)}`);
checked++;
}
assert.ok(checked > 100, `expected many usable slugs, got ${checked}`);
});
test("a memory written from a hostile title lands inside the vault", () => {
const dir = tmpVault();
try {
const v = validateMemory({ ...OK, title: "../../escape attempt" }, { now: DAY, origin: "p" });
assert.equal(v.ok, true, "this title still has usable characters, so it should validate");
const { full } = writeMemory(dir, v.value!, []);
assert.ok(resolve(full).startsWith(resolve(dir, MEMORY_ROOT) + sep));
} finally {
rmTemp(dir);
}
});
});
// ---------------------------------------------------------------------------
// 10. Reachability — never write a memory nobody can ever see
// ---------------------------------------------------------------------------
describe("reachability guard", () => {
test("a project-scoped memory with no projects and no caller identity is REFUSED", () => {
// The observed hole: a client that never answered roots/list writes a
// memory that validates, indexes, reports success — and is invisible to
// every caller forever.
const r = validateMemory(OK, { now: DAY, origin: null });
assert.equal(r.ok, false);
assert.ok(r.errors.some((e) => /reach nobody/i.test(e)));
assert.ok(r.errors.some((e) => /general/.test(e)), "the error must name the way out");
});
test("the same memory is fine once the caller has an identity", () => {
assert.equal(validateMemory(OK, { now: DAY, origin: "atlas" }).ok, true);
});
test("the same memory is fine once it names its projects", () => {
assert.equal(validateMemory({ ...OK, projects: ["atlas"] }, { now: DAY, origin: null }).ok, true);
});
test("an explicitly general memory needs neither", () => {
const r = validateMemory({ ...OK, scope: "general" }, { now: DAY, origin: null });
assert.equal(r.ok, true);
assert.equal(r.value!.scope, "general");
});
test("a platform-scoped memory naming no platforms is REFUSED", () => {
const r = validateMemory({ ...OK, scope: "platform" }, { now: DAY, origin: "atlas" });
assert.equal(r.ok, false);
assert.ok(r.errors.some((e) => /reach nobody/i.test(e)));
});
test("a platform-scoped memory naming platforms is fine", () => {
assert.equal(
validateMemory({ ...OK, scope: "platform", platforms: ["ios"] }, { now: DAY, origin: "atlas" }).ok,
true,
);
});
test("refusing beats widening — an unscopable memory never becomes general", () => {
// Silently granting the WIDEST reach because the narrowest could not be
// determined is the opposite of what narrowing is for.
const r = validateMemory(OK, { now: DAY, origin: null });
assert.equal(r.value!, null, "nothing is written at all");
});
test("every memory that validates is visible to at least one caller", () => {
// The property the guard exists to hold. Any accepted memory must have a
// facet some caller could match.
const cases: [MemoryInput, { now: Date; origin: string | null }][] = [
[{ ...OK, projects: ["atlas"] }, { now: DAY, origin: null }],
[{ ...OK }, { now: DAY, origin: "atlas" }],
[{ ...OK, scope: "general" }, { now: DAY, origin: null }],
[{ ...OK, scope: "platform", platforms: ["ios"] }, { now: DAY, origin: "atlas" }],
];
for (const [input, ctx] of cases) {
const r = validateMemory(input, ctx);
assert.equal(r.ok, true, JSON.stringify(r.errors));
const reachable =
r.value!.scope === "general" || r.value!.projects.length > 0 || r.value!.platforms.length > 0;
assert.ok(reachable, `accepted an unreachable memory: ${JSON.stringify(r.value!)}`);
}
});
});
/**
* A memory has to be citable by the one string anyone would use: its own claim.
*
* `slugify` truncates at SLUG_MAX and its comment says a long title is "still
* fine as the H1" — true for reading, false for LINKING. Obsidian resolves a
* link target against filenames and aliases; an H1 is never a link target, so a
* memory whose title outran the slug was addressable by nothing a reader would
* naturally type. Titles run long as a rule here, because the contract asks for
* the lesson stated as a claim.
*/
describe("a long-titled memory stays linkable by its title", () => {
const LONG =
"A gate can be wrong about its situation as well as its assertion, and only mutation separates the two";
const render = (title: string): string =>
renderMemory({
title,
body: "b".repeat(120),
date: new Date(2026, 6, 26),
scope: "general",
projects: [],
platforms: [],
confidence: "inferred",
flags: [],
origin: null,
downgraded_from: null,
} as never);
test("the title is emitted as an alias when the filename cannot carry it", () => {
const md = render(LONG);
assert.notEqual(slugify(LONG), LONG, "fixture must actually be truncated");
assert.match(md, /^aliases: \[/m, "no alias emitted, so the memory is uncitable by name");
// The property that actually matters. Asserting only that SOME alias was
// emitted would pass against a truncated or re-quoted one, which would
// still not resolve.
assert.deepEqual(extractAliases(md), [LONG]);
});
test("a link written with the title resolves against the rendered memory", () => {
const md = render(LONG);
const rel = `memories/2026/07/2026-07-26 ${slugify(LONG)}.md`;
const resolves = buildResolver([rel], new Map([[rel, extractAliases(md)]]));
assert.equal(resolves(LONG, "some/note.md"), true);
});
test("a short title emits no alias — the filename already carries it", () => {
const short = "short enough";
assert.equal(slugify(short), short);
assert.doesNotMatch(render(short), /^aliases:/m);
});
test("a title carrying a quote still round-trips through the alias", () => {
const tricky = `The writer's "two facts" rule, restated at length so the slug must truncate it`;
assert.deepEqual(extractAliases(render(tricky)), [tricky]);
});
});