Skip to content

The cell model's docs call it the Window Reducer and its stored unit a sample - #3172

Open
matrixarkai wants to merge 1 commit into
mainfrom
docs/window-reducer-naming
Open

matrixarkai wants to merge 1 commit into
mainfrom
docs/window-reducer-naming

Conversation

@matrixarkai

Copy link
Copy Markdown
Owner

Stage 1 of renaming the cell model: documentation only. The model is now called the Window Reducer (WindowReduce), and the unit it stores at one timestamp of a key (all the cells of that key at that timestamp) is called a sample instead of a snapshot.

What changed

  • docs/CELLS_PROTOCOL.md is now docs/WINDOW_REDUCE_PROTOCOL.md and docs/CELLS_WORKED_EXAMPLE.md is now docs/WINDOW_REDUCE_WORKED_EXAMPLE.md (git renames); every link to them is updated: README, the two docs, two code comments and two proto comments (comment text only).
  • In those docs and in the README Window Reducer section, table row, concept table, scenario, command and limits tables, the word snapshot became sample where it names this unit. The README's other uses (raft and storage snapshots) are untouched.
  • The README names the model (table row, intro sentence, a new concept-table row) and notes that the command names in the code blocks move to WindowReduce* names in a later stage.
  • Both docs carry a short naming note: message and field names (Cell*, snapshots_written, snapshot_info, ...) stay as they are on the wire today.

What did not change

  • No code, no proto field, number or name, no stored or wire byte. The stored key tag stays as it is.
  • Every test name and file name cited in the docs is unchanged (tests are renamed in a later stage).
  • The only non-doc files touched carry a path in a comment: cells.proto, cell_protocol.rs, a_cell_rollup_is_a_command.rs.

Verification

  • tools/validate_open_source_readiness.py run locally: status ok.
  • No remaining mention of the old doc paths in the tree.
  • Scrub of added lines, title, body and branch name: clean.

🤖 Generated with Claude Code

…a sample

Rename the two cell docs to WINDOW_REDUCE_PROTOCOL.md and
WINDOW_REDUCE_WORKED_EXAMPLE.md, fix every link to them, and say sample
where the docs and README mean the cells stored at one timestamp of a key.
Documentation and comment paths only: no code, proto field or byte changes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@matrixarkai
matrixarkai removed the request for review from bjmeetsfo November 16, 2026 03:42
@matrixarkai

matrixarkai commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner Author

Stage 2 plan (proto), for a separate PR after this one merges. Not started.

Scope: proto/temporalstore/cells/v1/cells.proto, crates/temporalstore-rust/build.rs, and the Rust that names the generated types (engine/cell_protocol.rs and its tests). No engine, command or SDK change. It waits until the open cell performance PRs (cell_merge_append.rs, cell_set.rs, cell_rank_read.rs) have landed, so it does not collide with them.

Renames, every field number, wire type and enum value unchanged:

  • package temporalstore.cells.v1 becomes temporalstore.windowreduce.v1; the directory becomes proto/temporalstore/windowreduce/v1/windowreduce.proto; build.rs and the tonic::include_proto! line follow.
  • message SnapshotInfo becomes SampleInfo; field snapshot_info (7) becomes sample_info; snapshots_written (16) becomes samples_written; want_snapshot_info (19) and has_want_snapshot_info (30) become want_sample_info and has_want_sample_info; snapshots (18) on the answer becomes samples; snapshots_before and snapshots_after (16, 17, on the remove and delete responses) become samples_before and samples_after. Comments that say snapshot for this unit become sample.
  • the Cell* message and enum names (CellAddRequest, CellQuery, CellAnswer, CellSelector, CellOperation, CellStatusCode, CellShape, CellCall, CellReply and so on) become WindowReduce* with the same suffix; Cell-free names (Window, Observation, RankMode, Rounding, TimeSpan, KeyFilter and the like) stay. The 31 top-level message and enum names are listed in the PR as an old-to-new table.
  • CellEntry stays: Cell remains the element type.
  • the stored key tag VIEW_TAG = "cells" in cell_set.rs is not touched.

Why wire bytes cannot move: protobuf encodes field numbers and wire types, never names, so a rename is byte-neutral as long as numbers and types are untouched. The risk is a slip, not the principle, so the PR proves it.

Bytes-equality test design (one test file, pinned by exact name in .github/workflows/rust-ci.yml, with a nonzero test count asserted):

  1. Before the rename, generate a golden file from the current messages: for every message type, one fully populated value (every field set to a distinct non-default value, repeated fields with two entries, oneof/presence flags both ways, the reserved numbers left unused) encoded to bytes, stored as hex under crates/temporalstore-rust/tests/golden/ together with the message name. Commit the golden file in its own first commit on the PR branch, so it is produced by the old code.
  2. After the rename, the test decodes each golden entry with the new type, re-encodes it, and asserts the bytes equal the golden bytes exactly. It also asserts the decoded value carries every field set (a decode into an empty value would pass an equality of two empty encodings), by comparing a per-field checklist built from the descriptor.
  3. A numbers test reads the new descriptor set and asserts the (message, field number, wire type) triples equal a checked-in table taken from the old proto, so an accidental renumber fails even in a message the golden values did not exercise. Plants: change one number in the proto and confirm the test fails; drop one populated field from the golden value and confirm the checklist fails; each plant committed first, never reverted with checkout.
  4. A grep guard that the proto holds no snapshot token for this unit (the raft/storage snapshot is not in this file), and that VIEW_TAG still equals "cells".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants