From bf3646c0c79ed5b16915c6c5bb624a902f5c902d Mon Sep 17 00:00:00 2001 From: Mathias Date: Mon, 5 Oct 2026 07:02:41 +0200 Subject: [PATCH 1/4] test(brainfs): per-caller in-brain symlink targets for slices 1-3 (#171) os.Root refuses links that leave the brain on its own, so the slice 1-3 callers' outside-target tests stayed green when a caller read without brainfs's Lstat/SameFile checks (PR #168 round-2 review). Adds a static in-brain link (wiki/w/facts/inlink.md -> ../../../raw/s.md) and an AssertNoLeakFrom swap race with an in-brain target for search.Query, hydrate, vectorstore.Sync, readExcerpt and api.ReadNote. Flip-verified: replacing each caller's bfs.ReadRegular with an os.OpenRoot(brainDir).ReadFile turns every one red on the new assertions (Query, hydrate, Sync, readExcerpt, ReadNote). Also from that review: rename TestReadRegularNever... to ...DoesNotReturn... (rule 9: a sampled race), and AssertNoLeakFrom's failure message names the symlink target instead of 'outside file'. Closes #171 Co-Authored-By: Claude Opus 5.5 --- ingestion/internal/api/readnote_root_test.go | 9 ++++ ingestion/internal/brainfs/brainfs_test.go | 2 +- .../brainfs/brainfstest/brainfstest.go | 2 +- .../internal/mcp/readexcerpt_root_test.go | 8 ++++ ingestion/internal/search/brainroot_test.go | 46 +++++++++++++++++++ .../internal/vectorstore/sync_root_test.go | 7 +++ 6 files changed, 72 insertions(+), 2 deletions(-) diff --git a/ingestion/internal/api/readnote_root_test.go b/ingestion/internal/api/readnote_root_test.go index 94fedff..24ac216 100644 --- a/ingestion/internal/api/readnote_root_test.go +++ b/ingestion/internal/api/readnote_root_test.go @@ -23,6 +23,13 @@ func TestReadNoteRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) { _, body, _, err := api.ReadNote(brain, "wiki/w/facts/leak.md") assert.Error(t, err) assert.NotContains(t, body, brainfstest.Sentinel) + // A link to a file elsewhere in the brain: os.Root allows it, only the + // regular-file check refuses it (hyperguild#171). + brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md")) + require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md"))) + _, body, _, err = api.ReadNote(brain, "wiki/w/facts/inlink.md") + assert.Error(t, err) + assert.NotContains(t, body, brainfstest.Sentinel) p := filepath.Join(facts, "r.md") require.NoError(t, os.WriteFile(p, []byte("---\nx: y\n---\ninside"), 0o644)) @@ -39,5 +46,7 @@ func TestReadNoteRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) { return s } brainfstest.AssertNoLeak(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, read) + inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md")) + brainfstest.AssertNoLeakFrom(t, p, "---\nx: y\n---\ninside", inBrain, 1500*time.Millisecond, read) brainfstest.AssertNoHang(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, 6*time.Second, func() { _ = read() }) } diff --git a/ingestion/internal/brainfs/brainfs_test.go b/ingestion/internal/brainfs/brainfs_test.go index 7146af8..dbc0025 100644 --- a/ingestion/internal/brainfs/brainfs_test.go +++ b/ingestion/internal/brainfs/brainfs_test.go @@ -218,7 +218,7 @@ func TestReadDirRegularListsOnlyRegularFilesAndRefusesSymlinkedComponents(t *tes // A final component swapped for a symlink to another regular file in the // brain between the Lstat and the open: os.Root follows in-root links, so // only comparing the two (os.SameFile) refuses it. -func TestReadRegularNeverReturnsAnInBrainFileSwappedInBehindASymlink(t *testing.T) { +func TestReadRegularDoesNotReturnAnInBrainFileSwappedInBehindASymlink(t *testing.T) { dir := t.TempDir() require.NoError(t, os.WriteFile(filepath.Join(dir, "s.md"), []byte("zqsamefilesentinel"), 0o644)) p := filepath.Join(dir, "r.md") diff --git a/ingestion/internal/brainfs/brainfstest/brainfstest.go b/ingestion/internal/brainfs/brainfstest/brainfstest.go index fdfe968..fd9ef0d 100644 --- a/ingestion/internal/brainfs/brainfstest/brainfstest.go +++ b/ingestion/internal/brainfs/brainfstest/brainfstest.go @@ -117,7 +117,7 @@ func AssertNoLeakFrom(t *testing.T, path, inside, target string, d time.Duration leaks += strings.Count(read(), Sentinel) } if leaks > 0 { - t.Fatalf("outside file leaked %d times in %d iterations", leaks, iters) + t.Fatalf("symlink target %s leaked %d times in %d iterations", target, leaks, iters) } } diff --git a/ingestion/internal/mcp/readexcerpt_root_test.go b/ingestion/internal/mcp/readexcerpt_root_test.go index 9ba1748..73df8a2 100644 --- a/ingestion/internal/mcp/readexcerpt_root_test.go +++ b/ingestion/internal/mcp/readexcerpt_root_test.go @@ -21,6 +21,11 @@ func TestReadExcerptRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) { require.NoError(t, os.MkdirAll(facts, 0o755)) require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(facts, "leak.md"))) assert.NotContains(t, readExcerpt(brain, "wiki/w/facts/leak.md", 500), brainfstest.Sentinel) + // A link to a file elsewhere in the brain: os.Root allows it, only the + // regular-file check refuses it (hyperguild#171). + inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md")) + require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md"))) + assert.NotContains(t, readExcerpt(brain, "wiki/w/facts/inlink.md", 500), brainfstest.Sentinel) p := filepath.Join(facts, "r.md") require.NoError(t, os.WriteFile(p, []byte("---\nx: y\n---\ninside"), 0o644)) @@ -28,6 +33,9 @@ func TestReadExcerptRefusesSymlinksAndSurvivesSwapRaces(t *testing.T) { brainfstest.AssertNoLeak(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, func() string { return readExcerpt(brain, "wiki/w/facts/r.md", 500) }) + brainfstest.AssertNoLeakFrom(t, p, "---\nx: y\n---\ninside", inBrain, 1500*time.Millisecond, func() string { + return readExcerpt(brain, "wiki/w/facts/r.md", 500) + }) brainfstest.AssertNoHang(t, p, "---\nx: y\n---\ninside", 1500*time.Millisecond, 6*time.Second, func() { _ = readExcerpt(brain, "wiki/w/facts/r.md", 500) }) diff --git a/ingestion/internal/search/brainroot_test.go b/ingestion/internal/search/brainroot_test.go index 6acb636..ea5f5d2 100644 --- a/ingestion/internal/search/brainroot_test.go +++ b/ingestion/internal/search/brainroot_test.go @@ -12,6 +12,8 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + + "github.com/mathiasbq/hyperguild/ingestion/internal/brainfs/brainfstest" ) // hyperguild#157 option 1: search walked and read the brain by path, so a @@ -172,3 +174,47 @@ func TestHydrateRefusesASymlink(t *testing.T) { assert.Error(t, err) assert.NotContains(t, r.Excerpt, sentinel157) } + +// hyperguild#171: os.Root refuses links that leave the brain on its own, so +// the outside-target cases above would stay green for a caller that read +// without brainfs's Lstat and SameFile checks. These targets are inside the +// brain (raw/, which is not a search root). +func inBrainTarget(t *testing.T, brain string) string { + t.Helper() + return brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md")) +} + +func TestQueryLeaksNothingFromAnInBrainTargetUnderASymlinkSwapRace(t *testing.T) { + brain, facts, _ := searchBrain(t) + target := inBrainTarget(t, brain) + read := func() string { + rs, _ := Query(brain, QueryOptions{Query: brainfstest.Sentinel, Limit: 10}) + s := "" + for _, r := range rs { + s += r.Title + r.Excerpt + } + return s + } + brainfstest.AssertNoLeakFrom(t, filepath.Join(facts, "r.md"), "# r\n\nzqinside", target, 1500*time.Millisecond, read) + require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md"))) + assert.NotContains(t, read(), brainfstest.Sentinel, "static in-brain link") +} + +func TestHydrateRefusesAnInBrainSymlinkAndLeaksNothingUnderASwapRace(t *testing.T) { + brain, facts, _ := searchBrain(t) + target := inBrainTarget(t, brain) + require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md"))) + r, err := hydrate(brain, "wiki/w/facts/inlink.md") + assert.Error(t, err) + assert.NotContains(t, r.Excerpt+r.Title, brainfstest.Sentinel) + + p := filepath.Join(facts, "r.md") + require.NoError(t, os.WriteFile(p, []byte("# r\n\nzqinside"), 0o644)) + r, err = hydrate(brain, "wiki/w/facts/r.md") + require.NoError(t, err) + assert.Contains(t, r.Excerpt, "zqinside", "positive control: a regular note hydrates") + brainfstest.AssertNoLeakFrom(t, p, "# r\n\nzqinside", target, 1500*time.Millisecond, func() string { + r, _ := hydrate(brain, "wiki/w/facts/r.md") + return r.Title + r.Excerpt + }) +} diff --git a/ingestion/internal/vectorstore/sync_root_test.go b/ingestion/internal/vectorstore/sync_root_test.go index 8f83f74..63512d2 100644 --- a/ingestion/internal/vectorstore/sync_root_test.go +++ b/ingestion/internal/vectorstore/sync_root_test.go @@ -42,6 +42,11 @@ func TestSyncRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) { brain := t.TempDir() writeNote(t, brain, "wiki/w/facts/ok.md", "inside note") require.NoError(t, os.Symlink(brainfstest.Outside(t), filepath.Join(brain, "wiki", "w", "facts", "leak.md"))) + // A link to a file elsewhere in the brain: os.Root allows it, only the + // regular-file checks refuse it (hyperguild#171). raw/ is not a scan root, + // so its sentinel can only arrive through the link. + inBrain := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md")) + require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(brain, "wiki", "w", "facts", "inlink.md"))) emb := &recordingEmbedder{} store := &stubStore{} @@ -51,6 +56,7 @@ func TestSyncRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) { assert.NotContains(t, emb.all(), brainfstest.Sentinel) for p := range store.upserts { assert.NotContains(t, p, "leak.md") + assert.NotContains(t, p, "inlink.md") } p := filepath.Join(brain, "knowledge", "r.md") @@ -61,6 +67,7 @@ func TestSyncRefusesSymlinkedNotesAndSurvivesSwapRaces(t *testing.T) { return e.all() } brainfstest.AssertNoLeak(t, p, "inside", 1500*time.Millisecond, sync) + brainfstest.AssertNoLeakFrom(t, p, "inside", inBrain, 1500*time.Millisecond, sync) brainfstest.AssertNoHang(t, p, "inside", 1500*time.Millisecond, 6*time.Second, func() { _ = sync() }) } -- 2.54.0 From a83f0cb381f2b4c61be7d40ad728694e8799e744 Mon Sep 17 00:00:00 2001 From: Mathias Date: Mon, 5 Oct 2026 07:19:27 +0200 Subject: [PATCH 2/4] test(search): name the in-brain swap-race tests after what they sample Review of #172 (rule 9): "LeaksNothing" claims more than a 1.5s sampled race can prove -- the same overclaim this PR removes from the "Never" names. Renamed to DoesNotReturn...DuringASampledSwapRace, and the brainfstest doc now says the target may be inside the brain (#171) and that observation is over a sampled window. Co-Authored-By: Claude Opus 5.5 --- .../internal/brainfs/brainfstest/brainfstest.go | 12 +++++++----- ingestion/internal/search/brainroot_test.go | 4 ++-- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/ingestion/internal/brainfs/brainfstest/brainfstest.go b/ingestion/internal/brainfs/brainfstest/brainfstest.go index fd9ef0d..582925f 100644 --- a/ingestion/internal/brainfs/brainfstest/brainfstest.go +++ b/ingestion/internal/brainfs/brainfstest/brainfstest.go @@ -1,8 +1,10 @@ // Package brainfstest is the shared harness for hyperguild#157's swap-race -// tests: it keeps swapping a regular note, a symlink to an outside file, or a -// FIFO (with a writer held open) into a path while a reader under test loops. -// It observes two things: no sentinel byte from the outside file reaches the -// reader's output, and the reader returns within a timeout. It does not cover +// tests: it keeps swapping a regular note, a symlink to a sentinel target file +// (outside the brain, or inside it for hyperguild#171), or a FIFO (with a +// writer held open) into a path while a reader under test loops. +// It observes two things, over a sampled window only: no sentinel byte from +// the target reaches the reader's output, and the reader returns within a +// timeout. It does not cover // hard links, other paths into the reader, or races it does not generate. package brainfstest @@ -18,7 +20,7 @@ import ( "time" ) -// Sentinel marks the outside file's contents. +// Sentinel marks the target file's contents. const Sentinel = "zqbrainfssentinelonefiftyseven" // outsideContent carries Sentinel in every field a reader might extract: the diff --git a/ingestion/internal/search/brainroot_test.go b/ingestion/internal/search/brainroot_test.go index ea5f5d2..9ea2cb9 100644 --- a/ingestion/internal/search/brainroot_test.go +++ b/ingestion/internal/search/brainroot_test.go @@ -184,7 +184,7 @@ func inBrainTarget(t *testing.T, brain string) string { return brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md")) } -func TestQueryLeaksNothingFromAnInBrainTargetUnderASymlinkSwapRace(t *testing.T) { +func TestQueryDoesNotReturnAnInBrainSymlinkTargetDuringASampledSwapRace(t *testing.T) { brain, facts, _ := searchBrain(t) target := inBrainTarget(t, brain) read := func() string { @@ -200,7 +200,7 @@ func TestQueryLeaksNothingFromAnInBrainTargetUnderASymlinkSwapRace(t *testing.T) assert.NotContains(t, read(), brainfstest.Sentinel, "static in-brain link") } -func TestHydrateRefusesAnInBrainSymlinkAndLeaksNothingUnderASwapRace(t *testing.T) { +func TestHydrateRefusesAnInBrainSymlinkAndDoesNotReturnItsTargetDuringASampledSwapRace(t *testing.T) { brain, facts, _ := searchBrain(t) target := inBrainTarget(t, brain) require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md"))) -- 2.54.0 From f969d97c1696bbe8941f6d366cc2250ecbeb1e57 Mon Sep 17 00:00:00 2001 From: Mathias Date: Mon, 5 Oct 2026 07:20:59 +0200 Subject: [PATCH 3/4] test(notes): in-brain symlink target for ReadScoped, the sixth slice 1-3 caller Review of #172 (finding 1): notes.ReadScoped (brain_read, slice 2) had only outside-brain targets, which os.Root refuses on its own, so a reader bypassing brainfs's Lstat/SameFile stayed green. Adds a static in-brain link, a positive control and an in-brain swap race. Flip: replacing ReadRegularMax with os.OpenRoot().ReadFile turns it red 3/3. Co-Authored-By: Claude Opus 5.5 --- ingestion/internal/notes/read_root_test.go | 28 ++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/ingestion/internal/notes/read_root_test.go b/ingestion/internal/notes/read_root_test.go index a699fd4..eaa970b 100644 --- a/ingestion/internal/notes/read_root_test.go +++ b/ingestion/internal/notes/read_root_test.go @@ -38,3 +38,31 @@ func TestReadScopedRefusesANoteOverMaxNoteBytes(t *testing.T) { _, err := ReadScoped(brain, "wiki/w/facts/big.md", ScopeNotes) assert.ErrorIs(t, err, ErrTooLarge) } + +// hyperguild#171 (review of #172, finding 1): os.Root alone refuses links that +// leave the brain, so the outside-target race above stays green for a reader +// that skips brainfs's Lstat and SameFile checks. An in-brain target (raw/, +// outside ScopeNotes) is what tells them apart. +func TestReadScopedDoesNotReturnAnInBrainSymlinkTargetStaticallyOrDuringASampledSwapRace(t *testing.T) { + brain := t.TempDir() + facts := filepath.Join(brain, "wiki", "w", "facts") + require.NoError(t, os.MkdirAll(facts, 0o755)) + target := brainfstest.WriteSentinelAt(t, filepath.Join(brain, "raw", "s.md")) + + require.NoError(t, os.Symlink(filepath.Join("..", "..", "..", "raw", "s.md"), filepath.Join(facts, "inlink.md"))) + b, err := ReadScoped(brain, "wiki/w/facts/inlink.md", ScopeNotes) + assert.Error(t, err, "static in-brain link") + assert.NotContains(t, string(b), brainfstest.Sentinel, "static in-brain link") + + p := filepath.Join(facts, "r.md") + require.NoError(t, os.WriteFile(p, []byte("inside"), 0o644)) + b, err = ReadScoped(brain, "wiki/w/facts/r.md", ScopeNotes) + require.NoError(t, err) + assert.Equal(t, "inside", string(b), "positive control: a regular note reads") + + read := func() string { + b, _ := ReadScoped(brain, "wiki/w/facts/r.md", ScopeNotes) + return string(b) + } + brainfstest.AssertNoLeakFrom(t, p, "inside", target, 1500*time.Millisecond, read) +} -- 2.54.0 From 1cf05fdf15de39503fb62a8464281ff8da94bf2e Mon Sep 17 00:00:00 2001 From: Mathias Date: Mon, 5 Oct 2026 16:20:41 +0200 Subject: [PATCH 4/4] test(search): in-brain Query race queries the inside note too After main's #177 floor (AssertNoLeakFrom needs at least one read that returns the inside note), this test went red on merge: the reader queried only the sentinel, so the regular note could never be a hit and the race had been passing vacuously. Query both terms. Co-Authored-By: Claude Opus 5.5 --- ingestion/internal/search/brainroot_test.go | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/ingestion/internal/search/brainroot_test.go b/ingestion/internal/search/brainroot_test.go index f9253e5..a94a4a9 100644 --- a/ingestion/internal/search/brainroot_test.go +++ b/ingestion/internal/search/brainroot_test.go @@ -205,7 +205,9 @@ func TestQueryDoesNotReturnAnInBrainSymlinkTargetDuringASampledSwapRace(t *testi brain, facts, _ := searchBrain(t) target := inBrainTarget(t, brain) read := func() string { - rs, _ := Query(brain, QueryOptions{Query: brainfstest.Sentinel, Limit: 10}) + // Both terms, so the regular note is a possible hit: a reader that + // never returns the inside note would pass vacuously (#177 floor). + rs, _ := Query(brain, QueryOptions{Query: brainfstest.Sentinel + " zqinside", Limit: 10}) s := "" for _, r := range rs { s += r.Title + r.Excerpt -- 2.54.0