@rotorsoft/act 0.34.0 → 0.35.0

package/README.md

@@ -74,6 +74,11 @@ const app = act().withSlice(CounterSlice).build();
 - [API Reference](https://rotorsoft.github.io/act-root/docs/api/)
 - [Examples](https://github.com/rotorsoft/act-root/tree/master/packages)
 
+## Performance
+
+- [PERFORMANCE.md](./PERFORMANCE.md) — historical optimizations, batched projection replay, and the **[Reaction latency](./PERFORMANCE.md#reaction-latency-act-103)** section answering "how long from `do()` to reaction firing?"
+- [BENCH.md](../../BENCH.md) — index of every benchmark in the workspace with run commands and current numbers.
+
 ---
 
 ## Event Store
@@ -337,6 +342,28 @@ Stores **self-filter** their own commits (per-instance UUID in the payload) so t
 
 `notify` is a hint, not a contract: if the store doesn't implement it, or a notification is dropped, the existing debounce/poll path still drains correctly. Build-time contract: inject the configured store via `store(adapter)` *before* `act()...build()` — wiring binds at construction.
 
+### Reaction Priority Lanes (ACT-102)
+
+When the worker is saturated (more lagging streams than `streamLimit` per cycle), priority biases which lagging stream gets the lease first:
+
+```ts
+.on("OrderConfirmed")
+  .do(sendCriticalNotification)
+  .to({ target: "notifications-out", priority: 10 })  // jumps the lagging queue
+```
+
+`claim()`'s lagging frontier orders by `priority DESC, at ASC`. Default priority is `0` — apps that don't opt in see no behavior change. **Per-stream event ordering is unchanged** — priority only biases *which streams claim() picks first*, never reorders events within a stream.
+
+Operators can override scheduling at runtime with `app.prioritize(filter, n)`. Filter shape mirrors `query_streams` (regex on `stream`/`source`, exact-match flags, `blocked` state). Sets the priority outright, ignoring the build-time max invariant — so it can decrease too:
+
+```ts
+await app.prioritize({ stream: "^proj-orders$", stream_exact: false }, 10);
+await app.prioritize({ source: "^audit-" }, -5);
+await app.prioritize({}, 0);   // reset all to default
+```
+
+Only meaningful under saturation. With `streamLimit` ≥ candidate streams every cycle, every stream gets a slot every cycle and priority never binds. See [`@rotorsoft/act-pg/PERFORMANCE.md`](../act-pg/PERFORMANCE.md) for the ~11× speedup benchmark on tied-watermark replays under heavy contention.
+
 ## Dual-Frontier Drain
 
 In event-sourced systems, consumers often subscribe to multiple event streams that advance at different rates: some produce bursts of events, while others stay idle for long periods. New streams can also be discovered while processing events from existing streams.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rotorsoft/act",
   "type": "module",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "act core library",
   "author": "rotorsoft",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@rotorsoft/act-patch": "^1.1.0"
+    "@rotorsoft/act-patch": "^1.2.0"
   },
   "peerDependencies": {
     "zod": "^4.4.3"
@@ -44,6 +44,9 @@
     "clean": "rm -rf dist",
     "types": "tsc --build tsconfig.build.json --emitDeclarationOnly",
     "build": "pnpm clean && tsup && pnpm types",
+    "bench:micro": "vitest bench --run",
+    "bench:scenarios": "vitest run --config vitest.bench.config.ts",
+    "bench:latency": "vitest run --config vitest.bench.config.ts bench/reaction-latency.bench.ts",
     "bench:run": "NODE_ENV=test LOG_LEVEL=fatal tsx scripts/perf-bench.ts > perf-result.json",
     "bench:check": "tsx scripts/perf-check.ts",
     "bench:update": "NODE_ENV=test LOG_LEVEL=fatal tsx scripts/perf-bench.ts > perf-baseline.json",