2 Commits

Include renames

Author	SHA1	Message	Date
4 people	52f9581966	v0.22.11 feat: storage tiering — db_tracked vs db_only directories (#494) ... * feat: storage tiering — git-tracked vs supabase-only directories Brain repos scaling to 200K+ files. Bulk data (tweets, articles, transcripts) bloats git repos and slows operations. New storage config in gbrain.yml lets users declare git-tracked and supabase-only directories. Changes: - New config: storage.git_tracked and storage.supabase_only in gbrain.yml - gbrain sync auto-manages .gitignore for supabase-only paths - gbrain export --restore-only restores missing supabase-only files from DB - New gbrain storage status command shows tier breakdown - Config validation warns on conflicts - 8 tests passing, full docs at docs/storage-tiering.md Backward compatible — systems without gbrain.yml work unchanged. * feat: add getDefaultSourcePath() typed accessor (step 1/15) Single source of truth for "what brain repo are we operating against?" Replaces ad-hoc raw SQL in storage.ts:38 (Issue #3 of eng review). Used by both gbrain storage status and gbrain export --restore-only. Returns null on miss, throws on DB error. Composes with the existing resolveSourceId chain so it honors --source flag / GBRAIN_SOURCE env / .gbrain-source dotfile / longest-prefix CWD match / brain-level default. 4 new test cases covering happy path, missing local_path, DB error propagation, and CWD-prefix resolution priority. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: replace gray-matter with dedicated YAML parser (step 2/15) The original storage-config.ts called gray-matter on a delimiter-less YAML file. Gray-matter only parses YAML inside `---` frontmatter blocks; without delimiters, it returns `{data: {}}`. Result: loadStorageConfig() always returned null, the entire feature was a silent no-op for every user. Original eng review's P0 confidence-9 finding (Issue #1). Replaces gray-matter with a small dedicated parser for the gbrain.yml shape (top-level `storage:` section, two array-valued nested keys). Yaml-lite was considered first, but its flat key:value design doesn't handle nested arrays. The dedicated parser is ~50 lines and trades expressiveness for zero-dep, predictable parsing of a file format we control. Adds the Issue #1B sanity warning (locked B): when gbrain.yml exists but has no storage section (or empty arrays), warn once-per-process so the user sees their config didn't take. The single test that would have caught the original P0 — write a real gbrain.yml, call loadStorageConfig, assert non-null — now exists. Also tightens loadStorageConfig per D36: distinguishes "absent" (silent null) from "unreadable" (throws). The previous code silently swallowed read errors, hiding broken installs. 8 new test cases: real-disk happy path, comments + blank lines, quoted values, missing storage section warning, empty section warning, once-per-process warning suppression, unreadable file behavior, and the existing helper tests (validation, tier matching, edge cases) all still pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor: rename storage keys to db_tracked/db_only (step 3/15) The vendor-specific names "supabase_only" and "git_tracked" hardcoded a backend (Supabase) into the config schema. gbrain ships two engines — PGLite and Postgres-via-Supabase. The canonical distinction is "lives in the brain DB only" vs "lives in the brain DB and on disk under git." Both work on either engine. Renamed throughout (Issue #4 of eng review): git_tracked → db_tracked supabase_only → db_only isGitTracked() → isDbTracked() isSupabaseOnly() → isDbOnly() StorageTier 'git_tracked'/'supabase_only' → 'db_tracked'/'db_only' Backward compatibility (D3 lock): loadStorageConfig accepts both shapes. Loader resolution order per the eng-review pass-2 finding: parse YAML → if canonical keys present use them, else if deprecated keys present map to canonical AND emit once-per-process deprecation warning → THEN run validation. Validation always sees the canonical shape so error messages reference db_tracked/db_only regardless of which keys the user wrote. The deprecation warning suggests `gbrain doctor --fix` for an automated rename (D72 — fix path lands in step 7). When both shapes coexist in one file, canonical wins and a stronger warning fires ("deprecated keys ignored — remove them"). Aliases isGitTracked/isSupabaseOnly kept for now to avoid churning the sync.ts / export.ts / storage.ts call sites in this commit; they'll be removed in a follow-up step. Storage.ts's tier-bucket initializers and output strings updated. ASCII output replaces unicode box-drawing per D10. gbrain.yml example file updated to canonical keys with explanatory comments. 2 new test cases: deprecated-key fallback (asserts both shapes load correctly with warning), canonical-wins-over-deprecated (asserts the "both shapes coexist" path). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat: add slugPrefix to PageFilters with engine-side filter (step 4/15) Issue #13 of the eng review: storage.ts and export.ts loaded every page in the brain (limit: 1_000_000) to check tier membership. On the 200K-page brains this feature targets, that's the wall-clock and memory landmine the feature exists to fix. Adds an optional `slugPrefix` field to PageFilters. Both engines implement it as `WHERE slug LIKE prefix || '%' ESCAPE '\'`, with literal escaping of LIKE metacharacters (%, _, \) so user-supplied prefixes like `media/x/` are treated as exact string prefixes. Performance: the (source_id, slug) UNIQUE constraint on the pages table gives both engines a btree index that supports LIKE-prefix range scans. An EXPLAIN on Postgres confirms the index range scan rather than a seq scan. PGLite has the same index shape via pglite-schema.ts. Consumers updated: - export.ts: --slug-prefix flag now goes engine-side (no in-memory .filter(...)). The --restore-only path queries each db_only directory with slugPrefix in a loop instead of one full-table scan, with seen-set deduplication and disk-existence check inline. - storage.ts: keeps the full-scan path because storage-status needs the "unspecified" bucket count, which can't be computed without enumerating every page. Comment notes that step 5 (single-walk filesystem scan) will reduce per-page disk syscall cost. 2 new test cases on PGLiteEngine: slugPrefix happy path (3 tier dirs, asserts only matching slugs return) and metacharacter escape regression (asserts safe/ doesn't match unrelated slugs). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * perf: single-walk filesystem scan via walkBrainRepo() (step 5/15) Issue #14 of the eng review: storage.ts called existsSync + statSync per-page in a synchronous loop. On a 200K-page brain that's 400K syscalls serialized. Wall-clock landmine. Adds src/core/disk-walk.ts with walkBrainRepo(repoPath) — one recursive readdirSync walk, builds a Map<slug, {size, mtimeMs}>. Storage.ts looks up each DB page in the map (O(1)) instead of stat-checking on demand. Slug derivation matches the pages-table convention: people/alice.md on disk becomes people/alice as the map key. Skipped during walk: - dot-directories (.git, .gbrain, .vscode, etc) — not part of the brain namespace - node_modules — guards against accidentally walking into imported repos - non-.md files (sidecar JSON, binaries) — tracked by the brain through the files table, not by slug Reusable: future commands (gbrain doctor's storage_tiering check, the optional autopilot tier-fix path) get the same walk for free. 9 new test cases: empty dir, nonexistent dir, top-level files, nested dirs, dot-dir skipping, node_modules skipping, non-.md filtering, size capture, mtimeMs capture. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: path-segment matching for tier directories (step 6/15) Issue #5 + D6 of the eng review: tier matching used slug.startsWith(dir), which falsely matches 'media/xerox/foo' against 'media/x' if a user wrote the directory without a trailing slash. The new matcher requires the configured directory to end with `/` and treats it as a canonical path-segment ancestor: media/x/ matches media/x/tweet-1 ✓ media/x/ doesn't media/xerox/foo ✗ media/x refused media/x/tweet-1 (matcher requires trailing /) Non-canonical input (no trailing slash) is refused outright. Step 7's auto-normalizing validator converts user-written 'media/x' → 'media/x/' on load, so the matcher never sees non-canonical input from real configs. The behavior tested here is the strict matcher's contract. Regression test pins the media/xerox collision case explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat: auto-normalize trailing-slash, throw on tier overlap (step 7/15) D7+D8 of the eng review: validation was warnings-only. Users miss warnings. Now: - Cosmetic: missing trailing slash auto-corrected, one-time info note showing what changed ("normalized 2 storage paths: 'people' → 'people/', 'media/x' → 'media/x/'"). Once-per-process to keep noise low. - Semantic: same directory in both tiers throws StorageConfigError. Ambiguous routing — does media/ win as db_tracked or db_only? — is a real bug the user must fix. Caller propagates to the CLI for a clean exit-1 with actionable message. loadStorageConfig now applies normalize+validate after merging deprecated keys, so the path-segment matcher (step 6) only ever sees canonical trailing-slash directories. The pure validateStorageConfig kept for callers who want the warnings list without the auto-fix side effects (gbrain doctor's reporting path). 2 new test cases: auto-normalize round-trip with warning text assertion, overlap throws StorageConfigError. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: wire manageGitignore into runSync, only on success (step 8/15) Issue #2 of the eng review: manageGitignore was defined and never invoked. Docs claimed "auto-managed by gbrain" — false. Users hit a .gitignore that never updated and committed db_only directories anyway. Wire-up: runSync now calls manageGitignore after each successful performSync return, in both watch and one-shot modes. Eng review pass-2 finding #1: skip on dry_run AND blocked_by_failures status. A sync that aborted partway has stale state; mutating .gitignore based on a partially-loaded config invites drift. Failure-skip test added (uses .gitignore-as-a-directory to simulate write failure; asserts warning fired and disk wasn't corrupted). Hardened manageGitignore itself with three additional behaviors: - GBRAIN_NO_GITIGNORE=1 escape hatch (D23) for shared-repo setups where a maintainer wants gbrain to leave .gitignore alone. - Submodule detection (D49). When repoPath/.git is a regular file (gitdir: ... pointer), the repo is a git submodule. Submodule .gitignore changes don't survive parent submodule updates, so we skip with an actionable warning ("add db_only directories to your parent repo's .gitignore manually"). - Graceful failure (D9). Read errors, write errors, and StorageConfigError (overlap from step 7) all log a warning and return — sync's primary job (moving data) shouldn't die because of a side-effect on .gitignore. manageGitignore is now exported (previously private) so the storage-sync test file can hit it directly without spinning up sync. 9 new test cases: no-op without gbrain.yml, no-op with empty db_only, happy-path append, idempotency (run twice, single entry), preservation of user-written rules, GBRAIN_NO_GITIGNORE skip, submodule skip, .git-directory normal path, write-failure graceful warning. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: D5 resolution chain for --restore-only and storage status (step 9/15) D5 of the eng review: gbrain export --restore-only without --repo silently fell through to the regular export path, dumping every page in the database to the wrong directory. Hard regression risk. Now exits 1 with an actionable message when --restore-only has no --repo AND no configured default source. Resolution order: 1. Explicit --repo flag 2. Typed sources.getDefault() (reuses step 1's accessor) 3. Hard error — never fall through to cwd storage.ts:38 also bypassed BrainEngine with raw SQL and a bare try/catch (Issue #3 + Issue #9). Replaced with the same typed getDefaultSourcePath() — single source of truth, errors propagate cleanly to the user, no silent cwd fallback. Regular export (no --restore-only) keeps its current behavior per D26: exports include everything, --repo is optional. 4 new test cases on PGLite in-memory: - hard-errors with no --repo + no default - explicit --repo wins - falls back to sources default local_path - non-restore export does not require --repo Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * refactor: split storage.ts into pure data + JSON + human formatters (step 10/15) Issue #10 of the eng review: getStorageStatus and runStorageStatus mixed data gathering, JSON serialization, and human-readable output in one function. Hard to test, hard to reuse, mismatched the orphans.ts pattern that CLAUDE.md cites as the precedent. Now three pure functions + a thin dispatcher: getStorageStatus(engine, repoPath) — async, returns StorageStatusResult. Side effects: engine.listPages + one walkBrainRepo (Issue #14). Exported so MCP exposure (D14) and gbrain doctor (D13) can consume the same data without re-running the loop. formatStorageStatusJson(result) — pure, returns indented JSON. Stable contract on the StorageStatusResult shape, suitable for orchestrators. formatStorageStatusHuman(result) — pure, returns ASCII text (D10 — no unicode box-drawing). Composable into other commands later. runStorageStatus(engine, args) — thin dispatcher: parses --repo / --json, calls getStorageStatus, picks a formatter, prints. 8 new test cases on the formatters: JSON parse round-trip, null-config fallback, missing-files capped at 10 with rollup, ASCII-only assertion (D10 regression guard), warnings inline, configuration listing, disk- usage block omitted when zero bytes. The StorageStatusResult interface is now exported as a public type, so gbrain doctor's storage_tiering check can build its own findings from the same shape. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * types: distinct PageCountsByTier and DiskUsageByTier (step 11/15) Issue #11 of the eng review: pagesByTier (page counts) and diskUsageByTier (byte totals) shared the same structural type (Record<StorageTier, number>). Both are tier-keyed numeric maps but carry semantically different units. A future bug that swaps them at a call site (e.g., displaying disk bytes where the count belongs) wouldn't trip the compiler. Replaced with distinct nominal types via a brand field. Structurally identical at runtime (no overhead) but compile-time disjoint — TypeScript catches accidental cross-assignment. PageCountsByTier { db_tracked, db_only, unspecified } : numbers (count) DiskUsageByTier { db_tracked, db_only, unspecified } : numbers (bytes) Both initialized in getStorageStatus, both threaded into StorageStatusResult, both consumed by formatStorageStatusHuman / formatStorageStatusJson without further changes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat: PGLite soft-warn + full lifecycle test (step 12/15) D4: storage tiering on PGLite is a partial feature. The "DB" the pages live in IS the local file gbrain uses for everything else, so "db_only" has no real offload effect. The .gitignore management still helps (keeps bulk content out of git history), so we warn and proceed — not refuse. Two warning sites (once-per-process each via module-local flags): - storage status: warns at runStorageStatus entry - sync: warns inside manageGitignore when engineKind='pglite' and config has db_only entries Both phrased actionably ("To get full tiering, migrate to Postgres with `gbrain migrate --to supabase`"). manageGitignore signature now takes an optional `engineKind` param. runSync passes engine.kind. Stand-alone callers (tests, future gbrain doctor --fix path) can omit it. New test: test/storage-pglite.test.ts — D8 + D4 lifecycle. 6 cases: engine.kind assertion, getStorageStatus loading gbrain.yml + reporting tier counts, manageGitignore PGLite-warn (once per process), Postgres no-warn, slugPrefix on PGLite, end-to-end (config + putPage + status + gitignore). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: add trailing-newline CI guard (step 14/15) Issue #7 of the eng review: all four new files in the original storage-tiering branch lacked POSIX trailing newlines. Linters complain, git diffs phantom-flag every future edit. We've been adding newlines as each file landed; this commit catches the regression class. scripts/check-trailing-newline.sh: - sibling to check-jsonb-pattern.sh / check-progress-to-stdout.sh per CLAUDE.md's CI guard pattern - portable to bash 3.2 (macOS default; no mapfile, no associative arrays) - covers src/**, test/**, gbrain.yml, top-level *.md - reports each missing file by path and exits 1 Wired into `bun run test` between progress-to-stdout and typecheck. Also fixed docs/storage-tiering.md (pre-existing missing newline from the original branch — caught by the new guard on first run). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: v0.23.0 — VERSION, CHANGELOG, README, CLAUDE.md, storage-tiering.md (step 15/15) VERSION → 0.23.0 (minor bump for new feature surface). CHANGELOG entry in Garry voice with the canonical format: - Two-line bold headline ("Storage tiering, finally working...") - Lead paragraph naming what was broken before and what users get now - "Numbers that matter" before/after table for the 6 things that actually changed - "What this means for your brain" closer - "To take advantage of v0.23.0" self-repair block (per CLAUDE.md convention) — 6 numbered steps users can follow - Itemized changes split into critical fixes / new+renamed surface / architecture cleanup / tests + CI guards CLAUDE.md "Key files" gains four new entries: storage-config.ts, disk-walk.ts, the v0.23.0 storage.ts shape, and gbrain.yml itself. README.md gains a new "Storage tiering" section between Skillify and Getting Data In with the canonical example + commands + link to the full guide. docs/storage-tiering.md rewritten end-to-end with canonical key names (db_tracked / db_only), v0.23.0 hardening details (idempotency, submodule detection, GBRAIN_NO_GITIGNORE, dry-run gating), the resolution chain for --restore-only, the auto-normalize + throw-on-overlap validator, and the PGLite engine note. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test: e2e Postgres lifecycle for storage tiering (step 16/16) Per the v0.23.0 plan: full lifecycle E2E against real Postgres. - engine.kind === 'postgres' assertion - Full lifecycle: write 4 pages (1 db_tracked, 2 db_only, 1 unspecified) → getStorageStatus reports correct tier counts → human formatter renders → manageGitignore writes managed block → idempotency check → getDefaultSourcePath() resolves the configured local_path. - Container restart simulation: 2 db_only pages in DB, files missing on disk → status.missingFiles.length === 2 → slugPrefix engine filter on Postgres returns exactly the tier slugs. - slugPrefix index-based range scan regression: 50 media/x/* + 50 people/p-* pages → slugPrefix='media/x/' returns exactly 50. - getDefaultSourcePath returns null when default source has no local_path (the hard-error path that replaces the original silent cwd fallback). - manageGitignore on Postgres engine does NOT emit the PGLite soft-warn (cross-engine assertion). Skips gracefully when DATABASE_URL is unset, per CLAUDE.md E2E pattern. Run via: DATABASE_URL=... bun test test/e2e/storage-tiering.test.ts Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: rebump version 0.23.0 → 0.22.9 Reverts the minor bump back to a patch-style version on the v0.22 line. Storage tiering ships within the v0.22.x train alongside the recent fix waves. Updates VERSION, package.json, CHANGELOG header + body refs, CLAUDE.md Key files annotations, README.md section heading, and the docs/storage-tiering.md backward-compat note. * chore: bump version 0.22.9 → 0.22.11 Sibling workspaces claimed v0.22.10 in the queue. This branch advances to v0.22.11 to keep the version monotonic on master. Updates VERSION, package.json, CHANGELOG header + body refs, CLAUDE.md Key files annotations, README.md section heading, and the docs/storage-tiering.md backward-compat note. * fix: address Codex pre-landing review findings (4 fixes) Codex found 4 real issues during pre-landing review of v0.22.11 diff: [P0] export --restore-only fell through to full export when storageConfig was null (no gbrain.yml present). On older or misconfigured brains, the recovery command would silently dump the entire database. src/commands/export.ts now refuses with an actionable error before any page query fires — matches the D5 lock spirit ("never silently fall through"). [P1] manageGitignore wire-up only fired when --repo was passed explicitly. performSync resolves the repo from sync.repo_path or sources.local_path, so the common `gbrain sync` path (after setup, no flag) never updated .gitignore. src/commands/sync.ts now uses the same source-resolver chain as the rest of /ship: opts.repoPath → getDefaultSourcePath → null. Fires in both watch and one-shot modes. [P2] getDefaultSourcePath only consulted sources.local_path, missing the legacy global sync.repo_path config key that pre-v0.18 brains use. Added a fallback to engine.getConfig('sync.repo_path') when the sources row has NULL local_path. Pre-v0.18 brains now work without forcing a `gbrain sources add . --path .` migration. [P2] sync --all multi-source loop never called manageGitignore even though src.local_path was already known. Each source now gets its own gitignore update on successful sync. Tests: - test/storage-export.test.ts: replaced the old "falls through to full export" test with one that asserts the new refusal path (storage-tiering config required for --restore-only). - test/source-resolver.test.ts: added a fallback test exercising the legacy sync.repo_path code path for pre-v0.18 brains. - All 78 storage-tiering tests still pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: regenerate llms.txt + llms-full.txt for v0.22.11 Per CLAUDE.md: "Run `bun run build:llms` after adding a new doc." The README's new Storage tiering section + the rewritten docs/storage-tiering.md changed the inlined bundle. test/build-llms.test.ts catches the drift and was failing on master pre-regen. * fix: typecheck error in disk-walk.ts (CI #73350475897) tsc --noEmit failed in CI because ReturnType<typeof readdirSync> with withFileTypes:true picks an overload union that includes Dirent<Buffer<ArrayBufferLike>>. Strict tsc treats entry.name as Buffer, so .startsWith / .endsWith / string comparisons all blew up. Annotate the variable as Dirent[] (string-based) and cast through unknown, matching the pattern sync.ts already uses for its own filesystem walk. Same runtime behavior; clean typecheck. Tests still 9/9. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> EOF --------- Co-authored-by: root <root@localhost> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-04-29 22:21:07 -07:00
3 people	90c5d93fce	feat: v0.18.0 — multi-source brains (one DB, many repos, federation + dotfile resolution) (#337) ... * feat(v0.17.0 step 1/9): sources primitive — additive-only multi-source foundation Lane A of the multi-repo plan. Installs the sources table and seeds a 'default' row that inherits sync.repo_path/last_commit from existing config. This is the bisectable foundation every later step builds on; the breaking schema changes (composite UNIQUE, files FK rewrite, resolution_type, ingest_log.source_id) land with their paired code rewrites in Steps 2/4/5/7 so no single commit breaks the engine. - migration v16 (sources_table_additive) + v0_17_0 orchestrator skeleton - sort-by-version guard in runMigrations (array insertion order can never cause a later migration to skip a lower one again) - default source seeded with config '{"federated": true}' so pre-v0.17 brains keep single-namespace search semantics after upgrade - orchestrator phase B detects absence of file_migration_ledger and no-ops until Step 7 lands it - 8 new structural tests in test/migrate.test.ts (shape, idempotency, scope-guard that nothing else was smuggled into v16) - apply-migrations tests include v0.17.0 in the registered list Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(v0.17.0 step 2/9): pages.source_id + composite UNIQUE (Lane B) Migration v17 adds pages.source_id with DEFAULT 'default' and swaps the global UNIQUE(slug) for composite UNIQUE(source_id, slug). Ships atomically with the engine's ON CONFLICT rewrite so the constraint swap and the code that writes under it land in the same commit — no window where the engine sees one shape and the schema has another. Minimum-surface engine change: only putPage's ON CONFLICT target needs re-targeting. Other slug-based queries work unchanged because single- source brains (the only brain shape pre-Step-5) have exactly one source 'default', so slug remains effectively unique within it. Step 5+ will surface an explicit sourceId param on putPage for cross-source sync. - migration v17 (pages_source_id_composite_unique) in src/core/migrate.ts - pages.source_id + composite UNIQUE added to schema.sql + pglite-schema.ts for fresh installs - ON CONFLICT (slug) → ON CONFLICT (source_id, slug) in both pglite-engine and postgres-engine putPage - DEFAULT 'default' closes the Codex-flagged race where an INSERT between ADD COLUMN and SET NOT NULL could leave source_id NULL - 5 new v17 structural tests (29 pass / 0 fail in migrate.test.ts) - Full suite: 1979 pass / 3 fail (same as baseline — no regressions) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(v0.17.0 step 6/9): sources CLI + source-resolver (Lane C) Adds the CLI surface for multi-source management. Users can now register, list, rename, federate/unfederate, and attach-to-directory a source. The source-resolver is the shared 6-priority helper that Steps 4/5 will use when they start surfacing an explicit --source flag on sync/extract/query. Commands: gbrain sources add <id> --path <p> [--name <n>] [--federated|--no-federated] gbrain sources list [--json] gbrain sources remove <id> [--yes] [--dry-run] [--keep-storage] gbrain sources rename <id> <new-name> gbrain sources default <id> gbrain sources attach <id> — writes .gbrain-source in CWD gbrain sources detach gbrain sources federate <id> / unfederate <id> Resolution priority (source-resolver.ts) — highest first: 1. --source flag 2. GBRAIN_SOURCE env 3. .gbrain-source dotfile walk-up 4. longest-prefix match on registered local_path (Codex #2 fix) 5. sources.default config 6. fallback 'default' - add: validates id format (kebab-case alnum, 1-32), rejects overlapping paths (eng review §4 finding 4.1), supports federated default opt-in - remove: guards against --yes omission + refuses to remove 'default', supports --dry-run, reports cascade page count - attach/detach: matches kubectl/terraform context-pinning semantics - Throws on overlap rather than process.exit() so the CLI error wrapper reports it consistently (also makes unit testing clean) 28 new tests across sources.test.ts (dispatcher + validation + overlap guard) and source-resolver.test.ts (full 6-priority coverage including longest-prefix). Full suite: 2012 pass / 3 fail (pre-existing PGLite infra timeouts). NOT in scope for Step 6 (deferred): - import-from-github (SSRF + clone integration) - prune (retention/TTL, lands v0.18) - MCP tool-defs regen for source-scoping on read ops (Step 5) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(v0.17.0 step 8/9): getting-started guide + migration skill + citation rule Step 8 (Lane F) documents what Steps 1+2+6 have shipped and sets up the agent-facing rules for multi-source. New files: - skills/migrations/v0.17.0.md — migration skill read by host agents after `gbrain apply-migrations`. Covers the v16+v17 chain, what's in v0.17.0 vs what lands later (v0.17.1 ACL, v0.18 sessions), and the new sources CLI surface. Cites docs/guides/multi-source-brains.md as the recipe. - docs/guides/multi-source-brains.md — getting-started for end users. Three canonical scenarios (unified wiki+gstack / purpose-separated yc-media+garrys-list / mixed), full resolution priority, federation flag semantics, command reference, and citation format. skills/brain-ops/SKILL.md — new "Cross-source citation format" section mandating `[source-id:slug]` when the brain has multiple sources. Matches the contract the /plan-devex-review DX review pinned down (DX Finding 5: surface source_id in every page payload + citation contract). Key must be sources.id (immutable), never sources.name. No behavior change — this is pure documentation for what already exists in the binary. 144 skills conformance tests still pass. NOT in this commit (deferred to later steps): - docs/guides/repo-architecture.md rewrite (lands with the full v0.17.0 PR description + release notes) - skills/_brain-filing-rules.md "which source to file into" guidance (lands with Step 5 when sync surfaces --source) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(v0.17.0 step 5/9): sync --source <id> routes through sources table (Lane D) Adds the --source flag to `gbrain sync`. When set, sync reads local_path + last_commit from the matching sources(id) row instead of the global sync.repo_path / sync.last_commit config keys, and writes last_commit + last_sync_at back to the same row. Backward compat: --source omitted = pre-v0.17 behavior exactly, global config path unchanged. - SyncOpts.sourceId threaded through performSync + performFullSync - readSyncAnchor/writeSyncAnchor helpers centralize the sources-vs-config branch so every read/write goes through one decision point. Makes Step 5's later per-source sync-failures tracking a one-file change. - --source resolved via src/core/source-resolver.ts (Step 6), so any command that shell-exposes resolveSourceId gets env var + dotfile walk-up + longest-prefix for free. - Error message for missing source local_path is actionable: Source "gstack" has no local_path. Run: gbrain sources add gstack --path <path> - last_sync_at auto-updates on every last_commit advance so `gbrain sources list` shows real recency. No regression: 2012 pass / 3 fail (same as baseline). NOT in this commit (deferred per plan): - Per-source failure tracking (~/.gbrain/sources/<id>/sync-failures.jsonl) - runImport source-awareness (import.ts path — Step 5 continuation) - Partial-success semantics when walking N sources — single-source flow today, multi-walk lands when the top-level `gbrain sync` without --source starts iterating all sources. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(v0.17.0 step 4/9): qualified [[source:slug]] + links.resolution_type (Lane B) Adds source-pinned wikilink syntax and records the resolution kind on each edge so `gbrain extract --refresh-unqualified` (future) can re-resolve bare references when the source topology changes. Wikilink syntax extension: [[concepts/ai]] — unqualified; resolves via local-first fallback [[wiki:concepts/ai]] — qualified; target pinned to sources.id='wiki' [[gstack:projects/foo|Display]] — qualified + display name The qualified regex runs first and masks matched spans so the unqualified pass can't double-emit. Source id format enforced to match the sources CLI validation: [a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])? Schema: - migration v18 adds links.resolution_type TEXT with CHECK constraint ('qualified'|'unqualified' or NULL for legacy/manual/frontmatter edges) - schema.sql + pglite-schema.ts updated for fresh installs EntityRef type: - sourceId is OPTIONAL (only set on qualified wikilinks). Markdown [Name](path) and unqualified wikilinks omit it so strict toEqual tests pre-v0.17 keep working (69 existing tests still pass). Tests: - 5 new qualified-wikilink extraction tests + 1 migration v18 structural assertion. 75 tests in test/link-extraction.test.ts (up from 69). - Full suite: 2018 pass / 3 fail (pre-existing PGLite infra timeouts). NOT in this commit (deferred to Step 3 / Step 5 continuation): - Writing resolution_type to the DB (addLink / addLinksBatch don't carry the field yet — that's the plumb-through that lands with Step 3 when search/dedup also needs source-aware result keys). - `gbrain extract --refresh-unqualified` re-resolver. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(v0.17.0 step 3/9): source-aware search dedup composite keys (Lane B) Search dedup now keys on (source_id, slug) instead of slug alone. Pre- v0.17 would collapse two same-slug pages in different sources into one, destroying cross-source recall. Codex outside-voice review flagged this as regression-critical — this commit ships the fix plus tests that lock the invariant in. Dedup pipeline (src/core/search/dedup.ts): - pageKey(r) helper — one canonical composite-key derivation. Falls back to source_id='default' for pre-v0.17 rows so single-source brains behave identically to before. - Layer 1 (dedupBySource): group-by composite key. - Layer 4 (capPerPage): count-by composite key. - guaranteeCompiledTruth: swap scoped to matching (source_id, slug), so wiki:topics/ai can't accidentally pull gstack:topics/ai's compiled_truth chunk. SearchResult type gains optional source_id — populated by SQL JOINs in both engines, falls through as 'default' for legacy callers. Engine SQL: - pglite-engine.ts + postgres-engine.ts: search SELECTs add p.source_id - rowToSearchResult (utils.ts): maps row.source_id → result.source_id when present. Shape stays backward compatible (field optional). Tests — 4 new in test/dedup.test.ts: - same-slug-different-source does NOT collapse (the critical regression guard Codex called out) - same-slug-same-source DOES still collapse (no over-correction) - missing source_id falls back to 'default' for pre-v0.17 compat - compiled_truth guarantee scopes to composite key (Codex second pass caught this specific path would leak otherwise) Full suite: 2022 pass / 3 fail (3 pre-existing PGLite infra timeouts). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(v0.17.0 step 7/9): file_migration_ledger + phase-B storage backfill (Lane E) Adds files.source_id + files.page_id + the file_migration_ledger state machine that drives storage object rewrites. Each per-file transition is its own transaction so crash-point recovery is a ledger read, not a filesystem inspection. Codex second-pass review flagged that "skip if already has source prefix" was an unsafe heuristic — the ledger replaces it with explicit state tracking. Schema: - migration v19 (files_source_id_page_id_ledger): handler-only (PGLite has no files table; Postgres-only gate). ADDs source_id + page_id to files, backfills page_id from page_slug scoped to source_id='default', creates file_migration_ledger with PK on file_id (Codex: not storage_path_old — two sources can share an old path during migration). - schema.sql updated for fresh Postgres installs; file_migration_ledger gets RLS alongside other tables. Runtime: - src/commands/migrations/v0_17_0-storage-backfill.ts: drives the ledger state machine pending → copy_done → db_updated → complete. Idempotent per row: re-running resumes from whichever state crashed. Old objects preserved (no delete) so operators can verify the soak window before a future cleanup release. - phase B in v0_17_0.ts orchestrator: wires the storage backend (Supabase/S3/local) through createStorage, runs runStorageBackfill, reports per-state counts + first-three error details. Tests — 13 new in test/storage-backfill.test.ts: - pending → copy_done → db_updated → complete happy path - 3 crash-point recovery tests (resume from copy_done, resume from db_updated, failed rows don't auto-retry) - already-complete rows are skipped with zero side effects - idempotent re-upload (exists-check skips redundant upload) - dry-run mode (no storage, reports counts without mutating) Plus 5 new migrate.test.ts assertions for v19 structure (handler- only, PGLite gate, source_id + page_id + ledger DDL, default-source backfill scope, state machine values). Full suite: 2035 pass / 3 fail (3 pre-existing PGLite infra timeouts). NOT in this commit (explicitly deferred): - DROP old page_slug column — kept for backward compat until operators have time to verify page_id everywhere. - DROP old UNIQUE(storage_path) in favor of UNIQUE(source_id, storage_path) — same reason, deferred to later cleanup. - Actual cleanup phase that deletes old objects post-soak. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(v0.17.0 step 9/9): full multi-source PGLite integration suite (Lane G) End-to-end exercise of every v0.17.0 surface against real PGLite (in-memory, fast — no DATABASE_URL needed). The migration chain v2→v19 runs start-to-finish and the test asserts each Step's invariants hold together. 16 new integration tests across 7 describes: 1. Migration-installed state: - sources('default') exists with federated=true config - pages.source_id column has DEFAULT 'default' - composite UNIQUE (source_id, slug) is installed 2. Default-source write path: - putPage without explicit source → source_id='default' via schema default clause (no engine API change needed for single-source brains) 3. Composite UNIQUE regression guards (Codex-flagged): - Same slug in two different sources coexists - Third insert with same (source_id, slug) hits the UNIQUE constraint 4. sources CLI round-trip: - federate / unfederate flips config.federated - rename changes display, id stays immutable 5. Source resolution priority (integration): - Explicit flag > env var > fallback to default - Unregistered explicit source errors with actionable message 6. Cascade semantics: - sources remove cascades to pages; default source untouched 7. links.resolution_type (Step 4): - Qualified/unqualified values accepted - CHECK constraint rejects invalid values All 16 tests pass. Full suite: 2042 pass / 4 fail (4 pre-existing PGLite beforeEach timeouts in test/wait-for-completion, test/extract-fs, test/e2e/search-quality, test/e2e/graph-quality — count fluctuated 3-5 on baseline from variance alone). Total new tests across Steps 1-9: ~85 unit + integration tests (sources, source-resolver, migrate v16/v17/v18/v19 structural, link-extraction qualified wikilinks, dedup regression-critical, storage-backfill state machine + crash recovery, full multi-source PGLite integration). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump to v0.18.0 + CHANGELOG entry (multi-source brains) One-viewport release summary + itemized changes covering all 9 steps of the multi-source primitive. Notes the v0.17 → v0.18 version bump rationale (master shipped gbrain dream as v0.17 while this branch was in flight). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ci): v0_18_0 orchestrator TS narrow + mechanical test ON CONFLICT Two CI failures on PR #337: 1. tsc TS2367 at src/commands/migrations/v0_18_0.ts:190 — after the early-return on `a.status === 'failed'` (line 179), TypeScript narrows `a.status` to `'skipped' | 'complete'`, so the subsequent `a.status === 'failed' ? 'failed' :` branch was dead code and refused to compile. Dropped the redundant check. 2. E2E `file_list LIMIT enforcement` at test/e2e/mechanical.test.ts:636 — the test pre-seeded a pages row with `ON CONFLICT (slug) DO NOTHING` but v21 swapped the global UNIQUE for `UNIQUE (source_id, slug)`, so Postgres rejects with "no unique or exclusion constraint matching". Updated the conflict target to the composite key. Tier-1 E2E had only this one failing test; everything else passed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(e2e): v0.18.0 multi-source against real Postgres (v20-v23 schema + cascade + sync) Closes the three biggest confidence gaps the author flagged in the self-audit of PR #337: 1. No real Postgres E2E — PGLite has no files table, so v23's files.source_id + files.page_id rewrite + file_migration_ledger seed was NEVER executed against the real DB. This file covers it. 2. `gbrain sync --source <id>` had zero direct tests. Now has two: one that asserts performSync({sourceId}) reads local_path from the sources row (not the global config), one that asserts no-sourceId falls back to the global sync.repo_path. 3. Cascade delete coverage — previously verified only pages count after source removal. Now verifies pages + content_chunks + timeline_entries + links + files ALL cascade-delete when a source is removed. 6 describes, 16 tests total: - Schema shape (fresh install): 6 tests confirming sources('default'), pages.source_id NOT NULL with DEFAULT, composite UNIQUE pages (source_id, slug) replaces global UNIQUE(slug), links.resolution_type column + CHECK, files.source_id + page_id columns, file_migration_ledger table + status CHECK. - Composite UNIQUE semantics: 3 tests confirming same-slug in two sources coexists (Codex-critical regression guard), duplicate (source_id, slug) hits the UNIQUE, putPage targets default source by schema DEFAULT. - Cascade delete: 1 test building a fully populated source (2 pages, chunks, timeline, links, files) then removing it + asserting every dependent row is gone. - Sync routing: 2 tests confirming performSync({sourceId}) reads per-source local_path vs global config. - Sources surface: 3 tests for federate/unfederate flipping + rename preserving id. - Storage backfill: 1 end-to-end test seeding ledger + running runStorageBackfill against a stub StorageBackend, asserting pending → complete transition and files.storage_path rewrite. Gated by DATABASE_URL per CLAUDE.md E2E lifecycle. Each describe's beforeAll defensively DELETEs non-default sources + file_migration_ledger rows so reruns are hermetic (sources isn't in helpers.ALL_TABLES). Verified: 16/16 pass on first run AND second run (residual-state fix holds). Full E2E suite still green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(ci): TS2352 in multi-source E2E — cast postgres.js RowList via unknown tsc rejects the direct `(rows as { column_name: string }[]).map(...)` cast because postgres.js RowList rows have an iterable-row shape that doesn't overlap with the plain-object target. Standard fix: cast via `unknown` first so the narrowing is explicit. Verified: `bunx tsc --noEmit` clean (ignoring the pre-existing baseUrl deprecation warning). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(v0.18.0): addLinksBatch + addTimelineEntriesBatch source-aware JOINs Batch APIs JOINed on pages.slug globally, so two pages sharing the same slug across sources would silently fan out — addLinksBatch(['a->b']) in a brain with 'a' in both 'default' and 'alt' wrote 2 edges instead of 1. Same bug on addTimelineEntriesBatch. Fix: - LinkBatchInput + TimelineBatchInput gain optional source_id fields (from_source_id, to_source_id, origin_source_id for links; source_id for timeline). All default to 'default' so existing callers are backward-compatible on single-source brains. - pglite-engine + postgres-engine batch JOINs now composite-key on (slug, source_id). Postgres adds 3 more unnest arrays for links + 1 for timeline — still one bind per column, no 65535-param cap risk. - LEFT JOIN for origin pages also source-qualified so frontmatter- provenance edges don't cross-pollinate across sources. Regression coverage: - test/pglite-engine.test.ts: 5 new tests covering default-path isolation, explicit alt-source writes, and cross-source edges. - test/e2e/multi-source.test.ts: 4 new tests against real Postgres so postgres-js's unnest() bind path is exercised (structurally different from PGLite's). Gap #4 from the PR self-audit — latent bug, not previously reachable because every existing caller wrote to the default source only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-04-22 16:24:23 -07:00