bunsane 0.3.0 → 0.3.2

package/docs/RFC_APP_REFACTOR.md

@@ -0,0 +1,248 @@
+# RFC: Split `core/App.ts`
+
+**Status:** Draft
+**Author:** uray@qyubit.io (drafted with Claude)
+**Branch target:** `refactor/app-split` (off `main`)
+**Date:** 2026-05-09
+**Companion work:** `refactor/archetype-split` (commit `a886b45`) — same playbook applied to `core/ArcheType.ts`.
+
+---
+
+## 1. Summary
+
+Split `core/App.ts` (1477 LOC, single God class) into a thin orchestrator (~400 LOC) plus 6–8 focused modules under `core/app/`. Public API surface (`new App(...)`, `app.use()`, `app.setCors()`, `app.start()`, `app.shutdown()`, etc.) remains byte-identical. No behavior change. Each step independently verifiable by the existing test suite.
+
+## 2. Motivation
+
+`App.ts` is the boot path for every entrypoint in the framework. Today it owns:
+
+- HTTP request routing (REST + GraphQL + Studio + health + metrics + OpenAPI/Swagger UI).
+- CORS validation + header injection.
+- GraphQL schema build + Yoga instance creation + plugin pipe + depth/complexity limits.
+- REST endpoint collection from `ServiceRegistry` + OpenAPI spec generation.
+- Lifecycle phase orchestration (`DATABASE_INITIALIZING` → `DATABASE_READY` → `SYSTEM_REGISTERING` → `SYSTEM_READY` → `APPLICATION_READY`).
+- Scheduler bootstrap + scheduled-task registration.
+- RemoteManager bootstrap + remote handler registration.
+- Process signal/error handlers (SIGTERM, SIGINT, unhandledRejection, uncaughtException).
+- Graceful shutdown ordering (HTTP drain → scheduler → remote → cache → DB pool).
+- Prepared-statement cache warm-up.
+- Metrics aggregation (`/metrics`).
+
+Concrete pain points observed in the file:
+
+| Method | Lines | Concern |
+|---|---|---|
+| `init()` | 151–495 (~345) | Phase switch + phase listener + DB prep + component registration. Multiple nested phases each running 30–80 LOC of business logic. |
+| `handleRequest()` | 663–1090 (~430) | Health, metrics, OpenAPI, Swagger UI, Studio API (4 sub-paths), static assets, REST router, GraphQL fall-through. |
+| `shutdown()` | 1365–1456 (~91) | Reasonable size today but couples directly to 5 subsystems. |
+| `warmUpPreparedStatementCache` | 1183–1237 | Unrelated to anything else `App` does. |
+| Studio API block inside `handleRequest` | 810–917 (~107) | Belongs in `studioEndpoint` module, not request router. |
+
+Effects today:
+
+1. **Hard to read.** Anyone changing CORS behavior reads through 1500 LOC to find the 80 LOC that matter.
+2. **Hard to test.** Health-endpoint logic, OpenAPI generation, Studio routing all require an `App` instance even though they're pure functions of state.
+3. **Hard to extend.** Adding a new subsystem (e.g. tracing) means another branch in `init()` and another endpoint in `handleRequest`, growing the monolith.
+4. **Coupling risk.** `handleRequest()` already references 8 modules transitively. Moving anything risks an import cycle.
+
+## 3. Goals / Non-Goals
+
+### Goals
+
+- Reduce `App.ts` to ≤500 LOC.
+- Each new module <500 LOC, single concern.
+- Zero change to public API (`App` class methods, `CorsConfig`, `AppConfig` exports).
+- Zero change to phase ordering, shutdown ordering, signal handling, or error handling.
+- All extractions verified by `tsc --noEmit` clean + `bun run test:pglite` green per step.
+- Each step is an independently revertable commit.
+
+### Non-Goals
+
+- **No DI introduction.** Project rule: singletons + global exports (per `MEMORY.md`). Extracted modules accept `App` (or its state subset) as a parameter; they do not receive an injection container.
+- **No new abstractions** (router DSL, middleware framework, plugin SPI v2, etc.). This is an extraction, not a redesign.
+- **No type-only changes** that would force consumer updates. `App` continues to default-export the same class.
+- **No fix to existing bugs** as part of this refactor. Issues found get filed and fixed in separate PRs.
+
+## 4. Proposed Layout
+
+```
+core/
+  App.ts                    # ~400 LOC: class skeleton + public API + delegates
+  app/
+    cors.ts                 # ~100 LOC: validateOrigin, getCorsHeaders, addCorsHeaders, validateCorsConfig
+    bootstrap.ts            # ~250 LOC: phase listener body, phase-specific handlers
+    graphqlSetup.ts         # ~80  LOC: yoga instance build, depth/complexity envvar resolution
+    restRegistry.ts         # ~120 LOC: REST endpoint collection from services + OpenAPI tagging
+    requestRouter.ts        # ~250 LOC: handleRequest body, dispatch table, request signal plumbing
+    healthEndpoints.ts      # ~80  LOC: /health, /health/ready, /health/remote handlers
+    studioRouter.ts         # ~120 LOC: /studio/api/* sub-router (lifts existing block)
+    metricsCollector.ts     # ~40  LOC: collectMetrics
+    preparedStatementWarmup.ts # ~60 LOC: warmUpPreparedStatementCache
+    processHandlers.ts      # ~80  LOC: register/unregister SIGTERM/SIGINT/unhandled/uncaught
+    shutdown.ts             # ~100 LOC: shutdown body + waitForHttpDrain
+```
+
+### Module responsibilities
+
+#### `app/cors.ts`
+- `validateOrigin(config, requestOrigin) → string | null`
+- `getCorsHeaders(config, req?) → Record<string, string>`
+- `addCorsHeaders(response, config, req?) → Response`
+- `assertValidCorsConfig(cors)` — throws if `origin === undefined`, etc.
+
+`App` keeps `setCors` as a public method but its body becomes `assertValidCorsConfig(cors); this.config.cors = cors;`. CORS state lives on `App.config.cors`; pure functions take it as a parameter.
+
+#### `app/bootstrap.ts`
+- `runDatabaseReadyPhase(app)` — wraps `warmUpPreparedStatementCache`.
+- `runSystemReadyPhase(app)` — cache health check, GraphQL setup (delegates to `graphqlSetup`), scheduler init, remote init, REST endpoint collection (delegates to `restRegistry`), final `setPhase(APPLICATION_READY)`.
+- `runApplicationReadyPhase(app)` — `app.start()` outside test env.
+- `createPhaseListener(app)` returns the closure currently inlined inside `init()`.
+
+`App.init()` becomes:
+```ts
+async init() {
+  this.openAPISpecGenerator = new OpenAPISpecGenerator(...);
+  this.registerProcessHandlers();
+  validateEnv();
+  if (this.cacheConfig) await CacheManager.initialize({ ...defaultCacheConfig, ...this.cacheConfig });
+  for (const plugin of this.plugins) plugin.init?.(this);
+  this.phaseListener = createPhaseListener(this);
+  ApplicationLifecycle.addPhaseListener(this.phaseListener);
+  if (currentPhase === DATABASE_INITIALIZING) {
+    if (!(await HasValidBaseTable())) await PrepareDatabase();
+    else await EnsureDatabaseMigrations();
+    ApplicationLifecycle.setPhase(DATABASE_READY);
+    await ComponentRegistry.registerAllComponents();
+    ApplicationLifecycle.setPhase(SYSTEM_REGISTERING);
+  }
+}
+```
+
+#### `app/requestRouter.ts`
+- `handleRequest(app, req)` — top-level dispatcher. Pulls path/method, attaches abort signal, runs the dispatch table.
+- Dispatch table lives here as a `Map<string, (app, req, url) => Promise<Response>>` for static paths plus regex for dynamic REST.
+- Calls `healthEndpoints`, `studioRouter`, `metricsCollector`, OpenAPI/docs handlers.
+
+This is the largest extraction — and the one with the highest risk because of subtle order-dependence. Mitigation: keep every `if (url.pathname === ...)` branch in the same order in the new module. No reordering.
+
+#### `app/healthEndpoints.ts`
+- `handleHealth()`, `handleReady(app)`, `handleRemoteHealth(app)`.
+
+Each returns `{ result, httpStatus }` so the router applies CORS uniformly. Today these are inline blocks; they become 8–10 LOC functions.
+
+#### `app/studioRouter.ts`
+- `routeStudio(app, url, req, method) → Promise<Response | null>` — returns `null` if not a studio path so the main router falls through.
+- Today: 107 LOC inline in `handleRequest`. Lifted with no change.
+
+#### `app/processHandlers.ts`
+- `registerProcessHandlers(app)`, `unregisterProcessHandlers(app)`.
+- Returns and stores handler refs on `app` (same shape as today).
+
+#### `app/shutdown.ts`
+- `shutdown(app)` body (HTTP drain → scheduler → remote → cache → DB → lifecycle disposal → handler unregister).
+- `waitForHttpDrain(server, timeoutMs)`.
+
+### Cross-cutting decisions
+
+- **`App` instance passed by reference.** Extracted functions take `app: App` (or a typed slice) and mutate state via existing setters/fields. We do not refactor private fields into a separate `AppState` type — that's a non-goal change.
+- **No lazy require for these.** Unlike the ArcheType extraction (which had circular type deps with `BaseArcheType`), the App extractions are leaves: they import `App` only as a type. Use `import type { default as App } from "../App"` to avoid runtime cycles.
+- **Logger reuse.** Each module creates its own child logger: `MainLogger.child({ scope: "App.cors" })`. Matches existing `scope: 'app'` conventions in the file.
+- **Error semantics preserved exactly.** The `SYSTEM_READY` failure path (line 451–467) is load-bearing — it sets `isReady=false`, logs fatal, and `process.exit(1)` outside test env (memory: H-K8S-1 / C09). Extraction keeps this exit path intact and tested.
+
+## 5. Migration Plan
+
+Each step is a separate commit on `refactor/app-split`. Run `tsc --noEmit` and `bun run test:pglite` between steps. Skip a step if its preconditions aren't met after the prior commit.
+
+### Step 1 — `cors.ts` (lowest risk, smallest blast)
+- Move `validateOrigin`, `getCorsHeaders`, `addCorsHeaders` to `core/app/cors.ts`.
+- Each takes `app.config.cors` (or a `CorsConfig`) explicitly; no `this`.
+- `App` methods become 1-line delegates.
+- **Verify:** existing CORS tests pass. Check `tests/e2e` for CORS assertions.
+
+### Step 2 — `processHandlers.ts`
+- Lift `registerProcessHandlers` / `unregisterProcessHandlers`.
+- **Verify:** signal handler tests if any; otherwise sanity-test by sending SIGINT in a dev run.
+
+### Step 3 — `shutdown.ts` + `waitForHttpDrain`
+- Lift the entire `shutdown()` body + helper.
+- `App.shutdown()` becomes `return runShutdown(this)`.
+- **Verify:** shutdown ordering tests (memory: C10, C14 referenced).
+
+### Step 4 — `metricsCollector.ts` + `preparedStatementWarmup.ts`
+- Pure leaves. Move and re-import.
+- **Verify:** `/metrics` endpoint test (E2E).
+
+### Step 5 — `healthEndpoints.ts`
+- Move `/health`, `/health/ready`, `/health/remote` handlers.
+- Each returns `{ result, httpStatus }`; router wraps in `Response` with CORS.
+- **Verify:** health endpoint tests (`tests/e2e`).
+
+### Step 6 — `studioRouter.ts`
+- Lift the entire `if (this.studioEnabled && pathname.startsWith("/studio/api/"))` block.
+- **Verify:** Studio is opt-in (`enableStudio()`) so most tests don't exercise it. Manual smoke test with `STUDIO_ENABLED=true` env.
+
+### Step 7 — `graphqlSetup.ts` + `restRegistry.ts`
+- Extract Yoga instance build + GraphQL depth/complexity envvar resolution.
+- Extract REST endpoint collection loop (lines 347–446) including OpenAPI spec generation per endpoint.
+- **Verify:** GraphQL schema tests (`bun run test:graphql`), REST endpoint tests.
+
+### Step 8 — `bootstrap.ts`
+- Move the `switch (phase)` body into per-phase functions.
+- `App.init()` shrinks to the skeleton above.
+- **Highest risk step** — this is where lifecycle ordering bugs would surface. Mitigation: do this last, after all leaves are extracted, so any test failure isolates to the orchestrator.
+- **Verify:** full test suite. Pay attention to `tests/integration` (boot-sensitive).
+
+### Step 9 — `requestRouter.ts`
+- Move `handleRequest` body. By this point everything it calls is already extracted, so this is largely cut/paste.
+- `App.handleRequest()` becomes `return handleRequest(this, req)`.
+- **Verify:** every E2E test (HTTP path coverage).
+
+### Order rationale
+
+Leaves first (cors, processHandlers, shutdown, metrics, prepStmtWarmup, healthEndpoints, studioRouter), then composites (graphqlSetup, restRegistry), then orchestrators (bootstrap, requestRouter). This minimizes the number of in-flight extractions when the riskiest steps run.
+
+## 6. Verification Strategy
+
+For every step:
+
+1. `tsc --noEmit` — must show only the 4 pre-existing `gql/index.ts` errors.
+2. `bun run test:pglite` — full suite (currently 770 pass / 0 fail post-archetype-split).
+3. `bun run test:e2e` — covers HTTP routing, CORS, health, OpenAPI.
+4. Manual smoke at the end: `bun examples/<some-app>/index.ts`, hit `/health`, `/openapi.json`, `/graphql`.
+5. **Lifecycle assertion:** before & after Step 8 + Step 9, capture the printed phase log on a clean boot and `diff` them. Phase order must be byte-identical.
+
+## 7. Risks
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| Phase listener ordering bug in `bootstrap.ts` extraction | High | Step 8 done last, after every dependency lifted. `diff` the boot log before/after. |
+| Studio path order in `requestRouter` changes a fall-through | Medium | Keep branch order identical; extract as one block, not per-handler. |
+| `handleRequest` abort-signal plumbing breaks | Medium | The signal-combine logic stays in the router (not split). Test with deliberate slow handlers. |
+| Import cycle between `App` and `bootstrap` (or `requestRouter`) | Medium | Use `import type` for `App` in extracted modules. Verified by `tsc --noEmit` per step. |
+| `setRemoteManager(null)` in shutdown is missed | Low | Lifted as part of `shutdown.ts`; verified by remote-shutdown tests. |
+| `process.exit(1)` path on SYSTEM_READY failure removed accidentally | High | Step 8 includes a regression test asserting that `runSystemReadyPhase` rethrows in `NODE_ENV=test`. |
+| Hidden coupling: `composedHandler` set in `start()` but bound to `handleRequest` | Medium | Keep the `bind(this)` site in `App.start()` (not in `requestRouter`). The function `handleRequest` is exported from the module but the bound reference lives on `App`. |
+
+## 8. Rollback
+
+Each step is a single commit. Roll back with `git revert <sha>`. Because every step preserves the public API, partial rollback (steps 1–6 kept, 7–9 reverted) is also safe.
+
+If the whole branch needs to be abandoned: `git checkout main; git branch -D refactor/app-split`. No state outside git.
+
+## 9. Out of Scope (Follow-ups)
+
+Items observed during analysis but explicitly not addressed here:
+
+- **`handleRequest` cyclomatic complexity.** Even after extraction, `requestRouter` has ~15 branches. Could later be a registration-based dispatch (`app.registerRoute(method, path, handler)`) — but that's a feature, not a refactor.
+- **`enforceDocs` warning text.** Hardcoded "Don't use this endpoint until it's properly documented!" in `init()`. Extraction preserves it; cleanup is separate.
+- **Studio API duplication.** Several `studio/api/*` paths repeat the same `parseInt(url.searchParams.get(...))` pattern. After extraction these are obvious to dedupe — but again, separate PR.
+- **Metrics shape.** `/metrics` returns ad-hoc JSON. Prometheus exposition format is a future concern.
+- **Prepared-statement warmup heuristics.** "First 5 components, first 3 for multi-component" is arbitrary. Tunable later.
+
+## 10. Decision Required
+
+- [ ] Approve scope and 9-step plan.
+- [ ] Approve module names / locations under `core/app/`.
+- [ ] Confirm: no public API change, no behavior change, no DI introduction.
+
+Once approved, work proceeds on `refactor/app-split` with one commit per step. Estimated effort: 4–6 focused hours given the test suite already in place.

package/docs/RFC_REFACTOR_TARGETS.md

@@ -0,0 +1,251 @@
+# RFC: Remaining Refactor Targets
+
+**Status:** Backlog / planning
+**Author:** uray@qyubit.io (drafted with Claude)
+**Date:** 2026-05-09
+**Prior work:** `core/ArcheType.ts` split — commit `a886b45`, merged to `staging` (`fd75f21`).
+
+---
+
+## 1. Purpose
+
+After `ArcheType.ts` was split (3064 → 1032 LOC across 8 modules under `core/archetype/`), several other files in `core/` remain large and concern-dense. This RFC enumerates them in priority order so future refactor work has a reference.
+
+This is a **planning document**, not an approval-bound RFC. Each target listed here would get its own scoped RFC (like `RFC_APP_REFACTOR.md`) before work starts.
+
+## 2. Selection Criteria
+
+Files are ordered by combined score of:
+
+1. **Size** (LOC) — bigger = harder to read, harder to test.
+2. **Concern density** — number of distinct responsibilities mixed in one class/module.
+3. **Blast radius** — how many tests/consumers depend on the file booting cleanly.
+4. **Refactor ROI** — likelihood that splitting yields independently testable modules without behavior change.
+
+Pure "library leaf" files (formatter helpers, fixed schemas) are excluded even when large, because splitting them wouldn't reveal new structure.
+
+## 3. Targets
+
+### 3.1 `core/App.ts` — 1477 LOC — **highest priority**
+
+**Why next:** Most God-class. Mixes:
+
+- Application lifecycle (phase orchestration, DB prep, component registration).
+- HTTP server (Bun.serve setup, request routing, signal/disconnect plumbing).
+- CORS (origin validation, header injection, preflight handling).
+- OpenAPI spec generation (per-endpoint registration, Swagger UI HTML).
+- GraphQL setup (Yoga instance, depth/complexity limits, plugin pipe, context factory wrap).
+- REST routing (endpoint collection, dispatch).
+- Plugin pipeline (`addPlugin`, `addYogaPlugin`).
+- Scheduler bootstrap (`SchedulerManager` init, scheduled task registration per service).
+- Health endpoints (`/health`, `/health/ready`, `/health/remote`).
+- Metrics endpoint (`/metrics`).
+- Studio routing (`/studio/api/*` — 107 LOC inline).
+- Remote subsystem bootstrap (RemoteManager init, handler registration).
+- Process signal & error handlers (SIGTERM, SIGINT, unhandledRejection, uncaughtException).
+- Graceful shutdown ordering (HTTP → scheduler → remote → cache → DB).
+- Prepared-statement cache warm-up.
+
+`init()` is a giant `switch (phase)` (lines 198–476) where each case runs 30–80 LOC of business logic. `handleRequest()` is ~430 LOC across 8+ branches.
+
+**Detailed plan:** see `RFC_APP_REFACTOR.md` (drafted, awaiting approval).
+
+**Status:** RFC drafted, not started.
+
+---
+
+### 3.2 `core/Entity.ts` — 1212 LOC
+
+**Why next:** `save()` alone likely 300+ LOC. Cache ops inline. Mixes:
+
+- Component add/get/remove (in-memory + persisted).
+- DB persistence (insert/update/delete with abort signal + per-component partitioned writes).
+- Cache write-through / write-invalidate strategies (L1 + L2 + pubsub).
+- Hook dispatch (pre-save, post-save, post-delete) via `EntityHookManager`.
+- Pending side-effects queue (`Entity.pendingCacheOps`, `Entity.pendingSideEffects` static drain methods for shutdown).
+- Profile timing (`DB_SAVE_PROFILE`).
+- Abort signal handling (timeout + client disconnect cancellation).
+- Component-ready preflight (`ComponentRegistry.getReadyPromise`).
+- Static finders (`FindById`, etc.).
+
+**Proposed split direction:**
+
+```
+core/entity/
+  saveEntity.ts       # save() body — DB writes, abort, profile
+  cacheStrategies.ts  # write-through, write-invalidate per component
+  pendingOps.ts       # pendingCacheOps + pendingSideEffects + drain methods
+  componentAccess.ts  # add/get/remove + in-memory cache
+  finders.ts          # static FindById, etc.
+```
+
+Class skeleton + public API stays in `Entity.ts`.
+
+**Risks:**
+
+- `Entity.save()` is hot-path. Per-step micro-benchmark (save 1000 entities) before/after each extraction.
+- Hook ordering is load-bearing (per `MEMORY.md` H-HOOK-1..3, C13). Don't reorder pre/post-commit phases.
+- The PGlite Bun-SQL ACK race (documented in `CLAUDE.md`) is in this file's blast radius — keep `await entity.save()` semantics byte-identical.
+
+**Estimated effort:** larger than App.ts because of perf sensitivity. ~6–8 hours plus benchmark validation.
+
+**Status:** Not started.
+
+---
+
+### 3.3 `core/SchedulerManager.ts` — 932 LOC
+
+**Why next:** Scheduling logic + distributed lock + hook orchestration in one class.
+
+Concerns to disentangle:
+
+- Cron expression parsing + schedule evaluation.
+- Task registration & lookup (`registerScheduledTasks`).
+- Per-task execution loop with skip-on-running guard (H-SCHED-1..5 in memory).
+- Distributed lock (`DistributedLock`) acquisition + release semantics.
+- Lifecycle integration (`disposeLifecycleIntegration`, awaiting in-flight tasks on `stop()` per C14).
+- Metrics (`getMetrics`).
+- Error handling per task.
+
+**Proposed split direction:**
+
+```
+core/scheduler/
+  cronEvaluator.ts    # cron expression -> next-fire-time
+  taskRunner.ts       # per-task execute loop + skip-on-running
+  lockCoordinator.ts  # DistributedLock wiring
+  lifecycleHooks.ts   # phase-listener + dispose
+  metrics.ts          # getMetrics
+```
+
+`SchedulerManager` keeps singleton + public API.
+
+**Risks:**
+
+- Concurrency hardening already done in v0.3.0 (H-SCHED-1..5). Refactor must preserve every guard. Property-based tests on the runner would help.
+- Re-entry semantics on `DistributedLock` (memory: `acquired:false` on overlap). Don't change.
+
+**Status:** Not started.
+
+---
+
+### 3.4 `core/EntityHookManager.ts` — 921 LOC
+
+**Why next:** Hook registry + dispatch + lifecycle in one place.
+
+Concerns:
+
+- Hook registration (per-component, per-event).
+- Dispatch ordering (pre vs post, sync vs async).
+- Hook chain with timer leak fixes (memory: H-HOOK-2, H-MEM-2).
+- Re-entry / recursion guard.
+- Integration with `Entity.save()` post-commit microtask scheduling.
+
+**Proposed split direction:**
+
+```
+core/hooks/
+  registry.ts     # register/lookup
+  dispatcher.ts   # dispatch loop + ordering
+  guards.ts       # re-entry guard, timer cleanup
+```
+
+`EntityHookManager` keeps public API.
+
+**Risks:**
+
+- Hook timing fixes (C13, H-HOOK-1..3) are load-bearing. Tests assert specific orderings.
+- Cross-file coupling with `Entity.ts` — coordinate with §3.2 if both run in flight.
+
+**Status:** Not started.
+
+---
+
+### 3.5 `core/cache/CacheManager.ts` — 574 LOC
+
+**Why next:** L1 (memory) + L2 (Redis) + strategies + pub/sub all-in-one. Already smaller than peers, so lower priority.
+
+Concerns:
+
+- Provider initialization (memory + Redis).
+- Strategy dispatch (write-through vs write-invalidate).
+- Cross-instance invalidation via Redis pub/sub (`instanceId` loop prevention).
+- Cache stats / health (`ping`, `getStats`).
+- Singleton lifecycle (`initialize` async, `shutdown`).
+
+**Proposed split direction:**
+
+```
+core/cache/
+  CacheManager.ts        # singleton + public API (kept)
+  strategies/
+    writeThrough.ts
+    writeInvalidate.ts
+  invalidation.ts        # pub/sub coordinator
+  health.ts              # ping + stats
+```
+
+**Risks:**
+
+- `CacheManager.initialize()` is now async (BREAKING CHANGE per memory, 2026-02-17). Don't regress.
+- Cross-instance loop prevention (`instanceId`) is load-bearing. Test with two instances on same Redis.
+
+**Status:** Not started. Lowest priority of the five — defer until at least one peer refactor lands.
+
+---
+
+## 4. Cross-Cutting Themes
+
+Several patterns recur and would benefit from being decided once before any of these refactors start:
+
+### 4.1 Extraction pattern
+
+`ArcheType.ts` split established the pattern:
+
+- Pure functions in submodules accept the class instance as a parameter (`buildFieldResolvers(archetype)`).
+- Class methods become 1-line delegates via lazy `require()` to break circular type deps.
+- Maps/state stay in the submodule that owns them, exported as `const`.
+- Public API preserved by re-export from the parent file.
+
+This pattern works well for ECS-style classes where the class is mostly a data bag with methods. **Re-use it for App, Entity, SchedulerManager, EntityHookManager.** `CacheManager` may want a different shape (provider injection) given its strategy variants.
+
+### 4.2 Test infrastructure assumed stable
+
+All five targets are exercised by the current 770-test suite (under `bun run test:pglite`). No target requires new test scaffolding before extraction starts; existing tests are sufficient guardrails for behavior preservation.
+
+### 4.3 No DI introduction
+
+Project rule (per `CLAUDE.md` and `MEMORY.md`): singletons + global exports, no dependency injection container. Extracted modules must respect this — pass `app: App`, `entity: Entity`, etc., not an injection token.
+
+### 4.4 No bundled bug fixes
+
+If a refactor reveals a latent bug (wrong ordering, missing guard, stale comment claim), file it separately. Refactor PRs must show "no behavior change" by passing the existing test suite unchanged.
+
+## 5. Recommended Order
+
+1. **`App.ts`** — RFC drafted, ready to start. Highest payoff: every test boots through it.
+2. **`Entity.ts`** — Highest perf sensitivity but biggest readability win. Allocate benchmark time.
+3. **`SchedulerManager.ts`** *or* **`EntityHookManager.ts`** — Either next. They're partially coupled (hooks fire from scheduler-triggered work), so coordinate.
+4. **`CacheManager.ts`** — Last. Smallest of the five, already structured around providers.
+
+This ordering minimizes risk because the most heavily-tested file goes first (more guardrails) and the perf-sensitive file goes early-second when there's still energy for benchmarking.
+
+## 6. Anti-Goals
+
+These are not refactors and should not be bundled:
+
+- **Adding new abstractions** (router DSL, plugin SPI v2, hook framework). Out of scope for any of these.
+- **Performance "improvements"** that change semantics. If a refactor reveals an O(n²) loop, file it separately.
+- **API renaming** for "consistency". Public symbols stay byte-identical.
+- **Comment cleanup pass** as a side effect. Touch only comments that are actively wrong after a code move.
+
+## 7. Decision
+
+This RFC requires no decision. It exists so the next person picking up refactor work has:
+
+- A prioritized list.
+- Concern inventory per file.
+- Pre-identified risks per file.
+- Cross-cutting guardrails (extraction pattern, no-DI rule, no bundled fixes).
+
+When work starts on any one target, that target gets its own RFC and own branch (per the `RFC_APP_REFACTOR.md` template).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "author": {
         "name": "yaaruu"
     },

package/query/ComponentInclusionNode.ts

@@ -606,11 +606,11 @@ export class ComponentInclusionNode extends QueryNode {
                     condition = result.sql;
                     // Note: custom builder is responsible for adding parameters via context.addParam()
                 } else {
-                    // Default filter logic
-                    // Validate filter value to prevent PostgreSQL UUID parsing errors
-                    if (filter.value === '' || (typeof filter.value === 'string' && filter.value.trim() === '')) {
-                        throw new Error(`Filter value for field "${filter.field}" is an empty string. This would cause PostgreSQL UUID parsing errors.`);
-                    }
+                    // Default filter logic. Empty-string values are permitted
+                    // here — `c.data->>'field'` extracts text, so `=`/`!=`/
+                    // `LIKE` against '' is legitimate. The UUID-cast path
+                    // below is gated on a regex that empty string cannot
+                    // match, so unsafe casts never fire.
 
                     // Check if value looks like a UUID (case-insensitive, with or without hyphens)
                     const valueStr = String(filter.value);