bunsane 0.3.0 → 0.3.2

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
@@ -430,14 +461,11 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
             console.log('---');
         }
 
-        // Validate params before execution to catch UUID errors early
-        for (let i = 0; i < result.params.length; i++) {
-            const param = result.params[i];
-            if (param === '' || (typeof param === 'string' && param.trim() === '')) {
-                logger.error(`Empty string parameter detected at position ${i + 1} in count query`);
-                throw new Error(`Query count parameter $${i + 1} is an empty string. This will cause PostgreSQL UUID parsing errors.`);
-            }
-        }
+        // Empty-string params are legitimate for text-field filters
+        // (`c.data->>'field' = ''`). UUID-typed params never reach this
+        // point empty — findById guards at entry; cursor/excluded IDs come
+        // from saved entities. PG emits a clear error if a UUID cast meets
+        // an empty string at execution time.
 
         // Safely extract count from result - handle undefined/null cases
         if (!countResult || countResult.length === 0 || countResult[0] === undefined) {
@@ -606,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
@@ -623,14 +651,8 @@ AND c.deleted_at IS NULL`;
             console.log('---');
         }
 
-        // Validate params
-        for (let i = 0; i < result.params.length; i++) {
-            const param = result.params[i];
-            if (param === '' || (typeof param === 'string' && param.trim() === '')) {
-                logger.error(`Empty string parameter detected at position ${i + 1} in ${aggregateType} query`);
-                throw new Error(`Query ${aggregateType} parameter $${i + 1} is an empty string.`);
-            }
-        }
+        // Empty-string params are legitimate for text-field filters; see
+        // comment above in doCount.
 
         // Extract result
         if (!aggregateResult || aggregateResult.length === 0 || aggregateResult[0] === undefined) {
@@ -654,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(),
@@ -794,14 +817,11 @@ AND c.deleted_at IS NULL`;
             console.log('---');
         }
 
-        // Validate params before execution to catch UUID errors early
-        for (let i = 0; i < result.params.length; i++) {
-            const param = result.params[i];
-            if (param === '' || (typeof param === 'string' && param.trim() === '')) {
-                logger.error(`Empty string parameter detected at position ${i + 1}: SQL=${result.sql.substring(0, 200)}`);
-                throw new Error(`Query parameter $${i + 1} is an empty string. This will cause PostgreSQL UUID parsing errors. SQL: ${result.sql.substring(0, 100)}...`);
-            }
-        }
+        // Empty-string params are legitimate for text-field filters
+        // (`c.data->>'field' = ''`). UUID-typed params never reach this
+        // point empty — findById guards at entry; cursor/excluded IDs
+        // originate from saved entities. PG emits a clear error at
+        // execution time if a UUID cast meets an empty string.
 
         // Validate parameters before execution
         for (let i = 0; i < result.params.length; i++) {
@@ -818,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
@@ -883,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
@@ -957,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();
 
@@ -1005,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');
@@ -1021,10 +1042,6 @@ AND c.deleted_at IS NULL`;
     static filterOp = FilterOp;
 
     public static filter(field: string, operator: FilterOperator, value: any): QueryFilter {
-        // Validate value to catch empty strings early
-        if (value === '' || (typeof value === 'string' && value.trim() === '')) {
-            throw new Error(`Query.filter: Cannot create filter for field "${field}" with empty string value. This would cause PostgreSQL UUID parsing errors.`);
-        }
         return { field, operator, value };
     }
 

package/service/ServiceRegistry.ts

@@ -3,7 +3,13 @@ import ApplicationLifecycle, {ApplicationPhase, type PhaseChangeEvent} from "../
 import { generateGraphQLSchemaV2 } from "../gql";
 import { GraphQLSchema } from "graphql";
 
-class ServiceRegistry {
+/**
+ * ServiceRegistry is a singleton. The default export and the re-exported
+ * named `ServiceRegistry` from `service/index.ts` both resolve to the
+ * singleton instance (for backward compatibility). When you need the class
+ * itself (for typing or subclassing), import `ServiceRegistryClass`.
+ */
+export class ServiceRegistry {
     static #instance: ServiceRegistry;
 
     private services: Map<string, BaseService> = new Map();

package/service/index.ts

@@ -1,10 +1,12 @@
 import BaseService from "./Service";
-import  ServiceRegistry  from "./ServiceRegistry";
+import ServiceRegistry from "./ServiceRegistry";
+import { ServiceRegistry as ServiceRegistryClass } from "./ServiceRegistry";
 import { httpEndpoint } from "../rest";
 
 export {
     BaseService,
-    ServiceRegistry
+    ServiceRegistry,
+    ServiceRegistryClass,
 }
 
 // Shorthand decorators for HTTP methods

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);
+    });
+});

package/tests/unit/cache/CacheManager.test.ts

@@ -3,7 +3,7 @@
  * Tests cache configuration and management
  */
 import { describe, test, expect, beforeEach, afterEach, mock } from 'bun:test';
-import { CacheManager } from '../../../core/cache/CacheManager';
+import { CacheManager, COMPONENT_TOMBSTONE } from '../../../core/cache/CacheManager';
 import { MemoryCache } from '../../../core/cache/MemoryCache';
 import { MultiLevelCache } from '../../../core/cache/MultiLevelCache';
 
@@ -141,6 +141,26 @@ describe('CacheManager', () => {
             expect(result).toBeNull();
         });
 
+        test('invalidateEntities clears entity + all component caches for a batch', async () => {
+            const provider = cacheManager.getProvider();
+            // Two entities, each with cached entity entry + one component
+            await provider.set('entity:e1', 'e1', 3600000);
+            await provider.set('entity:e2', 'e2', 3600000);
+            await provider.set('component:e1:t1', { data: 'a' }, 3600000);
+            await provider.set('component:e2:t1', { data: 'b' }, 3600000);
+
+            await cacheManager.invalidateEntities(['e1', 'e2']);
+
+            expect(await cacheManager.getEntity('e1')).toBeNull();
+            expect(await cacheManager.getEntity('e2')).toBeNull();
+            expect(await cacheManager.getComponentsByEntity('e1', 't1')).toBeNull();
+            expect(await cacheManager.getComponentsByEntity('e2', 't1')).toBeNull();
+        });
+
+        test('invalidateEntities is a noop for empty list', async () => {
+            await expect(cacheManager.invalidateEntities([])).resolves.toBeUndefined();
+        });
+
         test('getEntities returns null for missing entities', async () => {
             const results = await cacheManager.getEntities(['id1', 'id2', 'id3']);
             expect(results.length).toBe(3);
@@ -190,6 +210,137 @@ describe('CacheManager', () => {
         });
     });
 
+    describe('component negative cache (tombstones)', () => {
+        beforeEach(async () => {
+            await cacheManager.initialize({
+                enabled: true,
+                provider: 'memory',
+                strategy: 'write-through',
+                defaultTTL: 3600000,
+                entity: { enabled: true, ttl: 3600000 },
+                component: {
+                    enabled: true,
+                    ttl: 1800000,
+                    negativeCacheEnabled: true,
+                    negativeCacheTtl: 60_000,
+                },
+                query: { enabled: false, ttl: 300000, maxSize: 10000 },
+            });
+        });
+
+        test('setComponentsWriteThrough writes tombstones for absent requested keys', async () => {
+            const requested = [
+                { entityId: 'e1', typeId: 't1' },
+                { entityId: 'e2', typeId: 't2' },
+            ];
+            await cacheManager.setComponentsWriteThrough([], requested);
+            const results = await cacheManager.getComponents(requested);
+            expect(results[0]).toBe(COMPONENT_TOMBSTONE);
+            expect(results[1]).toBe(COMPONENT_TOMBSTONE);
+        });
+
+        test('found rows are written, absent are tombstoned, single setMany', async () => {
+            const requested = [
+                { entityId: 'e1', typeId: 't1' },
+                { entityId: 'e2', typeId: 't2' },
+            ];
+            const found = [{
+                id: 'c1', entityId: 'e1', typeId: 't1',
+                data: { x: 1 }, createdAt: new Date(), updatedAt: new Date(), deletedAt: null,
+            }];
+            await cacheManager.setComponentsWriteThrough(found, requested);
+            const results = await cacheManager.getComponents(requested);
+            expect((results[0] as any)?.id).toBe('c1');
+            expect(results[1]).toBe(COMPONENT_TOMBSTONE);
+        });
+
+        test('invalidateComponent drops tombstone', async () => {
+            await cacheManager.setComponentsWriteThrough([], [{ entityId: 'e1', typeId: 't1' }]);
+            await cacheManager.invalidateComponent('e1', 't1');
+            const results = await cacheManager.getComponents([{ entityId: 'e1', typeId: 't1' }]);
+            expect(results[0]).toBeNull();
+        });
+
+        test('negativeCacheEnabled=false skips tombstone writes (backward compat)', async () => {
+            await cacheManager.initialize({
+                enabled: true,
+                provider: 'memory',
+                strategy: 'write-through',
+                defaultTTL: 3600000,
+                entity: { enabled: true, ttl: 3600000 },
+                component: { enabled: true, ttl: 1800000 },
+                query: { enabled: false, ttl: 300000, maxSize: 10000 },
+            });
+            await cacheManager.setComponentsWriteThrough([], [{ entityId: 'e1', typeId: 't1' }]);
+            const results = await cacheManager.getComponents([{ entityId: 'e1', typeId: 't1' }]);
+            expect(results[0]).toBeNull();
+        });
+
+        test('legacy 2-arg signature (components, ttl) still works', async () => {
+            const data = [{
+                id: 'c1', entityId: 'e1', typeId: 't1',
+                data: { x: 1 }, createdAt: new Date(), updatedAt: new Date(), deletedAt: null,
+            }];
+            await cacheManager.setComponentsWriteThrough(data, 3600_000);
+            const results = await cacheManager.getComponents([{ entityId: 'e1', typeId: 't1' }]);
+            expect((results[0] as any)?.id).toBe('c1');
+        });
+    });
+
+    describe('relation negative cache', () => {
+        beforeEach(async () => {
+            await cacheManager.initialize({
+                enabled: true,
+                provider: 'memory',
+                strategy: 'write-through',
+                defaultTTL: 3600000,
+                entity: { enabled: true, ttl: 3600000 },
+                component: { enabled: true, ttl: 1800000 },
+                relation: { negativeCacheEnabled: true, negativeCacheTtl: 60_000 },
+                query: { enabled: false, ttl: 300000, maxSize: 10000 },
+            });
+        });
+
+        test('setRelationsEmpty + getRelationsEmpty round trip', async () => {
+            const keys = [
+                { entityId: 'u1', relationField: 'orders', relatedType: 'Order', foreignKey: 'user_id' },
+                { entityId: 'u2', relationField: 'orders', relatedType: 'Order', foreignKey: 'user_id' },
+            ];
+            await cacheManager.setRelationsEmpty(keys);
+            const flags = await cacheManager.getRelationsEmpty(keys);
+            expect(flags).toEqual([true, true]);
+        });
+
+        test('getRelationsEmpty returns false for keys never tombstoned', async () => {
+            const flags = await cacheManager.getRelationsEmpty([
+                { entityId: 'u-fresh', relationField: 'orders', relatedType: 'Order', foreignKey: 'user_id' },
+            ]);
+            expect(flags).toEqual([false]);
+        });
+
+        test('invalidateRelation drops tombstone', async () => {
+            const key = { entityId: 'u1', relationField: 'orders', relatedType: 'Order', foreignKey: 'user_id' };
+            await cacheManager.setRelationsEmpty([key]);
+            await cacheManager.invalidateRelation(key.entityId, key.relationField, key.relatedType, key.foreignKey);
+            const flags = await cacheManager.getRelationsEmpty([key]);
+            expect(flags).toEqual([false]);
+        });
+
+        test('relation cache disabled returns all-false (no-op)', async () => {
+            await cacheManager.initialize({
+                enabled: true,
+                provider: 'memory',
+                strategy: 'write-through',
+                defaultTTL: 3600000,
+                relation: { negativeCacheEnabled: false },
+            });
+            const key = { entityId: 'u1', relationField: 'orders', relatedType: 'Order', foreignKey: 'user_id' };
+            await cacheManager.setRelationsEmpty([key]);
+            const flags = await cacheManager.getRelationsEmpty([key]);
+            expect(flags).toEqual([false]);
+        });
+    });
+
     describe('cache disabled', () => {
         beforeEach(async () => {
             await cacheManager.initialize({ enabled: false });