shoney/writeonce
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
writeonce/docs/00-git-commit-history.md
shoney.arickathil 185251c404 docs(site-update): guide for changing the site application 
- new docs/guides/updating-site.md: the developer loop deploying-site.md
  deliberately does not cover — the submodule two-repo commit dance in
  the order that cannot strand other clones (push writeonce-site first,
  bump the pointer second), the gate living in the monorepo by design,
  and framework changes being ordinary monorepo commits
- the schema section is measured against the built site, not inferred:
  adding views: Int stopped the build with WO-E206 until all ten seed
  inserts carried it (no field-default syntax — the seed cannot drift
  from the schema), then the live WO_DATA migrated at boot, all ten
  chapters rendered, and a live admin edit SURVIVED the migration;
  retyping the field refused by name with the log intact
- states the one release combination that still needs the content wipe:
  a schema change WITH new seed rows — migration handles the shape,
  seeds still cannot reach a non-empty table
- deploying-site.md cross-links; site-update prefix registered

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
(cherry picked from commit a21a02f2c264a3fe1c31b3bfd9159415a594fa05)
2026-09-15 01:15:30 +02:00

167 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Git commit history — features and their cherry-picks
Reference for **which commits carried which feature onto `master`**, so a
feature can be traced, re-reviewed, or reverted as a unit long after the
history it was written in has moved on.
## The workflow this file records
1. **Development happens on `dev`.** Not on `master`, and not on a fresh
branch per feature.
2. **Every commit on `dev` carries a feature-specific unique prefix**, written
as the conventional-commit scope — `feat(db2-keys): …`, `fix(db2-keys): …`.
The scope, not a bare leading word, so the repo keeps the `feat`/`fix`/`docs`
type it has used throughout. One prefix per feature, reused by every commit
belonging to it, which makes a feature's commits selectable with
`git log --grep` without reading a single diff.
3. **When the feature is ready** — complete, not merely green — `git checkout
master` and **cherry-pick** that feature's commits, in order.
4. **Record the result below**: the `dev` hashes, the `master` hashes the
cherry-pick produced, and the date. The two differ — a cherry-pick makes new
commits — and that mapping is the whole reason this file exists.
Ready means the same gate as always: no half-implemented feature reaches
master. An annotation the compiler accepts but does not honour counts as
broken, however green the suite.
## Prefix registry
One row per feature. The prefix is claimed here before its first commit, so two
features cannot collide.
| Prefix | Feature | Status |
| --- | --- | --- |
| `commit-history` | this file and the workflow it records | ✅ on `master` 2026-08-30 |
| `db2-keys` | databasev2 2 — `resident: keys` storage and readers | ✅ on `master` 2026-08-30 (with `db2-delta` and `db2-chains`). The “Not ready” note this row carried is spent: the loader refusal was lifted and updates are implemented |
| `db2-chain-review` | review of the databasev2 chain and dependency graph | ✅ on `master` 2026-08-30 |
| `db2-delta` | databasev2 2 — keys-resident updates as WAL delta records | ✅ on `master` 2026-08-30 |
| `db2-chains` / `db2-chain` | databasev2 11 — bounding a keys-resident row's delta chain | ✅ on `master` 2026-08-30 |
| `site` | the writeonce.de tutorial site | ✅ on `master` 2026-08-30 |
| `db2-migrate` | databasev2 12 — schema migrations (add/delete, declarative, auto on boot) | ✅ on `master` 2026-08-31 |
| `site-deploy` | the writeonce.de redeploy runbook (`docs/guides/deploying-site.md`) | ✅ on `master` 2026-08-31, picked as iteration 12's docs dependency |
| `site-update` | the developer loop for changing the site app (`docs/guides/updating-site.md`) | on `dev` 2026-08-31 |
| `site-submodule` | `docs/examples/site` extracted to github.com/shoneyJ/writeonce-site and consumed as a submodule | ✅ on `master` 2026-08-30. Both branches now track the site by revision; an edit to it is a commit in that repo plus a pointer bump here |
| `lang41` | runtime: unadopted shard must not impersonate shard 0 | on `dev` (`9dca0b4`); independent of the residency stack, not picked |
| `porch-store` | porch store tables, Limiter and Idempotent middleware (Phases A, B, C) | on `dev` (`519d411`, `5b1e82a`, `aee7926`). **In progress**: Phase C was uncommitted work from a parallel session, committed as-is, and calls `json.decode`/`json.encode` with no `use json` import |
| `query-corpus` | databasev2 query-grammar corpus #1 | on `dev` (`4c82461`). Conclusion was "no new grammar needed" |
## Cherry-picks onto master
Newest first. `dev` hash is the original; `master` hash is what the cherry-pick
produced.
| Date | Prefix | Feature | `dev` → `master` |
| --- | --- | --- | --- |
| 2026-08-31 | `db2-migrate` + `site-deploy` | **databasev2 12 — schema migrations v1**: WO_WAL_SCHEMA head record, name-keyed boot diff, record-level transcode for add/delete, poisons that bite only with records; plus the redeploy runbook the close-out edits (dev-only until now). Zero conflicts. Verified on `master`: 36 suites 0 fail (`test_wal` 5966/0), woc-test clean, residency-accept 14/0, site-accept 23/0 | `930a715` → `b594717`, `072e007` → `8d9207d`, `ba8519f` → `570e0d6`, `63a063b` → `b1b7984`, `b69092a` → `4a70fc7`, `b21943a` → `ace5699`, `4bb6ece` → `4f1fda1` |
| 2026-08-30 | `site-submodule` | **`docs/examples/site` becomes a submodule** — extracted to github.com/shoneyJ/writeonce-site with `git subtree split` (its own 9 commits of history, not a snapshot) | `4b56348` → `a5497a3`, `4eead89` → `565b894` |
| 2026-08-30 | `db2-keys` + `db2-delta` + `db2-chains` + `site` | **databasev2 `resident: keys`, end to end** — storage, readers, deletes, updates as delta records, bounded delta chains, and the tutorial chapter documenting them | 37 commits, mapped one-to-one below |
### 2026-08-30 — the databasev2 residency stack
The first cherry-pick under this convention, and it could not be a single
iteration: **databasev2 11 (bounded delta chains) does not stand alone.** Its
commits touch `wo_wal_fold_row_at`, `keys_fold_into` and `row_apply_field_keys`,
none of which existed on `master` — so the whole stack it sits on came with it,
in dev order:
| # | Prefix | `dev` | `master` | Title |
| --- | --- | --- | --- | --- |
| 1 | `db2-keys` | `125bd09` | `620c0a7` | feat(db2-keys): storage — drop the payload, read it back from the log |
| 2 | `db2-keys` | `08abd09` | `d985901` | feat(db2-keys): inserts and boot — payload dropped after the barrier |
| 3 | `db2-keys` | `0c97fa4` | `d8839c0` | feat(db2-keys): the query paths read through the iterator and borrow |
| 4 | `db2-keys` | `f606fc9` | `234b1f0` | feat(db2-keys): rewire remaining readers, survive compaction |
| 5 | `db2-keys` | `b3d8c40` | `89a7456` | docs(db2-keys): reconcile databasev2 and porch markdown with the code |
| 6 | `db2-chain-review` | `2ecaf0c` | `1af4910` | docs(db2-chain-review): review the databasev2 chain and dependency graph |
| 7 | `db2-keys` | `76b8fd9` | `390635c` | fix(db2-keys): delete on a keys-resident table was memory corruption |
| 8 | `db2-keys` | `c9c7e03` | `d27e774` | docs(db2-keys): a runnable example for per-table storage |
| 9 | `db2-keys` | `dc25462` | `c8a0c7b` | fix(db2-keys): a logged delete must replay on a keys-resident table |
| 10 | `db2-keys` | `d4104dc` | `4105f1c` | docs(db2-keys): the residency example becomes a product catalogue |
| 11 | `db2-keys` | `c9a88b0` | `daba10c` | docs(db2-keys): spec — delta records for keys-resident updates |
| 12 | `db2-delta` | `abb8fc9` | `b5cc77d` | docs(db2-delta): implementation plan for keys-resident delta updates |
| 13 | `db2-delta` | `c6cd486` | `efa118b` | docs(db2-delta): correct a line citation before execution |
| 14 | `db2-delta` | `9c6f832` | `ff73da7` | feat(db2-delta): WAL delta record kind and encoder |
| 15 | `db2-delta` | `20ba096` | `82dbd4a` | fix(db2-delta): make delta test detect a field_idx/back_off transposition |
| 16 | `db2-delta` | `a60231c` | `1f04cff` | feat(db2-delta): fold a delta chain, route reads through it |
| 17 | `db2-delta` | `173dbf2` | `38159b0` | fix(db2-delta): fold's cycle guard checks direction, not step count |
| 18 | `db2-delta` | `89c56a1` | `5b9ffb7` | feat(db2-delta): keys-resident updates append, indexes follow |
| 19 | `db2-delta` | `409186d` | `f1f4d13` | fix(db2-delta): unique shadow-check gets its own buffer, not r's |
| 20 | `db2-delta` | `4d13bce` | `dbfa385` | feat(db2-delta): wire the request path, defer re-point to the barrier |
| 21 | `db2-delta` | `c049ab9` | `d6eeacb` | fix(db2-delta): close the unique-shadow-check's same-drain blind spot |
| 22 | `db2-delta` | `7e4ae70` | `ef606e1` | feat(db2-delta): replay and compaction fold delta chains |
| 23 | `db2-delta` | `b87c68f` | `8dbeb2a` | feat(db2-delta): lift the resident:keys refusal, prove it end to end |
| 24 | `db2-delta` | `3ea6d64` | `76a9f17` | fix(db2-delta): refuse resident:keys with no WO_DATA at runtime |
| 25 | `db2-delta` | `d4b12d1` | `4ae3af2` | fix(db2-delta): borrow the pending re-point, not the stale durable offset |
| 26 | `db2-delta` | `fed9fe8` | `b8e4bc9` | fix(db2-delta): pend_repoint failure fatal; delta fold no longer trusts a live WAL |
| 27 | `db2-delta` | `b575678` | `bdedc50` | docs(db2-delta): resident:keys has storage; move done criteria to Met |
| 28 | `db2-delta` | `e643440` | `35aa0be` | docs(db2-delta): guide to log-structured rows for a new reader |
| 29 | `db2-chains` | `f667cad` | `0c874a6` | docs(db2-chains): spec + story for bounding a row's delta chain |
| 30 | `db2-keys` | `7cba9b1` | `ab292a4` | feat(db2-keys): task 7 — measure resident: keys against swapping |
| 31 | `db2-keys` | `abc276a` | `152b5ea` | feat(db2-keys): GB-scale bench modes, unmeasured |
| 32 | `db2-keys` | `a310496` | `3855e58` | feat(db2-keys): gate the residency measurement, close out task 7 |
| 33 | `db2-chains` | `1b808ab` | `e3c544c` | feat(db2-chains): bound a keys-resident row's delta chain |
| 34 | `db2-chain` | `f93b5d9` | `b375772` | test(db2-chain): cover flattening, and drop a ceiling no input could reach |
| 35 | `db2-chain` | `de39a88` | `5a98730` | docs(db2-chain): close out iteration 11 on the board |
| 36 | `site` | `3b503c0` | `461ba18` | feat(site): tutorial chapter for durable and resident storage modes |
| 37 | `commit-history` | `41923eb` | `397a2b6` | docs(commit-history): feature-to-cherry-pick reference |
**What was deliberately left on `dev`:** the 26 `porch-store` commits. porch 1
was re-scoped mid-flight (`79e6da4` reverts idempotency to porch 9), so it is
the exact case this file's “ready means complete, not merely green” bar exists to
catch. `lang41` and `query-corpus` also stayed — independent features, not
dependencies of this one.
**Three conflicts, all in docs, all resolved toward what `master` can honestly
claim:**
- `docs/examples/skill-catalog/README.md` — a one-line link fix inside a file
belonging to `query-corpus`, which is not on `master`. Edit dropped; the file
stays absent.
- `docs/00-databasev2-chain-review.md` — created by `db2-chain-review`, which the
prefix filter had excluded while later `db2-keys` commits kept editing it. Resolved
by picking that commit too, rather than dropping edit after edit.
- `docs/stories/00-status.md` — `b87c68f` carried one databasev2 status entry
bundled with two porch-1 entries. **Only the databasev2 entry was kept.** Taking
the whole block would have left `master` claiming porch 1 was done while none
of its code was there.
**Verified on `master` after the pick, not assumed:** `woc-test` clean; `wovm-test`
all 20 suites green (`test_wal` 5700/0, `test_table` 856/0); `just site` 23 checks,
0 failures; `residency-accept` 14 checks, 0 failures — including the leg proving
`resident: keys` without `WO_DATA` exits 2 and names the offending class.
**Still outstanding on `master`, and known:** databasev2 2 task 6's byte-budget
refusal. A missing *guard*, not an unhonoured annotation — the annotation is now
genuinely honoured, measured at a 2.55× smaller resident set. The other half of
task 6 (`durable: true` with no `WO_DATA` silently discarding writes) predates this
pick and is unchanged by it.
## Before this convention
Work up to 2026-08-29 landed on `master` by **merging** feature branches, so
those commits keep their original hashes and have no entry here.
`git log --merges master` is the record for that period.
The `db2-keys` and `porch-store` commits are the seam: they were written on
`porch-store-middleware` before this convention (`18ce4d5`, `f9c36ef`,
`11a92df`, `91411ae`, `6c8550a`, `01af1b9`) and were replayed onto `dev` with
prefixed titles. The replay was verified identical, not merely applied — after
it, `git diff porch-store-middleware dev` over the whole tree was empty.
On 2026-08-29 every other branch was consolidated so only `dev` and `master`
remain. Three could not be replayed and were preserved as **annotated tags**
instead — nothing is lost, and each tag's message says why:
| Tag | Why it is not on `dev` |
| --- | --- |
| `archive/cleanup-pre-existing-changes` | Aug 10, based on an Aug 8 commit. Carries `crates/` and `Cargo.toml` — the Rust runtime `master` has since deleted entirely. Replaying it would resurrect it. |
| `archive/ipc-attach` | Iteration 9c attach channel. Refactors `wo_row_insert`/`wo_row_update_field` into engine-encoded cores; `dev` rewrote those same functions for `db2-keys`. Two overlapping refactors of one function, ~250 conflicted lines. |
| `archive/keypair-auth` | Iteration 9d, builds on 9c — blocked by the same overlap. |
The 9c/9d hazard is specific and worth stating: that branch's contract
transfers ownership of `vals` **on failure as well as success**, while `dev`'s
keys-resident arm returns early *without* freeing. A merge that compiles and
passes could still leak or double-free. Reconciling them is an integration
task, not a conflict resolution — recover the work with
`git checkout -b <name> archive/ipc-attach` when it is scheduled.
Reference in a new issue View git blame Copy permalink