bunsane 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 All notable changes to bunsane are documented here.
 
+## 0.5.1 — 2026-06-16
+
+### Added
+
+- **Transaction-aware cache invalidation** — component writes made via
+  `comp.save(trx, id)` inside the new `transaction()` wrapper now bust the
+  component cache on commit, using the same
+  `CacheManager.invalidateEntityComponents` path (L1 + L2 + cross-instance
+  pub/sub) that `Entity.save` uses. Touched `(entityId, typeId)` pairs are
+  tracked automatically (keyed by the transaction handle), then flushed after
+  the transaction commits. The `tx` context also exposes `tx.markDirty(entityId,
+  component)` for components not saved directly and `tx.onCommit(cb)` for
+  post-commit side effects. Exported from `bunsane/core/cache` as `transaction`,
+  `txMarkDirty`, `txOnCommit`. No behavior change for `comp.save` outside the
+  wrapper — tracking is a no-op there.
+- **`ArcheTypeQuery.select(...fields)`** — opt-in projection for archetype
+  queries. Loads data only for the selected component fields instead of every
+  component in the archetype, cutting JSONB wire + parse cost for wide
+  archetypes read with narrow selections. Membership filtering is unaffected
+  (matching still requires all components); unselected fields remain
+  lazy-loadable. Backward-compatible — without `select()`, all components load as
+  before.
+
+### Fixed
+
+- **RedisCache test connects on `127.0.0.1`** instead of `localhost`, which
+  resolves to IPv6 `::1` first on Windows and times out against an IPv4-only
+  Redis. Test-only change.
+
+## 0.5.0 — 2026-06-15
+
+### Added
+
+- **`/health` write probe** — the deep health check now exercises a real write
+  through the same `db.transaction()` path `Entity.save` uses (a temp-table
+  insert dropped on commit, no persistent side effect), instead of a read-only
+  `SELECT 1`. A wedged write pool — one where reads stay healthy but writes hang
+  — now fails liveness so orchestrators restart the container instead of it
+  serving timeouts indefinitely. Configurable via `HEALTH_DB_WRITE_PROBE`
+  (default on) and `DB_HEALTH_WRITE_TIMEOUT` (default 5000 ms). When the probe
+  fails or times out, `/health` returns 503.
+- **`DB_DISABLE_PREPARE`** — set to `true` to disable Bun SQL's automatic
+  server-side prepared statements (`prepare: false`). **Required behind PgBouncer
+  in transaction pooling mode**, where per-connection prepared statements break
+  across pooled backends and can wedge the write path. Default behavior is
+  unchanged (prepared statements remain on).
+- **`docs/CONFIGURATION.md`** — full environment-variable reference, including a
+  PgBouncer deployment section and the health-check/liveness guidance above.
+
+### Behavior change
+
+- `/health` now performs a database write by default. If you point a liveness
+  probe at `/health`, ensure the write path is reachable, or set
+  `HEALTH_DB_WRITE_PROBE=false` to keep the previous read-only behavior.
+
 ## 0.4.0 — 2026-06-11
 
 ### Performance (2026-06-10 overhaul)

package/core/App.ts

@@ -11,7 +11,20 @@ import {
 } from "../database/DatabaseHelper";
 import { ComponentRegistry } from "./components";
 import { logger as MainLogger } from "./Logger";
+import { readFileSync } from "fs";
 const logger = MainLogger.child({ scope: "App" });
+
+// BunSane framework version, read from the package's own package.json at module
+// load. Resolved relative to this module file so it works regardless of cwd or
+// how the consumer installs the package.
+let BUNSANE_VERSION = "unknown";
+try {
+    BUNSANE_VERSION = JSON.parse(
+        readFileSync(new URL("../package.json", import.meta.url), "utf8")
+    ).version;
+} catch {
+    // version stays "unknown" if package.json can't be read
+}
 import ServiceRegistry from "../service/ServiceRegistry";
 import { type Plugin, createPubSub } from "graphql-yoga";
 import * as path from "path";
@@ -351,6 +364,20 @@ export default class App {
         this.maxRequestBodySize = bytes;
     }
 
+    /**
+     * Re-weave the GraphQL schema from the currently registered services and
+     * swap it into the live Yoga instance — no restart, no Yoga recreation.
+     * The next request observes the new schema (Yoga reads it via a factory).
+     *
+     * Phase 0 primitive for runtime schema mutation: register/modify a service
+     * (or its @GraphQLOperation metadata), then call this to reflect it live.
+     * Returns the new schema version number (monotonic, starts at 1).
+     */
+    public rebuildGraphQLSchema(): number {
+        ServiceRegistry.rebuildSchema();
+        return ServiceRegistry.getSchemaVersion();
+    }
+
     private async warmUpPreparedStatementCache(): Promise<void> {
         return warmUpPreparedStatementCacheFn(this);
     }
@@ -396,7 +423,7 @@ export default class App {
             `Server is running on ${new URL(
                 this.yoga?.graphqlEndpoint || "/graphql",
                 `http://${this.server.hostname}:${this.server.port}`
-            )}`
+            )} (BunSane v${BUNSANE_VERSION})`
         );
 
         // Signal handlers now registered in init() via registerProcessHandlers()

package/core/ArcheType.ts

@@ -160,6 +160,7 @@ export class ArcheTypeQuery<T extends BaseArcheType> {
     private innerQuery: Query<any>;
     private archetypeInstance: T;
     private archetypeCtor: new () => T;
+    private selectedFields: string[] | null = null;
 
     constructor(archetypeCtor: new () => T) {
         this.archetypeCtor = archetypeCtor;
@@ -241,6 +242,50 @@ export class ArcheTypeQuery<T extends BaseArcheType> {
         return this;
     }
 
+    /**
+     * Project: load data only for the given archetype fields (components).
+     *
+     * Membership filtering is unaffected — matching the archetype still requires
+     * all its components. This only limits which component DATA is fetched, so a
+     * wide archetype read with a narrow selection skips the JSONB wire+parse cost
+     * of unselected components. Unselected fields are absent from results; they
+     * remain lazy-loadable later via entity.get() under a request scope.
+     *
+     * Backward-compatible: without select(), exec()/first() load all components.
+     *
+     * @example
+     * ```typescript
+     * const players = await Player.query().select('position', 'health').exec();
+     * // only position + health component data loaded; velocity etc. skipped
+     * ```
+     */
+    public select<K extends keyof ArcheTypeOwnProperties<T>>(...fields: K[]): this {
+        this.selectedFields = fields.map((f) => {
+            const name = String(f);
+            if (!this.archetypeInstance.componentMap[name]) {
+                throw new Error(`Field '${name}' is not a component field on this archetype`);
+            }
+            return name;
+        });
+        return this;
+    }
+
+    private selectedComponentCtors(): Array<new () => BaseComponent> {
+        return (this.selectedFields ?? []).map(
+            (f) => this.archetypeInstance.componentMap[f] as unknown as new () => BaseComponent
+        );
+    }
+
+    /**
+     * Apply the load strategy: projected (eager-load selected components) when
+     * select() was used, otherwise populate() all archetype components.
+     */
+    private withLoadStrategy(): Query<any> {
+        return this.selectedFields
+            ? this.innerQuery.eagerLoadComponents(this.selectedComponentCtors())
+            : this.innerQuery.populate();
+    }
+
     /**
      * Enable populate mode to load all component data
      */
@@ -261,7 +306,7 @@ export class ArcheTypeQuery<T extends BaseArcheType> {
      * Execute the query and return typed archetype results
      */
     public async exec(): Promise<ArcheTypeResult<T>[]> {
-        const entities = await this.innerQuery.populate().exec();
+        const entities = await this.withLoadStrategy().exec();
         return entities.map(entity => this.wrapAsArchetype(entity as Entity));
     }
 
@@ -269,7 +314,7 @@ export class ArcheTypeQuery<T extends BaseArcheType> {
      * Execute the query and return the first result (or null)
      */
     public async first(): Promise<ArcheTypeResult<T> | null> {
-        const results = await this.innerQuery.take(1).populate().exec();
+        const results = await this.withLoadStrategy().take(1).exec();
         return results[0] ? this.wrapAsArchetype(results[0] as Entity) : null;
     }
 

package/core/Entity.ts

@@ -20,6 +20,14 @@ export class Entity implements IEntity {
     // This persists after save() so resolvers can detect removed components
     /** @internal Promoted from private for the core/entity/ submodule split (RFC §3.2). Not part of the public API. */
     public savedRemovedComponents: Set<string> = new Set<string>();
+    /**
+     * @internal Type IDs confirmed absent from the DB during this entity's
+     * lifetime. Used as a negative cache in loadComponent() so repeated
+     * get() probes for optional components skip the SELECT. Invalidated
+     * whenever a component is added (addComponent) or the entity is
+     * reloaded. Not part of the public API.
+     */
+    public _missingComponents: Set<string> = new Set<string>();
     protected _dirty: boolean = false;
 
     constructor(id?: string) {

package/core/app/graphqlSetup.ts

@@ -4,7 +4,10 @@ import { createYogaInstance } from "../../gql";
 import { createRequestContextPlugin } from "../RequestContext";
 
 export function setupGraphQL(app: any): void {
-    const schema = ServiceRegistry.getSchema();
+    // Provide the schema as a live factory rather than a fixed reference, so
+    // ServiceRegistry.rebuildSchema() is observed by the next request without
+    // recreating Yoga. Falls back to the static placeholder while null.
+    const schemaProvider = () => ServiceRegistry.getSchema();
 
     const wrappedContextFactory = app.contextFactory
         ? async (yogaContext: any) => {
@@ -38,19 +41,10 @@ export function setupGraphQL(app: any): void {
         ? [createRequestContextPlugin(), ...app.yogaPlugins]
         : [...app.yogaPlugins];
 
-    if (schema) {
-        app.yoga = createYogaInstance(
-            schema,
-            effectivePlugins,
-            wrappedContextFactory,
-            yogaOptions,
-        );
-    } else {
-        app.yoga = createYogaInstance(
-            undefined,
-            effectivePlugins,
-            wrappedContextFactory,
-            yogaOptions,
-        );
-    }
+    app.yoga = createYogaInstance(
+        schemaProvider,
+        effectivePlugins,
+        wrappedContextFactory,
+        yogaOptions,
+    );
 }

package/core/cache/RedisCache.ts

@@ -270,18 +270,19 @@ export class RedisCache implements CacheProvider {
      */
     async setMany<T>(entries: Array<{key: string, value: T, ttl?: number}>): Promise<void> {
         try {
+            const compressed = await Promise.all(entries.map(e => CompressionUtils.compressForStorage(e.value)));
+
             const pipeline = this.client.pipeline();
 
-            for (const entry of entries) {
+            entries.forEach((entry, i) => {
                 const prefixedKey = this.prefixKey(entry.key);
-                const serializedValue = await CompressionUtils.compressForStorage(entry.value);
-
+                const serializedValue = compressed[i] as string;
                 if (entry.ttl) {
                     pipeline.setex(prefixedKey, Math.floor(entry.ttl / 1000), serializedValue);
                 } else {
                     pipeline.set(prefixedKey, serializedValue);
                 }
-            }
+            });
 
             await pipeline.exec();
         } catch (error) {

package/core/cache/index.ts

@@ -3,4 +3,13 @@ export { MemoryCache } from './MemoryCache';
 export type { MemoryCacheConfig } from './MemoryCache';
 export { NoOpCache } from './NoOpCache';
 export { CacheManager } from './CacheManager';
-export { CacheFactory } from './CacheFactory';
+export { CacheFactory } from './CacheFactory';
+export {
+    transaction,
+    markDirty as txMarkDirty,
+    registerOnCommit as txOnCommit,
+    trackComponentDirty,
+    beginTxTracking,
+    flushTxTracking,
+} from './txInvalidation';
+export type { TxContext } from './txInvalidation';

package/core/cache/txInvalidation.ts

@@ -0,0 +1,183 @@
+/**
+ * Transaction-aware cache invalidation.
+ *
+ * `comp.save(trx, id)` writes the DB but does no cache invalidation on its own.
+ * Inside a tracked transaction we accumulate the (entityId, typeId) pairs that
+ * were touched and, once the transaction COMMITS, run the same invalidation that
+ * entity.save() uses (CacheManager.invalidateEntityComponents → deleteMany +
+ * cross-instance pub/sub).
+ *
+ * Bun.SQL exposes no commit hook, so "on commit" means: after the
+ * `db.transaction(cb)` promise resolves. The `transaction()` wrapper below owns
+ * that boundary. Tracking is keyed by the trx object via a WeakMap, so
+ * `trackComponentDirty` is a cheap no-op for any comp.save() that runs outside a
+ * tracked transaction (top-level db, or entity.save() which handles its own
+ * cache) — zero behavior change for existing callers.
+ */
+import { logger as MainLogger } from '../Logger';
+
+const logger = MainLogger.child({ scope: 'TxCacheInvalidation' });
+
+/** Anything carrying a component type_id — avoids a hard BaseComponent import (cycle). */
+type ComponentRef = string | { _typeId?: string } | (new (...args: any[]) => any);
+
+type SQLLike = Bun.SQL;
+
+interface TxState {
+    /** entityId -> set of touched component type_ids */
+    dirty: Map<string, Set<string>>;
+    onCommit: Array<() => void | Promise<void>>;
+}
+
+/** Tracking state keyed by the transaction's SQL handle. */
+const txRegistry = new WeakMap<SQLLike, TxState>();
+
+/** Begin tracking for a transaction handle. Idempotent. */
+export function beginTxTracking(trx: SQLLike): TxState {
+    let state = txRegistry.get(trx);
+    if (!state) {
+        state = { dirty: new Map(), onCommit: [] };
+        txRegistry.set(trx, state);
+    }
+    return state;
+}
+
+export function getTxState(trx: SQLLike): TxState | undefined {
+    return txRegistry.get(trx);
+}
+
+/**
+ * Record that a component (entityId + typeId) was written under this trx.
+ * No-op when the trx is not tracked (i.e. not inside transaction()).
+ */
+export function trackComponentDirty(trx: SQLLike, entityId: string, typeId: string): void {
+    const state = txRegistry.get(trx);
+    if (!state || !entityId || !typeId) return;
+    let set = state.dirty.get(entityId);
+    if (!set) {
+        set = new Set();
+        state.dirty.set(entityId, set);
+    }
+    set.add(typeId);
+}
+
+/** Resolve a component ctor / instance / raw typeId string to its type_id. */
+function resolveTypeId(component: ComponentRef): string | null {
+    if (typeof component === 'string') return component;
+    // Instance carrying a _typeId (BaseComponent) — duck-typed to avoid an import cycle.
+    const instanceTypeId = (component as { _typeId?: string })._typeId;
+    if (typeof instanceTypeId === 'string' && instanceTypeId.length > 0) return instanceTypeId;
+    // Constructor: derive from class name via metadata.
+    if (typeof component === 'function') {
+        try {
+            const { getMetadataStorage } = require('../metadata');
+            return getMetadataStorage().getComponentId(component.name);
+        } catch {
+            return null;
+        }
+    }
+    return null;
+}
+
+/**
+ * Explicitly mark a component dirty for invalidation on commit.
+ * Accepts a component constructor, instance, or raw type_id string.
+ */
+export function markDirty(trx: SQLLike, entityId: string, component: ComponentRef): void {
+    const typeId = resolveTypeId(component);
+    if (!typeId) {
+        logger.warn({ entityId, msg: 'markDirty: could not resolve component type_id; skipping' });
+        return;
+    }
+    trackComponentDirty(trx, entityId, typeId);
+}
+
+/** Register a callback to run after the transaction commits. */
+export function registerOnCommit(trx: SQLLike, cb: () => void | Promise<void>): void {
+    const state = beginTxTracking(trx);
+    state.onCommit.push(cb);
+}
+
+/**
+ * Flush accumulated invalidations + run onCommit callbacks. Call ONLY after the
+ * transaction has committed. Errors are logged, never thrown — a cache flush
+ * failure must not surface as a transaction failure (the data is already
+ * committed; stale cache is recoverable, a thrown error is not).
+ */
+export async function flushTxTracking(state: TxState | undefined): Promise<void> {
+    if (!state) return;
+    try {
+        if (state.dirty.size > 0) {
+            const { CacheManager } = require('./CacheManager');
+            const cacheManager = CacheManager.getInstance();
+            await Promise.all(
+                Array.from(state.dirty.entries()).map(([entityId, typeIds]) =>
+                    cacheManager
+                        .invalidateEntityComponents(entityId, Array.from(typeIds), { includeEntityKey: true })
+                        .catch((error: unknown) =>
+                            logger.error({ entityId, error, msg: 'Failed to invalidate entity components on commit' }),
+                        ),
+                ),
+            );
+        }
+    } catch (error) {
+        logger.error({ error, msg: 'Error during transaction cache flush' });
+    }
+
+    for (const cb of state.onCommit) {
+        try {
+            await cb();
+        } catch (error) {
+            logger.error({ error, msg: 'onCommit callback threw' });
+        }
+    }
+}
+
+/** Context handed to the transaction() callback for explicit control. */
+export interface TxContext {
+    /** Mark a component dirty for invalidation on commit. */
+    markDirty(entityId: string, component: ComponentRef): void;
+    /** Run a callback after the transaction commits (cache already flushed). */
+    onCommit(cb: () => void | Promise<void>): void;
+}
+
+/**
+ * Run a transaction with automatic, transaction-aware cache invalidation.
+ *
+ * Any `comp.save(trx, entityId)` performed with the provided `trx` is tracked
+ * automatically; on commit, those components are invalidated using the same
+ * logic entity.save() uses. The `tx` context adds explicit markDirty/onCommit
+ * escape hatches.
+ *
+ * Invalidation runs inline (awaited) after commit, so when this resolves the
+ * cache is already consistent.
+ *
+ * @example
+ * ```typescript
+ * await transaction(async (trx, tx) => {
+ *   await positionComp.save(trx, entityId);   // auto-tracked
+ *   tx.markDirty(entityId, Velocity);          // explicit
+ *   tx.onCommit(() => metrics.bump());         // after commit
+ * });
+ * ```
+ */
+export async function transaction<T>(
+    fn: (trx: SQLLike, tx: TxContext) => Promise<T>,
+): Promise<T> {
+    const { getDb } = require('../../database');
+    const db: SQLLike = getDb();
+
+    let state: TxState | undefined;
+    const result = await db.transaction(async (trx: SQLLike) => {
+        state = beginTxTracking(trx);
+        const ctx: TxContext = {
+            markDirty: (entityId, component) => markDirty(trx, entityId, component),
+            onCommit: (cb) => registerOnCommit(trx, cb),
+        };
+        return await fn(trx, ctx);
+    });
+
+    // Transaction committed (resolved without throwing) → flush invalidations.
+    await flushTxTracking(state);
+    return result as T;
+}

package/core/components/BaseComponent.ts

@@ -5,8 +5,13 @@ import ComponentRegistry from "./ComponentRegistry";
 import { type ComponentDataType } from './Interfaces';
 import { uuidv7 } from '../../utils/uuid';
 import { getMetadataStorage } from '../metadata';
+import { trackComponentDirty } from '../cache/txInvalidation';
 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 +31,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;
     }
 
     /**
@@ -97,6 +105,10 @@ export class BaseComponent {
             await this.insert(trx, entity_id);
             this._persisted = true;
         }
+        // Transaction-aware cache invalidation: record this write so the
+        // transaction() wrapper can bust the component cache on commit.
+        // No-op outside a tracked transaction (cheap WeakMap miss).
+        trackComponentDirty(trx, entity_id, this._typeId);
     }
 
     async insert(trx: Bun.SQL, entity_id: string) {

package/core/entity/cacheStrategies.ts

@@ -6,6 +6,7 @@ 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";
 
 /**
@@ -15,8 +16,7 @@ import type { Entity } from "../Entity";
  */
 export async function handleCacheAfterSave(entity: Entity, changedComponentTypeIds: string[], removedComponentTypeIds: string[], context?: { loaders?: { componentsByEntityType?: any }; trx?: SQL; signal?: AbortSignal }): Promise<void> {
     try {
-        // Import CacheManager dynamically to avoid circular dependency
-        const { CacheManager } = await import('../cache/CacheManager');
+        const CacheManager = getCacheManager();
         const cacheManager = CacheManager.getInstance();
         const config = cacheManager.getConfig();
 
@@ -81,7 +81,7 @@ export async function runPostDeleteSideEffects(entity: Entity, softDelete: boole
     }
 
     try {
-        const { CacheManager } = await import('../cache/CacheManager');
+        const CacheManager = getCacheManager();
         const cacheManager = CacheManager.getInstance();
         const config = cacheManager.getConfig();
 

package/core/entity/componentAccess.ts

@@ -14,10 +14,15 @@ 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 {
-    entity.components.set(component.getTypeID(), component);
+    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;
 }
 
@@ -55,8 +60,6 @@ export function add<T extends BaseComponent>(entity: Entity, ctor: new (...args:
     const instance = new ctor();
     if (data) {
         Object.assign(instance, data);
-    } else {
-        Object.assign(instance, {});
     }
     addComponent(entity, instance);
     entity.setDirty(true);
@@ -109,7 +112,7 @@ export async function set<T extends BaseComponent>(entity: Entity, ctor: new (..
         // App.shutdown can await it (H-CACHE-1).
         trackCacheOp((async () => {
             try {
-                const { CacheManager } = await import('../cache/CacheManager');
+                const CacheManager = getCacheManager();
                 const cacheManager = CacheManager.getInstance();
                 const config = cacheManager.getConfig();
 
@@ -167,7 +170,7 @@ export function remove<T extends BaseComponent>(entity: Entity, ctor: new (...ar
         // (H-CACHE-1).
         trackCacheOp((async () => {
             try {
-                const { CacheManager } = await import('../cache/CacheManager');
+                const CacheManager = getCacheManager();
                 const cacheManager = CacheManager.getInstance();
                 const config = cacheManager.getConfig();
 
@@ -222,6 +225,7 @@ export async function reload(entity: Entity, opts?: { trx?: SQL; signal?: AbortS
     entity.components.clear();
     entity.removedComponents.clear();
     entity.savedRemovedComponents.clear();
+    entity._missingComponents.clear();
 
     const dbConn = opts?.trx ?? db;
     const rows = await runWithSignal<any[]>(
@@ -291,6 +295,15 @@ async function loadComponent<T extends BaseComponent>(entity: Entity, ctor: new
     // 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;
 
@@ -353,6 +366,12 @@ async function loadComponent<T extends BaseComponent>(entity: Entity, ctor: new
             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) {

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