@rotorsoft/act 0.19.1 → 0.21.0

package/README.md

@@ -169,16 +169,46 @@ store(new PostgresStore({ host: "localhost", database: "myapp", user: "postgres"
 
 Custom store implementations must fulfill the `Store` interface contract (see [CLAUDE.md](../../CLAUDE.md) or the source for details).
 
+### Cache
+
+Cache is always-on with `InMemoryCache` as the default. It avoids full event replay on every `load()` by storing the latest state checkpoint in memory. On `load()`, the cache is checked first — only events committed after the cached position are replayed from the store. Actions update the cache automatically after each successful commit and invalidate on concurrency errors.
+
+```typescript
+import { cache } from "@rotorsoft/act";
+
+// Cache is active by default (InMemoryCache, LRU, maxSize 1000)
+// load() and action() use it transparently — no setup needed
+
+// Replace with a custom adapter (e.g., Redis) for distributed caching:
+cache(new RedisCache({ url: "redis://localhost:6379" }));
+```
+
+The `Cache` interface is async, so you can implement adapters backed by Redis or other external caches. `InMemoryCache` is included as a fast, in-process LRU implementation.
+
+#### Snapshots vs Cache
+
+Cache and snapshots are the same checkpoint pattern at different layers:
+
+- **Cache** (in-memory) — checked first on every `load()`. Eliminates store round-trips entirely on warm hits.
+- **Snapshots** (in-store) — written to the event store as `__snapshot__` events. Used as a fallback on cache miss (cold start, eviction, process restart) to avoid replaying the entire event stream.
+
+On cache hit, snapshot events in the store are skipped (`with_snaps: false`). On cache miss, the store is queried with `with_snaps: true` to find the latest snapshot and replay only events after it.
+
 ### Performance Considerations
 
+- **Cache is always-on** — warm reads skip the store entirely, delivering consistent throughput (7-46x faster than uncached). No configuration needed.
+- **Use snapshots for cold-start resilience** — on process restart or LRU eviction, snaps limit how much of the event stream must be replayed. Set `.snap((s) => s.patches >= 50)` for most use cases.
+- **Cache invalidation is automatic** — concurrency errors (`ERR_CONCURRENCY`) invalidate the stale cache entry, forcing a fresh load from the store on the next access.
+- **Snap writes are fire-and-forget** — `snap()` commits to the store asynchronously after `action()` returns. The cache is updated synchronously within `action()`, so subsequent reads see the post-snap state immediately without waiting for the store write.
+- **Atomic claim eliminates poll→lease overhead** — `claim()` fuses discovery and locking into a single SQL transaction using `FOR UPDATE SKIP LOCKED`, saving one round-trip per drain cycle and eliminating contention between workers.
 - Events are indexed by stream and version for fast lookups, with additional indexes on timestamps and correlation IDs.
-- Use snapshots for states with long event histories to avoid full replay on every load.
 - The PostgreSQL adapter supports connection pooling and partitioning for high-volume deployments.
-- Active event streams remain in fast storage; consider archival strategies for very large datasets.
+
+For detailed benchmark data and performance evolution history, see [PERFORMANCE.md](PERFORMANCE.md).
 
 ## Event-Driven Processing
 
-Act handles event-driven workflows through stream leasing and correlation, ensuring ordered, non-duplicated event processing without external message queues. The event store itself acts as the message backbone — events are written once and consumed by multiple independent reaction handlers.
+Act handles event-driven workflows through atomic stream claiming and correlation, ensuring ordered, non-duplicated event processing without external message queues. The event store itself acts as the message backbone — events are written once and consumed by multiple independent reaction handlers.
 
 ### Reactions
 
@@ -196,27 +226,28 @@ const app = act()
 
 Resolvers dynamically determine which stream a reaction targets, enabling flexible event routing without hardcoded dependencies. They can include source regex patterns to limit which streams trigger the reaction.
 
-### Stream Leasing
+### Stream Claiming
 
-Rather than processing events immediately, Act uses a leasing mechanism to coordinate distributed consumers. The application fetches events and pushes them to reaction handlers by leasing correlated streams:
+Rather than processing events immediately, Act uses an atomic claim mechanism to coordinate distributed consumers. The `claim()` method atomically discovers and locks streams in a single operation using PostgreSQL's `FOR UPDATE SKIP LOCKED` pattern — competing consumers never block each other, and locked rows are silently skipped. This is the same pattern used by pgBoss, Graphile Worker, and other production job queues.
 
 - **Per-stream ordering** — Events within a stream are processed sequentially.
-- **Temporary ownership** — Leases expire after a configurable duration, allowing re-processing if a consumer fails.
-- **Backpressure** — Only a limited number of leases can be active at a time, preventing consumer overload.
+- **Temporary ownership** — Claims expire after a configurable duration, allowing re-processing if a consumer fails.
+- **Zero-contention** — `FOR UPDATE SKIP LOCKED` means workers never block each other; locked rows are silently skipped.
+- **Backpressure** — Only a limited number of claims can be active at a time, preventing consumer overload.
 
-If a lease expires due to failure, the stream is automatically re-leased to another consumer, ensuring no event is permanently lost.
+If a claim expires due to failure, the stream is automatically re-claimed by another consumer, ensuring no event is permanently lost.
 
 ### Event Correlation
 
 Act tracks causation chains across actions and reactions using correlation metadata:
 
 - Each action/event carries a `correlation` ID (request trace) and `causation` ID (what triggered it).
-- Reactions can discover new streams to process by querying uncommitted events with matching correlation IDs.
+- `app.correlate()` scans events, discovers new target streams via reaction resolvers, and registers them with `subscribe()`. It returns `{ subscribed, last_id }` where `subscribed` is the count of newly registered streams.
 - This enables full workflow tracing — from the initial user action through every downstream reaction.
 
 ```typescript
-// Correlate events to discover new streams for processing
-await app.correlate();
+// Correlate events to discover and subscribe new streams for processing
+const { subscribed, last_id } = await app.correlate();
 
 // Or run periodic background correlation
 app.start_correlations();
@@ -243,12 +274,12 @@ app.settle();
 
 // Subscribe to the "settled" lifecycle event
 app.on("settled", (drain) => {
-  // drain has { fetched, leased, acked, blocked }
+  // drain has { fetched, claimed, acked, blocked }
   // notify SSE clients, update caches, etc.
 });
 ```
 
-Drain cycles continue until all reactions have caught up to the latest events. Consumers only process new work — acknowledged events are skipped, and failed events are re-leased automatically.
+Drain cycles continue until all reactions have caught up to the latest events. Consumers only process new work — acknowledged events are skipped, and failed streams are re-claimed automatically.
 
 The `settle()` method is the recommended production pattern — it debounces rapid commits (10ms default), runs correlate→drain in a loop until the system is consistent, and emits a `"settled"` event when done.