Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/spec/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,12 @@ rules, exact values and reactive session, headless ·
mapping for a table, on and off the owner thread, and `table::apply` for a
server ·
[`table/database_pages.md`](table/database_pages.md) — paging a table that
lives in a database: `planQuery`, `Page::totalKind` and the conformance helper
lives in a database: `planQuery`, `Page::totalKind` and the conformance helper ·
[`table/table.md`](table/table.md) — the one table every surface
uses: a table as a description any model can offer, the single pipeline,
unloaded cells and levels, the caches, configuration, acting on rows, and the budgets ·
[`table/editing.md`](table/editing.md) — typing into a table: a grid of a form, cells of a model's table, the
cell editor, walking, paste, header bands, spans, summary rows and fixed grids

**Reactive state and control**
[`reactive/signals.md`](reactive/signals.md) ·
Expand Down
12 changes: 12 additions & 0 deletions docs/spec/table/database_pages.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,13 +206,21 @@ message naming the column. The predicate runs after `validate`, so the usual ref
that the refusals are equal values. Which columns a client may offer to sort and filter belongs in the schema and is
not part of this seam.

A model that asks for it (`Residual::Allow`) is not refused: it receives a prefilter plan, fetches the rows that
plan admits, and `finishPlan` answers the whole query over them in C++
([`table.md`, "What a store cannot express"](table.md#what-a-store-cannot-express)). The refusal above is what
a model that does not ask receives.

## Totals

`Page<Row>` has `TotalKind totalKind = TotalKind::Exact`, with `enum class TotalKind { Exact, AtLeast }`, written in JSON
by name, `"exact"` and `"atLeast"`, as the module's other wire enums are:

- `Exact`: `total` is the count of the filtered view.
- `AtLeast`: `total` is a lower bound and the view has at least that many rows; a client shows "100,000 or more".
A total is a lower bound for one of two reasons: the count stopped at the cap, or the filter cannot yet decide some
rows because a cell it reads is not loaded ([`table.md`, "Totals"](table.md#totals)), and `Page::undecided`
is then not zero.
- `total` absent: not counted.

`apply` reports `Exact` at or below `QueryLimits::totalCap` and omits the total above it. A model
Expand All @@ -225,6 +233,10 @@ than `totalCap`, reports `AtLeast` with `total = totalCap`. Rules:
- A `limit` of zero returns the count and no rows.
- The conformance helper holds an `Exact` total to the true count on either side of the cap: where `apply` omits the
total it counts the view itself.
- When the oracle reports undecided rows, a total at or below the cap is `AtLeast` on both sides and equals the count
of the rows the filter has admitted; the helper holds the model to that count, to that kind and to the same
`undecided`. Above the cap the rule is the cap's: `AtLeast` with `total = totalCap`, or an `Exact` count, which a
model may report only when `undecided` is zero.

`PageWindow<Row>::totalKind()` returns the kind of the latest reply that carried a total; `reset` clears it with the
total. `PageWindow` stops fetching past an `Exact` total only; past an `AtLeast` total it keeps fetching until a
Expand Down
625 changes: 625 additions & 0 deletions docs/spec/table/editing.md

Large diffs are not rendered by default.

5 changes: 5 additions & 0 deletions docs/spec/table/engine.md
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,10 @@ edited included; the next repair holds them again.
model's translation and reports every disagreement. `compileFilterGuarded` is the one compile step `apply`,
`Engine` and `planQuery` share, so a collator or date parser that throws is `ServiceFailed` in all three. The
design is [`database_pages.md`](database_pages.md).
- A table whose rows are cheap and whose slow columns load later marks the unloaded cells `Unloaded`: an unloaded cell
sorts after the empties, a filter over it is three-valued, and its row is undecided rather than rejected. A column
names the data level its cells need, a query names the columns it shows, and a `Page` says which of its cells are
still coming. The design is [`table.md`](table.md).
- `escapeLikePattern` is for a database-backed server that maps `contains` to
SQL `LIKE`: it keeps `%` and `_` ordinary.
- `TableError` serialises with its code by name (`"unsupportedOperator"`), so a
Expand Down Expand Up @@ -470,6 +474,7 @@ against `wire::decode` both ways.

- `docs/superpowers/specs/2026-10-08-table-engine-design.md` — the
program-level design this module implements.
- [table.md](table.md) — the one table every surface uses: descriptions, the pipeline, unloaded cells, caches, configuration and budgets.
- [../core/callback_scope.md](../core/callback_scope.md) — the lifetime gate on
every completion.
- [../core/executor.md](../core/executor.md) — owner and worker executors.
Expand Down
Loading
Loading