fix: creating and generated writes go through the brain root (#188, #158 part A) (#189)

New brainfs PutRegular (create or replace), CreateRegular (create only), AppendRegular, Remove and RealParent: missing parents created one component at a time through the root, every existing component a real directory, new files created with O_EXCL and confirmed before writing. brain_write, promote/reject (O_EXCL create, source kept on refusal), StampProvenanceFile, BuildWingIndex, RebuildIndex, AppendLog and the tunnel candidate log use them; provenance.ApplyFile removed.

Fixes #188. Refs #158. Adversarial review: BLOCKED, BLOCKED, PASS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Mathias <mthbqv@gmail.com>

ingestion/internal/brain/index.go

@@ -7,8 +7,6 @@ import (
 	"fmt"
 	"io"
 	"io/fs"
-	"os"
-	"path/filepath"
 	"sort"
 	"strings"
 	"time"
@@ -32,7 +30,6 @@ func BuildWingIndex(brainDir, wing string) error {
 	if w == "" {
 		return fmt.Errorf("invalid wing %q", wing)
 	}
-	wingDir := filepath.Join(brainDir, "wiki", w)
 	// Listed and read through the brain root (hyperguild#157): a wing or
 	// hall that is a symlink is not followed, and notes are regular files.
 	bfs, err := brainfs.Open(brainDir)
@@ -63,8 +60,9 @@ func BuildWingIndex(brainDir, wing string) error {
 		fmt.Fprintf(&b, "| %s | [%s](%s/%s.md) | %s |\n", e.Hall, e.Title, e.Hall, e.Slug, e.Created)
 	}
 
-	dest := filepath.Join(wingDir, "_index.md")
-	return os.WriteFile(dest, []byte(b.String()), 0o644)
+	// Written through the brain root, never through a symlinked _index.md
+	// (hyperguild#158).
+	return bfs.PutRegular("wiki/"+w+"/_index.md", []byte(b.String()))
 }
 
 // BuildAllWingIndexes regenerates _index.md for every wing under brain/wiki/.

ingestion/internal/brain/tunnel.go

@@ -5,7 +5,6 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
-	"os"
 	"path"
 	"path/filepath"
 	"strings"
@@ -176,35 +175,23 @@ func logFuzzyCandidates(brainDir, sourcePath string, cs []TunnelCandidate) error
 	if len(cs) == 0 {
 		return nil
 	}
-	rawDir := filepath.Join(brainDir, "raw")
-	if err := os.MkdirAll(rawDir, 0o755); err != nil {
-		return err
-	}
-	stamp := time.Now().UTC().Format("2006-01-02")
-	path := filepath.Join(rawDir, "tunnel-candidates-"+stamp+".md")
-	existed := fileExists(path)
-	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
+	// Appended through the brain root, never through a symlinked raw/ or
+	// log file (hyperguild#158).
+	bfs, err := brainfs.Open(brainDir)
 	if err != nil {
-		return err
+		return fmt.Errorf("open brain: %w", err)
 	}
-	defer func() { _ = f.Close() }()
-	if !existed {
-		if _, err := f.WriteString("# Tunnel candidates " + stamp + "\n\nFuzzy cross-wing matches surfaced by AutoTunnel. Review and promote to a tunnel via `brain_tunnel` if relevant.\n\n"); err != nil {
-			return err
-		}
+	defer func() { _ = bfs.Close() }()
+	stamp := time.Now().UTC().Format("2006-01-02")
+	rel := "raw/tunnel-candidates-" + stamp + ".md"
+	var buf strings.Builder
+	if _, err := bfs.Lstat(rel); errors.Is(err, fs.ErrNotExist) {
+		buf.WriteString("# Tunnel candidates " + stamp + "\n\nFuzzy cross-wing matches surfaced by AutoTunnel. Review and promote to a tunnel via `brain_tunnel` if relevant.\n\n")
 	}
 	for _, c := range cs {
-		line := fmt.Sprintf("- `%s` ↔ `%s` (term: %q)\n", sourcePath, c.TargetPath, c.MatchedTerm)
-		if _, err := f.WriteString(line); err != nil {
-			return err
-		}
+		fmt.Fprintf(&buf, "- `%s` ↔ `%s` (term: %q)\n", sourcePath, c.TargetPath, c.MatchedTerm)
 	}
-	return nil
-}
-
-func fileExists(p string) bool {
-	_, err := os.Stat(p)
-	return err == nil
+	return bfs.AppendRegular(rel, []byte(buf.String()))
 }
 
 // WriteTunnel appends a bidirectional wikilink between sourcePath and

ingestion/internal/brain/writers_redirect_test.go

@@ -0,0 +1,52 @@
+package brain_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/mathiasbq/hyperguild/ingestion/internal/brain"
+)
+
+// hyperguild#158: BuildWingIndex wrote wiki/<wing>/_index.md with
+// os.WriteFile, so a symlinked _index.md was written through.
+func TestBuildWingIndexDoesNotWriteThroughASymlinkedIndex(t *testing.T) {
+	b := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "w", "facts"), 0o755))
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "w", "facts", "n.md"), []byte("---\ntitle: zqn\n---\n"), 0o644))
+	victim := filepath.Join(b, "raw", "v.md")
+	require.NoError(t, os.MkdirAll(filepath.Dir(victim), 0o755))
+	require.NoError(t, os.WriteFile(victim, []byte("untouched"), 0o644))
+	require.NoError(t, os.Symlink(filepath.Join("..", "..", "raw", "v.md"), filepath.Join(b, "wiki", "w", "_index.md")))
+	assert.Error(t, brain.BuildWingIndex(b, "w"))
+	got, _ := os.ReadFile(victim)
+	assert.Equal(t, "untouched", string(got))
+
+	require.NoError(t, os.Remove(filepath.Join(b, "wiki", "w", "_index.md")))
+	require.NoError(t, brain.BuildWingIndex(b, "w"), "positive control")
+	idx, _ := os.ReadFile(filepath.Join(b, "wiki", "w", "_index.md"))
+	assert.Contains(t, string(idx), "zqn")
+}
+
+// AutoTunnel's fuzzy-candidate log appended to raw/tunnel-candidates-*.md
+// with os.OpenFile, so a symlinked raw/ (or log file) was written through.
+func TestAutoTunnelDoesNotAppendTheCandidateLogThroughASymlinkedRaw(t *testing.T) {
+	b := t.TempDir()
+	outside := t.TempDir()
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "a", "facts"), 0o755))
+	require.NoError(t, os.MkdirAll(filepath.Join(b, "wiki", "b", "facts"), 0o755))
+	// "zq widget" matches as a substring of "zq widgets", a fuzzy candidate.
+	require.NoError(t, os.WriteFile(filepath.Join(b, "wiki", "b", "facts", "t.md"), []byte("---\ntitle: Zq Widget\n---\n"), 0o644))
+	require.NoError(t, os.Symlink(outside, filepath.Join(b, "raw")))
+	_ = brain.AutoTunnel(b, "wiki/a/facts/s.md", "about zq widgets")
+	ents, _ := os.ReadDir(outside)
+	assert.Empty(t, ents, "the candidate log was written outside the brain")
+
+	require.NoError(t, os.Remove(filepath.Join(b, "raw")))
+	require.NoError(t, brain.AutoTunnel(b, "wiki/a/facts/s.md", "about zq widgets"))
+	logs, _ := filepath.Glob(filepath.Join(b, "raw", "tunnel-candidates-*.md"))
+	assert.Len(t, logs, 1, "positive control: the fuzzy candidate is logged in the real raw/")
+}