Derived views
A derived view keeps a reusable answer built from retained Cheetah messages. It is useful when many requests would otherwise scan the same growing history and repeat the same reduction—for example, the latest reported status for every client, a bounded list of recent results, or an error summary.
The answer is a saved projection, not an independently authoritative record. History supplies the retained evidence; an application-selected reducer explains what each message means; the view store keeps the reduced state and the cursors that say how far it has advanced.
The host decides when processing runs. A successful checkpoint commits the answer and its per-stream evidence boundary together.
Choose it for a repeated question
| Need | Use | Why |
|---|---|---|
| one command needs one timely terminal outcome | application RPC | the caller needs one correlated answer, not accumulated state |
| inspect or collect retained messages | history and response-selection APIs | the messages themselves are the answer |
| answer the same evolving question repeatedly | derived view | new messages update one reusable snapshot |
| preserve business truth or coordinate side effects | product-owned storage and workflow | a projection is rebuildable and must not perform external effects |
Suppose a product receives device reports on user/device-status. A LatestPerKeyReducer can keep one entry per device. The processor reads only after the saved cursor, while any number of application readers can load the resulting map without rescanning the stream.
“Current” is always relative to the saved cursors. A snapshot does not prove that the host's processor is running, that the newest retained message has already been folded in, or that retention preserved every older message needed for a future rebuild.
The application and Cheetah divide the work
Cheetah provides the incremental mechanics:
- query one page after each source-stream cursor;
- invoke the reducer for each returned message;
- save state and cursors as one snapshot;
- resume after restart from that snapshot; and
- build a replacement privately before publishing a successful rebuild.
The application provides the meaning and operating policy:
- reducer code and a bounded, JSON-compatible state shape;
- registration after every process start;
- scheduling, cancellation, health reporting, and failure isolation;
- retention long enough for normal lag and any required rebuild;
- one deliberate processing location per view across the deployment; and
- reducer migration, view deletion, and application-level freshness rules.
There is no background scheduler, server preset, query language, schema-migration framework, or distributed writer election hidden behind ViewEngine.
Support boundary
Derived Views is a frozen, experimental v1 facility for a trusted single-tenant host. User IDs are structural parts of history queries and snapshot keys, but that storage separation is not a shared-hosting certification. The engine has no cross-process fencing, state-byte or CPU quotas, per-customer reducer sandbox, or audited administrative isolation.
Use it when the host controls the reducers and the bounded set of view registrations. Do not add it to a shared multi-tenant service merely because the underlying store takes a user_id; the audited shared-tenancy preset deliberately excludes this facility.
Read the contracts in order
Run and schedule the engine covers construction, registration, processing, reads, callbacks, restart, and unregistration.
Define reducers gives the custom-reducer contract and the exact behavior and bounds of all five supplied reducer patterns.
Understand checkpoints and failures explains page and stream ordering, skip and fail, at-least-once replay, callbacks, and what a committed cursor proves.
Store, rebuild, and operate views covers the two supplied stores, atomic rebuild publication, reducer replacement, retention, monitoring, and deployment limits.
For the messages that feed a view, see Response waiting and history. For the shared-tenancy exclusion, see Shared-tenancy composition.