Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Consolidate 4 scattered data roots into one (Etan: 'why the fuck would we have 4 places?')

Open
  • Is something wrong?
#715 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Refactor
Clarity
Mostly clear
Activity status
Quiet
Tech stack
python, sqlite
Domain
backend, databases, documentation

Research direction

Start after #713 lands by reading paths.py and the existing Spotlight exclusion runbook, then trace the four roots named in the issue. The work is done when one documented root and doctor inventory remain, migration has rollback and a time-boxed compatibility read-path, and the runbook uses one Spotlight marker.

Written by the indexing model from the issue text.

Description

Etan, 2026-08-15, after having to add four separate Spotlight exclusions by hand (one of them a hidden Library path he couldn't find in Finder): "that's the type of thing we need to consolidate out of the system, why the fuck would we have 4 places?"

Current sprawl

Root What it holds Verdict
~/.local/share/brainlayer DB + WAL/SHM + vector sidecars keep — the data root
~/.brainlayer durable queue, quarantine, drain logs, runtime state earned a separate root ONLY for the "survives a corrupt DB" property — but that argument covers the queue, not the logs living beside it
~/Library/Logs/brainlayer launchd stdout/err + BrainBar logs macOS convention; a third place to remember
~/.brainlayer-p0-counter one counter log pure accretion — a top-level dotfolder for a single log

Cost already paid

  • The Spotlight exclusion runbook needs FOUR marker roots, four probes, four Search Privacy entries — and the hidden Library/Logs one is invisible in Finder (Etan needed Cmd+Shift+G).
  • Backups, doctor, and every future "exclude/verify/inventory" operation multiplies by four.
  • 08-15 M1 window: markers alone did not take; the human step became a 4-item checklist instead of 1.

Target

One root with a documented internal layout, e.g.

~/.local/share/brainlayer/
  db/        (brainlayer.db + wal/shm + vector sidecars)
  queue/     (durable queue, quarantine)
  logs/      (launchd + BrainBar + drain + p0-counter)
  • paths.py becomes the single resolver; nothing else constructs a root.
  • Migration must be a runbook operation (writers stopped, moves are same-volume renames) with rollback, like the Spotlight window.
  • Keep a compatibility read-path for one release so an un-migrated machine still starts, then delete it (per Etan's no-shim standing preference, the compat window is explicitly time-boxed and tracked).
  • After consolidation: ONE Spotlight marker, ONE thing to back up, ONE inventory line in doctor.

Sequencing

Do it AFTER #713 (self-verification layer) lands, so the migration itself can be verified automatically — and fold the Spotlight runbook down to a single root as part of it.

Related: #713 (nothing verifies itself), #714 (stale socket = existence≠liveness), the 08-15 Spotlight windows on both hosts.

Filed by brainlayerClaude lead (Fable 5).

🤖 Generated with Claude Code

Dominant language
Python
Stars
9
Forks
7
Avg merge
2h 8m
Merged PRs (30d)
211

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from EtanHey/brainlayer

All issues in EtanHey/brainlayer

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.