93 lines
3.9 KiB
Markdown
93 lines
3.9 KiB
Markdown
|
# T0.8 — Fold and re-derive
|
|||
|
|
|
|||
|
|
| Field | Value |
|
|||
|
|
|---|---|
|
|||
|
|
| Phase | P0 — Foundations |
|
|||
|
|
| Size | M — 1 to 3 days |
|
|||
|
|
| Status | Not started |
|
|||
|
|
| Flags | — |
|
|||
|
|
| Spec | inlined below |
|
|||
|
|
| Blocks | P1 gate |
|
|||
|
|
|
|||
|
|
## Goal
|
|||
|
|
|
|||
|
|
The projection from log to materialized state, as a pure function. This task
|
|||
|
|
establishes the property every later phase re-runs.
|
|||
|
|
|
|||
|
|
## Facts (inlined — no spec read needed)
|
|||
|
|
|
|||
|
|
- **Nothing derived is authoritative.** Materialized state is a cache of the log.
|
|||
|
|
If it cannot be dropped and rebuilt byte-identically, it has hidden inputs and
|
|||
|
|
that is a bug.
|
|||
|
|
- The fold is pure: `fold(state, record) -> state`. No clock reads, no random,
|
|||
|
|
no filesystem, no map iteration order leaking into the output.
|
|||
|
|
- Reduction (T8.4) is designed around this property: it appends a
|
|||
|
|
`Reduced { original, summary }` event rather than editing the log or rewriting
|
|||
|
|
a blob, precisely so the fold still reaches the same state from LSN 0.
|
|||
|
|
- Restart folds forward from the newest checkpoint (T2.5); `None` means fold from
|
|||
|
|
LSN 0. Checkpoints are an optimization only — deleting every checkpoint costs
|
|||
|
|
startup time and nothing else.
|
|||
|
|
|
|||
|
|
## Steps
|
|||
|
|
|
|||
|
|
1. Define the materialized state type: runs, branches, attempts, refs, intent
|
|||
|
|
status. Whatever the query surface (T1.7) needs and nothing more.
|
|||
|
|
2. Write `fn fold(state: &mut State, record: &LogRecord)` as a pure function.
|
|||
|
|
Take no `&self`, no store handle, no `Instant::now()`.
|
|||
|
|
3. Use ordered collections (`BTreeMap`) anywhere the state is serialized, so
|
|||
|
|
byte-identity does not depend on hash seed.
|
|||
|
|
4. Write `rebuild(log, key) -> State`: read from LSN 0 (or from the newest
|
|||
|
|
checkpoint once T2.5 lands), fold every record in order.
|
|||
|
|
5. Write the property test as a **reusable helper**, not a one-off: drop the
|
|||
|
|
state tables, `rebuild`, assert the serialized bytes match. Every subsequent
|
|||
|
|
phase calls this helper on its own fixtures.
|
|||
|
|
6. Wire that helper into P1–P8 fixture suites as they land.
|
|||
|
|
|
|||
|
|
## Acceptance
|
|||
|
|
|
|||
|
|
- Drop the state tables, re-fold from LSN 0, assert byte-identical state.
|
|||
|
|
- The helper is exported and used by at least one later phase's fixture set.
|
|||
|
|
|
|||
|
|
## Verify
|
|||
|
|
|
|||
|
|
**Harness:** export `assert_refold_identical(&log, key)` as a **public test
|
|||
|
|
helper from this crate**. Every later phase calls it on its own fixtures; that
|
|||
|
|
reuse is the deliverable, not the one-off test.
|
|||
|
|
|
|||
|
|
**Integration test** — `tests/it_refold.rs`:
|
|||
|
|
1. Build a log containing a retry, a rewind (once T2.3 lands) and a reduction
|
|||
|
|
(once T8.4 lands) — the three cases with non-trivial fold logic.
|
|||
|
|
2. Snapshot `serialize(state)`.
|
|||
|
|
3. Drop the state tables entirely.
|
|||
|
|
4. `rebuild` from LSN 0.
|
|||
|
|
5. Assert **byte equality** of the serialized state, not `PartialEq`.
|
|||
|
|
6. Repeat the fold twice in the same process and assert both runs produce
|
|||
|
|
identical bytes — catches hash-seed and iteration-order leakage.
|
|||
|
|
7. Purity check: run the fold with the system clock moved forward and with a
|
|||
|
|
different `TZ`; assert the bytes are unchanged.
|
|||
|
|
|
|||
|
|
**Command:** `cargo test -p projection refold`
|
|||
|
|
|
|||
|
|
**False pass:**
|
|||
|
|
- Comparing states with derived `PartialEq`. `HashMap` compares order-insensitively,
|
|||
|
|
so byte-identity can be broken while the test is green — and byte-identity is
|
|||
|
|
the actual property.
|
|||
|
|
- Testing on a log with one linear run and no branches, retries or reductions.
|
|||
|
|
Every implementation passes that.
|
|||
|
|
- Running the fold once and comparing to the live state that was built by the
|
|||
|
|
same code path incrementally — assert against a committed expected snapshot for
|
|||
|
|
at least one fixture.
|
|||
|
|
|
|||
|
|
## Traps
|
|||
|
|
|
|||
|
|
- `HashMap` in serialized state — iteration order varies and byte-identity fails
|
|||
|
|
intermittently, which reads as flakiness rather than as the bug it is.
|
|||
|
|
- Any hidden input: a timestamp taken at fold time, a config value read from the
|
|||
|
|
environment, a default filled in from the current schema version.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
Background (not required to do this task):
|
|||
|
|
[rust-agentic-sys.md](../../../rust-agentic-sys.md) §1, §8.6 ·
|
|||
|
|
[rust-agentic-task.md](../../../rust-agentic-task.md)
|