bunsane 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,58 @@ All notable changes to bunsane are documented here.
 
 ## Unreleased
 
+### Added (HR-Screening ticket batch — BUNSANE-002..006)
+
+- **`@ScheduledTask` allows entity-less time-based tasks.** Previously
+  `SchedulerManager.registerTask` rejected tasks without `query` or
+  `componentTarget`, contradicting documented "runs every hour" examples.
+  Time-based tasks now register successfully and invoke the handler with
+  no entity argument on each tick. Existing entity-targeted tasks
+  unchanged. Ticket BUNSANE-002.
+
+- **`Entity.requireComponents(ctors)` hydrator.** Batched-load helper
+  that ensures the given component constructors are present on the
+  in-memory `componentList`. Required before `set` / `save` flows that
+  may trigger `@ComponentTargetHook` — hook matching reads
+  `componentList()` (in-memory only), so tag components must be loaded
+  first for the hook to fire. Ticket BUNSANE-003.
+
+- **`ServiceRegistry` class named-exported.** `service/ServiceRegistry.ts`
+  now exports the class as named alongside the existing default-instance
+  export. Available via `service/index.ts` as `ServiceRegistryClass` for
+  type/subclass use; existing `ServiceRegistry` import remains the
+  singleton instance for backward compatibility. Ticket BUNSANE-004.
+
+- **`CacheManager.invalidateEntities(ids: string[])`.** Batched helper
+  that invalidates both the entity-existence cache and all component
+  caches for a list of IDs. Call after a raw-SQL write (`db.unsafe`)
+  that bypasses `Entity.set` / `Entity.save`. Ticket BUNSANE-005.
+
+- **`Entity.reload(opts?)` refresher.** Discards in-memory component
+  state and re-hydrates from the `components` table. Preserves entity
+  identity — callers holding a reference see fresh data on the same
+  instance. Use after raw-SQL writes or when a sibling `Entity`
+  instance with the same id mutated persisted data. Ticket BUNSANE-006.
+
+- **Empty-string filter values supported.** `Query.filter(field, op, '')`
+  and the downstream SQL emit path (`ComponentInclusionNode`,
+  `PreparedStatementCache.execute`, `Query.doExec` / `doCount` /
+  `doAggregate` param validators) previously rejected empty /
+  whitespace-only values with "would cause PostgreSQL UUID parsing errors".
+  JSONB text extraction (`c.data->>'field'`) returns text, so `= ''` /
+  `!= ''` / `LIKE ''` are legitimate for text fields. The UUID-cast path
+  is gated by a value-side regex that an empty string cannot match, so
+  unsafe casts never fire. `findById('')` still throws — entity IDs
+  remain UUID-typed.
+
+- **`Entity.drainPendingSideEffects(timeoutMs)`.** Drainable tracking
+  for post-commit work scheduled via `queueMicrotask` from `save()`
+  (cache invalidation + lifecycle hooks). Wired into `App.shutdown`
+  after `drainPendingCacheOps`. Tests under PGlite can call this in
+  `beforeAll` to settle prior-file background work before asserting.
+  Partial mitigation for BUNSANE-001 (Bun SQL / PGlite visibility race
+  — see `CLAUDE.md` PGlite section for full context).
+
 ### Fixed (PR E — outbox, cache, query hardening)
 
 - **OutboxWorker publishes to Redis concurrently and marks rows in bulk.**

package/CLAUDE.md

@@ -159,6 +159,26 @@ The wrapper script:
 - `?|` and `?&` operators not supported (use `@>` / `<@` instead)
 - `CREATE INDEX CONCURRENTLY` not supported
 - Single connection only (`POSTGRES_MAX_CONNECTIONS=1`)
+- **Known Bun SQL + PGlite visibility race**: under a single-connection
+  pool with background work from a prior test file, `await entity.save()`
+  may resolve ≥1ms before the `INSERT INTO entity_components` row is
+  visible to a subsequent `db.unsafe('SELECT ...')` on the same driver.
+  The per-component partition INSERT (e.g. `components_<compname>`) in
+  the same transaction is visible immediately; only the flat
+  `entity_components` row lags. This causes multi-component Query
+  INTERSECTs to return 0 rows when run immediately after save.
+
+  **Mitigation (not a full fix):**
+  1. Shut down application-owned background workers (AI processors,
+     outbox workers, hook-driven save chains) in `afterAll` of each test
+     file — prevents cross-file bleed that amplifies the race.
+  2. Call `await Entity.drainPendingSideEffects()` in `beforeAll` / test
+     `setup` to settle hook-triggered post-commit work (helpful but
+     insufficient on its own).
+  3. Skip the affected test or poll with a short `setTimeout(1)`.
+
+  Root cause lives in the Bun SQL adapter's ACK handling, not bunsane.
+  File upstream with a minimal repro if you hit this.
 
 ## Directory Structure
 

package/core/App.ts

@@ -1410,9 +1410,13 @@ export default class App {
 
         // 4. Drain any fire-and-forget cache ops triggered by entity.set /
         //    entity.remove before we disconnect the cache (H-CACHE-1).
+        //    Also drain post-commit side effects (cache + hooks scheduled
+        //    via queueMicrotask from save()) so hook-triggered DB work
+        //    doesn't hit a closed pool.
         try {
             const { Entity } = await import('./Entity');
             await Entity.drainPendingCacheOps(Math.min(budgetRemaining(), 5_000));
+            await Entity.drainPendingSideEffects(Math.min(budgetRemaining(), 5_000));
         } catch (error) {
             logger.warn({ scope: 'cache', component: 'App', msg: 'Entity cache op drain error', err: error });
         }

package/core/Entity.ts

@@ -27,6 +27,17 @@ export class Entity implements IEntity {
     // (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
@@ -45,11 +56,36 @@ export class Entity implements IEntity {
         ]);
     }
 
+    /**
+     * 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();
@@ -348,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") {
@@ -465,14 +576,21 @@ export class Entity implements IEntity {
 
             // Post-commit side effects are fire-and-forget so Redis / hook
             // latency cannot consume the save budget or block the caller.
-            queueMicrotask(() => this.runPostCommitSideEffects(
-                wasNew,
-                changedComponentTypeIds,
-                removedComponentTypeIds,
-                context,
-                profile ? phases : undefined,
-                profile ? phaseStart : undefined,
-            ));
+            // 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) {

package/core/SchedulerManager.ts

@@ -109,12 +109,10 @@ export class SchedulerManager {
             throw error;
         }
 
-        // Validate query configuration
-        if (!taskInfo.options?.query && !taskInfo.options?.componentTarget && !taskInfo.componentTarget) {
-            const error = new Error(`Invalid task info: must provide either query function, componentTarget config, or legacy componentTarget`);
-            loggerInstance.error(`Failed to register task: ${error.message}`);
-            throw error;
-        }
+        // Time-based tasks (no query, no componentTarget) are allowed — they
+        // invoke the handler with no entity arguments on each tick. Useful
+        // for external polling, stats aggregation, or ad-hoc queries inside
+        // the callback.
 
         if (!taskInfo.service) {
             const error = new Error(`Task ${taskInfo.id} has no service instance`);
@@ -395,7 +393,7 @@ export class SchedulerManager {
         try {
             // Create query based on targeting configuration
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            let query: Query<any>;
+            let query: Query<any> | null = null;
 
             if (taskInfo.options?.query) {
                 // Use custom query function (preferred approach)
@@ -407,16 +405,16 @@ export class SchedulerManager {
             } else if (taskInfo.componentTarget) {
                 // Use legacy single component targeting (deprecated - use query instead)
                 query = new Query().with(taskInfo.componentTarget);
-            } else {
-                throw new Error('No query function or component target specified');
             }
+            // else: time-based task — no entity selection. Handler invoked
+            // with no arguments on each tick.
 
             // Apply entity limit if specified (can be used with query function)
-            if (taskInfo.options?.maxEntitiesPerExecution) {
+            if (query && taskInfo.options?.maxEntitiesPerExecution) {
                 query.take(taskInfo.options.maxEntitiesPerExecution);
             }
 
-            const entities = await query.exec();
+            const entities = query ? await query.exec() : [];
 
             // Execute the scheduled method with the entities array
             const method = taskInfo.service[taskInfo.methodName];
@@ -424,9 +422,11 @@ export class SchedulerManager {
                 throw new Error(`Method ${taskInfo.methodName} not found on service`);
             }
 
-            // Execute with timeout
+            // Execute with timeout. Time-based tasks receive no entity arg.
             const result = await this.executeWithTimeout(
-                method.call(taskInfo.service, entities),
+                query
+                    ? method.call(taskInfo.service, entities)
+                    : method.call(taskInfo.service),
                 timeout,
                 taskInfo
             );

package/core/cache/CacheManager.ts

@@ -284,6 +284,24 @@ export class CacheManager {
         }
     }
 
+    /**
+     * Invalidate cached state (entity + all components) for a batch of
+     * entity IDs. Call this after a raw-SQL write (db.unsafe) that bypasses
+     * Entity.set/save, so downstream reads observe fresh data instead of
+     * stale L1/L2 cache entries.
+     */
+    public async invalidateEntities(entityIds: string[]): Promise<void> {
+        if (!this.config.enabled || entityIds.length === 0) {
+            return;
+        }
+        await Promise.all(
+            entityIds.flatMap(id => [
+                this.invalidateEntity(id),
+                this.invalidateAllEntityComponents(id),
+            ])
+        );
+    }
+
     /**
      * Invalidate all components for a specific entity from cache
      * Uses pattern matching to efficiently clear all component caches for an entity

package/core/components/BaseComponent.ts

@@ -55,8 +55,18 @@ export class BaseComponent {
         this.properties().forEach((prop: string) => {
             let value = (this as any)[prop];
             const propMeta = props?.find(p => p.propertyKey === prop);
-            if (propMeta?.propertyType === Date && value instanceof Date) {
-                value = value.toISOString();
+            if (value !== null && value !== undefined) {
+                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}`);
+                    }
+                    if (Number.isNaN(value.getTime())) {
+                        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)) {
+                    throw new Error(`Invalid number for property '${prop}' on component '${this._comp_name}': ${value}`);
+                }
             }
             data[prop] = value;
         });

package/database/PreparedStatementCache.ts

@@ -111,19 +111,11 @@ export class PreparedStatementCache {
      * Execute a prepared statement with parameters
      */
     public async execute(statement: any, params: any[], db: any): Promise<any[]> {
-        // Validate params to catch empty strings that would cause UUID parsing errors
-        for (let i = 0; i < params.length; i++) {
-            const param = params[i];
-            if (param === '' || (typeof param === 'string' && param.trim() === '')) {
-                logger.error(`[PreparedStatementCache] Empty string parameter at position ${i + 1}`);
-                logger.error(`[PreparedStatementCache] SQL: ${statement.sql}`);
-                logger.error(`[PreparedStatementCache] All params: ${JSON.stringify(params)}`);
-                throw new Error(`PreparedStatementCache.execute: Parameter $${i + 1} is an empty string. SQL: ${statement.sql.substring(0, 100)}...`);
-            }
-        }
-        
-        // For Bun's SQL, we still use db.unsafe() but with the prepared statement concept
-        // In a real implementation, this might use a prepared statement pool
+        // Empty-string params are legitimate for text-field filters
+        // (`c.data->>'field' = ''`). UUID-typed params never reach this
+        // point empty — callers (Query.findById etc.) guard at entry. PG
+        // emits a clear error at execution time if a UUID cast meets an
+        // empty string.
         return await db.unsafe(statement.sql, params);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.3.0",
+    "version": "0.3.1",
     "author": {
         "name": "yaaruu"
     },

package/query/ComponentInclusionNode.ts

@@ -606,11 +606,11 @@ export class ComponentInclusionNode extends QueryNode {
                     condition = result.sql;
                     // Note: custom builder is responsible for adding parameters via context.addParam()
                 } else {
-                    // Default filter logic
-                    // Validate filter value to prevent PostgreSQL UUID parsing errors
-                    if (filter.value === '' || (typeof filter.value === 'string' && filter.value.trim() === '')) {
-                        throw new Error(`Filter value for field "${filter.field}" is an empty string. This would cause PostgreSQL UUID parsing errors.`);
-                    }
+                    // Default filter logic. Empty-string values are permitted
+                    // here — `c.data->>'field'` extracts text, so `=`/`!=`/
+                    // `LIKE` against '' is legitimate. The UUID-cast path
+                    // below is gated on a regex that empty string cannot
+                    // match, so unsafe casts never fire.
 
                     // Check if value looks like a UUID (case-insensitive, with or without hyphens)
                     const valueStr = String(filter.value);

package/query/Query.ts

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

package/service/ServiceRegistry.ts

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

package/service/index.ts

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

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

@@ -141,6 +141,26 @@ describe('CacheManager', () => {
             expect(result).toBeNull();
         });
 
+        test('invalidateEntities clears entity + all component caches for a batch', async () => {
+            const provider = cacheManager.getProvider();
+            // Two entities, each with cached entity entry + one component
+            await provider.set('entity:e1', 'e1', 3600000);
+            await provider.set('entity:e2', 'e2', 3600000);
+            await provider.set('component:e1:t1', { data: 'a' }, 3600000);
+            await provider.set('component:e2:t1', { data: 'b' }, 3600000);
+
+            await cacheManager.invalidateEntities(['e1', 'e2']);
+
+            expect(await cacheManager.getEntity('e1')).toBeNull();
+            expect(await cacheManager.getEntity('e2')).toBeNull();
+            expect(await cacheManager.getComponentsByEntity('e1', 't1')).toBeNull();
+            expect(await cacheManager.getComponentsByEntity('e2', 't1')).toBeNull();
+        });
+
+        test('invalidateEntities is a noop for empty list', async () => {
+            await expect(cacheManager.invalidateEntities([])).resolves.toBeUndefined();
+        });
+
         test('getEntities returns null for missing entities', async () => {
             const results = await cacheManager.getEntities(['id1', 'id2', 'id3']);
             expect(results.length).toBe(3);

package/tests/unit/entity/Entity.components.test.ts

@@ -187,6 +187,79 @@ describe('Entity Component Management', () => {
 
             expect(data?.createdAt).toBe('2024-01-15T10:30:00.000Z');
         });
+
+        test('serializableData throws descriptive error on invalid Date', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-002',
+                total: 50,
+                status: 'pending',
+                createdAt: new Date('not-a-date')
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).toThrow(
+                /Invalid Date for property 'createdAt' on component 'TestOrder'/
+            );
+        });
+
+        test('serializableData throws on Date type mismatch', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-003',
+                total: 50,
+                status: 'pending',
+                createdAt: '2024-01-15' as any
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).toThrow(
+                /Type mismatch for property 'createdAt' on component 'TestOrder': expected Date, got string/
+            );
+        });
+
+        test('serializableData throws on NaN number', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-004',
+                total: NaN,
+                status: 'pending',
+                createdAt: new Date()
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).toThrow(
+                /Invalid number for property 'total' on component 'TestOrder'/
+            );
+        });
+
+        test('serializableData throws on Infinity number', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-005',
+                total: Infinity,
+                status: 'pending',
+                createdAt: new Date()
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).toThrow(
+                /Invalid number for property 'total' on component 'TestOrder'/
+            );
+        });
+
+        test('serializableData allows null/undefined for nullable Date/Number', () => {
+            const entity = new Entity();
+            entity.add(TestOrder, {
+                orderNumber: 'ORD-006',
+                total: 0,
+                status: 'pending',
+                createdAt: null as any
+            });
+
+            const component = entity.getInMemory(TestOrder);
+            expect(() => component?.serializableData()).not.toThrow();
+        });
     });
 
     describe('component state', () => {

package/tests/unit/entity/Entity.drainSideEffects.test.ts

@@ -0,0 +1,51 @@
+/**
+ * BUNSANE-001 defensive harness: verify Entity.drainPendingSideEffects()
+ * awaits post-commit work scheduled via queueMicrotask from save(), so
+ * tests under PGlite can settle prior-file background work before
+ * asserting against freshly-committed state.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { ensureComponentsRegistered } from '../../utils';
+
+@Component
+class DrainMarker extends BaseComponent {
+    @CompData()
+    value: string = '';
+}
+
+describe('Entity.drainPendingSideEffects', () => {
+    beforeAll(async () => {
+        await ensureComponentsRegistered(DrainMarker);
+    });
+
+    test('no-op when nothing is pending', async () => {
+        await expect(Entity.drainPendingSideEffects(100)).resolves.toBeUndefined();
+    });
+
+    test('awaits post-commit side effects scheduled by save()', async () => {
+        const saved = Entity.Create();
+        saved.add(DrainMarker, { value: 'pending' });
+        await saved.save();
+
+        // runPostCommitSideEffects is queued as a microtask. drain() must
+        // settle it before returning.
+        await Entity.drainPendingSideEffects(2_000);
+
+        // A second drain is a no-op.
+        await Entity.drainPendingSideEffects(100);
+    });
+
+    test('bounded by timeout, returns even if drain exceeds it', async () => {
+        const saved = Entity.Create();
+        saved.add(DrainMarker, { value: 'bounded' });
+        await saved.save();
+
+        const start = Date.now();
+        await Entity.drainPendingSideEffects(1);
+        const elapsed = Date.now() - start;
+        expect(elapsed).toBeLessThan(500);
+    });
+});

package/tests/unit/entity/Entity.reload.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Unit tests for Entity.reload (BUNSANE-006).
+ * Ensures in-memory component state is discarded and re-hydrated from DB.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { ensureComponentsRegistered } from '../../utils';
+import db from '../../../database';
+
+@Component
+class ReloadStatus extends BaseComponent {
+    @CompData()
+    value: string = '';
+}
+
+describe('Entity.reload', () => {
+    beforeAll(async () => {
+        await ensureComponentsRegistered(ReloadStatus);
+    });
+
+    test('no-op on entity without a valid id', async () => {
+        const entity = new Entity('');
+        await expect(entity.reload()).resolves.toBe(entity);
+    });
+
+    test('refreshes in-memory data after raw-SQL write', async () => {
+        const saved = Entity.Create();
+        saved.add(ReloadStatus, { value: 'before' });
+        await saved.save();
+
+        const typeId = new ReloadStatus().getTypeID();
+
+        // Write new value via raw SQL — bypasses entity cache invalidation.
+        await db.unsafe(
+            `UPDATE components SET data = data || '{"value":"after"}'::jsonb
+             WHERE entity_id = $1 AND type_id = $2`,
+            [saved.id, typeId]
+        );
+
+        // In-memory copy still holds stale value.
+        expect(saved.getInMemory(ReloadStatus)?.value).toBe('before');
+
+        const returned = await saved.reload();
+        expect(returned).toBe(saved);
+        expect(saved.getInMemory(ReloadStatus)?.value).toBe('after');
+    });
+
+    test('hydrates a bare Entity instance from DB', async () => {
+        const saved = Entity.Create();
+        saved.add(ReloadStatus, { value: 'hydrated' });
+        await saved.save();
+
+        const bare = new Entity(saved.id);
+        expect(bare.componentList().length).toBe(0);
+
+        await bare.reload();
+
+        expect(bare.hasInMemory(ReloadStatus)).toBe(true);
+        expect(bare.getInMemory(ReloadStatus)?.value).toBe('hydrated');
+    });
+});

package/tests/unit/entity/Entity.requireComponents.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Unit tests for Entity.requireComponents (BUNSANE-003).
+ * Ensures ComponentTargetHook includeComponents matching sees tag
+ * components that weren't eagerly loaded.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { TestUser } from '../../fixtures/components';
+import { ensureComponentsRegistered } from '../../utils';
+
+@Component
+class ReqTag extends BaseComponent {}
+
+@Component
+class ReqData extends BaseComponent {
+    @CompData()
+    value: string = '';
+}
+
+describe('Entity.requireComponents', () => {
+    beforeAll(async () => {
+        await ensureComponentsRegistered(TestUser, ReqTag, ReqData);
+    });
+
+    test('no-op for empty list', async () => {
+        const entity = Entity.Create();
+        await expect(entity.requireComponents([])).resolves.toBeUndefined();
+        expect(entity.componentList().length).toBe(0);
+    });
+
+    test('does nothing when components already in memory', async () => {
+        const entity = Entity.Create();
+        entity.add(ReqTag);
+        const before = entity.componentList().length;
+        await entity.requireComponents([ReqTag]);
+        expect(entity.componentList().length).toBe(before);
+    });
+
+    test('hydrates missing components from DB after save', async () => {
+        const saved = Entity.Create();
+        saved.add(ReqTag);
+        saved.add(ReqData, { value: 'hello' });
+        await saved.save();
+
+        const loaded = new Entity(saved.id);
+        expect(loaded.componentList().length).toBe(0);
+
+        await loaded.requireComponents([ReqTag, ReqData]);
+
+        expect(loaded.hasInMemory(ReqTag)).toBe(true);
+        expect(loaded.hasInMemory(ReqData)).toBe(true);
+        expect(loaded.getInMemory(ReqData)?.value).toBe('hello');
+    });
+
+    test('only fetches missing components, not already-loaded ones', async () => {
+        const saved = Entity.Create();
+        saved.add(ReqTag);
+        saved.add(ReqData, { value: 'mix' });
+        await saved.save();
+
+        const loaded = new Entity(saved.id);
+        await loaded.requireComponents([ReqData]);
+        expect(loaded.hasInMemory(ReqData)).toBe(true);
+        expect(loaded.hasInMemory(ReqTag)).toBe(false);
+
+        await loaded.requireComponents([ReqTag, ReqData]);
+        expect(loaded.hasInMemory(ReqTag)).toBe(true);
+        expect(loaded.getInMemory(ReqData)?.value).toBe('mix');
+    });
+});

package/tests/unit/query/Query.emptyString.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Empty-string filter support. JSONB text extraction (c.data->>'field')
+ * returns text, so `= ''` / `!= ''` / LIKE against empty string are
+ * legitimate. UUID-cast path is gated on a regex that empty cannot match.
+ */
+import { describe, test, expect, beforeAll } from 'bun:test';
+import { Entity } from '../../../core/Entity';
+import { BaseComponent } from '../../../core/components/BaseComponent';
+import { Component, CompData } from '../../../core/components/Decorators';
+import { Query, FilterOp } from '../../../query/Query';
+import { ensureComponentsRegistered } from '../../utils';
+
+@Component
+class EmptyableNote extends BaseComponent {
+    @CompData()
+    value: string = '';
+}
+
+describe('Query empty-string filter', () => {
+    beforeAll(async () => {
+        await ensureComponentsRegistered(EmptyableNote);
+    });
+
+    test('Query.filter accepts empty-string value without throwing', () => {
+        expect(() => Query.filter('value', FilterOp.EQ, '')).not.toThrow();
+        const f = Query.filter('value', FilterOp.EQ, '');
+        expect(f.value).toBe('');
+    });
+
+    test('Query.filter accepts whitespace-only value without throwing', () => {
+        expect(() => Query.filter('value', FilterOp.EQ, '   ')).not.toThrow();
+    });
+
+    test('.with(C, filter EQ "") executes and returns matching rows', async () => {
+        const withEmpty = Entity.Create();
+        withEmpty.add(EmptyableNote, { value: '' });
+        await withEmpty.save();
+
+        const withData = Entity.Create();
+        withData.add(EmptyableNote, { value: 'not empty' });
+        await withData.save();
+
+        const rows = await new Query()
+            .with(EmptyableNote, Query.filters(Query.filter('value', FilterOp.EQ, '')))
+            .exec();
+
+        const ids = rows.map(e => e.id);
+        expect(ids).toContain(withEmpty.id);
+        expect(ids).not.toContain(withData.id);
+    });
+
+    test('.with(C, filter != "") excludes rows with empty value', async () => {
+        const withEmpty = Entity.Create();
+        withEmpty.add(EmptyableNote, { value: '' });
+        await withEmpty.save();
+
+        const withData = Entity.Create();
+        withData.add(EmptyableNote, { value: 'populated' });
+        await withData.save();
+
+        const rows = await new Query()
+            .with(EmptyableNote, Query.filters(Query.filter('value', FilterOp.NEQ, '')))
+            .exec();
+
+        const ids = rows.map(e => e.id);
+        expect(ids).toContain(withData.id);
+        expect(ids).not.toContain(withEmpty.id);
+    });
+});

package/tests/unit/query/Query.test.ts

@@ -192,12 +192,14 @@ describe('Query', () => {
             expect(filter.value).toBe('John');
         });
 
-        test('throws for empty string value', () => {
-            expect(() => Query.filter('name', FilterOp.EQ, '')).toThrow();
+        test('accepts empty string value', () => {
+            const filter = Query.filter('name', FilterOp.EQ, '');
+            expect(filter.value).toBe('');
         });
 
-        test('throws for whitespace value', () => {
-            expect(() => Query.filter('name', FilterOp.EQ, '   ')).toThrow();
+        test('accepts whitespace value', () => {
+            const filter = Query.filter('name', FilterOp.EQ, '   ');
+            expect(filter.value).toBe('   ');
         });
     });
 

package/tests/unit/scheduler/SchedulerManager.timeBased.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Unit tests for SchedulerManager time-based (entity-less) tasks.
+ * Covers BUNSANE-002: @ScheduledTask without query/componentTarget.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { SchedulerManager } from '../../../core/SchedulerManager';
+import { ScheduleInterval } from '../../../types/scheduler.types';
+
+describe('SchedulerManager time-based tasks', () => {
+    let scheduler: SchedulerManager;
+
+    beforeEach(() => {
+        scheduler = SchedulerManager.getInstance();
+        scheduler.updateConfig({
+            enabled: true,
+            enableLogging: false,
+            runOnStart: false,
+            distributedLocking: false,
+            maxConcurrentTasks: 5,
+            defaultTimeout: 5000,
+        });
+    });
+
+    afterEach(async () => {
+        await scheduler.stop().catch(() => {});
+    });
+
+    test('registers task with no query / no componentTarget', () => {
+        let called = 0;
+        const service = {
+            tick: async () => {
+                called++;
+            },
+        };
+
+        expect(() =>
+            scheduler.registerTask({
+                id: 'test.timebased.register',
+                name: 'timebased-register',
+                interval: ScheduleInterval.MINUTE,
+                options: {},
+                service,
+                methodName: 'tick',
+                nextExecution: new Date(),
+                executionCount: 0,
+                isRunning: false,
+                enabled: true,
+            })
+        ).not.toThrow();
+    });
+
+    test('executes handler with no entity argument', async () => {
+        const receivedArgsBox: { args: unknown[] | null } = { args: null };
+        const service = {
+            tick: async (...args: unknown[]) => {
+                receivedArgsBox.args = args;
+            },
+        };
+
+        scheduler.registerTask({
+            id: 'test.timebased.exec',
+            name: 'timebased-exec',
+            interval: ScheduleInterval.MINUTE,
+            options: {},
+            service,
+            methodName: 'tick',
+            nextExecution: new Date(),
+            executionCount: 0,
+            isRunning: false,
+            enabled: true,
+        });
+
+        const ok = await scheduler.executeTaskNow('test.timebased.exec');
+        expect(ok).toBe(true);
+        expect(receivedArgsBox.args).toEqual([]);
+    });
+
+    test('rejects task still missing required fields', () => {
+        const service = { tick: async () => {} };
+        expect(() =>
+            scheduler.registerTask({
+                // missing id
+                name: 'bad',
+                interval: ScheduleInterval.MINUTE,
+                options: {},
+                service,
+                methodName: 'tick',
+                nextExecution: new Date(),
+                executionCount: 0,
+                isRunning: false,
+                enabled: true,
+            } as any)
+        ).toThrow(/missing required fields/);
+    });
+});