Behavior-contract checklist
A documented runtime guarantee is a lie until a test fails when it stops
holding. The with_snaps regression (#1024) shipped a doc/intent that had
quietly diverged from the code because nothing executable pinned the claim.
This page is the antidote: every load-bearing behavioral claim Act makes in
its docs and port doc-comments, mapped to the test that enforces it.
The rule that follows from it lives in the pre-handoff workflow: a doc claim about runtime behavior ships with its test. When you add or change a claim here, add or update the row.
Scope is deliberately narrow — load-bearing guarantees a caller or adapter
author would rely on, not every sentence in the docs. Adapter-level claims are
backed in the TCK (libs/act-tck/src/store-tck.ts) so they run against
InMemory, Postgres, and SQLite at once; orchestrator and builder claims are
backed by unit/integration specs under libs/act/test/.
Cache and snapshots
| Claim | Source | Backing test |
|---|---|---|
seed() is the schema maintenance story: additive, idempotent, lossless on any prior released shape, and safe to run on every boot from every worker (advisory-locked on Postgres for concurrent cold boots) | writing-a-store.md § The store schema is the framework's job; extension-points.md | act-pg + act-sqlite seed-upgrade.spec.ts → "upgrades the oldest supported shape losslessly and idempotently", "serializes concurrent cold boots on an empty schema" (#1140) |
On Postgres, streams.retry is int (widened from smallint via the seed ladder), so a persistently-failing blockOnError: false stream whose retry counter climbs unbounded never overflows claim()'s retry + 1 update — matching the unbounded SQLite/InMemory adapters | writing-a-store.md § The store schema is the framework's job | act-pg retry-overflow.spec.ts → "claims a stream whose retry sits at the old smallint ceiling"; seed-upgrade.spec.ts → "upgrades the oldest supported shape…" (asserts retry migrated to integer) (#1190) |
with_snaps: true resumes from the latest snapshot per stream — in both scan directions (forward resumes at the snapshot, backward stops at it); an explicit after overrides the floor; a stream with no snapshot returns full history. The store applies the floor whenever with_snaps is set and does not cross-check bounds — the caller owns eligibility (RFC 1274) | cache-and-snapshots.md, Store.query doc | store-tck.ts → "with_snaps resumes from the latest snapshot per stream", "with_snaps applies the resume floor on a backward scan too" |
Cold start absorbs the snapshot event into state and resets patches to 0 (snaps increments) | cache-and-snapshots.md "How the two interact on cold start" | event-sourcing.spec.ts → "should load from a snapshot event on cold start" |
| Snapshot writes are fire-and-forget; a snap failure does not propagate | cache-and-snapshots.md "Snapshot creation" | event-sourcing.spec.ts → "should not throw on snap error and warn with stream, reason, and hint" |
| A snapshot write failure never fails the action and is surfaced at warn level with the stream, reason, and full-replay hint | cache-and-snapshots.md "Snapshot creation" | event-sourcing.spec.ts → "should complete the action and warn when the snapshot write fails" |
A successful snap predicate commits a __snapshot__ event | cache-and-snapshots.md | event-sourcing.spec.ts → "should persist snapshot event on snap success" |
| Cache miss populates the cache; a warm hit replays nothing older | cache-and-snapshots.md "Read path" | cache.spec.ts → "cache miss populates cache on load" |
A warm cache hit resumes with with_snaps ({ after: cached.event_id, with_snaps: true }), so a rebaselining __snapshot__ landing above a stale checkpoint is still folded — even after a windowed close pruned the domain events between the checkpoint and that snapshot. Without it the fold silently applies the surviving tail on top of stale state while version still reports the true head (guard passes → silent corruption) | cache-and-snapshots.md "Read path"; event-sourcing.ts load doc | close-windowed.spec.ts → "warm reload after a prune folds through the rebaselining snapshot (#1345)"; optimizations.spec.ts → "a cache-warm load queries with after and replays zero rows" |
The cache is invalidated only on ConcurrencyError | cache-and-snapshots.md "Cache invalidation — narrow contract" | cache.spec.ts → "cache invalidated on ConcurrencyError" |
| Invariant / validation failures (no commit) leave the warm cache untouched | cache-and-snapshots.md "Anything else … leaves the cache untouched" | cache.spec.ts → "invariant failure leaves the warm cache untouched", "validation failure leaves the warm cache untouched" (gap filled — #1029) |
A cache.set rejection is logged, not fatal to the action | cache-and-snapshots.md | cache.spec.ts → "cache.set rejection is logged but does not fail the action" |
Time-travel (asOf) bypasses cache read and write, and ignores snapshots outside the cutoff for every bound — before (id), created_before/created_after (timestamp), and limit. The orchestrator drops with_snaps under any asOf bound so the load full-scans under its filter instead of jumping to a snapshot outside the window (RFC 1274) | cache-and-snapshots.md "Time-travel reads" | time-travel.spec.ts → "should not read from cache…", "should not write to cache…", "should not use snapshots…", and the "time-travel ignores snapshots outside the cutoff (RFC 1274)" matrix (before / limit / created_before / created_after) |
query_stats head/tail never carry pii — it is an operator-introspection surface with no actor context and no disclosure gate, so it omits the pii sidecar on every adapter (matching load's default-deny for un-gated reads, #1277/#1294) | extension-points.md § Store; ports.ts Store.query_stats doc | store-tck → "query_stats head/tail never carry pii — introspection surface is pii-safe (#1294)" (runs on every pii-capable adapter); act-sqlite pii-encryption.spec.ts → "never carries pii on query_stats head/tail" |
Reactions, drain, and errors
| Claim | Source | Backing test |
|---|---|---|
On Postgres, event ids become visible in id order — the append path (commit, truncate) holds a transaction-scoped advisory lock so a concurrent cross-stream commit can never surface below an id a watermark consumer already acked past | concurrency-model.md § Commit visibility ordering | act-pg commit-visibility.spec.ts → "a commit waits for an in-flight append transaction to finish", "truncate seeds take the same visibility lock" (#1178) |
reactingTo is auto-injected when a reaction handler omits it; an explicit value is respected | CLAUDE.md safety one-liner; state-management.md | reacting-to.spec.ts → "should auto-inject reactingTo when handler omits it", "should respect explicit reactingTo when provided" |
NonRetryableError forces a block on the first attempt when blockOnError is true (default) | error-handling.md "Non-retryable errors" | non-retryable.spec.ts → "blocks on first attempt when blockOnError is true (default)" |
NonRetryableError does not override blockOnError: false | error-handling.md; CLAUDE.md safety one-liner | non-retryable.spec.ts → "ignores NonRetryableError when blockOnError is false" |
A worker whose lease was stolen mid-handler gets a short ack return, and the drain reports the difference rather than discarding the round silently | concurrency-model.md § Observability | non-retryable.spec.ts → "reports the round of work the stolen lease discarded"; act-pg lease-loss.spec.ts (same, over a real store); store TCK → "drops the ack of a holder whose lease was taken, and accrues retry per claim" (#1418) |
A stream arriving at claim with retry strictly greater than maxRetries blocks before dispatch — the budget was spent with no error, so only lease loss can explain it. retry === maxRetries still runs its final attempt, and blockOnError: false still retries forever | concurrency-model.md § When every attempt loses its lease; error-handling.md § Blocked Streams | non-retryable.spec.ts → "blocks the stream once the budget is spent with no error raised", "control — a claim at exactly maxRetries still gets its attempt", "control — blockOnError:false still means retry forever"; act-pg lease-loss.spec.ts (same four, over a real store) (#1418) |
| Per-reaction backoff defers retry until the window elapses (persisted per-stream schedule) | error-handling.md "Backoff" | backoff.spec.ts → "defers retry until backoff window elapses (persisted schedule)" |
| Backoff entry clears on a successful ack | error-handling.md | backoff.spec.ts → "clears backoff entry on successful ack" |
| Backoff still blocks when retries are exhausted | error-handling.md | backoff.spec.ts → "preserves blocking behavior when retries are exhausted" |
compute_backoff_delay strategy/clamp/jitter semantics | error-handling.md | backoff.spec.ts → compute_backoff_delay unit block |
Backoff persists deferred_at and is honored precisely — decoupled from leaseMillis (the due-ack releases the lease), so no mid-window re-claim phantom-bumps retry | error-handling.md "Backoff"; CLAUDE.md "Reaction backoff is a persisted per-stream schedule" | backoff.spec.ts → "backoff window is honored precisely via persisted deferred_at, not the lease duration (#1262)" |
A backoff-style due-ack persists the lease's retry (budget survives the window); an explicit defer passes retry: -1 (a defer is not a failure) | ports.ts ack doc-comment; error-handling.md "Backoff" | store-tck → "persists the lease's retry on a backoff-style due lease (#1262)" / "holds the watermark and resets retry on an explicit-defer due lease (retry: -1)" |
A due-marked ack advances the watermark to at and persists the schedule — advance and defer are independent legs, so a partial-progress backoff/defer keeps the handled prefix (it never re-runs) while the failing tail waits for deferred_at | reaction.ts Lease.due doc; error-handling.md "Backoff" § Per-stream schedule | store-tck → "advances the watermark to at while persisting the schedule on a partial-progress due lease (#1278)"; backoff.spec.ts → "advances the watermark past the succeeded prefix AND persists the window on partial progress (#1278)" |
A batch that makes partial progress and then blocks (handled > 0 and block: true — e.g. a NonRetryableError on the tail event) lands in both acked and blocked in the same cycle: the watermark advances past the succeeded prefix and the stream blocks. block finalizes before ack because ack releases the lease block's WHERE clause requires — acking first would silently drop the block and re-run the permanently-failed tail next cycle | drain-cycle.ts finalize comment; error-handling.md "Non-retryable errors" | non-retryable.spec.ts → "blocks in the SAME cycle after partial progress — ack must not drop the block (#1296)" |
The settle loop records a circuit-breaker passed() only when its correlate actually probed the store (the app has dynamic resolvers). A static-reaction app's correlate is a no-op, so settle never closes an OPEN breaker off it — otherwise a settle during a store outage would re-close the breaker and let the drain hammer the down store; the breaker recovers via the drain claim's own passed()/failed() in half-open | act.ts breaker on_retry doc-comment; ACT-984 | settle-wakeup.spec.ts → "does not close an OPEN breaker when correlate did not probe the store" / "still closes the breaker when correlate probed the store (#1329)" |
app.unblock resumes a blocked stream from its watermark without replaying history; app.reset rewinds to -1 and replays everything (the resume-vs-rebuild distinction) | CLAUDE.md "Blocked-stream recovery"; error-handling.md | non-retryable.spec.ts → "recovers via app.unblock without replaying history"; rebuild.spec.ts → "should enable replay of projection after reset" (gap filled — #1065) |
correlate() arms the lane controllers when it subscribes new streams — the same contract reset/unblock honor — so a freshly-discovered dynamic target cannot starve on a lane whose worker disarmed before the subscription landed | correlation-and-drain.md | correlate-arm.spec.ts → "revives a lane that disarmed before the subscription landed" |
Correlate's cold-start checkpoint floors at watermark - back_scan (when dynamic resolvers exist) — a dynamic-resolver event committed but not correlated before a crash is re-scanned on restart instead of skipped past a busier stream's watermark | correlation-and-drain.md | correlate-cold-start.spec.ts → "still discovers a dynamic target committed-but-not-correlated before restart" (#1207) |
settle() never drops a wake-up requested while a cycle is running — the running cycle's finally re-arms the pending pass, so armed controllers cannot starve on an instance with no lane cycleMs and no polling | correlation-and-drain.md | settle-wakeup.spec.ts → "runs a cycle for a schedule() that fires while a cycle is in flight"; act.spec.ts → "re-arms a wake-up requested while a cycle is running (ACT-1205)" (#1205) |
| A state projection's flush precedes its watermark ack — a failed flush holds the watermark and the retry re-folds to the same rows (idempotent at-least-once) | projections-to-database.md | state-projection.spec.ts → "holds the watermark when flush fails and converges on retry" |
A state projection evicting under maxCachedStates pressure flushes the evictee first — eviction never loses folded work | projections-to-database.md | state-projection.spec.ts → "flushes the evictee before dropping it under maxCachedStates pressure" |
| A state projection rebuild writes one row per stream per flush round, not one per event | event-sourcing.md § Projection Rebuild | state-projection.spec.ts → "rebuilds in O(streams) upserts, not O(events)" |
| A state projection'''s first-sight load resumes from the latest snapshot floor and folds only the tail | projections-to-database.md § State projections | state-projection.spec.ts → "resumes the first-sight load from the latest snapshot" |
A cache entry's state equals the fold of events at or below its event_id — a guardless commit that lands past the loaded frontier invalidates instead of caching a gapped fold | cache-and-snapshots.md | cache-frontier.spec.ts → "never leaves a stale-at-head cache entry after guardless commits" |
A state projection's first-sight fold pairs the loaded state with the head event id load() returns atomically (Snapshot.id) — never a separate cache read, which could race a concurrent commit and pair older state with a newer id, permanently skipping the intervening events | cache-and-snapshots.md; projections-to-database.md | fold-frontier-toctou.spec.ts → "does not skip events when the cache frontier moves during first-sight load" (#1204) |
load() fire-and-forgets its checkpoint write: a failing cache.set is logged, not thrown — the read returns the correctly-computed state (matching action()'s fire-and-forget cache write) | cache-and-snapshots.md; extension-points.md § Cache | load-cache-error.spec.ts → "returns the correct state and swallows a failing cache.set" (#1206) |
action() rethrows a ConcurrencyError immediately when expectedVersion was caller-supplied — a pinned version is a fixed target that every retry re-conflicts on, so the budget and backoff are only spent on framework-derived versions | error-handling.md § Retry pattern | action-retry.spec.ts → "rethrows immediately without consuming the retry budget or sleeping (ACT-1208)" (#1208) |
The optimistic guard holds on warm cache hits — a concurrent plain action surfaces ConcurrencyError, never a silent append past unfolded events | concurrency-model.md | cache-frontier.spec.ts → "keeps the optimistic guard on warm cache hits" |
A cold load during the close guard window (tombstone committed, truncate pending) does not cache — leaving the entry cold keeps action()'s cold-path tombstone check live, so a subsequent action throws StreamClosedError instead of committing past the tombstone | concurrency-model.md; close-cycle.md | event-sourcing.spec.ts → "a cold load during the guard window keeps the tombstone check live" (#1188) |
| A snapshot event is only persisted from a contiguous fold, and the action awaits it and caches the snap checkpoint before returning — sequential callers never see a conflict caused by the framework's own bookkeeping | cache-and-snapshots.md | optimizations.spec.ts cadence + calculator.spec.ts lifecycle (fail on regression) |
Lanes drain in parallel — _drain_all runs every controller's drain() via Promise.all, so a stalled slow-lane handler does not block the fast lane | CLAUDE.md "Lanes give intra-process responsiveness"; configuration.md § Lanes | lanes.spec.ts → "drains lanes in parallel — a stalled slow handler does not block the fast lane" (gap filled — #1065) |
When onlyLanes excludes a declared lane (default or a .withLane name), the constructor logs a one-line advisory naming the orphaned lane(s); it stays silent when onlyLanes is unset or covers every declared lane — the cluster invariant is ∪ onlyLanes ⊇ declared lanes | configuration.md § onlyLanes; production-checklist.md § Sizing lanes | lanes.spec.ts → "orphaned-lane advisory" (#1220) |
A cold start re-seeds the defer timer from each still-future persisted deferred_at, so an idle deferred stream re-arms at its due-time with no intervening commit; a stream whose lane isn't active on this instance is skipped | close-cycle.md § Defer, not poll; writing-a-store.md § Deferring a stream; extension-points.md § query_streams | defer-durability.spec.ts → "re-seeds the DeferTimer", "re-arms the drain at the persisted due-time" (#1221) |
A defer outcome holds the triggering event pending — the drain does not advance the watermark past the deferred event and does not bump retry — then re-delivers once the persisted due-time passes (any fully-handled prefix ahead of the trigger still advances) | close-cycle.md § Defer, not poll; extension-points.md § defer | defer-outcome.spec.ts → "holds pending until the due-time, then redelivers and acks" (#1090) |
The registry is complete and frozen at act().build(): autoclose reactions are synthesized by the builder (not the orchestrator), and post-build mutation of the registry containers throws | close-cycle.md § Online close-the-books | registry-freeze.spec.ts → "freezes the registry containers at build", "synthesizes the autoclose reaction at build, not construction" (#1121) |
.autocloses closes a stream when its policy matches the live head, re-evaluates the live head so a reopened stream is not closed, parks on the cooldown while after has not elapsed, closes on a reaches threshold, and defers (not closes) outside the autocloseWindow | close-policies.md; close-cycle.md § Online close-the-books | autoclose-reaction.spec.ts → "closes immediately on the terminal event for an is policy", "evaluates the live head — a reopened stream is not closed", "parks on the cooldown instead of closing while after has not elapsed", "closes on the threshold event for a reaches policy", "respects the off-hours window — outside it, defers instead of closing" (#1090) |
When after has already elapsed but the AND-combined predicate is still unmet, .autocloses defers only to a future due-time — never a past one (which claim can't exclude, causing a per-cycle re-claim busy-loop); with no future due it returns and waits for the next event | close-policies.md; autoclose-reaction.ts dues doc-comment | autoclose-reaction.spec.ts → "does not defer to a PAST due-time when after has elapsed but the predicate is unmet (#1330)" |
.autocloses keys its terminate/reaches decision on the domain head and count (snapshots excluded from query_stats), and the full-close guard tombstones at the stream's true head version — so a policy fires correctly even when a __snapshot__ trails the terminal event (snap() commits it into the next version slot). Without both, is never matches the snapshot head and never recovers, reaches counts snapshot events, and the close-cycle skips the tombstone on a stale expected version | close-policies.md; close-cycle.md § Phase 1 | autoclose-reaction.spec.ts → "closes on the terminal event even when a snapshot trails it (is, #1356)", "counts only domain events toward reaches when snapshots trail (#1356)" |
On a DST spring-forward day whose autocloseWindow.start hour is skipped, the window still opens at the gap's replacement instant — in_autoclose_window admits it and next_window_open defers ~1 h to it, not ~24 h | close-policies.md § off-hours window | autoclose-builder.spec.ts → "opens ~1h out on a DST spring-forward day whose start hour is in the gap (#1233)", "in_autoclose_window is true at the DST gap replacement instant (#1233)" (#1233) |
The declarative .defer(when) builder step holds the reaction until its schedule is due, then runs the handler once (available on both act() and slice()) | state-management.md § Deferred reactions | declarative-defer.spec.ts → "literal { after } holds the reaction (handler not run, not acked)", "runs immediately once the schedule is already due", "is available on the slice() builder too" (#1091) |
The .defer function form reads the triggering event's payload to choose the schedule | state-management.md § Deferred reactions | declarative-defer.spec.ts → "function form reads the payload to choose the schedule, then runs" (#1091) |
Drain finalization is atomic: defer schedules ride the same Store.ack call as the acks (due-marked leases), so a failed finalize lands nothing — close requests are never lost, no watermark moves without its cycle's schedules | close-cycle.md § Defer, not poll; extension-points.md § Store; recipes/temporal/recurring-timers § Failure modes | defer-durability.spec.ts → "a failed finalize lands nothing — close requests are never lost", "persists the defer schedule in the same store call as the acks"; TCK store-tck.ts → describe("ack finalize (due-marked leases)") (#1124) |
A failed finalize never stalls a deferred stream: the controller stays armed and the next drain redelivers, so the handler re-throws its DeferSignal and the retried finalize persists the schedule | close-cycle.md § Defer, not poll | defer-durability.spec.ts → "keeps the drain armed while finalization is unhealed" (#1124) |
A malformed literal .defer(...) schedule (neither/both of after/at, or an empty duration) is rejected at build time with a ZodError | state-management.md § Deferred reactions | declarative-defer.spec.ts → "rejects a bad literal schedule at build time" (#1091) |
Imperative throw new DeferSignal(when) resolves the schedule against the triggering event and holds the stream until the due-time, then re-delivers and acks | state-management.md § The DeferSignal escape hatch | public-defer.spec.ts → "{ at: Date } holds until the due-time, then acts", "{ after } is measured from the event's created time (parks, not acked)" (#1091) |
Store contract (runs on all three adapters via the TCK)
| Claim | Source | Backing test |
|---|---|---|
subscribe is idempotent on repeat | Store.subscribe doc | store-tck.ts → "subscribes new streams and is idempotent on repeat" |
subscribe keeps the maximum priority when a stream is re-subscribed with a different priority | Store.subscribe priority doc-comment | store-tck.ts → "keeps the maximum priority when a stream is re-subscribed" (gap filled — #1029) |
A dynamic-resolver target's priority/lane obeys the runtime max() invariant across correlate scans — a later scan resolving a higher priority re-subscribes it (raising the store's priority + carrying the winning lane); a lower-or-equal resolution dedups without downgrading. The orchestrator's _subscribed map records the last-subscribed priority per target instead of a plain presence set, so the guarantee isn't frozen at first discovery | priority-lanes.md § "the same max() invariant holds at runtime" | correlate-lane.spec.ts → describe("cross-scan priority upgrade (#1363)"): "a later higher-priority scan raises the target's priority and lane", "a later lower-priority scan does NOT lower the target (max holds)" |
prioritize sets priority directly, overriding subscribe's max() rule | Store.prioritize doc | store-tck.ts → "sets priority directly, overriding subscribe's max() rule" |
unblock returns 0 when the stream is not blocked; reset/unblock return 0 for unknown/empty input | Store.unblock / Store.reset docs | store-tck.ts → "returns 0 when the stream is not blocked", "returns 0 for unknown streams and empty input" |
unblock clears the blocked flag and preserves the watermark; reset rewinds it to -1 (resume-vs-rebuild at the port level) | Store.unblock / Store.reset docs | store-tck.ts → "clears blocked flag and preserves the watermark", "rewinds a stream watermark to -1", "clears blocked status when resetting" (gap filled — #1065) |
truncate (full target) deletes events, removes the stream entry, and seeds a snapshot or tombstone | Store.truncate doc | store-tck.ts → truncate describe block |
A windowed truncate target (before) deletes only the prefix below the closest safe snapshot (latest __snapshot__ with created < before), keeps the snapshot + tail, seeds nothing, and leaves subscriptions untouched — the stream stays writable and readable | Store.truncate doc; extension-points.md § Store contract; writing-a-store.md § Truncating streams | store-tck.ts → describe("windowed (before boundary)"): "deletes the prefix below the closest safe snapshot and keeps the snapshot + tail", "leaves subscriptions untouched, unlike a full truncate", "keeps the stream writable and readable after a prune", "mixes full and windowed targets in one call" (#1011) |
The max_id cap on a windowed target is honored — the boundary never rises past a lagging consumer's watermark, so a lagging reaction degrades the prune, never loses data | Store.truncate doc; close-cycle.md § Windowed close | store-tck.ts → "honors the max_id cap — boundary never rises past a lagging consumer"; close-windowed.spec.ts → "caps the boundary at a lagging consumer's watermark" (#1011) |
A windowed target with no qualifying snapshot is a no-op: events untouched, stream absent from the truncate result, reported in CloseResult.skipped by the orchestrator | Store.truncate doc; close-cycle.md § Skipped semantics | store-tck.ts → "no-ops when no snapshot qualifies — stream absent from the result, events untouched"; close-windowed.spec.ts → "skips streams with no qualifying snapshot" (#1011) |
forget_pii wipes PII for every event and is idempotent (second call returns 0; no-PII stream returns 0) | Store.forget_pii doc | store-tck.ts → "wipes pii for every event on the stream via forget_pii", "is idempotent — second forget_pii returns 0, no error", "forget_pii on a stream with no pii events returns 0" |
Every gated external read — load, query, query_array — drops the isolated pii sidecar from the returned event; plaintext survives only inside data, and only on the authorized path. query/query_array carry no actor, so they default-deny ([REDACTED], [SHREDDED] post-forget) like a bare-string load. The single pii_gate produces the view; there is no raw read mode (#1277) | sensitive-data.md § Reading it back; IAct.load / query / query_array doc | read-gate.spec.ts → "the gated load event drops the pii sidecar" + "query / query_array default-deny PII gate (#1277)" block |
The projection fold engine applies the same PII treatment on its cold first-sight load() path as on its warm incremental path — sensitive keys are structurally stripped (removed, not [REDACTED]), so a folded PII-aware projection row is identical regardless of cache warmth, eviction, or rebuild timing | sensitive-data.md § Projections; pii_strip doc-comment | fold-pii-path.spec.ts → "cold-loaded and warm-folded rows of an identical history match" (#1320) |
query_streams reports maxEventId tracking the highest committed id | Store.query_streams doc | store-tck.ts → "maxEventId tracks the highest committed id" |
query_streams surfaces an active future deferred_at (ms since epoch) on a stream's position, so a cold start can read it and re-seed the defer timer | Store.query_streams / StreamPosition.deferred_at doc; writing-a-store.md; extension-points.md | store-tck.ts → describe("defer") → surfaces a future deferred_at on query_streams (#1221) |
claim skips a stream until its deferred_at passes, then makes it claimable again; a defer never bumps retry; reset clears a pending defer; a filter-form defer counts the streams it matched | Store.defer doc; extension-points.md § defer | store-tck.ts → defer describe block: "hides a stream from claim until its deferred_at passes", "makes a stream claimable once the deferred_at is in the past", "does not bump retry while a stream is deferred", "reset clears a pending defer", "defers streams matching a filter and counts matches" (#1090) |
Stream filters guarantee a portable grammar — ^ / $ anchors, ., .*, literal characters (including literal _ / %) — matching identically on every adapter; a richer pattern either matches with full regex semantics or throws ValidationError, never a silent approximation | QueryStreams.stream / StreamFilter / Query.stream docs; extension-points.md § Stream filters | store-tck.ts → "stream filter grammar" describe block: "portable subset: anchors, ., and .* match identically", "literal _ and % in patterns are not wildcards", "portable subset applies to stream-position filters", "non-portable patterns match with full regex semantics or throw", "bulk stream ops reject non-portable filters instead of mis-matching" (#1114) |
Stream/source filters match case-sensitively on every adapter — Postgres ~, InMemory RegExp, SQLite GLOB (not LIKE, whose ASCII case-insensitivity let ^order- overmatch Order-x) | writing-a-store.md § The contract (query bullet); extension-points.md § Stream filters | store-tck.ts → "stream filter grammar" describe block: "stream filters match case-sensitively" (#1197) |
An empty names: [] matches no events (explicit empty allow-list); an omitted names matches all | writing-a-store.md § The contract (query bullet); extension-points.md § Query edge inputs | store-tck.ts → "query" describe block: "names:[] matches no events" (#1199) |
Falsy-zero before: 0 / after: 0 are honored as strict id bounds (id < before / id > after), never dropped as falsy filters | writing-a-store.md § The contract (query bullet); extension-points.md § Query edge inputs | store-tck.ts → "query" describe block: "after:0 and before:0 are honored as id bounds" (#1199) |
A Date in event data round-trips as a Date on every adapter and through CsvFile — every JSON-persisting reader revives ISO-8601-shaped strings, including the bundled backup/restore source (#1399) | writing-a-store.md § The contract (query bullet); extension-points.md § payload Date revival | act-pg date-roundtrip.spec.ts; act-sqlite date-roundtrip.spec.ts (#1198); csv.spec.ts → "round-trips a Date in data through a store, not just CsvFile" (#1399) |
A Date in an event's pii field revives to a Date too — the pii read path runs the same reviver as data/meta, so a sensitive Date isn't a string on SQLite only | writing-a-store.md § The contract (query bullet, data/pii) | store-tck.ts → pii_isolation: "revives a Date in a pii field to a Date, like data (#1365)" (runs on every pii-capable adapter) (#1365) |
SQLite commit maps a (stream, version) unique-constraint violation to ConcurrencyError (parity with Postgres' 23505) and wraps every other driver error in StoreError('commit') | writing-a-store.md § The contract (commit bullet); extension-points.md § Invariants an adapter must hold | act-sqlite store.error.spec.ts → "maps a (stream,version) unique collision to ConcurrencyError" (#1202) |
claim matches a literal subscription source (no regex metacharacter) by string equality — a source s1 never matches a sibling stream s12, and it receives exactly its stream's events (drain fetch uses stream_exact for literals) | Store.claim / Store.subscribe docs; Resolved.source doc | store-tck.ts → describe("claim source matching"): "treats source as an exact stream name — no substring or pattern overmatch", "receives exactly its source stream's events", "fetches only the exact source stream's events, never a sibling prefix" (#1182 exact fix; #1220 fetch consistency — the overmatch case failed red on InMemory's unanchored-RegExp and SQLite's contains-LIKE probes before #1182's fix) |
claim matches a pattern source (one carrying regex metacharacters, e.g. `^(A | B)$) as a compiled regex against candidate streams, so a static regex-source reaction (the shipped calculator Board projection) is claimed for every stream it anchors; adapters that cannot run an arbitrary regex reject a non-portable claim source at subscribe` time | Store.claim / Store.subscribe docs; Resolved.source doc |
A lease timeout counts against the retry budget — reclaiming an expired lease increments retry no matter which worker reclaims it, and only ack resets the counter | concurrency-model.md § Timeout; Store.claim doc | store-tck.ts → "counts a timed-out lease reclaimed by another worker against the retry budget; ack resets it" (#1183 — the doc previously claimed the opposite; the code was right) |
| An unexpired lease is invisible to competing claimers; an expired lease is handed to exactly one of them, with the shared retry counter intact | concurrency-model.md § Timeout / lease lifecycle | store-tck.ts → concurrency (capability): "does not hand an unexpired lease to a competing claimer", "hands an expired lease to exactly one competing claimer, with retry accounting shared across workers" (#1184) |
A claim() locks only its own lagging+leading candidate rows, not the whole eligible frontier — two competing workers whose candidate sets are disjoint both win their full slice in the same concurrent round, instead of the first worker locking every claimable stream and starving the rest | concurrency-model.md § competing consumers ("gets the next available stream. Zero contention") | act-pg contention.spec.ts → "locks only the claimed candidates, not the whole eligible frontier (ACT-1201)" (#1201 — the available CTE previously held FOR UPDATE SKIP LOCKED with no LIMIT, so it materialized and locked the entire frontier) |
notify is self-filtering — an instance never receives its own commits, only a sibling instance's writing to the same backing store | Store.notify doc ("implementations must skip their own commits") | store-tck.ts → notify (capability): "does not deliver an instance's own commits (self-filtering)" (#1184 — promoted from adapter-local suites to the TCK so third-party stores can't badge conformance while echoing their own commits) |
notify delivers one notification per commit transaction, carrying the full ordered event batch | Store.notify doc; cross-process-reactions.md | store-tck.ts → notify (capability): "delivers one notification per commit transaction carrying the full event batch" (#1184) |
PostgresStore notify (adapter-specific — outside the TCK)
The portable notify contract (cross-instance delivery, self-filtering,
batch-per-commit) lives in the TCK's notify capability suite as of #1184.
What stays here is PostgreSQL plumbing the TCK can't express portably —
the LISTEN reconnect discipline and the 8000-byte NOTIFY payload cap —
pinned in libs/act-pg/test/.
| Claim | Source | Backing test |
|---|---|---|
notify is self-filtered per instance — a commit wakes other instances' listeners, never its own (the LISTEN handler skips payloads where by === this._by) | cross-process-reactions.md § Self-filter | notify.contract.spec.ts (act-pg) → "notify is self-filtered per instance — a commit wakes the other instance, never its own" (#1120) |
| An oversize NOTIFY payload (≥ 8000 bytes) skips the NOTIFY instead of aborting the commit — the commit succeeds and delivery falls back to the poll path, preserving at-least-once | cross-process-reactions.md § Payload cap | notify.contract.spec.ts (act-pg) → "oversize notify payload skips the NOTIFY — the commit succeeds and events stay discoverable via the poll path" (gap exposed a real bug, fixed — #1120) |
The dedicated LISTEN client carries an error listener, so a connection loss cannot crash the process; on error it tears the dead client down and re-LISTENs on a fresh one with capped exponential backoff, degrading to the poll path in between | cross-process-reactions.md § Connection loss — the LISTEN client self-heals | notify.resilience.spec.ts (act-pg) → "attaches an error listener…", "self-heals: on client error it tears down the dead client and re-LISTENs on a fresh one", "grows the backoff on repeated failures and resets it after a healthy reconnect" (#1189) |
| A pending reconnect is cancelled by disposal (or a re-subscribe) — no reconnect fires after teardown | cross-process-reactions.md § Connection loss — the LISTEN client self-heals | notify.resilience.spec.ts (act-pg) → "dispose during a pending reconnect cancels it — no client is checked out after teardown" (#1189) |
The dead LISTEN client keeps an error listener across the whole reconnect window — a second socket error on teardown (in-flight LISTEN rejection, then ECONNRESET/end) is swallowed, not re-raised as an uncaught exception; a re-entrant reconnect cancels the pending timer so two never race to re-LISTEN | cross-process-reactions.md § Connection loss — the LISTEN client self-heals | notify.resilience.spec.ts (act-pg) → "a SECOND error on the dead client during the backoff window does not crash the process", "repeated reconnect cycles return the checked-out and listener counts to baseline", "a re-entrant reconnect cancels the pending timer instead of leaking a second one" (regression fix — #1231) |
Receiver idempotency (act-http / act-ops — two-phase claim)
The receiver-side IdempotencyStore is two-phase: claim reserves a key
tentatively, and the caller confirms the outcome with commit (durable) or
release (drop). The load-bearing guarantee is that a transient handler
failure does not permanently drop the delivery — the sender's retry
re-processes instead of being deduped into a silent success (#1193).
| Claim | Source | Backing test |
|---|---|---|
claim is tentative; commit makes a key survive so a retry dedups, release drops an uncommitted claim so a retry re-processes, release after commit is a no-op, and committed entries still expire on TTL | external-integration.md § The IdempotencyStore port; IdempotencyStore doc-comment | act-ops in-memory.spec.ts → describe("two-phase commit / release"): "release drops an uncommitted claim so a retry re-processes", "commit makes a claim survive so a retry dedups", "release after commit is a no-op", "committed entries still expire after ttlMs" (#1193) |
The receiver builder releases the claim on a handler throw (retry re-runs the handler) and commits on success (retry dedups); a concurrent duplicate mid-flight is still deduped | external-integration.md § status table (500 row); receiver builder | act-http receiver/start.spec.ts → "re-runs the handler on retry after a transient handler failure (no lost delivery)", "dedups a retry after a successful delivery (handler runs exactly once)", "dedups a concurrent duplicate that arrives while the handler is in flight" (#1193) |
The wrapping adapters (Hono, tRPC) auto-finalize off the downstream outcome — commit on a 2xx / resolved result, release on a 5xx / thrown / { ok: false } result; Express and Fastify expose commit/release on the request context for the handler to call | external-integration.md § Composing into an existing app | act-http receiver/{hono,trpc,express,fastify}/index.spec.ts (auto-commit/release + commit/release finalize cases); receiver/finalize.spec.ts → make_finalizers finalize-once + deduped-inert (#1193) |
withIdempotency (generated API) commits after the handler resolves and releases + re-throws when it rejects | api/idempotency.ts withIdempotency doc-comment | act-http api/idempotency.spec.ts → "commits the key after the handler succeeds", "releases the key and propagates handler rejections after a fresh claim" (#1193) |
SSE subscription wiring (act-http — bounded backlog, slot accounting)
The shared runSseSubscription loop bounds each connection's undelivered-frame
backlog and pairs every slot release with a prior acquire, so one stalled
consumer can't grow memory without bound and a cap-full subscription can't
underflow the connection counter (#1196).
| Claim | Source | Backing test |
|---|---|---|
The per-connection pending backlog is bounded by maxPendingPerConnection (default 256, drop-oldest): a stalled consumer flooded past the bound retains only the newest N frames | auto-generated-api.md § Defaults and validation; SseOptions.maxPendingPerConnection doc-comment | act-http api/sse-wiring.spec.ts → "bounds the per-connection pending buffer, dropping the oldest when a slow consumer stalls" (#1196) |
A subscription that fails to acquire a slot (cap full, no on_cap_exceeded) releases nothing on teardown — only an acquired slot is released, so the counter never underflows below the true open count | auto-generated-api.md § SSE flow (teardown); runSseSubscription doc-comment | act-http api/sse-wiring.spec.ts → "does not release a slot it never acquired when the cap is full and no on_cap_exceeded is supplied" (#1196) |
An overlay() frame (_overlay: true, keyed at the current version) is merged onto a caught-up client's state by applyPatchMessage, keeping _v; a same-version message WITHOUT the marker is still stale | real-time.md § Overlays / § Client-side; PatchMessage._overlay + applyPatchMessage doc-comments | act-http sse/apply-patch.spec.ts → "merges a marked overlay at the current version, keeping _v" / "still treats a same-version patch WITHOUT the marker as stale" (#1312) |
openapi() emits a document for any registry hono() serves — an action-input field whose Zod type has no JSON-Schema form (z.date/z.bigint/z.map/…) emits an open ({}) schema (unrepresentable: "any"), never aborting the whole doc | auto-generated-api.md § OpenAPI; openapi/index.ts conversion doc-comment | act-http openapi/index.spec.ts → "emits an open schema for a z.date() field instead of aborting the doc (#1328)" |
Orchestrator and builders
| Claim | Source | Backing test |
|---|---|---|
app.reset() arms the orchestrator's drain flag, so a settled app still replays (store().reset() alone does not) | CLAUDE.md safety one-liner; event-sourcing.md | rebuild.spec.ts → "should replay events when drain runs after reset on a settled app" |
reset resets watermarks to -1 and unblocks blocked streams | Store.reset doc | rebuild.spec.ts → "should reset subscribed stream watermarks to -1", "should unblock blocked streams after reset" |
A static .emit() of a deprecated event version throws at build | event-schema-evolution.md; CLAUDE.md safety one-liner | deprecation.spec.ts → "throws when an action statically emits a deprecated event" |
Two event names in one version group that map to the same numeric version (e.g. a leading-zero Foo_v02 alongside Foo_v2) are rejected at build with a clear, order-independent error — never silently deprecating whichever declares second | event-schema-evolution.md § The versioning convention is the deprecation signal | deprecation.spec.ts → "rejects a leading-zero version colliding with its canonical form regardless of order (#1234)" (#1234) |
Single-key records (.on, state(...)) throw on zero or multiple keys | CLAUDE.md safety one-liner; state-management.md | state-builder.spec.ts → "should throw when .on() receives multiple keys", "should throw when record has more than one key", "should throw when record has zero keys" |
| Same-name state partials sharing an event must reference the same Zod schema instance; mismatched references throw | CLAUDE.md safety one-liner; state-management.md | slice.spec.ts → "throws when same-name state partials use different schema references for the same event" |
| Scoped Acts keep per-Act store and cache isolated (no cross-talk) | CLAUDE.md safety one-liner; extension-points.md | scope.spec.ts → "two Acts with their own scoped ports — no cross-talk", "scoped cache keeps per-Act snapshots isolated" |
A scoped Act's background paths — settle-driven correlate init, the start_correlations poll timer, and per-lane worker ticks — resolve store()/cache() to the scoped ports, not the singleton: static targets subscribe and drains run on the scoped store | CLAUDE.md "Per-Act scoped ports"; extension-points.md § Scoped ports | scope.spec.ts → "settle() subscribes static targets on the scoped store, not the singleton", "start_correlations polls against the scoped store, not the singleton", "lane worker ticks drain against the scoped store, not the singleton" (#1191) |
Cross-process reactions: the orchestrator auto-wires Store.notify at construction when the store supports it and reactive events exist; it does not wire when the store lacks notify or there are no reactive events | CLAUDE.md "Cross-process reactions"; cross-process-reactions.md | notify.spec.ts → "subscribes when store has notify and reactions exist", "does not subscribe when store lacks notify", "does not subscribe when there are no reactive events" (gap filled — #1065) |
| A windowed close leaves the cache untouched and the stream live — no invalidation on prune, and the stream keeps accepting actions | close-cycle.md § Windowed close; IAct.close doc-comment | close-windowed.spec.ts → "prunes the prefix behind the boundary snapshot and keeps the stream live", "leaves the cache untouched — no invalidation on prune" (#1011) |
Two windowed closes racing the same stream (a manual app.close({ before }) and an autoclose windowed close bypass each other's lease) fire the archive callback at most once per pruned range — serialized by a per-stream lock, the second closer sees the already-pruned prefix and skips | close-cycle.md § Why there is no head guard, but there is a per-stream lock; close-policies.md § The archive contract | close-windowed.spec.ts → "fires the archive callback at most once when two windowed closes race the same stream" (#1222) |
.autocloses({ keep }) requires .snap(...) earlier in the chain — type-gated on the ActionBuilder, with a runtime throw backstopping untyped callers — and rejects windows below one day and keep inside or | close-policies.md § keep; AutoclosePolicy.keep doc-comment | autoclose-builder.spec.ts → describe(".autocloses({ keep }) — rolling window"): "requires .snap earlier in the chain — the runtime guard for untyped callers", "gates keep behind .snap at the type level", "rejects windows below one day — close is low-cadence housekeeping", "rejects keep inside the or block" (#1011) |
A stream is never acked past an event while any reaction on it is unhandled — a mid-group failure holds the watermark, redelivers the whole group (already-succeeded reactions re-run, at-least-once), and counts as no progress so the retry counter marches toward blockOnError | error-handling.md § Retry pattern; concurrency-model.md at-least-once | intra-event-ack.spec.ts → "holds the watermark when a later reaction on the same event fails", "acks the group once every reaction on the event succeeds", "keeps cross-event partial progress — completed events ack, the failing group holds" (#1179) |
A keep prune is staged only once the stream's oldest domain event ages out of the window; otherwise the reaction defers to tail.created + keep, and a terminate match takes precedence (full close) with terminate and prune staying independent | close-policies.md § keep; close-cycle.md § Online close-the-books | autoclose-reaction.spec.ts → describe("autoclose rolling window (keep)"): "defers while the window holds, prunes once the tail ages out", "terminate and prune stay independent — is full-closes even with keep declared", "passes the cutoff to the archiver on a windowed close", "skips the prune when no snapshot qualifies, retrying next trigger" (#1011) |
With validateFoldedState, a reducer producing schema-violating state throws a ValidationError at the triggering event (message names <state>.<event>#<id>) on the command, cold-replay, and projection-fold paths; with the flag off (default) the same reduction produces the bad state and does not throw | configuration.md § Debugging: validating folded state; ActOptions.validateFoldedState doc-comment | validate-folded-state.spec.ts → "throws at the triggering event when a reducer produces schema-violating state", "names the state and the triggering event in the error", "does NOT throw and produces the bad state when the flag is off (default)", "catches the bad state on cold replay, not only on the committing action", "validates folded projection state (make_fold_handler) on replay" (#1238) |
A throwing lifecycle listener is contained: the drain cycle still finalizes, the remaining sinks still fire, drain() returns its real result, and no error (circuit-breaker) event is emitted — observer failures are never the cycle's failure — and containment covers the emits only: a StoreError raised inside on_close's close machinery still reaches the circuit breaker, which records passed() only after the close succeeds | observability.md § Two things to know; drain-cycle.ts finalize | non-retryable.spec.ts → "keeps emitting blocked when an acked listener throws", "contains a throwing blocked listener without losing the ack"; autoclose-reaction.spec.ts → "contains a throwing closed listener without failing the cycle", "surfaces a store failure inside the close as an error event" (#1373, #1388) |
The settled payload accumulates every pass of the settle, so it reports what the whole settle did — the union of its passes matches, lease for lease, what the dedicated acked/blocked listeners saw. It is NOT the final (no-progress) pass alone | observability.md § The lifecycle events | settle-wakeup.spec.ts → "reports the work the settle did, not its final empty pass" (#1383) |
Store.block returns the post-block row, not the caller's lease: the returned at is the durable watermark (a block never advances it), even when the drain hands in a lease whose at was fast-forwarded to the fetch ceiling | Store.block doc; Lease.at ("last successfully processed event ID") | store-tck.ts → "returns the post-block row, not the caller's lease (#1382)" (#1382, #1347) |
A durably blocked stream emits exactly one blocked lifecycle event, even if the ack that follows the block fails — the emit happens as soon as block confirms, because block is guarded on blocked = false and a blocked stream is excluded from claim, so it never runs again | drain-cycle.ts finalize; Store.block doc | non-retryable.spec.ts → "emits blocked even when the following ack fails" (#1390) |
Correlate's one-shot init() is retryable: a store failure during the static-target subscribe does not latch, so a later correlate()/settle() re-runs it and the reactions come up. Concurrent callers share one in-flight init | CorrelateCycle.init doc | correlate-cold-start.spec.ts → "subscribes static targets on a retry after subscribe throws", "shares one init across concurrent callers (single-flight)" (#1387) |
An SSE _overlay frame is version-neutral and is classified exhaustively: caught-up merges keeping _v, ahead by ANY amount (including exactly one) reports behind, below the baseline reports stale, and no baseline reports behind. An overlay never reaches the contiguous fold, so its payload is never adopted as a version's domain patch | real-time.md § Overlays | apply-patch.spec.ts → "frame kind × version position" matrix (#1312, #1346, #1419) |
A _resync frame carries no versions and always reports behind, so a client refetches rather than treating it as stale. overlay() emits one when the stream's baseline has been evicted from the LRU, instead of silently broadcasting nothing | real-time.md § Overlays; RFC 1434 | broadcast.spec.ts → "a resync frame makes the client refetch rather than go stale", "reports an overlay whose baseline was evicted" (#1423) |
Gaps closed by #1029
Two load-bearing claims had no executable backing before this checklist:
- Cache narrow-invalidation, negative half. The docs guarantee that
invariant / validation failures leave the warm cache untouched (only
ConcurrencyErrorinvalidates). Nothing tested the negative case — a regression that invalidated on every throw would have passed CI. Closed incache.spec.ts. subscribemax-priority merge. TheStore.subscribedoc-comment mandates that re-subscribing a stream keeps the maximum priority so the highest-priority reaction wins. No adapter test enforced it; a last-write-wins regression on any adapter would have shipped silently. Closed instore-tck.ts(runs on InMemory, Postgres, SQLite).
No documented claim was found to be false against the code during this audit; both gaps were missing tests for behavior that already held.
Audit closed by #1065
#1029 seeded the checklist; #1065 walked the remaining load-bearing
documented runtime guarantees to exhaustion. Most already had backing tests
that were simply not yet recorded here — the blocked-stream resume-vs-rebuild
distinction (non-retryable.spec.ts, store-tck.ts, rebuild.spec.ts) and
the cross-process notify auto-wiring contract (notify.spec.ts) are now
mapped to their rows. Two guarantees had no executable backing and gained a
focused test:
- Backoff's effective window. Backoff persists
deferred_aton the stream via a due-markedackand releases the lease, so the effective delay is the configuredbackoff, decoupled fromleaseMillis. Pinned inbackoff.spec.ts(a 50ms backoff under a 500ms lease retries after 50ms, not the lease). Earlier this was inverted — the held lease floored the backoff up toleaseMillisand mid-window re-claims phantom-bumped the retry counter (#1262). - Lane drain parallelism.
lanes.spec.tscovered controller wiring, arming, and worker lifecycle but never the actual concurrency guarantee: that_drain_all'sPromise.alllets the fast lane complete while a slow-lane handler is stalled. Closed with a gated-handler test.
No documented claim was found false against the code during this audit; every remaining gap was a missing test for behavior that already held.