bunsane 0.3.0 → 0.3.2

package/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"302022ef-825d-48c8-8ef6-656f1cd141e0","pid":60520,"procStart":"639139204827053470","acquiredAt":1778489386099}

package/CHANGELOG.md

@@ -4,6 +4,110 @@ All notable changes to bunsane are documented here.
 
 ## Unreleased
 
+### Added (v0.3.2 — AbortSignal propagation + DB observability)
+
+- **AbortSignal threading into `Query.exec` + DataLoaders.** Resolvers
+  invoked from a GraphQL request now receive the request's `AbortSignal`
+  via the request-context plugin. When the framework's 30s wall-clock
+  fires (`core/app/requestRouter.ts`), in-flight `db.unsafe()` queries
+  are cancelled through Bun's `SQL.Query.cancel()`. Without this an
+  aborted request leaked its backend connection into
+  `idle in transaction` under pgbouncer transaction-mode pooling,
+  cascading into pool starvation under sustained timeout pressure.
+  Public surface: `Query.exec({ signal })`, `Query.count({ signal })`,
+  `Query.estimatedCount(component, { signal })`,
+  `Query.findOneById(id, { signal })`,
+  `Query.explainAnalyze(buffers, { signal })`,
+  `createRequestLoaders(db, cache?, signal?, perRequest?)`.
+  Reuses helper `runWithSignal` extracted to `database/cancellable.ts`
+  and shared with the existing `Entity.doSave` / `Entity.doDelete`
+  abort paths.
+
+- **DB roundtrip observability (`database/instrumentedDb.ts`).** Every
+  `db.unsafe()` callsite in `Query.ts`, `RequestLoaders.ts` and the
+  shared `PreparedStatementCache.execute` now routes through
+  `timedUnsafe`. Tracks `totalCount`, `totalMs`, `maxMs`, `avgMs`,
+  `slowCount`, `abortedCount`, `inFlightMax`, plus per-DataLoader-kind
+  counters. Exposed at `/metrics` under the new `db` key. Calls over
+  `BUNSANE_DB_SLOW_MS` (default 500ms, set 0 to disable warn) log a
+  structured `Slow DB call` warning with a SQL snippet.
+
+- **Per-request stats on access + timeout logs.** GraphQL request
+  context now captures `operationName`, `dataLoaderCalls`
+  (entity / component / relation), and `dbQueryCount`. These attach to
+  the underlying `Request` via `__bunsaneStats` so the HTTP router's
+  catch block and `AccessLog` middleware can include them in every
+  log line. The previous `Request failed after 30004ms: POST /graphql`
+  log now carries enough fields to identify the offending operation
+  without re-running production with a debug build. Timeout warn log
+  also includes operation name when reachable.
+
+### Env vars added
+
+- `BUNSANE_DB_SLOW_MS` (default `500`) — per-call DB threshold for
+  slow log + `slowCount` metric. Set `0` to suppress the warn (stats
+  still accumulate).
+
+### Backward compatibility
+
+All additions are opt-in. Existing apps see no behavior change:
+`Query.exec()`, `Query.count()`, `createRequestLoaders(db, cache)`,
+and `preparedStatementCache.execute(s, p, db)` retain their pre-0.3.2
+signatures. `/metrics` gains a `db` key (pure addition). Log lines
+gain fields but preserve existing ones.
+
+### 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/config/cache.config.ts

@@ -31,6 +31,29 @@ export interface CacheConfig {
     component?: {
         enabled: boolean;
         ttl: number;
+        /**
+         * Cache "absent" component lookups (negative cache) so repeated reads
+         * of optional components on the same entity do not re-hit the DB.
+         * Default false (opt-in) to preserve prior behavior.
+         */
+        negativeCacheEnabled?: boolean;
+        /**
+         * TTL in ms for tombstone entries written for absent components.
+         * Defaults to min(component.ttl, 60_000). Keep ≤ ttl so a created
+         * row supersedes the tombstone within bounded staleness.
+         */
+        negativeCacheTtl?: number;
+    };
+
+    /**
+     * Negative-only cache for relation lookups (e.g. @HasMany returning []).
+     * Empty results are cached with a short TTL; positive results are not
+     * cached here (cross-entity invalidation is non-trivial — see RFC
+     * H-CACHE-NEG). Bounded staleness window equal to negativeCacheTtl.
+     */
+    relation?: {
+        negativeCacheEnabled?: boolean;
+        negativeCacheTtl?: number;
     };
 
     query?: {
@@ -76,7 +99,18 @@ export const defaultCacheConfig: CacheConfig = {
 
     component: {
         enabled: process.env.CACHE_COMPONENT_ENABLED !== 'false', // Default true
-        ttl: parseInt(process.env.CACHE_COMPONENT_TTL || '1800000') // 30 minutes
+        ttl: parseInt(process.env.CACHE_COMPONENT_TTL || '1800000'), // 30 minutes
+        negativeCacheEnabled: process.env.CACHE_COMPONENT_NEGATIVE_ENABLED === 'true',
+        negativeCacheTtl: process.env.CACHE_COMPONENT_NEGATIVE_TTL
+            ? parseInt(process.env.CACHE_COMPONENT_NEGATIVE_TTL)
+            : undefined
+    },
+
+    relation: {
+        negativeCacheEnabled: process.env.CACHE_RELATION_NEGATIVE_ENABLED === 'true',
+        negativeCacheTtl: process.env.CACHE_RELATION_NEGATIVE_TTL
+            ? parseInt(process.env.CACHE_RELATION_NEGATIVE_TTL)
+            : 60_000
     },
 
     query: {