feat(native): DbClient factory — MYCELIUM_USE_PGLITE switch (#176 follow-up)

[Dewinator]

Summary

Foundation for the next big native-app refactor — ships the boot factory atomically so each service can be migrated in its own follow-up PR without re-negotiating the env-flag plumbing.

PR #208 ('sidecar bundling pipeline') called out the next native-app PR explicitly:

Refactor [`mcp-server/src/index.ts`] to honour `MYCELIUM_USE_PGLITE=1` and route all services through the in-process adapter is the next big native-app PR.

That refactor touches ~30 service constructors. This PR is the small piece that goes first: it gives each future migration a single stable type to depend on.

Changes

mcp-server/src/services/db-client.ts (new, 82 LOC)

• `DbClient = PostgrestClient | PGliteAdapter` — both already speak the same chain shape (`.from(t).select|insert|update|delete().eq|or|order|limit()` + `.rpc(name, args)` returning `{ data, error }`). The adapter contract tests in `pglite-adapter.test.ts` gate that surface so it stays drop-in.
• `createDbClient({ supabaseUrl, supabaseKey, pglite? })` returns `{ client, mode, close() }`. `MYCELIUM_USE_PGLITE=1` routes through `createNativeDb()`; any other value (unset, "0", "false", "true", anything) keeps the PostgREST client.
• Strict `=== "1"` matches the pattern PR feat(security): MYCELIUM_LLAMA_REQUIRE_CHECKSUM=1 fail-closed — Pillar 6 follow-up to #188 #189 (`MYCELIUM_LLAMA_REQUIRE_CHECKSUM`) and PR feat(middleware): EmbeddingProvider injection — #178 native-app readiness #190 (`MYCELIUM_LLM_PROVIDER`) already established for native-app feature flags.

mcp-server/src/__tests__/db-client.test.ts (new, 4 tests, 128 LOC)

• default (env unset) → `postgrest` mode
• any non-"1" value → `postgrest` mode (covers "0", "false", "true", "yes", "")
• "1" + temp `MYCELIUM_DATA_DIR` + `skipMigrations: true` → `pglite` mode; round-trips an insert/select through the adapter chain
• `close()` in pglite mode releases the underlying PGlite handle (`adapter.raw().closed === true`)

What's intentionally not in this PR

• No service migrated yet. `index.ts` still constructs each service with `(url, key, ...)`. The 30-site migration is split across follow-up PRs so each service is reviewed against both backends independently.
• No prod boot path changed. `MYCELIUM_USE_PGLITE` has no effect on the running MCP server until the first service starts depending on `createDbClient()`.

Validation

```
npm run build → clean
node --test dist/tests/db-client.test.js → 4/4 passed (8.6s)
node --test dist/tests/native/*.test.js → 36/36 passed (43s, no regression)
```

Test plan

• `cd mcp-server && npm run build` — clean
• `node --test dist/tests/db-client.test.js` — 4 passes
• Confirm no existing test imports `services/db-client.ts` (it's new — empty grep result expected)

Related

• Issue epic: native standalone app (no Docker) — macOS / Windows / Linux #176 (native standalone app epic — sub-task 3 / next big PR after sidecar bundling)
• PR feat(app): sidecar bundling pipeline — first .app builds clean (#176 ticket A) #208 (sidecar bundling) — body explicitly identifies this refactor as the next step
• PR feat(native): PGlite adapter foundation — issue #184 part 1 #185 (PGliteAdapter foundation, on main) — the adapter side of this factory
• PR feat(middleware): EmbeddingProvider injection — #178 native-app readiness #190 (`EmbeddingProvider` injection) — pattern this PR mirrors

🤖 Generated with Claude Code

[Dewinator]

Local validation (179th-tick fresh-clone walk, queue-bound, no-new-PR)

Walked the full DbClient stack #209 → #210 → #211 on a clean rebuild from each branch. All three green.

#209 (this PR — DbClient factory, branch agent/db-client-factory)

rm -rf dist && npm run build                  → clean
node --test dist/__tests__/db-client.test.js  → 4/4 pass (8.0s)
node --test 'dist/__tests__/native/*.test.js' → 36/36 pass (41s, no regression)

#210 (SwarmPin onto DbClient, branch agent/swarm-pin-dbclient-stacked)

rm -rf dist && npm run build                  → clean
node --test dist/__tests__/swarm-pin.test.js  → 14/14 pass (363ms)

#211 (Skills onto DbClient + shared dbClient, branch agent/skills-dbclient-stacked)

rm -rf dist && npm run build                                          → clean
node --test dist/__tests__/affect-skill-record-payload.test.js        → 8/8 pass (319ms)

(#211 is RPC-only and adds no new tests per the PR body; the Skills surface
is exercised through the existing affect-skill-record-payload regression
test, which still passes after the PostgrestClient → DbClient rename.)

Merge-order confirmation

The stack is linear and the merges chain cleanly: #209 lands first, then
#210, then #211. Each rebuild was done from a clean dist/ after switching
branches (per pinned mcp-server lesson — stale dist/ would mask
"no tests collected" failures unrelated to the PR).

No queue growth from this validation tick.

🤖 Generated with Claude Code

[Dewinator]

Independent local revalidation — 2026-05-05 (Mac M4, 16 GB)

Re-ran the validation block in the PR body on a fresh checkout of agent/db-client-factory (commit 8b6a203), ~26h after CI:

rm -rf dist && npm run build                      → clean (tsc, no errors)
node --test dist/__tests__/db-client.test.js      → 4/4 passed (8.3s total)
  ✔ PostgREST mode (default — env unset)            (0.1s)
  ✔ PostgREST mode for any non-1 value              (0.001s)
  ✔ PGlite mode boots adapter with usable .from()   (4.4s)
  ✔ close() in PGlite mode releases handle          (3.4s)
node --test 'dist/__tests__/*.test.js'            → 1010 pass / 1 skip / 0 fail (14.9s)

No regressions across the broader suite. Foundation is merge-ready; #210 and #211 are stacked behind via base-branch retargeting (verified: gh pr view 210 --json baseRefName → agent/db-client-factory, gh pr view 211 --json baseRefName → agent/swarm-pin-dbclient-stacked), so GitHub will auto-retarget on merge.

🤖 Auto-tick empirical validation