bunsane 0.2.10 → 0.3.1

package/core/Entity.ts

@@ -22,6 +22,70 @@ export class Entity implements IEntity {
     private savedRemovedComponents: Set<string> = new Set<string>();
     protected _dirty: boolean = false;
 
+    // Drainable set of fire-and-forget cache ops triggered from set/remove.
+    // App.shutdown can await these to avoid losing writes mid-shutdown
+    // (H-CACHE-1).
+    private static pendingCacheOps: Set<Promise<void>> = new Set();
+
+    // Drainable set of post-commit side-effect Promises scheduled via
+    // queueMicrotask from save(). Includes cache invalidation + lifecycle
+    // hooks (EntityCreated / EntityUpdated). Hooks may transitively trigger
+    // more DB work (e.g., entity.save() from a handler), which is why this
+    // is tracked separately from pendingCacheOps. Tests running against
+    // PGlite's single-connection pool should drain this between test files
+    // to prevent background work from prior files queueing behind the
+    // current file's save and masking visibility of recently-committed
+    // rows. See BUNSANE-001.
+    private static pendingSideEffects: Set<Promise<void>> = new Set();
+
+    /**
+     * Await all pending background cache operations. Call during shutdown
+     * after HTTP drain but before cache.disconnect so setImmediate'd cache
+     * writes are not lost. Bounded by `timeoutMs`.
+     */
+    public static async drainPendingCacheOps(timeoutMs: number = 5_000): Promise<void> {
+        if (Entity.pendingCacheOps.size === 0) return;
+        const snapshot = [...Entity.pendingCacheOps];
+        const drainTimer = new Promise<'timeout'>((resolve) => {
+            const t = setTimeout(() => resolve('timeout'), timeoutMs);
+            t.unref?.();
+        });
+        await Promise.race([
+            Promise.allSettled(snapshot).then(() => 'drained' as const),
+            drainTimer,
+        ]);
+    }
+
+    /**
+     * Await all pending post-commit side effects (cache invalidation +
+     * lifecycle hooks scheduled via queueMicrotask from save()). Call from
+     * test setup/teardown hooks under PGlite to guarantee prior-file
+     * background work has settled before the next file's saves run. Bounded
+     * by `timeoutMs`. Safe to call repeatedly; no-op when the set is empty.
+     */
+    public static async drainPendingSideEffects(timeoutMs: number = 5_000): Promise<void> {
+        if (Entity.pendingSideEffects.size === 0) return;
+        const snapshot = [...Entity.pendingSideEffects];
+        const drainTimer = new Promise<'timeout'>((resolve) => {
+            const t = setTimeout(() => resolve('timeout'), timeoutMs);
+            t.unref?.();
+        });
+        await Promise.race([
+            Promise.allSettled(snapshot).then(() => 'drained' as const),
+            drainTimer,
+        ]);
+    }
+
+    private static trackCacheOp(p: Promise<void>): void {
+        Entity.pendingCacheOps.add(p);
+        p.finally(() => Entity.pendingCacheOps.delete(p));
+    }
+
+    private static trackSideEffect(p: Promise<void>): void {
+        Entity.pendingSideEffects.add(p);
+        p.finally(() => Entity.pendingSideEffects.delete(p));
+    }
+
     constructor(id?: string) {
         // Use || instead of ?? to also handle empty strings
         this.id = (id && id.trim() !== '') ? id : uuidv7();
@@ -89,15 +153,18 @@ export class Entity implements IEntity {
             Object.assign(instance, {});
         }
         this.addComponent(instance);
-        this._dirty = true; 
-        // Fire component added event
-        try {
-            EntityHookManager.executeHooks(new ComponentAddedEvent(this, instance));
-        } catch (error) {
-            logger.error(`Error firing component added hook for ${instance.getTypeID()}: ${error}`);
-            // Don't fail the add operation if hooks fail
-        }
-        
+        this._dirty = true;
+        // executeHooks is async; the surrounding try/catch only captures
+        // synchronous throws. Attach a .catch so an async rejection from a
+        // hook handler does not escape as an unhandled rejection (H-HOOK-1).
+        // Add stays sync to preserve the fluent chaining signature; hook
+        // failures are logged and do not fail the add operation.
+        Promise.resolve()
+            .then(() => EntityHookManager.executeHooks(new ComponentAddedEvent(this, instance)))
+            .catch((error) => {
+                logger.error(`Error firing component added hook for ${instance.getTypeID()}: ${error}`);
+            });
+
         return this;
     }
 
@@ -120,9 +187,11 @@ export class Entity implements IEntity {
             component.setDirty(true);
             this._dirty = true;
             
-            // Fire component updated event
+            // Fire component updated event. Await so a hook rejection is
+            // captured by this method's try/catch and does not escape as an
+            // unhandled rejection (H-HOOK-1).
             try {
-                EntityHookManager.executeHooks(new ComponentUpdatedEvent(this, component, oldData, component));
+                await EntityHookManager.executeHooks(new ComponentUpdatedEvent(this, component, oldData, component));
             } catch (error) {
                 logger.error(`Error firing component updated hook for ${component.getTypeID()}: ${error}`);
                 // Don't fail the set operation if hooks fail
@@ -136,26 +205,25 @@ export class Entity implements IEntity {
                 });
             }
             
-            // Handle cache operations for component update
-            setImmediate(async () => {
+            // Fire-and-forget cache update, tracked via drainable set so
+            // App.shutdown can await it (H-CACHE-1).
+            Entity.trackCacheOp((async () => {
                 try {
                     const { CacheManager } = await import('./cache/CacheManager');
                     const cacheManager = CacheManager.getInstance();
                     const config = cacheManager.getConfig();
-                    
+
                     if (config.enabled && config.component?.enabled) {
                         if (config.strategy === 'write-through') {
-                            // Write-through: update cache with new component data
                             await cacheManager.setComponentWriteThrough(this.id, [component], component.getTypeID(), config.component.ttl);
                         } else {
-                            // Write-invalidate: remove from cache
                             await cacheManager.invalidateComponent(this.id, component.getTypeID());
                         }
                     }
                 } catch (error) {
-                    logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache operation failed after set', error });
+                    logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache operation failed after set', err: error });
                 }
-            });
+            })());
         } else {
             // Add new component
             this.add(ctor, data);
@@ -185,13 +253,14 @@ export class Entity implements IEntity {
             this.components.delete(typeId);
             this._dirty = true;
             
-            // Fire component removed event
-            try {
-                EntityHookManager.executeHooks(new ComponentRemovedEvent(this, component));
-            } catch (error) {
-                logger.error(`Error firing component removed hook for ${typeId}: ${error}`);
-                // Don't fail the remove operation if hooks fail
-            }
+            // Fire component removed event. remove() stays sync to preserve
+            // the boolean return signature used by callers; attach .catch so
+            // async hook rejections do not escape (H-HOOK-1).
+            Promise.resolve()
+                .then(() => EntityHookManager.executeHooks(new ComponentRemovedEvent(this, component)))
+                .catch((error) => {
+                    logger.error(`Error firing component removed hook for ${typeId}: ${error}`);
+                });
             
             // Invalidate DataLoader cache if context is provided
             if (context?.loaders?.componentsByEntityType) {
@@ -201,20 +270,21 @@ export class Entity implements IEntity {
                 });
             }
             
-            // Invalidate cache for removed component
-            setImmediate(async () => {
+            // Fire-and-forget cache invalidation, tracked for shutdown drain
+            // (H-CACHE-1).
+            Entity.trackCacheOp((async () => {
                 try {
                     const { CacheManager } = await import('./cache/CacheManager');
                     const cacheManager = CacheManager.getInstance();
                     const config = cacheManager.getConfig();
-                    
+
                     if (config.enabled && config.component?.enabled) {
                         await cacheManager.invalidateComponent(this.id, typeId);
                     }
                 } catch (error) {
-                    logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache invalidation failed after remove', error });
+                    logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache invalidation failed after remove', err: error });
                 }
-            });
+            })());
             
             return true;
         }
@@ -314,6 +384,81 @@ export class Entity implements IEntity {
         return this._loadComponent(ctor, context);
     }
 
+    /**
+     * Discard in-memory component state and re-hydrate from the database.
+     * Preserves entity identity — callers holding a reference see fresh data
+     * on the same instance. Use after a raw-SQL write that bypassed
+     * `entity.set`/`entity.save`, or when a different `Entity` instance with
+     * the same id mutated persisted data.
+     *
+     * @param opts Optional transaction
+     */
+    public async reload(opts?: { trx?: SQL }): Promise<this> {
+        if (!this.id || this.id.trim() === '') {
+            return this;
+        }
+        this.components.clear();
+        this.removedComponents.clear();
+        this.savedRemovedComponents.clear();
+
+        const dbConn = opts?.trx ?? db;
+        const rows = await dbConn`
+            SELECT c.id, c.type_id, c.data
+            FROM components c
+            WHERE c.entity_id = ${this.id} AND c.deleted_at IS NULL
+        `;
+
+        const storage = getMetadataStorage();
+        for (const row of rows) {
+            const ctor = ComponentRegistry.getConstructor(row.type_id);
+            if (!ctor) continue;
+            const comp: any = new ctor();
+            const parsed = typeof row.data === 'string' ? JSON.parse(row.data) : row.data;
+            Object.assign(comp, parsed);
+            comp.id = row.id;
+            const props = storage.componentProperties.get(row.type_id);
+            if (props) {
+                for (const prop of props) {
+                    if (prop.propertyType === Date && typeof comp[prop.propertyKey] === 'string') {
+                        comp[prop.propertyKey] = new Date(comp[prop.propertyKey]);
+                    }
+                }
+            }
+            comp.setPersisted(true);
+            comp.setDirty(false);
+            this.addComponent(comp);
+        }
+
+        this.setPersisted(true);
+        this.setDirty(false);
+        return this;
+    }
+
+    /**
+     * Ensure the given components are hydrated on this entity's in-memory
+     * componentList. No-op for components already loaded. Batched: one SQL
+     * call for all missing components.
+     *
+     * Required when a later `entity.set(...)` + `entity.save()` may trigger
+     * a `@ComponentTargetHook` whose `includeComponents` lists tag
+     * components. Hook matching reads `componentList()` (in-memory only), so
+     * tags must be loaded first for the hook to fire.
+     *
+     * @param ctors Component constructors to ensure are loaded
+     */
+    public async requireComponents(ctors: Array<new (...args: any[]) => BaseComponent>): Promise<void> {
+        if (ctors.length === 0) return;
+        const missing: string[] = [];
+        for (const ctor of ctors) {
+            const existing = Array.from(this.components.values()).find(c => c instanceof ctor);
+            if (existing) continue;
+            const typeId = new ctor().getTypeID();
+            missing.push(typeId);
+        }
+        if (missing.length === 0) return;
+        await Entity.LoadComponents([this], missing);
+    }
+
     private async _loadComponent<T extends BaseComponent>(ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }): Promise<T | null> {
         const comp = Array.from(this.components.values()).find(comp => comp instanceof ctor) as T | undefined;
         if (typeof comp !== "undefined") {
@@ -383,46 +528,122 @@ export class Entity implements IEntity {
     }
 
     @timed("Entity.save")
-    public save(trx?: SQL, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }) {
-        return new Promise<boolean>((resolve, reject) => {
-            // Add timeout to prevent hanging
-            const timeout = setTimeout(() => {
-                logger.error(`Entity save timeout for entity ${this.id}`);
-                reject(new Error(`Entity save timeout for entity ${this.id}`));
-            }, QUERY_TIMEOUT_MS); // Configurable timeout via DB_QUERY_TIMEOUT env var
-
-            // Capture dirty components BEFORE doSave clears the dirty flags
-            const changedComponentTypeIds = this.getDirtyComponents();
-            const removedComponentTypeIds = Array.from(this.removedComponents);
+    public async save(trx?: SQL, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL }): Promise<boolean> {
+        // Capture pre-save state BEFORE doSave mutates persisted/dirty flags.
+        const wasNew = !this._persisted;
+        const changedComponentTypeIds = this.getDirtyComponents();
+        const removedComponentTypeIds = Array.from(this.removedComponents);
+
+        // Pre-flight: await ComponentRegistry readiness for every component on
+        // this entity BEFORE opening the transaction. Previously doSave awaited
+        // ComponentRegistry.getReadyPromise inside the executeSave loop, so a
+        // slow DDL (partition creation) would keep the PG transaction open and
+        // idle-in-transaction waiting on registry state. (H-DB-4).
+        for (const comp of this.components.values()) {
+            const compName = comp.constructor.name;
+            if (!ComponentRegistry.isComponentReady(compName)) {
+                await ComponentRegistry.getReadyPromise(compName);
+            }
+        }
+
+        const profile = process.env.DB_SAVE_PROFILE === 'true';
+        const phaseStart = profile ? performance.now() : 0;
+        const phases: Record<string, number> = {};
+
+        // AbortController cancels in-flight queries and propagates ROLLBACK
+        // when the wall-clock timer fires. Throwing from inside the transaction
+        // callback triggers Bun SQL's auto-ROLLBACK, releasing the pooled connection.
+        const controller = new AbortController();
+        const timeoutMs = QUERY_TIMEOUT_MS;
+        const timeoutHandle = setTimeout(() => {
+            const err = new Error(`Entity save timeout for entity ${this.id} after ${timeoutMs}ms`);
+            logger.error({ scope: 'Entity.save', entityId: this.id, timeoutMs }, err.message);
+            controller.abort(err);
+        }, timeoutMs);
 
+        try {
+            const dbStart = profile ? performance.now() : 0;
             if (trx) {
-                // Use provided transaction
-                this.doSave(trx)
-                .then(async result => {
-                    clearTimeout(timeout);
-                    await this.handleCacheAfterSave(changedComponentTypeIds, removedComponentTypeIds, context);
-                    resolve(result);
-                })
-                .catch(error => {
-                    clearTimeout(timeout);
-                    reject(error);
-                });
+                await this.doSave(trx, controller.signal);
             } else {
-                // Create new transaction
-                db.transaction(async (newTrx) => {
-                    return await this.doSave(newTrx);
-                })
-                .then(async result => {
-                    clearTimeout(timeout);
-                    await this.handleCacheAfterSave(changedComponentTypeIds, removedComponentTypeIds, context);
-                    resolve(result);
-                })
-                .catch(error => {
-                    clearTimeout(timeout);
-                    reject(error);
+                await db.transaction(async (newTrx) => {
+                    await this.doSave(newTrx, controller.signal);
                 });
             }
-        });
+            if (profile) phases.db = performance.now() - dbStart;
+
+            clearTimeout(timeoutHandle);
+
+            // Post-commit side effects are fire-and-forget so Redis / hook
+            // latency cannot consume the save budget or block the caller.
+            // Tracked in pendingSideEffects so tests/shutdown can drain
+            // background work before asserting or tearing down.
+            const sideEffectPromise = new Promise<void>((resolve) => {
+                queueMicrotask(() => {
+                    this.runPostCommitSideEffects(
+                        wasNew,
+                        changedComponentTypeIds,
+                        removedComponentTypeIds,
+                        context,
+                        profile ? phases : undefined,
+                        profile ? phaseStart : undefined,
+                    ).finally(() => resolve());
+                });
+            });
+            Entity.trackSideEffect(sideEffectPromise);
+
+            return true;
+        } catch (error) {
+            clearTimeout(timeoutHandle);
+            if (controller.signal.aborted) {
+                throw controller.signal.reason ?? error;
+            }
+            throw error;
+        } finally {
+            // Ensure AbortController listeners are released even on success.
+            if (!controller.signal.aborted) controller.abort();
+        }
+    }
+
+    /**
+     * Fire-and-forget post-commit work: cache invalidation + lifecycle hooks.
+     * Runs outside the save budget. Errors are logged and swallowed so cache
+     * or hook failures never surface as save failures.
+     */
+    private async runPostCommitSideEffects(
+        wasNew: boolean,
+        changedComponentTypeIds: string[],
+        removedComponentTypeIds: string[],
+        context: { loaders?: { componentsByEntityType?: any }; trx?: SQL } | undefined,
+        phases: Record<string, number> | undefined,
+        phaseStart: number | undefined,
+    ): Promise<void> {
+        const profile = phases !== undefined && phaseStart !== undefined;
+
+        const cacheStart = profile ? performance.now() : 0;
+        try {
+            await this.handleCacheAfterSave(changedComponentTypeIds, removedComponentTypeIds, context);
+        } catch (err) {
+            logger.warn({ scope: 'cache', entityId: this.id, err }, 'post-commit cache invalidation failed');
+        }
+        if (profile) phases!.cache = performance.now() - cacheStart;
+
+        const hookStart = profile ? performance.now() : 0;
+        try {
+            if (wasNew) {
+                await EntityHookManager.executeHooks(new EntityCreatedEvent(this));
+            } else if (changedComponentTypeIds.length > 0) {
+                await EntityHookManager.executeHooks(new EntityUpdatedEvent(this, changedComponentTypeIds));
+            }
+        } catch (err) {
+            logger.error({ scope: 'hooks', entityId: this.id, err }, 'post-commit lifecycle hooks failed');
+        }
+        if (profile) phases!.hooks = performance.now() - hookStart;
+
+        if (profile) {
+            phases!.total = performance.now() - phaseStart!;
+            logger.info({ scope: 'Entity.save.profile', entityId: this.id, phases }, 'Entity.save phase timings');
+        }
     }
 
     /**
@@ -490,235 +711,283 @@ export class Entity implements IEntity {
         }
     }
 
-    public doSave(trx: SQL) {
-        return new Promise<boolean>(async (resolve, reject) => {
-            // Validate entity ID to prevent PostgreSQL UUID parsing errors
-            if (!this.id || this.id.trim() === '') {
-                logger.error(`Cannot save entity: id is empty or invalid`);
-                return reject(new Error(`Cannot save entity: id is empty or invalid`));
-            }
+    public async doSave(trx: SQL, signal?: AbortSignal): Promise<boolean> {
+        // Validate entity ID to prevent PostgreSQL UUID parsing errors
+        if (!this.id || this.id.trim() === '') {
+            logger.error(`Cannot save entity: id is empty or invalid`);
+            throw new Error(`Cannot save entity: id is empty or invalid`);
+        }
 
-            if(!this._dirty) {
-                let dirtyComponents: string[] = [];
-                try {
-                    dirtyComponents = this.getDirtyComponents();
-                } catch {
-                    // best-effort diagnostics only
-                }
+        if (!this._dirty) {
+            let dirtyComponents: string[] = [];
+            try {
+                dirtyComponents = this.getDirtyComponents();
+            } catch {
+                // best-effort diagnostics only
+            }
 
-                const removedTypeIds = Array.from(this.removedComponents);
-                const entityType = (this as any)?.constructor?.name ?? "Entity";
-                const dirtyComponentPreview = dirtyComponents.slice(0, 10).map((component) => {
-                    const anyComponent = component as any;
-                    return {
-                        type: anyComponent?.constructor?.name ?? "Component",
-                        typeId: typeof anyComponent?.getTypeID === "function" ? anyComponent.getTypeID() : undefined,
-                        id: anyComponent?.id,
-                        persisted: anyComponent?._persisted,
-                        dirty: anyComponent?._dirty,
-                    };
-                });
+            const removedTypeIds = Array.from(this.removedComponents);
+            const entityType = (this as any)?.constructor?.name ?? "Entity";
+            const dirtyComponentPreview = dirtyComponents.slice(0, 10).map((component) => {
+                const anyComponent = component as any;
+                return {
+                    type: anyComponent?.constructor?.name ?? "Component",
+                    typeId: typeof anyComponent?.getTypeID === "function" ? anyComponent.getTypeID() : undefined,
+                    id: anyComponent?.id,
+                    persisted: anyComponent?._persisted,
+                    dirty: anyComponent?._dirty,
+                };
+            });
 
-                logger.trace(
-                    {
-                        component: "Entity",
-                        entity: {
-                            type: entityType,
-                            id: this.id,
-                            persisted: this._persisted,
-                            dirty: this._dirty,
-                        },
-                        components: {
-                            total: this.components.size,
-                            dirtyCount: dirtyComponents.length,
-                            dirtyPreview: dirtyComponentPreview,
-                        },
-                        removedComponents: {
-                            count: removedTypeIds.length,
-                            typeIdsPreview: removedTypeIds.slice(0, 10),
-                        },
+            logger.trace(
+                {
+                    component: "Entity",
+                    entity: {
+                        type: entityType,
+                        id: this.id,
+                        persisted: this._persisted,
+                        dirty: this._dirty,
+                    },
+                    components: {
+                        total: this.components.size,
+                        dirtyCount: dirtyComponents.length,
+                        dirtyPreview: dirtyComponentPreview,
                     },
-                    "[Entity.doSave] Skipping save because entity is not dirty"
-                );
-                return resolve(true);
+                    removedComponents: {
+                        count: removedTypeIds.length,
+                        typeIdsPreview: removedTypeIds.slice(0, 10),
+                    },
+                },
+                "[Entity.doSave] Skipping save because entity is not dirty"
+            );
+            return true;
+        }
+
+        // Execute a Bun SQL query with AbortSignal support. On abort, the
+        // in-flight query is cancelled (SQL.Query.cancel()) which causes the
+        // transaction callback to throw, triggering Bun's automatic ROLLBACK
+        // and releasing the pooled backend connection. Without this, a wall-
+        // clock timeout leaks backends into `idle in transaction` state —
+        // fatal under pgbouncer transaction-mode pooling.
+        const run = async <T>(q: any): Promise<T> => {
+            if (!signal) return await q;
+            if (signal.aborted) {
+                try { q.cancel?.(); } catch { /* ignore */ }
+                throw signal.reason ?? new Error('Entity.save aborted');
+            }
+            const onAbort = () => { try { q.cancel?.(); } catch { /* ignore */ } };
+            signal.addEventListener('abort', onAbort, { once: true });
+            try {
+                return await q;
+            } finally {
+                signal.removeEventListener('abort', onAbort);
             }
+        };
 
-            const wasNew = !this._persisted;
-            const changedComponents = this.getDirtyComponents();
+        const executeSave = async (saveTrx: SQL) => {
+            if (!this._persisted) {
+                await run(saveTrx`INSERT INTO entities (id) VALUES (${this.id}) ON CONFLICT DO NOTHING`);
+                this._persisted = true;
+            }
 
-            const executeSave = async (saveTrx: SQL) => {
-                if(!this._persisted) {
-                    await saveTrx`INSERT INTO entities (id) VALUES (${this.id}) ON CONFLICT DO NOTHING`;
-                    this._persisted = true;
+            // Delete removed components from database
+            if (this.removedComponents.size > 0) {
+                const typeIds = Array.from(this.removedComponents);
+                await run(saveTrx`DELETE FROM components WHERE entity_id = ${this.id} AND type_id IN ${sql(typeIds)}`);
+                await run(saveTrx`DELETE FROM entity_components WHERE entity_id = ${this.id} AND type_id IN ${sql(typeIds)}`);
+                // Move to savedRemovedComponents so resolvers can still detect removed components
+                // This is needed because DataLoader may have stale cached data for this request
+                for (const typeId of typeIds) {
+                    this.savedRemovedComponents.add(typeId);
                 }
+                this.removedComponents.clear();
+            }
 
-                // Delete removed components from database
-                if (this.removedComponents.size > 0) {
-                    const typeIds = Array.from(this.removedComponents);
-                    await saveTrx`DELETE FROM components WHERE entity_id = ${this.id} AND type_id IN ${sql(typeIds)}`;
-                    await saveTrx`DELETE FROM entity_components WHERE entity_id = ${this.id} AND type_id IN ${sql(typeIds)}`;
-                    // Move to savedRemovedComponents so resolvers can still detect removed components
-                    // This is needed because DataLoader may have stale cached data for this request
-                    for (const typeId of typeIds) {
-                        this.savedRemovedComponents.add(typeId);
-                    }
-                    this.removedComponents.clear();
-                }
-                
-                if(this.components.size === 0) {
-                    logger.trace(`No components to save for entity ${this.id}`);
-                    return;
+            if (this.components.size === 0) {
+                logger.trace(`No components to save for entity ${this.id}`);
+                return;
+            }
+
+            // Batch inserts and updates for better performance
+            const componentsToInsert = [];
+            const entityComponentsToInsert = [];
+            const componentsToUpdate = [];
+
+            for (const comp of this.components.values()) {
+                const compName = comp.constructor.name;
+                // Registry readiness is pre-flighted in save() before the
+                // transaction starts (H-DB-4). This assert catches a
+                // theoretical race if a caller skipped save() and jumped
+                // straight to doSave — we refuse to await inside the txn so
+                // a slow DDL cannot hold a pg session idle in transaction.
+                if (!ComponentRegistry.isComponentReady(compName)) {
+                    throw new Error(`Component ${compName} not ready; call save() (not doSave) or await registry readiness before the transaction.`);
                 }
-                
-                // Batch inserts and updates for better performance
-                const componentsToInsert = [];
-                const entityComponentsToInsert = [];
-                const componentsToUpdate = [];
-                
-                for(const comp of this.components.values()) {
-                    const compName = comp.constructor.name;
-                    if (!ComponentRegistry.isComponentReady(compName)) {
-                        await ComponentRegistry.getReadyPromise(compName);
+
+                if (!(comp as any)._persisted) {
+                    if (comp.id === "") {
+                        comp.id = uuidv7();
                     }
-                    
-                    if(!(comp as any)._persisted) {
-                        if(comp.id === "") {
-                            comp.id = uuidv7();
-                        }
-                        componentsToInsert.push({
-                            id: comp.id,
-                            entity_id: this.id,
-                            name: compName,
-                            type_id: comp.getTypeID(),
-                            data: comp.serializableData()
-                        });
-                        entityComponentsToInsert.push({
+                    componentsToInsert.push({
+                        id: comp.id,
+                        entity_id: this.id,
+                        name: compName,
+                        type_id: comp.getTypeID(),
+                        data: comp.serializableData()
+                    });
+                    entityComponentsToInsert.push({
+                        entity_id: this.id,
+                        type_id: comp.getTypeID(),
+                        component_id: comp.id
+                    });
+                    (comp as any).setPersisted(true);
+                    (comp as any).setDirty(false);
+                } else if ((comp as any)._dirty) {
+                    componentsToUpdate.push({
+                        id: comp.id,
+                        data: comp.serializableData()
+                    });
+                    (comp as any).setDirty(false);
+                }
+            }
+
+            // Perform batch inserts
+            if (componentsToInsert.length > 0) {
+                await run(saveTrx`INSERT INTO components ${sql(componentsToInsert, 'id', 'entity_id', 'name', 'type_id', 'data')}`);
+                await run(saveTrx`INSERT INTO entity_components ${sql(entityComponentsToInsert, 'entity_id', 'type_id', 'component_id')} ON CONFLICT DO NOTHING`);
+            }
+
+            // Insert entity_components for existing components if entity is new
+            if (!this._persisted) {
+                const existingEntityComponents = [];
+                for (const comp of this.components.values()) {
+                    if ((comp as any)._persisted) {
+                        existingEntityComponents.push({
                             entity_id: this.id,
                             type_id: comp.getTypeID(),
                             component_id: comp.id
                         });
-                        (comp as any).setPersisted(true);
-                        (comp as any).setDirty(false);
-                    } else if((comp as any)._dirty) {
-                        componentsToUpdate.push({
-                            id: comp.id,
-                            data: comp.serializableData()
-                        });
-                        (comp as any).setDirty(false);
                     }
                 }
-                
-                // Perform batch inserts
-                if(componentsToInsert.length > 0) {
-                    await saveTrx`INSERT INTO components ${sql(componentsToInsert, 'id', 'entity_id', 'name', 'type_id', 'data')}`;
-                    await saveTrx`INSERT INTO entity_components ${sql(entityComponentsToInsert, 'entity_id', 'type_id', 'component_id')} ON CONFLICT DO NOTHING`;
-                }
-
-                // Insert entity_components for existing components if entity is new
-                if(!this._persisted) {
-                    const existingEntityComponents = [];
-                    for(const comp of this.components.values()) {
-                        if((comp as any)._persisted) {
-                            existingEntityComponents.push({
-                                entity_id: this.id,
-                                type_id: comp.getTypeID(),
-                                component_id: comp.id
-                            });
-                        }
-                    }
-                    if(existingEntityComponents.length > 0) {
-                        await saveTrx`INSERT INTO entity_components ${sql(existingEntityComponents, 'entity_id', 'type_id', 'component_id')} ON CONFLICT DO NOTHING`;
-                    }
+                if (existingEntityComponents.length > 0) {
+                    await run(saveTrx`INSERT INTO entity_components ${sql(existingEntityComponents, 'entity_id', 'type_id', 'component_id')} ON CONFLICT DO NOTHING`);
                 }
+            }
 
-                // Perform batch updates
-                if(componentsToUpdate.length > 0) {
-                    for(const comp of componentsToUpdate) {
-                        // Validate component ID to prevent PostgreSQL UUID parsing errors
-                        if (!comp.id || comp.id.trim() === '') {
-                            logger.error(`Cannot update component: id is empty or invalid. Component data: ${JSON.stringify(comp.data).substring(0, 200)}`);
-                            throw new Error(`Cannot update component: component id is empty or invalid`);
-                        }
-                        logger.trace({ componentId: comp.id, data: comp.data }, `[Entity.doSave] Updating component`);
-                        await saveTrx`UPDATE components SET data = ${comp.data} WHERE id = ${comp.id}`;
+            // Perform batch updates
+            if (componentsToUpdate.length > 0) {
+                for (const comp of componentsToUpdate) {
+                    // Validate component ID to prevent PostgreSQL UUID parsing errors
+                    if (!comp.id || comp.id.trim() === '') {
+                        logger.error(`Cannot update component: id is empty or invalid. Component data: ${JSON.stringify(comp.data).substring(0, 200)}`);
+                        throw new Error(`Cannot update component: component id is empty or invalid`);
                     }
+                    logger.trace({ componentId: comp.id, data: comp.data }, `[Entity.doSave] Updating component`);
+                    await run(saveTrx`UPDATE components SET data = ${comp.data} WHERE id = ${comp.id}`);
                 }
-            };
-
-            await executeSave(trx);
+            }
+        };
 
-            this._dirty = false;
+        await executeSave(trx);
 
-            // Fire lifecycle events after successful save
-            try {
-                if (wasNew) {
-                    await EntityHookManager.executeHooks(new EntityCreatedEvent(this));
-                } else if (changedComponents.length > 0) {
-                    await EntityHookManager.executeHooks(new EntityUpdatedEvent(this, changedComponents));
-                }
-            } catch (error) {
-                logger.error(`Error firing lifecycle hooks for entity ${this.id}: ${error}`);
-                // Don't fail the save operation if hooks fail
-            }
+        this._dirty = false;
 
-            resolve(true);
-        })
-        
+        return true;
     }
 
     public delete(force: boolean = false) {
         return EntityManager.deleteEntity(this, force);
     }
 
-    public doDelete(force: boolean = false) {
-        return new Promise<boolean>(async resolve => {
-            if(!this._persisted) {
-                logger.warn("Entity is not persisted, cannot delete.");
-                return resolve(false); 
+    public async doDelete(force: boolean = false): Promise<boolean> {
+        if (!this._persisted) {
+            logger.warn("Entity is not persisted, cannot delete.");
+            return false;
+        }
+
+        // AbortController cancels in-flight queries on wall-clock timeout so a
+        // hanging DELETE cannot leak backends into `idle in transaction` under
+        // pgbouncer transaction pool mode. Same pattern as Entity.save.
+        const controller = new AbortController();
+        const timeoutMs = QUERY_TIMEOUT_MS;
+        const timeoutHandle = setTimeout(() => {
+            const err = new Error(`Entity delete timeout for entity ${this.id} after ${timeoutMs}ms`);
+            logger.error({ scope: 'Entity.doDelete', entityId: this.id, timeoutMs }, err.message);
+            controller.abort(err);
+        }, timeoutMs);
+
+        const signal = controller.signal;
+        const run = async <T>(q: any): Promise<T> => {
+            if (signal.aborted) {
+                try { q.cancel?.(); } catch { /* ignore */ }
+                throw signal.reason ?? new Error('Entity.doDelete aborted');
             }
+            const onAbort = () => { try { q.cancel?.(); } catch { /* ignore */ } };
+            signal.addEventListener('abort', onAbort, { once: true });
             try {
-                await db.transaction(async (trx) => {
-                    if(force) {
-                        await trx`DELETE FROM entity_components WHERE entity_id = ${this.id}`;
-                        await trx`DELETE FROM components WHERE entity_id = ${this.id}`;
-                        await trx`DELETE FROM entities WHERE id = ${this.id}`;
-                    } else {
-                        await trx`UPDATE entities SET deleted_at = CURRENT_TIMESTAMP WHERE id = ${this.id} AND deleted_at IS NULL`;
-                        await trx`UPDATE entity_components SET deleted_at = CURRENT_TIMESTAMP WHERE entity_id = ${this.id} AND deleted_at IS NULL`;
-                        await trx`UPDATE components SET deleted_at = CURRENT_TIMESTAMP WHERE entity_id = ${this.id} AND deleted_at IS NULL`;
-                    }
-                });
+                return await q;
+            } finally {
+                signal.removeEventListener('abort', onAbort);
+            }
+        };
 
-                // Fire lifecycle event after successful deletion
-                try {
-                    await EntityHookManager.executeHooks(new EntityDeletedEvent(this, !force));
-                } catch (error) {
-                    logger.error(`Error firing delete lifecycle hook for entity ${this.id}: ${error}`);
-                    // Don't fail the delete operation if hooks fail
+        try {
+            await db.transaction(async (trx) => {
+                if (force) {
+                    await run(trx`DELETE FROM entity_components WHERE entity_id = ${this.id}`);
+                    await run(trx`DELETE FROM components WHERE entity_id = ${this.id}`);
+                    await run(trx`DELETE FROM entities WHERE id = ${this.id}`);
+                } else {
+                    await run(trx`UPDATE entities SET deleted_at = CURRENT_TIMESTAMP WHERE id = ${this.id} AND deleted_at IS NULL`);
+                    await run(trx`UPDATE entity_components SET deleted_at = CURRENT_TIMESTAMP WHERE entity_id = ${this.id} AND deleted_at IS NULL`);
+                    await run(trx`UPDATE components SET deleted_at = CURRENT_TIMESTAMP WHERE entity_id = ${this.id} AND deleted_at IS NULL`);
                 }
+            });
+            clearTimeout(timeoutHandle);
 
-                // Invalidate cache after successful deletion
-                try {
-                    const { CacheManager } = await import('./cache/CacheManager');
-                    const cacheManager = CacheManager.getInstance();
-                    const config = cacheManager.getConfig();
+            // Fire-and-forget post-commit side effects: lifecycle hooks + cache
+            // invalidation. Errors are logged, never propagate to caller.
+            queueMicrotask(() => this.runPostDeleteSideEffects(!force));
 
-                    if (config.enabled && config.entity?.enabled) {
-                        await cacheManager.invalidateEntity(this.id);
-                    }
-                    if (config.enabled && config.component?.enabled) {
-                        await cacheManager.invalidateAllEntityComponents(this.id);
-                    }
-                } catch (error) {
-                    logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache invalidation failed after delete', error });
-                }
+            return true;
+        } catch (error) {
+            clearTimeout(timeoutHandle);
+            if (signal.aborted) {
+                logger.error({ scope: 'Entity.doDelete', entityId: this.id }, `Entity delete aborted: ${signal.reason ?? error}`);
+            } else {
+                logger.error({ scope: 'Entity.doDelete', entityId: this.id, err: error }, 'Failed to delete entity');
+            }
+            // Re-throw so callers can distinguish DB failures (pool exhausted,
+            // lock timeout, etc.) from "entity not found" / not persisted,
+            // which still returns `false`. Previously any error produced the
+            // same `false` return, hiding infrastructure problems (H-OBS-4).
+            throw error instanceof Error ? error : new Error(String(error));
+        } finally {
+            if (!signal.aborted) controller.abort();
+        }
+    }
 
-                resolve(true);
-            } catch (error) {
-                logger.error(`Failed to delete entity: ${error}`);
-                resolve(false);
+    private async runPostDeleteSideEffects(softDelete: boolean): Promise<void> {
+        try {
+            await EntityHookManager.executeHooks(new EntityDeletedEvent(this, softDelete));
+        } catch (err) {
+            logger.error({ scope: 'hooks', entityId: this.id, err }, 'post-delete lifecycle hooks failed');
+        }
+
+        try {
+            const { CacheManager } = await import('./cache/CacheManager');
+            const cacheManager = CacheManager.getInstance();
+            const config = cacheManager.getConfig();
+
+            if (config.enabled && config.entity?.enabled) {
+                await cacheManager.invalidateEntity(this.id);
             }
-        })
+            if (config.enabled && config.component?.enabled) {
+                await cacheManager.invalidateAllEntityComponents(this.id);
+            }
+        } catch (err) {
+            logger.warn({ scope: 'cache', entityId: this.id, err }, 'post-delete cache invalidation failed');
+        }
     }
 
     public setPersisted(persisted: boolean) {