bunsane 0.3.2 → 0.5.0

package/core/components/BaseComponent.ts

@@ -7,6 +7,10 @@ import { uuidv7 } from '../../utils/uuid';
 import { getMetadataStorage } from '../metadata';
 const logger = MainLogger.child({ scope: "Components" });
 
+// Cached property-name arrays keyed by typeId. Metadata is immutable after
+// decorator registration, so allocating once per class is safe.
+const _propNamesCache = new Map<string, string[]>();
+
 export class BaseComponent {
     public id: string = "";
     protected _comp_name: string = "";
@@ -26,10 +30,13 @@ export class BaseComponent {
     }
 
     properties(): string[] {
+        const cached = _propNamesCache.get(this._typeId);
+        if (cached) return cached;
         const storage = getMetadataStorage();
         const props = storage.componentProperties.get(this._typeId);
-        if(!props) return [];
-        return props.map(p => p.propertyKey);
+        const names = Object.freeze(props ? props.map(p => p.propertyKey) : []) as string[];
+        _propNamesCache.set(this._typeId, names);
+        return names;
     }
 
     /**
@@ -52,11 +59,16 @@ export class BaseComponent {
         const data: Record<string, any> = {};
         const storage = getMetadataStorage();
         const props = storage.componentProperties.get(this._typeId);
-        this.properties().forEach((prop: string) => {
+        if (!props) return data;
+        // Iterate the property metadata directly — avoids the prior O(n²)
+        // pattern (properties().forEach + props.find per property) and the
+        // redundant second metadata lookup inside properties(). Hot write path:
+        // runs for every dirty component on every save.
+        for (const propMeta of props) {
+            const prop = propMeta.propertyKey;
             let value = (this as any)[prop];
-            const propMeta = props?.find(p => p.propertyKey === prop);
             if (value !== null && value !== undefined) {
-                if (propMeta?.propertyType === Date) {
+                if (propMeta.propertyType === Date) {
                     if (!(value instanceof Date)) {
                         throw new Error(`Type mismatch for property '${prop}' on component '${this._comp_name}': expected Date, got ${typeof value}`);
                     }
@@ -64,17 +76,21 @@ export class BaseComponent {
                         throw new Error(`Invalid Date for property '${prop}' on component '${this._comp_name}'`);
                     }
                     value = value.toISOString();
-                } else if (propMeta?.propertyType === Number && typeof value === 'number' && !Number.isFinite(value)) {
+                } else if (propMeta.propertyType === Number && typeof value === 'number' && !Number.isFinite(value)) {
                     throw new Error(`Invalid number for property '${prop}' on component '${this._comp_name}': ${value}`);
                 }
             }
             data[prop] = value;
-        });
+        }
         return data;
     }
 
     async save(trx: Bun.SQL, entity_id: string) {
-        logger.trace(`Saving component ${this._comp_name} for entity ${entity_id}`);
+        // Level-gated: template literal allocates per component save even
+        // when trace is disabled.
+        if (logger.isLevelEnabled?.('trace')) {
+            logger.trace(`Saving component ${this._comp_name} for entity ${entity_id}`);
+        }
         // Only check readiness if component is not yet registered
         // This optimization avoids 40,000+ unnecessary async calls for bulk operations
         if(!ComponentRegistry.isComponentReady(this._comp_name)) {
@@ -98,10 +114,9 @@ export class BaseComponent {
         if (!entity_id || entity_id.trim() === '') {
             throw new Error(`Cannot insert component ${this._comp_name}: entity_id is empty or invalid`);
         }
-        await trx`INSERT INTO components 
+        await trx`INSERT INTO components
         (id, entity_id, name, type_id, data)
         VALUES (${this.id}, ${entity_id}, ${this._comp_name}, ${this._typeId}, ${this.serializableData()})`
-        await trx`INSERT INTO entity_components (entity_id, type_id, component_id) VALUES (${entity_id}, ${this._typeId}, ${this.id}) ON CONFLICT DO NOTHING`
     }
 
     async update(trx: Bun.SQL) {

package/core/components/ComponentRegistry.ts

@@ -8,6 +8,7 @@ import {
     GenerateTableName,
     UpdateComponentIndexes,
     AnalyzeAllComponentTables,
+    CreateRelationIndexes,
     GetPartitionStrategy,
 } from "../../database/DatabaseHelper";
 import { ensureMultipleJSONBPathIndexes } from "../../database/IndexingStrategy";
@@ -34,6 +35,7 @@ class ComponentRegistry {
     private readinessPromises = new Map<string, Promise<void>>();
     private readinessResolvers = new Map<string, () => void>();
     private componentsRegistered: boolean = false;
+    private cachedPartitionStrategy: string | null = null;
 
     constructor() {}
 
@@ -200,6 +202,18 @@ class ComponentRegistry {
     }
 
     register(name: string, typeid: string, ctor: ComponentConstructor) {
+        // Warn when a LIST partition is being attached after startup registration
+        // completed. CREATE TABLE ... PARTITION OF takes ACCESS EXCLUSIVE on the
+        // parent `components` table, stalling all component I/O during the lock.
+        // Fine at boot; dangerous if a request triggers first use of a new type.
+        if (this.componentsRegistered && this.cachedPartitionStrategy === 'list') {
+            logger.warn(
+                `Runtime partition attach for component "${name}" takes ACCESS EXCLUSIVE on the ` +
+                `components table, stalling all component reads and writes until the DDL completes. ` +
+                `Pre-register all components at startup, or set BUNSANE_PARTITION_STRATEGY=hash ` +
+                `to avoid per-component partitions.`
+            );
+        }
         return new Promise<boolean>(async (resolve) => {
             const partitionTableName = GenerateTableName(name);
             // await this.populateCurrentTables();
@@ -289,6 +303,7 @@ class ComponentRegistry {
 
         // Check partitioning strategy for index creation
         const partitionStrategy = await GetPartitionStrategy();
+        this.cachedPartitionStrategy = partitionStrategy;
 
         // Update component indexes for components that have indexed properties
         // NOTE: Index operations are serialized to prevent deadlocks with ANALYZE
@@ -346,6 +361,19 @@ class ComponentRegistry {
         }
         logger.info(`Registered hooks for ${services.length} services`);
 
+        // Create btree indexes on archetype relation foreign-key fields
+        // (data->>'fk'). Without these, @BelongsTo/@HasMany resolver queries
+        // sequentially scan the relation component partition tables. Runs
+        // before ANALYZE so the planner picks up fresh stats for the new
+        // indexes. Idempotent (IF NOT EXISTS) and CONCURRENTLY on LIST
+        // partitions, so it is safe to re-run on every startup against live
+        // tables.
+        try {
+            await CreateRelationIndexes();
+        } catch (error) {
+            logger.warn(`Failed to create relation FK indexes: ${error}`);
+        }
+
         // Run ANALYZE on all component tables to update query planner statistics
         await AnalyzeAllComponentTables();
     }

package/core/decorators/IndexedField.ts

@@ -11,7 +11,7 @@ import { getMetadataStorage } from '../metadata';
  *   - 'numeric': BTREE index with numeric cast for range queries (>, <, BETWEEN)
  * @param isDateField Whether this field contains date values (affects BTREE index casting)
  */
-export function IndexedField(indexType: 'gin' | 'btree' | 'hash' | 'numeric' = 'gin', isDateField: boolean = false) {
+export function IndexedField(indexType: 'gin' | 'btree' | 'hash' | 'numeric' | 'fulltext' = 'gin', isDateField: boolean = false) {
     return function(target: any, propertyKey: string) {
         const storage = getMetadataStorage();
         const componentId = storage.getComponentId(target.constructor.name);

package/core/entity/cacheStrategies.ts

@@ -0,0 +1,97 @@
+// Cache side-effect strategies for Entity save/delete. Extracted from
+// Entity.ts (RFC_REFACTOR_TARGETS §3.2). Pure functions take the entity
+// instance as the first parameter.
+import type { BaseComponent } from "../components";
+import { logger } from "../Logger";
+import EntityHookManager from "../EntityHookManager";
+import { EntityDeletedEvent } from "../events/EntityLifecycleEvents";
+import type { SQL } from "bun";
+import { getCacheManager } from "./getCacheManager";
+import type { Entity } from "../Entity";
+
+/**
+ * Handle cache operations after successful save
+ * @param changedComponentTypeIds - Component type IDs that were dirty before save (captured before doSave clears flags)
+ * @param removedComponentTypeIds - Component type IDs that were removed (captured before doSave clears the set)
+ */
+export async function handleCacheAfterSave(entity: Entity, changedComponentTypeIds: string[], removedComponentTypeIds: string[], context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<void> {
+    try {
+        const CacheManager = getCacheManager();
+        const cacheManager = CacheManager.getInstance();
+        const config = cacheManager.getConfig();
+
+        const entityEnabled = !!(config.enabled && config.entity?.enabled);
+        const componentEnabled = !!(config.enabled && config.component?.enabled);
+
+        if (entityEnabled && config.strategy === 'write-through') {
+            await cacheManager.setEntityWriteThrough(entity, config.entity!.ttl);
+        }
+
+        // Handle component cache invalidation with granular approach
+        if (componentEnabled) {
+            // Use the pre-captured lists instead of re-querying (dirty flags are already cleared by doSave)
+
+            if (config.strategy === 'write-through') {
+                // Single batched write-through (2 pipelined provider
+                // round-trips total) instead of one GET+SET pair per
+                // changed component.
+                const entries = changedComponentTypeIds
+                    .map(typeId => ({ typeId, component: entity.components.get(typeId) }))
+                    .filter((e): e is { typeId: string; component: BaseComponent } => !!e.component)
+                    .map(e => ({ entityId: entity.id, typeId: e.typeId, component: e.component, ttl: config.component!.ttl }));
+                if (entries.length > 0) {
+                    await cacheManager.setComponentsBatchWriteThrough(entries);
+                }
+                // Removed components must still drop out of cache.
+                if (removedComponentTypeIds.length > 0) {
+                    await cacheManager.invalidateEntityComponents(entity.id, removedComponentTypeIds);
+                }
+            } else {
+                // One deleteMany + ONE pub/sub message for the whole save
+                // (entity key included) — previously N+1 DEL+PUBLISH pairs
+                // per save, fanning out to every other instance.
+                const toInvalidate = [...changedComponentTypeIds, ...removedComponentTypeIds];
+                if (toInvalidate.length > 0 || entityEnabled) {
+                    await cacheManager.invalidateEntityComponents(entity.id, toInvalidate, { includeEntityKey: entityEnabled });
+                }
+            }
+
+            // Invalidate DataLoader cache for changed + removed components
+            if (context?.loaders?.componentsByEntityType) {
+                for (const typeId of [...changedComponentTypeIds, ...removedComponentTypeIds]) {
+                    context.loaders.componentsByEntityType.clear({
+                        entityId: entity.id,
+                        typeId: typeId
+                    });
+                }
+            }
+        } else if (entityEnabled && config.strategy !== 'write-through') {
+            await cacheManager.invalidateEntity(entity.id);
+        }
+    } catch (error) {
+        logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache operation failed after save', error });
+    }
+}
+
+export async function runPostDeleteSideEffects(entity: Entity, softDelete: boolean): Promise<void> {
+    try {
+        await EntityHookManager.executeHooks(new EntityDeletedEvent(entity, softDelete));
+    } catch (err) {
+        logger.error({ scope: 'hooks', entityId: entity.id, err }, 'post-delete lifecycle hooks failed');
+    }
+
+    try {
+        const CacheManager = getCacheManager();
+        const cacheManager = CacheManager.getInstance();
+        const config = cacheManager.getConfig();
+
+        if (config.enabled && config.entity?.enabled) {
+            await cacheManager.invalidateEntity(entity.id);
+        }
+        if (config.enabled && config.component?.enabled) {
+            await cacheManager.invalidateAllEntityComponents(entity.id);
+        }
+    } catch (err) {
+        logger.warn({ scope: 'cache', entityId: entity.id, err }, 'post-delete cache invalidation failed');
+    }
+}

package/core/entity/componentAccess.ts

@@ -0,0 +1,383 @@
+// Component access + mutation for Entity (add/set/remove/get/has/reload
+// and the in-memory helpers). Extracted from Entity.ts
+// (RFC_REFACTOR_TARGETS §3.2). Pure functions take the entity instance as
+// the first parameter; hook phases/order are byte-identical to the
+// original inline implementation.
+import type { ComponentDataType, ComponentGetter, BaseComponent } from "../components";
+import { logger } from "../Logger";
+import db from "../../database";
+import { runWithSignal } from "../../database/cancellable";
+import ComponentRegistry from "../components/ComponentRegistry";
+import { SQL } from "bun";
+import EntityHookManager from "../EntityHookManager";
+import { getMetadataStorage } from "../metadata";
+import { ComponentAddedEvent, ComponentUpdatedEvent, ComponentRemovedEvent } from "../events/EntityLifecycleEvents";
+import { getRequestScope } from "../requestScope";
+import { trackCacheOp } from "./pendingOps";
+import { getCacheManager } from "./getCacheManager";
+import type { Entity } from "../Entity";
+
+export function addComponent(entity: Entity, component: BaseComponent): Entity {
+    const typeId = component.getTypeID();
+    entity.components.set(typeId, component);
+    // A component that just arrived can never be "missing" — clear any
+    // previously recorded absence so future get() calls see the new data.
+    entity._missingComponents.delete(typeId);
+    return entity;
+}
+
+/**
+ * Resolve a component constructor to its type id. `getComponentId` is
+ * memoized in metadata storage, so this is an O(1) Map lookup with no
+ * component instantiation — unlike `new ctor().getTypeID()`. The
+ * `components` map is keyed by type id (see addComponent), so callers can
+ * then do `entity.components.get(typeId)` instead of allocating an array and
+ * scanning it with `instanceof`.
+ */
+export function typeIdOf(ctor: new (...args: any[]) => BaseComponent): string {
+    return getMetadataStorage().getComponentId(ctor.name);
+}
+
+export function componentList(entity: Entity): BaseComponent[] {
+    return Array.from(entity.components.values());
+}
+
+export function getInMemory<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): T | undefined {
+    return entity.components.get(typeIdOf(ctor)) as T | undefined;
+}
+
+export function hasInMemory<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): boolean {
+    return entity.components.has(typeIdOf(ctor));
+}
+
+export function wasRemoved<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): boolean {
+    const typeId = typeIdOf(ctor);
+    // Check both pending removals and already-saved removals
+    return entity.removedComponents.has(typeId) || entity.savedRemovedComponents.has(typeId);
+}
+
+export function add<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, data?: Partial<ComponentDataType<T>>): Entity {
+    const instance = new ctor();
+    if (data) {
+        Object.assign(instance, data);
+    }
+    addComponent(entity, instance);
+    entity.setDirty(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(entity, instance)))
+        .catch((error) => {
+            logger.error(`Error firing component added hook for ${instance.getTypeID()}: ${error}`);
+        });
+
+    return entity;
+}
+
+export async function set<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, data: Partial<ComponentDataType<T>>, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<Entity> {
+    await get(entity, ctor, context);
+
+    const component = entity.components.get(typeIdOf(ctor)) as T;
+    if (component) {
+        // Store old data for the update event
+        const oldData = { ...component };
+
+        // Update existing component
+        Object.assign(component, data);
+        component.setDirty(true);
+        entity.setDirty(true);
+
+        // 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 {
+            await EntityHookManager.executeHooks(new ComponentUpdatedEvent(entity, 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
+        }
+
+        // Invalidate DataLoader cache if context is provided
+        if (context?.loaders?.componentsByEntityType) {
+            context.loaders.componentsByEntityType.clear({
+                entityId: entity.id,
+                typeId: component.getTypeID()
+            });
+        }
+
+        // Fire-and-forget cache update, tracked via drainable set so
+        // App.shutdown can await it (H-CACHE-1).
+        trackCacheOp((async () => {
+            try {
+                const CacheManager = getCacheManager();
+                const cacheManager = CacheManager.getInstance();
+                const config = cacheManager.getConfig();
+
+                if (config.enabled && config.component?.enabled) {
+                    if (config.strategy === 'write-through') {
+                        await cacheManager.setComponentWriteThrough(entity.id, [component], component.getTypeID(), config.component.ttl);
+                    } else {
+                        await cacheManager.invalidateComponent(entity.id, component.getTypeID());
+                    }
+                }
+            } catch (error) {
+                logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache operation failed after set', err: error });
+            }
+        })());
+    } else {
+        // Add new component
+        add(entity, ctor, data);
+        entity.setDirty(true);
+        // Note: add() already fires ComponentAddedEvent, so we don't need to fire it again
+    }
+    return entity;
+}
+
+export function remove<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): boolean {
+    const component = entity.components.get(typeIdOf(ctor)) as T;
+
+    if (component) {
+        const typeId = component.getTypeID();
+
+        // Track the component type for database deletion
+        entity.removedComponents.add(typeId);
+
+        // Remove the component from the map
+        entity.components.delete(typeId);
+        entity.setDirty(true);
+
+        // 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(entity, component)))
+            .catch((error) => {
+                logger.error(`Error firing component removed hook for ${typeId}: ${error}`);
+            });
+
+        // Invalidate DataLoader cache if context is provided
+        if (context?.loaders?.componentsByEntityType) {
+            context.loaders.componentsByEntityType.clear({
+                entityId: entity.id,
+                typeId: typeId
+            });
+        }
+
+        // Fire-and-forget cache invalidation, tracked for shutdown drain
+        // (H-CACHE-1).
+        trackCacheOp((async () => {
+            try {
+                const CacheManager = getCacheManager();
+                const cacheManager = CacheManager.getInstance();
+                const config = cacheManager.getConfig();
+
+                if (config.enabled && config.component?.enabled) {
+                    await cacheManager.invalidateComponent(entity.id, typeId);
+                }
+            } catch (error) {
+                logger.warn({ scope: 'cache', component: 'Entity', msg: 'Cache invalidation failed after remove', err: error });
+            }
+        })());
+
+        return true;
+    }
+
+    return false;
+}
+
+export async function get<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<ComponentDataType<T> | null> {
+    const comp = await loadComponent(entity, ctor, context);
+    return comp ? (comp as ComponentGetter<T>).data() : null;
+}
+
+export function has<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): boolean {
+    return hasInMemory(entity, ctor);
+}
+
+export async function getOrThrow<T extends BaseComponent>(
+    entity: Entity,
+    ctor: new (...args: any[]) => T,
+    context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }
+): Promise<ComponentDataType<T>> {
+    const data = await get(entity, ctor, context);
+    if (data === null) {
+        throw new Error(`Entity ${entity.id} is missing required component ${ctor.name}`);
+    }
+    return data;
+}
+
+export function getCached<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T): ComponentDataType<T> | undefined {
+    const comp = getInMemory(entity, ctor);
+    return comp ? (comp as ComponentGetter<T>).data() : undefined;
+}
+
+export async function getInstanceOf<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<T | null> {
+    return loadComponent(entity, ctor, context);
+}
+
+export async function reload(entity: Entity, opts?: { trx?: SQL; signal?: AbortSignal }): Promise<Entity> {
+    if (!entity.id || entity.id.trim() === '') {
+        return entity;
+    }
+    entity.components.clear();
+    entity.removedComponents.clear();
+    entity.savedRemovedComponents.clear();
+    entity._missingComponents.clear();
+
+    const dbConn = opts?.trx ?? db;
+    const rows = await runWithSignal<any[]>(
+        dbConn`
+        SELECT c.id, c.type_id, c.data
+        FROM components c
+        WHERE c.entity_id = ${entity.id} AND c.deleted_at IS NULL
+    `,
+        opts?.signal
+    );
+
+    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);
+        addComponent(entity, comp);
+    }
+
+    entity.setPersisted(true);
+    entity.setDirty(false);
+    return entity;
+}
+
+export async function requireComponents(entity: Entity, ctors: Array<new (...args: any[]) => BaseComponent>): Promise<void> {
+    if (ctors.length === 0) return;
+    const missing: string[] = [];
+    for (const ctor of ctors) {
+        // components is keyed by type id — O(1) lookup, no instantiation
+        // and no O(K) instanceof scan per constructor.
+        const typeId = typeIdOf(ctor);
+        if (!entity.components.has(typeId)) {
+            missing.push(typeId);
+        }
+    }
+    if (missing.length === 0) return;
+    const { Entity } = await import("../Entity");
+    await Entity.LoadComponents([entity], missing);
+}
+
+async function loadComponent<T extends BaseComponent>(entity: Entity, ctor: new (...args: any[]) => T, context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<T | null> {
+    const comp = entity.components.get(typeIdOf(ctor)) as T | undefined;
+    if (typeof comp !== "undefined") {
+        return comp;
+    }
+
+    // Validate entity ID before database query
+    if (!entity.id || entity.id.trim() === '') {
+        logger.warn(`Cannot load component ${ctor.name}: entity id is empty`);
+        return null;
+    }
+
+    // Memoized metadata lookup — no throwaway component instantiation
+    // just to read the type id.
+    const typeId = typeIdOf(ctor);
+
+    // Negative-cache short-circuit: if we previously confirmed this component
+    // is absent from the DB (and no explicit transaction is in scope that
+    // could see a different snapshot), skip the SELECT entirely.
+    // Skipped when a trx is provided — within a transaction the visibility
+    // horizon may differ from the outer read (stale-read hazard).
+    if (!context?.trx && entity._missingComponents.has(typeId)) {
+        return null;
+    }
+
+    // Use transaction if provided, otherwise use default db
+    const dbConn = context?.trx ?? db;
+
+    // Ambient request scope fallback: bare entity.get() calls (e.g.
+    // inside @ArcheTypeFunction bodies or Unwrap()) batch through the
+    // request's DataLoaders instead of firing one SELECT per call.
+    // Never substituted when the caller passed an explicit trx — a
+    // loader read outside the transaction could see stale data.
+    const scope = (!context?.loaders && !context?.trx) ? getRequestScope() : undefined;
+    const loaders = context?.loaders ?? scope?.loaders;
+    const signal = context?.signal ?? scope?.signal;
+
+    try {
+        let componentData: any = null;
+        let componentId: string | null = null;
+
+        if (loaders?.componentsByEntityType) {
+            const loaderResult = await loaders.componentsByEntityType.load({
+                entityId: entity.id,
+                typeId: typeId
+            });
+            if (loaderResult) {
+                componentData = loaderResult.data;
+                componentId = loaderResult.id;
+            }
+        } else {
+            // Route through runWithSignal so a request/wall-clock abort can
+            // cancel this in-flight read. When dbConn is context.trx, an
+            // uncancelled read leaks the backend into `idle in transaction`
+            // on timeout (matches the d1dde84 save/delete fix, which missed
+            // the read path).
+            const rows = await runWithSignal<any[]>(
+                dbConn`SELECT id, data FROM components WHERE entity_id = ${entity.id} AND type_id = ${typeId} AND deleted_at IS NULL`,
+                signal
+            );
+            if (rows.length > 0) {
+                componentData = rows[0].data;
+                componentId = rows[0].id;
+            }
+        }
+
+        if (componentData !== null) {
+            const comp: any = new ctor();
+            if (componentId) {
+                comp.id = componentId;
+            }
+            const parsedData = typeof componentData === 'string' ? JSON.parse(componentData) : componentData;
+            Object.assign(comp, parsedData);
+            const storage = getMetadataStorage();
+            const props = storage.componentProperties.get(typeId);
+            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);
+            addComponent(entity, comp);
+            return comp as T;
+        } else {
+            // Record the confirmed absence so repeated probes skip the DB.
+            // Only when no explicit trx — within a transaction the caller
+            // may insert the component and probe again in the same scope.
+            if (!context?.trx) {
+                entity._missingComponents.add(typeId);
+            }
+            return null;
+        }
+    } catch (error) {
+        logger.error(`Failed to fetch component ${ctor.name}: ${error}`);
+        return null;
+    }
+}
+
+export { loadComponent };