Skip to content

[M11] How a write travels: the four-stage strip (M11.5) - #94

Merged
ssoufii merged 1 commit into
mainfrom
auto/m11.5-four-stage-write-strip
Nov 17, 2026
Merged

ssoufii merged 1 commit into
mainfrom
auto/m11.5-four-stage-write-strip

Conversation

@ssoufii

@ssoufii ssoufii commented Nov 17, 2026

Copy link
Copy Markdown
Owner

Builds the four stage strip from section 6: four full height colour fields, the same record card in each, following one real record through the log, memory, disk and a merge.

The part that is not frontend

The card's rows cannot come from snapshot. A snapshot says a table holds N records between two bounds and that its filter has M bits set; it cannot say whether this key is one of the indexed ones, which bits this key lands on, or which table actually answers for it. Deriving that in TypeScript would be reimplementing the read path in the page, which CLAUDE.md rules out. So the engine grew the API the story needs:

  • ledgerlog.introspect.locate(engine, key): walks the layers in the order a get consults them (log, active memtable, frozen memtables, then every table newest first) and reports what each one said, including answered_by so a caller does not re-derive precedence. A table whose filter rejects the key reports searched: false and is not opened, which is the saving a bloom filter buys, stated rather than implied.
  • BloomFilter.bit_positions(key) and BloomFilter.bit_is_set(index): public, because "the filter said no" is not an explanation; the positions and whether each is set are. A test drives 200 probes and asserts the bits agree with might_contain on every one, so the two walks cannot disagree.

Both are read only. A test asserts that locating a key twice gives the same answer, leaves the snapshot identical and leaves every get answering the same, and another runs the call with threading.Thread.start monkeypatched to raise, because Pyodide has no threads.

The frontend

  • WriteStrip.tsx and RecordCard.tsx: four fields stepping --ground, --surface-3, --maroon-deep, --maroon, no gaps, the card at 38% down and one clause at the foot of each.
  • engine/state.ts: one store for the engine's state. From this story there are two views of the same engine on the page, and two components each taking their own snapshot would be showing two different engines the moment one refreshed and the other did not. The console is now a view over the same store.
  • session.py writes one demo record when it opens the database, so the strip has something true to follow before anyone types. Section 9 forbids invented proof, and a card of plausible numbers is exactly that.

Acceptance criteria

  • The four field strip is built as section 6 describes, with the same record card in each field.
  • The card shows the visitor's most recent key at each stage from the engine: WAL offset, length and checksum; tower level; SSTable sequence, whether the sparse index points at it and bloom bits set; and the compaction result.
  • Before the visitor writes anything the strip uses a demo key the engine writes at boot; a stage the record has not reached says so and offers the action that gets it there, and never shows invented data.
  • Playwright: after a put, card 1's offset equals the snapshot's WAL offset for that key; after a flush, card 3 shows the SSTable sequence; after a compaction, card 4 shows the merged table.

What ran, and what passed

  • pytest: 1264 passed (20 new). ruff check src tests and ruff format --check src tests: clean.
  • In web/: npm ci, lint, typecheck, build: clean.
  • npx playwright test: 66 passed across both projects (default and chromium-reduced-motion). Playwright ran locally, not only in CI.

The strip's assertions compare a card against the engine's numbers as the console reports them (the console reads snapshot, the strip reads locate), so a card is checked against a different call on the same engine rather than against a constant its own component also uses. Card 4's "3 records dropped" is the real figure from merging four copies of one key.

I drove the page by hand at 1440 and looked at the strip at 1440 and 768: the four fields step correctly, the cards sit 38% down, the heading runs across the top from the first field, and the stacked layout keeps its margins.

Decisions taken without asking

  • The heading runs across the top of the strip rather than wrapping inside the first field. "how a write travels" sets about 570px at --step-head, and a 25vw field is 360px at 1440, so inside the field it is three lines and fails house rule 1. It still starts top left in the first field, which is where section 6 puts it; it does not stop there.
  • The fields stack below 1200px, not only on a phone. A 25vw field is 192px at 768 and the card is 260px at true size, so four columns below 1200 would mean a cropped fragment at every width in between.
  • The demo record is written when the database opens, not re-written by reset. Reset is the visitor asking for an empty database, and it gives one. The strip then says the key was never written and offers the control that writes one, which is the behaviour the third criterion asks for anyway.
  • The boot record shifts the baseline of the M11.2 and M11.4 specs, which assumed an empty page. Those specs now press reset in beforeEach and establish the empty database explicitly. No assertion was changed or relaxed; one step was added.
  • Button locators in the existing specs are now exact. The page legitimately has more than one control that mentions flushing (the console's flush and the strip's flush it), so the console's is targeted exactly. That is a stronger match than the substring it replaces, not a weaker one.

No motion was added. Section 8 is story M11.9.

Closes #83


Generated by Claude Code

Story M11.5. Four colour fields, the same record card in each, following the
visitor's most recent key or the record the session writes when it opens.

The cards cannot be drawn from a snapshot: which table answers for a key,
whether the sparse index points at it or sends a reader scanning, and which
bloom bits it lands on are all per key, and working them out in TypeScript
would be reimplementing the read path in the page. So the engine gained
ledgerlog.introspect.locate, which walks the layers in the order a get
consults them and reports what each one said, and BloomFilter gained
bit_positions and bit_is_set, so a false positive can be explained rather
than asserted. Both are read only and tested as such.

A stage the record has not reached says so and offers the control that gets
it there, and never fills the gap with a plausible number.

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QWNkuNh5Bysnfo2KrxL9Sp
@ssoufii
ssoufii merged commit 430e545 into main Nov 17, 2026
9 checks passed
@ssoufii
ssoufii deleted the auto/m11.5-four-stage-write-strip branch November 17, 2026 05:52
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.

[M11] How a write travels: the four-stage strip (M11.5)

2 participants