bunsane 0.3.1 → 0.3.2

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.1",
+    "version": "0.3.2",
     "author": {
         "name": "yaaruu"
     },

package/query/Query.ts

@@ -8,6 +8,7 @@ import { QueryContext, QueryDAG, SourceNode, ComponentInclusionNode } from "./in
 import { OrQuery } from "./OrQuery";
 import { OrNode } from "./OrNode";
 import { preparedStatementCache } from "../database/PreparedStatementCache";
+import { timedUnsafe, type PerRequestCounters } from "../database/instrumentedDb";
 import { getMetadataStorage } from "../core/metadata";
 import { shouldUseDirectPartition } from "../core/Config";
 import type { SQL } from "bun";
@@ -62,6 +63,21 @@ export interface QueryCacheOptions {
     component?: boolean;
 }
 
+/**
+ * Options accepted by Query terminal methods (`exec`, `count`, `sum`, etc.).
+ * - `signal` cancels in-flight DB queries via Bun's `Query.cancel()` when
+ *   fired. The request-scoped signal from `req.signal` is automatically
+ *   threaded into resolver-level Query instances by the framework's
+ *   GraphQL request context plugin; manual callers pass it explicitly.
+ * - `perRequest` is an opaque counter object incremented by the
+ *   instrumented DB layer so per-request stats (dbQueryCount,
+ *   dataLoaderCalls) are reported on access/timeout logs.
+ */
+export interface QueryExecOptions {
+    signal?: AbortSignal;
+    perRequest?: PerRequestCounters;
+}
+
 /**
  * New Query class that uses DAG internally for better modularity and extensibility.
  *
@@ -85,6 +101,8 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
     private trx: SQL | undefined;
     private skipPreparedCache: boolean = false;
     private skipComponentCache: boolean = false;
+    private execSignal?: AbortSignal;
+    private execPerRequest?: PerRequestCounters;
 
     /** Component constructors added to this query for type-safe access */
     private _componentCtors: ComponentConstructor[] = [];
@@ -110,12 +128,12 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
         return this;
     }
 
-    public async findOneById(id: string): Promise<TypedEntity<TComponents> | null> {
+    public async findOneById(id: string, opts?: QueryExecOptions): Promise<TypedEntity<TComponents> | null> {
         // Validate ID to prevent PostgreSQL UUID parsing errors
         if (!id || typeof id !== 'string' || id.trim() === '') {
             return null;
         }
-        const entities = await this.findById(id).exec();
+        const entities = await this.findById(id).exec(opts);
         return entities.length > 0 ? entities[0]! : null;
     }
 
@@ -300,7 +318,8 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
         return this;
     }
 
-    public count(): Promise<number> {
+    public count(opts?: QueryExecOptions): Promise<number> {
+        this.applyExecOptions(opts);
         return new Promise<number>((resolve, reject) => {
             const timeout = setTimeout(() => {
                 logger.error(`Query count execution timeout`);
@@ -318,6 +337,17 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
         });
     }
 
+    /**
+     * Apply terminal-method options to instance fields so internal helpers
+     * (doCount, doExec, populateComponents, doAggregate, …) can read them
+     * without threading parameters through every private method.
+     */
+    private applyExecOptions(opts?: QueryExecOptions): void {
+        if (!opts) return;
+        if (opts.signal !== undefined) this.execSignal = opts.signal;
+        if (opts.perRequest !== undefined) this.execPerRequest = opts.perRequest;
+    }
+
     /**
      * Get an estimated count using PostgreSQL statistics.
      * Much faster than exact count() for large tables - O(1) instead of O(n).
@@ -333,7 +363,8 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
      * const approxCount = await new Query().with(User).estimatedCount(User);
      * console.log(`Approximately ${approxCount} users`);
      */
-    public async estimatedCount(component: new (...args: any[]) => BaseComponent): Promise<number> {
+    public async estimatedCount(component: new (...args: any[]) => BaseComponent, opts?: QueryExecOptions): Promise<number> {
+        this.applyExecOptions(opts);
         const typeId = ComponentRegistry.getComponentId(component.name);
         if (!typeId) {
             throw new Error(`Component ${component.name} not registered`);
@@ -354,7 +385,7 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
             ? `SELECT reltuples::bigint AS estimate FROM pg_class WHERE relname = $1`
             : `SELECT reltuples::bigint AS estimate FROM pg_class WHERE relname = 'entity_components'`;
 
-        const result = await dbConn.unsafe(sql, [tableName || 'entity_components']);
+        const result = await timedUnsafe<any[]>(dbConn, sql, [tableName || 'entity_components'], this.execSignal, this.execPerRequest);
 
         if (!result || result.length === 0 || result[0].estimate === null) {
             // Fallback to exact count if statistics not available
@@ -410,13 +441,13 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
 
         if (this.skipPreparedCache) {
             // Bypass cache - execute directly
-            countResult = await dbConn.unsafe(countSql, result.params);
+            countResult = await timedUnsafe<any[]>(dbConn, countSql, result.params, this.execSignal, this.execPerRequest);
         } else {
             // Check prepared statement cache
             // Add 'count:' prefix to differentiate count queries from exec queries
             const cacheKey = 'count:' + this.context.generateCacheKey();
             const { statement, isHit } = await preparedStatementCache.getOrCreate(countSql, cacheKey, dbConn);
-            countResult = await preparedStatementCache.execute(statement, result.params, dbConn);
+            countResult = await preparedStatementCache.execute(statement, result.params, dbConn, this.execSignal, this.execPerRequest);
         }
 
         // Debug logging
@@ -603,11 +634,11 @@ AND c.deleted_at IS NULL`;
         let aggregateResult: any[];
 
         if (this.skipPreparedCache) {
-            aggregateResult = await dbConn.unsafe(aggregateSql, result.params);
+            aggregateResult = await timedUnsafe<any[]>(dbConn, aggregateSql, result.params, this.execSignal, this.execPerRequest);
         } else {
             const cacheKey = `${aggregateType.toLowerCase()}:${typeId}:${field}:` + this.context.generateCacheKey();
             const { statement } = await preparedStatementCache.getOrCreate(aggregateSql, cacheKey, dbConn);
-            aggregateResult = await preparedStatementCache.execute(statement, result.params, dbConn);
+            aggregateResult = await preparedStatementCache.execute(statement, result.params, dbConn, this.execSignal, this.execPerRequest);
         }
 
         // Debug logging
@@ -645,7 +676,8 @@ AND c.deleted_at IS NULL`;
      * @returns Promise resolving to array of TypedEntity with accumulated component types
      */
     @timed("Query.exec")
-    public async exec(): Promise<TypedEntity<TComponents>[]> {
+    public async exec(opts?: QueryExecOptions): Promise<TypedEntity<TComponents>[]> {
+        this.applyExecOptions(opts);
         // Apply default LIMIT so unbounded queries cannot load entire tables
         // into memory. Configurable via BUNSANE_DEFAULT_QUERY_LIMIT, 0 to
         // disable. When the default is applied without an explicit .take(),
@@ -806,12 +838,12 @@ AND c.deleted_at IS NULL`;
         if (this.orQuery || this.skipPreparedCache) {
             // For OR queries or explicit cache bypass, execute directly
             // This avoids potential parameter type inference issues with Bun's SQL
-            entities = await dbConn.unsafe(result.sql, result.params);
+            entities = await timedUnsafe<any[]>(dbConn, result.sql, result.params, this.execSignal, this.execPerRequest);
         } else {
             // Check prepared statement cache for regular queries
             const cacheKey = this.context.generateCacheKey();
             const { statement, isHit } = await preparedStatementCache.getOrCreate(result.sql, cacheKey, dbConn);
-            entities = await preparedStatementCache.execute(statement, result.params, dbConn);
+            entities = await preparedStatementCache.execute(statement, result.params, dbConn, this.execSignal, this.execPerRequest);
         }
 
         // Convert to Entity objects
@@ -871,32 +903,32 @@ AND c.deleted_at IS NULL`;
             // Single component type - use direct partition if available
             const partitionTableName = ComponentRegistry.getPartitionTableName(componentTypeIds[0]!);
             if (partitionTableName) {
-                components = await dbConn.unsafe(`
+                components = await timedUnsafe<any[]>(dbConn, `
                     SELECT id, entity_id, type_id, data
                     FROM ${partitionTableName}
                     WHERE entity_id IN ${entityIdList.sql}
                     AND type_id IN ${typeIdList.sql}
                     AND deleted_at IS NULL
-                `, [...entityIdList.params, ...typeIdList.params]);
+                `, [...entityIdList.params, ...typeIdList.params], this.execSignal, this.execPerRequest);
             } else {
                 // Fallback to parent table
-                components = await dbConn.unsafe(`
+                components = await timedUnsafe<any[]>(dbConn, `
                     SELECT id, entity_id, type_id, data
                     FROM components
                     WHERE entity_id IN ${entityIdList.sql}
                     AND type_id IN ${typeIdList.sql}
                     AND deleted_at IS NULL
-                `, [...entityIdList.params, ...typeIdList.params]);
+                `, [...entityIdList.params, ...typeIdList.params], this.execSignal, this.execPerRequest);
             }
         } else {
             // Multiple types or direct partition disabled - use parent table
-            components = await dbConn.unsafe(`
+            components = await timedUnsafe<any[]>(dbConn, `
                 SELECT id, entity_id, type_id, data
                 FROM components
                 WHERE entity_id IN ${entityIdList.sql}
                 AND type_id IN ${typeIdList.sql}
                 AND deleted_at IS NULL
-            `, [...entityIdList.params, ...typeIdList.params]);
+            `, [...entityIdList.params, ...typeIdList.params], this.execSignal, this.execPerRequest);
         }
 
         // Get metadata storage for Date deserialization
@@ -945,7 +977,8 @@ AND c.deleted_at IS NULL`;
      * Execute query with EXPLAIN ANALYZE for performance debugging
      * Returns the query plan and execution statistics
      */
-    public async explainAnalyze(buffers: boolean = true): Promise<string> {
+    public async explainAnalyze(buffers: boolean = true, opts?: QueryExecOptions): Promise<string> {
+        this.applyExecOptions(opts);
         // Reset context for fresh execution
         this.context.reset();
 
@@ -993,7 +1026,7 @@ AND c.deleted_at IS NULL`;
         }
 
         // Execute the EXPLAIN ANALYZE query
-        const explainResult = await dbConn.unsafe(explainSql, result.params);
+        const explainResult = await timedUnsafe<any[]>(dbConn, explainSql, result.params, this.execSignal, this.execPerRequest);
 
         // Format the result
         return explainResult.map((row: any) => row['QUERY PLAN']).join('\n');

package/tests/integration/loaders/RequestLoaders.abort.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Integration tests for `createRequestLoaders` AbortSignal threading.
+ *
+ * The GraphQL request plugin (core/RequestContext.ts) wires the request's
+ * AbortSignal into each DataLoader's `db.unsafe()` call via timedUnsafe.
+ * On abort the in-flight query is cancelled, releasing the backend
+ * connection back to pgbouncer.
+ */
+import { describe, test, expect, beforeAll, beforeEach } from 'bun:test';
+import db from '../../../database';
+import { Entity } from '../../../core/Entity';
+import { createRequestLoaders } from '../../../core/RequestLoaders';
+import { ComponentRegistry } from '../../../core/components';
+import { TestUser } from '../../fixtures/components';
+import { createTestContext, ensureComponentsRegistered } from '../../utils';
+
+describe('RequestLoaders AbortSignal', () => {
+    const ctx = createTestContext();
+    let seededEntity: Entity;
+    let testUserTypeId: string;
+
+    beforeAll(async () => {
+        await ensureComponentsRegistered(TestUser);
+        testUserTypeId = ComponentRegistry.getComponentId('TestUser')!;
+        expect(testUserTypeId).toBeTruthy();
+    });
+
+    beforeEach(async () => {
+        // Fresh seed per test — createTestContext's afterEach cleans tracked
+        // entities, so seeds set up once would disappear after the first
+        // test in the suite runs.
+        seededEntity = ctx.tracker.create();
+        seededEntity.add(TestUser, { name: 'loader-seed', email: 'l@e.com', age: 1 });
+        await seededEntity.save();
+        await Entity.drainPendingSideEffects();
+    });
+
+    test('entityById loader rejects when pre-aborted', async () => {
+        const controller = new AbortController();
+        controller.abort(new Error('pre-aborted'));
+
+        const loaders = createRequestLoaders(db, undefined, controller.signal);
+        await expect(loaders.entityById.load(seededEntity.id)).rejects.toBeDefined();
+    });
+
+    test('componentsByEntityType loader rejects when pre-aborted', async () => {
+        const controller = new AbortController();
+        controller.abort(new Error('pre-aborted'));
+
+        const loaders = createRequestLoaders(db, undefined, controller.signal);
+        await expect(
+            loaders.componentsByEntityType.load({
+                entityId: seededEntity.id,
+                typeId: testUserTypeId,
+            }),
+        ).rejects.toBeDefined();
+    });
+
+    test('loaders without signal still work (backwards compatible)', async () => {
+        const loaders = createRequestLoaders(db);
+        const ent = await loaders.entityById.load(seededEntity.id);
+        expect(ent?.id).toBe(seededEntity.id);
+    });
+
+    test('perRequest counters track DataLoader invocations', async () => {
+        const perRequest = {
+            dbQueryCount: 0,
+            dataLoaderCalls: { entity: 0, component: 0, relation: 0 },
+        };
+        const loaders = createRequestLoaders(db, undefined, undefined, perRequest);
+
+        await loaders.entityById.load(seededEntity.id);
+        await loaders.componentsByEntityType.load({
+            entityId: seededEntity.id,
+            typeId: testUserTypeId,
+        });
+
+        expect(perRequest.dataLoaderCalls.entity).toBeGreaterThanOrEqual(1);
+        expect(perRequest.dataLoaderCalls.component).toBeGreaterThanOrEqual(1);
+        expect(perRequest.dbQueryCount).toBeGreaterThan(0);
+    });
+});

package/tests/integration/query/Query.abort.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Integration tests for Query.exec / Query.count AbortSignal propagation.
+ *
+ * The framework wall-clock timeout (core/app/requestRouter.ts) aborts a
+ * controller on 30s. The plugin in core/RequestContext.ts threads the
+ * request's AbortSignal into Query.exec via `{ signal }` options. These
+ * tests prove the abort actually cancels the underlying Bun SQL query
+ * (releasing the pgbouncer-backed connection) rather than just rejecting
+ * the outer promise.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Query } from '../../../query/Query';
+import { TestUser } from '../../fixtures/components';
+import { createTestContext, ensureComponentsRegistered } from '../../utils';
+
+describe('Query AbortSignal propagation', () => {
+    const ctx = createTestContext();
+
+    beforeAll(async () => {
+        await ensureComponentsRegistered(TestUser);
+
+        // Seed a small dataset so queries actually hit the DB.
+        for (let i = 0; i < 5; i++) {
+            const e = ctx.tracker.create();
+            e.add(TestUser, { name: `abort-seed-${i}`, email: `a${i}@e.com`, age: i });
+            await e.save();
+        }
+    });
+
+    test('exec() with pre-aborted signal rejects without running query', async () => {
+        const controller = new AbortController();
+        controller.abort(new Error('pre-aborted'));
+
+        const promise = new Query().with(TestUser).exec({ signal: controller.signal });
+        await expect(promise).rejects.toBeDefined();
+    });
+
+    test('exec() rejects when signal aborts mid-flight', async () => {
+        const controller = new AbortController();
+        queueMicrotask(() => controller.abort(new Error('mid-flight')));
+
+        const promise = new Query().with(TestUser).exec({ signal: controller.signal });
+        await expect(promise).rejects.toBeDefined();
+    });
+
+    test('exec() without signal still works (backwards compatible)', async () => {
+        const rows = await new Query().with(TestUser).take(5).exec();
+        expect(Array.isArray(rows)).toBe(true);
+    });
+
+    test('count() respects signal abort', async () => {
+        const controller = new AbortController();
+        controller.abort(new Error('pre-aborted'));
+
+        const promise = new Query().with(TestUser).count({ signal: controller.signal });
+        await expect(promise).rejects.toBeDefined();
+    });
+
+    test('perRequest counters increment when supplied', async () => {
+        const perRequest = { dbQueryCount: 0 };
+        await new Query().with(TestUser).take(5).exec({ perRequest });
+        // Exec performs at least one DB query (count guard / select). Real
+        // count depends on prepared-cache state; assert non-zero only.
+        expect(perRequest.dbQueryCount).toBeGreaterThan(0);
+    });
+});