# v0.2.0 — Top-N Views, Immediate Refresh, and Diamond Dependency Safety

> **Full technical details:** [v0.2.0.md-full.md](v0.2.0.md-full.md)

**Status: ✅ Released** | **Scope: Medium** (~4 weeks)

> Three major capabilities: maintain "top 10" style queries incrementally,
> guarantee consistency across diamond-shaped dependency chains, and refresh
> stream tables transactionally inside the same database commit.

---

## What problem does this solve?

After the v0.1.x series proved the core engine, three common real-world needs
became the focus: ranking queries ("show me the top N customers by spend"),
complex multi-table dependency chains where the same source feeds multiple
stream tables, and use cases requiring the freshest possible data inside
application transactions.

---

## TopK: ORDER BY + LIMIT in Stream Tables

A very common reporting pattern is "top 10 products by sales this month" or
"most active users in the last 24 hours." These queries use `ORDER BY` with
a `LIMIT` clause. Maintaining them incrementally is non-trivial — when a new
row joins the top 10, the row that drops off must also be removed.

v0.2.0 adds full incremental support for `ORDER BY … LIMIT N` queries.
The engine tracks the boundary of the top-N set and efficiently computes
additions and removals as the underlying data changes.

*In plain terms:* leaderboards, "most recent" feeds, and ranked reports can
now all be stream tables — always current, with no full recomputation.

---

## Diamond Dependency Consistency

A **diamond dependency** occurs when a stream table depends on two other
stream tables that both depend on the same source. For example:

- `orders → daily_summary` and `orders → regional_summary`
- `combined_view` depends on both `daily_summary` and `regional_summary`

Before v0.2.0, if `orders` was updated, the two intermediate stream tables
might refresh at slightly different times, leaving `combined_view` temporarily
inconsistent — reading from a daily summary that was already updated while
the regional summary still showed old data.

v0.2.0 detects diamond dependencies and guarantees that all branches of
the diamond are refreshed before the downstream node runs. Consistency is
always preserved.

---

## IMMEDIATE Refresh Mode

Standard refresh mode processes changes asynchronously in the background.
**IMMEDIATE mode** is a new option for stream tables that need to be updated
*transactionally* — within the same database transaction as the source change.

When a row is inserted into a source table, the stream table is updated
atomically before the transaction commits. From the application's perspective,
the stream table is always perfectly in sync with the source.

*In plain terms:* IMMEDIATE mode is for cases where you cannot tolerate even
a brief delay — such as a balance column that must always reflect the latest
transactions, even mid-transaction.

---

## Scope

v0.2.0 expands the range of queries that can be maintained incrementally
(TopK), ensures correctness in complex dependency graphs (diamond consistency),
and adds a synchronous refresh option for latency-sensitive use cases
(IMMEDIATE mode). The three features are independent and can be adopted
separately.