bunsane 0.3.2 → 0.5.0

package/core/entity/finders.ts

@@ -0,0 +1,202 @@
+// Entity loaders, clone/ref factories, and (de)serialization. Extracted
+// from Entity.ts (RFC_REFACTOR_TARGETS §3.2). Functions take/return the
+// Entity instance; the Entity class is imported lazily where construction
+// is needed to avoid a module-eval cycle.
+import { logger } from "../Logger";
+import db from "../../database";
+import ComponentRegistry from "../components/ComponentRegistry";
+import { uuidv7 } from "../../utils/uuid";
+import { sql, SQL } from "bun";
+import { getMetadataStorage } from "../metadata";
+import { addComponent } from "./componentAccess";
+// Value import: the Entity class is only referenced inside function bodies
+// (called at runtime, after module init), so the ESM cycle with Entity.ts
+// resolves via live bindings without a load-order hazard.
+import { Entity } from "../Entity";
+
+export async function loadMultiple(ids: string[]): Promise<Entity[]> {
+    if (ids.length === 0) return [];
+
+    // Filter out empty/invalid IDs to prevent PostgreSQL UUID parsing errors
+    const validIds = ids.filter(id => id && id.trim() !== '');
+    if (validIds.length === 0) return [];
+    if (validIds.length !== ids.length) {
+        logger.warn(`LoadMultiple: Filtered out ${ids.length - validIds.length} invalid entity IDs`);
+    }
+
+    const components = await db`
+        SELECT c.id, c.entity_id, c.type_id, c.data
+        FROM components c
+        WHERE c.entity_id IN ${sql(validIds)} AND c.deleted_at IS NULL
+    `;
+
+    const entitiesMap = new Map<string, Entity>();
+
+    for (const id of validIds) {
+        const entity = new Entity();
+        entity.id = id;
+        entity.setPersisted(true);
+        entity.setDirty(false);
+        entitiesMap.set(id, entity);
+    }
+
+    for (const row of components) {
+        const { id, entity_id, type_id, data } = row;
+        const ctor = ComponentRegistry.getConstructor(type_id);
+        if (ctor) {
+            const comp = new ctor();
+            const componentData = typeof data === 'string' ? JSON.parse(data) : data;
+            Object.assign(comp, componentData);
+            comp.id = id;
+            comp.setPersisted(true);
+            comp.setDirty(false);
+            const target = entitiesMap.get(entity_id);
+            if (target) addComponent(target, comp);
+        }
+    }
+
+    return Array.from(entitiesMap.values());
+}
+
+export async function loadComponents(entities: Entity[], componentIds: string[], skipCache: boolean = false): Promise<void> {
+    if (entities.length === 0 || componentIds.length === 0) return;
+
+    // Filter out entities with empty/invalid IDs to prevent PostgreSQL UUID parsing errors
+    const validEntities = entities.filter(e => e.id && e.id.trim() !== '');
+    if (validEntities.length === 0) return;
+
+    const entityIds = validEntities.map(e => e.id);
+
+    const components = await db`
+        SELECT c.id, c.entity_id, c.type_id, c.data
+        FROM components c
+        WHERE c.entity_id IN ${sql(entityIds)} AND c.type_id IN ${sql(componentIds)} AND c.deleted_at IS NULL
+    `;
+
+    // Use Map for O(1) lookups instead of O(n) find() - fixes O(n²) performance issue
+    const entityMap = new Map<string, Entity>(validEntities.map(e => [e.id, e]));
+
+    for (const row of components) {
+        const { id, entity_id, type_id, data } = row;
+        const entity = entityMap.get(entity_id);  // O(1) instead of O(n)
+        if (entity) {
+            const ctor = ComponentRegistry.getConstructor(type_id);
+            if (ctor) {
+                const comp = new ctor();
+                const componentData = typeof data === 'string' ? JSON.parse(data) : data;
+                Object.assign(comp, componentData);
+                comp.id = id;
+                comp.setPersisted(true);
+                comp.setDirty(false);
+                addComponent(entity, comp);
+            }
+        }
+    }
+}
+
+/**
+ * Find an entity by its ID. Returning populated with all components. Or null if not found.
+ */
+export async function findById(id: string, trx?: SQL): Promise<Entity | null> {
+    // Validate ID to prevent PostgreSQL UUID parsing errors
+    if (!id || typeof id !== 'string' || id.trim() === '') {
+        logger.warn(`FindById called with invalid id: "${id}"`);
+        return null;
+    }
+    const { Query } = await import("../../query/Query");
+    const entities = await new Query(trx).findById(id).populate().exec()
+    if (entities.length === 1) {
+        return entities[0]!;
+    }
+    return null;
+}
+
+export function clone(entity: Entity): Entity {
+    const clone = new Entity();
+    clone.setDirty(true);
+    clone.setPersisted(false);
+    for (const comp of entity.components.values()) {
+        const newComp = new (comp.constructor as any)();
+        Object.assign(newComp, comp.data());
+        newComp.id = uuidv7();
+        newComp.setDirty(true);
+        newComp.setPersisted(false);
+        addComponent(clone, newComp);
+    }
+    return clone;
+}
+
+export function makeRef(entity: Entity): Entity {
+    const ref = new Entity();
+    ref.setDirty(true);
+    ref.setPersisted(false);
+    for (const comp of entity.components.values()) {
+        const refComp = comp;
+        refComp.setDirty(false);
+        refComp.setPersisted(true);
+        addComponent(ref, refComp);
+    }
+    return ref;
+}
+
+/**
+ * Serialize the entity with only the currently loaded components
+ */
+export function serialize(entity: Entity): { id: string; components: Record<string, any> } {
+    const components: Record<string, any> = {};
+    for (const comp of entity.components.values()) {
+        components[comp.constructor.name] = comp.serializableData();
+    }
+    return {
+        id: entity.id,
+        components
+    };
+}
+
+/**
+ * Deserialize/reconstitute an Entity from cached/serialized data.
+ */
+export function deserialize(data: any): Entity {
+    if (data instanceof Entity) {
+        return data;
+    }
+
+    const entity = new Entity(data.id);
+    entity.setPersisted(true);
+    entity.setDirty(false);
+
+    // Handle serialized format: { id, components: { ComponentName: {...data} } }
+    if (data.components && typeof data.components === 'object') {
+        const storage = getMetadataStorage();
+
+        for (const [componentName, componentData] of Object.entries(data.components)) {
+            // Find the component constructor by name
+            const ComponentCtor = ComponentRegistry.getConstructorByName(componentName);
+            if (!ComponentCtor) {
+                logger.warn(`Cannot deserialize component: constructor not found for ${componentName}`);
+                continue;
+            }
+
+            const comp = new ComponentCtor();
+            const parsedData = typeof componentData === 'string' ? JSON.parse(componentData) : componentData;
+            Object.assign(comp, parsedData);
+
+            // Restore Date objects
+            const typeId = comp.getTypeID();
+            const props = storage.componentProperties.get(typeId);
+            if (props) {
+                for (const prop of props) {
+                    if (prop.propertyType === Date && typeof (comp as any)[prop.propertyKey] === 'string') {
+                        (comp as any)[prop.propertyKey] = new Date((comp as any)[prop.propertyKey]);
+                    }
+                }
+            }
+
+            comp.setPersisted(true);
+            comp.setDirty(false);
+            addComponent(entity, comp);
+        }
+    }
+
+    return entity;
+}

package/core/entity/getCacheManager.ts

@@ -0,0 +1,10 @@
+// Static import of CacheManager for hot-path use in componentAccess and
+// cacheStrategies. CacheManager's imports are all type-only references back
+// to core/Entity, so there is no runtime circular dependency — static import
+// is safe and avoids the microtask + Promise allocation of a dynamic import
+// on every set/remove/save/delete call.
+import { CacheManager } from '../cache/CacheManager';
+
+export function getCacheManager(): typeof CacheManager {
+    return CacheManager;
+}

package/core/entity/pendingOps.ts

@@ -0,0 +1,72 @@
+// Drainable background-work tracking for Entity. Extracted from Entity.ts
+// (RFC_REFACTOR_TARGETS §3.2). Module-level state owns the Sets; Entity
+// keeps thin public static delegates for external callers.
+
+// 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).
+const 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.
+const 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`.
+ */
+export async function drainPendingCacheOps(timeoutMs: number = 5_000): Promise<void> {
+    if (pendingCacheOps.size === 0) return;
+    const snapshot = [...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.
+ */
+export async function drainPendingSideEffects(timeoutMs: number = 5_000): Promise<void> {
+    if (pendingSideEffects.size === 0) return;
+    const snapshot = [...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,
+    ]);
+}
+
+/**
+ * Track a fire-and-forget cache promise in the drainable set. Public so
+ * other framework read paths (e.g. Query.populateComponents cache
+ * warming) share the same drain semantics (H-CACHE-1).
+ */
+export function trackCacheOp(p: Promise<void>): void {
+    pendingCacheOps.add(p);
+    p.finally(() => pendingCacheOps.delete(p));
+}
+
+export function trackSideEffect(p: Promise<void>): void {
+    pendingSideEffects.add(p);
+    p.finally(() => pendingSideEffects.delete(p));
+}

package/core/entity/saveEntity.ts

@@ -0,0 +1,375 @@
+// Persistence path for Entity (save / doSave / doDelete) and post-commit
+// side effects. Extracted from Entity.ts (RFC_REFACTOR_TARGETS §3.2). This
+// is the framework's hottest path — behavior is byte-identical to the
+// original inline implementation. Pure functions take the entity instance
+// as the first parameter.
+import { logger } from "../Logger";
+import db, { QUERY_TIMEOUT_MS } from "../../database";
+import { runWithSignal } from "../../database/cancellable";
+import ComponentRegistry from "../components/ComponentRegistry";
+import { uuidv7 } from "../../utils/uuid";
+import { sql, SQL } from "bun";
+import EntityHookManager from "../EntityHookManager";
+import { EntityCreatedEvent, EntityUpdatedEvent } from "../events/EntityLifecycleEvents";
+import { trackSideEffect } from "./pendingOps";
+import { handleCacheAfterSave, runPostDeleteSideEffects } from "./cacheStrategies";
+import type { Entity } from "../Entity";
+
+export async function saveEntity(entity: Entity, trx?: SQL, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<boolean> {
+    // Capture pre-save state BEFORE doSave mutates persisted/dirty flags.
+    const wasNew = !entity._persisted;
+    const changedComponentTypeIds = getDirtyComponents(entity);
+    const removedComponentTypeIds = Array.from(entity.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 entity.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 ${entity.id} after ${timeoutMs}ms`);
+        logger.error({ scope: 'Entity.save', entityId: entity.id, timeoutMs }, err.message);
+        controller.abort(err);
+    }, timeoutMs);
+
+    try {
+        const dbStart = profile ? performance.now() : 0;
+        if (trx) {
+            await doSave(entity, trx, controller.signal);
+        } else {
+            await db.transaction(async (newTrx) => {
+                await doSave(entity, 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(() => {
+                runPostCommitSideEffects(
+                    entity,
+                    wasNew,
+                    changedComponentTypeIds,
+                    removedComponentTypeIds,
+                    context,
+                    profile ? phases : undefined,
+                    profile ? phaseStart : undefined,
+                ).finally(() => resolve());
+            });
+        });
+        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.
+ */
+async function runPostCommitSideEffects(
+    entity: Entity,
+    wasNew: boolean,
+    changedComponentTypeIds: string[],
+    removedComponentTypeIds: string[],
+    context: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal } | 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 handleCacheAfterSave(entity, changedComponentTypeIds, removedComponentTypeIds, context);
+    } catch (err) {
+        logger.warn({ scope: 'cache', entityId: entity.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(entity));
+        } else if (changedComponentTypeIds.length > 0) {
+            await EntityHookManager.executeHooks(new EntityUpdatedEvent(entity, changedComponentTypeIds));
+        }
+    } catch (err) {
+        logger.error({ scope: 'hooks', entityId: entity.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: entity.id, phases }, 'Entity.save phase timings');
+    }
+}
+
+export async function doSave(entity: Entity, trx: SQL, signal?: AbortSignal): Promise<boolean> {
+    // Validate entity ID to prevent PostgreSQL UUID parsing errors
+    if (!entity.id || entity.id.trim() === '') {
+        logger.error(`Cannot save entity: id is empty or invalid`);
+        throw new Error(`Cannot save entity: id is empty or invalid`);
+    }
+
+    if (!(entity as any)._dirty) {
+        // Diagnostics object is non-trivial to build (component walk +
+        // preview mapping) — gate on the active level so the not-dirty
+        // fast path stays allocation-free in production.
+        if (logger.isLevelEnabled?.('trace')) {
+            let dirtyComponents: string[] = [];
+            try {
+                dirtyComponents = getDirtyComponents(entity);
+            } catch {
+                // best-effort diagnostics only
+            }
+
+            const removedTypeIds = Array.from(entity.removedComponents);
+            const entityType = (entity 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: entity.id,
+                        persisted: entity._persisted,
+                        dirty: (entity as any)._dirty,
+                    },
+                    components: {
+                        total: entity.components.size,
+                        dirtyCount: dirtyComponents.length,
+                        dirtyPreview: dirtyComponentPreview,
+                    },
+                    removedComponents: {
+                        count: removedTypeIds.length,
+                        typeIdsPreview: removedTypeIds.slice(0, 10),
+                    },
+                },
+                "[Entity.doSave] Skipping save because entity is not dirty"
+            );
+        }
+        return true;
+    }
+
+    // Cancellation goes through the shared `runWithSignal` helper so
+    // every db.unsafe / trx`...` callsite in the framework uses the same
+    // pattern: on abort the in-flight Bun SQL Query is cancelled, the
+    // transaction callback throws, Bun emits ROLLBACK, and the pooled
+    // backend connection is released. Without this a wall-clock timeout
+    // leaks the backend into `idle in transaction` under pgbouncer
+    // transaction-mode pooling.
+    const run = <T>(q: any): Promise<T> => runWithSignal<T>(q, signal);
+
+    const executeSave = async (saveTrx: SQL) => {
+        if (!entity._persisted) {
+            await run(saveTrx`INSERT INTO entities (id) VALUES (${entity.id}) ON CONFLICT DO NOTHING`);
+            entity._persisted = true;
+        }
+
+        // Delete removed components from database. `components` is the
+        // single source of membership truth — one DELETE per removal batch.
+        if (entity.removedComponents.size > 0) {
+            const typeIds = Array.from(entity.removedComponents);
+            await run(saveTrx`DELETE FROM components WHERE entity_id = ${entity.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) {
+                entity.savedRemovedComponents.add(typeId);
+            }
+            entity.removedComponents.clear();
+        }
+
+        if (entity.components.size === 0) {
+            logger.trace(`No components to save for entity ${entity.id}`);
+            return;
+        }
+
+        // Batch inserts and updates for better performance
+        const componentsToInsert = [];
+        const componentsToUpdate = [];
+
+        for (const comp of entity.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.`);
+            }
+
+            if (!(comp as any)._persisted) {
+                if (comp.id === "") {
+                    comp.id = uuidv7();
+                }
+                componentsToInsert.push({
+                    id: comp.id,
+                    entity_id: entity.id,
+                    name: compName,
+                    type_id: comp.getTypeID(),
+                    data: comp.serializableData()
+                });
+                (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')}`);
+        }
+
+        // Perform updates. Validate all ids up front (synchronous, fails
+        // fast), then issue the UPDATEs sequentially. They were previously
+        // fired together via Promise.all to "pipeline" on the transaction
+        // connection, but multiple concurrent in-flight queries on one
+        // connection deadlock single-backend servers (PGlite test harness),
+        // and a single wire serializes them regardless — no real gain.
+        if (componentsToUpdate.length > 0) {
+            const traceEnabled = logger.isLevelEnabled?.('trace') === true;
+            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`);
+                }
+                // Level-gated: per-component log-object allocation in the
+                // write hot path is pure waste when trace is off.
+                if (traceEnabled) {
+                    logger.trace({ componentId: comp.id, data: comp.data }, `[Entity.doSave] Updating component`);
+                }
+            }
+            for (const comp of componentsToUpdate) {
+                await run(saveTrx`UPDATE components SET data = ${comp.data} WHERE id = ${comp.id}`);
+            }
+        }
+    };
+
+    await executeSave(trx);
+
+    entity.setDirty(false);
+
+    return true;
+}
+
+export async function doDelete(entity: Entity, force: boolean = false): Promise<boolean> {
+    if (!entity._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 ${entity.id} after ${timeoutMs}ms`);
+        logger.error({ scope: 'Entity.doDelete', entityId: entity.id, timeoutMs }, err.message);
+        controller.abort(err);
+    }, timeoutMs);
+
+    const signal = controller.signal;
+    const run = <T>(q: any): Promise<T> => runWithSignal<T>(q, signal);
+
+    try {
+        await db.transaction(async (trx) => {
+            // Independent tables, no FK constraints. Issued sequentially:
+            // multiple concurrent in-flight queries on one connection
+            // deadlock single-backend servers (PGlite test harness), and a
+            // single wire serializes them anyway — Promise.all gave no real
+            // pipelining here.
+            if (force) {
+                await run(trx`DELETE FROM components WHERE entity_id = ${entity.id}`);
+                await run(trx`DELETE FROM entities WHERE id = ${entity.id}`);
+            } else {
+                await run(trx`UPDATE entities SET deleted_at = CURRENT_TIMESTAMP WHERE id = ${entity.id} AND deleted_at IS NULL`);
+                await run(trx`UPDATE components SET deleted_at = CURRENT_TIMESTAMP WHERE entity_id = ${entity.id} AND deleted_at IS NULL`);
+            }
+        });
+        clearTimeout(timeoutHandle);
+
+        // Fire-and-forget post-commit side effects: lifecycle hooks + cache
+        // invalidation. Errors are logged, never propagate to caller.
+        queueMicrotask(() => runPostDeleteSideEffects(entity, !force));
+
+        return true;
+    } catch (error) {
+        clearTimeout(timeoutHandle);
+        if (signal.aborted) {
+            logger.error({ scope: 'Entity.doDelete', entityId: entity.id }, `Entity delete aborted: ${signal.reason ?? error}`);
+        } else {
+            logger.error({ scope: 'Entity.doDelete', entityId: entity.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();
+    }
+}
+
+/**
+ * Get list of component type IDs that are dirty
+ */
+export function getDirtyComponents(entity: Entity): string[] {
+    const dirtyComponents: string[] = [];
+    for (const component of entity.components.values()) {
+        // Include both dirty (modified) components AND new (not persisted) components
+        // New components need to be cached after save, not just modified ones
+        if ((component as any)._dirty || !(component as any)._persisted) {
+            dirtyComponents.push(component.getTypeID());
+        }
+    }
+    return dirtyComponents;
+}